Programmer Guide/Macro Library/COBJ

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

---

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

New (static)

static

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 (static)

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.

argument	description	default
instname	the instance item to be deleted.
RESULT	description
undefined	The function has no return value

See also

New, Destroy

Import (static)

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 (static)

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

Construct (public)

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 (public)

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 (public)

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 (public)

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 (public)

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 (public)

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 (public)

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 (public)

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

SerializeCheckVersion (protected)

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.