User Interface Construction Toolkit - Creation of UI Controls

• Contents
• Concepts
• Name Conventions
• Common UI Control Properties

• Creation of UI Controls
  • sd-create-dialog-shell
  • sd-create-resizable-dialog-shell
  • sd-append-area
  • sd-append-grid-area
  • sd-append-newline
  • sd-create-grid-area
  • sd-create-scrolled-grid-area
  • sd-create-resizable-grid-area
  • sd-create-splitter-control
  • sd-create-tab-control
  • sd-insert-tab-control-page
  • sd-create-pushbutton-control
  • sd-create-togglebutton-control
  • sd-create-colorbutton-control
  • sd-create-separator-control
  • sd-create-label-control
  • sd-create-text-control
  • sd-create-range-control
  • sd-create-list-control
  • sd-create-display-table-control
  • sd-create-slider-control
  • sd-create-context-menu
  • sd-create-viewport-control

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

SD-CREATE-DIALOG-SHELL  [function]

(sd-create-dialog-shell basename 
                        :title           title
                        :pin             pin-flag
                        :pinType         pin-type
                        :close           close-flag
                        :bottomLine      :bottom-line
                        :closeAction     close-action
                        :okAction        ok-action
                        :cancelAction    cancel-action
                        :helpAction      help-action
                        :margin          margin)

Description:

Creates a dialog shell as basis for a generic Creo Elements/Direct Modeling user interface.
The client area which can be filled with additional areas or grid areas has the name "name-AA" where name is the name of the dialog shell which you pass to this function.
To make a dialog shell appear on the screen, you have to use the function sd-show-dialog-shell.

Parameters:

basename {STRING}

Basename of the dialog shell. This name is used as basis to create several other handles to controls which will be created with a call to this function.
The name of the dialog shell will be "name-DS".

:title {STRING [" "]} - Top title of dialog shell

:pin {BOOLEAN [t]}

Flag to indicate whether the dialog shell shall contain a pin or not.

:pinType {KEYWORD [:command]}

Can be one of the following keywords:

• :command
• :option

Controls the look of the pin used in this dialog shell.

:close {BOOLEAN [t]}

Flag to indicate whether the dialog shell shall contain a close button or not. The action specified for the property :closeAction will be executed when the user hits the close button.

:bottomLine {KEYWORD or NIL [:ok-cancel-help]}

Can be one of the following keywords:

• :ok-cancel-help - show OK, Cancel and Help buttons
• :help - show Help button only
• :none - don't show any buttons

:closeAction {LISP-Form [hide dialog shell]}

Action which takes place when the user clicks the upper right close button (if available). The default action is to hide the dialog shell.

:okAction {LISP-Form ["complete"]}

Action which is executed when the user hits the OK button. The default action inputs the token complete into Creo Elements/Direct Modeling's command buffer.

:cancelAction {LISP-Form ["cancel"]}

Action which is executed when the user hits the Cancel button. The default action inputs the token cancel into Creo Elements/Direct Modeling's command buffer.

:helpAction {LISP-Form}

Action which is executed when the user hits the Help button.

:margin {FIXNUM [3]}

Space (in pixels) between the border of the client area (with name "name-AA") and its children areas or grid areas. A value greater than 0 is useful if the children areas employ a frame and/or title. See here for a visual explanation of this property.

Return Value:

t - success

nil - failure

Example:

(sd-create-dialog-shell "UICT-TEST"
      :title           "UICT Test"
      :bottomLine      :help)

See also:

• Specific Dialog Shell Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-RESIZABLE-DIALOG-SHELL  [function]

(sd-create-resizable-dialog-shell basename 
                                  :title       title
                                  :closeAction close-action
                                  :margin      margin
                                  :spacing     spacing
                                  :cellSize    cell-size
                                  :width       width
                                  :height      height)

Description:

Creates a resizable dialog shell as basis for a generic Creo Elements/Direct Modeling user interface.
To enable child controls for resize adjustments see sd-set-control-binding.
To make a dialog shell appear on the screen, you have to use the function sd-show-dialog-shell.

Parameters:

basename {STRING}

Basename of the dialog shell. The name of the dialog shell will be "name-DS". The client area (a grid area) that can be populated with grid areas and controls will have the name "name-RG".

:title {STRING [" "]} - Top title of dialog shell

:closeAction {LISP-Form [hide dialog shell]}

Action which takes place when the user clicks the upper right close button (if available). The default action is to hide the dialog shell.

:width {FIXNUM} - Width of the client area measured in pixels

This value also specifies the minimum width of the dialog shell.

:height {FIXNUM} - Height of the client area measured in pixels

This value also specifies the minimum height of the dialog shell.

:margin {FIXNUM [3]}

Space (in pixels) between the border of the client area and its child controls. See here for a visual explanation of this property.

:spacing {FIXNUM [2]} - See here

Spacing of the controls in client area.

:cellSize {GPNT2D [10,10]}

This value specifies the size of each cell of the grid. The default grid cell is 10 pixels wide and 10 pixels high.
Modifying this value allows you to have a finer or coarser grid raster. A grid cell does not have to be of square shape, you can easily pass different values for the cell width and height to have rectangular shaped cells.

Return Value:

t - success

nil - failure

Example:

(sd-create-resizable-dialog-shell "RESIZABLE-DLG-SHELL"
      :title    "Resizable Dialog Shell"
      :width    300
      :height   300
      :spacing  0
      :cellSize 10,11)

See also:

• Full Example
• sd-create-resizable-grid-area
• sd-create-splitter-control
• sd-set-control-binding
• Specific Dialog Shell Utility Functions
• Generic UI Control Utility Functions

SD-APPEND-AREA  [function]

(sd-append-area name
                parent
                :title             title
                :frame             frame-flag
                :margin            margin)

Description:

Appends an area (of no size) to an existing parent area.

Parameters:

name {STRING} - Name of this area used as handle

parent {STRING} - Parent area name

:title {STRING or NIL [nil]} - Optional title to appear on the top left border of the area

:frame {BOOLEAN [nil]} - Optional frame (border) around the area

:margin {FIXNUM [3]}

Space (in pixels) between the border of the area and its children areas or grid areas. A value greater than 0 is useful if the children areas employ a frame and/or title. See here for a visual explanation of this property.

Return Value:

t - success

nil - failure

Example:

(sd-append-area "UICT-TEST-1-AA" "UICT-TEST-AA"
      :frame            t
      :title            "Area 1"
      :margin           5)

See also:

• Area Concept
• Generic UI Control Utility Functions

SD-APPEND-GRID-AREA  [function]

(sd-append-grid-area name
                     parent
                     :title             title
                     :frame             frame-flag
                     :width             width
                     :height            height
                     :cellSize          cell-size
                     :margin            margin
                     :spacing           spacing)

Description:

Appends a grid area to an existing parent area. A grid area can be used as parent for further user interface controls like push buttons, text input fields and so on.

Parameters:

name {STRING} - Name of the grid area used as handle

parent {STRING} - Name of parent area

:title {STRING or NIL [nil]} - Optional title to appear on the top left border of the grid area

:frame {BOOLEAN [nil]} - Optional frame (border) around the grid area

:width {FIXNUM} - Width of the grid area measured in pixels

:height {FIXNUM} - Height of the grid area measured in pixels

:cellSize {GPNT2D [10,10]}

This value specifies the size of each cell of the grid. The default grid cell is 10 pixels wide and 10 pixels high.
Modifying this value allows you to have a finer or coarser grid raster. A grid cell does not have to be of square shape, you can easily pass different values for the cell width and height to have rectangular shaped cells.
The first value of this 2D vector (GPNT2D) describes the width of each grid cell (x value) and the second value of this 2D vector determines the height of each grid cell (y value).
See here for a visual explanation of this property.
Use sd-get-default-grid-size to retrieve the grid size which fits best to your current Windows session.

:margin {FIXNUM [3]} - See here

:spacing {FIXNUM [2]} - See here

Return Value:

t - success

nil - failure

Example:

(sd-append-grid-area "UICT-TEST-11-GA" "UICT-TEST-1-AA"
      :frame            t
      :title            "Grid Area 11"
      :width            120
      :height           70
      :cellSize         12,12)

See also:

• Grid Area Concept
• Generic UI Control Utility Functions

SD-APPEND-NEWLINE  [function]

(sd-append-newline parent)

Description:

Areas and grid areas are appended to its parent from left to right. If you want to continue with appending the next area or grid area in the next row of the parent, you have to call this function.

Parameters:

parent {STRING} - Name of the parent area

Return Value:

t - success

nil - failure

Example:

(sd-append-grid-area "UICT-TEST-11-GA" "UICT-TEST-1-AA"
      :frame            t
      :title            "Grid Area 11"
      :width            120
      :height           70
      :cellSize         12,12)

(sd-append-newline "UICT-TEST-1-AA")

(sd-append-grid-area "UICT-TEST-12-GA" "UICT-TEST-1-AA"
      :frame t
      :title "Grid Area 12"
      :spacing 1
      :margin 4
      :cellSize 10,12
      :width 130
      :height 150)

See also:

• Area Concept

SD-CREATE-GRID-AREA  [function]

(sd-create-grid-area name
                     parent
                     :title             title
                     :frame             frame-flag
                     :x                 x-coordinate
                     :y                 y-coordinate
                     :width             width
                     :height            height
                     :cellSize          cell-size
                     :margin            margin
                     :spacing           spacing)

Description:

This function is almost the same as sd-append-grid-area except it does not append this grid area to a parent area - it creates the new grid area as child of the passed parent grid area (for an explanation on area and grid area see here).
Note: The parent of this grid area must be an existing grid area.

Parameters:

name {STRING} - Name of grid area used as handle

parent {STRING} - Name of the parent grid area

:title {STRING or NIL [nil]} - Optional title to appear on the top left border of the grid area

:frame {BOOLEAN [nil]} - Optional frame (border) around the grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM} - Width of the grid area measured in parent grid units

:height {FIXNUM} - Height of the grid area measured in parent grid units

:cellSize {GPNT2D [10,10]} - See here

:margin {FIXNUM [3]} - See here

:spacing {FIXNUM [2]} - See here

Return Value:

t - success

nil - failure

Example:

(sd-create-grid-area "UICT-TEST-21-GA" "UICT-TEST-2-GA"
      :title     "Grid 21"
      :frame     t
      :x         0
      :y         4
      :cellSize  9,8
      :margin    5
      :spacing   2
      :width     10
      :height    6)

See also:

• Grid Area Concept
• Generic UI Control Utility Functions

SD-CREATE-SCROLLED-GRID-AREA  [function]

(sd-create-scrolled-grid-area name
                              parent
                              :x            x-coordinate
                              :y            y-coordinate
                              :width        width
                              :height       height
                              :gridWidth    grid-width
                              :gridHeight   grid-height
                              :cellSize     cell-size
                              :margin       margin
                              :spacing      spacing)

Description:

This function is almost the same as sd-create-grid-area except it offers the possibility to define a client area that differs in size from the visible part of the area. A horizontal and/or vertical scroll bar enables the user to scroll over the client area.

Parameters:

name {STRING} - Name of grid area used as handle

parent {STRING} - Name of the parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of the visible part of the grid area measured in parent grid units

:height {FIXNUM[2]} - Height of the visible part of the grid area measured in parent grid units

:gridWidth {FIXNUM [10]} - Horizontal number of cells in client area

:gridHeight {FIXNUM [10]} - Vertical number of cells in client area

:cellSize {GPNT2D [10,10]}

Size of each client area cell. See here for more information. The three parameters :cellSize, :gridWidth and :gridHeight determine the physical size of the client area. Using the default values for these parameters, the client area will be 100x100 pixels.

:margin {FIXNUM [3]} - See here

:spacing {FIXNUM [2]} - See here

Return Value:

t - success

nil - failure

Example:

 (sd-create-scrolled-grid-area "UICT-TEST-41-GA" "UICT-TEST-4-GA"
          :x  0
          :y  11
          :width  17
          :height 8
          :gridWidth 20
          :gridHeight 16
          :margin 3
          :cellSize 12,12
          :spacing 2)

See also:

• Grid Area Concept
• Specific Scrolled Grid Area Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-RESIZABLE-GRID-AREA  [function]

(sd-create-resizable-grid-area name parent
                               :title        title
                               :frame        frame-flag
                               :x            x-coordinate
                               :y            y-coordinate
                               :width        width
                               :height       height
                               :cellSize     cell-size
                               :margin       margin
                               :spacing      spacing)

Description:

Creates a grid area which can be resized and which propagates the size change to its immediate children. A child control needs to define a binding relative to its parent in order to adjust its size and position accordingly.

Only a resizable grid area itself can be the parent of a resizable grid area. This implies that only resizable dialog shells can host resizable grid areas in their widget tree.

Parameters:

name {STRING} - Name of resizable grid area used as handle

parent {STRING} - Name of the parent grid area which must be a resizable grid area

:title {STRING or NIL [nil]} - Optional title to appear on the top left border of the grid area

:frame {BOOLEAN [nil]} - Optional frame (border) around the grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM} - Width of the grid area measured in parent grid units

:height {FIXNUM} - Height of the grid area measured in parent grid units

:cellSize {GPNT2D [10,10]} - See here

:margin {FIXNUM [3]} - See here

:spacing {FIXNUM [2]} - See here

Return Value:

t - success

nil - failure

Example:

 (sd-create-resizable-grid-area "RESIZABLE-GRID-AREA-RG" "PARENT-RG"
   :title "Resizable Grid Area"
   :frame t
   :margin 5
   :spacing 2
   :cellSize 12,12
   :width 100
   :height 50
   :x 0
   :y 0)
    
 (oli:sd-set-control-binding "RESIZABLE-GRID-AREA-RG" '(:resize-both))

See also:

• Grid Area Concept
• sd-create-resizable-dialog-shell
• sd-create-splitter-control
• sd-set-control-binding

SD-CREATE-SPLITTER-CONTROL  [function]

(sd-create-splitter-control name parent
                            :horizontal   horizontal-p
                            :x            x-coordinate
                            :y            y-coordinate
                            :width        width
                            :height       height
                            :cellSize     cell-size
                            :margin       margin
                            :spacing      spacing)

Description:

A splitter control provides two panes which are either horizontally or vertically separated from each other. Each pane provides a resizable grid area which may host UICT controls. The name of the left pane is name-LEFT-PANE-RG and name of the right pane is name-RIGHT-PANE-RG, respectively. The space provided for the panes can be changed by moving the splitter.

A child control of the panes needs to define a binding relative to its parent in order to adjust its size and position accordingly.

Only a resizable grid area itself can be the parent of a splitter control. This implies that only resizable dialog shells can host splitter controls in their widget tree.

Parameters:

name {STRING} - Name of splitter control used as handle

parent {STRING} - Name of the parent grid area which must be a resizable grid area

:horizontal {BOOLEAN [t]} - Defines the orientation of the splitter

:x {FIXNUM [0]} - X coordinate within parent grid area

:y {FIXNUM [0]} - Y coordinate within parent grid area

:width {FIXNUM} - Width of the splitter control measured in parent grid units

:height {FIXNUM} - Height of the splitter control measured in parent grid units

:cellSize {GPNT2D [10,10]} - Cell size applied to both panes

:margin {FIXNUM [3]} - Margin applied to both panes

:spacing {FIXNUM [2]} - Spacing applied to both panes

Return Value:

t - success

nil - failure

Example:

  (sd-create-splitter-control
    "SPLITTER-CONTROL-SP"
    "SPLITTER-DIALOG-RG"
    :horizontal t
    :margin 0
    :x 0
    :y 0
    :width 400
    :height 300
    :cellSize 1,1
    :spacing 0)

  (oli:sd-set-control-binding "SPLITTER-CONTROL-SP" '(:resize-both))

See also:

• Full Example
• Grid Area Concept
• sd-set-control-binding
• sd-create-resizable-dialog-shell
• sd-create-resizable-grid-area

SD-CREATE-TAB-CONTROL  [function]

(sd-create-tab-control name
                       parent
                       :x                 x-coordinate
                       :y                 y-coordinate
                       :width             width
                       :height            height
                       :verticalTabs      vertical-tabs-flag
                       :verticalTabSize   vertical-tab-size
                       :tabChangedAction  tab-changed-action)

Description:

This function creates the basis of a tab control. A tab control is analogous to the dividers in a notebook or the labels in a file cabinet. To add pages to the tab control, use the function sd-insert-tab-control-page (see below).
If the tab control contains more pages than available space to present the tabs, little scroll buttons appear in the top right corner of the tab control to give access to tabs which are currently not visible. Alternatively you can create the tab control with vertical tabs which are presented as selectable items in a list. That way, more tabs are accessible without scrolling.
Note: The parent of this tab control must be an existing grid area.

Parameters:

name {STRING} - Name of tab control used as handle

parent {STRING} - Name of the parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM} - Total width of the tab control measured in parent grid units including space for horizontal or vertical tabs

:height {FIXNUM} - Total height of the tab control measured in parent grid units including space for horizontal or vertical tabs

:verticalTabs {BOOLEAN [nil]}

Set this parameter to t to make the page-access tabs appear in a list on the left side of the main tab page area.
Note: In this mode, the parent grid area should have a grid spacing of 0 or 1.

:verticalTabSize {NUMBER or sizing instructions}

If :verticalTabs is set to t, this parameter describes how wide the vertical tab list should be.
You have two options to specify the width:

• Fixed width {NUMBER}
  Pass a number for this parameter. This number is the width of the vertical tab list measured in parent grid units.
  Note, that the width which is left to display the page contents is equal to the total width given for this tab control (sd-create-tab-control) minus the width for the vertical tabs. Tab titles which are wider than the list width cause the appearance of a horizontal scrollbar.
• Variable width {sizing instructions}
  If you pass appropriate sizing instructions for this parameter, the width of the vertical tab list is calculated depending on the tab title length of the added pages. The list will be as wide as the widest tab title so that there is no need for horizontal scrolling. This feature is especially useful if you support tab titles of unknown length, e.g. localized strings.
  The sizing instructions given here describe how depended controls should behave when the vertical tab list becomes wider or smaller to make the UI look good. You have three possibilities:
  • Move - Controls of the move list will change their x coordinate according to the adjusted width of the vertical tab list. The width of the move list controls is maintained.
  • Stretch - Controls given in the stretch list will maintain their x coordinate but change their width according to the adjusted vertical tab list.
  • Spread - Controls in the spread lists behave like this: The first control in each list maintains its x coordinate. The last item of each list maintains its relative right position based on the width change of the vertical tab list. The x coordinates and widths of all other controls of each spread list is adapted in a way that the width change amout is equally spread so that their relative x coordinates and widths are maintained.
  The syntax of these sizing instruction lists is as follows:

   '(:move {List of controls to be moved}
     :stretch {List of controls to be stretched}
     :spread {List of {List of controls that spread}})
  

  Notes:
  • Controls specified in these lists should exist before you insert the first tab page.
  • Controls you add to dependent controls (members of the sizing instruction lists) should be added before you insert the first tab page, otherwise the coordinates and/or sizes of those dependent controls have been tweaked already.
  • The width which is available for the page display is equal to the total width of the tab control (sd-create-tab-control) minus 8 grid units.

  See the example below for further clarification.

:tabChangedAction {function symbol}

This (global) function is called when the user activates a page interactively or programmatically via sd-set-current-tab-control-page. This function has to accept exactly one parameter. On call, the page name as given in sd-insert-tab-control-page is passed to this fuction.

Return Value:

t - success

nil - failure

Examples:

(sd-create-tab-control "UICT-TEST-51-TC" "UICT-TEST-5-GA"
      :x           0
      :y           0
      :width       20
      :height      12)

Vertical Tabs Example

See also:

• Specific Tab Control Utility Functions
• Generic UI Control Utility Functions

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

(sd-insert-tab-control-page name
                            parent
                            :tabTitle          tab-title
                            :title             title
                            :frame             frame-flag
                            :cellSize          cell-size
                            :margin            margin
                            :spacing           spacing)

Description:

Use this function to add pages to a tab control created by sd-create-tab-control. Each page is represented by a tab with a tabTitle. Click this tab to toggle between different pages of a tab control.
The client area of a page is a grid area with or without a frame and/or title. Its size is automatically determined by the size of the parent tab control.
The name of the page grid area is

'name'-TAB-GA

Use this name as parent for all controls which should become children of this tab control page.
For more information on grid areas see here.
Note: The parent of this tab control page must be an existing tab control.

Parameters:

name {STRING} - Name of tab control page used as handle

parent {STRING} - Name of the parent tab control

:tabTitle {STRING} - Title to appear on the tab representing this page

:title {STRING or NIL [nil]}

Optional title to appear on the top left border of the page (grid area title)
(not supported if tab control has been created with :verticalTabs = t)

:frame {BOOLEAN [nil]}

Optional frame (border) around the page (grid area)
(not supported if tab control has been created with :verticalTabs = t)

:cellSize {GPNT2D [10,10]} - See here

:margin {FIXNUM [3]} - See here

:spacing {FIXNUM [2]} - See here

Return Value:

t - success

nil - failure

Examples:

(sd-insert-tab-control-page "UICT-TEST-51-PAGE2" "UICT-TEST-51-TC"
      :tabTitle "Page 2 with Frame"
      :frame    t
      :title    "Title"
      :cellSize 10,10
      :spacing  2
      :margin   2)

(sd-create-togglebutton-control "UICT-TEST-51-PAGE2-1-TB" "UICT-TEST-51-PAGE2-TAB-GA"
      :x  0
      :y  0
      :width 8
      :height 2
      :indicator :check
      :title  "Button 1"
      :pushAction  ":button1_of_page2")

Vertical Tabs Example

See also:

• Grid Area Concept
• Specific Tab Control Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-PUSHBUTTON-CONTROL  [function]

(sd-create-pushbutton-control name
                              parent
                              :x              x-coordinate
                              :y              y-coordinate
                              :width          width
                              :height         height
                              :pushAction     push-action
                              :title          title
                              :alignment      title-alignment
                              :image          image
                              :disabledImage  disabled-image)

Description:

Creates a push button control within the parent grid area.

Parameters:

name {STRING} - Name of push button control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of push button control measured in parent grid units

:height {FIXNUM [2]} - Height of push button control measured in parent grid units

:pushAction {quoted LISP-Form or STRING} - Action to take place as soon as the user hits the push button control

:title {STRING [" "]} - Title to be shown on the push button control

:alignment {KEYWORD [:center]} - Alignment of push button control title

:image {STRING} - Image to be shown instead of title

:disabledImage {STRING} - Image to be shown in case the button is disabled

Return Value:

t - success

nil - failure

Example:

(sd-create-pushbutton-control "UICT-TEST-122-PB" "UICT-TEST-12-GA"
      :x           10
      :y           0
      :width       10
      :height      2
      :title       "Test 122"
      :pushAction  '(format t "~%Test 122 pushed"))

See also:

• Generic UI Control Utility Functions

SD-CREATE-TOGGLEBUTTON-CONTROL  [function]

(sd-create-togglebutton-control name
                                parent
                                :x                      x-coordinate
                                :y                      y-coordinate
                                :width                  width
                                :height                 height
                                :indicator              indicator-type
                                :pushAction             push-action
                                :releaseAction          release-action
                                :title                  title
                                :alignment              title-alignment
                                :image                  image
                                :disabledImage          disabled-image
                                :selectedImage          selected-image
                                :disabledSelectedImage  disabled-selected-image)

Description:

Creates a toggle button control within the parent grid area.

Parameters:

name {STRING} - Name of toggle button control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of toggle button control measured in parent grid units

:height {FIXNUM [2]} - Height of toggle button control measured in parent grid units

:indicator {KEYWORD [:check]}

Can be one of the following keywords:

• :check - used for N of Many toggle button types
• :radio - used for One of Many toggle button types
• :none - creates a toggle button which looks like a regular push button but has two states: pressed and depressed

:pushAction {quoted LISP-Form or STRING}

Action to take place as soon as the user clicks the depressed (checks the) toggle button control

:releaseAction {LISP-Form}

Action to take place as soon as the user clicks the pressed (unchecks the) toggle button control

:title {STRING [" "]} - Title to be shown on the toggle button control

:alignment {KEYWORD [:center]} - Alignment of toggle button control title

:image {STRING} - Image to be shown instead of title

:disabledImage {STRING} - Image to be shown in case the button is disabled

:selectedImage {STRING} - Image to be shown instead of title in case the toggle button is selected

:disabledSelectedImage {STRING} - Image to be shown instead of title in case the toggle button is selected and disabled

Return Value:

t - success

nil - failure

Example:

(sd-create-togglebutton-control "UICT-TEST-111-TB" "UICT-TEST-11-GA"
      :title          "Toggle 111"
      :x              0
      :y              0
      :width          10
      :height         2
      :indicator      :check
      :pushAction     '(format t "~%Toggle 111 pushed")
      :releaseAction  '(format t "~%Toggle 111 released"))

See also:

• Specific Toggle Button Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-COLORBUTTON-CONTROL  [function]

(sd-create-colorbutton-control name
                               parent
                               :x             x-coordinate
                               :y             y-coordinate
                               :width         width
                               :height        height
                               :displayOnly   display-only-flag
                               :pushAction    push-action)

Description:

Creates a color button control within the parent grid area. The color button can be used as a push button control or as a display only control.
The color of the color button control can be set with sd-set-colorbutton-color.

Parameters:

name {STRING} - Name of color button control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of color button control measured in parent grid units

:height {FIXNUM [2]} - Height of color button control measured in parent grid units

:displayOnly {BOOLEAN [nil]}

Flag to indicate whether this control should be used as push button (default) or as display only control

:pushAction {quoted LISP-Form or STRING}

Action to take place as soon as the user hits the color button control (only valid if :displayOnly is set to nil).

Return Value:

t - success

nil - failure

Example:

(sd-create-colorbutton-control "UICT-TEST-128-CB" "UICT-TEST-12-GA"
      :x            20
      :y            0
      :width        6
      :height       2
      :displayOnly  t)

See also:

• Specific Color Button Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-SEPARATOR-CONTROL  [function]

(sd-create-separator-control name
                             parent
                             :x            x-coordinate
                             :y            y-coordinate
                             :width        width
                             :height       height)

Description:

Creates a horizontal separator control within the parent grid area. This control is useful to separate visually groups of other controls within the same grid area without the need to use extra grid areas with frames and titles.
The color of the control is determined by its parent grid area.
Note: Even if you enlarge the height of the control the visual separator line is always centered in the separator control. The height of the line is fixed.

Parameters:

name {STRING} - Name of separator control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of separator control measured in parent grid units

:height {FIXNUM [2]} - Height of separator control measured in parent grid units

Return Value:

t - success

nil - failure

Example:

(sd-create-separator-control "UICT-TEST-51-PAGE1-1-SE" 
                             "UICT-TEST-51-PAGE1-TAB-GA"
      :x       0
      :y       2
      :width   18
      :height  1)

See also:

• Generic UI Control Utility Functions

SD-CREATE-LABEL-CONTROL  [function]

(sd-create-label-control name
                         parent
                         :x            x-coordinate
                         :y            y-coordinate
                         :width        width
                         :height       height
                         :title        title
                         :alignment    title-alignment
                         :image        image)

Description:

Creates a static label control within the parent grid area.

Parameters:

name {STRING} - Name of label control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of label control measured in parent grid units

:height {FIXNUM [2]} - Height of label control measured in parent grid units

:title {STRING [" "]} - Title to be shown on the label control

:alignment {KEYWORD [:center]} - Alignment of label control title

:image {STRING} - Image to be shown instead of title

Return Value:

t - success

nil - failure

Example:

(sd-create-label-control "UICT-TEST-112-LB" "UICT-TEST-11-GA"
      :title      "Label 112"
      :x          0
      :y          2
      :width      8
      :height     2
      :alignment  :left)

See also:

• Generic UI Control Utility Functions

SD-CREATE-TEXT-CONTROL  [function]

(sd-create-text-control name
                        parent
                        :x                    x-coordinate
                        :y                    y-coordinate
                        :width                width
                        :height               height
                        :editable             editable-flag
                        :multiline            multiline-flag
                        :autoWrap             auto-wrap-flag
                        :showModified         show-modified-flag
                        :enterAction          enter-action
                        :setFocusAction       set-focus-action
                        :modifyAction         modify-action
                        :killFocusAction      kill-focus-action
                        :range                range-list
                        :autoAdd              auto-add-flag
                        :enterActionAfterRangeSelection
                                              enter-action-after-range-selection-flag
                        :maxRangeCount        max-range-count
                        :maxVisibleRangeCount max-visible-range-count)

Description:

Creates a single or multiline text control within the parent grid area. This text control can be editable or not.
An editable singleline text control may have a range that is initialized by a range-list. Strings entered in the text control are added to the beginning of the text range.

Parameters:

name {STRING} - Name of text control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of text control measured in parent grid units

:height {FIXNUM [2]} - Height of text control measured in parent grid units

:editable {BOOLEAN [t]} - Indicates whether the text field is editable for the user or not

:multiline {BOOLEAN [nil]} - Single or multiline text control

:autoWrap {BOOLEAN [nil]}

Valid for :multiline text controls only. If this parameter is set to t, the entered text wraps automatically to the new line if the user hits the right border of the text control.
Note: No Newline is added to the string itself. The string is still one long string without newline characters.

:showModified {BOOLEAN [nil]}

If this flag is set for editable text controls, the text control background turns to its highlight color as soon as the user starts typing into the text control. To get rid of the yellow background you have to set a valid text control value (as :enterAction for instance) using the function sd-set-text-control-value.

:enterAction {quoted LISP-Form or STRING}

Action to take place as soon as the user hits the Enter key in single line text controls. This action will never be called for multiline text controls.

:setFocusAction {quoted LISP-Form or STRING}

Action which will be executed when the text control gets the keyboard focus.

:killFocusAction {quoted LISP-Form or STRING}

Action which will be executed when the text control looses the keyboard focus (Tab key or mouse click on a different control).

:modifyAction {quoted LISP-Form or STRING}

Action which will be executed when the text control's contents is about to be changed.

:range {LIST [nil]}

Initial list of string items displayed by the text range. This range changes when strings are entered in the text control if :autoAdd is set to T.

:autoAdd {BOOLEAN [t]}

If set, new items will automatically be added to the text range.

:enterActionAfterRangeSelection {BOOLEAN [nil]}

If this flag is set to t, a selection in the text range causes the execution of the enter action, too.

:maxRangeCount {FIXNUM [20]}

Maximum number of string items that can be stored in the text range. The last item in the range is removed if a new item is added to the beginning of the range with already containing maxRangeCount items.

:maxVisibleRangeCount {FIXNUM [5]}

Maximum number of string items that can be displayed in the text range without using a scroll bar.

Return Value:

t - success

nil - failure

Example:

(sd-create-text-control "UICT-TEST-125-TX" "UICT-TEST-12-GA"
      :x             0
      :y             4
      :width         20
      :height        5
      :editable      t
      :showModified  nil
      :autoWrap      nil
      :multiline     t)

See also:

• Specific Text Control Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-RANGE-CONTROL  [function]

(sd-create-range-control name
                         parent
                         :x                 x-coordinate
                         :y                 y-coordinate
                         :width             width
                         :height            height
                         :alignment         item-alignment
                         :range             range-list
                         :selectionAction   selection-action)

Description:

Creates a range control within the parent grid area.

Parameters:

name {STRING} - Name of range control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of range control measured in parent grid units

:height {FIXNUM [2]} - Height of range control measured in parent grid units

:alignment {KEYWORD [:left]} - Alignment of range control item titles

:range {LIST}

List of items to appear as choices on the range popup menu. The form of this list is
'(ItemA ItemB ItemC ...)
where ItemX could be either

1. A string, number, symbol or keyword or
2. A list like this (ItemX :title "Item X") or
3. A list like this (ItemY :color "color" :title "Item Y")
4. A list like this (ItemZ :image "Item-Z-Image")

In case 1. the string, number, symbol or keyword appears as title on the choice button. Case 2. allows you to specify a different title to appear than the choice value (first item in list) (see :selectionAction). Case 3. displays a colored rectangle left of the title. In case 4. you can visualize a choice with an image instead of a title string.

:selectionAction {Function Symbol}

This (global) function gets called when the user selects a choice of the range. This function has to accept exactly one parameter. On call, the value of the selected choice gets assigned to this parameter automatically. This value is either the string, number, symbol or keyword of ItemX or the first item of the list in case the item was specified with :title or :image option. See :range parameter for more information.

Return Value:

t - success

nil - failure

Example:

(defun range-test-26-callback (value)
  (format t "~%Range UICT-TEST-26-RA callback value: ~S  Type: ~S"
            value
            (type-of value)))

(sd-create-range-control "UICT-TEST-26-RA" "UICT-TEST-2-GA"
      :x                10
      :y                8
      :width            10
      :height           2
      :alignment        :center
      :selectionAction  'range-test-26-callback
      :range            '("A" 
                          (:b :title "Beta")
                          (0xff :color "#ff0000" :title "Red")
                          3
                          ("D" :image "Error-Icon")
                          (5 :title "Fifth item")))

See also:

• Specific Range Control Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-LIST-CONTROL  [function]

(sd-create-list-control name
                        parent
                        :x                 x-coordinate
                        :y                 y-coordinate
                        :width             width
                        :height            height
                        :itemHeight        item-height
                        :alignment         item-alignment
                        :selectionMode     selection-mode
                        :items             item-list
                        :selectionAction   selection-action
                        :doubleClickAction double-click-action)

Description:

Creates a list control within the parent grid area. If the list control displays more items than visible screen space, a vertical scrollbar appears automatically.

Parameters:

name {STRING} - Name of list control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of list control measured in parent grid units

:height {FIXNUM [2]} - Height of list control measured in parent grid units

:itemHeight {KEYWORD [:default] or FIXNUM}

Determines the height in pixels of a single list item. The system default height will be used if the keyword :default is specified.

:alignment {KEYWORD [:left]} - Alignment of list control items

:selectionMode {KEYWORD [:single]}

Determines whether the user is allowed to select just one item (pass :single) or multiple items at a time (pass :multiple)

:items {LIST}

List of items to be displayed in the list control. The single items can be of type string, number, symbol or keyword.

:selectionAction {quoted LISP-Form or STRING}

Action to take place as soon as the user selects one (or more in case of :selectionMode set to :multiple) item(s). Use the function sd-get-list-control-selected-items to retrieve the selected items.

:doubleClickAction {quoted LISP-Form or STRING}

Action to take place as soon as the user doubleclicks one (or more in case of :selectionMode set to :multiple) item(s)

Return Value:

t - success

nil - failure

Example:

(sd-create-list-control "UICT-TEST-31-LI" "UICT-TEST-3-GA"
      :x                  0
      :y                  0
      :width              10
      :height             8
      :selectionAction    '(progn
                             (format t "~%Single selection callback")
                             (format t "~%  Selected items: ~S"
                                       (sd-get-list-control-selected-items
                                                           "UICT-TEST-31-LI")))
      :doubleClickAction  '(format t "~%Double selection callback")
      :selectionMode      :multiple
      :items              '("Item 1" "Item No. 2" 3 4 :item_5 "Item 6"))

See also:

• Specific List Control Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-DISPLAY-TABLE-CONTROL  [function]

(sd-create-display-table-control name
                                 parent
                                 :x                     x-coordinate
                                 :y                     y-coordinate
                                 :width                 width
                                 :height                height
                                 :logicalTable          logical-table
                                 :columns               column-keywords
                                 :entryAlignment        entry-alignment
                                 :formatFunctions       format-functions
                                 :selectionAction       selection-action
                                 :applyColumns          apply-columns
                                 :keyColumnsApplyToken  apply-token
                                 :keyColumnsApplyUnits  apply-units
                                 :selectionMode         selection-mode
                                 :applyAction           apply-action
                                 :doubleClickAction     double-click-action
                                 :afterEditAction       after-edit-action
                                 :editCellCheckFunction check-function)

Description:

Creates the table portion of a Display Table within the parent grid area.

Parameters:

name {STRING} - Name of display table control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of display table control measured in parent grid units

:height {FIXNUM [2]} - Height of display table control measured in parent grid units

:logicalTable {STRING} - Same as for sd-create-display-table

:columns {LIST of KEYWORDs} - Same as for sd-create-display-table

:entryAlignment {LIST of KEYWORDs} - Same as for sd-create-display-table

:formatFunctions {LIST of SYMBOLs} - Same as for sd-create-display-table

:selectionAction {Function Symbol} - Same as for sd-create-display-table

:applyColumns {LIST of KEYWORDs} - Same as for sd-create-display-table

:keyColumnsApplyToken {KEYWORD} - Same as for sd-create-display-table

:keyColumnsApplyUnits {KEYWORD [:external]} - Same as for sd-create-display-table

:selectionMode {KEYWORD [:single-row]} - Same as for sd-create-display-table

:applyAction {KEYWORD or LISP-Form [:default-tokens]} - Same as for sd-create-display-table

:doubleClickAction {KEYWORD or function} - Same as for sd-create-display-table

:afterEditAction {KEYWORD or function} - Same as for sd-create-display-table

:editCellCheckFunction {function} - Same as for sd-create-display-table

Return Value:

t - success

nil - failure

Example:

(sd-create-logical-table
 "Example-Table"
 :columns     '(:first   :second     :third       :untyped :fifth    :sixth)
 :columnNames '("String" "Angle"     "Length"     nil      "Mass"    "Number")
 :keyColumns  '(:second :third)
 :secured     nil
 :types       '(:string :angle       :length      nil      :mass      :number)
 :units       '(nil     :deg         :mm          nil      :kg        nil)
 :contents  '(("Eric"   (17.2 :deg)  (2 :inch)    :test105 (42 :kg)   000)
              ("Alf"    0.57         22.4         :bla     23.6       111)
              ("Willie" 1.673        (143.85 :mm) "Eric"   62.3       222)
              ("Lynn"   (33.33 :deg) (0.5 :km)    105      (17.5 :kg) 333)
              ("Kate"   2.222        (422.2 :mm)  'hugo    (23.5 :mg) 444)
              ("Brian"  3.1415       65.5         15       345.85     555)
              ("Jake"   1.2354       (15.6 :mm)   :foo     42.5       666)
              ("Raquel" 0.03745      (99.89 :mm)  :zip     234.645    777)
              ("Bill"   0.8765       (126 :mm)    :bar     0.42       888)))

(defun example-table-selection-action (table)
  (format t "~%Row selected in table ~S." table))

(sd-create-display-table-control "UICT-TEST-41-DT" "UICT-TEST-4-GA"
      :x                    0
      :y                    0
      :width                27
      :height               11
      :logicalTable         "Example-Table"
      :columns              '(:first :second :third :fifth :sixth)
      :entryAlignment       '(:left :right :right :right :left)
      :formatFunctions      '(nil sd-display-table-format-3-digits nil)
      :applyColumns         '(:first :third)
      :applyAction          :default-tokens
      :keyColumnsApplyToken :keyValues
      :selectionMode        :single-row
      :selectionAction      'example-table-selection-action)

See also:

• sd-create-display-table
• Generic UI Control Utility Functions

SD-CREATE-SLIDER-CONTROL  [function]

(sd-create-slider-control name
                          parent
                          :x                   x-coordinate
                          :y                   y-coordinate
                          :width               width
                          :height              height
                          :minValue            min-value
                          :maxValue            max-value
                          :increment           increment
                          :decimalPoints       decimal-points
                          :orientation         orientation
                          :showValue           show-value-flag
                          :minLeftTop          min-left-top-flag
                          :dragAction          drag-action
                          :valueChangedAction  change-action)

Description:

Creates a horizontal or vertical slider control within the parent grid area.

Parameters:

name {STRING} - Name of slider control used as handle

parent {STRING} - Name of parent grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM [5]} - Width of slider control measured in parent grid units

:height {FIXNUM [2]} - Height of slider control measured in parent grid units

:minValue {FIXNUM [0]} - Minimum value of slider

:maxValue {FIXNUM [100]} - Maximum value slider

:increment {FIXNUM [10]}

Value to increment or decrement the slider value if the user picks into the empty slider area to the right or left of the slider thumb

:decimalPoints {FIXNUM [0]}

Specifies the number of decimal points to shift the slider value when displaying it. For example a slider value of 93 and a value of 2 for :decimalPoints results in a display value of 0.93.

:orientation {KEYWORD [:horizontal]}

Determines the display orientation of the slider. Pass :horizontal to see a horizontal oriented slider, pass :vertical to see a vertical oriented slider.

:showValue {BOOLEAN [t]}

Specifies whether a label for the current slider value should be displayed next to the slider or not.

:minLeftTop {BOOLEAN [t]}

Flag whether the minimum slider value should be on the left for horizontal sliders or on top for vertical sliders or the other way around.

:dragAction {quoted LISP-Form or STRING}

Action which gets executed whenever the user drags the slider thumb. Use sd-get-slider-control-value to get the current slider value.

:valueChangedAction {quoted LISP-Form or STRING}

This action is called when the user finishes a slider drag or clicked to the left or right of the slider thumb. Use sd-get-slider-control-value to get the current slider value.

Return Value:

t - success

nil - failure

Example:

(sd-create-slider-control "UICT-TEST-34-SL" "UICT-TEST-3-GA"
      :x                   18
      :y                   0
      :width               4
      :height              8
      :minValue            0
      :maxValue            50
      :increment           5
      :decimalPoints       0
      :orientation         :vertical
      :showValue           t
      :minLeftTop          t
      :dragAction          '(format t "~%Slider drag callback")
      :valueChangedAction  '(format t "~%Slider value changed callback"))

See also:

• Specific Slider Control Utility Functions
• Generic UI Control Utility Functions

SD-CREATE-CONTEXT-MENU  [function]

(sd-create-context-menu name
                        parent
                        :title        title
                        :contents     contents-list)

Description:

Creates a context menu for a specific control. To access this context menu the user has to click the right mouse button over the parent control.
The context menu can contain simple push buttons, toggle buttons, separators and further cascading menus which itself may contain further controls and submenus.
Restriction: This function is only supported when parent is of type

• push button control,
• toggle button control,
• edit control, or
• list control.

Parameters:

name {STRING} - Name of context menu used as handle

parent {STRING} - Name of the parent control to which this context menu is assigned to

:title {STRING or NIL [nil]} - Optional title of context menu to appear on top of the menu

:contents {LIST}

Description of context menu contents in the following form:
'(Entry1 Entry2 ... EntryN)
where each entry can be one of the following:

• (:pushbutton :title title :pushAction action)
• (:pushbutton :image image :pushAction action)

• (:togglebutton :title          title
                 :indicator      [either :check (default) or :radio]
                 :pushAction     push-action
                 :releaseAction  release-action)
  

• (:togglebutton :image          image
                 :selectedImage  selected-image
                 :indicator      [either :check (default) or :radio]
                 :pushAction     push-action
                 :releaseAction  release-action)
  

• (:separator)
• (:submenu :title title :contents contents)

Return Value:

t - success

nil - failure

Example:

(sd-create-context-menu "UICT-TEST-33-CX" "UICT-TEST-33-PB"
      :title "Test Popup"
      :contents
      '((:pushbutton :title       "First Item"
                     :pushAction  (format t "~%Context item 1 pushed"))
        (:pushbutton :title       "Call Extrude"
                     :pushAction  "extrude")
        (:separator)
        (:togglebutton :title          "Toggle Me"
                       :indicator      :radio
                       :pushAction     (format t "~%Context toggle pushed")
                       :releaseAction  (format t "~%Context toggle released"))
        (:submenu :title    "Submenu"
                  :contents ((:pushbutton :title       "Rectangle"
                                          :pushAction  "rectangle")
                             (:pushbutton :image       "Error-Icon"
                                          :pushAction  (sd-display-error "Hi"))
                             (:submenu :title     "Dummy Sub"
                                       :contents  ((:pushbutton)
                                                   (:separator)
                                                   (:togglebutton)))
                             (:togglebutton :image          "Option-Unpinned"
                                            :selectedImage  "Option-Pinned"
                                            :pushAction     ":on"
                                            :releaseAction  ":off")))))

See also:

• Generic UI Control Utility Functions

SD-CREATE-VIEWPORT-CONTROL  [function]

(sd-create-viewport-control name parent
                               :x            x-coordinate
                               :y            y-coordinate
                               :width        width
                               :height       height)

Description:

Creates a UI control which hosts a 3D viewport. The name of the viewport control is also used as name of the hosted 3D viewport. Consequently, name must not be used as name of another existing 3D viewport.

Only a resizable grid area can be the parent of a viewport control. The binding for the viewport control is preset to adjust size and position according to the parent grid area in both directions.

Once the viewport control has been created, the hosted 3D viewport can be accessed using most of the standard Viewport commands and name as name of the viewport. Only the commands to inquire and set window size and visibility are not supported because these propreties are controled by the UI viewport control.

Parameters:

name {STRING} - Name of viewport control and the 3D viewport hosted by the control

parent {STRING} - Name of the parent grid area which must be a resizable grid area

:x {FIXNUM [0]} - X grid coordinate within parent grid area

:y {FIXNUM [0]} - Y grid coordinate within parent grid area

:width {FIXNUM} - Width of the grid area measured in parent grid units

:height {FIXNUM} - Height of the grid area measured in parent grid units

Return Value:

t - success

nil - failure

Example:

 (sd-create-viewport-control "VIEWPORT-CONTROL" "PARENT-RG"
   :width 100
   :height 50
   :x 0
   :y 0)

See also:

• sd-create-resizable-grid-area
• Viewport commands