User Interface: Dashboards
This section introduces the basics of dashboards and describes how Creo TOOLKIT offers the capability to create and control dashboards. Creo TOOLKIT applications can construct dashboards for any tool where they would typically require a dialog box.
The behavior of the Creo TOOLKIT dashboard is similar to the Creo Parametric dashboard. The TOOLKIT dashboards use the same commands and dismiss mechanism as the native Creo Parametric dashboard. However, individual commands may have different accessibility logic and so different dashboards can have slightly different commands available.
Introduction to Dashboards
A dashboard is an embedded "dialog box" at the top of the Creo Parametric graphics window. A dashboard typically appears when you create or modify a feature in Creo Parametric. It offers the necessary controls, inputs, status and guidance for creating or editing of features.
Dashboard components
Image
1 Tool Icon
2 Dialog Bar
3 Slide-down Panels
4 Standard Buttons
A dashboard consists of the following components:
•  A main dialog bar, which show the commonly used commands and entry fields. You perform most of your modeling tasks in the graphics window and the dialog bar. When you activate a tool, the dialog bar displays commonly used options and collectors.
•  Standard buttons for controlling the tool.
•  Slide-down panels that open to reveal less commonly-used functionality. You can use them to perform advanced modeling actions or retrieve comprehensive feature information.
•  A bitmap identifies the tool (typically the same icon used on buttons that invoke the tool).
Creo Parametric uses the dashboard to create features that involve extensive interaction with user interface components and geometry manipulation. You can use dashboards in Creo TOOLKIT applications:
•  Where a dialog box is too large in size or is intrusive onto the graphics window. Dashboards enable you to make a smooth-flow tool.
•  To present a streamlined "simple-user" activity with more complicated actions available to "expert users".
•  Where Creo TOOLKIT dashboards are not only limited to feature creation activities and solid model modes.
Dashboard
An opaque pointer ProUIDashboard is a handle to the overall dashboard tool after it has been shown.
Showing a Dashboard
Functions Introduced:
  • ProUIDashboardShow()
    		•
  • ProUIDashboardshowoptionsAlloc()
    		•
  • ProUIDashboardshowoptionsNotificationSet()
    		•
  • ProUIDashboardshowoptionsTitleSet()
    		•
  • ProUIDashboardshowoptionsIconSet()
    		•
  • ProUIDashboardshowoptionsHelpTextSet()
    		•
  • ProUIDashboardshowoptionsDefaultOpenSet()
    		•
  • ProUIDashboardshowoptionsFree()
    		•
  • ProUIDashboardDestroy()
    		•
    Use the function ProUIDashboardShow() to push a new dashboard User Interface into the dashboard stack mechanism. The dashboard will be shown in the message area of Creo Parametric. This function creates an event loop, and thus does not exit until the dashboard is being dismissed.
    Use the function ProUIDashboardshowoptionsAlloc() to allocate a handle containing data used to build a dashboard. The input arguments for this function are:
    •  main_page—Specifies the main page for the dashboard.
    •  slideup_pages—Specifies a ProArray of handles representing the slide-down pages, if needed.
    •  appdata—Specifies the application data to be stored with the dashboard.
    Use the function ProUIDashboardshowoptionsNotificationSet() to assign a callback function to be called for the indicated event occurrence in the dashboard. The input arguments for this function are:
    •  options—Specifies a handle to data used to build a dashboard.
    •  notification—Specifies the notification function to be called for the given event.
    •  appdata—Specifies the application data to be passed to the callback function when it is invoked.
    You can register event notifications for the following events on the dashboard:
    •  PRO_UI_DASHBOARD_CREATE—when the dashboard is first initialized (before the pages are initialized).
    •  PRO_UI_DASHBOARD_SHOW—when the dashboard is shown or resumed.
    •  PRO_UI_DASHBOARD_HIDE—when the dashboard is paused and replaced by another tool.
    •  PRO_UI_DASHBOARD_ENTER—when you switch to a dashboard from another component in the ribbon user interface
    •  PRO_UI_DASHBOARD_EXIT—when you leave the dash board and return to a component on the ribbon user interface
    •  PRO_UI_DASHBOARD_DISMISS—upon the dashboard “close” event.
    •  PRO_UI_DASHBOARD_DESTROY—when the dashboard is finally destroyed.
    The function ProUIDashboardshowoptionsTitleSet() sets the title of the dashboard. The input arguments of this function are:
    •  dash_options—Specifies the handle containing data that is used to build the dashboard.
    •  title—Specifies the title of the dashboard.
    Use the function ProUIDashboardshowoptionsIconSet() to set an icon for the specified dashboard. This is the first icon in the first group from the left on the dashboard.
    The function ProUIDashboardshowoptionsHelpTextSet() sets the help text for the specified dashboard.
    Image
    •  1. Dashboard icon
    •  2. Dashboard help text
    Use the function ProUIDashboardshowoptionsDefaultOpenSet() to set the specified dashboard as the open by default page. The input arguments follow:
    •  dash_options—Specify the handle to the data used to build the dashboard.
    •  page_name—Specify the page name to be opened by default.
    You can use the function ProUIDashboardshowoptionsFree() to free a handle containing the data used to build a dashboard.
    Use the function ProUIDashboardDestroy() to pop the dashboard from the dashboard stack mechanism. The dashboard User Interface will be destroyed.
    Accessing a Dashboard
    Functions Introduced:
  • ProUIDashboardUserdataGet()
    		•
  • ProUIDashboardStdlayoutGet()
    		•
  • ProUIDashboardBitmapSet()
    		•
    Use the functions ProUIDashboardUserdataGet() to get the application data you attached to the dashboard items upon registration. This can be used to store the current state of the tool, and thus to control the visibility of components.
    Creo TOOLKIT does not currently provide access to create the feature dashboard’s standard buttons. However, you can use ProUIDashboardStdlayoutGet() to get the layout name where you can create and place the buttons in the standard button area. Typically this consists of (at least) OK and Cancel buttons.
    Use the function ProUIDashboardBitmapSet() to assign the icon for the dashboard, which appears to the left of the slide-down panel buttons.
    Dashboard Page
    Each section of content in a dashboard is called a dashboard page. The opaque handle ProUIDashboardPage represents an individual page, that is, either the dialog bar, or a single slide-down panel.
    Dashboard Page Options
    Functions Introduced:
  • ProUIDashboardpageoptionsAlloc()
    		•
  • ProUIDashboardpageoptionsNotificationSet()
    		•
  • ProUIDashboardpageoptionsFree()
    		•
    Use the function ProUIDashboardpageoptionsAlloc() to allocate a handle representing a single page (or layout) that will be shown in a dashboard. The input arguments for this function are:
    •  page_name— Specifies the page name (must be unique).
    •  resource_name—Specifies the name of the resource file to use (whose top component must be a layout, not a dialog). If NULL, an empty default layout is used.
    •  application_data—Specifies the application data stored for the page.
    Use the function ProUIDashboardpageoptionsNotificationSet() to assign a function to be called upon a certain event occurring in the dashboard. The input arguments for this function are:
    •  options—Specifies a handle representing a dashboard page.
    •  notification—Specifies the function to be called upon the designated event occurrence.
    •  appdata—Specifies the application data passed to the callback function when it is invoked.
    You can register event notifications for the following events on the dashboard page:
    •  PRO_UI_DASHBOARD_PAGE_CREATE—when the page is first created.
    •  PRO_UI_DASHBOARD_PAGE_SHOW—when the page is shown (slide-down panels only).
    •  PRO_UI_DASHBOARD_PAGE_HIDE—when the page is hidden (slide-down panels only).
    •  PRO_UI_DASHBOARD_PAGE_DESTROY—when the page is destroyed.
    You can use the function ProUIDashboardpageoptionsFree() to free a handle representing a single page (or layout) that will be shown in a dashboard.
    Accessing a Dashboard Page
    Functions Introduced:
  • ProUIDashboardPageGet()
    		•
  • ProUIDashboardpageTitleSet()
    		•
  • ProUIDashboardpageForegroundcolorSet()
    		•
  • ProUIDashboardStdlayoutDefaultBtnsAdd()
    		•
  • ProUIDashboardStdlayoutButtonAdd()
    		•
  • ProUIDashboardStdlayoutDefaultButtonNameGet()
    		•
  • ProUIDashboardPauseresumeButtonStateGet()
    		•
  • ProUIDashboardPauseresumeButtonStateSet()
    		•
  • ProUIDashboardpageStateSet()
    		•
  • ProUIDashboardpageVisibleSet()
    		•
  • ProUIDashboardpageNameGet()
    		•
  • ProUIDashboardpageDashboardGet()
    		•
  • ProUIDashboardpageUserdataGet()
    		•
  • ProUIDashboardpageClose()
    		•
  • ProUIDashboardpageOpen()
    		•
  • ProUIDashboardpageIsOpen()
    		•
    Use the function ProUIDashboardPageGet() to obtain the handle to a given page from the dashboard. The input arguments for this function are:
    •  dashboard—Specifies the dashboard handle.
    •  name—Specifies the page name. Pass NULL to get the handle to the main page.
    Use the function ProUIDashboardpageTitleSet() to assign the title string for the dashboard page. This will be shown as the button name for the slide-down panel. This should typically be called from the CREATE notification of the dashboard page.
    Use the function ProUIDashboardpageForegroundcolorSet() to set the text color for the button that invokes a slide-down panel. This technique is used in several Creo Parametric tools to notify the user that they must enter one of the panels to complete the tool.
    The function ProUIDashboardStdlayoutDefaultBtnsAdd() adds new standard push buttons to the Creo Parametric dashboard. The input arguments follow:
    •  pageHandler—A handle to the dashboard page.
    •  buttons—The bit mask to identify the buttons to be added. This value is defined by the enumerated data type ProUIDashboardStdLayoutButton. The valid values are as follows:
    ○  PRO_UI_DASHBOARD_BUTTON_PAUSE_RESUME
    ○  PRO_UI_DASHBOARD_BUTTON_PREVIEW
    ○  PRO_UI_DASHBOARD_BUTTON_OK
    ○  PRO_UI_DASHBOARD_BUTTON_CANCEL
    The function ProUIDashboardStdlayoutButtonAdd() adds a new push button to the Creo Parametric dashboard. This function is executed only once during a Creo Parametric session for each push button. Subsequent calls to this function for a previously loaded push button are ignored. The input arguments follow:
    •  page_handle—A handle to the dashboard page.
    •  button_Name—A unique name for the push button. The maximum size should be less than PRO_NAME_SIZE.
    •  button_label—A label for the push button. The maximum size should be less than PRO_LINE_SIZE.
    •  one_line_help—A one-line help for the push button. The maximum size should be less than PRO_LINE_SIZE
    •  icon—An image of the push button.
    •  filename—The name of the message file that contains the label and help string.
    PRO_NAME_SIZE and PRO_LINE_SIZE are defined in the ProSizeConst.h header file.
    The function ProUIDashboardStdlayoutDefaultButtonNameGet() returns the default name of the specified button id. The output argument button_name is in the form of a character string. Use the function ProStringFree() to free this string.
    The function ProUIDashboardPauseresumeButtonStateGet() returns the state of the button. The output argument state is defined by the enumerated data type ProUIDashboardPauseResumeButtonState and the valid are as values follows:
    •  ProUIDashboardButtonPauseState—Specifies that the button is in a paused state.
    •  ProUIDashboardButtonResumeState—Specifies that the button is in a resume state.
    Use the function ProUIDashboardPauseresumeButtonStateSet() to set the pause or resume state of the button.
    Use the function ProUIDashboardpageStateSet() to modify the visibility of the button that opens the dashboard page according to the page state. This function affects the background and foreground of the button. The input arguments follow:
    •  page—Handle to the dashboard page defined by ProUIDashboardPage.
    •  state—State of the page defined by the enumerated data type ProUIDashboardPageState. The valid values are as follows:
    ○  PRO_UI_DASHBOARD_PAGE_DEFAULT_STATE
    ○  PRO_UI_DASHBOARD_PAGE_WARNING_STATE
    ○  PRO_UI_DASHBOARD_PAGE_ERROR_STATE
    Use the function ProUIDashboardpageVisibleSet() to modify the visibility of the button that opens the dashboard page.
    Use the function ProUIDashboardpageNameGet() to obtain the name of the page.
    Use the function ProUIDashboardpageDashboardGet() to obtain the dashboard that owns this page.
    Use the function ProUIDashboardpageUserdataGet()to obtain the application stored with this dashboard page on registration.
    Use the function ProUIDashboardpageClose() to close the dashboard slide-down page.
    Use the function ProUIDashboardpageOpen() to open the specified dashboard page.
    Use the function ProUIDashboardpageIsOpen() to check if the specified dashboard page is open. If the page is open, the function returns a ProBoolean output argument with the value PRO_B_TRUE. Otherwise, the function returns PRO_B_FALSE.argument
    Accessing Components in the Dashboard Pages
    Components added to the dashboard are actually "owned" by the Creo Parametric dialog window. 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 in this section allow you to locate the names of components that you need to access.
    Functions Introduced:
  • ProUIDashboardpageDevicenameGet()
    		•
  • ProUIDashboardpageComponentnameGet()
    		•
    Use the function ProUIDashboardpageDevicenameGet() to obtain the device name owning the dashboard page. This name should be used in other ProUI functions to access the components stored in the dashboard page.
    Use the function ProUIDashboardpageComponentnameGet() to obtain the real component name in the dashboard page, if the page contents were loaded from a layout. This name should be used in ProUI functions for accessing a component in the dashboard.