Building Dialogs

 
 
 

The standard way to provide a user interface for a plug-in is to create a custom property and use its property page as the dialog.

If you are going to manipulate data as part of your property page's logic, you need to create an underlying custom property set, or CustomProperty or CustomProperty object. This is the case even if the data you are referencing is not directly associated with any real scene data and will be deleted after the property page closes.

Tip

If you only want to display a message to users or have them answer a Yes/No type of question, the custom property page dialog is probably more powerful than you need. If so, consider using the XSIUIToolkit.MsgBox or UIToolkit::MsgBox feature instead.

  1. Make your custom property a self-installing plug-in by using the XSILoadPlugin and XSIUnloadPlugin callbacks (see Property Callbacks) if either of these situations applies:

    • If you are planning to save your custom property in the scene (ie., if you want the data and layout to persist after the property page closes).

    • If you are planning on distributing it but would like to protect your intellectual knowledge.

  2. Create a CustomProperty object and populate it with Parameter objects (see Defining a Custom Property).

  3. Define a layout for the CustomProperty object using the PPGLayout or PPGLayout object and include any extra controls or logic as necessary (see Property Page Controls).

  4. You may need to tweak the layout to achieve a more user-friendly presentation (see Setting Control Attributes). This can include:

    • You can set a number of attributes on individual controls (PPGItem or PPGItem objects). For example, you can set the size on control items, among other things.

    • Grouping related controls to align them in columns. For example, you could create a column of bitmap widgets on the left matching a column of text boxes on the right.

    • Grouping related controls inside a labelled boxed area. For example, you can group a set of three numeric controls that represent positions in X, Y, and Z.

    • Separating the information into several pages with an associated tab control for easy access.

  5. Create and connect the logic to the PPGLayout object (see Property Callbacks). The logic contains the functions that respond to user action on the property pages. Logic code can be implemented with scripting, in which case it can be embedded directly in the scene or stored in a script file. Alternatively, it can be implemented with C++ code inside a library file (*.dll or *.so).

  6. Associate any help pages to the property page (see Providing Help Files). You can set a location to a HTML file. For example, you can supply an URL to a web page that provides help on your customization.