SAT Display Language (SAT/DL) Commands
S@
Home SATGUI SATSHELL SATFORM SATFILTER SATREPORT SATMYSQL License Download Examples Contact

NOTES:


actionInitiate an action from a SAT server-side action process.
addBorderCreate a Border item with groove/sunken/raised relief.
addButtonCreate a Button item.
addButtonsCreate a row of Button items.
addCheckButtonsCreate a group of related Check Buttons.
addDataCreate a Data item.
addEntriesCreate a column -or- grid of Entry field items.
addEntryCreate an Entry field item.
addGridCreate a Button/Label Grid.
addHotKeyCreate a Hot Key action.
addLabelCreate a Label item.
addMenuCreate a Menubar with drop-down menus.
addMultiListCreate a Multi column Listbox item.
addPickListCreate a drop-down Pick List item.
addRadioButtonsCreate a group of related Radio Buttons.
addTextCreate Text item.
addToolbarCreate Toolbar item.
addTreeCreate Tree item.
addValidationCreate a new Validation pattern.
clearDelete all display and non-safe data items.
closeWindowClose child window and delete associated items.
gotoLabelMove display of text item to specified label.
hideHide specified item.
newScreenInitialise application Screen (Set title/size).
newWindowCreate new (child) window and initialise Window screen (Set title/size).
placeItemRedisplay a hidden item -or- move item to a new position.
placeWindowPlace window at specified position on the screen.
removeDelete a display/data item -or- menu.
setActionSet/change action for specified item.
setDateFormatSet Date Format used by entry field validations.
setFocusSet Focus to specified item.
setGroupSet name of menu Group.
setItemSet value of Item.
setItemsSet values for a list of Items.
setItemStateSet state of Item.
setMessageSet Message line text.
setReliefSet default Relief style.
setSizeSet Size of application screen.
setStateSet default item State (normal/disabled).
setTitleSet application window Title text.
setWindowSet default window name.
unlockUnlock display.
updateItemUpdate 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:


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:


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:


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:


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:


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:


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:


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:-

123
456
789

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"

PrefixPurposeExampleData NameSelected Value
:Create icon button:previousN/AN/A
@Create check button@dispatcheddeliver:dispatchedY
%Create radio button%arrive:mondaydeliver:arrivemonday
!Create label!DeleteN/AN/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:


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:


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:


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:


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:

OptionTag ProcessingText Wrap
DEFAULTYesYes
editNoNo
xscrollN/ANo
xyscrollN/ANo

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 OptionDescriptionDefault
folderSets 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:


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:


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:


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:


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:


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:


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:


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:


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:


Copyright © 2003 Adrian Davis.