tim Rowledge uploaded a new version of System to project The Trunk:
http://source.squeak.org/trunk/System-tpr.962.mcz

==================== Summary ====================

Name: System-tpr.962
Author: tpr
Time: 18 September 2017, 4:45:22.01173 pm
UUID: e1c54891-6fa2-45fd-9acb-58c76815aa62
Ancestors: System-dtl.961

Add and expand some comments that should help to explain UserInterfaceTheme for future readers

=============== Diff against System-dtl.961 ===============

Item was changed:
  ----- Method: UserInterfaceTheme>>doesNotUnderstand: (in category 'lookup') -----
+ doesNotUnderstand: aMessage
+ 	"In order to be able to use a UserInterfaceTheme as a container of fairly arbitrary properties whilst making it seem like we are sending regular messages as a way of accessing those properties we can handle the dNU: and check the not understood message name against our property list. This is clever, devious, interesting and may confuse users until they get to see an explanation like this"
+ 	"Answer nil or a value for the property specified by aMessage's #selector. Searching for the property proceeds by
+ 	a) searching my dictionary for a key made up of an Association with a key of the class of the 'client' and a value of the message name. For example SimpleButtonMorph->borderColor
+ 	b) searching again for a key made from the superclass(es) of the client - e.g. RectangleMorph->borderColor and then if required BorderedMorph->borderColor etc.
+ 	c) if there is a linked theme, search it in the same manner.
+ 	
+ 	As an extreme example, consider a basic theme with a linked theme specifically for buttons. 
+ 	mySimpleButtonMorph borderColor
+ 	would search the basic theme for SimpleButtonMorph->borderColor, the superclass equivalents as in b) above, then search the linked theme for SimpleButtonMorph->borderColor and, we hope, find something meaningful"
- doesNotUnderstand: aMessage 
- 	"Answer whether I have, or inherit, a value for the visual-attribute specified by aMessage's #selector."
  
  	aMessage numArgs > 0 ifTrue: [^ super doesNotUnderstand: aMessage].
  	scope isEmpty ifTrue: [^ super doesNotUnderstand: aMessage].
  	
  	^ [self get: scope top class -> aMessage selector]
  		ensure: [scope pop]!

Item was changed:
  ----- Method: UserInterfaceTheme>>get: (in category 'private') -----
  get: keyObject 
+ 	"keyObject is intended to be an Association. We have two lookup strategies: 1) along the superclass chain *of the client*, 2) via a linked theme. Evaluate the result because there can be message sends stored or blocks."
- 	"keyObject is intended to be an Association. We have two lookup strategies: 1) along the superclass chain, 2) via a linke theme. Evaluate the result because there can be message sends stored or blocks."
  	
  	| k |
  	properties
  		at: keyObject
  		ifPresent: [:prop | ^ prop value].
  	
  	keyObject isVariableBinding "simple key objects"
  		ifFalse: [^ self getViaLink: keyObject].
  	
  	k := keyObject key.
  	(self getViaSuperclasses: keyObject)
  		ifNotNil: [:prop | ^ prop].
  		
  	keyObject key: k. "restore"
  	^ self getViaLink: keyObject!

Item was changed:
  ----- Method: UserInterfaceTheme>>getViaLink: (in category 'private') -----
  getViaLink: keyObject 
+ 	"keyObject is intended to be an Association.
+ 	If there is a linked theme, see if it has the relevant property available"
- 	"keyObject is intended to be an Association"
  	
  	^ next ifNotNil: [next get: keyObject]!

Item was changed:
  ----- Method: UserInterfaceTheme>>getViaSuperclasses: (in category 'private') -----
  getViaSuperclasses: keyObject 
+ 	"keyObject is intended to be an Association.
+ 	Find the superclass of the key of the keyObject (which will initially be the client's class) and make a new keyObject using that and the original message name, then try searching for that."
- 	"keyObject is intended to be an Association"
  		
  	"We know we're the only referencer of keyObject.  Update it rather than create new ones, for performance reasons."
  	keyObject key: keyObject key superclass.
  
  	keyObject key ifNil: [^ nil].
  	
  	properties
  		at: keyObject
  		ifPresent: [:prop | ^ prop value].
  	
  	^ self getViaSuperclasses: keyObject!