Config Library: 4.1 Object Class Reference: PrefClass

PrefClass defines several fields of instance data which will be used by all of its subclasses.

There are several variable data fields which make sure that a given Preference gadget will not be usable by those without the proper privileges; other fields make sure that the gadgets will not appear to those users whose UI levels indicate that they would be confused by the presence of such an object. Keep in mind that if all gadgets in your module demand some privilege or User level, you should reflect this in the routine which provide Preferences module information about your module.

Code Display 22-4 PrefClass Instance Data

@class PrefClass, GenClass, master, variant;

@instance PrefAttributes  PI_attrs = (PA_LOAD_IF_USABLE|PA_SAVE_IF_USABLE);

typedef ByteFlags  PrefAttributes;
#define  PA_REBOOT_IF_CHANGED 0x80
/* This bit signals that changes in the state of 
 * this object requires a system reboot to take effect. */

#define PA_LOAD_IF_USABLE 0x40
 /* Load options only if this object is usable (this is ON by default). */

#define PA_SAVE_IF_USABLE 0x20
 /* Save options only if this object is usable (this is ON by default) */

#define PA_SAVE_IF_ENABLED 0x10
 /* Save options only if this object is enabled */

#define PA_SAVE_IF_CHANGED 0x08
 /* Save options only if this object has changed. */

@vardata optr  ATTR_PREF_REBOOT_STRING;
/* This is the string passed to MSG_PREF_MGR_DO_REBOOT_DIALOG -- the
 * string must be in a SHARABLE LMEM resource and is incorporated into the
 * middle of another sentence. In English, the sentence is "The system software
 * will shut down and restart to change the <reboot_string>. Do you wish
 * to proceed?"
 *
 * If an object has its PA_REBOOT_IF_CHANGED attribute set, it will scan for
 * this attribute, first in itself, then up the generic tree, until it
 * finds one. */
@reloc ATTR_PREF_REBOOT_STRING, 0, optr;

@vardata PrefMgrFeatures ATTR_PREF_REQUIRED_FEATURES;
/* features bits that must be set for this object to be usable. */

@vardata PrefMgrFeatures ATTR_PREF_PROHIBITED_FEATURES;
/* features bits that must not be set for this object to be usable. */

@vardata UIInterfaceLevel ATTR_PREF_MIN_LEVEL;
/* interface level below which this object will not be usable */

@vardata UIInterfaceLevel ATTR_PREF_MAX_LEVEL;
/* interface level above which this object will not be usable */

In addition to the instance data fields, there are messages which allow for the dynamic retrieval and updating of these fields.

MSG_PREF_SET_INIT_FILE_CATEGORY

void MSG_PREF_SET_INIT_FILE_CATEGORY(
        const char *category);

Pref objects automatically respond to this message by changing the value of the ATTR_GEN_INIT_FILE_CATEGORY variable data field. This is a utility message; similar functionality is available via MSG_META_ADD_VAR_DATA.

Source: Anywhere

Destination: Any PrefClass object.

Parameters: category Null-terminated category string.

Return: Nothing.

MSG_PREF_HAS_STATE_CHANGED

Boolean MSG_PREF_HAS_STATE_CHANGED();

This message determines whether the object or any of its children have changed since the last time options were loaded. This is used in conjunction with the PA_REBOOT_IF_CHANGED flag that can be set for an object--this flag signals that, if the object changes state, then GEOS should be restarted for the change to go into effect.

Source: PrefClass object sends this message to itself when handling MSG_PREF_GET_REBOOT_INFO .

Destination: Self.

Parameters: None.

Return: Should return true (i.e. non-zero) if state has changed, false (i.e. zero) otherwise.

Interception: New PrefClass subclasses will use this to compare the object's current state against the "original" state, assuming one was stored.

MSG_PREF_GET_REBOOT_INFO

optr MSG_PREF_GET_REBOOT_INFO();

This message asks whether the system will need to reboot as a result of changes. If a reboot is necessary, the dialog will then notify the user of the reboot, and give the user a chance to abort (since the system reset may be a lengthy process on some systems).

Source: PrefDialog sends this message to all children on an apply.

Destination: Any Pref- object.

Interception: Subclasses should check the PA_REBOOT_IF_CHANGED flag--if the flag is set, the object should compare its present value to its "original" value. If a reboot is never needed, then do nothing.
If a reboot is necessary, the method should return the string to use when rebooting. The standard way to do this is via MSG_PREF_GET_REBOOT_STRING .
If possible, developers should try to avoid situations where a system reset is necessary, and use mechanisms such as the General Change Notification instead.

Parameters: None.

Return: Zero if no reboot needed; otherwise the OD of string to insert in the confirm-shutdown dialog box. The string will be inserted into a sentence; the string should describe what is changing. You may wish to use the value of ATTR_PREF_REBOOT_STRING.

See Also: MSG_PREF_GET_REBOOT_STRING , ATTR_PREF_REBOOT_STRING.

MSG_PREF_GET_REBOOT_STRING

optr MSG_PREF_GET_REBOOT_STRING();

This message should return the optr of a string in a sharable local memory resource. This string will display in the dialog box which asks the user if it is all right to shut down. If a given object doesn't know of a good string to supply, it should forward the message on to its parent in the generic tree. The default PrefClass handler returns the value stored in ATTR_PREF_REBOOT_STRING.

Source: Pref- object sends this message to itself.

Destination: Any PrefClass object.

Parameters: Nothing.

Return: Object Pointer of string (or NULL if not found).

MSG_PREF_INIT

void MSG_PREF_INIT(
        PrefMgrFeatures 		features,
        UIInterfaceLevel 		level);

This message initializes the object. The object should perform any required set-up to appear on-screen. The PrefDialog object will send this object to all of its children when the dialog is first initiated.

Source: Generic Parent

Destination: Any Pref- object.

Parameters: features This structure tells you a bit what sorts of changes the user prepared to make.

level: The user's User Level.

Return: None.

Interception: Default behavior is to determine whether to make the object usable based on UI level and features (or will be, when implemented). Subclass should call superclass before handling, as subclass behavior may be different if the object is not usable.

MSG_PREF_NOTIFY_DIALOG_CHANGE

void MSG_PREF_NOTIFY_DIALOG_CHANGE(
        PrefDialogChangeType 			type);

This message goes out via PDGCNLT_DIALOG_CHANGE list bound to PrefDialog object telling interested parties of a change in the box's state. It is sent when the dialog box is being opened, closed, or destroyed.

Source: PrefDialog object.

Destination: Any Pref- object registered on PDCGCNLT_DIALOG_CHANGE.

Interception: This message has no default handler; it must be intercepted to do anything useful.

Structures:

typedef enum {
	 PDCT_OPEN,
	PDCT_CLOSE,
	PDCT_DESTROY,
	PDCT_RESTART,
	PDCT_SHUTDOWN
}  PrefDialogChangeType;

MSG_PREF_SET_ORIGINAL_STATE

void MSG_PREF_SET_ORIGINAL_STATE();

This message copies the object's current state to the "original" value field, which will be used on a MSG_GEN_RESET .

Parameters: None.

Return: Nothing.

Interception: Subclasses should respond to this message by copying their current value to whatever instance field represents the "original" state of the object.

GEOS SDK TechDocs |

4 Object Class Reference | Next:

4.2 PrefValueClass