SAT Display Language (SAT/DL) Commands

S^@

Home

SATGUI

SATSHELL

SATFORM

SATFILTER

SATREPORT

SATMYSQL

License

Download

Examples

Contact

NOTES:

For most commands, an additional page of examples with graphic illustrations is available by selecting the more link on the "Example" line.
All the example graphic illustrations were produced using SATDLTOOL running under Microsoft Windows. SATSHELL is only available for Unix/Linux, however the screens will have a similar look and feel.

action	Initiate an action from a SAT server-side action process.
addBorder	Create a Border item with groove/sunken/raised relief.
addButton	Create a Button item.
addButtons	Create a row of Button items.
addCheckButtons	Create a group of related Check Buttons.
addData	Create a Data item.
addEntries	Create a column -or- grid of Entry field items.
addEntry	Create an Entry field item.
addGrid	Create a Button/Label Grid.
addHotKey	Create a Hot Key action.
addLabel	Create a Label item.
addMenu	Create a Menubar with drop-down menus.
addMultiList	Create a Multi column Listbox item.
addPickList	Create a drop-down Pick List item.
addRadioButtons	Create a group of related Radio Buttons.
addText	Create Text item.
addToolbar	Create Toolbar item.
addTree	Create Tree item.
addValidation	Create a new Validation pattern.
clear	Delete all display and non-safe data items.
closeWindow	Close child window and delete associated items.
gotoLabel	Move display of text item to specified label.
hide	Hide specified item.
newScreen	Initialise application Screen (Set title/size).
newWindow	Create new (child) window and initialise Window screen (Set title/size).
placeItem	Redisplay a hidden item -or- move item to a new position.
placeWindow	Place window at specified position on the screen.
remove	Delete a display/data item -or- menu.
setAction	Set/change action for specified item.
setDateFormat	Set Date Format used by entry field validations.
setFocus	Set Focus to specified item.
setGroup	Set name of menu Group.
setItem	Set value of Item.
setItems	Set values for a list of Items.
setItemState	Set state of Item.
setMessage	Set Message line text.
setRelief	Set default Relief style.
setSize	Set Size of application screen.
setState	Set default item State (normal/disabled).
setTitle	Set application window Title text.
setWindow	Set default window name.
unlock	Unlock display.
updateItem	Update the value of MultiList/Text Item.

action

Syntax:	action {name ?parameters?}
Parameters:	name=item_name parameters=parameters
Options:	None.
Return:	None.
Example:	`action {addname "Adrian" "Davis"}`

The action command is used to initiate an action from a SAT server-side action process.

addBorder

Syntax:	addBorder {name position size ?options?} addBorder {name hide size ?options?}
Parameters:	name=item_name position=xpos,ypos hide=hide size=widthxheight options=black\|blue\|color\|darkgray\|flat\|gray\|green\|groove\|raised\|sunken\|text\|title\|yellow
Options:	black=Set border background colour to "black". blue=Set border background colour to "blue". color(color)=Set border background colour to color. darkgray=Set border background colour to "dark gray". flat=Set relief style to "flat". gray=Set border background colour to "gray". green=Set border background colour to "green". groove=Set relief style to "groove". raised=Set relief style to "raised". red=Set border background colour to "red". sunken=Set relief style to "sunken". text(text)=Set title text to text. title=Display title at top left of border. yellow=Set border background colour to "yellow".
Return:	None.
Example:	`addBorder {address 2,10 40x12}` more

The addBorder command is used to create a border item.

If an option is specified which is not matched to one of the literal options it is ignored.

Borders should be created before the items which are to be created within them. The border is not transparent, so creating it on top of existing items will obscure them. This effect could be used to temporarily "remove" items from the screen, as they can be made visible again by removing the border.

Borders can also be used as containers for display items.

If the border is created as using hide instead of a position, the border and any contianed items will not be displayed until the border is placed on the display using placeItem.

If the height is set to zero a horizontal line is displayed. A width of zero will display a vertical line.

The default relief style is "groove". The default can be set to another style using setRelief.

If the title option is specified a title derived from the name will be displayed at the top left of the border. This option is best used with the groove relief style.

Notes:

Display items may be contained in a border (See Using Borders as Contianers for Display Items).
To hide a border and its embedded contents use hide.
To display a hidden border use placeItem.

addButton

Syntax:	addButton {name position size ?options?}
Parameters:	name=item_name position=xpos,ypos size=width options=confirm\|color\|disabled\|exit\|filesave\|fileselect\|flat\|group\|icon\|noborder\|normal\|outline\|text\|validate\|action
Options:	confirm(message)=Enable action confirmation dialog with message. color(foreground/background)=Set button colours to foreground/background. disabled=Disable button. exit=Set action to cause application to exit. filesave(file)=Enable file "save as" dialog with file as default (SATSHELL Only). fileselect(file)=Enable file "file select" dialog with file as default (SATSHELL Only). flat=Set button relief style to "flat". group(groups)=Set list of groups which enable this button. icon(icon)=Create button with icon instead of name. noborder=Set border to 0 (default 2). normal=Enable button. outline=Display outline around button (Default Relief). text(text)=Set button text to text. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not known option then assume option is action.
Return:	None.
Example:	`addButton {Exit 2,10 6 exit}` more

The addButton command is used to create a button item.

If an option is specified which is not matched to one of the known options it is assumed to be an action.

Icons must be chosen from the Icon Selection.

Although buttons can be created without an action, this is not particularly useful.

The Button name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

Notes:

To change the state of buttons use setItemState.
To create a row of buttons use addButtons.
To add/amend an action use setAction.

addButtons

Syntax:	addButtons {position size buttondata}
Parameters:	position=xpos,ypos size=width buttondata=buttons
Options:	None.
Return:	None.
Example:	`addButtons {2,10 6 {Save save_customer} {Exit exit}}` more

The addButtons command is used to create a row of button items.

If buttondata is a number then this value is used as the number of characters padding between the buttons.

All button item options can be used for each item in buttondata.

Notes:

To create a single button item use addButton.

addCheckButtons

Syntax:	addCheckButtons {name position labels ?options?}
Parameters:	name=item_name position=xpos,ypos labels=labels options=disabled\|group\|horizontal\|normal\|outline\|text\|title
Options:	disabled=Disable check buttons. group(groups)=Set list of groups which enable this check button. horizontal=Arrange check buttons horizontal (default vertical). normal=Enable check buttons. outline=Display outline around check buttons (Default Relief). text(text)=Set title text to text. title=Display title at top left of check buttons.
Return:	name:label (For each button label. Set to "Y" if selected, otherwise "N").
Example:	`addCheckButtons {attributes 2,10 {+Bold Italic Underline}}` more

The addCheckButtons command is used to create a Check-Buttons Item.

Active check buttons can be set by prefixing the appropriate labels with "+".

If the title option is specified a title derived from the name will be displayed at the top left of the check buttons. This option is best used with the groove relief style outline.

The Check-Buttons name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

Notes:

To initialise/change the value of check buttons use setItem.
To change the state of check buttons use setItemState.

addData

Syntax:	addData {name value ?options?}
Parameters:	name=item_name value=value options=return\|safe
Options:	safe=Create "safe" data item.
Return:	None.
Example:	`addData {customer "VC001"}`

The addData command is used to create a data item.

Both clear and remove can be used to delete non-safe data items. Safe data items can only be deleted using remove.

Notes:

To initialise/change the value of data items use setItem.

addEntries

Syntax:	addEntries {position ?pad? columdata}
Parameters:	position=xpos,ypos pad=characters columndata=columns
Return:	None.
Example:	`addEntries {2,10 {10,25 {First_Name} {Last_Name} {Age 4}}}` more

The addEntries command is used to create a column/row (grid) pattern of Entry Items.

If the pad parameter is specified this value is used as the number of characters padding between columns, the default is 5.

All entry item options can be used for each item in columndata.

Notes:

To initialise/change the values of entry items use setItem.

addEntry

Syntax:	addEntry {name position size ?options?}
Parameters:	name=item_name position=xpos,ypos size=label,entry options=center\|color\|confirm\|disabled\|focus\|group\|normal\|outline\|right\|secret\|text\|validate\|action\|validation
Options:	center=Align label text in center of label area (default is left). color(foreground/background)=Set entry text colours to foreground/background. confirm(message)=Enable action confirmation dialog with message. disabled=Disallow entry update via keyboard. focus=Give this entry focus. group(groups)=Set list of groups which enable this entry. normal=Allow entry update via keyboard. outline=Display outline around entry (Default Relief). return(item)=Return value to saved screen item. right=Align label text to right of label area (default is left). secret=Display "" instead of actual character entered. text(?text?)=Set label text to text. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix* items when actioned. action=If not known option or validation then assume option is action. validation=If not a known option assume option is validation.
Return:	name (Value of entry text).
Example:	`addEntry {First_Name 2,10 8,20}` more

The addEntry command is used to create a labeled entry item.

If an option is specified which is not matched to one of the known options, it is first tested to see if there is a validation with that name. If there is a validation it is associated with the item such that the validation is invoked when the cursor moves away from the entry. If there is no matching validation the option is assumed to be an action. The action is activated by pressing the [enter] key when the cursor is in the entry.

The Entry name may have a prefix, "+" is equivalent to the normal option, "-" to disabled, and "!" will cause the label text to not be displayed. The label text will also not be displayed if the label width is set to zero, or the text() option is used.

Notes:

To initialise/change the value of entry items use setItem.
To change the state of entry items use setItemState.
To create a "grid" pattern of entry items use addEntries.
To save the contents of an entry between screens use setData.
To create a "special" validation use addValidation.
To add/amend an action use setAction.

addGrid

Syntax:	addGrid {name postion size griddata ?options?}
Parameters:	name=item_name position=xpos,ypos size=width griddata=rows options=color\|darkgray\|disabled\|flat\|gray\|groove\|group\|normal\|outline\|pad\|raised\|state\|sunken\|title\|'literal'\|action
Options:	color(foreground/background)=Set grid colours to foreground/background. darkgray=Set grid background colour to "dark gray". disabled=Disable grid buttons by default. flat=Set outline relief style to "flat". gray=Set grid background colour to "gray". groove=Set outline relief style to "groove". group(groups)=Set list of groups which enable the checkbuttons/buttons/radiobuttons in this grid. normal=Enable grid buttons by default. outline=Display outline around grid (Default Relief). pad(size)=Set padding between grid cells to size pixels. raised=Set button relief style to "raised". save=Add command to current saved screen. sunken=Set outline relief style to "sunken". title=Display title at top left of grid. 'literal'=Set default literal to 'literal'. action=If not a known option then assume option is action.
Cell Options:	black=Set item background colour to "black". blue=Set item text colour to "blue". center=Align label text in center of grid cell (Default left). color(foreground/background)=Set button/label colours to foreground/background. darkgray=Set grid background colour to "dark gray". gray=Set grid background colour to "gray". green=Set item text colour to "green" groove=Set button relief style to "groove". inverse=Set inverse label text (Black background, Default white text). outline=Display outline around grid (Default Relief). raised=Set button relief style to "raised". red=Set item text colour to "red". right=Align label text to right of grid cell (default is left). sunken=Set button relief style to "sunken". yellow=Set item text colour to "yellow". 'literal'=Set item literal to 'literal'. integer=Set item to span integer cells. action=If not a known option then assume option is action.
Return:	None.
Example:	`addGrid {keypad 2,3 1 {{1 2 3} {4 5 6} {7 8 9}} raised {keypadaction %}}` more

The addGrid command is used to create a Grid of Buttons/Labels.

If an option is specified which is not matched to one of the known options it is assumed to be an action.

The action has two percent ("%") substitution options. "%" will be replaced in the action by the item name, and "%%" will be replaced in the action by the default/grid item literal. The default grid literal is set using the 'literal' option, the default for the grid literal is "!".

The Grid name may have a prefix to set the default state for button items, "+" is equivalent to the normal option and "-" to disabled.

The grid is defined as a list of rows. Each row is a list of items (buttons/labels). The grid comprises of cells, each cell is one row deep an size characters wide. Using the span item option, an item can be created more than one cell wide. Each grid cell can use Cell Options to override/set cell specific options. The above example will create a grid of buttons with the following layout:-

1 2 3

4 5 6

7 8 9

By default grid items are created as buttons. There are also options to create icon buttons, check buttons, radio buttons and labels.

For the following examples it is assumed that the name of the grid is "deliver"

Prefix Purpose Example Data Name Selected Value

: Create icon button :previous N/A N/A

@ Create check button @dispatched deliver:dispatched Y

% Create radio button %arrive:monday deliver:arrive monday

! Create label !Delete N/A N/A

Check buttons have a value of "Y" when selected and "N" when not selected. Radio buttons use the string to the right of the colon (":") as the selected value.

Where options are to be specified for an individual item, the item and its options must be enclosed in braces ("{}").

Notes:

For further details and examples see Using Grids.
To change the text of button/label items use setItem.
To change the state of button items use setItemState.
Icons must be chosen from the Icon Selection.

addHotKey

Syntax:	addHotKey {name action ?options?}
Parameters:	name=item_name action=action options=confirm\|validate
Options:	confirm(message)=Enable action confirmation dialog with message. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned.
Return:	None.
Example:	`addHotKey {Control-p {printrecord customer}}`

The addHotKey command is used to create a "Hot Key" action.

Combinations of Alt, Control and Shift, together with upper/lower case letters/numbers and functions keys F1-F12 may be used. The symbolic key names should be separated by "-" (For example: Alt-Control-d, Shift-F1). The case used in symbolic key names is also important, "Control" must be used not "control".

To disable/deactivate a Hot Key a null action should be specified (For example:addHotKey {Control-p {}}).

Note:

For further details and examples see Using HotKeys.

addLabel

Syntax:	addLabel {name position size text ?options?}
Parameters:	name=item_name position=xpos,ypos size=width options=bold\|blue\|center\|color\|green\|inverse\|outline\|noborder\|red\|right\|text\|title\|yellow
Options:	blue=Set label text colour to "blue". bold=Set bold label text. center=Algin label text in centre of label area (default is left). color(foreground/background)=Set label colours to foreground/background. green=Set label text colour to "green". inverse=Set inverse label text (Black background, Default white text). inverse(colour)=Set inverse label text (Colour background). outline=Display outline around label (Default Relief). noborder=Do not add border padding around label. red=Set label text colour to "red". right=Align label text to right of label area (default is left). text(text)=Set title text to text. title=Display title at top left of label. yellow=Set label text colour to "yellow".
Return:	None.
Example:	`addLabel {address 2,10 20 "This is label text"}` more

The addLabel command is used to create a label item.

If an option is specified which is not matched to one of the known options it is ignored.

addMenu

Syntax:	addMenu {{menu {item ?options?} {...}} {menu {item ?options?} {...}}} addMenu {window {menu {item ?options?} {...}} {menu {item ?options?} {...}}}
Parameters:	window=window_name menu=menu item=item options=confirm\|disabled\|exit\|group\|normal\|validate\|action
Options:	confirm(message)=Enable action confirmation dialog with message. disabled=Disable menu item. exit=Set action to cause application to exit. group(groups)=Set list of groups which enable this menu item. normal=Enable menu item. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not a known option then assume option is action.
Return:	None.
Example:	`addMenu {{File {Save {save file}} {Delete {delete file}}}}` more

The addMenu command is used to create a menubar.

On Windows and Unix systems the menubar will be created at the top of the application screen.

If an option is specified which is not matched to one of the known options it is assumed to be an action. Menu actions have a percent ("%") subsitution facility. If an action name contains a percent sign ("%") it will be replaced by the name of the current Group.

The menu/item name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

A null item displays a separator bar.

The menu options obey the state. Each menu option can override the state and forced to be either normal or disabled. In addition, the state of menu options can be controlled using Groups.

If a menubar already exists this command will have no effect. In order to add a new menubar the existing one must first be deleted.

Notes:

To refine control of menu option states use setGroup.
To delete the menubar use remove.

addMultiList

Syntax:	addMultiList {name position size columndata ?options?}
Parameters:	name=item_name position=xpos,ypos columndata=columns size=lines options=confirm\|copy\|outline\|yscroll\|validate\|action
Options:	confirm(message)=Enable action confirmation dialog with message. copy(data_items)=Copy columns from selected line to data_items. outline=Display outline around list (Default Relief). validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. yscroll=Add "Y" direction (vertical) scrollbar. action=If not a known option then assume option is action.
Return:	name (Value of selected line text).
Example:	`addMultiList {result 2,10 10 {Name,30 Age,4 Pay,10,numeric}}` more

The addMultiList command is used to create a multi column listbox item.

If an option is specified which is not matched to one of the known options, it is assumed to be an action. The action is activated by double clicking on the required line in the list.

If the last column is given a size of zero ("0") it is created as a "hidden" column. The value in the hidden column is returned when a line is selected, but it is not displyed.

Notes:

To initialise/change the value of multi-list items use setItem.

addPickList

Syntax:	addPickList {name position size selectlist ?options?}
Parameters:	name=item_name position=xpos,ypos size=width,lines selectlist=selections options=disabled\|flat\|gray\|groove\|normal\|outline\|sunken
Options:	disabled=Disable button. flat=Set button relief style to "flat". gray=Set picklist background to gary matching window background. groove=Set relief style to "groove". group(groups)=Set list of groups which enable this picklist. normal=Enable button. outline=Display outline around picklist (Default Relief). sunken=Set relief style to "sunken".
Return:	name (Value of item selected from drop-down picklist).
Example:	`addPickList {Fruit 1,5 15,5 {+Apple Banana Peach Lemon Star_Fruit}}` more

The addPickList command is used to create a picklist item.

The value of the picklist can be set by prefixing the appropriate picklist selection with "+". If more than one picklist selection is specified, then the last only is used.

The Picklist name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

Notes:

To initialise/change the value of picklist items use setItem.
To change the state of picklist items use setItemState.

addRadioButtons

Syntax:	addRadioButtons {name position labels ?options?}
Parameters:	name=item_name position=xpos,ypos labels=labels options=disabled\|group\|horizontal\|normal\|outline\|text\|title\|action
Options:	disabled=Disable radio buttons. group(groups)=Set list of groups which enable this radio button. horizontal=Arrange radio buttons horizontal (default vertical). normal=Enable radio buttons. outline=Display outline around radio buttons (Default Relief). text(text)=Set title text to text. title=Display title at top left of radio buttons. action=If not a known option then assume option is action.
Return:	name (Label of selected button).
Example:	`addRadioButtons {start_at 2,10 {+begin middle end}}` more

The addRadioButtons command is used to create a Radio-Buttons Item.

If an option is specified which is not matched to one of the known options, it is assumed to be an action. The action is activated when a button is selected.

An active radio button can be set by prefixing the appropriate label with "+". If more than one active radio button is specified, then the last only is used.

If the title option is specified a title derived from the name will be displayed at the top left of the radio buttons. This option is best used with the groove relief style outline.

The Radio-Buttons name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

Notes:

To initialise/change the value of radio buttons use setItem.
To change the state of radio buttons use setItemState.

addText

Syntax:	addText {name position size ?options?}
Parameters:	name=item_name position=xpos,ypos size=widthxheight options=color\|confirm\|courier\|disabled\|edit\|exit\|helvetica\|normal\|notags\|nowrap\|outline\|tags\|times\|validate\|wrap\|xscroll\|xyscroll\|yscroll\|action
Options:	color(foreground/background)=Sets text foreground/background colors to forground/background (Edit mode). color(color)=Sets link foreground color to color (Read-only mode). confirm(message)=Enable action confirmation dialog with message. courier=Set default font to "courier". courier(size)=Set default font to "size" point "courier" (default is 10 point helvetica). disabled=Disallow text update via keyboard (default is read-only). edit=Create editable text item. exit=Set action to cause application to exit. helvetica=Set default font to "helvetica". helvetica(size)=Set default font to "size" point "helvetica" (default is 10 point helvetica). normal=Allow entry update via keyboard. notags=Disable tag processing for read-only text item. nowrap=Disable text wrapping for read-only text item. outline=Display outline around list. tags=Enable tag processing for editable text item. times=Set default font to "times". times(size)=Set default font to "size" point "times" (default is 10 point helvetica). validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. wrap=Enable text wrapping for editable text item. xscroll=Add "X" direction (horizontal) scrollbar. xyscroll=Add "X" direction (horizontal) and "Y" direction (vertical) scrollbars. yscroll=Add "Y" direction (vertical) scrollbar. action=If not a known option then assume option is action.
Return:	name (Contents of text item -or- tag identifier depending on mode).
Example:	`addText {information 2,10 40x12}` more

The addText command is used to create a Text item.

If an option is specified which is not matched to one of the known options it is assumed to be an action.

When creating an editable text item, the width is based on the character size of the selected font.

By default a read-only/tag-processing text item is created. The "tags" have a syntax similar to HTML and allow text attributes and links/actions to be used (See Tags). Text item actions are invoked using "action" tags.

The default values for tag processing and text wrap depend on which options are specified:

Option Tag Processing Text Wrap

DEFAULT Yes Yes

edit No No

xscroll N/A No

xyscroll N/A No

The text item supports cut, copy and paste operations. Text is selected in the normal way by holding down the left mouse button and draging. Click and hold the right mouse button to display the pop-up "Cut, Copy, Paste" menu. To select an option hold the right button down while moving the cursor. Cut and paste options are not available for read-only items.

For an editable text item, the data given by a text item when used as a parameter in an action is the contents of the text item. For read-only text item it is the identifier of the selected "action" link (See Tags).

The Text name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

Notes:

To initialise/change the value of text items use setItem.
To change the state of text items use setItemState.

addToolbar

Syntax:	addToolbar {style {icon ?options?} {icon ?options?} {...}} addToolbar {name position style {icon ?options?} {icon ?options?} {...}} addToolbar {style(definition) {icon ?options?} {icon ?options?} {...}} addToolbar {name position style(definition) {icon ?options?} {icon ?options?} {...}}
Parameters:	name=item_name position=xpos,ypos position=ypos style=style style(definition)=style(style,orient,size,position,button,separator,border,underline) icon=icon options=confirm\|disabled\|exit\|filesave\|fileselect\|help\|normal\|validate\|action
Options:	confirm(message)=Enable action confirmation dialog with message. disabled=Disable toolbar button. exit=Set action to cause application to exit. filesave(file)=Enable file "save as" dialog with file as default (SATSHELL Only). fileselect(file)=Enable file "file select" dialog with file as default (SATSHELL Only). group(groups)=Set list of groups which enable this toolbar button. help(message)=Enable balloon help with message. normal=Enable toolbar button. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not a known option then assume option is action.
Return:	None.
Example:	`addToolbar {flat {disk {save file}} {trash {delete file}}}` more

The addToolbar command is used to create a toolbar.

If the first parameter is a valid style, then the toolbar will be created inside the top of the application screen (position 0,0), with the name "toolbar". If the first parameter is not a valid style, then the first parameter is the name and the second parameter the position. This second syntax allows for more than one toolbar to be created and/or a toolbar to be positioned as required.

The toolbar style must be chosen from the Style Selection, the toolbar icons must be chosen from the Icon Selection. Style definitions can be used to create custom toobar styles and/or vertical toolbars.

If an option is specified which is not matched to one of the known options it is assumed to be an action.

The style/name/icon name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.

A null icon displays a style dependent separator.

The toolbar buttons obey the state. Each toolbar button can override the state and forced to be either normal or disabled.

Note:

To change the state of toolbar buttons use setItemState.
To delete the toolbar use remove.

addTree

Syntax:	addTree {name position size ?options?}
Parameters:	name=item_name position=xpos,ypos size=widthxheight options=confirm\|exit\|expand\|file\|folder\|outline\|validate\|xscroll\|xyscroll\|yscroll\|action
Options:	confirm(message)=Enable action confirmation dialog with message. exit=Set action to cause application to exit. expand=Display expanded tree by default. file(icon)=Set default file node icon to icon. folder(icon)=Set default folder node icon to icon. outline=Display outline around list. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. xscroll=Add "X" direction (horizontal) scrollbar. xyscroll=Add "X" direction (horizontal) and "Y" direction (vertical) scrollbars. yscroll=Add "Y" direction (vertical) scrollbar. action=If not a known option then assume option is action.
Return:	name (Selected node).
Example:	`addTree {files 2,10 40x12}` more

The addTree command is used to create a Tree item.

If an option is specified which is not matched to one of the known options it is assumed to be an action.

Tree items support two node types; "file" and "folder". Folders can be expanded and may contain files and/or folders. Although the nodes are refered to as files/folders they may be used for any purpose. The default icons reflect the file/folder use, but using the ICONS facility other icons may be specified, both as defaults and on a per node basis.

When a node is selected using a single/double click the full (hierarchic) node name is returned. If the node is selected using a double click the action (if specified) is invoked.

To expand/close a folder; single click on the black arrow to the left of the folder icon.

Tree item data is set using the setItem command. However, the tree item specific options are described here.

The setItem format for tree items: setItem {name {node ?options?} {node ?options?} ...}

Node Option Description Default

folder Sets node type to "folder" which can be expanded/contracted. "file"

icon(icon) Sets the icon for this node to icon. Depends on node type.

text(text) Sets the display text for this node to text. Based on node name.

Example:

setItem {tree1
   /File1
   /File2
   {/Dir1 folder}
   /Dir1/File_Name_Three
   /Dir1/File4
   {/Dir1/Dir2 folder text(Another_Folder)}
   {/Dir1/Dir2/File5 icon(devdiskunmount16)}
   /Dir1/Dir2/File6
   /Dir1/File7
   /File8
}

Notes:

To initialise/change the value of tree items use setItem.

addValidation

Syntax:	addValidation {name pattern}
Parameters:	name=item_name pattern=regular_expression
Options:	None.
Return:	None.
Example:	`addValidation {customer_id "^[A-Z][0-9]{6}$"}`

The addValidation command is used to create a new entry item validation.

The pattern must be a regular expression in a form acceptable to TCL.

clear

Syntax:	clear clear window
Parameters:	window=window_name
Options:	None.
Return:	None.
Example:	`clear`

The clear command is used to delete all display and non-safe data items.

By default the Main window will be cleared. To clear a Child window the name of the window must be specified.

Safe data items and user defined validations are not affected by this command.

closeWindow

Syntax:	closeWindow window
Parameters:	window=window_name
Options:	None.
Return:	None.
Example:	`closeWindow help_window`

The closeWindow command is used to close a specified child window, and to delete all of the items associated with the window.

gotoLabel

Syntax:	gotoLabel {name label}
Parameters:	name=item_name label=label
Options:	None.
Return:	None.
Example:	`gotoLabel {help_text sections_3}`

The gotoLabel command is used to move the display of a text item to the specified label.

hide

Syntax:	hide {name name ...}
Parameters:	name=name
Options:	None.
Return:	None.
Example:	`hide {customer}`

The hide command is used to "hide" display items and contents.

A hidden item is unmapped from the display but is not deleted. The item, and its contents still exist and can be redisplayed using the placeItem command.

Note:

The clear and remove commands will delete hidden items.

newScreen

Syntax:	newScreen {{title} ?options?} newScreen {window {title} ?options?}
Parameters:	window=window_name title=Title data in same format used by setTitle options=size\|group
Options:	size=widthxheight group=Name of display item/menubar Group.
Return:	None.
Example:	`newScreen {{"Add Customer"} 80x24 customer}`

The newScreen command is used to initailise the application screen.

By default the Main window is initialised. To initialise a Child window the name of the window must be specified.

If an option does not match the pattern of a screen size it is assumed to be a group.

This command deletes all display and non-safe data items, sets the window title text, clears the message line, optionally sets the screen size/Group and refreshes the menu (if one exists).

Therefore the above example is eqivalent to:-

clear
setTitle {"Add Customer"}
setMessage {}
setSize 80x24
setGroup customer
setFocus {}

The default window title is set in the application configuration file. The default action for newScreen is to append the title text to the window title with a dash separator. The title replace option causes the window title to be replaced with the title text. To restore the default title use newScreen with a null title value.

Note:

The screen size stays set until the next setSize or newScreen with a size specified.

newWindow

Syntax:	newWindow {window {title} size ?options?}
Parameters:	window=window_name title=Title data in same format used by setTitle size=widthxheight options=modal\|+position\|action
Options:	modal=Create "modal" window. position=+xpos+ypos action=If not known option then assume option is action.
Return:	None.
Example:	`newWindow {win1 {"Add Customer"} 80x24}`

The newWindow command is used to create and initailise a child window.

If an option is specified which is not matched to one of the known options, it is assumed to be an action. The action is activated when the window is "destroyed". This provides a facility to set a default action and/or tidy up if the window is closed using one of the title bar close buttons/menu options.

The window position, if specified, is measured in pixels relative to the top left of the screen. If the position is not specified then the Operating System Window Manager will "decide" where the new window is to be placed. There are a number of internal variables which can be used to give the screen/monitor resolution and window names/sizes/positions.

Note:

For further details and examples see Using Multiple (Child) Windows.

placeItem

Syntax:	placeItem {name position}
Parameters:	name=item_name position=xpos,ypos
Options:	None.
Return:	None.
Example:	`placeItem {Customer 2,10}`

The placeItem command is used to an item at the specified position.

This command can be used to redisplay a hidden item -or- move the specified item to a new postion in its window.

Note:

To hide an item use the hide command.

placeWindow

Syntax:	placeWindow {window position}
Parameters:	window=window_name position=+xpos+ypos
Options:	None.
Return:	None.
Example:	`placeWindow {Customer +200+150}`

The placeWindow command is used to a window to specified position on the monitor screen.

Notes:

The name of the parent window is MAIN (Must be uppercase).

There are two internal variables (:fposition and :tposition) which return the current position of a window.

remove

Syntax:	remove name
Parameters:	name=menu\|item_name
Options:	None.
Return:	None.
Example:	`remove address`

The remove command is used to delete a display, data item or menu.

To remove a menubar use the name menu.

Safe data items can be deleted using this command.

setAction

Syntax:	setAction name action
Parameters:	name=item_name action=action
Options:	None.
Return:	None.
Example:	`setAction save {save_customer cust_id}`

The setAction command is used to set/change the action for the item identified by name.

setDateFormat

Syntax:	setDateFormat date_format
Parameters:	date_format=date_format
Options:	None.
Return:	None.
Example:	`setDateFormat dd/mm/yyyy`

The setDateFormat command is used to set the date format used for entry date validations.

By default mm/dd/yy and mm/dd/yyyy formatted dates will be accepted by date validations.

setFocus

Syntax:	setFocus {item ?options?}
Parameters:	item=item options=next
Options:	next=Set focus to next "tab" sequence item.
Return:	None.
Example:	`setFocus first_name`

The setFocus command is used to set the focus to the specified item.

If item is the name of a display/data item, then the value of display/data item is used as the name of the item to which focus is given.

Currently only entry items and the parent window can be given focus. The item is assumed to be an entry item, unless the item is set to null (setFocus {}) in which case focus is given to the parent window.

This command is useful when using "Hot Keys" as they require that some part of the application screen has focus.

setGroup

Syntax:	setGroup group
Parameters:	group=group
Options:	None.
Return:	None.
Example:	`setGroup customer`

The setGroup command is used to set the name of the display item/menu group.

This command causes the display item and menubar options to be updated so that, where items/options are group specific, they are only enabled for the specified group.

Note:

The group can also be set using newScreen.

setItem

Syntax:	setItem {name value ...} setItem {name cell value}
Parameters:	name=item_name cell=row:column value=value
Options:	None.
Return:	None.
Example:	`setItem {first_name "Adrian"}` more

The setItem command is used to set the value of check-button, data, entry, grid, label, multi-list, picklist, radio-button, text and tree items.

The format of the value parameter depends on the type of item for which the value is to be set. For multi-list items a list of values (one for each item in the list) may be given. For grid items the cell must be specified.

If the name begins with "@", a safe data item is created (See Translations).

IMPORTANT: The new setItemState command should now be used in preference to setItem to set the state of button and toolbar items.

Notes:

To initialise/change the value of multiple items use setItems.

setItems

Syntax:	setItems {{name value} {name value} ...}
Parameters:	name=item_name value=value
Options:	None.
Return:	None.
Example:	`setItems {{first_name "Adrian"} {last_name "Davis"}}`

The setItems command is used to set the value of button, check-button, data, entry, label, picklist and radio-button items. This command cannot be used to set grid, multi-list or tree items.

The format of the value parameter depends on the type of item for which the value is to be set.

Notes:

To initialise/change the value of a single item use setItem.

setItemState

Syntax:	setItemState {name state} setItemState {name value ...} setItemState {name cell state}
Parameters:	name=item_name cell=row:column state=disabled\|normal value=[+\|-]name
Options:	None.
Return:	None.
Example:	`setItemState {first_name disabled}` more

The setItemState command is used to set the state (disabled|normal) of button, check-button, entry, grid, picklist, radio-button, text and toolbar items.

For grid items the cell must be specified.

Notes:

This command should be used in preference to setItem for buttons and toolbars.

setMessage

Syntax:	setMessage {text ?options?} setMessage { window text ?options?}
Parameters:	window=window_name text=text options=blue\|green\|red\|yellow
Options:	blue=Set message text colour to "blue". color(color)=Set message text colour to color. green=Set message text colour to "green". red=Set message text colour to "red". yellow=Set message text colour to "yellow".
Return:	None.
Example:	`setMessage {"Record not found" red}`

The setMessage command is used to set the message line text.

By default the message line of the Main window is set. To set the message line of a child window the window name must be specified.

setRelief

Syntax:	setRelief option
Parameters:	option=groove\|raised\|sunken
Options:	groove=Set relief style to "groove". raised=Set relief style to "raised". sunken=Set relief style to "sunken".
Return:	None.
Example:	`setRelief raised`

The setRelief command is used to set the default relief style.

The default relief style is "groove".

setSize

Syntax:	setSize size setSize {window size}
Parameters:	window=window_name size=widthxheight
Options:	None.
Return:	None.
Example:	`setSize 80x20`

The setSize command is used to set the size of the application screen.

Note:

The screen size stays set until the next setSize or newScreen with a size specified.

setState

Syntax:	setState option
Parameters:	option=disabled\|normal
Options:	disabled=Disable items. normal=Enable items.
Return:	None.
Example:	`setState disabled`

The setState command is used to set the default item state.

The default state depends on the access level assigned to the user. For users with "full" access the default state is "normal", for "read only" the default state is "disabled".

setTitle

Syntax:	setTitle {text ?options?} setTitle {window text ?options?}
Parameters:	window=window_name text=text options=replace
Options:	replace=Replace window title with text.
Return:	None.
Example:	`setTitle {"Add Customer"}` more

The setTitle command is used to set the window title text.

By default the title of the Main window is set. To set the title of a Child window the window name must be specified.

The default window title is set in the application configuration file. The default action for setTitle is to append the text to the window title with a dash separator. The replace option causes the window title to be replaced with text. To restore the default title use setTitle with a null text value.

setWindow

Syntax:	setWindow window
Parameters:	window=window_name
Options:	None.
Return:	None.
Example:	`setWindow help_window`

The setWindow command is used to set the default window name.

Note:

For further details and examples see Using Multiple (Child) Windows.

unlock

Syntax:	unlock
Parameters:	None.
Options:	None.
Return:	None.
Example:	`unlock`

The unlock command is used explicitly unlock the display.

This is can also be used for SATGUI screens without an associated processes.

updateItem

Syntax:	updateItem {name value ?options?}
Parameters:	name=item_name value=value options=top
Options:	top=Add text to top of item.
Return:	None.
Example:	`updateItem {Example1 "\nAdrian Davis"}`

The updateItem command is used to update the contents of an existing multi-list or text item.

By default the value is added to the end of current contents of the specified item. The top allows the value to be added to the top (begining) of current contents.

If it is required that the update be on a separate line within the item, a newline ("\n") should be added to the begining or end of value depending on whether update is to be added to the end or top of the item.

Notes:

To initialise the value of multi-list/text items use setItem.

Prefix	Purpose	Example	Data Name	Selected Value
`:`	Create icon button	`:previous`	N/A	N/A
`@`	Create check button	`@dispatched`	`deliver:dispatched`	`Y`
`%`	Create radio button	`%arrive:monday`	`deliver:arrive`	`monday`
`!`	Create label	`!Delete`	N/A	N/A

Option	Tag Processing	Text Wrap
DEFAULT	Yes	Yes
`edit`	No	No
`xscroll`	N/A	No
`xyscroll`	N/A	No

Node Option	Description	Default
`folder`	Sets node type to "folder" which can be expanded/contracted.	"file"
`icon(icon)`	Sets the icon for this node to icon.	Depends on node type.
`text(text)`	Sets the display text for this node to text.	Based on node name.