User Interface Construction Toolkitt - Specific UI Control Utility Functions

• Contents
• Concepts
• Name Conventions
• Common UI Control Properties
• Creation of UI Controls
• Generic UI Control Utility Functions

• Specific UI Control Utility Functions
  • sd-show-dialog-shell
  • sd-hide-dialog-shell
  • sd-destroy-dialog-shell
  • sd-dialog-shell-p
  • sd-dialog-shell-visible-p
  • sd-dialog-shell-pinned-p
  • sd-set-dialog-shell-title
  • sd-set-control-binding
  • sd-set-scrolled-grid-area-geometry
  • sd-set-togglebutton
  • sd-reset-togglebutton
  • sd-togglebutton-set-p
  • sd-set-colorbutton-color
  • sd-set-text-control-value
  • sd-insert-text-control-value
  • sd-get-text-control-value
  • sd-set-text-control-selection
  • sd-set-text-control-range
  • sd-get-text-control-range
  • sd-add-text-control-range-item
  • sd-text-control-p
  • sd-text-control-highlighted-p
  • sd-text-control-editable-p
  • sd-set-range-control-items
  • sd-set-range-control-selected-item
  • sd-get-range-control-selected-item
  • sd-set-list-control-items
  • sd-get-list-control-items
  • sd-set-list-control-selected-items
  • sd-get-list-control-selected-items
  • sd-set-slider-control-value
  • sd-get-slider-control-value
  • sd-set-current-tab-control-page
  • sd-get-current-tab-control-page
  • sd-hide-tab-control-page
  • sd-show-tab-control-page

• Other UI related Utility Functions

SD-SHOW-DIALOG-SHELL  [function]

(sd-show-dialog-shell name :position shell-position)

Description:

Shows a dialog shell at a specific location on the screen. If you omit to pass a value for :position, the dialog shell will appear in the top left corner of the screen.

Parameters:

name {STRING}

Basename of a dialog shell or the real dialog shell handle including the "-DS" suffix, i.e. "basename-DS".

:position {LIST} - See here

Return Value:

t - success

nil - failure

Example:

(sd-show-dialog-shell "UICT-TEST" 
                      :position '("TOP-MENU-TOOLBOX-TB" :bottomleft 10 10))

See also:

• sd-create-dialog-shell

SD-HIDE-DIALOG-SHELL  [function]

(sd-hide-dialog-shell name 
                      :ignorePin  ingnore-pin-flag)

Description:

Use this function to hide a dialog shell.

Parameters:

name {STRING}

Basename of a dialog shell without "-DS" suffix.

:ignorePin {BOOLEAN}

Set this flag to t is you want to ignore the state of the pin button while hiding the dialog shell. That means, even if the dialog shell is pinned, a call to this function will hide the dialog shell.
If this flag is set to nil, the dialog shell will remain on the screen if pinned.

Return Value:

t - Dialog shell was removed successfully from the screen

nil

Either the dialog shell does not exist, or it is pinned and the parameter :ignorePin is set to nil (means: dialog shell stays on the screen)

Example:

(sd-hide-dialog-shell "UICT-TEST" :ignorePin t)

See also:

• sd-create-dialog-shell

SD-DESTROY-DIALOG-SHELL  [function]

(sd-destroy-dialog-shell name)

Description:

Use this function to destroy a dialog shell.

Parameters:

name {STRING} - Name of a dialog shell with or without "-DS" suffix.

Return Value:

t - Dialog shell was destroyed successfully

nil - The dialog shell does not exist, or cannot be destroyed.

Example:

(sd-destroy-dialog-shell "UICT-TEST")

SD-DIALOG-SHELL-P  [function]

(sd-dialog-shell-p name)

Description:

Predicate to check whether the control with handle name is of type dialog shell.

Parameters:

name {STRING}

Basename of a dialog shell or the real dialog shell handle including the "-DS" suffix, i.e. "basename-DS".

Return Value:

t - Control is of type dialog shell.

nil - otherwise

Example:

(sd-dialog-shell-p "UICT-TEST-DS") ;; returns t

SD-DIALOG-SHELL-VISIBLE-P  [function]

(sd-dialog-shell-visible-p name)

Description:

Predicate to indicate whether the dialog shell with basename or handle name is visible on the screen or not.

Parameters:

name {STRING}

Basename of a dialog shell or the real dialog shell handle including the "-DS" suffix, i.e. "basename-DS".

Return Value:

t - Dialog shell is visible

nil - Dialog shell is invisible

Example:

(sd-dialog-shell-visible-p "UICT-TEST-DS")

See also:

• sd-create-dialog-shell

SD-DIALOG-SHELL-PINNED-P  [function]

(sd-dialog-shell-pinned-p basename)

Description:

Predicate to indicate whether the dialog shell with basename basename is pinned or unpinned.

Parameters:

basename {STRING} - Basename of dialog shell (without "-DS" suffix)

Return Value:

t - Dialog shell is pinned

nil - Dialog shell is unpinned

Example:

(sd-dialog-shell-pinned-p "UICT-TEST")

See also:

• sd-create-dialog-shell

SD-SET-DIALOG-SHELL-TITLE  [function]

(sd-set-dialog-shell-title basename :title title)

Description:

Changes the title of dialog shell with basename basename.

Parameters:

basename {STRING} - Basename of dialog shell (without "-DS" suffix)

:title {STRING} - New dialog shell title

Return Value:

t - success

nil - failure

Example:

(sd-set-dialog-shell-title "UICT-TEST" :title "New Title")

See also:

• sd-create-dialog-shell

SD-SET-CONTROL-BINDING  [function]

(sd-set-control-binding name binding)

Description:

Binds a control to a resizable grid area. (see sd-create-resizable-grid-area). Depending on the binding, a control adjusts its position and size according to the resize operation applied to the resizable grid area.
Note: A binding can only be applied to an intermediate child control of a resizable grid area.

Parameters:

name {STRING} - Name of the control to be bound.

binding {LIST of KEYWORDS}

List of binding definitions for the control.
Following bindings are available:

• nil - The control becomes unbound.
• :left - Binds control to the left border of the client area. If the client area is resized horizontally the control will keep its position relative to the left border.
• :right - Binds control to the right border of the client area. If the client area is resized horizontally the control will keep its position relative to the right border.
• :top - Binds control to the top border of the client area. If the client area is resized vertically the control will keep its position relative to the top border.
• :bottom - Binds control to the bottom border of the client area. If the client area is resized vertically the control will keep its position relative to the bottom border.
• :relative-vertical - Binds control to the top and the bottom border of the client area. If the client area is resized vertically the control will keep the ratio of the distance to top and bottom border.
• :relative-horizontal - Binds control to the left and the right border of the client area. If the client area is resized horizontally the control will keep the ratio of the distance to left and right border.
• :resize-vertical - Binds control to the top and the bottom border of the client area. The control will be resized vertically if the client area is resized vertically.
• :resize-horizontal - Binds control to the left and the right border of the client area. The control will be resized horizontally if the client area is resized horizontally.
• :resize-both - Binds control to the all four borders. The control will resize if the client area is resized.

Return Value:

t - success

nil - failure

Example:

(sd-create-pushbutton-control "LEFT-PB" "RESIZABLE-DLG-SHELL-RG"
                              :x      0
                              :y      12
                              :width  7
                              :height 2
                              :title  ":left")

(sd-set-control-binding "LEFT-PB" '(:left))

See also:

• Full Example
• sd-create-resizable-grid-area
• sd-create-resizable-dialog-shell
• sd-create-splitter-control

SD-SET-SCROLLED-GRID-AREA-GEOMETRY  [function]

(sd-set-scrolled-grid-area-geometry name
                                    :gridWidth  width
                                    :gridHeight height)

Description:

Sets number of cells of client area in horizontal and vertical direction. See here for more information.

Parameters:

name {STRING} - Name of the scrolled grid area

:gridWidth {FIXNUM}

New horizontal number of cells in client area.

:gridHeight {FIXNUM}

New vertical number of cells in client area.

Return Value:

t - success

nil - failure

Example:

(sd-set-scrolled-grid-area-geometry "UICT-TEST-41-GA"
                                    :gridWidth  25
                                    :gridHeight 15)

See also:

• sd-create-scrolled-grid-area

SD-SET-TOGGLEBUTTON  [function]

(sd-set-togglebutton name :callAction call-action-flag)

Description:

Sets the toggle button with handle name to a pressed (checked) state. If the flag :callAction is set to t, the :pushAction of the toggle button control gets executed as well.

Parameters:

name {STRING} - Name of the toggle button control

:callAction {BOOLEAN}

Flag to indicate whether the toggle button control :pushAction shall be executed or not.

Return Value:

t - success

nil - failure

Example:

(sd-set-togglebutton "UICT-TEST-111-TB" :callAction t)

See also:

• sd-create-togglebutton-control

SD-RESET-TOGGLEBUTTON  [function]

(sd-reset-togglebutton name :callAction call-action-flag)

Description:

Resets the toggle button with handle name to a depressed (unchecked) state. If the flag :callAction is set to t, the :releaseAction of the toggle button control gets executed as well.

Parameters:

name {STRING} - Name of the toggle button control

:callAction {BOOLEAN}

Flag to indicate whether the toggle button control :releaseAction shall be executed or not.

Return Value:

t - success

nil - failure

Example:

(sd-reset-togglebutton "UICT-TEST-111-TB")

See also:

• sd-create-togglebutton-control

SD-TOGGLEBUTTON-SET-P  [function]

(sd-togglebutton-set-p name)

Description:

Predicate to indicate whether the toggle button control with handle name is set (checked, pressed) or not.

Parameters:

name {STRING} - Name of the toggle button control

Return Value:

t - Toggle button is set

nil - Toggle button is not set

Example:

(sd-togglebutton-set-p "UICT-TEST-111-TB")

See also:

• sd-create-togglebutton-control

SD-SET-COLORBUTTON-COLOR  [function]

(sd-set-colorbutton-color name :color color)

Description:

Sets or clears the color of a color button control.

Parameters:

name {STRING} - Name of the color button control

:color {STRING or nil}

Specification of the new color in "#rrggbb" notation. If nil is specified the color is cleared and a label none is displayed.

Return Value:

t - success

nil - failure

Example:

(sd-set-colorbutton-color "UICT-TEST-128-CB" :color "#ff0000") ;; red

See also:

• sd-create-colorbutton-control

SD-SET-TEXT-CONTROL-VALUE  [function]

(sd-set-text-control-value name
                           :text    text-value
                           :seeEnd  see-end-flag)

Description:

Sets a new value for the text control with handle name.

Parameters:

name {STRING} - Name of the text control

:text {STRING} - New value to be displayed in text control

:seeEnd {BOOLEAN [t]}

If the text value which you display in the text control exceeds the visible space, the text control allows you to scroll thru its value. This flag indicates whether you want to see either the last portion of the text (:seeEnd = t) or the beginning of the text (:seeEnd = nil).

Return Value:

t - success

nil - failure

Example:

(sd-set-text-control-value "UICT-TEST-125-TX" :text "New text value")

See also:

• sd-create-text-control

SD-INSERT-TEXT-CONTROL-VALUE  [function]

(sd-insert-text-control-value name
                              :text      text-value
                              :position  insert-position)

Description:

Inserts some new text into a text control.

Parameters:

name {STRING} - Name of the text control

:text {STRING} - Text string to insert

:position {KEYWORD or FIXNUM [:end]}

Insertion position of new text portion. This can be either

• :beginning - insert at beginning
• :end - append text to present text
• number - the character position within the present text to determine the insertion position. The number must be between 0 and length of present text.
• nil - insert at current cursor position

Return Value:

t - success

nil - failure

Example:

(sd-insert-text-control-value "UICT-TEST-125-TX" :text "changed " :position 4)

See also:

• sd-create-text-control

SD-GET-TEXT-CONTROL-VALUE  [function]

(sd-get-text-control-value name :trimString trim-string-flag)

Description:

Returns the current value of the text control with handle name.

Parameters:

name {STRING} - Name of the text control

:trimString {BOOLEAN [t]}

Flag to indicate whether leading and trailing space and tab characters should be removed automatically from the resulting string.

Return Value:

string - the current text control value

nil - failure

Example:

(sd-get-text-control-value "UICT-TEST-125-TX")  => "New changed text value"

See also:

• sd-create-text-control

SD-SET-TEXT-CONTROL-SELECTION  [function]

(sd-set-text-control-selection name
                               :startPosition start-position
                               :endPosition   end-position)

Description:

Call this function to select a range of characters in the text control with handle name.

Parameters:

name {STRING} - Name of the text control.

:startPosition {FIXNUM [0]}

Specifies the starting position. If :startPosition is -1, any current selection is removed..

:endPosition {FIXNUM [-1]}

Specifies the ending position. If :startPosition is 0 and :endPosition is -1, all the text in the text control is selected.

Return Value:

t - success

nil - failure

Example:

(sd-set-text-control-selection "UICT-TEST-125-TX" :startPosition 0 :endPosition -1)

See also:

• sd-create-text-control

SD-SET-TEXT-CONTROL-RANGE  [function]

(sd-set-text-control-range name
                           :range range-list)

Description:

Call this function in order to initialize the range of a text control. But it only will work for text controls that were created with the :range parameter. For all other text controls it will have no effect.

Parameters:

name {STRING} - Name of the text control.

:range {LIST [nil]}

Same as in sd-create-text-control.

If the parameter :range is set to nil the text range will be cleared.

Return Value:

t - success

nil - failure

Example:

(sd-set-text-control-range "UICT-TEST-55-TX"
                           :range '("Item 5" "Item 6"))

See also:

• sd-create-text-control

SD-GET-TEXT-CONTROL-RANGE  [function]

(sd-get-text-control-range name)

Description:

Call this function in order to get the range of a text control. But it only will work for text controls that were created with the :range parameter. For all other text controls it will have no effect.

Parameters:

name {STRING} - Name of the text control.

Return Value:

list - list of string items added to the range

nil - failure

Example:

(sd-get-text-control-range "UICT-TEST-55-TX")
  => ("Item 5" "Item 6")

See also:

• sd-create-text-control

SD-ADD-TEXT-CONTROL-RANGE-ITEM  [function]

(sd-add-text-control-range-item name
                                :item list-item)

Description:

Adds a string item to an existing text range.

Parameters:

name {STRING} - Name of the text control.

:item {STRING}

The string item will be added to the beginning of the the text range. If the number of list items will exceed the limit that was specified during the creation of the text control by the parameter :maxRangeCount the last element of the text range will be removed.

Return Value:

t - success

nil - failure

Example:

(sd-add-text-control-range-item "UICT-TEST-55-TX"
                                 :item "Item 5")

See also:

• sd-create-text-control

SD-TEXT-CONTROL-P  [function]

(sd-text-control-p name)

Description:

Predicate to check whether or not specified control with handle name is a text control.

Parameters:

name {STRING} - Name of the control.

Return Value:

t - control is of type text

nil - control is not of type text

Example:

(sd-text-control-p "UICT-TEST-125-TX")

See also:

• sd-create-text-control

SD-TEXT-CONTROL-HIGHLIGHTED-P  [function]

(sd-text-control-highlighted-p name)

Description:

Predicate to check whether or not specified text control with handle name is highlighted.

Parameters:

name {STRING} - Name of the text control.

Return Value:

t - text control is highlighted

nil - text control is not highlighted

Example:

(sd-text-control-highlighted-p "UICT-TEST-125-TX")

See also:

• sd-create-text-control

SD-TEXT-CONTROL-EDITABLE-P  [function]

(sd-text-control-editable-p name)

Description:

Predicate to check whether or not specified text control with handle name is editable.

Parameters:

name {STRING} - Name of the text control.

Return Value:

t - text control is editable

nil - text control is not editable

See also:

• sd-create-text-control

SD-SET-RANGE-CONTROL-ITEMS  [function]

(sd-set-range-control-items name :range range-list)

Description:

Allows you to set the range control items at runtime.

Parameters:

name {STRING} - Name of the range control

:range {LIST} - Same as in sd-create-range-control

Return Value:

t - success

nil - failure

Example:

(sd-set-range-control-items "UICT-TEST-26-RA"
      :range '("Item 1" (2 :title "Second") :third))

See also:

• sd-create-range-control

SD-SET-RANGE-CONTROL-SELECTED-ITEM  [function]

(sd-set-range-control-selected-item name
                                    :item         selected-item
                                    :callAction   call-action-flag)

Description:

Sets the current selected item of range control with handle name.

Parameters:

name {STRING} - Name of the range control

:item {STRING, FIXNUM, SYMBOL or KEYWORD}

The item to be set as selected item. This is either the range list entry itself or if you specified a list as range entry use the first element of this list.

:callAction {BOOLEAN}

Flag to indicate whether the range control :selectionAction shall be executed or not.

Return Value:

t - success

nil - failure

Example:

(sd-set-range-control-selected-item "UICT-TEST-26-RA"
      :item        :third 
      :callAction  t)

See also:

• sd-create-range-control

SD-GET-RANGE-CONTROL-SELECTED-ITEM  [function]

(sd-get-range-control-selected-item name)

Description:

Returns the current selected item of the range control with handle name.

Parameters:

name {STRING} - Name of the range control

Return Value:

item - The selected range control item

nil - failure

Example:

(sd-get-range-control-selected-item "UICT-TEST-26-RA")  => :third

See also:

• sd-create-range-control

SD-SET-LIST-CONTROL-ITEMS  [function]

(sd-set-list-control-items name
                           :items      item-list
                           :positions  position-list)

Description:

Allows you to change the complete item list or single items at specific positions of the list control with handle name.

Parameters:

name {STRING} - Name of the list control

:items {LIST}

Same as in sd-create-list-control. If you don't pass a :positions list, this list will replace the current contents of the list control.

:positions {LIST}

If you pass a list of item positions {FIXNUM} for this parameter, the items of the :items list replace the currently displayed items at the passed positions. The first displayed item in a list control has the position 1.
Note: The number of positions passed to this parameter should be the same as the number of items passed as :items list.

Return Value:

t - success

nil - failure

Examples:

(sd-set-list-control-items "UICT-TEST-31-LI"
     :items '("Item 1" "Item 2" "Item 3" :item4 5))

(sd-set-list-control-items "UICT-TEST-31-LI"
     :items      '("New Item 2" "New Item 4")
     :positions  '(2 4))

See also:

• sd-create-list-control

SD-GET-LIST-CONTROL-ITEMS  [function]

(sd-get-list-control-items name)

Description:

Returns a list with all items of list control name.

Parameters:

name {STRING} - Name of the list control

Return Value:

list - items of list control as list of strings

nil - failure

Example:

(sd-get-list-control-items "UICT-TEST-31-LI")
 
 => ("Item 1" "Item 2" "Item 3" "ITEM4" "5")

See also:

• sd-create-list-control

SD-SET-LIST-CONTROL-SELECTED-ITEMS  [function]

(sd-set-list-control-selected-items name
                                    :items       item-list
                                    :positions   position-list
                                    :callAction  call-action-flag)

Description:

Allows you to set the current selected item(s). If the :selectionMode of the list control is set to :single just one item can be selected otherwise more than one.
Items can be selected either via their string, number, symbol keyword representation or via their position in the display.

Parameters:

name {STRING} - Name of the list control

:items {LIST or STRING, FIXNUM, SYMBOL, KEYWORD} - One item or a list of multiple items to be selected

:positions {LIST or FIXNUM} - One position or a list of positions to be selected

:callAction {BOOLEAN}

Flag to indicate whether the list control :selectionAction shall be executed or not.

Return Value:

t - success

nil - failure

Examples:

(sd-set-list-control-selected-items "UICT-TEST-31-LI" :items "Item 3")

(sd-set-list-control-selected-items "UICT-TEST-31-LI"
      :items  '("New Item 2" 5))

(sd-set-list-control-selected-items "UICT-TEST-31-LI"
      :positions  1)

(sd-set-list-control-selected-items "UICT-TEST-31-LI"
      :positions  '(1 2 4))

See also:

• sd-create-list-control

SD-GET-LIST-CONTROL-SELECTED-ITEMS  [function]

(sd-get-list-control-selected-items name)

Description:

Returns the current selected item(s) of list control with handle name as list of items and positions.

Parameters:

name {STRING} - Name of the list control

Return Value:

list - List of items and positions

nil - failure

Example:

(sd-get-list-control-selected-items "UICT-TEST-31-LI")  =>
 
    (("Item 1" "New Item 2" "New Item 4") (1 2 4))

See also:

• sd-create-list-control

SD-SET-SLIDER-CONTROL-VALUE  [function]

(sd-set-slider-control-value name
                             :value        slider-value
                             :callAction   call-action-flag)

Description:

Sets the current value of the slider control with handle name. The new value must be in the :minValue and :maxValue bounds of the slider control (see sd-create-slider-control).

Parameters:

name {STRING} - Name of the slider control

:value {NUMBER} - New slider value within :minValue and :maxValue bounds

:callAction {BOOLEAN}

Flag to indicate whether the slider control :valueChangedAction shall be executed or not.

Return Value:

t - success

nil - failure

Example:

(sd-set-slider-control-value "UICT-TEST-34-SL" :value 21 :callAction t)

See also:

• sd-create-slider-control

SD-GET-SLIDER-CONTROL-VALUE  [function]

(sd-get-slider-control-value name)

Description:

Returns the current value of slider control with handle name.

Parameters:

name {STRING} - Name of the slider control

Return Value:

number - The current slider value

nil - failure

Example:

(sd-get-slider-control-value "UICT-TEST-34-SL")  => 21

See also:

• sd-create-slider-control

SD-SET-CURRENT-TAB-CONTROL-PAGE  [function]

(sd-set-current-tab-control-page name
                                 :page        page-name)

Description:

Sets the current page of the tab control with name name. If the tab of that page is currently not visible, it will be scrolled automatically to become visible.

Parameters:

name {STRING} - Name of the tab control

:page {STRING} - Name of the page which should be current

Return Value:

t - success

nil - failure

Example:

(sd-set-current-tab-control-page "UICT-TEST-51-TC"
        :page "UICT-TEST-51-PAGE2")

See also:

• sd-create-tab-control
• sd-insert-tab-control-page

SD-GET-CURRENT-TAB-CONTROL-PAGE  [function]

(sd-get-current-tab-control-page name)

Description:

Gets the name of the current page of the tab control with name name.

Parameters:

name {STRING} - Name of the tab control

Return Value:

name - The name of the current tab control page

nil - failure

Example:

(sd-get-current-tab-control-page "UICT-TEST-51-TC") => "UICT-TEST-51-PAGE1"

See also:

• sd-create-tab-control
• sd-insert-tab-control-page

SD-HIDE-TAB-CONTROL-PAGE  [function]

(sd-hide-tab-control-page name
                          :page  page-name)

Description:

Supported for tab controls with :verticalTabs set to t only:
Hides the tab page with name page-name from tab control with identifier name and removes its tab title from the vertical tab list.

Parameters:

name {STRING} - Name of the tab control

:page {STRING} - Name of the page which should be removed

Return Value:

t - success

nil - failure

Example:

(sd-hide-tab-control-page "UICT-VERT-TABS-2-TC" :page "UICT-VERT-TABS-2-PAGE-2-PA")

See also:

• sd-create-tab-control
• sd-insert-tab-control-page

SD-SHOW-TAB-CONTROL-PAGE  [function]

(sd-show-tab-control-page name
                          :page     page-name
                          :current  current-flag)

Description:

Supported for tab controls with :verticalTabs set to t only:
Shows the tab page with name page-name of tab control with identifier name and adds its tab title to the vertical tab list. Its former position (before hide) is maintained.

Parameters:

name {STRING} - Name of the tab control

:page {STRING} - Name of the page which should be shown again

:current {BOOLEAN [nil]} - Indicates whether the page should become the current page or not

Return Value:

t - success

nil - failure

Example:

(sd-show-tab-control-page "UICT-VERT-TABS-2-TC" :page "UICT-VERT-TABS-2-PAGE-2-PA"
                                                :current t)

See also:

• sd-create-tab-control
• sd-insert-tab-control-page