Programmer Guide/Macro Library/COBJ: Difference between revisions
No edit summary |
|||
(14 intermediate revisions by 2 users not shown) | |||
Line 2: | Line 2: | ||
'''File''': CLASSES.STX, linked to library STX.LIB | '''File''': CLASSES.STX, linked to library STX.LIB | ||
---- | ---- | ||
The class CObj implements some basic functions of the {{STX}} class library. | 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. | ||
==New | |||
=Static Functions= | |||
==New== | |||
COBJ NEW <var>classname</var> [ <var>initargs</var> ] | COBJ NEW <var>classname</var> [ <var>initargs</var> ] | ||
COBJ NEW <var>classname</var>::<var>instname</var> [ <var>initargs</var> ] | COBJ NEW <var>classname</var>::<var>instname</var> [ <var>initargs</var> ] | ||
:Create a new instance of class <var>classname</var> and initialize it. To initialize the instance the public member function [[#Construct|Construct]] is called (<code><var>newinst</var> Construct [ <var>initargs</var> ]</code>). 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 <var>newinst</var> is deleted (without calling the [[#Destruct|destructor]]) and an empty string is returned. | :Create a new instance of class <var>classname</var> and initialize it. To initialize the instance the public member function [[#Construct|Construct]] is called (<code><var>newinst</var> Construct [ <var>initargs</var> ]</code>). 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 <var>newinst</var> is deleted (without calling the [[#Destruct|destructor]]) and an empty string is returned. | ||
:If | :If <var>instname</var> is specified, it is used as the name for the new instance. If an instance with name <var>instname</var> and class <var>classname</var> exists already, the function returns immediatly with result <var>instname</var>, without calling the <Code>Construct</code> member function. | ||
:This function should be used rather than the command [[Programmer_Guide/Command_Reference/NEW|NEW INSTANCE]], to create new [[Programmer_Guide/Shell_Items/Instance|instance items]]. | :This function should be used rather than the command [[Programmer_Guide/Command_Reference/NEW|NEW INSTANCE]], to create new [[Programmer_Guide/Shell_Items/Instance|instance items]]. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
Line 35: | Line 37: | ||
;See also: [[#Delete|Delete]], [[#Construct|Construct]] | ;See also: [[#Delete|Delete]], [[#Construct|Construct]] | ||
==Delete | ==Delete== | ||
COBJ DELETE <var>instname</var> | COBJ DELETE <var>instname</var> | ||
:Calls the [[#Destruct|Destruct]] member function (<code><var>instname</var> Destruct</code>), to reset the instance, and than deletes the instance item. The return value of [[#Destruct|Destruct]] is ignored. | :Calls the [[#Destruct|Destruct]] member function (<code><var>instname</var> Destruct</code>), to reset the instance, and than deletes the instance item. The return value of [[#Destruct|Destruct]] is ignored. | ||
:This function should be used rather than the command [[Programmer_Guide/Command_Reference/NEW|DELETE <var>instname</var>]], to delete [[Programmer_Guide/Shell_Items/Instance|instance items]]. | :This function should be used rather than the command [[Programmer_Guide/Command_Reference/NEW|DELETE <var>instname</var>]], to delete [[Programmer_Guide/Shell_Items/Instance|instance items]]. If you just delete the instance using the [[Programmer_Guide/Command_Reference/NEW|DELETE <var>instname</var>]] command, then the destructor is not called! | ||
{|class="einrahmen" | {|class="einrahmen" | ||
!argument !!description !!default | !argument !!description !!default | ||
Line 52: | Line 54: | ||
;See also: [[#New|New]], [[#Destroy|Destroy]] | ;See also: [[#New|New]], [[#Destroy|Destroy]] | ||
==Import | ==Import== | ||
COBJ IMPORT <var>classname</var> ; <var>filename</var> ; <var>silent</var> | COBJ IMPORT <var>classname</var> ; <var>filename</var> ; <var>silent</var> | ||
:Import a settings profile of class <var>classname</var> from the file <var>filename</var> into the workspace. This function creates an instance of <var>classname</var> and calls the member function [[#SerializeImport|SerializeImport]] to import the file. The class <var>classname</var> must be derived from <code>CObj</code> and must implement the serialization interface members and a member function named <code>Save</code>, which saves a profile in the workspace. E.g. this function is used for the import of Viewer- and Color-profiles. | :Import a settings profile of class <var>classname</var> from the file <var>filename</var> into the workspace. This function creates an instance of <var>classname</var> and calls the member function [[#SerializeImport|SerializeImport]] to import the file. The class <var>classname</var> must be derived from <code>CObj</code> and must implement the serialization interface members and a member function named <code>Save</code>, which saves a profile in the workspace. E.g. this function is used for the import of Viewer- and Color-profiles. | ||
Line 78: | Line 80: | ||
;See also: [[#SerializeImport|SerializeImport]], [[#Export|Export]] | ;See also: [[#SerializeImport|SerializeImport]], [[#Export|Export]] | ||
==Export | ==Export== | ||
COBJ EXPORT <var>classname</var> ; <var>setupname</var> ; <var>filename</var> ; <var>silent</var> | COBJ EXPORT <var>classname</var> ; <var>setupname</var> ; <var>filename</var> ; <var>silent</var> | ||
:Export the settings profile <var>setupname</var> of class <var>classname</var> from the workspace to the file <var>filename</var>. This function creates an instance of <var>classname</var> and calls the member function [[#SerializeExport|SerializeExport]] to export the file. The class <var>classname</var> must be derived from <code>CObj</code> and must implement the serialization interface members and a member function named <code>Load</code>, which loads a profile from the workspace. E.g. this function is used for the export of Viewer- and Color-profiles. | :Export the settings profile <var>setupname</var> of class <var>classname</var> from the workspace to the file <var>filename</var>. This function creates an instance of <var>classname</var> and calls the member function [[#SerializeExport|SerializeExport]] to export the file. The class <var>classname</var> must be derived from <code>CObj</code> and must implement the serialization interface members and a member function named <code>Load</code>, which loads a profile from the workspace. E.g. this function is used for the export of Viewer- and Color-profiles. | ||
Line 108: | Line 110: | ||
;See also: [[#SerializeExport|SerializeExport]], [[#Import|Import]] | ;See also: [[#SerializeExport|SerializeExport]], [[#Import|Import]] | ||
==Construct | =Public Functions= | ||
==Construct== | |||
<var>instname</var> CONSTRUCT [ <var>initargs</var> ] | <var>instname</var> CONSTRUCT [ <var>initargs</var> ] | ||
:Default constructor. Currently this function do nothing and returns the result <code>0</code>. For compatibility reasons it should be invoked by the constructors of derived classes. | :Default constructor. Currently this function do nothing and returns the result <code>0</code>. For compatibility reasons it should be invoked by the constructors of derived classes. | ||
Line 128: | Line 132: | ||
;See also: [[#New|New]], [[#Destruct|Destruct]] | ;See also: [[#New|New]], [[#Destruct|Destruct]] | ||
==Destruct | ==Destruct== | ||
<var>instname</var> DESTRUCT | <var>instname</var> 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. | :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. | ||
Line 144: | Line 148: | ||
;See also: [[#Delete|Delete]], [[#Destroy|Destroy]], [[#Construct|Construct]] | ;See also: [[#Delete|Delete]], [[#Destroy|Destroy]], [[#Construct|Construct]] | ||
==Destroy | ==Destroy== | ||
<var>instname</var> DESTROY | <var>instname</var> DESTROY | ||
:Calls the destructor to de-initialize the instance and than deletes the instance item <var>instname</var>. | :Calls the destructor to de-initialize the instance and than deletes the instance item <var>instname</var>. | ||
Line 160: | Line 164: | ||
;See also: [[#Delete|Delete]], [[#Destruct|Destruct]] | ;See also: [[#Delete|Delete]], [[#Destruct|Destruct]] | ||
==AttachItem / AttachShell | ==AttachItem / AttachShell== | ||
<var>instname</var> ATTACHITEM <var>itemname</var> [ <var>mhfun</var> ] | <var>instname</var> ATTACHITEM <var>itemname</var> [ <var>mhfun</var> ] | ||
<var>instname</var> ATTACHSHELL <var>shellid</var> [ <var>mhfun</var> ] | <var>instname</var> ATTACHSHELL <var>shellid</var> [ <var>mhfun</var> ] | ||
Line 174: | Line 178: | ||
|- | |- | ||
|<var>mhfun</var> ||The name of a public member function of <var>instname</var> which should process the messages. | |<var>mhfun</var> ||The name of a public member function of <var>instname</var> which should process the messages. | ||
||[[#MsgHandler | ||[[#MsgHandler)|MsgHandler]] | ||
|- | |- | ||
!RESULT !!description | !RESULT !!description | ||
Line 180: | Line 184: | ||
|''undefined''||The function has no return value. | |''undefined''||The function has no return value. | ||
|} | |} | ||
;See also: [[#DetachItem / DetachShell | ;See also: [[#DetachItem / DetachShell|DetachItem]], [[#MsgHandler|MsgHandler]], [[../SETMSGHANDLER|macro SetMsgHandler]] | ||
==DetachItem / DetachShell | ==DetachItem / DetachShell== | ||
<var>instname</var> DETACHITEM <var>itemname</var> [ <var>delitem</var> ] | <var>instname</var> DETACHITEM <var>itemname</var> [ <var>delitem</var> ] | ||
<var>instname</var> DETACHSHELL <var>shellid</var> | <var>instname</var> DETACHSHELL <var>shellid</var> | ||
Line 201: | Line 205: | ||
|''undefined'' ||The function has no return value | |''undefined'' ||The function has no return value | ||
|} | |} | ||
;See also: [[#AttachItem / AttachShell | ;See also: [[#AttachItem / AttachShell|AttachItem]], [[../SETMSGHANDLER|macro SetMsgHandler]] | ||
==MsgHandler | ==MsgHandler== | ||
<var>instname</var> MSGHANDLER <var>msgtype</var> <var>msgname</var> <var>msgid</var> <var>msgpar</var> | <var>instname</var> MSGHANDLER <var>msgtype</var> <var>msgname</var> <var>msgid</var> <var>msgpar</var> | ||
:This is the member function | :This is the member function which processes the messages of shell items and/or shells attached to the instance <var>instname</var> using the function [[#AttachItem|AttachItem or AttachShell]]. The function is called by the message handling system (see [[../GETMESSAGE|GETMESSAGE]] and [[../DISPATCHMSG|DISPATCHMSG]]) when a message from an attached item/shell is received and dispatched. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
!argument !!description !!default | !argument !!description !!default | ||
Line 224: | Line 228: | ||
|} | |} | ||
;Note: The default function performs no message processing and returns 1! | ;Note: The default function performs no message processing and returns 1! | ||
;See also: [[#AttachItem / AttachShell | ;See also: [[#AttachItem / AttachShell|AttachItem]], [[../SETMSGHANDLER|macro SetMsgHandler]], [[../GETMESSAGE|GetMessage]], [[../StdLib#DispatchMsg|DispatchMsg]] | ||
==SerializeImport | ==SerializeImport== | ||
<var>instname</var> SERIALIZEIMPORT <var>file</var>=* ; <var>level</var>=current [; <var>params</var> ] | <var>instname</var> SERIALIZEIMPORT <var>file</var>=* ; <var>level</var>=current [; <var>params</var> ] | ||
: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 <code>onSerializeImport</code> member is called to perform the element/data import. | :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 <code>onSerializeImport</code> member is called to perform the element/data import. | ||
Line 258: | Line 262: | ||
;See also: [[#Serialization|Serialization]] | ;See also: [[#Serialization|Serialization]] | ||
==SerializeExport | ==SerializeExport== | ||
<var>instname</var> SERIALIZEEXPORT <var>file</var>=* ; <var>level</var>=current [; <var>params</var> ] | <var>instname</var> SERIALIZEEXPORT <var>file</var>=* ; <var>level</var>=current [; <var>params</var> ] | ||
: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 <code>onSerializeExport</code> member is called to perform the element/data export. | :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 <code>onSerializeExport</code> member is called to perform the element/data export. | ||
Line 291: | Line 295: | ||
==SerializeInit (protected)== | ==SerializeInit (protected)== | ||
<var>instname</var> SERIALIZEINIT <var>parname</var>=<var>parvalue</var> ; ... | <var>instname</var> SERIALIZEINIT <var>parname</var>=<var>parvalue</var> ; ... | ||
: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 | :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|SerializeImport]] and [[#SerializeExport|SerializeExport]] can be used. The following table shows a list of the supported (and required) serialization parameters. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
!<var>parname</var> !!description of <var>parvalue</var> !! member variable !! default value | !<var>parname</var> !!description of <var>parvalue</var> !! member variable !! default value | ||
Line 319: | Line 323: | ||
;See also: [[#Serialization|Serialization]] | ;See also: [[#Serialization|Serialization]] | ||
==SerializeCheckVersion | =Protected Functions= | ||
==SerializeCheckVersion== | |||
<var>instname</var> SERIALIZECHECKVERSION <var>...</var> | <var>instname</var> SERIALIZECHECKVERSION <var>...</var> | ||
:if called by [[#SerializeExport | :if called by [[#SerializeExport|SerializeExport]] → Returns <code>1</code> if the version assigned to <code>&serializeVersion</code> is valid and supported, otherwise <code>0</code>. | ||
:if called by [[#SerializeImport | :if called by [[#SerializeImport|SerializeImport]] → Returns <code>1</code> if the version of the element to be imported is valid and supported, otherwise <code>0</code> | ||
{|class="einrahmen" | {|class="einrahmen" | ||
!RESULT !!description | !RESULT !!description | ||
Line 332: | Line 338: | ||
;See also: [[#Serialization|Serialization]] | ;See also: [[#Serialization|Serialization]] | ||
=Serialization= | |||
<u>Member variables which '''must be''' initialized by child classes</u> | |||
:;<code>&serializeTag</code>: The tag to be used to store/retrief data in/from. This variable must be set by the child class. | :;<code>&serializeTag</code>: The tag to be used to store/retrief data in/from. This variable must be set by the child class. | ||
:;<code>&serializeId</code>: The ID of this serialization object. | :;<code>&serializeId</code>: The ID of this serialization object. | ||
:;<code>&serializeFileText</code>: The text to display next to the extension. | :;<code>&serializeFileText</code>: The text to display next to the extension. | ||
<u>Member variables which may be modified by child classes</u> | |||
:;<code>&serializeIdAttr</code>=<code>ID</code>: The attribute name to store the ID in. | :;<code>&serializeIdAttr</code>=<code>ID</code>: The attribute name to store the ID in. | ||
:;<code>&serializeVersion</code>=<code>1.0</code>: 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. | :;<code>&serializeVersion</code>=<code>1.0</code>: 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. | ||
Line 346: | Line 351: | ||
:;<code>&serializeSupportedVersions</code>=<code>1.0</code>: A blank separated list of supported version. | :;<code>&serializeSupportedVersions</code>=<code>1.0</code>: A blank separated list of supported version. | ||
:;<code>&serializeFileType</code>=<code>xml</code>: The file extension to use for saving/opening files. | :;<code>&serializeFileType</code>=<code>xml</code>: The file extension to use for saving/opening files. | ||
<u>Member variables which '''must not''' be modifed by child classes</u> | |||
:;<code>&serializeFile</code>: The fileitem used for import/export. | :;<code>&serializeFile</code>: The fileitem used for import/export. | ||
:;<code>&serializeFilePath</code>: The path of the import/export file. | :;<code>&serializeFilePath</code>: The path of the import/export file. | ||
:;<code>&serializeState</code>: Either <code>import</code> or <code>export</code>. This is initialized by CObj if the import/export function is called. | :;<code>&serializeState</code>: Either <code>import</code> or <code>export</code>. This is initialized by CObj if the import/export function is called. | ||
:;<code>&serializeImportVersion</code>: The version of the element being imported. This is initialized by CObj before | :;<code>&serializeImportVersion</code>: The version of the element being imported. This is initialized by CObj before the import function is called. | ||
the import function is called. | |||
<u>Implementing Serialization for Classes</u> | |||
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: | Example: | ||
Line 379: | Line 384: | ||
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. | 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= | |||
[[Programmer_Guide/Source_code#Definition_of_Classes|Definition of Classes]] |
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). |
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 |
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 namedSave
, 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 namedLoad
, 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.
|
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 |
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 |
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.
- If the function returns 1 (success) the path of the xml-file is stored in the variable
- 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.
- If the function returns 1 (success) the path of the xml-file is stored in the variable
- 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, otherwise0
. - if called by SerializeImport → Returns
1
if the version of the element to be imported is valid and supported, otherwise0
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
orexport
. 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
- called by
- 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
- called by
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.