User Interface: Dashboards
This section introduces the basics of dashboards and describes how Creo Parametric TOOLKIT offers the capability to create and control dashboards. Creo Parametric TOOLKIT applications can construct dashboards for any tool where they would typically require a dialog box.
The behavior of the Creo Parametric 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 Parametric 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 Parametric 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()
    		•
  • 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.
    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 Parametric 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()
    		•
  • ProUIDashboardpageNameGet()
    		•
  • ProUIDashboardpageDashboardGet()
    		•
  • ProUIDashboardpageUserdataGet()
    		•
  • ProUIDashboardpageClose()
    		•
    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.
    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 obtains the application stored with this dashboard page on registration.
    Use the function ProUIDashboardpageClose() to close the dashboard slide-down page.
    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.