Implementing a Custom User Interface for an RT3 Plugin

When using RT3 with STK or Viewer, your plugin is given a default grid-based user interface for its configuration. It is possible, however, to implement your own user interface for entity providers, entity processors, queries, streams and actions.

There are two types of UI plugins, stand-alone and embedded. A stand-alone plugin is responsible for bringing up its own dialog - either modal or modeless - and must control all aspects of its UI. An embedded plugin, however, is simply a small part of a large dialog. For example, compare these two query configuration dialogs from STK:

When you add a query object, the query configuration dialog is displayed. On the left, the top portion of this dialog is specific to AgRt3SimplyQuery. If you were to implement a plugin without a custom UI, it would show up in the default configuration grid, as shown by the image on the right. The graphics options would remain the same, and the only thing that would change is the part specific to the plugin. If you implement a stand-alone UI, however, then you are responsible for configuring the entire query, graphics and all - not just the section custom to your plugin. Thus, your dialog would be displayed and this one would not.

Once you understand the different plugin types, implementing one is fairly straightforward. First, the stand-alone plugin must implement IAgUiRtDialog which contains two properties and one method. The first, Name, is the type name of the plugin (similar to the Name property on IAgRtPlugin). The second, Data, will contain the instance of the plugin which the UI is meant to configure. It is set by whoever is using the UI plugin. Finally, Activate, brings up its dialog and returns AgUiRtDialogResult result, which can either be OK, Cancel, or Modeless.

Creating an embedded plugin is equally easy. You must implement IAgUiRtWindowHandle, and IAgUiRtWindowHandleEvents. IAgUiRtWindowHandleEvents executes an event when the UI is modified; this allows the parent page to detect that a change has been made. IAgUiRtWindowHandle contains one method and three properties. The Apply method tells the plugin to apply the changes to the underlying Data object. If Apply is not called, then the Data object will not be changed. The HWND property returns the HWND of the window to be embedded. Once you are ready to start testing and debugging your UI, see Registering an RT3 Plugin.

STK 11.2.1 Programming Interface