CLASS Configuration FROM Persistent

Contains (persistent) module configuration info


Super classes

Persistent

Return

The function Configuration() returns the class object of the Configuration class.

Description

The Configuration class provides a means of bundling together all the data associated with configurable aspects of modules. As well, the class provides mechanisms for persistent storage of its instances via serialization and diskfile storage. As an adjunct to the persistence mechanism, the Configuration class has methods for handling the anticipatable event that the Configuration class is updated, which would cause the library version to differ from previously stored persistent instances.

The canonical method of accessing an instance of the Configuration class is via the Library Cfg() function (See the "Life Cycle" section of this page, and the Cfg() function documentation).

Each instance of the Configuration class contains a member :version that is used to indicate the currentness of the (possibly persistent) instance. The methods :uptoDate(), :verUpdate() and :antiquated() utilize the :version instance data member for comparison with the class :C_version data member

The Configuration instance member :savedCfg is always initialized as false; by definition, at time of creation an instance has not been read from persistent storage. The only action that can change the value of :savedCfg is reading back a serialized instance with the :fromDisk() method. The :toDisk() does not modify the value of :savedCfg (however, an instance serialized by :toDisk() will not normally become a runtime instance except when instantiated with :fromDisk()).

The Configuration class supports introspection via the standard data members :_data and :_methods.

Class Data

The class data associated with persistence and versioning is declared in the parent class Persistent. See its documentation for details on those data members.

Class Methods

:new()
Creates an instance of the Configuration class.
:exposeSelf() [implementation]
When implemented in a child class (of Persistent), :exposeSelf() is responsible for setting the child class' introspection and version data. All of the exposable data and method members of the child should be listed in :C_data and :C_methods, respectively. However, the exposed members declared in Class Persistent itself, will be added to the introspection data by :exposeParent().
:initClass()
Initializes class data to default values. By contract with its parent, Persistent, :initClass() must call ::exposeSelf(), then ::exposeParent()

Life Cycle

A Configuration instance comes into existence immediately upon its assignment with the Configuration():new() method. No seperate :create() method is required to request system resources.

A Configuration instance is destroyed when its variable falls out of its declaration scope. In principle, the variable containing a Configuration instance can be declared LOCAL to a function, and the exit condition of the controlling function will preform all necessary destruction of the instance.

However, in practical use, each module will access a single STATIC instance of the Configuration class via the Cfg() function. The instance managed by the Cfg() function is self-initializing and will de-serialize itself from diskfile if one is available. In other words, the Cfg() function can be treated as a globally available and persistent Configuration instance.

While the Cfg() function's Configuration instance will de-serialize itself from diskfile automatically, it will only be serialized with calls to the :toDisk() method. When changes are made to Configuration data that the programmers desires to be persistent, it is necessary to "commit" the changes with the :toDisk() method.

Instance Data

The instance data associated with persistence and versioning is declared in the parent class Persistent. See its documentation for details on those data members.

:Font_Alert [EXPORTED; Character ("10.Arial")]
What font to use in Alert/Inform dialogs?
:ButtonLabels [EXPORTED; Boolean (.F.)]
Display text labels on (most) buttons?
:GrayBar [EXPORTED; Boolean (.F.)]
Display an "Outlook-style" gray bar with screen title?
:ColorScheme [EXPORTED; Object (ColorScheme():new())]
What color scheme to use? Since the :ColorScheme data member is itself an object, it will usually be necessary to refer to the nested data or methods of this data. E.g. oCfg:ColorScheme:Titlebar
:MY_Date [EXPORTED; Date (DATE())]
What posting date to use in entry? See Functions PostDate() and Change_Postdate() also.

Instance Methods

:init() [implementation]
Set introspection data members and default values for exposed data members (see Class method :new() for a discussion of the special initializiation procedure of this class)
:toDisk(<cFile>) [implementation]
Writes a serialized copy of the instance to a diskfile. If no parameter is passed as a filename specification, the file MY_HOMEPATH+"USER.CFG" is used.
:fromDisk(<cFile>) [implementation]
Reads a serialized copy of a Configuration instance from diskfile. (if possible). If no file is specified, or if the file specified does not exist, ::savedCfg is simply set to .F., and a reference to the original instance is returned. Otherwise, the serialized data is read in, ::savedCfg is set to .T., and the read instance is returned.

Since XBase++ does not allow redefinition of self, the methods :fromDisk() and :verUpdate() return the modified Configuration instance, but do not update the existing instance in-place.

:antiquated() [implementation]
Return a character string report of the differences (if any) between the calling instance's and the Class' introspection data and version number.
:verUpdate() [implementation]
Returns an updated copy of an instance. Any data members of the current Class' instrospection data that are also present in the instance are copied into a new instance of the Configuration class. All other data members, and all methods, are defined according to the definition and initialization values of the most current version.

Two data members, however, will be given Library/Class default values rather than the values existing in the calling instance. These are :version, which is not changed because all version-specific structure is updated in the returned instance; and :ColorScheme, which reinitialized under the (paranoid) assumption that the Class ColorScheme might have changed structure also.

Since XBase++ does not allow redefinition of self, the methods :fromDisk() and :verUpdate() return the modified Configuration instance, but do not update the existing instance in-place.

:uptoDate() [implementation]
Returns a boolean value indicating whether the calling instance is current with the Class definition in the Library.

Examples

? Cfg():className() // Result: "Configuration"

// Check a configuration value
IF Cfg():GrayBar
  DrawGraBox(22, 0, 23, 79, "FLAT_PALE_BIGTEXT", cTitle)
ENDIF

// Set, serialize, and save a configuration value
Cfg():GrayBar := .T.
Cfg():toDisk()

// Operate on instance via variable name
oCfg := Cfg()
oCfg:GrayBar := .F.
oCfg:toDisk("Temp.CFG")

// Read a serialized instance from a diskfile
oCfg := Configuration():new():fromDisk("MyFile.CFG")

// Check what is out-of-date in the restored instance
MsgBox( oCfg:antiquated() )

// Update the configuration to match current class definition
oCfg := oCfg:verUpdate()

Files

Source file is Configuration.prg


See Also:

Cfg()

Class ColorScheme