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.

• Basic Constructors and Destructors
  • sd-create-BrowserNode
  • BrowserNode struct
  • sd-get-BrowserNode-struct
  • sd-is-pseudo-folder-node-p
  • sd-create-browser-tree
  • sd-create-graphical-browser
  • sd-destroy-browser-tree
  • sd-destroy-graphical-browser
• Browser Behaviours
  • sd-browser-add-interrogator
  • sd-browser-click-action
  • sd-browser-exec-cmd
  • sd-browser-set-border-mode
  • sd-query-browser
  • sd-browser-add-popup-entry
• Table functions
  • sd-browser-define-table
  • sd-browser-set-active-table
  • sd-browser-delete-table
• Utility/Convienence functions
  • sd-browser-register-image
  • sd-browser-set-status-text
  • sd-browser-get-status-text
  • sd-show-graphical-browser
  • sd-hide-graphical-browser
  • sd-dock-graphical-browser
  • sd-undock-graphical-browser
  • sd-graphical-browser-docked-p
  • sd-set-graphical-browser-parent
  • sd-is-graphical-browser-visible-p
  • sd-list-graphical-browsers
  • sd-browser-print-tree
  • sd-set-graphical-browser-help-action
• Browser Examples
  • A dummy Example

• Browser Views
• Browser Queries

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

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:

• BrowserNode-objPname: returns the print name of this node
• BrowserNode-objPath: returns the full path name of this node
• BrowserNode-objClientData: returns the client data attached to this node.
• BrowserNode-NodeID: returns the symbolic name for this node

Notes:

• All access functions provide read only access into the BrowserNode struct.
• The symbolic name for the root node of a data tree is always :root.
• If you have access to the symbolic name of a BrowserNode, you can retrieve its structure using the sd-get-browsernode-struct function.

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
    

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

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

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) 

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.

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

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

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.

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)

         

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)
    

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.

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)

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

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

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.

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

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:

• Under what conditions should this menu entry be displayed.
• Under what conditions should this menu entry be applicable (sensitive)
• What action to perform if menu entry is selected.
• Whether the toggle button is checked or unchecked.

Note:

• As with other interrogators, the supplied lisp function must be bound at the time a menu is added.
• Each menu interrogator will be passed two parameters: the BrowserNode struct of the object over which the popup menu action occurred, and the Browser Name, respectively.
• If you specified a value for the :string-client-data parameter, each interrogator function will be passed three parameters: BrowserNode struct, Browser Name and the specified string client data.
• The browser's popup menu is accessible by clicking button3.

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)

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

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

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"

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

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

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

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

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)

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

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

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)

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

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

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

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"

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