[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]

User Interface Construction Toolkit - Generic UI Control Utility Functions

Function Index Top of Page

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

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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")

Function Index Top of Page

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)

Function Index Top of Page

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)

Function Index Top of Page

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)

Function Index Top of Page

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)

Function Index Top of Page

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"

Function Index Top of Page

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")

Function Index Top of Page

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)

Function Index Top of Page

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

Function Index Top of Page

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")

Function Index Top of Page

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)

Function Index Top of Page

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")
[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]
© 2019 Parametric Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved