Best Practices

Command Strings

Design command strings for uniqueness. The user of your plugin will likely have more than one UI plugin running simultaneously in STK. When a custom toolbar button or menu item is clicked, STK will call Exec not just for the plugin that that command pertains to, but in every active plugin. Your command strings need to be unique across all of those plugins. For this reason, AGI recommends a MyCompany.MyPluginName.MyCommandName convention, to help enforce that uniqueness.

Use string variables. For clarity in this example, we have used literal strings in all of our function calls, string comparisons, etc. In practice, this can make it more difficult to change your command strings and debug your code. A better idea would be to use class variables for the command strings.

Isolate the Root

If the plugin either inputs or retrieves data from STK, it is always good practice to specify the units via the IAgStkObjectRoot.UnitPreferences property. Setting UnitPreferences on the root object, however, has additional implications.

The AgStkObjectRoot is a singleton—meaning, every time any plugin or other application instantiates the root, it is not a new root object that is created, but rather just a new pointer to the one root object. Therefore, when Plugin 1 instantiates the root, and Plugin 2 instantiates the root, both plugins are in fact manipulating the same root object. If Plugin 1 sets, for instance, angle units to radians, then Plugin 2 sets angle units to degrees, Plugin 1 will not function as expected.

To prevent this interference, isolate your root using the Isolate method, then set unit preferences:

[C#]
m_root = AgUiApp.Personality2 as AgStkObjectRoot;
m_root.Isolate();
m_root.UnitPreferences.SetCurrentUnit("AngleUnit", "rad");
[Visual Basic .NET]
m_root = DirectCast(m_pSite.Application.Personality2, AgStkObjectRoot)
m_root.Isolate()
m_root.UnitPreferences.SetCurrentUnit("AngleUnit", "rad")

Working with Toolbars

STK caches toolbar data. For this reason, changes to the plugin toolbar may not be immediately reflected. In STK, go to Edit > Preferences > UI Plugins. There will likely be multiple UI plugins in the list. Highlight the plugin of concern, then click "Reset Toolbars."

STK uses workbook files to manage the display and placement of windows and toolbars. When a scenario is saved, STK saves a corresponding workbook file, preserving information about which toolbars and buttons are displayed. There are also default workbooks that control the default appearance of a new scenario, and the appearance of STK when no scenario is loaded.

When no scenario is loaded, the STK default behavior is to display the toolbars of active plugins. When a new scenario is created, the STK default behavior is to display only the toolbars specified in the default workbook. For this reason, you will see your toolbar appear when you start up STK with no scenario, but once you create a new scenario, the toolbar is not displayed.

To display or hide a toolbar in STK, from the View menu, select Toolbars, and check or uncheck the listed toolbars as desired. The same toolbar selection menu can be accessed by right-clicking in the empty space adjacent to the displayed toolbars.

Window Management

STK keeps track of the state (docked, integrated, or floating), size, and position of windows in STK. This is a usability feature that improves the user experience. Similarly, a user may make similar adjustments to the forms in the UI Plugin. The programmer may wish to capture this information when the window is closed, so that when the window is re-opened, it will appear in the state, size, and position that the user had set.

File Management

Each STK scenario is composed of a stack of multiple files. Depending on the complexity and number of objects in the scenario, a single scenario could produce anywhere from a handful to a hundred or more files. For this and other reasons, best practice dictates that each scenario be saved in its own folder. The New Scenario Wizard helps to enforce this convention. No files are written when a new scenario is created and named, but when the scenario is saved for the first time, STK creates a new folder with the same name as the scenario, then saves the scenario and object files in the new folder.

If the UI Plugin creates or writes any files (aside from STK scenario or object files), those files will not be saved automatically by STK, and must be managed by the plugin. Most external files will fall into one of these categories:

For any files generated by the plugin, the programmer should carefully consider the scope of those files, and what sorts of events should trigger a save or deletion.

Related Topics:

STK 11.2.1 Programming Interface