Menus, Commands, and Pop-up Menus
This section describes the methods provided by Creo Object TOOLKIT C++ to create and modify menus, buttons, and pop-up menus in the Creo user interface.
Refer to the section Ribbon Tabs, Groups, and Menu Items for more information. Also, refer to the Creo Parametric Help for more information on customizing the ribbon user interface.
Introduction
The Creo Object TOOLKIT C++ classes enable you to supplement the Creo ribbon user interface.
Once the Creo Object TOOLKIT C++ application is loaded, you can add a new group to an existing tab or create a new tab using the Customize Ribbon tab in the Creo Parametric Options dialog box in Creo Parametric. You will not be able to modify the groups that are defined by Creo Parametric. If the translated messages are available for the newly added tabs or groups, then Creo Parametric will use them by searching for the same string in the list of sting based messages loaded.
You can customize the ribbon user interface only for a particular mode in Creo Parametric. For example, if you customize the ribbon user interface and save it to the toolkitribbonui.rbn file in the Part mode, then on loading Creo Parametric the customized user interface will be visible only in the Part mode. To view a particular tab or group in all the modes, you must customize the ribbon user interface and save the toolkitribbonui.rbn file in each mode. Refer to the Creo Parametric Fundamentals Help for more information on customizing the ribbon.
Menu Bar Definitions
•  Menu—A menu, such as the File menu, or a sub-menu, such as the Manage File menu under the File menu.
•  Menu button—A named item in a group or menu that is used to launch a set of instructions.
•  Pop-up menu—A menu invoked by selection of an item in the Creo Parametric graphics window.
•  Command—A procedure in Creo Parametric that may be activated from a button.
Menu Buttons and Menus
The following methods enable you to add new menu buttons in any location on the Ribbon user interface.
Methods Introduced:
  • pfcSession::UICreateCommand
    		•
  • pfcSession::UICreateMaxPriorityCommand
    		•
  • pfcUICommandActionListener::OnCommand
    		•
    The method pfcSession::UICreateCommand creates a pfcUICommand object that contains a pfcUICommandActionListener. You should override the pfcUICommandActionListener::OnCommand method with the code that you want to execute when the user clicks a button.
    The method pfcSession::UICreateMaxPriorityCommand creates a pfcUICommand object having maximum command priority. The priority of the action refers to the level of precedence the added action takes over other Creo Parametric actions. Maximum priority actions dismiss all other actions except asynchronous actions.
    Maximum command priority should be used only in commands that open and activate a new model in a window. Create all other commands using the method pfcSession::UICreateCommand.
    The listener method pfcUICommandListener::OnCommand is called when the command is activated in Creo Parametric by pressing a button.
    Designate the command using the function pfcUICommand::Designate and add a button to the ribbon user interface using the using the Customize Ribbon tab in the Creo Parametric Options dialog box. This operation binds the command to the button.
    Finding Creo Parametric Commands
    This method enables you to find existing Creo Parametric commands in order to modify their behavior.
    Method Introduced:
  • pfcSession::UIGetCommand
    		•
    The method pfcSession::UIGetCommand returns a pfcUICommand object representing an existing Creo Parametric command. The method allows you to find the command ID for an existing command so that you can add an access function or bracket function to the command. You must know the name of the command in order to find its ID.
    To find the name of an action command, click the corresponding icon on the ribbon user interface and then check the last entry in the trail file. For example, for the Save icon, the trail file will have the corresponding entry: 
    ~ Command `ProCmdModelSave`
    The action name for the Save icon is ProCmdModelSave. This string can be used as input to pfcSession::UIGetCommand to get the command ID.
    You can determine a command ID string for an option without an icon by searching through the resource files located in the <creo_loadpoint>\<datecode>\Common Files\text\resources directory. If you search for the menu button name, the line will contain the corresponding action command for the button.
    Access Listeners for Commands
    These methods allow you to apply an access listener to a command. The access listener determines whether or not the command is visible at the current time in the current session.
    Methods Introduced:
  • pfcActionSource::AddActionListener
    		•
  • pfcUICommandAccessListener::OnCommandAccess
    		•
    Use the method pfcActionSource::AddActionListener to register a new pfcUICommandAccessListener on any command (created either by an application or Creo Parametric). This listener will be called when buttons based on the command might be shown.
    The listener method pfcUICommandAccessListener::OnCommandAccess allows you to impose an access function on a particular command. The method determines if the action or command should be available, unavailable, or hidden.
    The potential return values are listed in the enumerated type pfcCommandAccess and are as follows:
    •  pfcACCESS_REMOVE—The button is not visible and if all of the menu buttons in the containing menu possess an access function returning pfcACCESS_REMOVE, the containing menu will also be removed from the Creo Parametric user interface.
    •  pfcACCESS_INVISIBLE—The button is not visible.
    •  pfcACCESS_UNAVAILABLE—The button is visible, but gray and cannot be selected.
    •  pfcACCESS_DISALLOW—The button shows as available, but the command will not be executed when it is chosen.
    •  pfcACCESS_AVAILABLE—The button is not gray and can be selected by the user. This is the default value.
    Bracket Listeners for Commands
    These methods allow you to apply a bracket listener to a command. The bracket listener is called before and after the command runs, which allows your application to provide custom logic to execute whenever the command is selected.
    Methods Introduced:
  • pfcActionSource::AddActionListener
    		•
  • pfcUICommandBracketListener::OnBeforeCommand
    		•
  • pfcUICommandBracketListener::OnAfterCommand
    		•
    Use the method pfcActionSource::AddActionListener to register a new pfcCommand::UICommandBracketListener on any command (created either by an application or Creo Parametric). This listener will be called when the command is selected by the user.
    The listener methods pfcUICommandBracketListener::OnBeforeCommand and pfcUICommandBracketListener::OnAfterCommand allow the creation of functions that will be called immediately before and after execution of a given command. These methods are used to add the business logic to the start or end (or both) of an existing Creo Parametric command.
    The method pfcUICommandBracketListener::OnBeforeCommand could also be used to cancel an upcoming command. To do this, throw a pfcXCancelProEAction exception from the body of the listener method using pfcXCancelProEAction::Throw.
    Designating Commands
    Using Creo Object TOOLKIT C++ you can designate Creo Parametric commands. These commands can later appear in the Creo Parametric ribbon user interface.
    To add a command you must:
    1. Define or add the command to be initiated on clicking the icon in the Creo Object TOOLKIT C++ application.
    2. Optionally designate an icon button to be used with the command.
    3. Designate the command to appear in the Customize Ribbon tab in the Creo Parametric Options dialog box.
    Note
    Refer to the chapter on Ribbon Tabs, Groups, and Menu Items for more information. Also, refer to the Creo Parametric Help for more information on customizing the Ribbon User Interface.
    4. Save the configuration in Creo Parametric so that changes to the ribbon user interface appear when a new session of Creo Parametric is started.
    Command Icons
    Method Introduced:
  • pfcUICommand::SetIcon
    		•
    The method pfcUICommand::SetIcon allows you to designate an icon to be used with the command you created. The method adds the icon to the Creo Parametric command. Specify the name of the icon file, including the extension as the input argument for this method. A valid format for the icon file is a standard .GIF, .JPG, or.PNG. PTC recommends using .PNG format. All icons in the Creo Parametric ribbon are either 16x16 (small) or 32x32 (large) size. The naming convention for the icons is as follows:
    •  Small icon—<iconname.ext>
    •  Large icon—<iconname_large.ext>
    Note
    •  The legacy naming convention for icons <icon_name_icon_size.ext> will not be supported in future releases of Creo Parametric. The icon size was added as a suffix to the name of the icon. For example, the legacy naming convention for small icons was iconname16X16.ext. It is recommended to use the standard naming conventions for icons, that is, iconname.ext or iconname_large.ext.
    •  While specifying the name of the icon file, do not specify the full path to the icon names.
    The application searches for the icon files in the following locations:
    •  <creo_loadpoint>\<datecode>\Common Files\text\resource
    •  <Application text dir>\resource
    •  <Application text dir>\<language>\resource
    The location of the application text directory is specified in the registry file.
    Commands that do not have an icon assigned to them display the button label.
    You may also use this method to assign a small icon to a button. The icon appears to the left of the button label.
    Designating the Command
    Method Introduced:
  • pfcUICommand::Designate
    		•
    This method allows you designate the command as available in the Customize Ribbon tab in the Creo Parametric Options dialog of Creo Parametric. After a Creo Object TOOLKIT C++ application has used the method pfcUICommand::Designate on a command, you can add the button associated with this command into the Creo Parametric ribbon user interface.
    If this method is not called, the button will not be visible in the Toolkit Commands list in the Customize Ribbon tab in the Creo Parametric Options dialog of Creo Parametric.
    The arguments to this method are:
    •  Label—The message string that refers to the icon label. This label (stored in the message file) identifies the text seen when the button is displayed. If the command is not assigned an icon, the button label string appears on the toolbar button by default.
    •  Help—The one-line Help for the icon. This label (stored in the message file) identifies the help line seen when the mouse moves over the icon.
    •  Description—The message appears in the Customize Ribbon tab in the Creo Parametric Options dialog box and also when Description is clicked in Creo Parametric.
    •  MessageFile—The message file name. All the labels including the one-line Help labels must be present in the message file.
    Note
    This file must be in the directory <text_path>\text or <text_path>\text\<language>.
    Placing the Button
    Once the button has been created using the methods discussed, place the button on the Creo Parametric ribbon user interface. Refer to the chapter on Ribbon Tabs, Groups, and Menu Items for more information. Also, refer to the Creo Parametric Help for more information on customizing the Ribbon User Interface.
    Pop-up Menus
    Creo Parametric provides shortcut menus that contain frequently used commands appropriate to the currently selected items. You can access a shortcut menu by right-clicking a selected item. Shortcut menus are accessible in:
    •  Graphics window
    •  Model Tree
    •  Some dialog boxes
    •  Any area where you can perform an object-action operation by selecting an item and choosing a command to perform on the selected item.
    The methods described in this section allow you to add menus to a graphics window pop-up menu.
    Adding a Pop-up Menu to the Graphics Window
    You can activate different pop-up menus during a given session of Creo Parametric. Every time the Creo Parametric context changes when you open a different model type, enter different tools or special modes such as Edit, a different pop-up menu is created. When Creo Parametric moves to the next context, the pop-up menu may be destroyed.
    As a result of this, Creo Object TOOLKIT C++ applications must attach a button to the pop-up menu during initialization of the pop-up menu. The Creo Object TOOLKIT C++ application is notified each time a particular pop-up menu is created, which then allows the user to add to the pop-up menu.
    Use the following procedure to add items to pop-up menus in the graphics window:
    1. Obtain the name of the existing pop-up menus to which you want to add a new menu using the trail file.
    2. Create commands for the new pop-up menu items.
    3. Implement access listeners to provide visibility information for the items.
    4. Add an action listener to the session to listen for pop-up menu initialization.
    5. In the listener method, if the pop-up menu is the correct menu to which you wish to add the button, then add it.
    The following sections describe each of these steps in detail. You can add push buttons and cascade menus to the pop-up menus. You can add pop-up menu items only in the active window. You cannot use this procedure to remove items from existing menus.
    Using the Trail File to Determine Existing Pop-up Menu Names
    The trail file in Creo Parametric contains a comment that identifies the name of the pop-up menu if the configuration option, auxapp_popup_menu_info is set to yes.
    For example, the pop-up menu, Edit Properties, has the following comment in the trail file:
    Listening for Pop-up Menu Initialization
    Methods Introduced:
  • pfcActionSource::AddActionListener
    		•
  • pfcActionSource::AddActionListenerWithType
    		•
  • pfcPopupmenuListener::OnPopupmenuCreate
    		•
    Use the method pfcActionSource::AddActionListener or pfcActionSource::AddActionListenerWithType to register a new pfcPopupmenuListener to the session. This listener will be called when pop-up menus are initialized.
    The method pfcPopupmenuListener::OnPopupmenuCreate is called after the pop-up menu is created internally in Creo Parametric and may be used to assign application-owned buttons to the pop-up menu.
    Accessing the Pop-up Menus
    The method described in this section provides the name of the pop-up menus used to access these menus while using other methods.
    Method Introduced:
  • pfcPopupmenu::GetName
    		•
    The method pfcPopupmenu::GetName returns the name of the pop-up menu.
    Adding Content to the Pop-up Menus
    Methods Introduced:
  • pfcPopupmenu::AddButton
    		•
  • pfcPopupmenu::AddMenu
    		•
    Use pfcPopupmenu::AddButton to add a new item to a pop-up menu. The input arguments are:
    •  Command—Specifies the command associated with the pop-up menu.
    •  Options – A pfcPopupmenuOptions object containing other options for the method. The options that may be included are:
    ○  PositionIndex—Specifies the position in the pop-up menu at which to add the menu button. Pass null to add the button to the bottom of the menu. Use the method pfcPopupmenuOptions::SetPositionIndex to set this option.
    ○  Name—Specifies the name of the added button. The button name is placed in the trail file when the user selects the menu button. Use the method pfcPopupmenuOptions::SetName to set this option.
    ○  SetLabel—Specifies the button label. This label identifies the text displayed when the button is displayed. Use the method to set this option.
    ○  Helptext—Specifies the help message associated with the button. Use the method pfcPopupmenuOptions::SetHelptext to set this option.
    Use the method pfcPopupmenu::AddMenu to add a new cascade menu to an existing pop-up menu.
    The argument for this method is a pfcPopupmenuOptions object, whose members have the same purpose as described for newly added buttons. This method returns a new pfcPopupmenu object to which you may add new buttons.