Hi guys I was reading the comment of the SettingManager (may be should be called a preference manager). But this is impressive. We should start in 1.1 to use setting. Stef System settings are used to manage useful global parameters. A system setting is an instance of SystemSettingNode or of one of its subclasses. SettingManager is a facade for system setting instanciation. A setting is declared by a class method with a simple pragma. The pragma allows the SystemSettingBrowser to dynamically discover current settings. The default system setting pragma is <setting>. The important point is that a setting must be package specific. It means that each package is responsible for the declaring of its own settings. For a particular package, specific settings are declared by one or several of its classes. The consequence is that when the package is loaded, then its settings are automatically loaded and that when a package is unloaded, then its settings are automatically unloaded. Basically, settings are of two main kinds: setting nodes and settings with value. - A setting node don't hold any value. Such a setting is declared by a method which simply returns a SystemSettingNode instance. Any setting can declare any setting node as its parent. - A setting with value is an instance of SettingValue or of one of its subclasses. Such a setting holds a useful global system parameter and is made persistent: it is stored in a class variable which is initialized by the method that declares the setting. 1 DECLARING A SETTING NODE All System settings are organized in trees. Each tree root is a setting with no parent (parent set to nil). Whatever setting can be a root. If a root doesn't need to keep any value, then it can be an instance of SystemSettingNode. Such a setting is instanciated with: #SettingManager class>>newNode:. The argument is the name of the node. A setting node is mostly useful for the grouping of several related settings. The dialog instance variable can be set to the name of a dialog class. Then, the SystemSettingBrowser shows a button for this dialog: when pressed, the class which name is the dialog instance variable value receives the #open message. It can be useful in order to open a complex or handy dialog for the input of some settings. The example below shows a root node named 'System' declared in a SystemSettings class. ------------------ SystemSettings class>>systemSettingNode <setting> ^ (SettingManager newNode: 'System') description: 'All standard system settings' ------------------ The example below shows a the declaration of a subnode of systemSettingNode, it is declared in a UISettings class: ------------------ UISettings class>>UINode <setting> ^ (SettingManager newNode: 'User interface') description: 'Paramaters for the user interface'; parent: #systemSettingNode ------------------ 2 DECLARING SIMPLE VALUE SETTINGS 2.1 PRESENTATION A simple value setting is a setting which value is a Boolean, a String, a Symbol, a Number, a Font or a Color. Such a setting is hold by a SettingValue which is instanciated with #SettingManager class>>newSetting:. The argument is the name of the setting. If the setting has a default value, then, the setting is declared with the default value as below: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting name') description: 'A useful description'; default: aDefaultValue] ------------------ where: - MyPackageSettings is a class of MyPackage package (a system setting is declared class side) - mySetting is the getter for the setting - MySetting is the name of the class variable which value is the setting (instance of SettingValue) - 'My setting label' and 'A useful description' are respectively, the name and the description shown by the SystemSettingBrowser. - aDefaultValue is the default value for the setting If the setting doesn't have any default value (or if its default value is nil): ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting name') description: 'A useful description'; type: aTypeSymbol] ------------------ aTypeSymbol is a symbol used by the setting browser in order to know how to build the input widget. By default, possible values are #Boolean, #String, #Symbol, #Integer, #Float, #Font or #Color. It can be of another value but in that case, the class which name is the type value should understand the #settingInputWidgetForNode: message. Classically, a SettingValue is not a root: it is declared as a child of one or several nodes in order to ease its managing. ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting name') description: 'A useful description'; parent: aParentNodeSelector; type: aTypeSymbol] ------------------ aParentNodeSelector is a symbol which is the parent node method selector. A setting node may have several parents: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting name') description: 'A useful description'; parent: firstParentNodeSelector; parent: secondParentNodeSelector; type: aTypeSymbol] ------------------ or ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting name') description: 'A useful description'; parents: #(firstParentNodeSelector secondParentNodeSelector); type: aTypeSymbol] ------------------ 2.2 SIMPLE VALUE SETTING EXAMPLES 2.2.1 Boolean settings Definition of the boolean setting "newbyMode" with only a label and a default value: ------------------ MyClass class>>newbyMode <setting> ^ NewbyMode ifNil: [NewbyMode := (SettingManager newSetting: 'Newby mode') default: false]. ------------------ A description could be very helpful when using the SystemSettingBrowser: ------------------ MyClass class>>newbyMode <setting> ^ NewbyMode ifNil: [NewbyMode := (SettingManager newSetting: 'Newby mode') default: false; description: 'the useful description goes here...']. ------------------ The default value is optional. If not present, the declaration must explicitly initialize the setting type: ------------------ MyClass class>>newbyMode <setting> ^ NewbyMode ifNil: [NewbyMode := (SettingManager newSetting: 'Newby mode') type: #Boolean; description: 'the useful description goes here...']. ------------------ 2.2.4 Color setting Note that the default can be a valuable. Here, the default is given by a MessageSend instance: ------------------ MyClass class>>desktopColor <setting> ^ DesktopColor ifNil: [DesktopColor := (SettingManager newSetting: 'Desktop color') parent: #uiColors; description: 'The color used for the desktop background'; default: (MessageSend receiver: Color selector: #green)] ------------------ You can also use a block for the default: ------------------ MyClass class>>desktopColor <setting> ^ DesktopColor ifNil: [DesktopColor := (SettingManager newSetting: 'Desktop color') parent: #uiColors; description: 'The color used for the desktop background'; default: [Color green]] ------------------ 2.2.5 Font setting Here the default is an instance of LogicalFont: ------------------ MyClass class>>codeFont <setting> ^ CodeFont ifNil: [CodeFont := (SettingManager newSetting: 'Code') description: 'The code font'; parent: #fontSettingNode; default: (LogicalFont familyName: 'DejaVu Sans' fallbackFamilyNames: nil pointSize: 12 stretchValue: 5 weightValue: 400 slantValue: 0)] ------------------ The default can also be set with a MessageSend instance: ------------------ MyClass class>>codeFont <setting> ^ CodeFont ifNil: [CodeFont := (SettingManager newSetting: 'Code') description: 'The code font'; parent: #fontSettingNode; default: (MessageSend receiver: self selector: #defaultStandardFont)] MyClass class>>defaultStandardFont ^ LogicalFont familyName: 'DejaVu Sans' fallbackFamilyNames: nil pointSize: 12 stretchValue: 5 weightValue: 400 slantValue: 0 ------------------ 3 DECLARING A SETTING WITH FINITE SET OF VALUES 3.1 PRESENTATION A setting can be defined so that its value is get from a restricted set of values. The setting is an instance of MultipleSettingValue. It is instanciated with #SettingManager class>>newMultiple:. The argument is the name of the setting. The collection of values from which a multiple setting takes its value is always a set of FixedSettingValue. A FixedSettingValue is created with #SettingManager class>>newFixed:. Such a setting can be of two different kinds : - if the valid value list is known at declaration time and is constant, then the list of values is set by sending the #domainValues: message to the setting. The argument is an array of fixed values. Such a setting can be declared as below: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newMultiple: 'My setting name') description: 'A useful description'; default: aDefaultValue; domainValues: aListOfFixedSettingValues] ------------------ The default should be one of the valid values: a real value which is token from the list of possible values. - if the valid value list is not known at declaration time, then the list of possible values is dynamically computed by the SystemSettingBrowser by evaluating the block or the MessageSend stored as the getter instance variable value. The getter instance variable is set by sending the #domainValuesGetter: message to the setting. Such a setting can be declared as below: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newMultiple:'My setting name') description: 'A useful description'; default: aDefaultValue; domainValuesGetter: aBlockOrAMessageSend] ------------------ The argument of #domainValuesGetter: can be a block or a instance of MessageSend. This valuable takes no argument. 3.2 EXAMPLES The declaration gives all possibles values for the setting. Each possible domain value is a fixed setting (read-only setting). Here is the example of #hintingSetting which value can be #Light, #Normal, #Full or #None: ------------------ MyClass class>>hintingSetting <setting> ^ HintingSetting ifNil: [HintingSetting := (SettingManager newMultiple: 'Hinting') description: 'Defines the glyph shapes' translated; parent: #freeTypeSettingNode; domainValues: { SettingManager newFixed value: #Light. SettingManager newFixed value: #Normal. SettingManager newFixed value: #Full. SettingManager newFixed value: #None }]. ------------------ In the case where domain values are of simple type, as Symbol for example, the shorter declaration given below can be used: ------------------ MyClass class>>hintingSetting <setting> ^ HintingSetting ifNil: [HintingSetting := (SettingManager newMultiple: 'Hinting') description: 'Defines the glyph shapes' translated; parent: #freeTypeSettingNode; domainValues: {#Light. #Normal. #Full. #None}] ------------------ The value domain can also be made of a set of complex objects. The example below shows #themeSetting setting. The value domain is an array with two fixed settings, for UIThemeStandardSqueak and for UIThemeWatery2: ------------------ MyClass class>>themeSetting <setting> ^ ThemeSetting ifNil: [ThemeSetting := (SettingManager newMultiple: 'UITheme') description: 'The theme to use for UI look and feel'; parent: #uiSettingNode; type: #UITheme; default: UIThemeWatery2; domainValues: { (SettingManager newFixed: 'Standard Squeak') value: UIThemeStandardSqueak. (SettingManager newFixed: 'Watery 2') description: 'Similar to a nice OS'; value: UIThemeWatery2}] ------------------ The shorter declaration given below can also be used. The domain values is a list of association. Each association key is used as the name of the fixed setting, and the corresponding association value is used as the value of the fixed setting: ------------------ MyClass class>>themeSetting <setting> ^ ThemeSetting ifNil: [ThemeSetting := (SettingManager newMultiple: 'UI theme') description: 'The theme to use for UI look and feel'; parent: #uiSettingNode; type: #UITheme; default: UIThemeWatery2; domainValues: {'Standard' -> UIThemeStandardSqueak. 'Watery 2' -

UIThemeWatery2}]

Previous version has a serious drawback: the list of possible values is fixed, then the first time the setting is read, the list is definitively built. After its building, there is no way to update the list except by the reinitializing of the corresponding class variable (hard reset). Regarding the themeSetting example, the problem is that new instances of UITheme can be added in the system after the setting has been created and initialized. In order be able to take into account system dependent domain values, you can makes the list dynamically computed. A getter instance variable can be set to a block or to an instance of a MessageSend. Such a valuable is dynamically evaluated by the SystemSettingBrowser in order to get current and up-to-date list of valid values. Here is the themeSetting example revisited: ------------------ MyClass class>>themeSetting <setting> ^ ThemeSetting ifNil: [ThemeSetting := (SettingManager newMultiple:'UI theme') parent: #uiSettingNode; default: UIThemeWatery2; domainValuesGetter: [UITheme allSubclasses collect: [:cls | SettingManager newFixed value: cls]]] ------------------ or with a much simpler version ------------------ MyClass class>>themeSetting <setting> ^ ThemeSetting ifNil: [ThemeSetting := (SettingManager newMultiple:'UI theme') parent: #uiSettingNode; default: UIThemeWatery2; domainValuesGetter: [UITheme allSubclasses]] ------------------ 4 DECLARING RANGE SETTING 4.1 PRESENTATION A setting for which all possible values are given by a range is an instance of RangeSettingValue. Such a setting is instanciated with #SettingManager class>>newRange:. The argument is the name of the setting. The range is set by sending a #range: message to a setting. The argument is an Interval instance. Such a setting can be declared as below: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newRange: 'My setting name') description: 'A useful description'; default: aDefaultValue; range: anInterval] ------------------ The range is an instance of Interval. It is set by the #range: message and is evaluated by the SystemSettingBrowser when choosing a new value. Note that the SystemSettingBrowser presents an input field and a slider. 4.2 EXAMPLE ------------------ FontSettings class>>glyphContrast <setting> ^ GlyphContrast ifNil: [GlyphContrast := (SettingManager newRange: 'Glyph contrast') description: 'Change the contrast level for glyphs. This is an integer between 1 and 100'; parent: #freeTypeSettingNode; default: 50; range: (1 to: 100)] ------------------ 5 USING SPECIFIC DIALOG For setting browsing and editing, it could be useful to use a specific dialog instead of SystemSettingBrowser simple input widgets. For that purpose, the dialog attribute can be set with the name of a dialog class. While browsing a setting with a dialog, the SystemSettingBrowser presents a button for the dialog opening. The only constraint is that the dialog class must understand the #open message. For a node with children, it can be very useful in order to be able to use a cool dialog for the input of all children instead of being forced to input them one by one as it is the case with the SystemSettingrowser. Here is an example of a setting node with its dialog instance variable set to the value #FontSettingDialog. In the case of fonts, it could be useful in order to allow the using of a specific cool dialog for font preferences settings. ------------------ FontSettings class>>fontSettingNode <setting> ^ (SettingManager newNode: 'Fonts') description: 'System fonts settings'; dialog: #FontSettingDialog; parent: #uiSettingNode ------------------ The dialog instance variable can be set for a setting value too. Then, neither the default value nor the type is needed: ------------------ UISettings class>>uiStyle <setting> ^ UIStyle ifNil: [UIStyle := (SettingManager newSetting: 'UI style') dialog: #UIStyleChooserDialog; description: 'System style']. ------------------ 6 SIMPLE SETTING WITH CHILDREN A setting value can be a parent for another setting value. As an example, #gradientButtonLook can be a child of a boolean setting #advancedGUISetting: ------------------ MyClass class>>advancedGUISetting <setting> ^ AdvancedGUISetting ifNil: [AdvancedGUISetting := (SettingManager newSetting: 'Advanced GUI settings') parent: #uiSettingNode; default: true] MyClass class>>gradientButtonLook <setting> ^ GradientButtonLook ifNil: [GradientButtonLook := (SettingManager newSetting: 'Gradient look for buttons') parent: #advancedGUISetting; default: true] ------------------ 7 MANAGING SETTING VALUES 7.1 GETTING AND CHANGING A SETTING VALUE Let's use the following example of a boolean setting declaration: ------------------ MyPackageSettings class>>mySetting <setting> ^ MySetting ifNil: [MySetting := (SettingManager newSetting: 'My setting label') default: true] ------------------ The following two expressions are used in order to, respectively, get and set the value of the setting: ------------------ MyPackageSettings mySetting value. "get the value of the setting" MyPackageSettings mySetting value: false. "change the value of the setting" ------------------ 7.2 SETTING VALUE CHANGE NOTIFICATION 7.2.1 REGISTERING A LISTENER Whatever object can be declared as a change listener for a particular setting: each time the setting value is changed, each listener is aware of the change by receiving a particular message. In order to declare a listener, a client object must send the #whenChangedSend:to: message to a setting. The first argument is a message selector and the second argument it a receiver for the message. Then, the receiver becomes a listener for the setting. The message selector can take zero or one argument. In the case of one argument, the changed setting value is passed as argument to the message send. Note that an object can be declared as a listener several times, each time with a different message selector. As an example, lets take the example of the desktopColor setting: ------------------ DesktopSettings class>>desktopColor <setting> ^ DesktopColor ifNil: [DesktopColor := (SettingManager newSetting: 'Desktop color') parent: #uiColors; description: 'The color used for the desktop background'; default: (MessageSend receiver: Color selector: #white)] ------------------ Each time the desktop color setting is changed, the World color should be changed according to the new setting value. A solution could be to declare the World as a listener for the desktopColor setting changes and make it change its color according to the desktopColor setting each time the desktopColor setting value is changed. This can be achieved from the class initialize method as below: ------------------ DesktopSettings class>>initialize self desktopColor whenChangedSend: #color: to: World. ------------------ 7.2.2 UNREGISTERING A LISTENER There is two ways to unregister a listener for a particular setting changes. - The first way is to globally unregister a listener whatever the message selector. After the listener is unregistered, it is totally ignored when the concerned setting is changed. This is achieved by sending a #forget: message to the setting with the listener as argument. Concerning the desktopColor setting example, the World can be unregistered as shown below: ------------------ DesktopSettings desktopColor forget: World. "no more notification at all" ------------------ - The second way is to unregister a listener for only a specific selector. This is achieved by sending a #forget:selector: message to the setting. The first argument is the listener and the second is a selector. Concerning the desktopColor setting example, the World can be unregistered for only the #color: selector as shown below: ------------------ DesktopSettings desktopColor forget: World selector: #color:. "The World can still be notified using another selector" ------------------