Add a Custom User Control

Now that you have toolbar buttons and menu items, you may want one of those items to launch a custom user control.

Add a New User Control

  1. In the solution explorer, right click the project and select Add, then New Item.
  2. From the list of templates, select User Control.
  3. Give it a descriptive name, such as CustomUserInterface. Click Add.
  4. The newly created control will appear in design mode. We will come back to this later.
  5. The new class does not have any of our convenient using directives. Add AGI.Ui.Plugins and AGI.STKObjects:
    [C#] 
    using AGI.Ui.Plugins;
using AGI.STKObjects;
    [Visual Basic .NET] 
    Imports AGI.Ui.Plugins
Imports AGI.STKObjects
Imports System.Windows.Forms
  6. Now that you have a custom user control, you need to edit the child class (CustomUserInterface) so that it can communicate with the parent class (MySampleUIPlugin), and so that it does something. Then you need to edit the parent class so that it can communicate with the child: first create a method that will open the new user control, then call that method from the Exec function.

Configure the CustomUserInterface

If you want your CustomUserInterface control to manipulate your STK scenario, it needs some way to communicate with its parent, the MySampleUIPlugin class. In this example, the Custom UI will access the STK root object property of the MyCSharpUIPlugin class, then use that root to determine whether a scenario is loaded. Your CustomUserInterface class needs to be a class of a type that is embedded within a UI plugin.

  1. Locate the CustomUserInterface class definition. Append the IAgUiPluginEmbeddedControl interface to the class declaration:
    [C#] 
    public partial class CustomUserInterface : UserControl, IAgUiPluginEmbeddedControl
    [Visual Basic .NET] 
    Public Class CustomUserInterface
    Implements IAgUiPluginEmbeddedControl
  2. For C#, right-click the interface (IAgUiPluginEmbeddedControl). Select Implement Interface, then Implement Interface again. For VB, at the end of the Implements line, hit the Enter key.

    This will implement the IAgUiPluginEmbeddedControl interface, exposing its members.

  3. Add the following three class variables:
    [C#] 
    private IAgUiPluginEmbeddedControlSite m_pEmbeddedControlSite;
private MySampleUIPlugin m_uiplugin;
private AgStkObjectRoot m_root;
    [Visual Basic .NET] 
    Dim m_pEmbeddedControlSite As IAgUiPluginEmbeddedControlSite
Dim m_uiplugin As MySampleUIPlugin
Dim m_root As AgStkObjectRoot
  4. Edit the SetSite method as follows. Note that we use this opportunity to create a pointer to the STK Object Root.
    [C#] 
    public void SetSite(IAgUiPluginEmbeddedControlSite Site)
{
    m_pEmbeddedControlSite = Site;
    m_uiplugin = m_pEmbeddedControlSite.Plugin as MySampleUIPlugin;
    m_root = m_uiplugin.STKRoot;
}
    [Visual Basic .NET] 
    Public Sub SetSite(Site As AGI.Ui.Plugins.IAgUiPluginEmbeddedControlSite) Implements AGI.Ui.Plugins.IAgUiPluginEmbeddedControl.SetSite
    m_pEmbeddedControlSite = Site
    m_uiplugin = m_pEmbeddedControlSite.Plugin
    m_root = m_uiplugin.STKRoot
End Sub
  5. Go to the design view of your CustomUserInterface class. Use the Toolbox to add a button. The default name, button1, will suffice.
  6. Double-click button1. This will add the event button1_click to the class, and jump you to that location. Populate it as follows:
    [C#] 
    private void button1_Click(object sender, EventArgs e)
{
    if (m_root.CurrentScenario == null)
    {
        MessageBox.Show("I know that no scenario is open.");
    }
    else
    {
        MessageBox.Show("I know your scenario's name is " + m_root.CurrentScenario.InstanceName);
    }
}
    [Visual Basic .NET] 
    Private Sub Button1_Click(sender As System.Object, e As System.EventArgs) Handles Button1.Click
    If (m_root.CurrentScenario Is Nothing) Then
        MessageBox.Show("I know that no scenario is open.")
    Else
        MessageBox.Show("I know that your scenario's name is " + m_root.CurrentScenario.InstanceName)
    End If
End Sub

At this point, you have a custom user control which can interact with the STK Object Root and the STK application. You do not yet have a way to call or load that custom user control.

Configure the Plugin to Open the User Interface

Go to your MySamplePlugin class. In this section, you will create a method to launch your custom interface, then modify Exec so that one of your commands calls that method.

  1. In your MySampleUIPlugin class, create a new method to launch the custom window and configure its display parameters:
    [C#] 
    public void OpenUserInterface()
{
    IAgUiPluginWindowSite windows = m_psite as IAgUiPluginWindowSite;

    if (windows == null)
    {
        MessageBox.Show("Host application is unable to open windows.");
    }
    else
    {
        IAgUiPluginWindowCreateParameters winParams = windows.CreateParameters();
        winParams.AllowMultiple = false;
        winParams.AssemblyPath = this.GetType().Assembly.Location;
        winParams.UserControlFullName = typeof(CustomUserInterface).FullName;
        winParams.Caption = "My First User Interface";
        winParams.DockStyle = AgEDockStyle.eDockStyleDockedBottom;
        winParams.Height = 200;
        object obj = windows.CreateNetToolWindowParam(this, winParams);
    }
}
    [Visual Basic .NET] 
    Public Sub OpenUserInterface()
    Dim windows As IAgUiPluginWindowSite = TryCast(m_pSite, IAgUiPluginWindowSite)

    If (windows Is Nothing) Then
        MessageBox.Show("Host application is unable to open windows.")
    Else
        Dim params As AgUiPluginWindowCreateParameters = windows.CreateParameters()
        params.AllowMultiple = False
        params.AssemblyPath = Me.[GetType]().Assembly.Location
        params.UserControlFullName = GetType(CustomUserInterface).FullName
        params.Caption = "Basic User Interface"
        params.DockStyle = AgEDockStyle.eDockStyleDockedBottom
        params.Height = 200
        Dim obj As Object = windows.CreateNetToolWindowParam(Me, params)
    End If
End Sub

    The IAgUiWindow reference returned by the CreateNetToolWindowParam function allows you to manipulate the newly created window after its creation; for instance, the window caption can be changed by setting the IAgUiWindow.Caption property.

  2. Modify the Exec method so that the "MyCompany.MySampleUIPlugin.MySecondCommand" command launches your custom user control.
    [C#] 
    else if (string.Compare(CommandName, "MyCompany.MySampleUIPlugin.MySecondCommand", true) == 0)
{
    OpenUserInterface();
}
    [Visual Basic .NET] 
    ElseIf (String.Compare(CommandName, "MyCompany.MySampleUIPlugin.MySecondCommand", True) = 0) Then
    OpenUserInterface();
End If
  3. Build your project, then start up STK. Create a new scenario, then click your your context menu item. Confirm that it launches your custom user control and that button1 gives you the appropriate message box.


<<Previous

Use the STK Object Model

Next>>

Add a Custom Config Page

STK Programming Interface 11.0.1