User Interface Construction Toolkit - Generic UI Control Utility Functions

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

• Generic UI Control Utility Functions
  • sd-control-p
  • sd-destroy-control
  • sd-show-control
  • sd-hide-control
  • sd-control-visible-p
  • sd-control-visible-within-parent-p
  • sd-enable-control
  • sd-disable-control
  • sd-control-enabled-p
  • sd-get-toplevel-window-geometry
  • sd-set-toplevel-window-geometry
  • sd-get-control-geometry
  • sd-set-control-geometry
  • sd-get-control-title
  • sd-set-control-title
  • sd-eval-control-action
  • sd-set-control-action
  • sd-set-control-image
  • sd-get-control-focus
  • sd-set-control-focus

• Specific UI Control Utility Functions
• Other UI related Utility Functions

SD-CONTROL-P  [function]

(sd-control-p name)

Description:

Checks whether a control with identifier name exists.

Parameters:

name {STRING} - Name of control to check

Return Value:

t - control exists

nil - control does not exist

Examples:

(sd-control-p "UICT-TEST-DS") => t
(sd-control-p "Foo") => nil

SD-DESTROY-CONTROL  [function]

(sd-destroy-control name)

Description:

Destroys the control, area, grid area or dialog shell with handle name. If the control was parent control of more child controls, all these children get destroyed as well.

Parameters:

name {STRING} - Name of control to destroy

Return Value:

t - success

nil - failure

Example:

(sd-destroy-control "UICT-TEST-DS")

SD-SHOW-CONTROL  [function]

(sd-show-control name)

Description:

Makes a previously hidden control, area or grid area reappear on the screen. Children of a (grid) area will be shown as well. If you show a hidden (grid) area which was appended to an area before, the dialog shell will resize itself to accommodate the (grid) area again.
Note: To display a dialog shell, you have to use sd-show-dialog-shell

Parameters:

name {STRING} - Name of control, area or grid area to be shown

Return Value:

t - success

nil - failure

Example:

(sd-show-control "UICT-TEST-12-GA")

SD-HIDE-CONTROL  [function]

(sd-hide-control name)

Description:

Hides a control, area or grid area with handle name. If name refers to a (grid) area, all children of this (grid) area will disappear as well. If the (grid) area was appended to an area, the owning dialog shell will resize itself to reflect this change.
Note: To hide a dialog shell, you have to use sd-hide-dialog-shell

Parameters:

name {STRING} - Name of control, area or grid area to be hidden

Return Value:

t - success

nil - failure

Example:

(sd-hide-control "UICT-TEST-12-GA")

SD-CONTROL-VISIBLE-P  [function]

(sd-control-visible-p name)

Description:

Predicate to determine whether the control, area or grid area with handle name and all areas which lie above name in the hierarchy structure are visible (shown) or not.

Parameters:

name {STRING} - Name of control, area or grid area to check its visibility

Return Value:

t - control and all its higher-level areas are visible

nil - control or at least one of its higher-level areas is invisible

Example:

(sd-control-visible-p "UICT-TEST-12-GA")

SD-CONTROL-VISIBLE-WITHIN-PARENT-P  [function]

(sd-control-visible-within-parent-p name)

Description:

Predicate to determine whether the control, area or grid area with handle name is visible (shown) or not. It does not regard the visibility of its higher-level areas, that is, though one of the control's higher-level areas is invisible the control itself may be marked as visible.

Parameters:

name {STRING} - Name of control, area or grid area to check its visibility

Return Value:

t - control is visible

nil - control is invisible

Example:

(sd-control-visible-within-parent-p "UICT-TEST-12-GA")

SD-ENABLE-CONTROL  [function]

(sd-enable-control name :inclChildren incl-children-flag)

Description:

Reenables a previously disabled control with handle name. If you enable a (grid) area and set the flag :inclChildren to t, all (grid) area children get reenabled as well.
Note: This function replaces sd-enable-button.

Parameters:

name {STRING} - Name of control, area or grid area to be enabled

:inclChildren {BOOLEAN}

If this flag is set to t, all children of a (grid) area get reenabled as well

Return Value:

t - success

nil - failure

Example:

(sd-enable-control "UICT-TEST-111-TB")

SD-DISABLE-CONTROL  [function]

(sd-disable-control name :inclChildren incl-children-flag)

Description:

Disables a control with handle name. The user can no longer interact with disabled controls. Disabled controls are displayed greyed out.
If you disable a (grid) area and set the flag :inclChildren to t, all (grid) area children get disabled as well.
Note: This function replaces sd-disable-button.

Parameters:

name {STRING} - Name of control, area or grid area to be disabled

:inclChildren {BOOLEAN}

If this flag is set to t, all children of a (grid) area get disabled as well

Return Value:

t - success

nil - failure

Example:

(sd-disable-control "UICT-TEST-111-TB")

SD-CONTROL-ENABLED-P  [function]

(sd-control-enabled-p name)

Description:

Predicate to check whether a control with handle name is enabled or disabled

Parameters:

name {STRING} - Name of control to be checked

Return Value:

t - control is enabled

nil - control is disabled

Example:

(sd-control-enabled-p "UICT-TEST-111-TB")

SD-GET-TOPLEVEL-WINDOW-GEOMETRY  [function]

(sd-get-toplevel-window-geometry name)

Description:

Returns a property list containing the x,y position, width and height of a toplevel window, which is either a dialog shell or the application main window. The returned values are measured in screen coordinates. For grid controls refer to sd-get-control-geometry.

Parameters:

name {STRING or KEYWORD} - Name of dialog shell or :application to identify the application main window.

Return Value:

plist - Property list of the following format:

(:x x-coordinate :y y-coordinate :width width :height height)

nil - failure

Example:

(sd-get-toplevel-window-geometry "UICT-TEST-DS")  => (:x 0 :y 0 :width 100 :height 234)

SD-SET-TOPLEVEL-WINDOW-GEOMETRY  [function]

(sd-set-toplevel-window-geometry name
                         :x       x-coordinate
                         :y       y-coordinate
                         :width   width
                         :height  height)

Description:

Allows you to modify the x position, y position, width or height of a dialog shell or the application main window. In order to set size and position for a grid control refer to sd-set-control-geometry.

Parameters:

name {STRING or KEYWORD} - Name of dialog shell or :application to identify the application main window.

:x {FIXNUM} - New x position (in grid coordinates)

:y {FIXNUM} - New y position (in grid coordinates)

:width {FIXNUM} - New width (in grid units)

:height {FIXNUM} - New height (in grid units)

Return Value:

t - success

nil - failure

Example:

(sd-set-toplevel-window-geometry :application :y 100 :height 1000)

SD-GET-CONTROL-GEOMETRY  [function]

(sd-get-control-geometry name)

Description:

Returns a property list containing the x,y position, width and height of a grid control. The returned values are relative to the parent's grid coordinate system. For dialog shells and the application main window refer to sd-get-toplevel-window-geometry.

Note:The function used to work for toplevel windows, too. This behavior is deprecated and may change in future releases.

Parameters:

name {STRING} - Name of grid control for which geometry values shall be retrieved.

Return Value:

plist - Property list of the following format:

(:x x-coordinate :y y-coordinate :width width :height height)

nil - failure

Example:

(sd-get-control-geometry "UICT-TEST-111-TB")  => (:x 0 :y 0 :width 10 :height 2)

SD-SET-CONTROL-GEOMETRY  [function]

(sd-set-control-geometry name
                         :x       x-coordinate
                         :y       y-coordinate
                         :width   width
                         :height  height)

Description:

Allows you to modify the x position, y position, width or height of a grid control with handle name at runtime. All values have to be passed in the grid coordinate system of the parent grid area. In order to set size and position for a dialog shell or the application main window refer to sd-set-toplevel-window-geometry.

Note:The function used to work for toplevel windows, too. This behavior is deprecated and may change in future releases.

Parameters:

name {STRING} - Name of control

:x {FIXNUM} - New x position (in grid coordinates)

:y {FIXNUM} - New y position (in grid coordinates)

:width {FIXNUM} - New width (in grid units)

:height {FIXNUM} - New height (in grid units)

Return Value:

t - success

nil - failure

Example:

(sd-set-control-geometry "UICT-TEST-111-TB" :y 1 :height 1)

SD-GET-CONTROL-TITLE  [function]

(sd-get-control-title name)

Description:

Returns the title which is displayed on a control with handle name if it does not display an image instead of a string title.

Parameters:

name {STRING} - Name of control to inquire

Return Value:

title - String title displayed on control

nil - failure

Example:

(sd-get-control-title "UICT-TEST-111-TB")  =>  "Toggle 111"

SD-SET-CONTROL-TITLE  [function]

(sd-set-control-title name :title title)

Description:

Allows you to change the title of a control with handle name.

Parameters:

name {STRING} - Name of control

:title {STRING [" "]} - New title to be displayed

Return Value:

t - success

nil - failure

Example:

(sd-set-control-title "UICT-TEST-111-TB" :title "New Title")

SD-EVAL-CONTROL-ACTION  [function]

(sd-eval-control-action name action)

Description:

This function allows you the forced programmatic execution of a control's action.

Parameters:

name {STRING} - Name of control

action {KEYWORD}

Could be one of the following:

• :pushAction - see push, toggle, or color button control
• :releaseAction - see toggle button control
• :enterAction - see text control
• :setFocusAction - see text control
• :killFocusAction - see text control
• :modifyAction - see text control
• :closeAction - see dialog shell (pass basename of dialog shell as name)
• :okAction - see dialog shell (pass basename of dialog shell as name)
• :cancelAction - see dialog shell (pass basename of dialog shell as name)
• :helpAction - see dialog shell (pass basename of dialog shell as name)
• :dragAction - see slider control
• :valueChangedAction - see slider control

Return Value:

t - success

nil - failure

Example:

(sd-eval-control-action "UICT-TEST-111-TB" :releaseAction)

SD-SET-CONTROL-ACTION  [function]

(sd-set-control-action name action form)

Description:

Allows you to modify a control action at runtime.

Parameters:

name {STRING} - Name of control

action {KEYWORD}

Could be one of the following:

• :pushAction - see push or toggle button control
• :releaseAction - see toggle button control
• :enterAction - see text control
• :setFocusAction - see text control
• :killFocusAction - see text control
• :modifyAction - see text control
• :closeAction - see dialog shell (pass basename of dialog shell as name)
• :okAction - see dialog shell (pass basename of dialog shell as name)
• :cancelAction - see dialog shell (pass basename of dialog shell as name)
• :helpAction - see dialog shell (pass basename of dialog shell as name)
• :dragAction - see slider control
• :valueChangedAction - see slider control
• :selectionAction - see range control

form {quoted LISP-Form or STRING} - See here

Return Value:

t - success

nil - failure

Example:

(defun do-something-different-on-release ()
  ;; ...
  )

(sd-set-control-action "UICT-TEST-111-TB" 
                       :releaseAction '(do-something-different-on-release))

SD-SET-CONTROL-IMAGE  [function]

(sd-set-control-image name
                      :image                  image
                      :disabledImage          disabled-image
                      :selectedImage          selected-image
                      :disabledSelectedImage  disabled-selected-image)

Description:

Changes the image(s) of a control. If a control diplayed a string title before, it will display an image instead if you at least pass a valid image for the :image parameter.
If you pass no image at all for any of the parameters, the control will display a string title again. To set this title you have to use the function sd-set-control-title.

Parameters:

name {STRING} - Name of control

:image {STRING} - Name of a valid image created with sd-create-image

:disabledImage {STRING} - Name of a valid image to appear when control is disabled

:selectedImage {STRING} - Name of a valid image to appear when toggle button control is selected

:disabledSelectedImage {STRING}

Name of a valid image to appear when toggle button control is selected and disabled

Return Value:

t - success

nil - failure

Example:

(sd-set-control-image "UICT-TEST-111-TB" :image "Error-Icon")

SD-GET-CONTROL-FOCUS  [function]

(sd-get-control-focus)

Description:

Retrieves the name of the control that currently has the input focus.

Return Value:

name - Name string of control with input focus

nil - failure

Example:

(sd-get-control-focus)

SD-SET-CONTROL-FOCUS  [function]

(sd-set-control-focus &optional name)

Description:

Sets keyboard focus to the specified control with identifier name or to the default input window (User Input Line) if name is omitted.

Parameters:

name {STRING} - Name of specific control

Return Value:

t - always

Example:

(sd-set-control-focus "UICT-TEST-125-TX")