Config Library: 1.1 Providing the UI: Designing the UI Tree.

Preferences modules present a dialog box to the user. You will need to design the dialog for your module. As you do so, you may find objects of the following classes useful. Each of the following classes is based upon one of the Generic UI classes.

GenClass provides mechanisms by which objects will read and write values to the .INI file. Pref- classes provide further functionality, such as storing an "original" value to revert to if the user decides to Cancel their changes.

The following Pref- classes are available:

PrefDialogClass: This class specializes in acting as the root of a Pref module's UI tree. It has been set up to provide "OK" and "Cancel" triggers by default. It has a mechanism to restart the system on an Apply if the module specifies that such a reset will be necessary to implement the user's changes.
Often a module will use a subclass of PrefDialogClass as the head of its UI tree--often the subclass intercepts MSG_GEN_APPLY to ensure valid user choices and to take other appropriate actions.
PrefValueClass: PrefValue objects act like objects of GenValueClass . However, these objects have the ability to reset their values to that originally stored in the .INI file (in case the user wants to cancel). They can handle only word-length values.
PrefItemGroupClass: Objects of this class act like GenItemGroups. In addition, this class has the ability to store an "original" value.
PrefStringItemClass: A PrefItemGroup normally writes data about selected items in the form of an integer. However, if its children are PrefStringItem objects, the PrefItemGroup can instead write out a special string associated with each PrefStringItem, resulting in a more readable .INI file.
PrefBooleanGroupClass: This class acts like GenBooleanGroupClass with the ability to store an "original" value.
PrefDynamicListClass: Use objects of this class where you might otherwise use a GenDynamicList. This class will not work together with PrefStringItem objects.
PrefTocListClass: This class presents an alphabetized list of files or driver names. It is used to provide lists of devices, such as the list of available printers. It can also be used to show a list of files with a given token in a given directory.
TitledGlyphClass: This specialized subclass of GenGlyph shows both an icon and a text moniker. It is used to present the icon and name at the top of a typical Preferences module dialog box.
PrefInteractionClass: This class acts like GenInteractionClass , but also will relay certain messages to its children which GenInteraction would not. Those objects which will need to work with the .INI file should receive these messages, so any Gen- objects which will work with the .INI file and any Pref objects should be grouped under PrefInteractions instead of GenInteractions.
PrefTextClass: This class behaves like GenTextClass , except that it will load and save its value based upon that stored in the .INI file.
PrefTriggerClass: This class acts as does GenTriggerClass, but has an extra action, so that two separate messages will be sent when the trigger is activated.
PrefControlClass: This class acts as a cross between PrefClass and GenControlClass .
PrefTimeDateControlClass: This class allows the user to set the system date and time.
PrefClass: PrefClass is something like GenClass --while never used directly, it is the superclass of all the other Pref- classes, and sets up several of the mechanisms which all will use.

There aren't any special restrictions on what sorts of objects appear in the UI tree of a Preferences module. However, the following rules will prove useful in constructing modules that correctly write their data to the .INI file and have a look and feel consistent with existing modules. For an example, see Pref Module UI Framework .

As a rule of thumb, the top object of the tree should be a PrefDialog.
For a consistent look, the upper portion of the dialog should contain the module's icon, name, and some brief help text. This is normally done using a TitledGlyph and a GenText object.
Generally the easiest way to specify the .INI file category and key to use is by means of ATTR_GEN_INIT_FILE_CATEGORY and ATTR_GEN_INIT_FILE_KEY. Assuming that the module will work with just one category, it is sufficient to declare an ATTR_GEN_INIT_FILE field for just the top object of the module's UI tree.
Because of the way messages are relayed, you should use PrefInteractions instead of GenInteractions if any objects under the interaction will be saving data to the .INI file.

Code Display 22-1 Pref Module UI Framework

@object MPMDialogClass MPMRoot = {
	GI_states = @default & ~GS_USABLE;
	GI_comp = @MPMTitleGroup, @MPMOtherStuff;
	HINT_INTERACTION_SINGLE_USAGE;
	HINT_INTERACTION_COMPLEX_PROPERTIES;
	HINT_ORIENT_CHILDREN_VERTICALLY;
	HINT_LEFT_JUSTIFY_CHILDREN;
	ATTR_GEN_HELP_CONTEXT = "myPrefModule";
	ATTR_GEN_INIT_FILE_CATEGORY = "myPref";
}

@object GenInteractionClass MPMTitleGroup = {
	GI_comp = @MPMTitle, @MPMHelp;
	HINT_ORIENT_CHILDREN_HORIZONTALLY;
	HINT_EXPAND_WIDTH_TO_FIT_PARENT;
}

@object TitledGlyphClass MPMTitle = {
	GI_visMoniker = list {
		@FontTextMoniker, @FontLCMoniker, @FontLMMoniker, @FontLCGAMoniker
 	}
}

@object GenTextClass MPMHelp = {
	GI_attrs = @default | GA_READ_ONLY;
	GTXI_text = "Do such and such to configure your so and so.";
	HINT_EXPAND_WIDTH_TO_FIT_PARENT; 
	/* Might want HINT_MINIMUM_SIZE */
}

GEOS SDK TechDocs |

1 Providing the UI | Next:

1.2 UI Fetch Routine