Package Overview
These topics describe how to use the following sub-packages:
Domain Sub-Package
The Domain sub-package supports drag-and-drop from treeviews to domains. This allows you to provide a custom action when the user drags the cursor from a treeview to a domain or drops an object (dragged from a treeview) onto a domain. A typical use of this drag-and-drop functionality is to install objects in a network or graphics domain by dragging them from a tree-based palette or menu.
Icon Sub-Package
The Icon sub-package contains functions for general icon-related activities and for using managed icons. You can get an icon by name with Ets_Icon_Find(). To export an icon image in various formats (such as GIF or PNG), use Ets_Icon_Export(). To open an icon palette, use Ets_Icon_Palette_Create().
Many of the functions in this package support managed icons, which are icons that can be created dynamically from text strings. They are useful for visualizing data in the project workspace. You can create a managed icon with Ets_Icon_From_Text_Create() or Ets_Icon_From_Textlist_Create(). Managed icons have a reference count used to track their usage, allowing them to be automatically destroyed when no longer used. Each time a managed icon is used in a visualization, increase its reference count by calling Ets_Icon_Reference(). When an icon is removed from the visualization, decrease its reference count with Ets_Icon_Unreference(). This function includes an option to prevent the automatic destruction of an unused icon. You can destroy icons that were not destroyed automatically by calling Ets_Icon_Unreferenced_Destroy().
Progress Bar Sub-Package
When a lengthy operation is being performed, it is helpful to keep the user informed of the operation's progress with a progress bar. The Progress Bar sub-package allows you to manage multiple simultaneous progress bars. All progress bars appear in a single dialog box and each can be separately abortable. This API supports up to 5 simultaneous progress bars; however, we suggest using a maximum of 2 or 3 (for usability reasons and to allow sub-processes to display progress bars, if needed).
You can open a new progress bar with Ets_Progress_Bar_Handle_Start(). After a progress bar has been opened, you can update it using Ets_Progress_Bar_Handle_Advance(), which will also check to see if the Cancel button for that bar (if active) has been pressed. You can check the current setting of a progress bar with Ets_Progress_Bar_Handle_Current_Get() or specify an absolute setting with Ets_Progress_Bar_Handle_Progress_Set().
If you need to modify an open progress bar, you can change the maximum value with Ets_Progress_Bar_Handle_Max_Set() or change the title with Ets_Progress_Bar_Handle_Title_Set(). You can reset a progress bar to zero (and also change the maximum value, title, or abortable status) with Ets_Progress_Bar_Handle_Reset().
Progress bars can be indeterminate, meaning that they have no defined maximum value. An indeterminate progress bar is displayed with a "barber pole" pattern instead of a specific value. You can use an indeterminate progress bar as a placeholder while determining the scope of a task.
To create an indeterminate progress bar, use Ets_Progress_Bar_Handle_Start() with max_value equal to ETSC_PROGRESS_BAR_INDETERMINATE. To animate the barber pole pattern, repeatedly set the bar's progress with Ets_Progress_Bar_Handle_Advance() or Ets_Progress_Bar_Handle_Progress_Set(). When ready, you can make the progress bar determinate by setting a maximum value with Ets_Progress_Bar_Handle_Reset().
An open progress bar can be closed with Ets_Progress_Bar_Handle_End().
In addition to the preceding functions, Riverbed Modeler continues to support the original functions for a single progress bar (from release 10.5 and earlier). However, we suggest that you not use these functions in new code: