Programmer Guide/Macro Library/CObjEx: Difference between revisions

Latest revision as of 14:05, 7 March 2018

File: CLASSES.STX, linked to library STX.LIB
Parent: CObj, Derived classes: XPlot, XGraph, XWave

The class CObjEx is an enhanced base class designed for objects which are used in STx scripts. Objects based on this class are deleted automatically before the script application is finished. By convention a class based on CObjEx implements the following simple instantiation method:

cobjexinst := cobjExClassName constructionArguments

This instantation method can simply be implemented:

[class myclassex cobjex]
exit 1 set '$(cobj 'new $#mac $#argv')'

// start with member functions here
...

Rules for derived classes

If a derived class implementa a construct or destruct member, the base class member must be called.

public_construct:

The default constructor calls the CObj constructor and writes a construct-message to the console window. The base class member takes no arguments and returns always 0 (success). It must be called by derived classes.

public_destruct:

The default constructor stops and deletes the internal timer (&logTimerItem), calls the CObj destructor and writes a destruct-message to the console window. It must be called by derived classes.

Member Functions

Cleanup (static)

cobjex cleanup
Result: none:
Description: Delete all instances of classes derived from CObjEx. This function is called automatically by the script controller (BScript) before the script application exits.

Log

Usage

cobjex_inst log text:

text: the text to write to the script console

Result: none
Description: Write the message cobjex_inst: text to the script console.

ELog

Usage

cobjex_inst elog lev ; res ; text

lev: the number of macro levels to close (1 = return to caller, 2 = exit caller, ...; default=2)
res: the result value to be returned; no default (empty)
text: the text to write to the script console.

Result: none
Description: Write the message cobjex_inst: Error! - text to the script console and exits the specified number of macro levels (exit lev set 'res').

LogExit

Usage

cobjex_inst logexit res ; text:

res: the result to assign after returning.
text: the text to write to the console window

Result: The value of argument res
Description: Writes the message class-instance: text to the script console and exits from 2 macros (= return from caller) with the return value res.

LogTimer

cobjex_inst logtimer cmd ; text

cmd

one of the following:

ON or BEGIN: start the timer and/or display the elapsed time the console window.
OFF or END: stop the timer and display the elapsed time in the console window.

text: the text to write to the console window

Return: The elapsed time in seconds.
Description: Start (continue) or stop the internal timer of the object and write the elapsed time and text to the console window.

@@ Line 1: / Line 1: @@
-{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
+{{DISPLAYTITLE:{{SUBPAGENAME}} - Base class for objects used in script applications}}
 *'''File''': CLASSES.STX, linked to library STX.LIB
-*'''Title''': Base class for objects used in script applications
+*'''Parent''': [[Programmer_Guide/Macro_Library/COBJ|CObj]], '''Derived classes''': [[Programmer_Guide/Macro_Library/XPlot|XPlot]], [[Programmer_Guide/Macro_Library/XGraph|XGraph]], [[Programmer_Guide/Macro_Library/XWave|XWave]]
-*'''Parent''': [[Programmer_Guide/Macro_Library/CObj|CObj]], '''Derived classes''': [[Programmer_Guide/Macro_Library/XPlot|XPlot]], [[Programmer_Guide/Macro_Library/XGraph|XGraph]], [[Programmer_Guide/Macro_Library/XWave|XWave]]
-The class <code>CObjEx</code> is an enhanced base class designed for objects which are used in {{STX}} scripts. Objects based on this class are deleted automatically before the script application is finished. By convention a class based on CObjEx implements the following simple instantiation method:
+The class <code>CObjEx</code> is an enhanced base class designed for objects which are used in {{STX}} scripts. Objects based on this class are deleted automatically before the script application is finished. By convention a class based on <code>CObjEx</code> implements the following simple instantiation method:
-::<code> cobjExInstance := cobjExClassName <var>constructionArguments</var> </code>
+::<code> <var>cobjexinst</var> := <var>cobjExClassName</var> <var>constructionArguments</var> </code>
+This instantation method can simply be implemented:
-====CObjEx Member Functions====
+<pre>
+[class myclassex cobjex]
+exit 1 set '$(cobj 'new $#mac $#argv')'
-The <code>CObjEx</code> class has the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.
+// start with member functions here
+...
+</pre>
-===cleanup===
+==Rules for derived classes==
+If a derived class implementa a '''construct''' or '''destruct''' member, the base class member must be called.
-Delete all instances of classes based on <code>COBJEX</code>. This function is called automatically by <code>BScript</code> before the application exits.
+'''public_construct:'''
+:The default constructor calls the CObj constructor and writes a construct-message to the console window. The base class member takes no arguments and returns always 0 (success). It must be called by derived classes.
-=====Usage:=====
+'''public_destruct:'''
+:The default constructor stops and deletes the internal timer (&logTimerItem), calls the CObj destructor and writes a destruct-message to the console window. It must be called by derived classes.
-<code><var>cobjex</var> cleanup</code>
+==Member Functions==
-===construct===
+===Cleanup (static)===
-Calls the <code>COBJ</code> constructor and writes a construct message to the script console.
+;<code>cobjex cleanup</code>
+;Result: none:
+;Description:Delete all instances of classes derived from <code>CObjEx</code>. This function is called automatically by the script controller (<code>BScript</code>) before the script application exits.
-=====Usage:=====
+===Log===
+;Usage:<code><var>cobjex_inst</var> log <var>text</var></code>:
+:;<var>text</var>: the text to write to the script console
+;Result: none
+;Description: Write the message <code><var>cobjex_inst</var>: <var>text</var></code> to the script console.
-<code><var>cobjex</var> construct</code>
+===ELog===
+;Usage:<code><var>cobjex_inst</var> elog <var>lev ; res ; text</var></code>
+:;<var>lev</var>: the number of macro levels to close ('''1''' = return to caller, '''2''' = exit caller, ...; default=2)
+:;<var>res</var>: the result value to be returned; no default (empty)
+:;<var>text</var>: the text to write to the script console.
+;Result: none
+;Description: Write the message <code><var>cobjex_inst</var>: Error! - <var>text</var></code> to the script console and exits the specified number of macro levels (<code>exit <var>lev</var> set '<var>res</var>'</code>).
-===destruct===
+===LogExit===
+;Usage: <code><var>cobjex_inst</var> logexit <var>res ; text</var></code>:
-Calls the <code>COBJ</code> destructor and writes a destruct message to the script console.
+:;<var>res</var>: the result to assign after returning.
+:;<var>text</var>: the text to write to the console window
-=====Usage:=====
+;Result: The value of argument <var>res</var>
+;Description: Writes the message <code>class-instance: <var>text</var></code> to the script console and exits from 2 macros (= return from caller) with the return value <var>res</var>.
-<code><var>cobjex</var> destruct</code>
-===elog===
-Writes the message "<code>class-instance: ERROR -</code> <var>text</var>" to the script console and exits from '<var>level</var>' macros with the return value '<var>result</var>'.
-=====Usage:=====
-<code><var>cobjex</var> elog <var>level</var>; <var>result</var>; <var>text</var></code>
-=====Parameters:=====
-;<var>level</var>
-:The number of macro levels to return.
-;<var>result</var>
-:The result to set on returning.
-;<var>text</var>
-:The text to use write to the console window.
-===log===
-Write the message "<code>class-instance:</code> <var>text</var>" to the script console.
-=====Usage:=====
-<code><var>cobjex</var> log <var>text</var></code>
-=====Parameters:=====
-;<var>text</var>
-:The text to write to the log window.
-===logError===
-Writes the message "class-instance: ERROR - <var>text</var>" to the script console and exits from 2 macros with the return value 'result'.
-=====Usage:=====
-<code><var>cobjex</var> logError <var>result</var>; <var>text</var></code>
-=====Parameters:=====
-;<var>result</var>
-:The result to assign after returning.
-;<var>text</var>
-:The text to write to the console window.
-===LogExt===
-Write text to the <code>CON</code> log window with the option of overwriting the last line. This is useful for progress reports.
-Usage:
-<code><var>inst</var> LogExt <var>mode</var> ; <var>text</var></code>
-=====Parameters:=====
-;<var>mode</var>
-:If <code>0</code>, the text overwrites the last log window line. If <code>1</code>, the text is appended to the last log window line.
-;<var>text</var>
-:The text to write to the log window.
 ===LogTimer===
+;<code><var>cobjex_inst</var> logtimer <var>cmd ; text</var></code>:
-Start or stop the internal <code>BScript</code> timer. The elapsed time is written to the CON log window.
+:;<var>cmd</var>: one of the following:
+::*<code>ON</code> or <code>BEGIN</code>: start the timer and/or display the elapsed time the console window.
-Usage:
+::*<code>OFF</code> or <code>END</code>: stop the timer and display the elapsed time in the console window.
+:;<var>text</var>: the text to write to the console window
-<code><var>inst</var> LogTimer <var>cmd</var></code>
+;Return: The elapsed time in seconds.
+;Description: Start (continue) or stop the internal timer of the object and write the elapsed time and <var>text</var> to the console window.
-=====Parameters:=====
-;<var>cmd</var>
-:One of the following:
-:<code>ON</code>|<code>BEGIN</code> - Start the timer. If the timer has already been started, then the elapsed time in seconds is returned. The elapsed time is also displayed in the CON window.
-:<code>OFF</code>|<code>END</code> - Stop the timer. The elapsed time is also displayed in the CON window.

Programmer Guide/Macro Library/CObjEx: Difference between revisions

Latest revision as of 14:05, 7 March 2018

Contents

Rules for derived classes

Member Functions

Cleanup (static)

Log

ELog

LogExit

LogTimer

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools