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

Graphical Browsers

This section describes the functionality provided by the Integration Kit to construct, display, modify, query and destroy graphical browsers. All functions provided here are available within the oli package and operate with any graphical browser.

Function Index Top of Page

SD-CREATE-BROWSERNODE  [function]

(sd-create-BrowserNode :tree tree-name
                       :parent parent
                       :objPath path 
                       :objPname display-name 
                       :objClientData data)
    
Description:
Create and attach a BrowserNode to a tree. BrowserNodes are the basic pieces of data used to represent the data tree which are displayed within a graphical browser. BrowserNodes are used to both describe the parent/child relationship within a tree, and carries user supplied data which the browsers can interact with.

Parameters:
:tree {STRING} - Name of the tree to which this BrowserNode is attached.
Note: a tree must exist before BrowserNodes can be attached to it.
:parent {Symbolic name of a BrowserNode[:root]}
If parent is specified, this BrowserNode will become a child of the parent. If no parent is specified, this node will become the root of the data tree. There can only be one root. If multiple browsernodes are created with no parent (i.e. :root), the last one created will be the root node. All others will be discarded. The keyword :root, is the symbolic name of the root node of a tree. The return value of sd-create-BrowserNode is the symbolic name of that node.
:objPath {STRING} - Unique string ID for this BrowserNode
The path is the unique path to the object. It can be any string. If no path is specified, one will be derived based upon the parent's path and this nodes display-name with the slash character ("/") being used as the separator character.
:objPname {STRING[""]} - Print name for this BrowserNode
The objPname can be any string and not necessarily unique.
:objClientData {Any Data[nil]}
objClientData can be any user supplied data. This data can be used for whatever purpose the browser writer needs when interacting with the browser. See the Concepts Guide for further information. In general, this data is used to carry properties and attributes of the BrowserNodes used within a data tree.

Return Value:
Symbol - Symbolic name of the constructed BrowserNode
nil - No BrowserNode created. Usually as a result of invalid data being supplied.

Example:
(setq parent (sd-create-BrowserNode "dir-tree" :parent nil
          :objPath "/" :objPname "/" :objClientData root-data)) 

parent => :root

(sd-create-BrowserNode "dir-tree" :parent parent :objPname "dir1"
           :objClientData dir1-data)

return => NODE413

Function Index Top of Page

BROWSERNODE  [structure]

Description:
The BrowserNode is the structure used to represent each node in the data tree. They are created using the sd-create-BrowserNode function. Any time the browser needs to refer to an object, it is done via its BrowserNode struct. Each BrowserNode contains four pieces of data which are accessible using the following access functions: Notes:

Example:
(setq node-name (sd-create-BrowserNode "dir-tree" :parent nil
          :objPath "/" :objPname "top" :objClientData root-data)) 
(setq struct (sd-get-browsernode-struct "dir-tree" node-name))
(BrowserNode-objPath struct) => "/"
(BrowserNode-objPname struct) => "top"
(BrowserNode-objPath struct) => root-data
(BrowserNode-NodeID struct) => :root
    

Function Index Top of Page

SD-GET-BROWSERNODE-STRUCT  [function]

(sd-get-BrowserNode-struct tree-name node-name)
Description:
Inquire the BrowserNode to a tree which has the given symbolic name. The BrowserNodes are created using sd-create-BrowserNode function.

Parameters:
tree-name {STRING} - Name of the tree to which this BrowserNode is attached.
node-name {SYMBOL [:root]} - Symbolic name of a BrowserNode

Return Value:
BrowserNode - structure
nil - A BrowserNode with the specified name does not exist.

Example:
see BrowserNode struct

Function Index Top of Page

SD-IS-PSEUDO-FOLDER-NODE-P  [function]

(sd-is-pseudo-folder-node-p node)
    
Description:
Determines whether or not the specified browser node represents a pseudo folder. Currently only the parcel browser (Structure Browser (whose name is "parcel-gbrowser") uses pseudo folders.

Parameters:
node {BrowserNode-NodeID struct} - browser node ID that is to be checked.

Return Value:
t - Browser Node represents a pseudo folder.
nil - otherwise

Function Index Top of Page

SD-CREATE-BROWSER-TREE  [function]

(sd-create-browser-tree name  
                        :update-events events 
                        :update-func func
                        :update-args args)
Description:
Associate a name to a tree which is constructed by func when events occurs. This tree name can then be attached to a browser using the sd-create-graphical-browser function.

Parameters:
name {STRING} - Name of this tree
:update-events {STRING or EVENT} - a single item or a list
When an update-event occurs, the supplied func will automatically be invoked.
:update-func {SYMBOL} - The function used to create your tree. The function will be called when an events occurs while the browser is visible. If the browser is not visible when events occurs, the update is delayed until the browser is displayed.
:update-args {LIST}
a list containing any number of arguments passed to func when events is processed.

Return Value:
t - success
nil - Tree already exists

Example:
(sd-create-browser-tree "dir-tree"
                :update-events oli:*SD-CHANGE-CURRENT-DIRECTORY-EVENT*
                :update-func 'build-file-tree) 

Function Index Top of Page

SD-CREATE-GRAPHICAL-BROWSER  [function]

(sd-create-graphical-browser name  
                             :tree                     tree-name
                             :refresh-events           refresh-event
                             :topLabel                 top-label
                             :treeStatusBar            tree-status-bar
                             :mapToggle                toggle
                             :closeAction              close-action
                             :minHeight                min-height
                             :maxWidth                 max-width
                             :maxHeight                max-height
                             :okButtonLabel            ok-label
                             :okButtonAction           ok-action
                             :abortButtonLabel         abort-label
                             :abortButtonAction        abort-action
                             :helpPageId               help-id
                             :buttonMenu               button-menu
                             :modeMenuLabel            mode-label
                             :modeMenu                 mode-menu
                             :modeMenuInitialButton    initial-mode
                             :topMenu                  top-menu
                             :modeMenuOffObjectOnly    flag
                             :buttonMenuOffObjectOnly  flag
                             :topMenuOffObjectOnly     flag
                             :primaryImageWidth        image-width
                             :primaryImageHeight       image-height
                             :secondaryImageWidth      image-width
                             :secondaryImageHeight     image-height
                             :createAsTab              tab-flag
                             :tabname                  tab-name
                             :tabImage                 tab-image
                             :tableStatusBar           table-status-bar
                             :graphicsRootBitmapPath   bitmap-path)
Description:
Create a graphical browser UI and instantiate a browser with the tree tree-name attached to it. This browser will be automatically updated when the tree is updated and when the browser is visible. If the browser is not visible, then the update is delayed.
The three menus buttonMenu, modeMenu and topMenu (if given) are mapped to right-click popup menu entries for compatibility reasons.
For an image of a sample UI that has labeled areas, click here.

Parameters:
name {STRING} - Name of the browser
:tree {STRING} -
The name of the tree to display in this browser. This tree must have been previously created. At this time, it is not yet possible to share the same tree between multiple browsers
:refresh-events {STRING or EVENT} - a single item or a list
When a refresh-event occurs, the tree is re-displayed but not rebuilt. This allows for the possibility to update a browsers display (the interrogators are executed at a refresh-event) without having to recreate the tree via it's update-func. As an example, the structure browser uses the refresh-event to update the pixmap representing whether an item was on the drawlist or not.
:topLabel {STRING[""]} - label to display at top of browser
:treeStatusBar {STRING [nil]}
Optional label above the tree. Use sd-browser-set-status-text to alter the value at runtime.
:mapToggle {STRING[nil]} - Name of the toggleButton to map
The toggle widget is the widget from which the browser is invoked. If the browser should be closed via the Cancel/OK/close action, this widget will be released. Also, when a browser is shown/hidden, the mapToggle will be mapped/unmapped.
:closeAction {LISP form['(sd-hide-graphical-browser name :ignore-pin t)]}
Action behind the close button. Defaults to hiding the browser regardless of whether it is currently pinned.
:minHeight {NUMBER [200]} - Min. Height of browser UI in pixels.
:maxWidth {NUMBER [1200]} - Max. Width of browser in pixels.
:maxHeight {NUMBER [950]} - Max. Height of browser in pixels.
:listLabel {STRING[""]} - Obsolete. Please use :treeStatusBar.
:okButtonLabel {STRING[localized "OK"]} -label for OK button
:okButtonAction {LISP FORM ['(sd-browser-exec-cmd name :select-and-execute)}
Action to occur when okButton is pressed. The default executes the browser command :select-and-execute which outputs the selected items to SD and closes the browser if not pinned. By default, the definition behind ok-action is also executed when a double click button1 or a control double click button1 action occurs within the browser.
:abortButtonLabel {STRING[ localized "Close"]}
:abortButtonAction {LISP form ['(sd-hide-graphical-browser name :ignore-pin t)]}
Action that occurs when abort button is pushed. Default is to hide the browser even if the pinning is set.
:helpPageId {STRING["name-DS"]}
Id used for help index
:buttonMenu {Quoted LISP Form[nil]} - list of buttonMenu definition
A buttonMenu provides the browser writer to specify a row of toggle buttons. The buttonMenu will appear directly above the topMenu. For each button, a menuButton Specification of the following form must be supplied:
(ButtonName :label label :push push-action :release release-action 
            :initial-value value)
           
ButtonName{STRING} - name of this button
:label{STRING} - label for this button
:push{STRING or Lisp form} - push action for this button
If the push-action is a string, the string is entered into Creo Elements/Direct Modeling's buffer. Otherwise, the supplied lisp form is evaluated.
:release{STRING or Lisp form[nil]} - release action for this button
If the release-action is specified, this button will have a toggle indicator on it. The release action can be a string or a lisp form as with the push action.
:inital-value{BOOLEAN[nil]} - initial state of toggle button
When a push and release action is defined, the intial-value of the toggle can be specified. If initial-value is nil, then the release action will be executed. Otherwise, the push action will be set.
Note: If the return value of the push or release action is not nil, the UI toggle is set. Otherwise, the UI is left in its previous state. Example.
:modeMenuLabel {STRING[localized "Show"]}
Label displayed above the modeMenu
:modeMenu {Quoted Lisp list[nil]} - list of modeButton Specifications
The modeMenu provides a row of toggle buttons. It will appear directly above the buttonMenu (if defined). For each button, a modeButton specification of the following form must be supplied.

(ButtonName :label label  :push push-form )
           

ButtonName{STRING} - name of this button in modeMenu
:label{STRING} - the label for this button
:push{Lisp form or STRING} - The push action for this button
:release{Lisp form or STRING} - The release action for this button
If push-form or release-form is a string, the string is entered into Creo Elements/Direct Modeling's buffer. Otherwise, the lisp form is evaluated.
Example.
:modeMenuInitialButton {STRING[nil]}
Name of toggle button to initially set in mode-menu. If none is supplied, then the first button in the modeMenu definition will be set.
:topMenu {Quoted LISP Form[nil]} - list of MenuSpecifications
The topMenu definition allows browser writers to define a set of pull down menu for the browser. For each pull down menu in the topMenu, the following MenuSpecification must be supplied:
(MenuName :label label :contents contents-specification
          :mutualExclusion button-name-list)
           
MenuName{STRING} - name of this pull down menu
:label{STRING} - the label for this pull down menu
:contents{Lisp List} - List of contents specifications
The contents-specification defines each of the buttons that are present in this pull down menu. For each button, the following menuButton specification must be supplied:
(ButtonName :label label :push push-action :release release-action)
                
See buttonMenu for details.
:mutualExclusion{List of ButtonNames}
The ButtonNames included in the mutualExclusion list will be mutually exclusive. They will be shown using a diamond indicator.
Example.
:modeMenuOffObjectOnly {BOOLEAN [t]}
Flag to indicate whether the mode menu which is mapped to the right-click context menu should appear only if the user clicks in free space and not on an object.
:buttonMenuOffObjectOnly {BOOLEAN [t]}
Flag to indicate whether the button menu which is mapped to the right-click context menu should appear only if the user clicks in free space and not on an object.
:topMenuOffObjectOnly {BOOLEAN [t]}
Flag to indicate whether the top menu which is mapped to the right-click context menu should appear only if the user clicks in free space and not on an object.
:primaryImageWidth {NUMBER [16]}
Width of the primary image to be displayed in the browser. All primary images displayed in this browser will be scaled to this size if the source pixmap is of a different size.
:primaryImageHeight {NUMBER [16]}
Height of the primary image to be displayed in the browser. All primary images displayed in this browser will be scaled to this size if the source pixmap is of a different size.
:secondaryImageWidth {NUMBER [16]}
Width of the secondary image to be displayed in the browser. All secondary images displayed in this browser will be scaled to this size if the source pixmap is of a different size. If the secondary pixmap interrogator returns nil as secondary pixmap for an object, no space for the icon is occupied.
:secondaryImageHeight {NUMBER [16]}
Height of the secondary image to be displayed in the browser. All secondary images displayed in this browser will be scaled to this size if the source pixmap is of a different size. If the secondary pixmap interrogator returns nil as secondary pixmap for an object, no space for the icon is occupied.
:createAsTab {BOOLEAN [nil]}
Indicates whether this graphical browser shall appear initially docked (as a tab) or floating. This parameter will be overwritten automatically by a value taken from PDS which was stored in the previous Creo Elements/Direct Modeling session.
:tabname {STRING}
Name to appear on the tab in the browser bar if browser is docked.
:tabImage {STRING}
Absolute or relative path to a BMP file to be displayed as image on the tab if the browser is docked. The size of this BMP image should be 16x16 pixels.
:tableStatusBar {STRING [nil]}
Optional text (similar to :treeStatusBar) to appear above the table. Use sd-browser-set-status-text to alter the value at runtime.
:graphicsRootBitmapPath {STRING}
Absolute or relative path to a BMP file to be displayed as tree root. If no such file is given, a default tree root image is taken.

Return Value:
{STRING} - name of the browser
nil - Browser exists or tree-name is used by another browser

Example:
Click Here for example.

Function Index Top of Page

SD-DESTROY-BROWSER-TREE  [function]

(sd-destroy-browser-tree name)
Description:
Destroys a browser tree (including all attached BrowserNodes) and unsubscribes update-func from the udpate-events defined at creation time.

Parameters:
name {STRING} - Name of the tree to Destroy

Return Value:
t - success
nil - Tree did not exist.

Example:
(sd-destroy-browser-tree "parcel-tree") 

Function Index Top of Page

SD-DESTROY-GRAPHICAL-BROWSER  [function]

(sd-destroy-graphical-browser name)
Description:
Destroy a browser definition and its UI. All data structures are destroyed(UI and browser itself). Any functions attached to the refresh-event are unsubscribed.

Parameters:
name {STRING} - Name of the browser to destroy

Return Value:
t - success
nil - Browser did not exist

Example:
(sd-destroy-graphical-browser "PARCEL-BROWSER") 

Function Index Top of Page

SD-BROWSER-ADD-INTERROGATOR  [function]

(sd-browser-add-interrogator name 
                             :interrogator-type type 
                             :interrogator-func func)
    
Description:
Attach an Interrogator to a Browser. Interrogators are used to control the display and properties of objects displayed in both the browser tree and browser table. Each object can have up to twelve different interrogators (properties) associated with it. Each time a browser object is updated or re-displayed, all attached interrogators are executed. It is only necessary to provide interrogators for those properties which are not satisfied by the default interrogator behaviours.

Parameters:
name {STRING} - Name of the browser to attach an interrogator
:interrogator-type {KEYWORD} - type of interrogator to attach
See Interrogator Table below for details.
:interrogator-func {SYMBOL} - The function to execute.
The func must be bound at the time when attaching the interrogator. Unless otherwise specified, the supplied function will be passed two parameters, and must accept both. The first parameter is the BrowserNode struct of the object for which the interrogator is to operate on. The second is the name of the browser calling the interrogator. The provided func must return a value as prescribed in the Interrogator Table shown below.
Note:
  • If no interrogator is provided for a specific property, the browser table indicates what the default browser behaviour is.
  • Since interrogators may be called often while a browser is displayed, some care should be taken to product fast and efficient procedures.

Interrogator Table

Interrogator-type: :primary-pixmap
Interrogator-func: function which accepts two parameters and returns a pixmap name{STRING}

Description:
The :primary-pixmap interrogator determines the pixmap to display for each object displayed in the browser.
Comments:
  1. sd-browser-register-image must be used to register a pixmap/bitmap file with the browser before it can be referenced by this browser.
  2. if the specified pixmap does not exist, or if nil is returned, no pixmap will be displayed.
Default: [Simple box Pixmap]
Interrogator-type: :secondary-pixmap
Interrogator-func: function which accepts two parameters and returns a pixmap name{STRING}

Description:
The :secondary-pixmap interrogator determines the secondary pixmap to display for each object displayed in the browser tree.
Comments: Same as those for :primary-pixmap
Default: [Simple box Pixmap] when secondary pixmaps are displayed
Interrogator-type: :display-in-graphics
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :display-in-graphics interrogator determines if an object is visible in the browser tree.
Default: [t] - object is displayable in browser tree.
Interrogator-type: :display-in-table
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :display-in-table interrogator determines if an object is visible in the browser table.
Default: [t] - object is displayable in browser table.
Interrogator-type: :is-selectable
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :is-selectable interrogator determines if an object is selectable within the browser.
Comments:
  1. Non-selectable objects can be expanded, dragged, or be valid drop targets.
Default: [t] - object is selectable.
Interrogator-type: :is-expandable
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :is-expandable interrogator determines if an object is expandable (i.e. can show its children) within the browser tree. This is independent of whether it actually has children in the data tree.
Comments:
  1. If an object is non-expandable, all children of that object will not be displayable.
  2. Expanding an object with no children will have no visible impact on the browser tree structure. However, the interrogators will be executed.
Default: [t] - object is expandable
Interrogator-type: :is-editable
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :is-editable interrogator determines if an object's name is editable within the browser tree. This interrogator only determines if a object is editable, it does not enable object editing. See Note below.
Comments:
  1. If an object is editable, the pop-up menu "Edit Name" will be enabled, and a cell editing field will be displayed when a user attempts to edit the object's name.
  2. To enable object name editing, you must use the function (sd-browser-exec-cmd "name" :set-object-editor ...)
Default: [nil] - object is not editable
Interrogator-type: :tree-display-name
Interrogator-func: function which accepts two parameters and returns an alternate print name for items in the browser tree {STRING}

Description:
The :tree-display-name interrogator provides a method to display an alternate print name (the label) for an object in the browser tree.
Comments:
  1. If nil is returned, the objPname will be used.
  2. The print name of objects shown in the browser table are not governed by this interrogator.
Default: [objPname]
Interrogator-type: :table-display-name
Interrogator-func: function which accepts two parameters and returns an alternate print name for items in the browser table {STRING}

Description:
The :table-display-name interrogator provides a method to display an alternate print name (the label) for an object in the browser table.
Comments:
  1. If nil is returned, the objPname will be used.
  2. The print name of objects shown in the browser tree are not governed by this interrogator.
  3. If this interrogator is not used, the print name of objects in the browser table is either the objectPname or objPath (depending if one or multiple table roots are displayed).
Default: [objPname or objPath as described above]
Interrogator-type: :tree-print-name
Interrogator-func: function which accepts two parameters and returns the name that will be printed into the file produced when saving a browser tree to a file. {STRING}

Description:
The :tree-print-name interrogator provides a method to display an alternate name for an object when saving the browser tree to a file. This can be useful to display additional information into the outputted browser file. This interrogator does not have any impact on the display of the browser tree on the screen.
Comments:
  1. If nil is returned, the objPname will be used.
  2. If this interrogator is not specified, then the output in the file will be the same as what is displayed on the screen.
Default: [objPname]
Interrogator-type: :border-color
Interrogator-func: function which accepts two parameters and returns a "#rrggbb" Color name {STRING}

Description:
The :border-color interrogator determines the underline or fill color of the object's label string. See here for more details.
Comments:
  1. If the color is not available, the next closest color will be used.
  2. If nil is returned, the default color (described below) will be used.
  3. The width of the border color can be controlled by resources
Default:
If the border color has been specified via resources, it will become the default color. Otherwise, the border color is the same as the background color of the browser tree.
Interrogator-type: :text-color
Interrogator-func: function which accepts two parameters and returns a "#rrggbb" Color name {STRING}

Description:
The :text-color interrogator determines the color of all displayed text of the browser object.
Comments:
  1. If the color is not available, the next closest color will be used.
  2. If nil is returned, the default color (described below) will be used.
Default:
If the text color has been specified via resources, it will become the default color. Otherwise, the text color is the same as the foreground color of the browser tree.
Interrogator-type: :drag-source
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :drag-source interrogator determines if an object is allowed to be a valid drag source (object which can participate in a drag operation).
Comments:
  1. If an object is not a valid drag source (i.e. interrogator returns nil), drag actions initiated on that object will be ignored.
Default: [t] - object is a valid drag source.
Interrogator-type: :drag-target
Interrogator-func: function which accepts two parameters and returns t or nil {BOOLEAN}

Description:
The :drag-target interrogator determines if an object is allowed to be a valid drag target (object upon which a drag operation is completed).
Comments:
  1. If an object is not a valid drag target, drag actions completed on this object will be ignored.
  2. During a drag operation, the browser will display a feedback cursor which is determined by this interrogator.
  3. Valid drag targets will display the ok-entry cursor.
  4. Invalid drag targets will display the no-entry cursor.
Default: [t] - object is a valid drag target.
Interrogator-type: :can-be-dropped
Interrogator-func: function which accepts three parameters and returns t or nil {BOOLEAN}.

Description:
The :can-be-dropped interrogator determines if the selected source and target objects are a valid combination for a drag operation. The supplied function, must accept three parameters: source object, target object, and the browser name - respectively.
Comments:
  1. Drag/Drop actions are by default in-active. To activate drag/drop behaviours, a drag function must be first defined (See sd-browser-click-action).
  2. Only if a valid drag/drop combination occurs (i.e. :can-be-dropped interrogator returns t) will the drag function be called.
Default: [t] - all source and target combinations are valid
Return Value:
t - Interrogator successfully attached to browser
nil - Invalid parameters were supplied.

Example:
(sd-create-image "dir-pix" :filename "dir_pix.pm")
(sd-create-image "file-pix" :filename "file_pix.pm")

(defun get-primary-pixmap(obj browser-name)
  (if (eq :file (get-type obj))
      "file-pix"
      "dir-pix"))

(defun get-drag-drop(source target name)
  (if (valid-drag-drop source target)
      t
      nil))

(sd-browser-add-interrogator "my-browser" :interrogator-type :primary-pixmap
                             :interrogator-func 'get-primary-pixmap)
(sd-browser-add-interrogator "my-browser" :interrogator-type :can-be-dropped
                             :interrogator-func 'get-drag-drop)

         

Function Index Top of Page

SD-BROWSER-CLICK-ACTION  [function]

(sd-browser-click-action name 
                         :action-type  type 
                         :mask         mask 
                         :button       button-name 
                         :action-func  func) 
    
Description:
Attach an action to a specified mouse event(s). It allows the browser writer to customize the actions of the browser when specified mouse events occur. For each pre-defined type, a different func can be invoked for all supported combinations of mask and button combinations. When the specified action type, mask, and button combination occurs, the supplied action function will be executed. See Click Action Table for supported combinations.

Parameters:
name {STRING} - Name of the browser to attach an custom action.
:action-type {KEYWORD} - one of the following actions to customize
  • :single-click - action type which is invoked when a single click (push and release) mouse event occurs over a browser object.
  • :multi-click - action type which is invoked when a double click mouse event occurs over a browser object.
  • :drag - action type which is invoked when a drag event occurs (more precisely, when a drag leaves the boundary of a browser object).
  • :icon-click - action type which is invoked when a click event occurs over the primary icon of a browser object.
  • :sec-icon-click - action type which is invoked when a click event occurs over the secondary icon of a browser object.
:mask {QUOTED list of KEYWORDS[nil]}
The mask combination which applies to this action (See Mask/Button Combination Table for supported interactions).
The mask is any combination of the following mask keywords:
Mask Keyword Description
:shift Shift Right or Shift Left Button
:ctrl Control Button
:button {KEYWORD [:button1]}
One of the following supported button keywords (the table shows the definition for a right handed mouse):
Button Name Description
:button1 Left Button
:button2 Middle Button
:button3 Right Button
:action-func {SYMBOL} - The function to execute.
The func must be bound at the time when defining the click action. It will be executed when the specified click action (combination of right button, mask and action-type) occurs. As shown in the Action Type Table, the supplied function will be passed multiple parameters, and must accept them all. Unless otherwise specified, the first parameter is the BrowserNode struct of the object for which the action is to operate on. The second is the name of the browser calling the action. The provided func return value will be ignored.

Shown below are the pre-defined click actions which exist.

Default Click Action Table

Action Type Mask Button Description
:single-click nil :button1 Select a single object
:single-click :ctrl :button1 Add/Remove a single object from the select list
:multi-click nil :button1 Select a single object and execute OK button action
:multi-click :ctrl :button1 Add/Remove object and execute OK button action
:single-click nil :button2 Select a table root
:single-click :ctrl :button2 Add/Remove a table root
:single-click :shift :button2 Expand/Contract an object
  • The use of button3 (no mask) is reserved for popup menu action
  • All other defaults actions can be overridden by supplying a new click action

Action Type Table

Action Type Mask Button Action-func parameters: (count), and type
:single-click any any (2) BrowserNode Struct, Browser Name
:multi-click any any (2) BrowserNode Struct, Browser Name
:drag any any (3) Source BrowserNode, Target BrowserNode, Browser Name
:icon-click nil :button1 (2) BrowserNode Struct, Browser Name
:sec-icon-click nil :button1 (2) BrowserNode Struct, Browser Name
  • The func must accept the parameters as shown.
  • Table shows supported combinations of mask and buttons that can be used for an action.
Return Value:
t - Click action successfully attached to browser
nil - Invalid parameters were supplied.

Example:
(defun single-click(obj name)
  (print (format nil "single click action on ~A in browser ~A" obj name))
)
(defun do-drag(source target name)
  (print (format nil "Drag ~A to ~A" (BrowserNode-objPname source)
                                     (BrowserNode-objPname target)))
)
(sd-browser-click-action "by-browser" :action-type :single-click 
                                     :mask '(:shift)
                                     :button :button1 :action-func 'single-click)
(sd-browser-click-action "by-browser" :action-type :drag
                                      :button :button2 :action-func 'do-drag)
    

Function Index Top of Page

SD-BROWSER-EXEC-CMD  [function]

(sd-browser-exec-cmd name cmd &optional param1 param2) 
    
Description:
Execute a browser command. Browser commands provide the ability for browser writers to set the mode or change the status of many browser properties. Browser commands are normally used within the browser UI to change the state of the browser, but can also be used in interrogators, or other lisp functions.

Parameters:
name {STRING} - Name of the browser to execute a command on.
cmd {KEYWORD} - one of the command types shown in the Command Table.
Each browser command may require up to two additional parameters to be specified. The Command Table below describes each command along with these required parameters.
param1, param2 {} - Optional parameter as specified in the Command Table.

Browser Command Table

:SET-GRAPHICS-MODE
Optional Parameters: none required.
Description: Set the browser to display browser tree only
:SET-TABLE-MODE
Optional Parameters: none required.
Description: Set browser to display browser table only
:SET-DUAL-MODE
Optional Parameters: none required.
Description: Set browser to display browser tree and table
:SELECT-ALL
Optional Parameters: none required.
Description: Select all visible items in the browser.
:CLEAR-SELECT-LIST
Optional Parameters: none required.
Description: Clear the list of selected items (unselect all items).
:DISPLAY-PRIMARY-ICON
Optional Parameters:
Param1: {BOOLEAN[t]} - t=On on tree side, nil=Off on both tree and table, :both = On on tree and table side, :table = On on table only.
Description: Turn primary icons on/off. By default, primary icons are on.
:DISPLAY-SECONDARY-ICON
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=On on tree side, nil=Off on both tree and table, :both = On on tree and table side, :table = On on table only.
Description: Turn secondary icons on/off. By default, secondary icons are off.
:EXPAND-TREE
Optional Parameters:
Param1: {INTEGER[0]} - number of levels to display
Param2: {BrowserNode struct [root node]} - object to be expanded
Description:
Expand/Contract the browser tree. If the number of levels is not specified or is 0, all branches of the sub tree referred to by Param2 are expanded. Otherwise the number of levels specified are expanded (counted from browser node (Param2)).
:CLEAR-TABLE-ROOTS
Optional Parameters: none required.
Description: Clear all table roots. (Show no data in browser table)
:SET-OBJECT-EDITOR
Optional Parameters:
Param1: {SYMBOL to lisp function} - Symbol to function which accepts three parameters and returns t or nil.
Description:
Enable Object Editing. The supplied function will be invoked by the browser when a user attempts to edit an object's name in the browser tree. The supplied function must be bound at the time of calling this command. The supplied function must accepts three parameters:
  1. BrowserNode - The object upon which the action is to operate.
  2. BrowserName - Name of the browser making the call.
  3. NewName - New name entered by the user.
Notes:
  • If no editor function is supplied, the command will not be executed.
  • If nil is returned by the edit function, the browser will ignore the new user value and request another value from the user.
:EXPAND-TABLE
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=expand table, nil=contract table
Description:
Normally, the browser table will display only the direct descendants of the table root (i.e. one level of children). Expand-table can be used to show all children of a table root. It is not possible to expand the table if more than one table root is selected. When the table is expanded, the browser table will display the full path name (i.e. objPathName) of the object.
:DISPLAY-ROOT-NODE
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=show root node, nil=hide root node
Description: Display/Hide the root node.
:ENABLE-WIDGET-TIPS
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=show widget tips, nil=don't show widget tips
Description: Display little additional explanation windows when the user hovers over a browser item or not.
:REFRESH-TREE
Optional Parameters: none required.
Description:
Force a redraw of the browser tree. This will cause all interrogators to be executed. Normally, browser trees are automatically redrawn, however in some situations it may be necessary to use this command.
:DISPLAY-TREE
Optional Parameters: none required.
Description:
Force the browser tree to be rebuilt. This command will rescan the browser tree and reconstruct it. This command is more time consuming than display-tree, and should only be required in special situations.
:BUFFER-DISPLAY
Optional Parameters:
Param1 {BOOLEAN[nil]}: t = Suspend Display, nil = Resume Display
Description:
Buffer display updates of the gbrowser. When Param1 is t, the command will delay all updates of the browser display until display updates are resumed. This command is useful when it is known that several browser commands need to be executed which normally causes display updates to the browser. To avoid annoying flashes during these command sequences, first set buffer-display to true, execute the command sequence, then set buffer-display to nil.

NOTE: Display updates must be resumed before user interaction can occur, otherwise unexpected results may occur.

:SELECT-AND-EXECUTE
Optional Parameters:
Param1 {STRING[nil]}: command sequence to execute
Description:
Convenience function which extracts the selected items in the browser and executes the supplied function. If no command is supplied, the selected items are entered into SD buffer which any running command may accept as input. If no items are selected, the supplied command will continue to be active after executing this command. This command will perform the following tasks:
  1. Initiate the supplied command string
  2. Create a select list and enter it into SD buffer
  3. hide the graphical browser if not pinned
  4. clear the selection list
Note: This command returns nil if no items were selected in the browser.
:SET-OBJECT-SELECTION
Optional Parameters:
Param1: {BrowserNode struct} - object to operate on
Param2: {BOOLEAN[nil]} - t=select object, nil=unselect object
Description:
Select/Unselect an object in the browser. Only items that are visible are selectable. The browser will automatically unselect objects not shown in the browser.
:SET-OBJECT-EXPANSION
Optional Parameters:
Param1: {BrowserNode struct} - object to operate on
Param2: {BOOLEAN[nil]}-t=show children, nil=hide children of object
Description:
Expand/Contract an object in the browser tree. If the specified object is non-expandable (as determined by the interrogators) then no action will take place.
:SET-OBJECT-DESCRIPTION
Optional Parameters:
Param1: {BrowserNode struct} - object to operate on
Param2: {STRING[nil]} - string to display as widget-tip
Description:
Sets the contents of the little additional explanation window (widget-tip) which appears when the user hovers over this browser item.
:CHANGE-TABLE-ROOT
Optional Parameters:
Param1: {BrowserNode struct} - object to operate on
Param2: {BOOLEAN[nil]} - t=make object a table root, nil=unset object as table root.
Description:
Set/Clear the object as a table root. To quickly unset all table roots, use CLEAR-TABLE-ROOTS command. Objects that are table roots will have their children shown in the browser table.
:CHANGE-GRAPHICS-ROOT
Optional Parameters:
Param1: {BrowserNode struct} - object to make the tree root.
Description:
Set the tree root to the specified object. Setting a graphics root allows the browser writer to display only the portion of the browser tree below this object. The hidden part of the browser tree will be represented by a simply icon.
:DISPLAY-GRAPHICS-ROOT-ICON
Optional Parameters:
Param1: {BOOLEAN[nil]} - display flag for graphics root icon
Description:
Determine whether graphics root icon is displayed when the graphics root is set to any subtree node. If the flag is set to t the icon will be displayed whereas if set to nil the icon won't be displayed and the tree will be filled starting with the immediate children of the graphics root node.
:SET-SEPERATION
Optional Parameters:
Param1: {INTEGER} - vertical separation in pixels between objects
Param2: {INTEGER[10]} - horizontal separation between parent/child
Description:
Set-seperation allows the browser writer to control the spacing between objects shown in the browser. Vertical spacing controls the vertical distance between objects. It is recommended that the minimum vertical spacing be 6 pixels larger than the largest pixmap. Horizontal separation controls the horizontal offset between a parent and its child in the browser tree. If no horizontal separation is specified, a default value of 10 pixels will be used.
Note: For parcel browsers Param1 is the spacing which is controlled by the keyword given in Param2. This Param2 keyword can be one of these:
  • :with-pixmap - vertical separation while pixmaps are visible
  • :without-pixmap - vertical separation without pixmaps
  • :indent-with-pixmap - horizontal separation while pixmaps are visible
  • :indent-without-pixmap - horizontal separation without pixmaps

Additional parcel browser (Structure Browser (whose name is "parcel-gbrowser") specific commands. For the description of

(sd-browser-exec-cmd name cmd &optional param1 param2)
see here.

Parcel Browser Specific Command Table

:SET-DETAILED-MODE [Deprecated]
Description: This command no longer has any effect. Tree Details can now be found under browser views.
:SET-DETAILED-PIXMAP-MODE
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=show primary icons, nil=hide primary icons
Description: Show or hide primary icons in tree and/or table side of parcel related browsers.
:SHOW-TREE-DETAILS [Deprecated]
Description: This command no longer has any effect. Tree Details can now be found under browser views.
:SET-BROWSER-MODE
Optional Parameters:
Param1: {KEYWORD} - One of:
  • :container-mode - Containers
  • :configuration-mode - Configurations
  • :clash_analysis-mode - Clash Analysis
  • :rel_set-mode - Relations, Relation sets
  • :animation-mode - Animations
  • :simplification - Simplifications
  • :molddesignadv - Mold Design Advisor Features
  • :taper-feature - Taper Features
  • :sheet-metal - Sheet Metal Features
  • :3d-library - 3D Library Features
  • :study-mode - Studies
  • :manufacturing - Manufacturing Features
  • :gdt - GDT Features
  • :3d-annotation - 3D Annotations
  • :group-mode - Groups
  • :grouping-features - Grouping Features
  • :open-reference - Open References
  • :element-names - Element Names
  • :generic-texts - Generic Texts
  • :hidden-features - Hidden Features
  • :user-defined-feature - User Defined Features
  • :feature-mode - Features
  • :coord_sys-mode - Coordinate Systems
  • :docu_plane-mode - Docuplanes, Docuplane Sets
  • :layout-mode - Views
  • :part-mode - Parts, Assemblies, Face parts, ...
  • :wp-mode - Workplanes, Workplane sets
Param2: {BOOLEAN[nil]} - t=show in Param1 specified items, nil=don't show in Param1 specified items
Description: Configures the parcel related browser to show only those items which you are interested in.
:SET-BROWSER-MODE-ORDER
Optional Parameters:
Param1: {LIST} - Containing any of the keywords applicable for the :SET-BROWSER-MODE command plus :others-mode
Description:
Specifies the order of objects in the parcel browser underneath a parent. All objects for which a keyword is not supplied are sorted alphabetically after the objects that had been specified. If the keyword :others-mode is in the list all other objects are inserted at this position.
:SET-VISIBLE [Deprecated]
Description: This command no longer has any effect. How to control the visibility of columns can now be found under browser views.
:SET-PARTIAL-VISIBLE-ADD-MODE
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=add mode, nil=remove mode
Description: For partial visible objects decide if click the drawlist icon adds or removes the object from the drawlist. Default value is add the object to the drawlist.
:INCREMENTAL-BUILD
Optional Parameters:
Param1: {BOOLEAN[t]} - t=build only visible part of the tree, nil=build complete tree
Description:
When the BrowserNode tree is completely built after each modification of the model the performance is decreased for large models. Therefor, only the visible part of the tree is built by default. Then the effort to rebuild the tree depends on how many nodes are expanded.
:BUILD-TREE-UPON-GRAPHICS-ROOT
Optional Parameters:
Param1: {BOOLEAN[nil]} - t=build tree upon graphics root, nil=start the tree at the graphics root node
Description:
When the graphics root is set to a node other then the root node the BrowserNode tree above the graphics root is not rebuild with the next update. But then sd-query-browser :get-parent will return nil for the graphics root. If you really need this node you have to set :BUILD-TREE-UPON-GRAPHICS-ROOT to t.
Note:
Setting :BUILD-TREE-UPON-GRAPHICS-ROOT to t may result in a performance decrease for large models.

Return Value:
t - Browser command was successfully executed.
nil - Invalid parameters were supplied, or command failed.

Example:
(defun set-single-table-root(obj name)
  (sd-browser-exec-cmd name :buffer-display t)
  (sd-browser-exec-cmd name :clear-table-roots)
  (sd-browser-exec-cmd name :change-table-root obj t)
  (sd-browser-exec-cmd name :buffer-display nil)
)

(sd-browser-exec-cmd "my-browser" :set-seperation 14)
(sd-browser-exec-cmd "my-browser" :set-graphics-mode)
(sd-browser-exec-cmd "my-browser" :expand-tree 0)
(sd-browser-exec-cmd "my-browser" :select-all)

(sd-browser-exec-cmd "my-browser" :select-and-execute
    "change_part_color :color xxx :parts")
    

Function Index Top of Page

SD-BROWSER-SET-BORDER-MODE  [function]

(sd-browser-set-border-mode name :mode border-mode)
Description:
The border color interrogator leads to an underlined object label string. This function allows you to change the mode in a way that the objects label string is drawn with the border-color interrogator color as background (filled).

Parameters:
name {STRING} - Name of the browser
:mode {KEYWORD [:underlined]} - Either :filled or :underlined

Return Value:
t - success
nil - failure

Function Index Top of Page

SD-QUERY-BROWSER  [function]

(sd-query-browser name property &optional param1 param2)
    
Description:
Query data from the browser. Browser queries provide the ability for browser writers to get the mode or inquire the status of many browser properties. Browser queries are commonly used within the interrogators to produce intelligent browsers. However they can be used anywhere.

Parameters:
name {STRING} - Name of the browser to query a property.
property {KEYWORD} - one of the types shown in the Query Table.
Each browser query may require up to two additional parameters to be specified. For each query, a value is returned to indicate the status of that property. The Query Table below describes each query along with these required parameters and return values.
param1, param2 {} - Optional parameter as specified in the Command Table.

Browser Query Table

:IS-DUAL-MODE
Optional Parameters: none required.
Description: Inquire if the browser is displaying both a browser tree and browser table
Return Value: t or nil
:IS-TABLE-MODE
Optional Parameters: none required.
Description: Inquire if browser is displaying only a browser table
Return Value: t or nil
:IS-GRAPHICS-MODE
Optional Parameters: none required.
Description: Inquire if browser is currently displaying only a browser tree
Return Value: t or nil
:ARE-SECONDARY-ICONS-DISPLAYED
Optional Parameters: none required.
Description: Inquire if secondary icons are currently displayed
Return Value: t or nil
:ARE-ALL-BRANCHES-EXPANDED
Optional Parameters: none required
Description: Inquire if all branches in the browser tree are currently expanded.
Return Value: t or nil
:IS-OBJECT-SELECTED
Optional Parameters:
Param1: {BrowserNode struct} - object to query
Description: Inquire if the supplied object is currently selected.
Return Value: t or nil
:IS-OBJECT-DISPLAYED
Optional Parameters:
Param1: {BrowserNode struct} - object to query
Description: Inquire if the supplied object is currently visible.
Return Value: t or nil
:IS-OBJECT-TABLE-ROOT
Optional Parameters:
Param1: {BrowserNode struct} - object to query
Description:
Inquire if supplied object is currently a table root. Children of a table root are shown in the browser table.
Return Value: t or nil
:IS-OBJECT-EXPANDED
Optional Parameters:
Param1: {BrowserNode struct} - object to query
Description:
Inquiries if the supplied object is currently expanded/contracted. If an object is expanded, its children will be shown in the browser tree.
Return Value: t or nil
:GET-GRAPHICS-ROOT
Optional Parameters: none required
Description:
Inquire which object is currently the tree root. If no graphics root is currently set, the root node will be returned.
Return Value: BrowserNode struct of tree root object.
:IS-GRAPHICS-ROOT-ICON-DISPLAYED
Optional Parameters: none required
Description:
Returns whether the graphics root icon is displayed when the graphics root is set to any subtree node.
Return Value: t or nil
:NUMBER-OF-SELECTED-OBJECTS
Optional Parameters: none required.
Description:
Inquires the number of objects that are currently selected.
Return Value: {INTEGER}
:NUMBER-OF-TABLE-ROOTS
Optional Parameters: none required.
Description:
Inquires the number of table roots present in the browser tree.
Return Value: {INTEGER}
:IS-DESCENDENT
Optional Parameters:
Param1 {BrowserNode struct}: reference object
Param2 {BrowserNode struct}: source object
Description:
Inquires if source object is a descendent (child) of the reference object. If the source object exist along a branch of the reference object, then it is a descendent. This utility can be useful to avoid recursive drag/drop actions and/or deterimining if an object is related to another.
Return Value: t or nil
:GET-SELECTED-OBJECTS
Optional Parameters: none required
Description:
Returns a list of the objects that are selected.
Return Value: {LIST of BrowserNode structs or nil if no objects are selected}
:GET_TABLE_ROOTS
Optional Parameters: none required
Description:
Returns a list of the objects that are set as table roots.
Return Value: {LIST of BrowserNode structs or nil if no table roots are set}
:GET-CHILDREN
Optional Parameters:
Param1: {BrowserNode struct} - object to get children of
Description:
Return a list of the objects that are the immediate (one level down) children of the supplied object.
Return Value: {LIST of BrowserNode structs or nil if there are no children}
:GET-PARENT
Optional Parameters:
Param1: {BrowserNode struct} - object to get parent of
Description:
Return the object that is the immediate (one level up) parent of the supplied object.
Note:
When the graphics root is set to another node than the root node :GET-PARENT may return nil. To avoid this behaviour set :BUILD-TREE-UPON-GRAPHICS-ROOT to t.
Return Value: {BrowserNode struct or nil if there is no parent}
Return Value:
Value as described in Query Table above.

Example:
(defun sec-icon-click(obj name)
   ;expand/contract the selected object. 
   ;if object is currently expanded, contract it.
   (if (sd-query-browser name :is-object-expanded obj)
    (sd-browser-exec-cmd name :set-object-expansion obj nil)
    (sd-browser-exec-cmd name :set-object-expansion obj t)
   )
)

(defun do-drag(source target name)
  ;don't do drag if target node is a child of source node
  (if (sd-query-browser name :is-descendent target source)
    nil
    ;else
    (do-drag-operation source target)
  )
)

(defun process-selected-objects(browser-name)
  (dolist (node (sd-query-browser name :get-selected-objects))
    (operate-on (BrowserNode-objPath node)))
)
    

Function Index Top of Page

SD-BROWSER-ADD-POPUP-ENTRY  [function]

(sd-browser-add-popup-entry name  
                            :label                label
                            :entry-type           entry-type
                            :parent-menu-name     parent-menu-name
                            :sub-menu-name        sub-menu-name
                            :is-entry-visible     is-visible
                            :is-entry-applicable  is-applicable
                            :menu-action          action
                            :is-on-fn             is-on-function
                            :new-group            new-group-flag
                            :string-client-data   string-client-data
                            :place-at-top         place-at-top-flag)
Description:
Add a new menu entry to the browsers popup menu. This new entry can either be a simple push button, a toggle button with a check mark if on or an entry which opens up a cascading submenu.
This function allows browser writers to add context dependent menu entry. When creating a popup menu, the writer must provide three to four menu interrogators. Each of these interrogators will call the supplied lisp function to determine: Note:

Parameters:
name {STRING} - Name of the browser to add a menu entry to.
:label {STRING [nil]} - Display label for this popup menu entry
:entry-type {KEYWORD [:push]} - Can be one of the following:
  • :push - the popup menu entry is a simple push button
  • :toggle - the popup menu entry is a toggle button. Supply a :is-on-fn function to determine whether the toggle button check mark is on or off.
  • :sub-menu - the popup menu entry is a cascading menu
:parent-menu-name {STRING [nil]}
Determines where to add the popup menu entry. If this parameter is NIL, the popup menu entry will be added to the core popup menu. If this parameter is the name of a submenu previously created with :entry-type set to :sub-menu and :sub-menu-name, this new popup menu entry will be added to this submenu.
:sub-menu-name {STRING [nil]}
Used as handle to a cascading submenu. If you want to add items to a submenu, you need to pass this name as parameter to :parent-menu-name in further calls to this function. This parameter is only valid in combination with :entry-type set to :sub-menu.
:is-entry-visible {Symbol to lisp function} which returns a {BOOLEAN}.
This menu interrogator determines the conditions under which this menu item will be visible in the popup menu. This provides the browser writer to hide menu entries unless they are applicable to the situation (the object over which the menu was displayed).
NOTE:
  • If the popup menu occurs over no objects, the first supplied parameter (the BrowserNode struct) will be set to nil.
  • If is-visibile is not specified, then this menu entry will always be visible.
:is-entry-applicable {Symbol to lisp function} which returns a {BOOLEAN}.
This menu interrogator determines the conditions under which this menu item will be applicable (not grayed out) in the popup menu. This provides the browser writer to make menu entries insensitive if they are not applicable to the situation (the object over which the menu was displayed).
NOTE:
  • If the popup menu occurs over no objects, the first supplied parameter (the BrowserNode struct) will be set to nil.
  • If is-applicable is not specified, then this menu entry will always be applicable (sensitive).
:menu-action {Symbol to lisp function} whose return value is ignored.
The function that will be executed if this popup menu entry is selected. This function is your doer for this menu entry.
NOTE:
  • If the popup menu occurs over no objects, the first supplied parameter (the BrowserNode struct) will be nil. Otherwise, it will be the BrowserNode struct of the object over which the menu action occurred.
  • If action is not specified, then this menu entry will perform no action.
:is-on-fn {Symbol to lisp function} which returns a {BOOLEAN}.
This interrogator determines whether this toggle button entry is checked or not.
NOTE:
  • If the popup menu occurs over no objects, the first supplied parameter (the BrowserNode struct) will be nil. Otherwise, it will be the BrowserNode struct of the object over which the menu action occurred.
  • If is-on-fn is not specified, then this menu entry will always show no check mark.
:new-group {BOOLEAN [nil]}
If this parameter is set to T a separator will appear above this menu entry. If the menu entry is not visible because of a :is-entry-visible interrogator, the separator is not visible as well.
:string-client-data {STRING}
Optional string which gets passed as third parameter to interrogator functions (:is-entry-visible, :is-entry-applicable, :menu-action, :is-on-fn). This string data allows you to write generic interrogator functions which can be used for several different popup menu entries.
:place-at-top {BOOLEAN [nil]}
Usually a new popup menu entry is added at the bottom of the popup menu. This parameter allows you to add the new entry at the top.

Return Value:
t - Menu entry successfully added to browser
nil - Invalid parameters supplied.

Examples:
(defun is-visible (obj name)
  (if obj
      t      ; menu entry should be visible if selected over on object
      nil))  ; don't show menu if not over an object

(defun is-applicable (obj name)
  (if (eq :file (type-of-obj obj))
    t
    nil))

(defun menu-action (obj name)
  ;since this menu is only visible when over an object, don't have to check
  ;if obj is nil.
  (print (format nil "load file:~A" (BrowserNode-objPath obj))))

(sd-browser-add-popup-entry "my-browser" :is-entry-visible 'is-visible
       :is-entry-applicable 'is-applicable :menu-action 'menu-action 
       :label "load file")

(sd-browser-add-popup-entry "my-browser" 
       :label           "More commands ..."
       :entry-type      :sub-menu
       :sub-menu-name   "More-Commands-Submenu"
       :new-group       t)   ;; add separator above

(defun generic-is-on-fn (obj name client-data)
  (cond ((sd-string= client-data "Check-Me-Button")
         (is-check-me-button-checked))
        ( ;; more buttons
        )))

(defun generic-toggle-menu-action (obj name client-data)
  (cond ((sd-string= client-data "Check-Me-Button")
         (if (is-check-me-button-checked)
             (execute-check-me-release-action)
            (execute-check-me-push-action)))
        ( ;; more buttons
        )))

(sd-browser-add-popup-entry "my-browser" 
       :label             "Check Me"
       :entry-type        :toggle
       :parent-menu-name  "More-Commands-Submenu"
       :string-client-data  "Check-Me-Button"
       :is-on-fn            'generic-is-on-fn
       :menu-action         'generic-toggle-menu-action)

Function Index Top of Page

SD-BROWSER-DEFINE-TABLE  [function]

(sd-browser-define-table browser-name
                         :table-name table-name 
                         :with-name-column value
                         :column-definition column)
Description:
Define the table definition for the browser table. With this utility browser writers can define the columns and the data to be displayed in the browser table. The browser table can be used to show any data for any object in the data tree. A browser table will only be filled with data when a table root has been selected. Unless filters are set, all the children of the selected table root(s) will be shown with their corresponding table data. Unless sorts are set, children of a table root will be shown in alphabetical order. Creating a table definition makes that the active table.

Parameters:
browser-name {STRING}-Name of the browser to attach the table
table-name {STRING[browser-name]} - Name of the this table
table-name is the identifier used to identify this table from other tables attached to this browser. If no table-name is provided, then the supplied browser-name will be used.
:with-name-column {BOOLEAN[t]} - Include "Name" column as first column in table
with-name-column is a convienence flag which controls whether the first column of the table should be a predefined "Name" column. A "Name" column has the following characteristcs:
  • Displays the objects name (objPname) or path (objPath) depending on whether multiple table roots are set, table is in expand mode, only the table is displayed. This "Name" column produces the same behaviour provided with the default browsers supplied by Creo Elements/Direct.
  • The column width will grow/contract automatically as required up to its maximum width. By default, this is 20 characters unless an end user specifies a different width via the UI.
:column-definition {QUOTED lisp list} - list of column specifications
For each column in the table, a column specification needs to be supplied of the following form:
           (  
              :label label
              :type type 
              :initial-width width
              :display-func disp-func
              :edit-func edit-func
              :applicable-func appl-func
              :justfication side
              :print-values p-values
              :clipping clipped [deprecated]
           )
           
Note: The option print-values is not necessarily applicable for all types of columns. See restriction below.

:type{KEYWORD[:string-column]} -data type for this column
Must be one of the following supported types:
:string-column - column whose data are strings
Non-applicable key| :print-values |
:integer-column - column whose data are integers
Non-applicable key| :print-values |
:float-column - column whose data are floating points
Non-applicable key| :print-values |
:boolean-column - column whose data are booleans
By default, the print-values for boolean columns are the words "True" and "False". If other print-values are desired, use :print-value to specify alternative values.
:enum-column - column whose data are enumerators
The :print-value option must be specified for this column type.

Each column type offer methods for performing filtering and sorting of based upon the data specified by the column type. The column type also controls what type of data may be entered by the user if column editing is enabled (edit-func is supplied).

:initial-width{INTEGER[width of label]}
This controls the initial width in characters that a column will be. Users can modify the width of columns interactively by the UI supplied via the column header push buttons.
:label{STRING["No Title"]}
The label that is displayed at the top of the column.
:display-func{SYMBOL to lisp function}
Symbol to function which accepts two parameters and returns the data of the correct type to be displayed within this column. The first parameter supplied to the display-func is the BrowserNode struct of the object to display data, the second is the browser name calling the display-func. If no display-func is provided, this is equivalent to setting the applicable-func to nil.

NOTE: The display-func should return a value of the same type as specified by the type value. Any other return type will produce unexpected results.

:edit-func{SYMBOL to lisp function}
Symbol to function which accepts three parameters and returns t or nil. The edit-func will be invoked by the browser when a user edits the cell of this column. The first parameter supplied to the edit-func is the BrowserNode struct of the object to edit, the second is the browser name calling the edit-func, the third is the new value entered by the user. If no edit-func is supplied, the column will be uneditable. If nil is returned by the edit-func, the browser will ignore the new user value and request another value from the user.
:applicable-func{SYMBOL to lisp function}
Symbol to function which accepts two parameters and returns the t or nil. The applicable-func determines if an object is applicable for this column. If nil is returned, the table cell for this object will be empty, otherwise, display-func will be called to determine what data to show in the table cell.The first parameter supplied to the applicable-func is the BrowserNode struct of the object to display data, the second is the browser name calling the display-func. If no applicable-func is supplied, it is equivalent to being always applicable.
(defun alwaysApplicable(browser-node browsername)
               t)
:justification{:left or :right [:left]}
Sets the column output to be either left or right justified
:print-values{Lisp list of STRINGS}
The print-values option is only applicable for boolean and enumeration columns.
  • :boolean-column
    the first string in the list is used to represent the display string for true results, while the second is used to represent false conditions. The supplied list must have two entries.
  • :enum-column
    The supplied list is used to determine the print value associated with each enumerator. The first string in the list corresponds to the enumerator of value 0, the second to the enumerator 1, and so on.

Return Value:
t - Table definition successfully added
nil - Invalid parameters supplied or table by that name already exists.

Example:
(defun get-write-status(obj name)
  (if (obj-is-writable obj)
    t
    nil
  )
)

(setq file-type-list '("Data" "Dir" "Executable" "Linked"))

(sd-browser-define-table "my-browser" :table-name "table1"
       :column-definition
         `((:label "FileType" :initial-width 15 :type
            :enum-column :display-func get-file-type
            :print-values ,file-type-list)
           (:label "Writeable" :type :boolean-column
            :display-func get-write-status :print-values ("Yes" "No"))
           (:label "Size" :display-func get-size
            :type :integer-column :initial-width 10)
           (:label "Owner" :type :string-column
            :display-func get-owner
            :justification :left
            )
          )
)

(sd-browser-define-table "my-browser" :table-name "table2"
       :with-name-column t
       :column-definition
         `((:label "FileType" :initial-width 7 :type
            :enum-column :display-func get-file-type
            :print-values ,file-type-list)))

Function Index Top of Page

SD-BROWSER-SET-ACTIVE-TABLE  [function]

(sd-browser-set-active-table name :table-name table)
Description:
Make the given table definition the active table in browser name . This function allows you to choose which of the tables associated with a browser should be used to display information in the browser table.

Parameters:
name {STRING} - Name of the browser to operate on
:table-name {STRING[name of browser]}

Return Value:
t - success
nil - browser or specified table-name does not exist.

Example:
(sd-browser-set-active-table "my-browser" :table-name "table1") 
         

Function Index Top of Page

SD-BROWSER-DELETE-TABLE  [function]

(sd-browser-delete-table name :table-name table
Description:
This utility will delete the table definition attached to browser name. If you destroy a browser, all tables will be deleted for you automatically.

Parameters:
name {STRING} - Name of the browser
:table-name {STRING[browser name]}
If no name is specified, the browser name will be used. If the currently active table is deleted, then no table will be active until another is explicitly set.

Return Value:
t - success
nil - browser or given table does not exist

Example:
(sd-browser-delete-table "my-browser" :table-name "table2"

Function Index Top of Page

SD-BROWSER-REGISTER-IMAGE  [function]

(sd-browser-register-image name
                           :image       image-name
                           :filename    filename
                           :type        type
                           :foreground  color
                           :background  color)
Description:
Registers an image with name image-name to be used as primary or secondary image.
The image can be either of format BMP, XPM or XBM. The image will automatically be scaled to the size specified in sd-create-graphical-browser.
Note: It is absolutely necessary to register images with a graphical browser before they can be used as primary or secondary pixmaps.

Parameters:
name {STRING} - Name of the browser
:image {STRING} - Name of image to be used in interrogators
:filename {STRING}
Absolute or relative (according to Creo Elements/Direct Modeling's search directories) path to an image file. For supported image formats see Description.
:type {KEYWORD [:primary-image]} - One of the following:
:primary-image - register image to be used as primary image
:secondary-image - register image to be used as seconadry image
:both-image - register image to be used as primary or secondary image
Note: For compatibility reasons the parameter :primary-pixmap, secondary-pixmap and :both-pixmaps are still valid.
:foreground {STRING} - Foreground color of an XBM image. Not used else.
:background {STRING} - Background color of an XBM image. Not used else.

Return Value:
image {STRING} - Name of registered image
nil - failure

Function Index Top of Page

SD-BROWSER-SET-STATUS-TEXT  [function]

(sd-browser-set-status-text name
                            :value   text-value
                            :color   color
                            :type    type)
Description:
Changes the optional status text displayed above the tree or table.

Parameters:
name {STRING} - Name of the browser
:value {STRING} - New value to be displayed
:color {STRING ["black"]} - Text color
:type {KEYWORD [:tree]} - One of the following:
:tree - Status text above tree
:table - Status text above table

Return Value:
t - success
nil - failure

Function Index Top of Page

SD-BROWSER-GET-STATUS-TEXT  [function]

(sd-browser-get-status-text name :type type)
Description:
Retrieves the value of the optional status text displayed above the tree or table.

Parameters:
name {STRING} - Name of the browser
:type {KEYWORD [:tree]} - One of the following:
:tree - Status text above tree
:table - Status text above table

Return Value:
text-value {STRING} - the currently displayed text
nil - failure

Function Index Top of Page

SD-SHOW-GRAPHICAL-BROWSER  [function]

(sd-show-graphical-browser name  
                           :position     position
                           :tabOnly      tab-only)
                           :setTabActive set-tab-active)
    
Description:
Show a graphical browser with name name . If the tree attached to the browser has been modified since the last display of the browser, the browser will be updated before being displayed. If there was a mapToggle associated with this browser, it will be set.
If the browser is docked, the browser tab becomes the active tab and therefore the browser becomes visible. If the browser was floating, its dialog shell will appear at the previous screen location or at position if this parameter is given.

Parameters:
name {STRING} - Name of the browser to show
:position {quoted LIST}
When specified, the browser is attached as defined. Otherwise, it is placed at top right corner of SD window. (See sd-show-display-table documentation for supported position options).
:tabOnly {BOOLEAN [nil]}
This parameter is important in combination with :inclTab of sd-hide-graphical-browser. Use a call to this function with this parameter set whenever your browser is associated with an add-on application which employs an application button. When the user switches into your add-on application, call this function with :tabOnly set to t to make the browser reappear in the state as it was before when the user left your add-on application. If the browser was docked before, it will appear docked again. If the browser was floating, nothing will happen (no tab will appear, no floating browser will appear automatically).
Note: :tabOnly and :inclTab maintain the visibility of your browser in the browser bar context menu. A hidden browser with :inclTab set to t is no longer accessible from the context menu.
:setTabActive {BOOLEAN [nil]}
The parameter is only evaluated when :tabOnly is set to t. If set to t the tab is activated.

Return Value:
t - success
nil - browser UI does not exist.

Example:
(sd-show-graphical-browser "parcel-gbrowser" :position 
                   '("TASK-DS" :LEFTCENTER 0 0 ))

Function Index Top of Page

SD-HIDE-GRAPHICAL-BROWSER  [function]

(sd-hide-graphical-browser name
                           :ignore-pin  ignore-pin
                           :inclTab     incl-tab)
    
Description:
Hide a graphical browser. If there was a mapToggle associated with this browser, it will be reset when the browser is hidden.
Nothing will happen to a docked browser unless the parameter :inclTab is given.

Parameters:
name {STRING} - Name of the browser to hide
:ignore-pin {BOOLEAN [nil]}
If ingore-pin is not nil, the browser will be closed regardless of whether it is pinned. If nil, the browser will only be closed if not pinned.
:inclTab {BOOLEAN [nil]}
This parameter is important in combination with :tabOnly of sd-show-graphical-browser. See there for a more detailed explanation.
If this parameter is given, even a docked browser will disappear including its tab AND its entry in the browser bar tab context menu which usually allows the user to access all available browsers even if they are not docked.

Return Value:
t - success
nil - Browser does not exist.

Example:
(sd-hide-graphical-browser "parcel-gbrowser" :ignore-pin nil)

Function Index Top of Page

SD-DOCK-GRAPHICAL-BROWSER  [function]

(sd-dock-graphical-browser name :show show-flag)
Description:
Docks a floating graphical browser into the Browser Bar. If the parameter :show is set to true, the browser tab becomes the active tab (browser is visible).

Parameters:
name {STRING} - Name of the browser to be docked
:show {BOOLEAN [t]} - Make browser tab active or not

Return Value:
t - success
nil - failure

Function Index Top of Page

SD-UNDOCK-GRAPHICAL-BROWSER  [function]

(sd-undock-graphical-browser name 
                             :show      show-flag
                             :position  position)
Description:
Undocks a docked graphical browser from the Browser Bar and displays it floating in a separate dialog shell if parameter :show is set to T. It will appear at its last screen position if :position is not given, otherwise at the location given in :position.

Parameters:
name {STRING} - Name of the browser to be undocked
:show {BOOLEAN [t]} - Shows the browser if set, otherwise hides it
:position {LIST} - See here for details

Return Value:
t - success
nil - failure

Function Index Top of Page

SD-GRAPHICAL-BROWSER-DOCKED-P  [function]

(sd-graphical-browser-docked-p name)
Description:
Returns whether the browser is docked in the Browser Bar or floating.

Parameters:
name {STRING} - Name of the browser to be docked

Return Value:
t - browser is docked
nil - browser is floating (might be hidden as well)

Function Index Top of Page

SD-SET-GRAPHICAL-BROWSER-PARENT  [function]

(sd-set-graphical-browser-parent name dialog parent
                                 :dockable dockable-p)
Description:
Defines the immediate parent widget parent which hosts the browser control when the browser is undocked. The parent widget itself must be a resizable grid area which again must be a descendant of a resizable dialog shell dialog.

Parameters:
name {STRING} - Name of the browser
dialog {STRING} - Basename of the dialog shell which hosts the floating browser. The suffix "-DS" has to be omitted.
parent {STRING} - Name of the hosting resizable grid area.
dockable {BOOLEAN[t]} - The browser can be docked in the browser bar when dockable is t. Otherwise the browser control becomes floating and can't be docked anymore. If the browser control is docked the hosting dialog shell will be hidden.

Return Value:
t - success
nil - error

Function Index Top of Page

SD-IS-GRAPHICAL-BROWSER-VISIBLE-P  [function]

(sd-is-graphical-browser-visible-p name)
Description:
Returns the state of visibility for browser name.

Parameters:
name {STRING} - Name of the browser

Return Value:
t - browser is visible
nil - browser is hidden

Function Index Top of Page

SD-LIST-GRAPHICAL-BROWSERS  [function]

(sd-list-graphical-browsers)
Description:
Provide a list of all existing graphical browsers.

Parameters:
None

Return Value:
{LIST} - List of graphical browser names

Example:
(sd-list-graphical-browsers)
 => ("shared-gbrowser" "parcel-gbrowser")
    

Function Index Top of Page

SD-BROWSER-PRINT-TREE  [function]

(sd-browser-print-tree name  
                       :file        file
                       :mode        mode
                       :start-node  node)
Description:
Output the browser tree to a file. This function will write out an text representation of the tree to file starting at the node. Only those items that are currently displayed in the browser will be printed.

Parameters:
name {STRING} - Name of the browser to print
:file {STRING [nil]}
The name of the file to send the output to. If no file is specified, a system generated file will be created, and will be set as the return value of this function.
:mode {Keyword [:write]} - write mode to open file
  • :write - open the new file specified by file
  • :overwrite - overwrite contents when file exists
The mode controls how the contents will be written to the file. If :overwrite is specified, the contents will replace the previous contents of the file (as long as it is writable).
:start-node {BrowserNode struct [nil]}
The BrowserNode which to start the printing process on. If no BrowserNode is provided, then the start node will be the root node of the tree.

Return Value:
{STRING} - name of the file which output was written to.
nil - Invalid parameters supplied, or write failed.

Example:
(sd-browser-print-tree "parcel" :file "c:/temp/browser_out" 
   => "c:/temp/browser_out"

Function Index Top of Page

SD-SET-GRAPHICAL-BROWSER-HELP-ACTION  [function]

(sd-set-graphical-browser-help-action name :help-action help-action)
Description:
A browser's help action is triggered if the help item from the browser's context menu or the help button of the undocked browser dialog is clicked. This function allows to overwrite the default help action.

Parameters:
name {STRING} - Name of the browser
:help-action {LISP FORM [nil]}
Lisp form which is assigned to the help action triggers. For nil the default help action is reassigned.

Return Value:
t - Action assigned successfully
nil - Action not assigned.

Example:
(sd-set-graphical-browser-help-action "parcel" :help-action '(pprint "Calling for help!"))
[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