Marcel Taeumel uploaded a new version of System to project The Trunk:
http://source.squeak.org/trunk/System-mt.1265.mcz

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

Name: System-mt.1265
Author: mt
Time: 9 December 2021, 4:24:51.225766 pm
UUID: 2f8316d1-de76-3740-b39e-fd1d62c0e66b
Ancestors: System-mt.1264

Fixes some issues in the commentary on UserInterfaceTheme. Complements Morphic-mt.1820.

Thanks to Eric Gade (EG) for pointing this out!

=============== Diff against System-mt.1264 ===============

Item was changed:
  Object subclass: #UserInterfaceTheme
  	instanceVariableNames: 'properties name next ignoreApply lastScaleFactor'
  	classVariableNames: 'All Current Default'
  	poolDictionaries: ''
  	category: 'System-Support'!
  
+ !UserInterfaceTheme commentStamp: 'mt 12/9/2021 16:24' prior: 0!
- !UserInterfaceTheme commentStamp: 'mt 5/9/2018 09:22' prior: 0!
  A UserInterfaceTheme is a dictionary of preferred visual properties; colors, borderStyles, borderWidths, fonts, forms, etc. used to color and style the IDE.
  
  Accessing the Theme
+ ===
+ To access the proper UserInterfaceTheme instance for an object, send it #userInterfaceTheme.  The default implementation on Object returns an instance of UserInterfaceThemeRequest that provides a lightweight, clean proxy of the actual theme in use by the IDE at the current time. To do anything more sophisticated than basic querying and setting of properties, you should ask the proxy for the actual #theme ... but can rely on #doesNotUnderstand: for forward all calls.
- To access the proper UserInterfaceTheme instance for an object, send it #userInterfaceTheme.  The default implementation on Object returns an instance of UserInterfaceThemeRequest that provides a lightweight, clean proxy of the actual theme in use by the IDE at the current time. To do anything more sophisticated than basic querying and setting of properties, you must ask the proxy for the actual theme by sending #theme.
  
+ Most widgets access the current theme in their implementation of #setDefaultParameters (typically called from #initialize or similar). Since their properties are state-based, they must also implement #applyUserInterfaceTheme to get notified when the theme changes. It is advisable to not read from the current theme in drawing methods or methods that are called frequently. Please cache that information nearby such as in the widget's instance variables.
+ 
+ 
  Customizing the Theme
+ ===
  We can ask the #userInterfaceTheme for the value of any visual property by name:
  
  	mySystemWindow userInterfaceTheme closeBoxImage
  
  Initially that would answer nil, which causes the legacy code to use whatever default it used so far. To override various visual properties of any kind of object, the #set:for:to: message can be used, for example:
  
+ 	UserInterfaceTheme current
- 	myUserInterfaceTheme
  		set: #closeBoxImage 
  		for: SystemWindow
  		to: MenuIcons smallCancelIcon
  
+ Now the closeBoxImage message will answer the MenuIcons icon instead of nil. Now go ahead and open a new window. :-)
- Now the closeBoxImage message will answer the MenuIcons icon instead of nil.
  
  Alternatively, values may be derived based on other values in the theme, as in:
  
+ 	UserInterfaceTheme current
+ 		derive: #color for: FillInTheBlankMorph
+ 		from: MenuMorph at: #color
+ 		do: [:c | c alphaMixed: 0.5 with: Color yellow ]
+ 		
+ This makes FillInTheBlankMorph use the same color as a MenuMorph but #twiceDarker, providing a clean way to build coherent sets of colors within a theme. SystemWindow's code can be changed to use the expression above to access elements of the theme (if it doesn't do so already). Now go ahead and open an input dialog like this: " Project uiManager request: 'Hello!!' "
- 	myUserInterfaceTheme
- 		set: #color 
- 		for: FillInTheBlankMorph
- 		to: { MenuMorph->#color. #twiceDarker }
  
+ Note that if you want to update existing widgets, you might have to call "UserInterfaceTheme current apply" again to broadcast your changes.
- This makes FillInTheBlankMorph use the same color as a MenuMorph but #twiceDarker, providing a clean way to build coherent sets of colors within a theme. SystemWindow's code can be changed to use the expression above to access elements of the theme.
  
  Upgrading Legacy Code
+ ===
  Following the introduction of this class, various client code all around the system must be modified to access it. This variety of legacy code uses a variety of methods to specify their visual properties:
  
  	1) a hard-coded values.
  	2) a values derived from some other value.
  	3) providing local storage for a settable value which can be nil.
  	4) providing local storage for a settable value which is expected to always have a particular valid value (never nil).
  
  The requirement, for each case, is to let the value be overridden. 
  
  The solution for each of the above should be handled respectively to the above list, as follows:
  
  	1) Check the #userInterfaceTheme, if that property returns nil, use the legacy hard-coded value. (see example: SystemWindow>>#createCloseBox).
  	2) Nothing to do -- simply perform the same derivation on the result of (1).
  	3) Check the local storage, if present, use it. If nil, then check the #userInterfaceTheme, if it has this property present, use it, else return nil.
  	4) Check the #userInterfaceTheme, if the property is not nil, use it, otherwise use the local value.
  
  Tool Support
+ ===
+ If a new access to #userInterfaceTheme is added to the code, be sure to add the property and its description to the #themeProperties for that class. See implementors of #themeProperties for examples.!
- If a new access to #userInterfaceTheme is added to the code, be sure to add the property and its description to the #themeSettings for that class. See implementors of #themeSettings for examples.!