User Interface: Menus, Commands, and Popupmenus
This section describes all the functions provided by Creo TOOLKIT to create and manipulate menus and buttons in the Creo Parametric ribbon user interface.
Refer to the section User Interface: 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
Using Creo TOOLKIT, you can supplement the Creo Parametric ribbon user interface.
Once the Creo TOOLKIT 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 thetoolkitribbonui.rbn file in each mode. Refer to the Creo Parametric Fundamentals Help for more information on customizing the ribbon.
When you are designing your Creo TOOLKIT application, you should carefully consider the context of the buttons that you add to the Creo Parametric User Interface (UI). Buttons specific to a particular mode (such as PART) should be located on the ribbon related to that mode. Buttons that initiate some action on a part, for example, should be located on the PART ribbon.
There are fundamental differences in the files and functions used to manipulate Ribbon and Menu-Manager menus. For this reason, this manual describes these subjects in separate sections.
Menu Buttons and Menus
The tabs in the Creo Parametric ribbon user interface contain groups composed of both buttons and submenus. Using Creo TOOLKIT, you can create similar structures in the Creo Parametric ribbon user interface. The object definitions are as follows:
•  Push button—A named item in a group or menu that is used to launch a set of instructions. An example is the Plane button in the Datum group.
Check button—An item in a group or menu that may be toggled on and off. An example is the Plane Display toggle in the Model Display group in the View tab.
•  Radio group—An item in a group or menu that may be set to one and only one of any number of options. An example is the group of windows listed in the Window group at the Windows tab which allow you to switch between different windows.
•  Command—A procedure in Creo Parametric that may be activated from a button.
•  Command ID—An opaque pointer to a command, used as an input to other Creo TOOLKIT functions.
•  Action command—A command which executes a set of instructions. Launched by push buttons.
•  Option command—A command which executes a set of instructions based on the state of a UI component. Commands are launched by check buttons and radio groups.
Using the Trail File to Determine UI Names
Several functions dealing with UI components require the input of strings that Creo Parametric uses to identify commands and menu buttons.
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 command name for the save button is ProCmdModelSave. This string can be used as input to ProCmdCmdIdFind() to get the command ID.
Adding a PushButton
To add a button to the ribbon user interface, your Creo TOOLKIT application must do the following:
1. Define the action command to be initiated by the button. The action is defined in a function known as the “callback function.”
2. Designate the command using the function ProCmdDesignate().
3. Add the button to the ribbon user interface using the using the Customize Ribbon tab in the File ▶ Options dialog box. This operation binds the added action to the button.
These procedures are described in the sections that follow.
Adding an Action to the Creo Parametric Ribbon
Function Introduced:
  • ProCmdActionAdd()
    		•
    The function ProCmdActionAdd() adds an action to Creo Parametric. This action can be later associated with a push button command in the Creo Parametric user interface. The syntax of this function is as follows: 
    ProError ProCmdActionAdd ( 
     char             *action_name,
     uiCmdCmdActFn     action_cb,
     uiCmdPriority     priority,
     uiCmdAccessFn     access_func,
     ProBoolean        allow_in_non_active_window,
     ProBoolean        allow_in_accessory_window,
     uiCmdCmdId       *action_id );
    This function takes the following arguments:
    •  action_name —The name of the command as it will be used in Creo Parametric. This name must be unique, and it must occur only once in your applications or in Creo Parametric. To prevent conflicts, PTC recommends prepending or appending a unique identifier to your command names, similar to ptc_openfile or openfile_ptc.
    •  action_cb—The action function (callback function) that will be called when the command is activated by pressing the button, cast to a uiCmdCmdActFn:
              typedef int   (*uiCmdCmdActFn)   (
              uiCmdCmdId  command,
              uiCmdValue *p_value,
              void       *p_push_command_data
          );
    ○  command—Identifier of the action or option.
    ○  p_value—For options passed to ValueGet functions. Ignored for actions.
    ○  p_push_command_dataNot implemented in this release.
    •  priority—The command priority. The priority of the action refers to the level of precedence the added action takes over other Creo Parametric actions.
    The available action priorities are defined in the enumerated type uiCmdPriority. The possible values are as follows: 
         typedef int uiCmdPriority;
     #define uiCmdPrioDefault     ((uiCmdPriority) 0)
     #define uiProeImmediate      ((uiCmdPriority) 2)
     #define uiProeAsynch         ((uiCmdPriority) 3)
     #define uiProe2ndImmediate   ((uiCmdPriority) 5)
     #define uiProe3rdImmediate   ((uiCmdPriority) 6)
     #define uiCmdNoPriority      ((uiCmdPriority) 999)
    The following table describes the enumerated values in detail.
    Value
    Description
    uiCmdPrioDefault
    Normal priority actions
    Normal priority actions dismiss all other actions except asynchronous actions. Note that buttons of this priority can lead to the dismissal of Menu Manager menus. Dismissing these menus can result in unexpected behavior from functions that depend on the mode and the context of the Creo Parametric session. One example of a function which can exhibit unintended behavior is ProSelect() when selecting objects from an active simplified representation. Menu buttons should have lesser priority if they depend on the context of the Creo Parametric session.
    uiProeImmediate, uiProe2ndImmediate, and uiProe3rdImmediate
    Levels of immediate priority. Actions of each level of priority dismiss actions with lower level priorities.
    uiProeAsynch
    Asynchronous priority. Actions with asynchronous priority are independent of all other actions.
    •  access_func—The access function (callback function) that determines if the menu button should be available, unavailable, or hidden. Action accessibility refers to whether an added button is available for user selection. This function is called each time the button is displayed. The accessibility is evaluated based on the conditions pertaining at the time the button is pressed. The access function must be cast to a uiCmdAccessFn: 
        typedef uiCmdAccessState (*uiCmdAccessFn) 
            (uiCmdAccessMode access_mode);
    The potential return values are listed in the enumerated type uiCmdAccessState:
    ○  ACCESS_REMOVE—The button is not visible, and the containing menus might also be removed from the menu, if all of the menu buttons in the containing menu possess an access function returning ACCESS_REMOVE.
    ○  ACCESS_INVISIBLE—The button is not visible.
    ○  ACCESS_UNAVAILABLE—The button is visible, but unavailable and cannot be selected.
    ○  ACCESS_DISALLOW—The button shows as available, but the command will not be executed when it is chosen.
    ○  ACCESS_AVAILABLE—The button is available and can be selected by the user.
    Note
    When you add a button, all the return values for the enumerated type uiCmdAccessState work as documented. However, when you add a button to the Creo Parametric ribbon user interface, and the access function returns the value ACCESS_REMOVE or ACCESS_INVISIBLE, these values are ignored. The values are treated as ACCESS_UNAVAILABLE instead. The button is visible, but is unavailable.
    •  allow_in_non_active_window—A ProBoolean determining whether or not to show this command in any non active window. A non-active window is a window that exists and contains a model, but that is no the active window in the Creo Parametric session. A window becomes active when the user chooses View ▶ Activate. This functionality is equivalent to changing the active window by selecting and activating a window using the pull-down menu of Windows command under the View tab in Creo Parametric.
    •  allow_in_accessory_window—A ProBoolean determining whether or not to show this command in an accessory window. An accessory window is smaller than a main Creo Parametric window and allows only the File>Exit command from the menu.
    •  action_id—The function will return a uiCmdCmdId, the command identifier. This identifier can be used in additional Creo Parametric function calls, such as, ProCmdDesignate.
    Note
    •  The function ProCmdActionAdd() is executed only once per Creo Parametric session for each action. Subsequent calls to this function for a previously loaded action are ignored (therefore you cannot redefine an action within a Creo Parametric session).
    Adding a Button to the Ribbon
    You can add a button to the ribbon user interface using the Customize Ribbon tab in the Creo Parametric Options dialog box. Refer to the chapter on User Interface: 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.
    Adding a Check Button to the Ribbon User Interface
    To add a check button to the ribbon user interface, your Creo TOOLKIT application must do the following:
    1. Define the option command to be initiated by the button. The definition of this command includes the definition of three callback functions.
    2. Designate the command using the function ProCmdDesignate().
    3. Add the check button to the ribbon user interface. This operation binds the added action to the button.
    These procedures are described in the sections that follow.
    Adding an Option Command to Creo Parametric —Check Button
    Functions Introduced:
  • ProCmdOptionAdd()
    		•
  • ProCmdChkbuttonValueGet()
    		•
  • ProCmdChkbuttonValueSet()
    		•
    The function ProCmdOptionAdd() adds a command to Creo Parametric.
    The syntax of this function is as follows:
    ProError ProCmdOptionAdd (
      char              *option_name,
      uiCmdCmdActFn     option_cb,
      ProBoolean        boolean_operation,
      uiCmdCmdValFn     set_value_cb,
      uiCmdAccessFn     access_func,
      ProBoolean        allow_in_non_active_window,
      ProBoolean        allow_in_accessory_window,
      uiCmdCmdId        *option_id );
    This function requires the following arguments:
    •  option_name—The name of the option command. This must be unique, in the same way as action command.
    •  option_cb—The action command to be executed when the check button is toggled, cast to a uiCmdCmdActFn. This function should include a call to ProCmdChkbuttonValueGet(), to determine the value of the check button.
    •  boolean_operation—Specifies whether or not the option has two values. Set this to PRO_B_TRUE for a check button.
    •  set_value_cb—The callback function that sets the value of the check button, cast to a uiCmdCmdValFn:
         typedef int   (*uiCmdCmdValFn) (
         uiCmdCmdId  command,
         uiCmdValue *p_value
     );
    This function should include a call to ProCmdChkbuttonValueSet() to set the value of the check button when the UI is displayed or refreshed.
    •  access_func—The callback function that determines if the command is accessible.
    •  allow_in_non_active_window—A ProBoolean determining whether or not to show this command in any non-active window. A non-active window is a window that exists and contains a model, but that is not the active window in the Creo Parametric session. A window becomes active when the user activates a new window or opens a model in a new window.
    •  allow_in_accessory_window—A ProBoolean determining whether or not to show this command in an accessory window. An accessory window is smaller then a main Creo Parametric window and allows only the File>Exit command from the ribbon user interface.
    The functions ProCmdChkbuttonValueGet() and ProCmdChkbuttonValueSet() provide access to the value of the check button. These functions require the option command value (provided by the callback functions as input), and the value is expressed as a ProBoolean.
    Adding a Check Button to the Ribbon
    You can add a check button to the ribbon user interface using the Customize Ribbon tab in the Creo Parametric Options dialog box. Refer to the chapter on User Interface: 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.
    Adding a Radio Button Group to the Ribbon
    To add a radio button group to the ribbon user interface, your Creo TOOLKIT application must:
    1. Define the option command to be initiated by the group of buttons. The definition of this command includes the definition of three callback functions.
    2. Designate the command using the function ProCmdDesignate()
    3. Add the radio button group to the ribbon user interface. This operation binds the added action to the button.
    These procedures are described in the sections that follow.
    Adding an Option Command to Creo Parametric —Radio Group
    Functions Introduced:
  • ProCmdOptionAdd()
    		•
  • ProCmdRadiogrpValueGet()
    		•
  • ProCmdRadiogrpValueSet()
    		•
    The function ProCmdOptionAdd() is used to create the option command corresponding to the button group.
    The arguments should be similar to the usage for creating the option command for a check button, with the following exceptions:
    •  output_callback_function—Must include a call to ProCmdRadiogrpValueGet() to determine the selected value in the radio group.
    •  boolean_operations —Must be PRO_B_FALSE for radio groups.
    •  set_value_cb—Must include a call to ProCmdRadiogrpValueSet() to set the value of the group upon redisplay of the radio group UI.
    The functions ProCmdRadiogrpValueGet() and ProCmdRadiogrpValueSet() provide access to getting or setting the selected item in the group. They require the option command value (provided by the callback functions) as an input. The selected value is returned as a ProMenuItemName string.
    Adding a Radio Button Group
    You can add a button to the ribbon user interface using the Customize Ribbon tab in the Creo Parametric Options dialog box. Refer to the chapter on User Interface: 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.
    Manipulating Existing Commands
    Functions Introduced:
  • ProCmdCmdIdFind()
    		•
  • ProCmdAccessFuncAdd()
    		•
  • ProCmdAccessFuncRemove()
    		•
  • ProCmdBracketFuncAdd()
    		•
    The function ProCmdCmdIdFind() allows you to find the command ID for an existing command so 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. See section Using the Trail File to Determine UI Names to determine UI names in order to determine the name of the command.
    The functions ProCmdAccessFuncAdd() and ProCmdAccessFuncRemove() allow you to impose an access function on a particular command. (See function ProCmdActionAdd() for a description of access functions.) The Add function provides an access_id. This ID must be saved for later use when you deactivate the access function.
    The function ProCmdBracketFuncAdd() allows the creation of a function that will be called immediately before and after execution of a given command. this function would be used to add company logic to the start or end (or both) of an existing Creo Parametric command. It could also be used to cancel an upcoming command. This function is declared as: 
    ProError ProCmdBracketFuncAdd ( 
     uiCmdCmdId        cmd_id,
     uiCmdCmdBktFn     bracket_func,
     char             *bracket_func_name,
     void            **pp_bracket_data );
    The function takes the following arguments:
    •  cmd_id—The command identifier.
    •  bracket_func—The callback function to be called before and after the command, cast to a uiCmdCmdBktFn:
         typedef int   (*uiCmdCmdBktFn)
        ( uiCmdCmdId   command,
          uiCmdValue  *p_new_value,
          int          entering_command,
          void       **pp_bracket_data);
    The entering command argument will be 1 before execution and 0 after. If the operation is before the upcoming command execution, and you want to cancel the upcoming command execution, return 0. Otherwise, return non-zero.
    •  bracket_func_name—The name of the bracket function.
    •  pp_bracket_data—A void** containing data to be passed to the bracket function.
    Note
    Model tree commands that use the model tree action functions cannot be used as bracket functions. Such commands exit before the redefinition starts. You can use the notification function ProNotificationSet() to get and set the notifications for the pre and post redefinition callbacks, respectively. You need to set the value of the enumerated data type ProNotifyType to PRO_FEATURE_REDEFINE_PRE or PRO_FEATURE_REDEFINE_POST.
    Designating Commands
    Using Creo TOOLKIT you can designate Creo Parametric commands. These commands can later appear in the Creo Parametric ribbon user interface.
    In Creo TOOLKIT you can set a button to refer to a command and subsequently drag this button on to the Creo Parametric ribbon user interface. When the button is clicked, the command is executed.
    To add a command, your Creo TOOLKIT application must do the following:
    1. Define or add the command to be initiated on clicking the icon.
    2. Optionally designate an icon button to be used with the command defined by you.
    3. Designate the command (icon) to appear in the Customize Ribbon tab in the Creo Parametric Options dialog box.
    Note
    Refer to the chapter on User Interface: 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.
    Adding the Command
    Functions Introduced:
  • ProCmdActionAdd()
    		•
  • ProCmdOptionAdd()
    		•
    The functions ProCmdActionAdd() and ProCmdOptionAdd() allow you to define or register a Creo Parametric command. See the section Adding an Action to the Creo Parametric Ribbon for more information on the function ProCmdActionAdd() and the section Adding an Option Command to Creo Parametric —Check Button for more information on the function ProCmdOptionAdd().
    Providing the Icon
    Function Introduced:
  • ProCmdIconSet()
    		•
    The function ProCmdIconSet() allows you to provide an icon to be used with the command you created. The function adds the icon to the Creo Parametric command. The function takes the command identifier as one of the inputs and the name of the icon file, including the extension as the other input. 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.
    The application searches for the icon files in the following locations:
    •  <creo_loadpoint>\<version>\Common Files\text\resources
    •  <application_text_dir>\resource
    •  <application_text_dir>\<language_dir>/resource
    The location of the application text directory is specified in the Creo TOOLKIT registry file.
    The Creo Parametric button is replaced with the icon image.
    Commands that do not have an icon assigned to them display the button label.
    You may also use this function to assign a small icon to a button.
    Designating the Command
    Function Introduced:
  • ProCmdDesignate()
    		•
  • ProCmdRadiogrpDesignate()
    		•
  • ProCmdAlwaysAllowValueUpdate()
    		•
    The function ProCmdDesignate() allows you to designate a command or check button to be available in the Customize Ribbon tab in the Creo Parametric Options dialog of Creo Parametric.
    After a Creo TOOLKIT application has used the function ProCmdDesignate() on a command, the user can add the button associated with this command into the Creo Parametric ribbon user interface.
    If this function 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 syntax of the function ProCmdDesignate() is: 
    ProError ProCmdDesignate ( uiCmdCmdId cmd_id, 
                           ProMenuItemLabel button_label,
                           ProMenuLineHelp one_line_help,
                           ProMenuDescription description,
                           ProFileName msg_file);
    The arguments to this function are:
    •  cmd_id—The command identifier.
    •  button_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 button by default.
    •  one_line_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 and also when "Description" is clicked in Creo Parametric.
    •  msg_file—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>.
    The function ProCmdRadiogrpDesignate designates the radio button to be available in the TOOLKIT Commands list in the Customize Ribbon tab in the Creo Parametric Options dialog box of Creo Parametric. The input arguments of this function are:
    •  option_id—The option identifier.
    •  number_radio_group_items—Specifies the number of options in the radio group
    •  radio_group_items—Specifies an array of items in the radio group.
    •  radio_group_labels—Specifies the labels for the radio buttons. 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 label string appears on the menu by default.
    •  one_line_helps—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.
    •  radio_group_icons—Specifies an array of icon file names, including the extension. 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— <icon_name_16X16.ext>
    ○  Large icon— <icon_name_32X32.ext>
    The application searches for the icon files in the following locations:
    ○  <creo_loadpoint>\<version>\Common Files\text\resources
    ○  <application_text_dir>\resource
    ○  <application_text_dir>\<language_dir>\resource
    The location of the application text directory is specified in the Creo TOOLKIT registry file.
    •  description—The message appears in the Customize Ribbon tab in the Creo Parametric Options dialog and also when "Description" is clicked in Creo Parametric.
    •  msg_file—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>.
    The function ProCmdAlwaysAllowValueUpdate() allows the value of the command to be updated always, even when the command is not accessible. By default, set_value_cb is called only when the command is accessible. The input arguments follow:
    •  cmd_id—The command identifier.
    •  allow—Specify as PRO_B_TRUE for the value of the command to be updated always. Specify it as PRO_B_FALSE, only when the command is accessible.
    Placing the Button
    Once the button has been created using the functions discussed, place the button on the Creo Parametric ribbon user interface. Refer to the chapter on User Interface: 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.
    Example 1: Designating a Command
    The example code in the file UgMain.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main illustrates how to designate a command to be available for placement as a button.
    Popup Menus
    Creo Parametric provides shortcut menus that contain frequently used commands appropriate to the currently selected items. You can access a shortcut menu by clicking the right mouse button (RMB) after selecting an 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 then choosing a command to perform on the selected item.
    Creo TOOLKIT provides different procedures to add custom buttons to popup menus, depending on the buttons’ context. To add to the model tree popup menu, use the procedure described in Adding a Button to the Model Tree Popup Menu. To add a popup menu to a custom dialog box, see the User Interface: Dialogs section (you cannot modify the popup menus in an existing UI dialog box). To add to a graphics window popup menu, refer to Adding a Popup Menu to the Graphics Window.
    Adding a Popup Menu to the Graphics Window
    Different popup menus can be activated during a given session of Creo Parametric. Every time the Creo Parametric context changes (by opening a different model type, by entering different tools, or by entering special modes like "Edit") a different popup menu is created. When Creo Parametric moves to the next context, the popup menu may be destroyed.
    Because of this, Creo TOOLKIT applications must attach a button to the popup menu during initialization of the popup menu. The Creo TOOLKIT application is notified each time a particular popup menu is created, which then allows the user to add to the popup menu.
    Use the following procedure to add items to graphics window popup menus:
    1. Obtain the name of the existing popup menus to which you want to add a new menu using the trail file.
    2. Register the Creo TOOLKIT notifications for creation and destruction of popup menus.
    3. Create commands for the new popup menu items.
    4. Implement access functions to provide visibility information for the items.
    5. When the notification is called for the desired popup menu, add the custom buttons to the menu.
    6. When the destroy notification is called, free the associated memory for the custom buttons.
    The following sections describe each of these steps in detail. You can add push buttons, check buttons, and cascade menus to the popup menus. You can add popup menu items only in the active window. You cannot use this procedure to remove items from existing menus. To remove items using an access function see the section on Manipulating Existing Commands.
    Using the Trail File to Determine Existing Popup Menu Names
    The trail file in Creo Parametric contains a comment that identifies the name of the popup menu if the configuration option auxapp_popup_menu_info is set to yes.
    For example, the popup menu, Edit Properties, has the following comment in the trail file: 
    ~ Close `rmb_popup` `PopupMenu`
~ Command `ProCmdEditProperties`
    Registering Notifications to Create and Destroy Popup Menus
    Popup menus are created at runtime in Creo Parametric and only when the required menus exist in the active window. Hence it is not possible to pre-register the custom buttons. Notification functions notify applications to add a new popup menu. For more information on using notifications see the section Event-driven Programming: Notifications.
    Functions Introduced:
  • ProNotificationSet()
    		•
  • ProPopupmenuCreatePostAction()
    		•
  • ProPopupmenuDestroyPreAction()
    		•
    If the notification value argument type is set to PRO_POPMENU_CREATE_POST, a registered callback function whose signature matches ProPopupmenuCreatePostAction() is called. This function is called after the popup menu is created internally in Creo Parametric and must be used to assign application-specific buttons to the popup menu.
    If the notification value argument type is set as PRO_POPUPMENU_DESTROY_PRE, a registered callback notification function ProPopupmenuDestroyPreAction() is called before the popup menu is destroyed. Use this function to free memory allocated by the application for the custom buttons in the popup menu.
    Accessing the Popup Menus
    The functions described in this section provide the name and ID of the popup menus that are used to access these menus while using other functions.
    Functions Introduced:
  • ProPopupmenuIdGet()
    		•
  • ProPopupmenuNameGet()
    		•
    The function ProPopupmenuIdGet() returns the popup menu ID for a given popup menu name. The popup menu ID is required for the functions that add buttons to the popup menu. IDs are dependent on the context of Creo Parametric and are not maintained between sessions.
    The function ProPopupmenuNameGet() returns the name of the popup menu assigned to a given ID.
    Creating Commands for the New Popup Menu Buttons
    Functions Introduced:
  • ProCmdActionAdd()
    		•
  • ProCmdOptionAdd()
    		•
  • ProCmdCmdIdFind()
    		•
    The functions ProCmdActionAdd() or ProCmdOptionAdd() are used to create commands for the popup menus. Only push buttons (action commands) and check buttons (option commands) are supported in popup menus. Commands with a given name are created only once in a session of Creo Parametric. Hence PTC recommends that you create the required commands in the user_initialize() function of the application.
    Use ProCmdCmdIdFind() to obtain the command ID for the command (in the notification callback for PRO_POPUPMENU_CREATE_POST) to add the button to the popup menu.
    Checking the Access State of a Popup Menu Item
    Functions Introduced:
  • ProPopupmenuAccessFunction()
    • A popup menu uses an additional access function to determine whether the popupmenu must be visible based on the currently selected items. Use the function whose signature matches ProPopupmenuAccessFunction() to set the access state of the button in the popup menu.
    The syntax for this function is as follows:
    typedef uiCmdAccessState (*ProPopupmenuAccessFunction)
(uiCmdCmdId command,
 ProAppData appdata,
 ProSelection* sel_buffer);
    The last argument contains an array of selected items that are used to determine the visibility of the popup menu button. It is PTC standard practice to remove popup menu buttons using ACCESS_REMOVE instead of graying them out using ACCESS_UNAVAILABLE when unusable item types have been selected. This is to minimize the size of the popup menu.
    Adding Creo Parametric Popup Menus
    Functions Introduced:
  • ProPopupmenuButtonAdd()
    		•
  • ProPopupmenuCascadebuttonAdd()
    		•
    Use ProPopupmenuButtonAdd() to add a new item to a popup menu. The input arguments are:
    •  menu_ID—Specifies the ID of the popup menu obtained from ProPopupmenuIdGet().
    •  position—Specifies the position in the popup menu at which to add the menu button. Pass PRO_VALUE_UNUSED to add to the bottom of the menu.
    •  button_name—Specifies the name of the added button. The button name is placed in the trail file when the user selects the menu button. For more information on valid characters that you can use to specify the name, refer to the section Naming Convention for UI Components.
    •  button_label—Specifies the message that refers to the button label. This label identifies the text seen when the button is displayed. To localize this text, obtain and pass a string from ProMessageToBuffer().
    Note
    The labels and the text added using the ProCmdDesignate() function duplicate existing messages that are previously added in the Creo database. To display the correct label and text message, you can use a prefix or a suffix with the message names that will identify your Creo TOOLKIT application. You should avoid using generic names of Creo TOOLKIT buttons such as Point, Arc, Circle, Ellipse in the labels and text.
    •  button_helptext—Specifies the help message associated with the button. This label acts as a keyword that identifies the help text in the message file. To localize this text, obtain and pass a string from ProMessageToBuffer().
    •  cmd_ID—Specifies the command identifier for the action or option.
    •  access_status—Specifies the callback function used to determine the visibility status of the added button.
    •  appdata—Specifies the user application data.
    Use the function ProPopupmenuCascadebuttonAdd() to add a new cascade menu to an existing popup menu.
    The input arguments are:
    •  menu_ID—Specifies the ID of the popup menu obtained from ProPopupmenuIdGet().
    •  position—Specifies the position in the menu at which to add the cascade button. Pass PRO_VALUE_UNUSED to add to the bottom of the menu.
    •  cascade_menu_name—Specifies the name of the cascade menu. The name is placed in the trail file when the user selects the menu button. For more information on valid characters that you can use to specify the name, refer to the section Naming Convention for UI Components.
    •  cascade_menu_label—Specifies the message that refers to the cascade menu label. This label identifies the text seen when the menu is displayed. To localize this text, obtain and pass a string from ProMessageToBuffer().
    •  cascade_menu_helptext—Specifies the help message associated with the cascade menu. This label acts as a keyword that identifies the help text in the message file. To localize this text, obtain and pass a string from ProMessageToBuffer().
    •  access_status—Specifies the callback function used to determine the visibility status of the added item.
    •  appdata—Specifies the user application data.
    The output argument is casc_menuId, the menu ID of the cascade menu.
    Adding a Button to the Model Tree Popup Menu
    To add a button to the ribbon user interface, refer to the section Menu Bar Buttons and Menus. Ensure that the following conditions are met:
    •  The menu name used should be “ActionMenu”.
    •  The command access function should be configured to read the selection buffer using ProSelbufferSelectionsGet(). If the buffer is inactive or empty, the access function should make the menu item invisible.
    Example 2: Assigning the Creo Parametric command to popup menus
    The example in the file UgPopupmenus.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main demonstrates how to assign a Creo Parametric command to the popup menus in the graphics window and the model tree. It adds the example UserAsmcompConstraintsHighlight() to the popup menu (see the section on Assembly: Basic Assembly Access for details). The popup menus use an access function to check the currently selected item in the selection buffer that is an assembly component. If it is not an assembly component, the button will be removed from the menu. The example adds the popup menu button using ProPopupmenuButtonAdd() if the menu name is the name of the current main popup menu in assembly mode.
    Menu Manager Buttons and Menus
    Very few modes in Creo Parametric display a menu manager. For example, the ASM PROCESS menu is displayed only when Creo Parametric is in the Process Plan Assembly mode, which occurs when a Process-Plan Assembly has been created or retrieved. Modifying and supplementing the menu manager interface is fundamentally different from similar operations on the ribbon.
    This section describes the files and functions necessary to manipulate the menu manager buttons and menus of Creo Parametric. This section covers the following topics:
    •  Menu Files
    •  Adding a Menu Button
    •  New Menus
    •  Preempting Creo Parametric Commands
    •  Submenus
    •  Manipulating Menus
    •  Data Menus
    •  Setting Menu Buttons
    •  Controlling Accessibility of Menu Buttons
    •  Pushing and Popping Menus
    •  Run-time Menus
    Menu Files
    Menu files enable you to specify your own text for the name of a menu button and the one-line help text that appears when you place the cursor over that button, along with translations for both of these.
    Creo Parametric looks for the Creo TOOLKIT menu files in the following locations:
    •  The current Creo Parametric startup directory
    •  The subdirectory text/menus under the directory named by the text_dir statement in the registry file
    PTC recommends that during development you place your menu files in text/menus under your working directory and specify the following registry file entry: 
               text_dir .
    Names and Contents of Menu Files
    There are two conventional extensions used in naming menu files:
    •  .mnu—Files that describe complete menus
    •  .aux—Files that describe new buttons to be added to existing Creo Parametric menus
    The following restrictions apply to file names:
    •  The name must be unique through out Creo Parametric.
    •  The name must have no more than 30 characters, including the extension.
    To find out what menu file names are used by Creo Parametric, look in the Creo Parametric menu directory at <creo_loadpoint>\<version>\Common Files\text\<language_dir>\menus.
    When you create an .aux file to extend an existing Creo Parametric menu, use the same file name root as Creo Parametric used for that menu.
    Syntax and Semantics of Menu Files
    The two types of files—.mnu and .aux—have identical formats.
    The format consists of groups of three lines (one group for each menu button) and a group at the top for the menu title. The title group contains the menu title on the first line, and then two blank lines.
    The menu title is the name that appears at the top of the menu when you run Creo Parametric in English. The menu title is also used to refer to the menu from your Creo TOOLKIT code, so it is essential that this name is unique in all Creo Parametric menus. For example, if you are writing an .aux file to add buttons to a Creo Parametric menu, make sure you use the title that appears in the corresponding .mnu file in Creo Parametric. If you are creating a new menu, make sure that the title you use has not already been used in Creo Parametric.
    If the menu title is followed by a second word, Creo Parametric displays the second word instead of the first one. This is how a translation is provided. If there is no second word, Creo Parametric displays the first word.
    Each menu button group consists of the following three lines:
    •  Button name—If the button name as it appears on the Creo Parametric screen contains spaces, each space must be replaced by the character # in the menu file. If the button name is followed by another name, separated by white space, the second name will be what is actually displayed.
    The first name is still used to refer to the button from your Creo TOOLKIT code. The second provides an optional translation of that button name.
    •  One-line Help—This is a single line of text that explains what the menu button does. When you place the mouse pointer on the menu button, Creo Parametric displays the one-line Help text in the Message Window.
    •  Alternate Help—If this line is not blank (or does not start with the comment character “#”), it will be used in place of the one-line Help. This provides a translation of the Help message.
    Example 3: Sample Menu File
    The following example code shows the menu file you would create to add a new button, Check Part, to the Creo Parametric PART menu. 
     Menu file "part.aux":
[Start of file on next line]
PART
<blank line>
<blank line>
Check#Part
Check the validity of the current part.
<blank line>
[End of file on previous line]
    Example 4: Adding Alternate Names and Help Text to a Button
    This example code creates an alternate button name and Help text for the previous example.
    Menu file "part.aux":
[Start of file on next line]
PART
<blank line>
<blank line>
Check#Part DRC#Check
Check the validity of the current part.
Perform a DRC (Design Rule Check) on the part.
[End of file on previous line]
    Adding a Menu Button
    Functions Introduced:
  • ProMenuFileRegister()
    		•
  • ProMenuAuxfileRegister()
    		•
  • ProMenubuttonActionSet()
    		•
  • ProMenubuttonGenactionSet()
    		•
    When you add a new button to an existing menu in user_initialize(), you are modifying the Creo Parametric definition of the menu in its memory before that menu has been used by Creo Parametric, and therefore before Creo Parametric has loaded it from its menu file. You must call the function ProMenuFileRegister() to tell Creo Parametric to load its own menu file before you can add your own buttons.
    To add a button to a menu, first write a menu file, and then add the following calls to user_initialize():
    1. Load the Creo Parametric menu into memory, using ProMenuFileRegister().
    2. Add the buttons in your menu file to the menu, using ProMenuAuxfileRegister().
    3. Define the actions of the new buttons, using ProMenubuttonActionSet().
    Calling ProMenuFileRegister()
    The input arguments to ProMenuFileRegister() are as follows:
    •  ProMenuName menuname—The unique title of the menu that appears as the first word on the first line of the menu file and on the heading of the menu on the screen when you run Creo Parametric in English. This argument is case-insensitive.
    •  ProMenufileName filename—The name of the menu file, including the extension but not the directory.
    The function outputs the integer identifier of the menu, which you do not normally need. If the function fails for some reason (for example, the menu file did not exist), it returns PRO_TK_GENERAL_ERROR. If you call this function a second time on the same menu file, it has no effect.
    Calling ProMenuAuxfileRegister()
    This function has the same arguments and return value as ProMenuFileRegister(). Instead of loading a new menu into memory, the function adds the buttons in the file to a menu already in memory.
    Calling ProMenubuttonActionSet()
    The first three arguments to ProMenubuttonActionSet() are as follows:
    •  ProMenuName menuname—The title of the menu that contains the button.
    •  ProMenubuttonName button—The first name for the button in the menu file (not the second, which provides the translation), but with spaces instead of pound signs (#). This argument is case-insensitive.
    •  ProMenubuttonAction action—A pointer to the Creo TOOLKIT callback function to be called when the user selects this menu button. To pass a pointer to a function, supply the name of the function without the following parentheses. If your function does not precede the call to ProMenubuttonActionSet() in the same file, you must add a declaration of it to show the compiler that this is a function.
    The other two arguments, app_data and app_int, are optional arguments to your command function. These arguments enable your command function to be more flexible in what it does. If you do not want to use app_data and app_int, supply the values NULL and 0, respectively.
    Sample declarations and the use of the optional arguments are shown in Example 5: Adding a Button to the Creo Parametric Ribbon; Example 6: Defining a New Menu that Closes Itself; and Example 7: Defining a New Menu the User Must Close.
    Example 5: Adding a Button to the Creo Parametric Ribbon
    The example code in the file UgMenuMenuButtonAdd.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_menu adds the button Check Part to the Creo Parametric PART tab. The example uses the menu file from the previous examples.
    New Menus
    Functions Introduced:
  • ProMenuProcess()
    		•
  • ProMenuDelete()
    		•
  • ProMenuCreate()
    		•
  • ProMenuHold()
    		•
  • ProMenuDeleteWithStatus()
    		•
    Creo TOOLKIT enables you to create new menus. Defining a new menu differs from adding buttons to an existing menu in the following ways:
    •  The menu file you supply should end in .mnu, not .aux. (It has the same syntax, though.)
    •  You do not need to call ProMenuAuxfileRegister() because the whole menu is defined in a single menu file.
    •  You need to define an exit action for the menu, in addition to an action for each button on the menu.
    •  You can either specify the new menu in user_initialize() or you can set up the new menu locally before you use it.
    Exit Actions
    You must not only tell the menu manager inside Creo Parametric which function to call for each button on your menu, but also which function to call if the user selects a button on another menu. This function is called an exit action because it is often used to close the menu.
    Note
    If you do not define an exit action, Creo Parametric’s behavior is undefined if the user selects from another menu.
    There are two types of exit action:
    •  Nothing—The menu selection is ignored. This is useful if you want the user to take some definite action before leaving the current menu.
    •  Close the current menu—The menus unwind to the level of the menu selected and the selected command is entered. This is the usual way to leave a menu.
    Defining a New Menu
    To define a new menu, first write a menu file. Before you need to use the menu, add the following calls to your Creo TOOLKIT program:
    1. Load the Creo Parametric menu into memory, using ProMenuFileRegister().
    2. Define the actions of the new buttons, using the function ProMenubuttonActionSet().
    3. Define the exit action of the new menu, using the functions ProMenubuttonActionSet() and one of the exit action functions described in the following section.
    Example 6: Defining a New Menu that Closes Itself
    This example code defines a new menu, MYMENU, that closes itself using the function ProMenuDelete(). 
    [Start of file on next line]
MYMENU
<blank line>
<blank line>
Partial#Check
Perform a partial check on the part.
<blank line>
Full#Check
Perform a full check on the part.
<blank line>
[End of file on previous line]
    The following code sets up the menu:
        int menuId;
    ProMenuFileRegister ("mymenu", "mymenu.mnu", &menuId);
    ProMenubuttonActionSet ("mymenu", "Partial Check", ProCheckPart,
        NULL, 0);
    ProMenubuttonActionSet ("mymenu", "Full Check", ProCheckPart, NULL,
        1);
    ProMenubuttonActionSet ("mymenu", "Quit Checks",
        (ProMenubuttonAction)ProMenuDelete, NULL, 0);
    ProMenubuttonActionSet("mymenu", "mymenu",
        (ProMenubuttonAction)ProMenuDelete, NULL, 0);
    Example 7: Defining a New Menu the User Must Close
    In the following example code, the user has to close MYMENU. 
        int menuId;
    ProMenuFileRegister ("mymenu", "mymenu.mnu", &menuId);
    ProMenubuttonActionSet ("mymenu", "Partial Check", ProCheckPart,
        NULL, 0);
    ProMenubuttonActionSet ("mymenu", "Full Check", ProCheckPart,
        NULL, 1);
    ProMenubuttonActionSet ("mymenu", "Quit Checks",
        (ProMenubuttonAction)ProMenuDelete, NULL, 0);
    ProMenubuttonActionSet ("mymenu", "mymenu",
        (ProMenubuttonAction)ProMenuHold, NULL, 0);
    Defining an Exit Action
    To define an exit action, make an extra call to ProMenubuttonActionSet(), but instead of the button name (the third argument), specify the menu name.
    If you want the menus to unwind and the new command to be entered, use ProMenuDelete() as the action function.
    If you want the selection to be ignored, use the function ProMenuHold() as the exit action. If you use this function, you must provide some other exit route for the menu. For example, you can specify an explicit menu button (such as Done) whose command function calls ProMenuDelete().
    If you want to perform some additional action in these cases (such as sending a warning to the user), you can provide your own exit function that performs the action and then calls ProMenuHold().
    Using a New Menu
    After you have defined your new menu, you need to know how to use it. This is normally done inside the command function of another menu button.
    To Use a New Menu
    1. Display the menu, using ProMenuCreate().
    2. Make the menu active so the user can select from it, using ProMenuProcess().
    Calling ProMenuCreate()
    The first argument to ProMenuCreate() is either PROMENUTYPE_MAIN or PROMENUTYPE_SUB. The usual choice is PROMENUTYPE_MAIN (see the section Submenus for detailed information about submenus). The second argument is the title of the menu. The last argument is the identifier of the displayed menu.
    Calling ProMenuProcess()
    The function ProMenuProcess() takes a single input argument—the title of the menu. If the menu is the last one displayed, you can pass an empty string. The return value is meaningful only if you use the function ProMenuDeleteWithStatus() as the exit action for the menu.
    The function ProMenuProcess() returns only when the menu is closed, as the result of a call to either ProMenuDelete() or ProMenuDeleteWithStatus(). The following is true for any code following the call to ProMenuProcess():
    1. The code does not get executed until the menu is closed.
    2. The code gets executed before any command that causes an exit from the menu. When the user closes a menu by selecting another command, that command is put into the input buffer and is not executed until control passes from your application back to Creo Parametric.
    Example 8: Using a New Menu
    The following example code shows how to use the functions ProMenuProcess() and ProMenuCreate(). The example builds on the previous examples. 
        int action, menuId;
    .
    .
    .
    ProMenuCreate (PROMENUTYPE_MAIN, "mymenu", &menuId);
    ProMenuProcess ("", &action);
    .
    .
    Creating a Menu for Selecting a Single Value
    Function Introduced:
  • ProMenuDeleteWithStatus()
    		•
  • ProMenubuttonActionSet()
    		•
  • ProMenuProcess()
    		•
    Use of ProMenubuttonActionSet() Final Arguments
    The two last arguments of ProMenubuttonActionSet() are app_data, of type ProAppData and app_int, of type integer. These arguments are passed directly to your callback function when it is invoked. Because Creo TOOLKIT and Creo Parametric do not look at these arguments, you can use them for any information that you want to pass to or from your function.
    Example 9: Creating a Menu that Selects a Value uses the final argument of ProMenubuttonActionSet() to distinguish between several menu buttons that share the same command function. Inside the command function, this value appears as the second argument. It is used to determine which button was selected and then perform the appropriate action. The command function does not use the fourth argument of ProMenubuttonActionSet(), but includes a dummy first argument of type ProAppData to match it, so that the second argument is received correctly.
    Returning a Value from ProMenuProcess()
    The function ProMenuDelete() closes the current menu and causes control to return from the call to ProMenuProcess() that made that menu active. If you want to close the menu under more than one condition and react to that condition in the code that follows the return from ProMenuProcess(), use ProMenuDeleteWithStatus() instead of ProMenuDelete(). The ProMenuDeleteWithStatus() function takes a single integer argument, which is the value returned by ProMenuProcess().
    Example 9: Creating a Menu that Selects a Value
    The example code in the file UgMenuValueSelect.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_menu shows several new techniques for using the menu functions. This example shows how to use ProMenuDeleteWithStatus() and uses more of the arguments to ProMenubuttonActionSet().
    Compound Menus
    Function Introduced:
  • ProCompoundmenuCreate()
    		•
    The ProCompoundmenuCreate() function enables you to take an array of previously loaded menu names and append them together into one menu.
    To Create a Compound Menu:
    1. Specify which submenus to include in the compound menu, as follows:
    static char **compound_menu = {"MENU_1","MENU_2",  "MENU_3", ""};
    2. Load the actions on the buttons.
    3. Set the button visibility and accessibility.
    4. Generate the compound menu, as follows:
    ProCompoundmenuCreate (compound_menu, n_submenus);
    5. Get user input, as follows:
    ProMenuProcess (compound_menu[0], action);
    Preempting Creo Parametric Commands
    Functions Introduced:
  • ProMenubuttonPreactionSet()
    		•
  • ProMenubuttonPostactionSet()
    		•
    In addition to adding your own menus and menu buttons, it is sometimes useful to be able to modify the effect of an existing Creo Parametric menu button. The function ProMenubuttonPreactionSet() enables you to call your function before the Creo Parametric command is executed. If the operation is before the upcoming command execution, and you want to cancel the upcoming command execution, return 1. Otherwise, return zero.
    You could also cancel the Creo Parametric command, so only your function gets called. Similarly, the function ProMenubuttonPostactionSet() enables you to call your function after the Creo Parametric command is executed.
    You can use the ProMenubuttonPreactionSet() function to protect certain commands, so that the user can use them only under certain circumstances specified by your Creo TOOLKIT application. For example, you may want to prevent the user from saving a model unless it has passed a certain validity check.
    Calling ProMenubutton*actionSet()
    The functions ProMenubuttonPreactionSet() and ProMenubuttonPostactionSet() have the same arguments as ProMenubuttonActionSet(). The function ProMenubuttonPreactionSet() inserts your function before an existing Creo Parametric command instead of assigning it to a new button. The function ProMenubuttonPostactionSet() inserts your function after an existing Creo Parametric command.
    Because you are changing the definition of the menu in Creo Parametric, you must make sure the menu is loaded into memory first, by calling ProMenuFileRegister().
    If the command function you load returns the value 0, the Creo Parametric command for that menu button will be executed immediately. If your function returns any other value, the Creo Parametric command will not be performed.
    Example 10: Asking for Confirmation on Quit Window
    The example code in the file UgMenuConfirmGet.c located at <creo_toolkit_loadpoint>protk_appls/pt_userguide/ptu_menu shows how to use ProMenubuttonPreactionSet() to ask the user to confirm a selection. The example uses ProMenubuttonPreactionSet() to protect Quit Window
    Submenus
    Function Introduced:
  • ProMenuCreate()
    		•
    All the menus described so far have been main menus. The other type of menu is called a submenu. A submenu differs from a main menu in the following ways:
    •  A submenu is active at the same time as the menu above it. Selecting from the menu above does not close the submenu.
    •  A submenu does not display its title.
    In effect, a submenu acts as an extension to the menu above it. This enables you to display two active menus at the same time, such as if you want the user to choose two options from two exclusive groups of values.
    Making a Menu a Submenu
    To make a Main Menu a Submenu:
    1. Display the menu above the submenu, using ProMenuCreate().
    2. Display the submenu, using ProMenuCreate(), but make the first argument PROMENUTYPE_SUB instead of PROMENUTYPE_MAIN.
    3. Call ProMenuProcess() for the submenu only. Because it is a submenu, the menu above it will become active at the same time.
    4. Close both menus, using either ProMenuDelete() or ProMenuDeleteWithStatus().
    Manipulating Menus
    Function Introduced:
  • ProMenubuttonLocationSet()
    		•
    The function ProMenubuttonLocationSet() provides the ability to move a Creo Parametric menu button to a different location on its menu, or to add new menu buttons to a Creo Parametric menu somewhere other than at the bottom of the menu.
    Before you call ProMenubuttonLocationSet(), you must make sure the menu you are modifying has been fully loaded into memory. Make sure ProMenuFileRegister() has been called, and, where appropriate, ProMenuAuxfileRegister().
    The first two arguments of the ProMenubuttonLocationSet() function identify the menu and the button, as in ProMenubuttonActionSet().
    The final argument is a switch that specifies where to move the button. The possible values are as follows:
    •  0—The button becomes the first in the menu.
    •  1—The button is inserted after the current first button.
    •  2—The button is inserted after the current second button.
    •  –1—The button becomes the last button on the menu.
    Data Menus
    Functions Introduced:
  • ProMenuModeSet()
    		•
  • ProMenuDatamodeSet()
    		•
    Menus can operate in two modes:
    •  PROMENUMODE_OPERATIONAL—The default mode. This mode is used in all the previous examples. On an operational menu, only one button is ever set (that is, displayed with a red background) while that command is in progress.
    •  PROMENUMODE_DATA—Each button remains set until you select it again. This is useful when the buttons do not represent commands, but, for example, a set of independently selectable options.
    The function ProMenuModeSet() sets the menu mode. For a PROMENUMODE_DATA menu, you can choose to indicate the set buttons with a check mark instead of the usual red background by using the function ProMenuDatamodeSet().
    Calling ProMenuModeSet() and ProMenuDatamodeSet()
    The function ProMenuModeSet() has two arguments:
    •  The menu title
    •  The menu mode (either PROMENU_MODE_OPERATIONAL or PROMENUMODE_DATA)
    The function ProMenuDatamodeSet() has two arguments:
    •  The menu title.
    •  The set indicator, which indicates which buttons are set. This argument can have either of the following values:
    ○  TRUE—Use a check mark.
    ○  FALSE—Use a red background. This is the default value.
    Both of these functions must be called after the menu has been loaded into memory (using ProMenuFileRegister()), and before the menu has been displayed (using ProMenuCreate()).
    If you want to create a menu whose buttons are dependent on run-time data, use the function ProMenuStringsSelect(), described later in this sectionchapter.
    Setting Menu Buttons
    Functions Introduced:
  • ProMenubuttonHighlight()
    		•
  • ProMenubuttonUnhighlight()
    		•
    Sometimes it is useful to be able to set and unset menu buttons from the Creo TOOLKIT application. For example, if you are using data menus, you can set the appropriate buttons when the menu is displayed to show the current options.
    Calling ProMenubuttonHighlight() and ProMenubuttonUnhighlight()
    Both ProMenubuttonHighlight() and ProMenubuttonUnhighlight() take two arguments—the menu title and button name. Both functions must be called after the menu has been displayed (using ProMenuCreate()), but before making the menu interactive (using ProMenuProcess()). Contrast these rules to the rules for using ProMenuModeSet() and ProMenuDatamodeSet().
    Controlling Accessibility of Menu Buttons
    Functions Introduced:
  • ProMenubuttonActivate()
    		•
  • ProMenubuttonDeactivate()
    		•
    A menu button that is inaccessible is one that, though currently displayed on a menu, is gray and has no effect when it is selected. Creo Parametric uses this facility for options that are temporarily unavailable for some reason. For example, you cannot create a hole until you have created the first protrusion.
    You can control the accessibility of your own menu buttons from Creo TOOLKIT using ProMenubuttonActivate() and ProMenubuttonDeactivate(). Each function takes two arguments: the menu title and button name. These functions must be called when the menu is displayed (after calling ProMenuCreate()).
    Pushing and Popping Menus
    Functions Introduced:
  • ProMenuVisibilityGet()
    		•
  • ProMenuPush()
    		•
  • ProMenuPop()
    		•
    Sometimes Creo Parametric temporarily hides certain menus, even though they are still in context, to make room for lower-level menus. An example of this is when you select Make Datum during feature creation. This process is called pushing menus, because they are put on a stack from which they can be popped to make them reappear.
    The function ProMenuVisibilityGet() tells you whether the specified menu is currently displayed. It takes one input argument—the menu title.
    The function ProMenuPush() pushes the current lowest menu. It takes no arguments.
    The function ProMenuPop() pops the menu from the top of the stack. It takes no arguments.
    Run-time Menus
    Functions Introduced:
  • ProMenuStringsSelect()
    		•
  • ProMenuFromStringsRegister()
    		•
    The ProMenuStringsSelect() function enables you to set up a menu at run time. You do not need to supply a menu file because the buttons are defined when you display the menu. You cannot attach command functions to the button; a run-time menu simply returns a list of the buttons selected.
    A run-time menu is displayed together with a submenu that contains the following buttons:
    •  Done Select
    •  Quit Select
    •  List
    The default option, List, causes the string menu itself to be displayed.
    You can set the maximum number of items you want to be selectable. The function returns when the user has selected the maximum number of items you specified, or has selected Done or Quit. Creo Parametric uses this type of menu to select a disk file to be retrieved after the user selects Search/Retr.
    The maximum size of the string you assign to a button is PRO_NAME_SIZE - 1. PRO_NAME_SIZE is defined in file ProSizeConst.h.
    The function ProMenuFromStringsRegister() creates menus at run time and attaches actions to the menu buttons. The function takes as arguments all the information required to create auxiliary (*.aux) and user-defined (*.mnu) menu files. The first argument is the default menu name. The next argument enables you to specify an alternate name for the menu if, for instance, your application supports a foreign language. The list of button labels is passed to the function as an array of wide character strings. As with the menu name, you can provide alternate button labels for foreign language support. You can also provide one-line Help for each button.
    After you have registered the menu with a call to the function ProMenuFromStringsRegister(), you can attach actions to the buttons by calling the function ProMenuButtonActionSet() for each button. You must also define an exit action for your run-time menu. To do this, call ProMenuButtonActionSet() and supply the name of the menu instead of a button name. Finally, create the menu by calling ProMenuProcess(), and then ProMenuCreate().
    Customizing the Creo Parametric Navigation Area
    The Creo Parametric navigation area includes the Model Tree and Layer Tree pane, Folder Browser pane, and Favorites pane. The functions described in this section enable Creo TOOLKIT applications to add custom panes to the Creo Parametric navigation area. The custom panes can contain custom dialog box components or WEB pages.
    Adding Custom Web Pages
    To add custom web pages to the navigation area, the Creo TOOLKIT application must:
    1. Add a new pane to the navigation area.
    2. Set an icon for this pane.
    3. Set the URL of the location that will be displayed in the pane.
    Functions Introduced:
  • ProNavigatorpaneBrowserAdd()
    		•
  • ProNavigatorpaneBrowsericonSet()
    		•
  • ProNavigatorpaneBrowserURLSet()
    		•
    The function ProNavigatorpaneBrowserAdd() adds a new pane that can display a web page to the navigation area. The input arguments are:
    •  pane_name—Specify a unique name for the pane. Use this name in susbsequent calls to ProNavigatorpaneBrowsericonSet() and ProNavigatorpaneBrowserURLSet().
    •  icon_file_name—Specify the name of the icon file, including the extension. A valid format for the icon file is .GIF, .JPG, or .PNG. The new pane is displayed with the icon image. If you specify the value as NULL, the default Creo Parametric icon is used.
    •  url—Specify the URL of the location to be accessed from the pane.
    Use the function ProNavigatorpaneBrowsericonSet() to set or change the icon of a specified browser pane in the navigation area.
    Use the ProNavigatorpaneBrowserURLSet() to change the URL of the page displayed in the browser pane in the navigation area.
    Adding Custom Dialog Box Components
    To add a new pane to the navigation area based on Creo TOOLKIT dialog box components:
    1. Add a new pane to the navigation area.
    2. Assign an icon for the pane.
    3. Add the Creo TOOLKIT dialog box components using one of the following methods:
    •  Assign resource files that describe the overall structure of the new navigation pane. To customize the components after placement in the navigation pane, get the window device name and component name using the Creo TOOLKIT functions described in this section and set the necessary values using the Creo TOOLKIT functions described in the section User Interface: Dialogs
    •  To build the layout of the dialog box programmatically, obtain the window device name and layout name. Add each component to the layout as desired using Creo TOOLKIT user interface functions described in the section User Interface: Dialogs.
    Functions Introduced:
  • ProNavigatorpanePHolderAdd()
    		•
  • ProNavigatorpanePHolderDelete()
    		•
  • ProNavigatorpanePHolderShow()
    		•
  • ProNavigatorpanePHolderHide()
    		•
  • ProNavigatorpanePHolderDevicenameGet()
    		•
  • ProNavigatorpanePHolderLayoutGet()
    		•
  • ProNavigatorpanePHolderComponentnameGet()
    		•
  • ProNavigatorpanePHolderHelptextSet()
    		•
    The function ProNavigatorpanePHolderAdd() adds a layout that will be displayed in the new pane in the navigation area. The input arguments are:
    •  pane_name— Specify a unique name for the pane.
    •  resource_name—Specify the name of the resource file to use (whose top component must be a layout, not a dialog box). The contents of the layout from the specified resource file will be inserted into the custom pane.
    •  icon_file_name—Specify the name of the icon file, including the extension. A valid format for the icon file is .GIF, .JPG, or .PNG. The new pane is displayed with the icon image. If you specify the value as NULL, the default Creo Parametric icon is used.
    The function ProNavigatorpanePHolderDelete() deletes the specified pane from the navigation area.
    Use the functions ProNavigatorpanePHolderShow() and ProNavigatorpanePHolderHide() to show and hide the specified pane in the navigation area.
    The function ProNavigatorpanePHolderLayoutGet() returns the layout name for the specified pane in the navigation area. You can create and place the user interface components within this layout.
    Components added to the custom pane actually belong to the Creo Parametric main window dialog. Creo Parametric automatically modifies the names of components loaded from resource files to ensure that no name collisions occur when the components are added. The functions ProNavigatorpanePHolderDevicenameGet() and ProNavigatorpanePHolderComponentnameGet() allow you to locate the names of components that you need to access.
    Use the function ProNavigatorpanePHolderDevicenameGet() to obtain name of the Creo Parametric window owning the new pane in the navigation area.
    Use the function ProNavigatorpanePHolderComponentnameGet() to obtain the complete name of the component in the navigation pane, if loaded from a layout.
    Use the device name and the component name to add or update the placement of the components in the layout with the help of the ProUI* functions. For more information on the user interface functions, refer to the section User Interface: Dialogs.
    The function ProNavigatorpanePHolderHelptextSet()sets the popup help text, which is displayed when you point over the navigator pane component.
    Example 11: Customizing the Creo Parametric Navigation Pane
    The sample code in the file UgNavigatorPane.c located at <creo_toolkit_loadpoint>protk_appls/pt_userguide/ptu_menu shows you how to customize the Creo Parametric navigation pane.
    Registering Notifications to Add and Destroy Content to a New Pane
    The navigation panes are available in every window within a Creo Parametric session. Notifications are provided to the Creo TOOLKIT application when a Creo Parametric window populated with a model so that the application can add the necessary contents to the new pane upon this event. Similarly, notifications are provided before a model is removed from a Creo Parametric window so that the application can cleanup resources related to added panes. For more information on using notifications see the section Event-driven Programming: Notifications.
    Functions Introduced:
  • ProNotificationSet()
    		•
  • ProWindowOccupyPostAction()
    		•
  • ProWindowVacatePreAction()
    		•
    Specify the argument type of the function ProNotificationSet() to PRO_WINDOW_OCCUPY_POST, to call the callback function whose signature matches ProWindowOccupyPostAction(). This function is called when a new Creo Parametric window is created, or when the base window is populated and is used by the application to add the necessary content to the new pane in the navigation area.
    Specify the argument type of the function ProNotificationSet() to PRO_WINDOW_VACATE_PRE, to call the callback function whose signature matches ProWindowVacatePreAction(). This function is called when a Creo Parametric window is closed, or when the base window gets cleared. Use this function to free memory allocated by the Creo TOOLKIT application to add content in the navigation pane.
    Entering Creo Parametric Commands
    Functions Introduced:
  • ProMacroLoad()
    		•
  • ProMacroExecute()
    		•
  • ProMenuCommandPush()
    		•
    The function ProMacroLoad() loads a macro string or a mapkey onto a stack of macros that are executed after control returns to Creo Parametric. A Creo TOOLKIT macro is a string. The macro string is equivalent to a mapkey without the key sequence and the mapkey name.
    Note
    ProMacroLoad() fails if a macro string contains a backslash or if a command splits over two lines with or without a backslash. A macro string can contain multiple commands separated by semicolons. However, each command should entirely appear in a single line.
    The function ProMacroLoad() enables you to execute the commands created by the Creo TOOLKIT application using the following macro:
    ~ Command `<command name>`
    Click Mapkeys Settings in the Environment tab of the Creo Parametric Options dialog box to create a mapkey in the Creo Parametric user interface. Copy the value of the generated mapkey option from the Configuration Editor in the Creo Parametric Options dialog box. An example of a created mapkey is as follows: 
    $F2 @MAPKEY_LABELtest;
    ~ Command `ProCmdModelNew`
    ~ Activate `new` `OK`
    The key sequence is $F2. . The remainder of the string after the first semicolon is the macro string. In this case, it is as follows: 
    ~ Command `ProCmdModelNew`
    ~ Activate `new` `OK`
    You can either pass the mapkey directly or the generated macro string to ProMacroLoad(). Pass the mapkey directly as %key_sequence.
    Note
    Creating or editing the macro string manually is not supported, as mapkeys are not a supported scripting language. The syntax is not defined for users and may not remain constant across different versions of Creo Parametric.
    Execution Rules
    Consider the following rules about the execution of macros:
    •  In asynchronous mode, macros are executed as soon as they are loaded with ProMacroLoad().
    •  In synchronous mode, the mapkey or the macro strings are pushed onto a stack and are popped off and executed only when control returns to Creo Parametric from the Creo TOOLKIT program. Due to the last in, first out nature of the stack, macros that cannot be passed entirely in one ProMacroLoad() call should have the strings loaded in reverse order of desired execution.
    •  To execute a macro from within Creo TOOLKIT, call the function ProMacroExecute(). The function runs the Creo Parametric macro and returns the control to the Creo TOOLKIT application. It executes the macros previously loaded using the function ProMacroLoad(). The function works only in the synchronous mode.
    •  Do not call the function ProMacroExecute() during the following operations:
    ○  Activating dialog boxes or setting the current model
    ○  Erasing the current model
    ○  Replaying a trail file
    •  Clicking the OK button on the dialog box to complete the command operation. In this case, the dialog box may be displayed momentarily without completing the command operation.
    Note
    ○  You can execute only the dialog boxes with built-in exit confirmation as macros, by canceling the exit action.
    ○  It is possible that a macro may not be executed because a command specified in the macro is currently inaccessible in the menus. The functional success of ProMacroExecute() depends on the priority of the executed command against the current context.
    •  If some of the commands ask for an input to be entered from the keyboard (such as a part name), the macro continues execution after you type the input and press ENTER. However, if you must select something with the mouse (such as selecting a sketching plane), the macro is interrupted and ignores the remaining commands in the string.
    This allows the application to create object-independent macros for long sequences of repeating choices (as long as the user does not have to select any geometry).
    A ProStringToWstring() call for defining the macro string must be followed by the following calls:
    •  ProMacroLoad(macro wstring) to load the macro strings or the mapkey
    •  ProMacroExecute() to execute the macro
    Some sample macros in various scenarios are given below.
    Ribbon User Interface Macros
    The following single entry and exit type of interactions are supported by ProMacroExecute().
    •  To switch the wireframe display of model, use the macro:
    Command `ProCmdEnvWireframe` 1
    •  To switch the shaded display of model, use the macro:
    ~ Command `ProCmdEnvShaded` 1
    •  You can switch the display for datum planes and datum axes using the following macros:
    ○  Datum Planes
    ~ Command `ProCmdEnvDtmDisp` 1
    ○  Datum Axes
    ~ Command `ProCmdEnvAxisDisp` 0
    •  To repaint a model, use the macro:
    ~ Command `ProCmdViewRepaint`
    •  To get the default model orientation, use the macro:
    ~ Command `ProCmdNamedViewsGalSelect` `Default`
    •  To get the model information, use the macro:
    ~ Command `ProCmdInfoModel`
    Macros For Feature Creation
    The following macros are used while creating the following features.
    •  To create a hole feature, use the macro:
    ~ Command `ProCmdHole`
    •  To extrude a feature, use the macro:
    ~ Command `ProCmdFtExtrude`
    •  To create a datum plane, use the macro:
    ~ Command `ProCmdDatumPlane`
    Creo Parametric Navigator Macros
    The following macros are provided for Creo Parametric navigator:
    •  For folder navigator:
    ~ Select `main_dlg_cur` `PHTLeft.ProExplorerTab` 1 `PHTLeft.Folders`
    •  For Favorites navigator:
    ~ Select `main_dlg_cur` `PHTLeft.ProExplorerTab` 1 `PHTLeft.FavLay`
    •  For the Model Tree:
    ~ Select `main_dlg_cur` `PHTLeft.ProExplorerTab` 1 `PHTLeft.MdlTreeLay`
    The function ProMenuCommandPush() places the name of a specific menu button in the command input buffer for Creo Parametric. This command is executed after control returns to Creo Parametric from the Creo TOOLKIT application, as if you have selected that menu button. This menu button must be from the menu that is currently displayed in the Creo Parametric user interface.
    Specifying Keyboard Input
    You can specify keyboard input within the command string. As previously specified, a macro must be preceded by a pound sign (#) and terminated by a semicolon. If the field after the semicolon does not start with a pound sign, the data up to the next semicolon is used as input at the next keyboard prompt. If the command currently being executed does not request keyboard input, the system ignores this keyboard data. Note that keyboard data is case-sensitive and spaces are not ignored. A carriage return is indicated when no data appears between the semicolons.
    Note
    Note that the correctness of the sequence is the responsibility of the user. PTC does not guarantee that a sequence will be valid from one version of Creo Parametric to another.