This document details how to setup preferences for your application.
Initializating the preferences
The first thing you must do to setup preferences for your application is create a
- 2 recommended routines (more flexible)
- and 3 other routines (might become obsolete one day)
Note: that you can build your own custom storage, by implementing the class
out of the box for correct or preferred functioning. Those files also contain additional attributes for preference configuration such as more detailed descriptions of the preference. If two files list the same preference, the last one to mention it takes precedence.
The format of the XML default file is very simple:
For backward compatibility, there is a default
To create an implementation of
In this scenario an underlying data store location will be created for you automatically based on the current system settings. For example, if you are using the Windows Registry as your data store, and your program is is called my_program.exe, then a registry key will be created in HKEY_CURRENT_USER\Software\myprogram.exe. In between user sessions the preference name-value pairs will be stored in this key location. This particular method of creating preferences is ideal if you are not particularly concerned where the values are stored. You may think of it as the "it just works" mode, and it is ideal for development and simple use.
The option (
Once you have created a
Now you have your preferences and at least one manager to put them in you can create the actual preferences. Preferences are generic, and all preferences inherit the class TYPED_PREFERENCE [G]. G denotes the type of the preference, for example INTEGER for a preference containing an integer value. Depending on the type you will use a factory class to actually create the new preference. By default the library supports 6 types of preferences, 4 basic type ones and 2 graphical types. The table below clearly indicates the currently available preferences and the factory class you should use to create them:
|Preference type||Description||Factory class||Factory method|
| ||Stores boolean value (true or false)|| || |
| ||Stores an integer value|| || |
| ||Stores a string value|| || |
| ||Stores a list of string values|| || |
| ||Stores a color value (rgb)|| || |
| ||Stores a font value (font name, face, height, etc)|| || |
When you create a preference using a factory class you will provide a manager, a name for the preference, and a value. For example, in
new_integer_preference_value (a_manager: PREFERENCE_MANAGER; a_name: STRING; a_fallback_value: INTEGER): INTEGER_PREFERENCE
-- Add a new integer preference with name `a_name'. If preference cannot be found in
-- underlying datastore or in a default values then `a_fallback_value' is used for the value.
name_valid: a_name /= Void
name_not_empty: not a_name.is_empty
not_has_preference: not a_manager.known_preference (a_name)
has_result: Result /= Void
preference_name_set: Result.name.is_equal (a_name)
preference_added: a_manager.preferences.has_preference (a_name)
end An appropriate example in code of this could be:
-- Preference holding value for width of application main window
-- Initialize the application preferences
window_width_preference := factory.new_integer_preference_value (my_manager, "window_width", 480)
endThis will create a new preference, which you can then use in your application to get, set and save the corresponding value when necessary. The issue to be aware of here though involves the value that the preference will contain when it is created. You see in the code above we pass the integer value 480. This does not mean, however, the initial value of the preference will be 480. This may sound odd, so let me explain...The value of a preference when initialized is determined by a number of factors. The first of these is the underlying data store value. If a preference value was changed in a previous session, by the user or by the application directly, and was saved to the underlying data store, then this value will be given priority. This makes sense, since if a user changes their preferences they don't want to have to do it every time they use your program. So, if they want the default window width to be larger, say 600, then this will be the value of the preference named "window_width" when initialized next time. Following this, if there is no previously saved value then the library will look for a default value to use. If a default file was given when the preferences were created (see above), and this default specifies a default value of 240 for the integer preference called "window_width", then this will be used. Finally, if no preference value was previously stored and no value is provided as a default value then the supplied value in the code is used - our 480 value from the example above. Although this process may seem confusing it is infact very simple and intuitive way to initialze the preferences. The process chart below illustrates more clearly the various permutations.
Using and Manipulating Preferences
Now you have preferences created you may use them from your application. Using the example preference above, window_width_preference, you can query the value of the preferences by simply querying the preference directly:
window_width := window_width_preference.value
Or for a value which should always be associated to the preference:
-- Width of window
Result := window_width_preference.value
If you need to react when a preference value is changed you can hook up an agent to the
window_width_preference.change_actions.extend (agent my_agent_routine)
To manually set the value of the preference call
To save the current preference to the underlying data store you must call
The preference window interface provided with the library will allow users to set there own preference values and will save the values upon confirmation. However, if you are using preferences in your code and do not wish to provide an interface for preference modification you must remember to manually save the preferences.
You can save all preferences at once my calling