User Interface Utility Functions

Image Functions
- sd-create-image
- sd-destroy-image
- sd-image-p
Cursor Functions
- sd-create-cursor
- sd-set-cmd-cursor
- sd-get-current-cursor
- sd-set-current-cursor
General Text Editor Functions
- sd-show-general-text-editor
- sd-hide-general-text-editor
- sd-general-text-editor-get-value
- sd-general-text-editor-set-value
- sd-general-text-editor-insert-value
- sd-general-text-editor-set-focus
Settings Registration
- sd-register-settings
- sd-unregister-settings
Miscellaneous Functions
- sd-put-buffer
- sd-call-dialog
- sd-get-module-controller-button
- sd-insert-module-controller-button
- sd-raise-application
- sd-lower-application
- sd-minimize-application
- sd-restore-application

SD-CREATE-IMAGE [function]

(sd-create-image name
                 :filename    filename
                 :background  color)

Description:

Creates an image to be used on controls such as push or togglebuttons.
The image file must be of type BMP - Windows bitmap format (.bmp file suffix). The color of the top-left pixel of that bitmap determines the transparent color of the image. I.e. all pixels of the same color will be displayed transparent. If you want to fill these transparent pixels with a specific color, you have to pass a color value for the :background parameter.

For compatibility reasons, XPM and XBM file formats (X Windows pixmap and bitmap) are still supported. These UNIX image formats can be converted to BMP with the Shareware tool collection ImageMagick.

Parameters:

name {STRING} - Unique name to be used as handle for image
:filename {STRING}: Absolute or relative path to a file which contains the image data.
:background {STRING}: Color with which all transparent pixels will be filled. See Description for more information.

Return Value:

t - success
nil - failure

Example:

(sd-create-image "Error-Icon" :filename "d:/data/bmp/error.bmp" :background "#FF0000")

SD-DESTROY-IMAGE [function]

(sd-destroy-image name)

Description:

Destroys an image with handle name.
Note: Make sure that no control employs an image with handle name as control title anymore. Otherwise you would end up in a system error.

Parameters:

name {STRING} - Name of image to destroy

Return Value:

t - success
nil - failure

Example:

(sd-destroy-image "Error-Icon")

SD-IMAGE-P [function]

(sd-image-p name)

Description:

Predicate to indicate whether an image with handle name exists in Creo Elements/Direct Modeling or not.

Parameters:

name {STRING} - Name of an image to check

Return Value:

t - Image exists
nil - Image does not exist

Example:

(sd-image-p "Error-Icon") => t

SD-CREATE-CURSOR [function]

(sd-create-cursor cursor-name filename)

Description:

Creates a mouse cursor with name cursor-name by using the definition given in the cursor file with name filename.
Note: A cursor file (*.cur) can be created for example with Microsoft Visual Studio. There is also a huge collection located on the world wide web to download.

Parameters:

cursor-name {STRING} - The identifier for the new cursor
filename {STRING} - Filename of a cursor file relative to Creo Elements/Direct Modeling's search directories

Return Value:

t - success
nil - failure

Example:

(sd-create-cursor "DELETE2D" "bitmaps/cursor/delete2d.cur")

SD-SET-CMD-CURSOR [function]

(sd-set-cmd-cursor command cursor-name :vp-only vp-only)

Description:

Assigns a specific cursor to be used for a specific command if this command is active. As soon as the user starts this command, the cursor shape changes to the one given by cursor-name. If the command terminates, the cursor changes back to the default cursor or the previously active cursor automatically.

Note: If you call this function while the command specified as command is not active or suspended, you'll define the cursor in a static way, i.e. every instance of the command will have this cursor.
If you call this function while command is active or suspended, you'll assign the cursor just for this one (if more, then the most recent) instance of the command, i.e. if you call the same command a second time without calling this function for this command, no command specific cursor will be specified.

Parameters:

command {STRING}: Name of the command for which you set a specific cursor. The command must exist at the call time of this function.
cursor-name {STRING}: The name of the cursor which was created by sd-create-cursor. If you pass NIL for this parameter the current active cursor is reset to the default cursor.
:vp-only {BOOLEAN [t]}: Defines if the cursor should be visible in viewport(s) only or in the whole Creo Elements/Direct Modeling user interface. If you set this parameter to NIL the cursor becomes visible only if the mouse cursor is in a viewport otherwise you see the regular default cursor.

Return Value:

t - success
nil - failure

Example:

(sd-set-cmd-cursor "delete_3d" "DELETE3D" :vp-only nil)

SD-GET-CURRENT-CURSOR [function]

(sd-get-current-cursor)

Description:

Returns the current active cursor or NIL if the default cursor is current.

Parameters:

Return Value:

("cursor-name" vp-only-flag): List containing the name of the current cursor and a boolean to indicate whether the current cursor is set for viewport(s) only or for the whole Creo Elements/Direct Modeling user interface.
nil - the current cursor is the default cursor

Example:

(sd-get-current-cursor)  => ("DELETE3D" nil)

SD-SET-CURRENT-CURSOR [function]

(sd-set-current-cursor cursor-name :vp-only vp-only)

Description:

This function is given for completeness only. You should rather use the function sd-set-cmd-cursor to assign a specific cursor to a specific command.
If you use this function you change the current cursor independent of the active command. I.e. you are also responsible for resetting the cursor back to the default one. This is not done automatically if you terminate the current command or if you invoke an interrupt command.

Parameters:

cursor-name {STRING}: The name of the cursor which was created by sd-create-cursor. If you pass NIL for this parameter the current active cursor is reset to the default cursor.
:vp-only {BOOLEAN [t]}: Defines if the cursor should be visible in viewport(s) only or in the whole Creo Elements/Direct Modeling user interface. If you set this parameter to NIL the cursor becomes visible only if the mouse cursor is in a viewport otherwise you see the regular default cursor.

Return Value:

t - success
nil - failure

Example:

(sd-set-current-cursor "DELETE2D" :vp-only t)

SD-SHOW-GENERAL-TEXT-EDITOR [function]

(sd-show-general-text-editor :title           title
                             :initialText     initialText
                             :mapToggle       mapToggle
                             :closeAction     closeAction
                             :doneLabel       doneLabel
                             :doneAction      doneAction
                             :clearLabel      clearLabel
                             :clearAction     clearAction
                             :userLabel       userLabel
                             :userAction      userAction
                             :trimString      trimString
                             :resizable       resizable
                             :position        position
                             :rows            rows
                             :columns         columns
                             :externalEditor  externalEditor)

Description:

Shows the general purpose text editor on the screen. The example on the right shows a resizable text editor with an additional user button Print.
This function is useful in the context of the dialog generator to show an input tool for variables of value type :string.
If :externalEditor is set to T, Creo Elements/Direct Modeling launches an external (system) editor instead of the built-in as shown in the picture. This external editor is the same which is used to edit a file from within Creo Elements/Direct Modeling (see Edit File command under File). It can be customized via the shell variable EDITOR.

Parameters:

:title {STRING ["Text Editor" (localized)]}: The toplabel of the text editor to appear between pin and close button.
:initialText {STRING [""]} - text to display in the editor
:mapToggle {STRING}: If this toggle button widget name is passed as argument, this button will reset automatically when the user closes the text editor.
Note: This map toggle has no effect if you specify a closeAction explicitly.
:closeAction {LISP form}: Form which gets executed when the user hits the close button of the text editor located in the upper right corner.
:doneLabel {STRING ["Done" (localized)]} - Label to appear on the left button
:doneAction {LISP Form}: Action which takes place if the the hits the Done button. The default action is to pass the actual contents of the text editor to the current command, which waits for input of a string. In addition to that, the text editor closes itself.
:clearLabel {STRING ["Clear" (localized)]} - Label to appear on the right button
:clearAction {LISP Form}: Action which takes place if the the hits the Clear button. The default action is to erase all text displayed in the text editor.
:userLabel {STRING}: If you pass a string for this parameter, a third optional button will appear between the two default buttons.
:userAction {LISP Form} - action of your user button
:trimString {Boolean [t]}: If you specified the default doneAction, the resulting string which gets passed to the current command will be trimmed automatically. That means the string will not contain any leading or trailing white spaces (Space, Tab, Carriage Return).
:resizable {Boolean [nil]} - controls resizability of text editor
:position {LISP list}: Specification of screen location where the editor will appear. Same format as used in sd-show-display-table.
:rows {FIXNUM [10]} - initial number of rows displayed
:columns {FIXNUM [50]} - initial number of columns displayed
:externalEditor {Boolean [nil]}: If set to T, Creo Elements/Direct Modeling will launch the external editor (see Edit File command and shell variable EDITOR) instead of the built-in editor.

Return Value:

t - always

Example:

(sd-show-general-text-editor :initialText  "This is an example."
                             :resizable    t
                             :userLabel    "Print")

SD-HIDE-GENERAL-TEXT-EDITOR [function]

(sd-hide-general-text-editor :ignorePin ignorePin)

Description:

This function is used to hide the general text editor. Most likely used as :hide-input-tool function for variables of type :string. See dialog generator manual for more information.

Parameters:

:ignorePin {BOOLEAN [t]}: If this value is set to t then the state of the pin button of the text editor is not taken into account. That means even if the editor is pinned it will be removed from the screen.
If this value is set to nil, the text editor stays on the screen if pinned.

Return Value:

t - If the text editor was removed from the screen successfully.
nil - The text editor was pinned and ignorePin was set to nil.

SD-GENERAL-TEXT-EDITOR-GET-VALUE [function]

(sd-general-text-editor-get-value :trimString trimString)

Description:

This function returns the current value (string) of the general purpose text editor.

Parameters:

trimString {Boolean [t]} - automatic string trim (get rid of white spaces) or not

Return Value:

string - The current value of the text editor trimmed or untrimmed

SD-GENERAL-TEXT-EDITOR-SET-VALUE [function]

(sd-general-text-editor-set-value value)

Description:

This function sets the current value (string) of the general purpose text editor.

Parameters:

value {STRING} - String to display

Return Value:

t - always

SD-GENERAL-TEXT-EDITOR-INSERT-VALUE [function]

(sd-general-text-editor-insert-value value &optional position)

Description:

This function inserts a string value at a certain position into the currently displayed text editor string.

Parameters:

value {STRING} - String to insert

position {KEYWORD or FIXNUM [nil]} - optional parameter

This parameter specifies the position where to insert the passed string. If you omit a value or pass nil, the string will be inserted at the current cursor position (default).
Here a list of the other position options:

:beginning - insert before the first character
:end - append string to the existing string
FIXNUM - an absolute position in the displayed string. It should be in the range of 0 to current length of displayed string. Every other number causes the string to be appended.

Return Value:

t - always

SD-GENERAL-TEXT-EDITOR-SET-FOCUS [function]

(sd-general-text-editor-set-focus)

Description:: This function sets the input focus to the editor's text window. Subsequent keyboard input goes directly to the editor.
Parameters:: none
Return Value:: t - successful; nil - failure

SD-REGISTER-SETTINGS [function]

(sd-register-settings registration-handle
                      :subMenuTitle sub-menu-title
                      :settings settings-items)

Description:

Settings registration enables programmers to launch settings UI from Modeling's Settings submenu.

Calling this function either creates a new Settings registration if it doesn't yet exist, or it extends an existing registration. A registration is uniquely identified by its registration-handle. A registration provides access to one or more Modeling Settings items which are added to a registration by means of settings-items. A Modeling settings item is defined by its entry in the according Available Commands file. Thus ensure that Settings registration always occur after the Available Commands file was loaded. To learn more about Available Commands please read the Customization Guide for Administrators and Advanced Users.

All Settings registrations are displayed in the Settings submenu which can be reached from the Edit popup menu. The sequence of the registration determines the sequence the registrations appear in the submenu.

Restriction: Only non-Annotation settings can be registered.

Parameters:

registration-handle {STRING}

Unique string handle to identify a Settings registration.

subMenuTitle {STRING[nil]} - optional parameter

If set this title is displayed in the Settings submenu. The menu item behind opens a new submenu which shows all Settings items. Unless set all Settings items appear directly in the Settings submenu.

settings {LIST}

List of Settings items. Each item is defined by a property list which consists of an item name and the definition of an Available Command:

     '( 
        ( :itemName itemName
          :application application
          :group group
          :cmd cmd
        )
        ...
      )

itemName {STRING[nil]} - optional property: Identifies the underlying Settings item. If not specified cmd acts as identifier.
application {STRING}: Application identifier as defined in the Available Commands file.
group {STRING}: Group identifier as defined in the Available Commands file.
cmd {STRING}: Command identifier as defined in the Available Commands file.

Return Value:

t - succesful
nil - failure

Example:

(oli:sd-register-settings "3D Documentation"
  :subMenuTitle "3D Documentation"
  :settings
  '(
     ( :application "3D Documentation"
       :group "3D Documentation"
       :cmd "BOM Settings"
       :itemName "3D Documentation BOM"  ;explicitely set for later unregistration example
     )
     ( :application "3D Documentation"
       :group "3D Documentation"
       :cmd "Settings DP"
     )
     ( :application "3D Documentation"
       :group "3D Documentation"
       :cmd "Scale Anno Default"
     )
     ( :application "3D Documentation"
       :group "3D Documentation"
       :cmd "Index Default Settings"
     )
   )
)

(oli:sd-register-settings "Relations"
  :settings
  '(
     ( :application "SolidDesigner"
       :group "AdvAssembly_Parametrics"
       :cmd "Relation Settings"
     )
   )
)

SD-UNREGISTER-SETTINGS [function]

(sd-unregister-settings registration-handle
                        :itemName item-name)

Description:

Unregisters a complete Settings registration or, if item-name is specified, removes a single Settings item. A registration is unregistered if the last item is removed.
For more informations on registration see sd-register-settings function.

Parameters:

registration-handle {STRING}: Unique string handle to identify a Settings registration.
item-name {STRING[NIL]} - optional parameter: If set only the specified Settings item is removed. Unregisters the complete registration if not set.

Return Value:

t - succesful
nil - failure

Example:

;; unregister a single Settings item
(sd-unregister-settings "3D Documentation"
  :itemName "3D Documentation BOM")

;; unregister whole registration
(sd-unregister-settings "3D Documentation")

SD-PUT-BUFFER [function]

(sd-put-buffer value)

Description:

Function to feed any value to Creo Elements/Direct Modeling's command line buffer. This function does the same as you would do if you enter (type in) value in Creo Elements/Direct Modeling's enter command line.
Whenever you want to input data to a running Creo Elements/Direct Modeling command via a user interface control (using one of its actions, e.g. :pushAction of a push button control) you have to use this function.
Note: Execution of value starts, as soon as Creo Elements/Direct Modeling requires interactive input from the user. That means if you feed multiple values to Creo Elements/Direct Modeling's command buffer within a LISP loop and you never give Creo Elements/Direct Modeling a chance to become interactive to start execution of the commands in the command buffer, you can easily fill up the command buffer until it overflows.

Parameters:

value {STRING} - The value appended to Creo Elements/Direct Modeling's command buffer

Return Value:

t - success
nil - failure

Example:

(sd-put-buffer "extrude :distance")

SD-CALL-DIALOG [function]

(sd-call-dialog dialog 
                :ref-control   control-id
                :parent-shell  dialog-shell
                :attachment    attachment
                :x-offset      offset
                :y-offset      offset)

Description:

Use this function to call a dialog (user or existing command) from a UICT control.
The dialog's option menu will be placed on the screen relative to the control from which you call this function as action ("this" control). If a valid control is passed to the :ref-control parameter, the dialog command options will be placed relative to the specified control.
The default placement of the command options menu relative to this control or :ref-control is :bottomleft, i.e. the menu will appear below the control left aligned.
If the control which calls this function is not a push- or togglebutton and :ref-control is not set to a different valid control, the option menu will be displayed relative to the mouse cursor.

Parameters:

dialog {STRING} - The dialog to be called with optional additional parameters
:ref-control {STRING [this] - Name of an alternate reference control
:parent-shell {STRING [nil]}: Set this parameter to the name of the sd-create-dialog-shell (without "-DS" suffix) if you want that its bottom-line with the OK and Cancel buttons should become sensitive (not greyed out) if you call this dialog (command).
:attachment {KEYWORD [:bottomleft] - See attachment parameter here
:x-offset {NUMBER [0]} - X offset from default screen location measured in pixels
:y-offset {NUMBER [0]} - Y offset from default screen location measured in pixels

Return Value:

t - always

Example:

(sd-create-togglebutton-control "TEST-TB" "TEST-GA"
      :title          "Call Extrude"
      :x              0
      :y              0
      :width          15
      :height         2
      :indicator      :none
      :pushAction     '(sd-call-dialog "extrude :distance")
      :releaseAction  '(sd-eval-control-action "TEST-TB" :pushAction))

SD-GET-MODULE-CONTROLLER-BUTTON [function]

(sd-get-module-controller-button module-name)

Description:

Returns the button identifier of the button in the Modules menu which belongs to the module with name module-name. Use this function to set/reset or enable/disable specific buttons in the Modules menu.

Parameters:

module-name {STRING}: Name of the module as specified in all_modules.dat.

Return Value:

handle {STRING} - if button belonging to module exists
nil - no button exists

Example:

(let ((button (sd-get-module-controller-button "SURFACING")))
  (when (sd-control-p button)
    (sd-disable-control button)))

SD-INSERT-MODULE-CONTROLLER-BUTTON [function]

(sd-insert-module-controller-button module-name page-name 
                                    :moduleTitle          module-title
                                    :pageTitle            page-title
                                    :subtitle             separator-title
                                    :activationFunction   activation-function
                                    :deactivationFunction deactivation-function)

Description:

Adds a new button to an existing or new page of the Modules Controller UI.
Note: If you add a call to this function to your sd_customize file you can use the Startup ... feature of the Modules UI to automatically activate this module with startup of Creo Elements/Direct Modeling.

Parameters:

module-name {STRING}

Name of the module. If you don't specify a moduleTitle this name is used as button title. Two special module names are supported additionally:

"" - creates an empty button on the next spot of the specified page
"-" - creates a horizontal separator line across the whole Modules UI. To create a separator with a title, pass :subtitle "Title" as additional parameter.

page-name {STRING}

Identifier of an existing page (see all_modules.dat :page "Page-name") or name of a new page which will automatically be added to the Modules UI. The module button will be added to this existing or new page.

:moduleTitle {STRING}

Optional title of the module button. If not given, module-name serves as button title.

:pageTitle {STRING}

Optional title of a new page. This parameter is ignored if you add the module button to an existing page. If this parameter is not given for a new page, page-name is taken as page title.

:subtitle {STRING}

Optional title of a horizontal separator line. Only used if module-name is equal to "-".

:activationFunction {LISP form}

Function which will be executed if the user clicks this module button. If no deactivation function is given, the module button will be greyed out right after calling the activationFunction.
For a successful activation of a module you need to consider these items:

The activation function needs to return T on a successful activation or NIL if the activation failed.
The activation of the module will be considered failed if the activation function displays an error message during execution.
If the module is a licensed or license free module and no license could be granted the activation of the module fails.

On any of the above mentioned failures the user will see a useful error message and the module activation button is reset automatically.

:deactivationFunction {LISP form}

Optional LISP form which will be executed if the user resets the module button. For a successful module deactivation consider the following:

The deactivation function needs to return T on a successful deactivation or NIL if the deactivation failed.
The deactivation of the module will be considered failed if the deactivation function displays an error message during execution.
If the module is a licensed or license free module and the license could not be released the deactivation of the module fails.

Return Value:

t - button could be created successfully
nil - button creation failed (button exists already or there is no space on specified page)

Examples:

(sd-insert-module-controller-button "Recorder" "Goodies"
    :activationFunction '(load "recorder"))

(sd-insert-module-controller-button "-" "Goodies" :subtitle "More Goodies")

SD-RAISE-APPLICATION [function]

(sd-raise-application)

Description:

Brings Creo Elements/Direct Modeling application window to the top of the window stack. All other open application windows will be obscured.

Parameters:

Return Value:

t - always

SD-LOWER-APPLICATION [function]

(sd-lower-application)

Description:

Places Creo Elements/Direct Modeling application window at the bottom of the window stack. All other open application windows will obscure Creo Elements/Direct Modeling's application window.

Parameters:

Return Value:

t - always

SD-MINIMIZE-APPLICATION [function]

(sd-minimize-application)

Description:

Minimizes the application window. Once minimized Creo Elements/Direct Modeling is accessible through its icon displayed on the taskbar.

Parameters:

Return Value:

t - always

SD-RESTORE-APPLICATION [function]

(sd-restore-application)

Description:

Restores the minimized application window.

Parameters:

Return Value:

t - always