UI Plugins: The Plug Part
- Nov 8, 2016
- Tech Tip
-
Integration
The purpose of this blog is to explain interaction between the STK Desktop application and the UI Plugin. Your plugin has to define the interaction with STK Desktop application by implementing required interfaces.
This interaction between STK and all the plugins is done through string commands. Each toolbar button or context menu entry define the string value of the entry. When the entry is clicked, the STK application broadcasts the string value to all UI plugins currently loaded in the application. Since all UI plugins will receive the string value of your command, you need to make sure that the value will be relatively unique. I like to make the string values similar to my plugin name.
IAgUiPlugin interface defines how the plugin is added to toolbars and menus. IAgUiPlugin2 interface is an extension of the IAgUiPlugin and I will discuss them together. All parts of the interface have to be implemented in order to build your plugin. So, you need to implement OnInitializeToolbar method even if you do not plan to create new toolbar (but you can leave the method blank). The interfaces require six methods:
OnDisplayConfigurationPage(IAgUiPluginConfigurationPageBuilder ConfigPageBuilder) OnDisplayContextMenu(IAgUiPluginMenuBuilder MenuBuilder) OnInitializeToolbar(IAgUiPluginToolbarBuilder ToolbarBuilder) OnDisplayMenu(string MenuTitle, AgEUiPluginMenuBarKind MenuBarKind, IAgUiPluginMenuBuilder2 MenuBuilder) OnShutdown() OnStartup(IAgUiPluginSite PluginSite)
The method names are pretty self-explanatory. The OnStartup method input parameter contains a link (pointer) to the host application, in this case the STK Desktop Application.
Second required interface is IAgUiPluginCommandTarget that implements two methods:
Exec(string CommandName, IAgProgressTrackCancel TrackCancel, IAgUiPluginCommandParameters Parameters) QueryState(string CommandName)
QueryState method controls if your command are enabled or not. Exec method receives the broadcasted message from STK that the user clicked on a custom button. Again, your plugin will be notified when any custom button is clicked, so your code has to be able to recognize if any of your plugin buttons are clicked.
STK Programming Interface help uses string literals in the example for UI Plugins. It is good programming practice to define string literals in a central location, but it is crucial to do it when developing UI Plugins. Each command string is used up to four times in the code. Even copying and pasting string values can introduce an error that cannot be detected by the compiler. I like to create member (global) variables for each command string in my UI Plugin.
IAgUiPlugin3DNotify interface was introduced with STK 11. The interface allows the UI Plugins to interact with STK globe. I will discuss the interface in a future blog entry.