SATGUI Display Language (SAT/DL) Commands

actionaddBorderclearsetActionunlock
addButtonnewScreensetDateFormat
addButtonsremovesetGroup
addCheckButtonssetItem
addDatasetItems
addEntriessetMessage
addEntrysetRelief
addLabelsetSize
addMenusetState
addMultiListsetTitle
addRadioButtons
addValidation


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?}
Parameters: name=item_name
position=xpos,ypos
size=widthxheight
options=groove|raised|sunken|title
Options: groove=Set relief style to "groove".
raised=Set relief style to "raised".
sunken=Set relief style to "sunken".
title=Display title at top left of border.
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.

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.


addButton

Syntax: addButton {name position size ?options?}
Parameters: name=item_name
position=xpos,ypos
size=width
options=disabled|exit|noborder|normal|outline|validate|action
Options: disabled=Disable button.
exit=Set action to cause application to exit.
noborder=Set border to 0 (default 2).
normal=Enable button.
outline=Display outline around button.
validate=Perform all entry validations when actioned.
validate(?prefix?)=Perform entry validations of prefix items when actioned.
action=If not literal 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 literal options it is assumed to be an action.

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 ?pad? buttondata}
Parameters: position=xpos,ypos
size=width
pad=characters
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 the pad parameter is specified this value is used as the number of characters padding between buttons when a null buttondata item is found, the default is 2.

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|horizontal|normal|outline|title
Options: disabled=Disable check buttons.
horizontal=Arrange check buttons horizontal (default vertical).
normal=Enable check buttons.
outline=Display outline around check buttons.
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=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|disabled|focus|normal|outline|right|secret|validate|action|validation
Options: center=Align label text in center of label area (default is left).
disabled=Disallow entry update via keyboard.
focus=Give this entry focus.
normal=Allow entry update via keyboard.
outline=Display outline around entry.
right=Align label text to right of label area (default is left).
secret=Display "*" instead of actual character entered.
validate=Perform all entry validations when actioned.
validate(?prefix?)=Perform entry validations of prefix items when actioned.
action=If not literal or validation then assume option is action.
validation=If not literal 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 literal 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 and "-" to disabled.

Notes:

  • To initialise/change the value of entry items use setItem.
  • 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.

addLabel

Syntax: addLabel {name position size text ?options?}
Parameters: name=item_name
position=xpos,ypos
size=width
options=blue|center|outline|noborder|red|right
Options: blue=Set label text colour to "blue".
center=Algin label text in centre of label area (default is left).
outline=Display outline around label.
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).
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 literal options it is ignored.


addMenu

Syntax: addMenu {{menu {item ?options?} {...}} {menu {item ?options?} {...}}}
Parameters: menu=menu
item=item
options=disabled|exit|group|normal|validate|action
Options: 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 literal 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 literal options it is assumed to be an action.

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 columns ?options?}
Parameters: name=item_name
position=xpos,ypos
columndata=columns
size=lines
options=copy|outline|yscroll|validate|action
Options: copy(data_items)=Copy columns from selected line to data_items.
outline=Display outline around list.
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 literal 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 literal options, it is assumed to be an action. The action is activated by double clicking on the required line in the list.

Notes:

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


addRadioButtons

Syntax: addRadioButtons {name position labels ?options?}
Parameters: name=item_name
position=xpos,ypos
labels=labels
options=disabled|horizontal|normal|outline|title
Options: disabled=Disable radio buttons.
horizontal=Arrange radio buttons horizontal (default vertical).
normal=Enable radio buttons.
outline=Display outline around radio buttons.
title=Display title at top left of radio buttons.
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.

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.

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
Parameters: None.
Options: None.
Return: None.
Example: clear

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

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


newScreen

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

The newScreen command is used to initailise the application screen.

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

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.


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 menu group.

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


setItem

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

The setItem command is used to set the value of button, check-button, data, entry, label, multi-list and radio-button 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.

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 and radio-button items. This command cannot be used to set multi-list items.

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

Notes:


setMessage

Syntax: setMessage {text ?options?}
Parameters: text=text
options=blue|red
Options: blue=Set label text colour to "blue".
red=Set label text colour to "red".
Return: None.
Example: setMessage {"Record not found" red}

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


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
Parameters: 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?}
Parameters: 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.

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.


unlock

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

The unlock command is used explicitly unlock the display.

This is intended to be used for screens without an associated process.


Copyright © 2001
Adrian Davis.