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)

Create and delete items, Execute item functions

The commands NEW, SET and DELETE can be used to deal with shell items in scripts.

NEW itemtype itemname ...

Create and initialize a shell item. The command returns the name of the created item and the string * if an error occurs. If the argument itemname is set to *, a unique name will be selected automatically.

SET itemname function ...

Perfrom an action with a shell item. In most cases it is not necessary to specify the SET command explicit, because it is used implizit if a command line begins with the name of an item. This means the command SET itemname function ... is equivalent to itemname function ....

DELETE itemname ...

Delete shell item(s).

• some items can not be deleted every time (e.g. a SPU must be in the EXIT-state before it can be deleted).
• items owned by an other item, are deleted when the owner is 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 * origName [ origShell ]

This command creates the reference rafName, 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.

Notes:

• A reference has the same type, attributes and data content as the original item. The reference 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 the functions to LOCK and UNLOCK an item are implemented.
• The workspace object BSTXIni and the project object BDataSet are using references, to share the content of the xml-file items containing the workspace and project data.

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