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 an instname is specified it is used as 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, processing 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.
