Create GUI Items

The section provides the necessary steps to create custom toolbar buttons and context-menu items, then associate those buttons and menu items with actions.

How UI Plugins Work

STK UI Plugins work by passing strings back and forth between STK and the plugin code. Those strings are called Commands. When you create a toolbar button, context menu item, or top-level menu item, you will assign a string (the Command) to that button or menu item (for example, "Blue button"). When the user clicks on that button or menu item, STK will pass the Command string back to the plugin: "Plugin, the user has clicked something, and the corresponding Command is 'Blue button'." Your plugin will contain the code that says "If STK gives me a string that says 'Blue button', do something. If the string says 'Red button', then do something else." This is the purpose of the Exec function.

Toolbar buttons and menu items can have various states: for instance, they can be enabled, greyed out, or checked. STK will use those same Command strings to check on the state of toolbar buttons and menu items by querying the plugin, "Plugin, is 'Blue button' a valid command right now?" This is the purpose of the QueryState function.

How to Make That Happen

In the previous section, we implemented the IAgUiPlugin interface and populated the OnStartup and OnShutdown methods. IAgUiPlugin also has OnInitializeToolbar and OnDisplayContextMenu methods. These are where we will define (and associate Commands with) each of the buttons to be added to our custom toolbar, or each item to be added to the object context menu.

The next step is then to implement the IAgUiPluginCommandTarget interface. IAgUiPluginCommandTarget contains the Exec and QueryState methods that will be called by STK when a toolbar button or menu item is clicked or changes state, as described above.

The following instructions assume that you already have a project that is a valid UI plugin.

Add a Toolbar Button or Menu Item

In this section, we will add a toolbar button, a context menu item, and a top-level menu item. One command will be assigned to the toolbar button; a second command will be assigned to the context menu and top-level menu items.

Add References

Add a reference to the System.Windows.Forms namespace. The System.Windows.Forms namespace provides access to Windows-based user interface features.

1. Right-click References in the Solution Explorer and select Add Reference...
2. On the .NET tab, select System.Windows.Forms and click OK.
3. Add the corresponding using directive/imports statement:

   [C#]
   using System.Windows.Forms;

   [Visual Basic .NET]
   Imports System.Windows.Forms

Add a Toolbar Button

To add buttons to your custom toolbar, locate the OnInitialzeToolbar method of the AgUiPlugin interface, and modify it to match the following:

public void OnInitializeToolbar(IAgUiPluginToolbarBuilder ToolbarBuilder)
{
    ToolbarBuilder.AddButton("MyCompany.MySampleUIPlugin.MyFirstCommand", "Example Button 1", "Example UI Plugin Toolbar Button", AgEToolBarButtonOptions.eToolBarButtonOptionAlwaysOn, null);
}

Public Sub OnInitializeToolbar(ToolbarBuilder As AGI.Ui.Plugins.IAgUiPluginToolbarBuilder) Implements AGI.Ui.Plugins.IAgUiPlugin.OnInitializeToolbar

    ToolbarBuilder.AddButton("MyCompany.MySampleUIPlugin.MyFirstCommand", "Example Button 1", "Example UI Plugin Toolbar Button", AgEToolBarButtonOptions.eToolBarButtonOptionNone, Nothing)

End Sub

Build your project, then start up STK. You should see your new button, with the text "Example Button 1." Clicking on it doesn't do anything yet; that comes in the Implement the Command Target Interface section.

Note: STK caches toolbar display properties. If you make a change to your custom toolbar buttons, rebuild the code, re-start STK, and don't see your changes reflected in STK, reset the toolbar. Go to Edit > Preferences > UI Plugins. Select your plugin from the list, and click "Reset Toolbars." This will refresh the toolbar cache.

See also: Use Toolbar or Menu Icons

Add a Context Menu Item

Locate the IAgUiPlugin interface's OnDisplayContextMenu handler and modify it to match the following:

public void OnDisplayContextMenu(IAgUiPluginMenuBuilder MenuBuilder)
{
    MenuBuilder.AddMenuItem("MyCompany.MySampleUIPlugin.MySecondCommand", "Example Menu Item 1", " Display a message box.", null);
}

Public Sub OnDisplayContextMenu(MenuBuilder As AGI.Ui.Plugins.IAgUiPluginMenuBuilder) Implements AGI.Ui.Plugins.IAgUiPlugin.OnDisplayContextMenu

    MenuBuilder.AddMenuItem("MyCompany.MySampleUIPlugin.MySecondCommand", "Example Menu Item 1", "Display a message box", Nothing)

End Sub

Build your project, then start up STK. Create a new scenario or open an existing scenario. Right-click on an object in the Object Browser. In the shortcut menu, you will see a sub-menu titled <Object Class> Plugins. Your "Example Menu Item 1" should be appear there. Clicking on it doesn't do anything yet; that comes in the Implement the Command Target Interface section.

See also: Use Toolbar or Menu Icons

See also: Make Context Menus Context-sensitive, so that your menu items only appear for certain types of STK objects.

See also: Create a submenu

See also: Insert Menu Items in Other Locations

Implement the Command Target Interface

You have a toolbar button and a context menu item, but they don't do anything. When you click the one of those items, STK will send the corresponding command ("MyCompany.MyCSharpUIPlugin.MyFirstCommand" for the toolbar button, "MyCompany.MyCSharpUIPlugin.MySecondCommand" for the Context menu item) to the plugin, but there is nothing in the plugin that is listening for those commands. The missing piece is the implementation of the IAgUiPluginCommandTarget interface.

1. Locate the MySampleUIPlugin class definition. Append the IAgUiPluginCommandTarget interface to the class declaration:

   [C#]
   public class MySampleUIPlugin: IAgUiPlugin, IAgUiPluginCommandTarget

   [Visual Basic .NET]
   Public Class MySampleUIPlugin Implements IAgUiPlugin, IAgUiPluginCommandTarget

2. For C#, right-click the interface (IAgUiPluginCommandTarget). Select Implement Interface, then Implement Interface again. For VB, at the end of the Implements line, hit the Enter key.

   This will implement the IAgUiPluginCommandTarget interface, exposing its members. IAgUiPluginCommandTarget has two public methods: Exec and QueryState.

3. Exec is called when your toolbar button or menu item is clicked. Locate the Exec method and modify it to match the following:

   [C#]
   public void Exec(string CommandName, IAgProgressTrackCancelM TrackCancel, IAgUiPluginCommandParameters Parameters) { if (string.Compare(CommandName, "MyCompany.MyCSharpUIPlugin.MyFirstCommand", true) == 0) { MessageBox.Show("Hello World!"); } else if (string.Compare(CommandName, "MyCompany.MyCSharpUIPlugin.MySecondCommand", true) == 0) { MessageBox.Show(CommandName); } }

   [Visual Basic .NET]

   Public Sub Exec(CommandName As String, TrackCancel As IAgProgressTrackCancel, Parameters As IAgUiPluginCommandParameters) Implements IAgUiPluginCommandTarget.Exec If (String.Compare(CommandName, "MyCompany.MySampleUIPlugin.MyFirstCommand", True) = 0) Then MessageBox.Show("Hello World!") ElseIf (String.Compare(CommandName, "MyCompany.MySampleUIPlugin.MySecondCommand", True) = 0) Then MessageBox.Show(CommandName) End If End Sub

4. STK will call QueryState at various times in order to determine the state of the toolbar buttons and menu items associated with each command. This allows you to specify whether a button or menu item is enabled, grayed out, checked, etc. Locate the QueryState method and modify it to match the following:

   [C#]

   public AgEUiPluginCommandState QueryState(string CommandName) { if (string.Compare(CommandName, "MyCompany.MyCSharpUIPlugin.MyFirstCommand", true) == 0) { return AgEUiPluginCommandState.eUiPluginCommandStateEnabled | AgEUiPluginCommandState.eUiPluginCommandStateSupported; } else if (string.Compare(CommandName, "MyCompany.MyCSharpUIPlugin.MySecondCommand", true) == 0) { return AgEUiPluginCommandState.eUiPluginCommandStateEnabled | AgEUiPluginCommandState.eUiPluginCommandStateSupported; } return AgEUiPluginCommandState.eUiPluginCommandStateNone; }

   [Visual Basic .NET]

   Public Function QueryState(CommandName As String) As AgEUiPluginCommandState Implements IAgUiPluginCommandTarget.QueryState If (String.Compare(CommandName, "MyCompany.MySampleUIPlugin.MyFirstCommand", True) = 0) Then Return AgEUiPluginCommandState.eUiPluginCommandStateEnabled Or AgEUiPluginCommandState.eUiPluginCommandStateSupported ElseIf (String.Compare(CommandName, "MyCompany.MySampleUIPlugin.MySecondCommand", True) = 0) Then Return AgEUiPluginCommandState.eUiPluginCommandStateEnabled Or AgEUiPluginCommandState.eUiPluginCommandStateSupported End If End Function

   Right now, both commands are always enabled and supported, but this may change this later.

   The enumeration AgEUiPluginCommandState is a bit mask: to represent several states simultaneously (such as Enabled and Supported), combine them together with the bitwise OR operator, as in the above example.

   Every time the user right-clicks on an object, STK will call QueryState in order to determine the proper state of your menu items. STK also calls QueryState during its idle cycles to determine the proper state of your toolbar buttons. Since QueryState is called so often, this function should be as simple and execute as fast as possible.

   Note: QueryState is not the only thing that controls the state of toolbar buttons. One of the arguments passed to ToolbarBuilder.AddButton is the enumeration AgEToolBarButtonOptions, which also affects the state of the button. See the AgEToolBarButtonOptions Help to read how those members affect interaction with QueryState.

5. Build your project, then start up STK. Click your toolbar button and your context menu item. Confirm that those actions launch the appropriate message box.

See also: Command Strings Best Practices

See also: Use Toolbar or Menu Icons

STK Programming Interface 11.0.1