COBJ - The base class for all STx classes

From STX Wiki
Jump to navigation Jump to search

File: CLASSES.STX, linked to library STX.LIB


The class CObj implements some basic functions of the STx class library. Most other classes of the standard library are derived from this class. It should also be used as the parent class for classes implemented in scripts. The derived classes should call the overridden member functions of CObj.

Static Functions

New

COBJ NEW classname [ initargs ]
COBJ NEW classname::instname [ initargs ]
Create a new instance of class classname and initialize it. To initialize the instance the public member function Construct is called (newinst Construct [ initargs ]). The constructor must return 0 if the initialization was successful, or a non-zero value if the initialization has failed. If the initialization has failed, the instance newinst is deleted (without calling the destructor) and an empty string is returned.
If instname is specified, it is used as the name for the new instance. If an instance with name instname and class classname exists already, the function returns immediatly with result instname, without calling the Construct member function.
This function should be used rather than the command NEW INSTANCE, to create new instance items.
argument description default
classname Name of the class of the object (instance) to be created.
instname If not specified or set to *, a new instance with an automatically selected name is created. Otherwise, instname is used as name of the instance to be created.
Note: If an object with name instname and of class classname exists already, this object is returned and no new instance is created.
*
initargs Arguments for the Construct member of the new instance.
RESULT description
newinst Name of the created and initialized instance item.
instname Name of the existing or created instance item.
empty string Failed to create (e.g. undefined class) or initialize the new instance (Construct returned a non-zero value).
See also
Delete, Construct

Delete

COBJ DELETE instname
Calls the Destruct member function (instname Destruct), to reset the instance, and than deletes the instance item. The return value of Destruct is ignored.
This function should be used rather than the command DELETE instname, to delete instance items. If you just delete the instance using the DELETE instname command, then the destructor is not called!
argument description default
instname the instance item to be deleted.
RESULT description
undefined The function has no return value
See also
New, Destroy

Import

COBJ IMPORT classname ; filename ; silent
Import a settings profile of class classname from the file filename into the workspace. This function creates an instance of classname and calls the member function SerializeImport to import the file. The class classname must be derived from CObj and must implement the serialization interface members and a member function named Save, which saves a profile in the workspace. E.g. this function is used for the import of Viewer- and Color-profiles.
argument description default
classname Name of the class.
filename Name of the file containing the profile.
silent Set this flag to 1 to suppress the error/done message box. 0
RESULT description
0 Import failed.
1 Import successful finished.
See also
SerializeImport, Export

Export

COBJ EXPORT classname ; setupname ; filename ; silent
Export the settings profile setupname of class classname from the workspace to the file filename. This function creates an instance of classname and calls the member function SerializeExport to export the file. The class classname must be derived from CObj and must implement the serialization interface members and a member function named Load, which loads a profile from the workspace. E.g. this function is used for the export of Viewer- and Color-profiles.
argument description default
classname Name of the class.
setupname Name of the settings profile to be exported.
filename Name of the export file.
silent Set this flag to 1 to suppress the error/done message box. 0
RESULT description
0 Export failed.
1 Export successful finished.
See also
SerializeExport, Import

Public Functions

Construct

instname CONSTRUCT [ initargs ]
Default constructor. Currently this function do nothing and returns the result 0. For compatibility reasons it should be invoked by the constructors of derived classes.
argument description default
instname Instance of a class derived from CObj
initargs Initialization arguments. The CObj constructor takes no arguments.
RESULT description
0 Returns always 0 -> instance initialized.
See also
New, Destruct

Destruct

instname DESTRUCT
Default destructor. Currently this function do nothing and returns immediatly without any result (void). For compatibility reasoons it should be invoked by the destructors of derived classes.
argument description default
instname Instance of a class derived from CObj
RESULT description
undefined The function has no return value
See also
Delete, Destroy, Construct

Destroy

instname DESTROY
Calls the destructor to de-initialize the instance and than deletes the instance item instname.
argument description default
instname Instance of a class derived from CObj. This instance item instname is deleted by this function!
RESULT description
undefined The function has no return value
See also
Delete, Destruct

AttachItem / AttachShell

instname ATTACHITEM itemname [ mhfun ]
instname ATTACHSHELL shellid [ mhfun ]
Installes a message handler for the specified shell item (itemname) or shell (shellid). The message handler function mhfun must be a public member function of the instance instname.
argument description default
instname Instance of a class derived from CObj.
itemname The shell item to be attached to the message handler.
shellid The id of the shell to be attached to the message handler. The shellid can be obtained from the variable SHELL (= thisShellId callerShellId) or from the variable @MASTER (= masterShellId). If shellid is set to * a message handler for all shells will be installed.
mhfun The name of a public member function of instname which should process the messages. MsgHandler
RESULT description
undefined The function has no return value.
See also
DetachItem, MsgHandler, macro SetMsgHandler

DetachItem / DetachShell

instname DETACHITEM itemname [ delitem ]
instname DETACHSHELL shellid
Deinstalles the message handler for the specified shell item (itemname or shell (shellid).
argument description default
instname Instance of a class derived from CObj.
itemname The shell item to be detached from its message handler.
delitem If set to 1 the item itemname will be deleted after deinstalling the message handler. 0
shellid The id of the shell (or * for all shells) to be detached from the message handler.
RESULT description
undefined The function has no return value
See also
AttachItem, macro SetMsgHandler

MsgHandler

instname MSGHANDLER msgtype msgname msgid msgpar
This is the member function which processes the messages of shell items and/or shells attached to the instance instname using the function AttachItem or AttachShell. The function is called by the message handling system (see GETMESSAGE and DISPATCHMSG) when a message from an attached item/shell is received and dispatched.
argument description default
instname Instance of a class derived from CObj.
msgtype The type of the shell item sending the message or the string SHELL if the message was sent by a shell.
msgname The type of the shell item or the id of shell sending the message.
msgid, msgpar The message id and (optional) parameter. The value and meaning of these arguments depends on the type of the sender.
RESULT description
1 The message was processed by the message handler and no further message handling is necessary.
1 The message was not processed (see GetMessage).
Note
The default function performs no message processing and returns 1!
See also
AttachItem, macro SetMsgHandler, GetMessage, DispatchMsg

SerializeImport

instname SERIALIZEIMPORT file=* ; level=current [; params ]
This function performs all necessary operations to import/restore the object data. After initializing the xml fileitem containing the element to be imported and preparing the member varaibles, the onSerializeImport member is called to perform the element/data import.
argument description default
instname Instance of a class derived from CObj.
file the import file: a xml fileitem, a xml filepath or * to use a dialog to select the import file *
level selects the level of the import element (only if file is a xml fileitem); use the keywords current (search on the current level), child (child of the current element) or select the level by an iref (internal reference) current
params a list of serialization parameters which are passed to cobj::serializeInit
RESULT description
0 import failed
1 import successful finished
Note
  • If the function returns 1 (success) the path of the xml-file is stored in the variable &serializeFilePath, otherwise this variable is empty.
  • Progress and error messages are displayed in the log-window.
See also
Serialization

SerializeExport

instname SERIALIZEEXPORT file=* ; level=current [; params ]
This function performs all necessary operations to export/save the object data. After initializing the xml fileitem, creating the export element and preparing the member varaibles, the onSerializeExport member is called to perform the element/data export.
argument description default
instname Instance of a class derived from CObj.
file the export file: a xml fileitem, a xml filepath or * to use a dialog to create the export file *
level selects the level of the export element (only if file is a xml fileitem); use the keywords current (create export element on the current level), child (create export element as child of the current element) or select the level by an iref (internal reference) current
params a list of serialization parameters which are passed to cobj::serializeInit
RESULT description
0 export failed
1 export successful finished
Note
  • If the function returns 1 (success) the path of the xml-file is stored in the variable &serializeFilePath, otherwise this variable is empty.
  • Progress and error messages are displayed in the log-window.
See also
Serialization

SerializeInit (protected)

instname SERIALIZEINIT parname=parvalue ; ...
This function configures the serialization member variables and is normally called by the constructor of classes using serialization. It must be called before the member functions SerializeImport and SerializeExport can be used. The following table shows a list of the supported (and required) serialization parameters.
parname description of parvalue member variable default value
Id the XML element id, e.g. the name of the settings profile &serializeId
Tag the XML element tag &serializeTag
IdAttr the XML element attribute used for the id &serializeIdAttr ID
Version the settings version &serializeVersion 1.0
SupportedVersions a blank serarated list of supported versions &serializeSupportedVersions 1.0
VersionAttr the XML element attribute used for the version &serializeVersionAttr version
FileType the type of the export/import files &serializeFileType xml
FileText description text for import/export files &serializeFileText XML File
RESULT description
1 initialization finished, no error
0 initialization failed
See also
Serialization

Protected Functions

SerializeCheckVersion

instname SERIALIZECHECKVERSION ...
if called by SerializeExport → Returns 1 if the version assigned to &serializeVersion is valid and supported, otherwise 0.
if called by SerializeImport → Returns 1 if the version of the element to be imported is valid and supported, otherwise 0
RESULT description
1 version is valid and supported
0 invalid or not supported version
See also
Serialization

Serialization

Member variables which must be initialized by child classes

&serializeTag
The tag to be used to store/retrief data in/from. This variable must be set by the child class.
&serializeId
The ID of this serialization object.
&serializeFileText
The text to display next to the extension.

Member variables which may be modified by child classes

&serializeIdAttr=ID
The attribute name to store the ID in.
&serializeVersion=1.0
The version number/text to be used when exporting data. This version number can later be used to determine which import function to use when retrieving settings.
&serializeVersionAttr=version
The attribute name to use for the version number.
&serializeSupportedVersions=1.0
A blank separated list of supported version.
&serializeFileType=xml
The file extension to use for saving/opening files.

Member variables which must not be modifed by child classes

&serializeFile
The fileitem used for import/export.
&serializeFilePath
The path of the import/export file.
&serializeState
Either import or export. This is initialized by CObj if the import/export function is called.
&serializeImportVersion
The version of the element being imported. This is initialized by CObj before the import function is called.

Implementing Serialization for Classes To enable the serialization environment, the class must call the initialization function before an import/export function call can be issued. The initialization function should be called in the constructor.


Example:

cobj::serializeInit tag=elemTag; version=1.2; supportedVersions=1.0 1.1 1.2;

The class must also implemented two protected member functions which are called by the serialization members of CObj to perform the import/export operation:


Import function
protected_onSerializeImport:
  • called by cobj::serializeImport
  • initialized member vars: &serializeFile (xml fileitem containing the element to be imported), &serializePos (the position of the element to be imported), &serializeState (is set to import) and &serializeImportVersion (to version of the element to be imported).
  • function: import from element; load the data from the element and process loaded data according to the value of &serializeImportVersion
  • result: 0 for error and 1 for success


Export function
protected_onSerializeExport:
  • called by cobj::serializeExport:
  • initialized member vars: &serializeFile (xml fileitem containing the element for export), &serializePos (the position of the export element) and &serializeState (is set to export)
  • function: export to element; save the object members into the export element
  • result: 0 for error and 1 for success

Both functions of the derived class must only load/save the element data. All other functions are performed by the member functions of the base class.

See Also

Definition of Classes