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:

m_root = AgUiApp.Personality2 as AgStkObjectRoot;
m_root.Isolate();
m_root.UnitPreferences.SetCurrentUnit("AngleUnit", "rad");

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:

• Files specific to a single scenario or object (e.g., an ephemeris file). These files should be saved in the scenario folder. If no scenario folder exists because the scenario has not been saved, files may be saved in a temporary location, then moved to the scenario folder upon an OnScenarioSave event, or deleted upon an OnScenarioClose event.

  For files specific to an object, there may be additional considerations. For instance, if the user deletes the object or makes changes to the object such that the file is no longer needed, the programmer can use the OnStkObjectDeleted and OnStkObjectChanged events to determine whether files should be deleted. Similarly, the OnStkObjectRenamed event is useful if, for instance, files are named according to the object name.

• Files for use across multiple scenarios. These files should be saved in a cecntral repository of some sort. Files used by a single user across multiple scenarios may be saved in the STK User Directory. Files used by multiple users sharing a single machine may be saved in the Application Data or ProgramData directory.

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:

• Advanced Techniques
• Install & Deploy UI Plugins

STK Programming Interface 11.0.1