Config Library: 3 Important Messages

If you're going to create a subclass for use in a Preferences module, the following messages will be of special interest, as they signal that the user is carrying out certain important actions.

MSG_PREF_INIT: When a dialog box containing Pref objects is brought up, each object will receive MSG_PREF_INIT. Developers can subclass MSG_PREF_INIT to perform basic initialization procedures.
MSG_META_LOAD_OPTIONS: Generic objects (and by inheritance, Pref- objects) respond to MSG_META_LOAD_OPTIONS by loading a value from the appropriate place in the .INI file. This place is determined by the object's ATTR_GEN_INIT_FILE_KEY field. If the object has an ATTR_GEN_INIT_FILE_CATEGORY field, that category will be used; otherwise the default handler will look up the Generic tree for an object with a ATTR_GEN_INIT_FILE_CATEGORY field defined and will use the value stored there.
Unlike a GenInteraction, a PrefInteraction will relay this message to its children. When it's time to load options from the .INI file, a MSG_META_LOAD_OPTIONS will be sent to the top level of the module's UI tree. This message should be propagated down the tree to reach all objects which should read their values from the .INI file. This is why it is suggested that you use PrefInteractions in place of GenInteractions if any Pref- objects will be underneath. If you create a new sort of object which should relay this message to other objects, be sure to do so.
MSG_META_SAVE_OPTIONS: Generic objects (and by inheritance, Pref- objects) respond to MSG_META_SAVE_OPTIONS by saving a value to the appropriate place in the .INI file. This place is determined by the object's ATTR_GEN_INIT_FILE_KEY field. If the object has an ATTR_GEN_INIT_FILE_CATEGORY field, that category will be used; otherwise the default handler will look up the Generic tree for an object with a ATTR_GEN_INIT_FILE_CATEGORY field defined and will use the value stored there.
Unlike a GenInteraction, a PrefInteraction will relay this message to its children. When it's time to save options to the .INI file, a MSG_META_SAVE_OPTIONS will be sent to the top level of the module's UI tree. This message should be propagated down the tree to reach all objects which should write their values to the .INI file. This is why it is suggested that you use PrefInteractions in place of GenInteractions if any Pref- objects will be underneath. If you create a new sort of object which should relay this message to other objects, be sure to do so.
Often, interceptors of this message will carry out whatever actions are necessary to carry out the user's wishes in those cases where writing something to the .INI file is not enough to bring the change about.
MSG_GEN_RESET: If the user clicks on a "Revert" or "Cancel" button, all values in UI gadgets should revert to those values originally stored in the .INI file. You will note that many Pref- objects have an extra field to store their "original" value. If you create your own kind of Preferences object, keep in mind that it will need some way to store the "original" value (probably initialized while handling MSG_META_LOAD_OPTIONS ) and should intercept MSG_GEN_RESET to replace its value with the "original" value.
MSG_GEN_LOAD_OPTIONS: Generic objects (and thus Pref- objects) respond to MSG_META_LOAD_OPTIONS by sending themselves this message. This message is only meant to be used for managing the .INI file; any other functionality should occur in the handling of MSG_META_LOAD_OPTIONS.
MSG_GEN_SAVE_OPTIONS: Generic objects (and thus Pref- objects) respond to MSG_META_SAVE_OPTIONS by sending themselves this message. This message is only meant to be used for managing the .INI file; any other functionality should occur in the handling of MSG_META_SAVE_OPTIONS .

If you are interested in detecting certain user actions, the following list may prove useful:

User Opens Dialog: Any objects which need to do some initialization when the user first opens the module's dialog box should intercept MSG_PREF_INIT . After receiving MSG_PREF_INIT , each object will receive a MSG_META_LOAD_OPTIONS .
User clicks Apply: Assuming the top object of the module's UI tree is a PrefDialog and that the dialog has been set up as a Properties dialog (as it is by default), then this object will receive a MSG_GEN_APPLY when the user activates the Apply trigger. The Pref dialog responds to this message by sending itself a MSG_META_SAVE_OPTIONS , which it will then pass on to its children.
User clicks Cancel or Reset: All Gen- and Pref- objects within the UI tree will receive a MSG_GEN_RESET .

GEOS SDK TechDocs |

2 Module Information Routine | Next:

4 Object Class Reference