Fluent UI

Introduction

Ribbon Tab

sd-fluentui-add-ribbon-tab

sd-fluentui-set-active-ribbon-tab

sd-fluentui-show-ribbon-tab-in-application

sd-fluentui-hide-ribbon-tab-in-application

sd-fluentui-recalc-ribbon-layout

sd-fluentui-ribbon-tab-exist-p

sd-fluentui-destroy-ribbon-tab

sd-fluentui-create-addon-context

sd-fluentui-show-addon-context-tabs

Existing Creo Elements/Direct ribbon tabs

Ribbon Group

sd-fluentui-add-ribbon-group

Ribbon Controls

sd-fluentui-add-ribbon-button

sd-fluentui-add-ribbon-separator

sd-fluentui-add-help-button

sd-fluentui-remove-help-button

Status Bar

Utilities

Introduction

Along with the Fluent UI definition come the ribbon tabs, the quick access toolbar and the status bar. Read more about the Fluent UI in the Fluent UI Concepts.

In Creo Elements/Direct Modeling there exist two different instances of a ribbon: one for base modeler along with all applications and modules and one which is explicitely available in Creo Elements/Direct Annotation. This means that for Creo Elements/Direct Annotation the ribbon tabs, quick access toolbar and status bar must be defined in parallel to everything which is done for Creo Elements/Direct Modeling and the other applications and modules. It also means that for any creation of a ribbon element it must be specified, in which of the two ribbon instances it should be created.

It is not possible to create an additional ribbon instance. But it is possible to create additional ribbon tabs and change the visibility of existing ribbon tabs in certain applications.

When switching between different applications the visibility of ribbon tabs is changed according to the specification in the ribbon tab definition. Nothing needs to be done programmatically.

To define the contents of a ribbon tab available commands need to be defined. Read more about the concept of available commands. Every control action is defined via a single available command. The command definition comes along with a title label, description, icon and enable status. All these informations are used to define a ribbon control but can be overwritten. This way for instance a label can be changed compared to the existing title in the available command.
It is also possible to directly specify an action when defining a ribbon control. This mechanism could be used for testing purposes but should not be used for writing add-on functionality. Every available command can be used for customization of ribbon controls. If a ribbon control action is specified directly in the ribbon control definition a customization is not possible.

Note: To make use of the available commands the available commands files must be loaded before the ribbon contents are defined. Otherwise the available commands are unknown and the control action will be empty. Read more on loading customization files here.

Example: A detailed example for a ribbon tab definition can be found in file fluent_ui_lsp.html.

SD-FLUENTUI-ADD-RIBBON-TAB  [function]

(sd-fluentui-add-ribbon-tab name 
                            :annotationRibbon annotationRibbon
                            :application application
                            :title title
                            :position position
                            :appendUtilitiesGroup appendUtilitiesGroup
                            :addonContext addonContext)

Description:

Adds a new ribbon tab to the current ribbon bar.

Parameters:

name {STRING}

Internal name of the tab for later reference. Tab name must be unique.

:annotationRibbon {BOOLEAN [nil]}

Adds the tab to the Modeling or Annotation ribbon. By default, the tab will be added to the Modeling ribbon. Read here for more information.

:application {STRING ["SolidDesigner"]}

Name of the application the new ribbon tab should be created for. By default, the ribbon tab will be visible in Modeling only.

:title {STRING}

Specifies a title of the tab that will be shown in the ribbon bar.

:position {FIXNUM or KEYWORD [:end] or STRING}

Specify the position where to insert the tab. This can be either:

• <number> - Zero based position within the ribbon. 0 corresponds to :beginning.
• :beginning - Insert the tab at the beginning of the ribbon.
• :end - Insert the tab at the end of the ribbon.
• <string> - Name of a tab created with sd-fluentui-add-ribbon-tab. The new ribbon tab will be shown before this tab.

:appendUtilitiesGroup {BOOLEAN [t]}

Specifies whether or not the standard group of utilities commands should be shown with the tab or not.

:addonContext {STRING}

Optional name of an addon context created with sd-fluentui-create-addon-context. If specified the ribbon tab is assigned to the addon context. All ribbon tabs which blong to one and the same addon context are grouped together.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-add-ribbon-tab "SDTAB"
  :title "New Tab")

SD-FLUENTUI-SET-ACTIVE-RIBBON-TAB  [function]

(sd-fluentui-set-active-ribbon-tab name 
                                   :annotationRibbon annotationRibbon)

Description:

Activates ribbon tab in the current ribbon bar.

Parameters:

name {STRING}

Name of the ribbon tab which should be activated.

:annotationRibbon {BOOLEAN [nil]}

Specifies whether or not the tab is available in the Modeling or Annotation ribbon. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-set-active-ribbon-tab "SDTAB")

SD-FLUENTUI-SHOW-RIBBON-TAB-IN-APPLICATION  [function]

(sd-fluentui-show-ribbon-tab-in-application name application
                                            :annotationRibbon annotationRibbon)

Description:

Shows a certain ribbon tab in a specific application.

Parameters:

name {STRING}

Name of the tab created with function sd-fluentui-add-ribbon-tab.

application {STRING}

Name of the application the ribbon tab should be shown in.

:annotationRibbon {BOOLEAN [nil]}

Specifies whether or not the tab is available in the Modeling or Annotation ribbon. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-show-ribbon-tab-in-application "SDANALYSE" "3D Documentation")

SD-FLUENTUI-HIDE-RIBBON-TAB-IN-APPLICATION  [function]

(sd-fluentui-hide-ribbon-tab-in-application name application
                                            :annotationRibbon annotationRibbon)

Description:

Hides a certain ribbon tab in a specific application.

Parameters:

name {STRING}

Name of the tab created with function sd-fluentui-add-ribbon-tab.

application {STRING}

Name of the application the ribbon tab should not be shown in.

:annotationRibbon {BOOLEAN [nil]}

Specifies whether or not the tab is available in the Modeling or Annotation ribbon. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-hide-ribbon-tab-in-application "SDVIEW" "3D Documentation")

SD-FLUENTUI-ADD-RIBBON-GROUP  [function]

(sd-fluentui-add-ribbon-group name 
                              :parent parent
                              :annotationRibbon annotationRibbon
                              :title title
                              :slot slot
                              :launchButtonAvailCmd launchButtonAvailCmd)

Description:

Adds a new ribbon group to a ribbon tab.

Parameters:

name {STRING}

Internal name of the group for later reference. Group name must be unique within a ribbon tab.

:parent {STRING}

Name of the tab to which the group should be added. This is a mandatory variable.

:annotationRibbon {BOOLEAN [nil]}

Adds the group to a tab available in the Modeling or Annotation ribbon. Read here for more information.

:title {STRING}

Specifies a title of the group that appears in the ribbon tab.

:slot {FIXNUM [-1]}

The slot number defines the position of the group in the ribbon tab. The ribbon tab is filled left to right with increasing slot numbers. The position of the group depends only on the slot number not on when it is created.

:launchButtonAvailCmd {List of three STRINGs}

Specifies an available command via a list of "Application" "Group" and "Command". This parameter is often used to show settings specific to commands displayed in this ribbon group. Read more about the definition of available commands here.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-add-ribbon-group "SDGROUP"
  :parent "SDTAB"
  :title "New Group"
  :launchButtonAvailCmd '("SolidDesigner" "Settings" "3D Object Settings")
  )

SD-FLUENTUI-ADD-RIBBON-SEPARATOR  [function]

(sd-fluentui-add-ribbon-separator :parent parent
                                  :annotationRibbon annotationRibbon
                                  :label label)

Description:

Adds a separator either to a ribbon group between ribbon buttons or to a ribbon button menu.
To add a separator to a ribbon group between ribbon buttons, the specification of the parent contains only a list of tab name and group name. In this case, the specification of label will be ignored.
To add a separator to a ribbon button menu, the specification of the parent contains a list of tab name, group name and a button name. In this case, a label specification will be displayed as a title of a separator if given.

Parameters:

:parent {List of STRINGs}

List of a tab name, a group name and possibly a button name. This is a mandatory variable.

:annotationRibbon {BOOLEAN [nil]}

Adds separator to a parent available in the Modeling or Annotation ribbon. Read here for more information.

:label {STRING [nil]}

If specified, a title is displayed in a ribbon button menu.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-add-ribbon-separator
  :parent '("SDTAB" "SDGROUP")
  )
  
(sd-fluentui-add-ribbon-separator
  :parent '("SDTAB" "SDGROUP" "SDBUTTON")
  :label "Properties"
  )  

SD-FLUENTUI-ADD-RIBBON-BUTTON  [function]

(sd-fluentui-add-ribbon-button :parent parent
                               :annotationRibbon annotationRibbon
                               :name name
                               :splitButton splitButton
                               :largeImage largeImage
                               :availCmd availCmd
                               :pushAction pushAction
                               :contents contents
                               :label label
                               :image image
                               :description description
                               :enable enable
                               :separator separator)

Description:

Adds a new Button to a ribbon group.

Parameters:

:parent {List of STRINGs}

List of tab name and group name and perhaps button name. This is a mandatory variable.

:annotationRibbon {BOOLEAN [nil]}

Adds the button to a parent available in the Modeling or Annotation ribbon. Read here for more information.

:name {STRING}

Name of the button that it can be referenced by later using parent parameter, for instance for adding additional entries in ribbon button menu.

:splitButton {BOOLEAN [nil]}

Specifies whether the new button will be displayed with two areas or not. The icon area can be pressed separately to start the default action. A click to the second area opens the menu.

:largeImage {BOOLEAN [nil]}

Specifies whether the button will be displayed as a large button or not.

:availCmd {List of three STRINGs}

If an available command is given then it must be an existing command and can be specified via a list of "Application" "Group" "Command". Read more about the definition of available commands here.
If an available command is specified, almost all other options are derived from it. But more options, such as a label, can be specified to override the command's properties.

:pushAction {Lisp Form}

This form will be executed if the user clicks this button. If not specified the action from the availCmd is taken. This option should not be used as default. Preferred is to use the availCmd to specify the button action. Reason is that any pushAction is not considered in the customization process of the ribbon definition. Only available commands are used as basis for any customization.

:contents {List of Lists}

A list of buttons that are mapped as a menu to this button. Each list element can contain the same options as specified for this function with the exception of parent, splitButton and largeButton.

:label {STRING}

Button label string. If not specified, label from availCmd is taken. If label appears as a single list element in contents, the button is displayed as a string separator.

:image {STRING}

Image file name. If not given, image from availCmd is taken.

:description {STRING}

A descriptive text of the button action or menu contents. If not specified, the description from the availCmd is taken.

:enable {LISP expression}

This can be either a single LISP global variable or a single LISP expression. If the variable or expression evaluates to T (true) at runtime, this button action is accessible by the user otherwise this button will be grayed out. If no enable expression is given for a button, the enable-expression from the specified availCmd is taken. If the availCmd is not specified the button is accessible all the time.

:separator {BOOLEAN [nil]}

Only valid within contents. If t, a separator will be added below the previous button.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-add-ribbon-button 
  :parent '("SDTAB" "SDGROUP")
  :availCmd '("SolidDesigner" "Part and Assy" "Copy Part/Assy")
  )

(sd-fluentui-add-ribbon-button 
  :parent '("SDTAB" "SDGROUP")
  :name "SDBUTTON"
  :splitButton t
  :largeImage t
  :label "Split Button"
  :contents
  `(
     (:label "Assembly"
      :availCmd ("SolidDesigner" "Part and Assy" "New Assembly"))
     (:label "Container"
      :availCmd ("SolidDesigner" "Part and Assy" "New Container"))
     ))

(sd-fluentui-add-ribbon-button 
  :parent '("SDTAB" "SDGROUP" "SDBUTTON")
  :availCmd '("SolidDesigner" "Part and Assy" "Rename Part/Assy")
  )

SD-FLUENTUI-ADD-HELP-BUTTON  [function]

(sd-fluentui-add-help-button :annotationRibbon annotationRibbon
                             :availCmd availCmd)

Description:

Adds a new button to the end of the help menu on the right side of the ribbon bar.

Parameters:

:annotationRibbon {BOOLEAN [nil]}

Adds a new help button to the help menu available in the Modeling or Annotation ribbon. Read here for more information.

:availCmd {List of three STRINGs}

Specifies an available command via a list of "Application" "Group" and "Command". Read more about the definition of available commands here.

Return Value:

t - success

nil - failure

SD-FLUENTUI-REMOVE-HELP-BUTTON  [function]

(sd-fluentui-remove-help-button :annotationRibbon annotationRibbon
                                :availCmd availCmd)

Description:

Removes a button to the end from the help menu on the right side of the ribbon bar.

Parameters:

:annotationRibbon {BOOLEAN [nil]}

Removes a help button from the help menu available in the Modeling or Annotation ribbon. Read here for more information.

:availCmd {List of three STRINGs}

Specifies an available command via a list of "Application" "Group" and "Command". The button created for this available command is removed from the help menu. Read more about the definition of available commands here.

Return Value:

t - success

nil - failure

SD-FLUENTUI-RECALC-RIBBON-LAYOUT  [function]

(sd-fluentui-recalc-ribbon-layout :annotationRibbon annotationRibbon)

Description:

Updates the ribbon bar layout. To ensure a good performance when adding components to the ribbon bar the ribbon bar layout is not updated automatically. So, it is good practise to call sd-fluentui-recalc-ribbon-layout when the ribbon bar modification is finished.

Parameters:

:annotationRibbon {BOOLEAN [nil]}

Updates the layout of the Modeling or Annotation ribbon bar. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-recalc-ribbon-layout)

SD-FLUENTUI-RIBBON-TAB-EXIST-P  [function]

sd-fluentui-ribbon-tab-exist-p name
                               :annotationRibbon annotationRibbon

Description:

Predicate to determine whether a ribbon tab of specified name exists in Modeling or Annotation ribbon or not.

Parameters:

name {STRING}

Name of ribbon tab

:annotationRibbon {BOOLEAN [nil]}

Check whether the tab should exist in Modeling or Annotation ribbon. Read here for more information.

Return Value:

t - tab with specified name exists

nil - tab with specified name doesn't exist

Example:

(sd-fluentui-ribbon-tab-exist-p "SDTAB")

SD-FLUENTUI-DESTROY-RIBBON-TAB  [function]

sd-fluentui-destroy-ribbon-tab name
                               :annotationRibbon annotationRibbon

Description:

Destroy a ribbon tab. This should be done in any case when a module or application is deactivated.

Parameters:

name {STRING}

Name of an existing ribbon tab which was created with sd-fluentui-add-ribbon-tab.

:annotationRibbon {BOOLEAN [nil]}

Destroy the ribbon tab which was created in Modeling or Annotation ribbon. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-destroy-ribbon-tab "SDTAB")

SD-FLUENTUI-CREATE-ADDON-CONTEXT  [function]

(sd-fluentui-create-addon-context name
                                  :annotationRibbon annotationRibbon

Description:

Creates an addon context. This context is used to add additional ribbon tabs to the base modeling application and group them together. Addon context can be shown or hidden as a group. They are also visually grouped together.

Parameters:

name {STRING}

Internal name of the context for later reference. The context name must be unique.

:annotationRibbon {BOOLEAN [nil]}

Create the context for Modeling or Annotation ribbon. By default, the context will be created for the Modeling ribbon. Read here for more information.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-create-addon-context "MY-MODULE")

(sd-fluentui-add-ribbon-tab "MY-MODULE1"
  :title "My Module 1"
  :addonContext "MY-MODULE")

(sd-fluentui-add-ribbon-tab "MY-MODULE2"
  :title "My Module 2"
  :addonContext "MY-MODULE")

See Also:

sd-fluentui-add-ribbon-tab

sd-fluentui-show-addon-context-tabs

SD-FLUENTUI-SHOW-ADDON-CONTEXT-TABS  [function]

(sd-fluentui-show-addon-context-tabs name
                                     :annotationRibbon annotationRibbon
                                     :show show-or-hide

Description:

Show or hide all ribbon tabs which belong to an addon context.

Parameters:

name {STRING}

Internal name of the context for to show or hide all ribbon tabs from.

:annotationRibbon {BOOLEAN [nil]}

Show the tabs which are related to the context in the Modeling or Annotation ribbon. By default, the tabs will be added to the Modeling ribbon. Read here for more information.

:show {BOOLEAN [t]}

Show or hide the tabs which are related to the addon context.

Return Value:

t - success

nil - failure

Example:

(sd-fluentui-show-addon-context-tabs "MY-MODULE")

Existing Creo Elements/Direct ribbon tabs