Latest revision as of 08:49, 7 August 2019

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.

Programmer Guide/Macro Library/COBJ: Difference between revisions