Programmer Guide/Shell Items

STx implements a number of different objects which can be used to manipulate files, graphics, dialogs, etc. These objects are called shell items.

A shell item is an object designed to be good at a specific range of tasks. E.g. there is a file item which allows you to read, write, copy, rename and list files and there is a dialog item, which allows you to design and display dialog boxes, and react to user input.

Shell items are implemented in C++ and made accessible to the STx programmer via commands, attributes and messages; these are documented in the Shell Items help chapter. The name of an item is used as a reference (pointer) to the item.

Currently STx implements the following shell items

DCOM	A shell item for working with Distributed Component Object Model (DCOM) interfaces (e.g. with the DCOM interface for the statistics package R).
DDECONV	A shell item for initiating a Dynamic Data Exchange (DDE) conversation with a DDE server and exchanging data between the server and the item (e.g. to exchange data with microsoft EXCEL or WORD).
MENU (dialog)	A shell item for designing and displaying dialog boxes and processing user input. A dialog is always a part of a display item. Note:For historical reasons the type id used for dialog items is MENU.
DISPLAY	A shell item for displaying one or more graph items and optionally a dialog. Each window displayed by STx is a display item.
FILE	A shell item for accessing files on disk and manipulating files in memory. It can be used to list files, to apply system commands (like copy, rename, move, ...) to files or to access data of different file formats (plane text, section files, xml, binary).
GRAPH	A shell item for displaying graphical representations of data, e.g. spectrograms. A graph is always a part of a display item.
INSTANCE	A shell item instance of an STx class. The instance items are used to implemented object oriented script programming.
IP	A shell item for sending and receiving data via the TCP/IP protocol. The ip item supports both the TCP and the UDP protocols and can act as server or client. The ip item can transfer data using the Open Sound Control protocol (OSC), an STx protocol, or as ASCII or UNICODE strings.
SPU	A shell item for controlling Signal Processing Units (SPUs). An SPU is a circuit connecting one or more Signal Processing Atom (see the SPU Reference for details) together.
TABLE	A shell item for storing data in columns and rows with sorting and find functions. The table items can be used to implement simple database functions and for numerical operations.
VALUE	A shell item for exchanging data between SPU and graph items and macros. They can also be used as timers and for numerical operations.
WAVE	A shell item to access stored signal, playback and record wave soundfiles as well as create and manipulate sound sequences. It is also possible to use wave items in numerical operations (e.g. to read source signals are write output signals of a dsp algorithm).
Reference	A shell item reference is not an item in itself, but rather a reference to an existing shell item. It is mainly used to share shell items between shells (for data exchange reasons). E.g. the dataset file item and the config file item are file items which are created by the master-shell of STx but shared between all application shells.

Note: Shell items of type TABLE, VALUE, FILE and WAVE can also be used directly in numerical expressions (EVAL)

Creating and deleting items, executing item functions

The commands NEW, SET and DELETE are used for dealing with shell items.

NEW itemtype itemname …

create and initialize a shell item. On success, the command returns the name of the created shell item (identical to the itemname argument, if other than *). If there is an error, the command returns the string *. If the argument itemname is set to *, the item will be assigned a unique name (e.g. T#1, T#2, … for tables).

SET itemname function ...

perform an action on a shell item. In most cases you may omit the string SET altogether, meaning that the command SET itemname function ... is equivalent to itemname function ....

DELETE itemname ...

delete shell item(s).

Note that:

• some items may not be deleted at will (e.g. a SPU may be deleted only if it has reached the EXIT state).
• the deletion of an item owned by another item is deferred until the owner has been deleted (e.g. graphs are deleted when the owning display is deleted).

NEW

// create a simple table item
// simple tables can be used to store strings (e.g. filenames)
#table := new table *
// create a parameter table item with 20 numerical fields
#data := new table * * num:x:20
// open a textfile for reading; the variable #path contains the path of the file
#textfile := new file * '$#path' /read /text

• SET:

// append 2 lines to a simple table
set $#table * 'first entry'  // explizit SET command
$#table * 'second entry'     // implizite SET command
// copy the content of a table to the clipboard
$#table clipboard
// load the whole file into a table
$#textfile load $#table

DELETE

// delete an item
delete $#table
// delete items, the item names are stored in the specified variables;
// the variables are also deleted (set to empty)
delete #data #textfile /variable /?

Item Attributes

All shell items have attributes which can be accessed using the following syntax:

itemName[!attributeName]

$varname[!attributeName] if the item name is stored in a variable

For example, you can retrieve the sampling rate of a wave item as follows:

#srate := $#wave[!srate]

If the attribute being requested does not exist, then an empty string is returned. Please see the individual shell item documentation for a list of supported attributes.

Some items have attributes with more than one value. Such attribute values are addressed by comma seperated id's.

// get item name, row and column of all graphs of a display
for #i := 0 to $#i < $#display[!graphs] step #i := int $#i+1
    readstr '$#display[!graph,$#i]' #gname #grow #gcol
    conlog 'graph $#gname is displayed in column $#gcol of row $#grow'
end

In same cases it may be necessary to use an item attribute in a string. To make sure that the item name is correctly terminated, the character ~ (tilde).

#table := new table MyTable
MyTable * ' <das ist ein test> '
writelog 'textMyTable[0]'  // -> will not work
writelog 'text~MyTable[0]' // -> okay

Item Messages

Some items uses messages to send informations to the shell. The messages can be processed by the command MSG or by the message handling system implemented via the library macros SETMSGHANDLER (install/remove message handler for an item) and GETMESSAGE (message loop, get and process messages).

The message sent to the shell contains information about the sending item and the message data in the following format:

itemtype itemname msgid msgpar

itemtype, itemname

the type and the name of the sending item

msgid, msgpar

the message id and the optional message data

Please see the individual shell item documentation for a list of messages.

References to shell items

A shell item reference can be used to refer to to an already existing item, even if it is owned by another shell. This feature makes it possible to share shell items between shells. Creating references is only possible for table, file and instance items.

refName := NEW origType * /Z origName [ origShell ]

This command creates the reference refName, which refers to the original item with type origType and name origName. If the original item is owned by another shell, also the id origShell of this shell must be specified. The option /Z causes the NEW command to create a reference and not a new item.

• A reference has the same type, attributes and data content as the original item, this means, it can be used like the original.
• If the reference and the original item are owned by different shells, the access to the items must be synchronized. For this purpose functions to LOCK and UNLOCK an item are implemented.
• The workspace object BSTXIni and the project object BDataSet are using references, to make the content of the xml-file items containing the workspace and project data available to all running shells.
• The item itself (e.g. the table) is deleted, when all references (including the original item) are deleted.

Protected shell items

In some situations it may be useful to protect shell items from (accidental) deletion. E.g. the script console uses this feature to protect all required items. STx implements to item protection methods.

Single Item Protection

• protects only one item

protecedItem := NEW itemtype itemname ... /u

create a protected item

DELETE protectedItem /u

delete a protected item

Global Item Protection

• uses a master-item to enable / disable global protection
• protects all items created before the master-item
• items created after the master are not proteced
• only one master-item is possible
• the global protection is enabled when the master item is created, and disabled when it is deleted

masterItem := NEW itemtype itemname ... /U

create the master-item and enable global protection

DELETE masterItem /u

delete the master-item and disable global protection

The options used for item protection control (/U and /u) are case sensitive!

Temporary shell items

A temporary shell item (also called local shell item) is a shell item, which is automatically deleted, when the macro which creates the shell item is leaved.

A temporary shell item is created ...

• by the command NEW, if the option /Garbage is specified

#table := new table * /g

• by the EVAL command, if the return value is a vector or a matrix and the result is not assigned to an item. The returned data are stored in a automatically created temporary parameter table.

#matrix := eval init(100,100,0)

• if a row or column of a value item or table item is extracted and not assigned to an item. The extracted data are stored in a automatically created temporary parameter table.

#rowVector := $#table[10,*]

It is possible to return temporary shell items from a macro. In this case the name of the temporary shell item must be the only return value of the macro and the return value must be assigned directly to a variable of the caller.

[macro testTempItem]
// create vector #1; the temporary vector returned by makeZeroVector is 
// converted (during the assignment) to a temporary vector of testTempItem
#vector1 := makeZeroVector 20        
showitem $#vector1      // display the content of table $#vector1
// create vector #2; the temporary vector returned by makeZeroVector is not 
// assigned and therefore deleted; the name of the (now invalid) item is 
// stored in the variable RESULT 
makeZeroVector 10                    
readvar result #vector2 // copy the returned item name to a local variable
showitem $#vector2      // display content of table $#vector2 failes, 
                        // because the string stored in #vector2 is not the name of an item
// exit (and delete temporary #vector1)
exit                                 

[macro makeZeroVector #size=100]
// create a vector with #size zeros; the result of the eval command is a 
// temporary numerical table item with 1 column and $#size rows
#vector := eval fill($#size, 0, 0)   
// return the vector (temporary table item) to the caller
exit 1 set $#vector