Add a Custom Configuration Page

As you design your plugin, you may find that you want some way to set preferences for the plugin. In ODTK, you can set User Preferences using the Preferences dialog box under the Edit menu. You can add a page for your UI Plugin to this Preferences dialog box.

Add a new user control to the project

  1. In the Solution Explorer, right-click the project and select Add and then New Item.
  2. From the list of templates, select User Control.
  3. Give it a descriptive name, such as CustomConfigPage, and click Add.
  4. The newly created control will appear in design mode. Feel free to resize the page, add containers, buttons, text fields, etc. Add at least one textbox and name it �txtboxDefaultFilePath.� There is no need to add OK, Apply, Cancel, and Help, as these buttons are already on the Preferences panel, outside the borders of your page.
  5. The new class doesn�t have any of the convenient using directives. Add AGI.Ui.Plugins:
    [C#]
    using AGI.Ui.Plugins;
    [Visual Basic .NET]
    Imports AGI.Ui.Plugins
  6. Now that you have a Config Page, the UI Plugin needs to understand that this is its config page, and should be displayed when the user opens the ODTK Preferences dialog box. In the MySampleUIPlugin class, locate the IAgUiPlugin interface's OnDisplayConfigurationPage handler and modify it to match the following:
    [C#]
    public void OnDisplayConfigurationPage(IAgUiPluginConfigurationPageBuilder ConfigPageBuilder)
{
    ConfigPageBuilder.AddCustomUserControlPage(this, this.GetType().Assembly.Location, typeof(CustomConfigPage).FullName, "My UI Plugin Config Page");
}
    [Visual Basic .NET]
    Public Sub OnDisplayConfigurationPage(ConfigPageBuilder As AGI.Ui.Plugins.IAgUiPluginConfigurationPageBuilder) Implements AGI.Ui.Plugins.IAgUiPlugin.OnDisplayConfigurationPage
    ConfigPageBuilder.AddCustomUserControlPage(Me, Me.GetType().Assembly.Location, GetType(CustomConfigPage).FullName, "My UI Plugin Config Page")
End Sub

Build your project and then start up ODTK. Click the Edit menu and select Preferences. In the left-hand column, you should see your new item, "My UI Plugin Config Page." Click that item and you should see the config page you designed. At this point, you have a form that takes inputs but nothing that saves or uses those inputs. That will be covered in the following sections.

Implement the config page actions interface

Your plugin can launch a config page, but that config page can't communicate any changes back to the parent plugin. You have OK and Cancel buttons, but all they do is close the page. You also have Apply and Help buttons; they don't do anything either. The missing piece is the implementation of the IAgUiPluginConfigurationPageActions interface, which will allow the config page to communicate with the plugin class.

  1. In the CustomConfigPage class, locate the CustomConfigPage class definition. Add the IAgUiPluginConfigurationPageActions interface:
    [C#]
    public partial class CustomConfigPage : UserControl, IAgUiPluginConfigurationPageActions
    [Visual Basic .NET]
    Public Class CustomConfigPage
    Implements IAgUiPluginConfigurationPageActions
  2. For C#, right-click the interface (IAgUiPluginConfigurationPageActions). Select Implement Interface and then Implement Interface again. For VB, at the end of the Implements line, press the Enter key.

    This will implement the IAgUiPluginConfigurationPageActions interface, exposing its members:

    1. OnCreated is called when you load the page. This method is a good place to populate the fields on your page with initial values. In this example, a text box on the config page (txtboxDefaultFilePath) is given the initial value of filePath, a property of the MySampleUIPlugin class.
      [C#]
      public class MySampleUIPlugin: IAgUiPlugin, IAgUiPluginCommandTarget
{
    public string m_filePath = "Sample string";

    public string filePath
    {
        get { return m_filePath; }
        set { m_filePath = value; }
    }
    ...
}


public partial class CustomConfigPage : UserControl, IAgUiPluginConfigurationPageActions
{
    IAgUiPluginConfigurationPageSite m_site;
    MySampleUIPlugin m_plugin;
    ...

    public void OnCreated(IAgUiPluginConfigurationPageSite Site)
    {
        m_site = Site;
        m_plugin = m_site.Plugin as MySampleUIPlugin;
        txtboxDefaultFilePath.Text = m_plugin.filePath;
    }
    ...
}
      [Visual Basic .NET]
      Public Class MySampleUIPlugin
    Implements IAgUiPlugin, IAgUiPluginCommandTarget

    Dim m_filePath As String = "Sample string"

    Public Property filePath() As String
        Get
            Return m_filePath
        End Get
        Set(ByVal value As String)
            m_filePath = value
        End Set
    End Property
    
    ...
    
End Class


Public Class CustomConfigPage
    Implements IAgUiPluginConfigurationPageActions

    Dim m_site As IAgUiPluginConfigurationPageSite
    Dim m_plugin As MySampleUIPlugin

    ...

    Public Sub OnCreated(Site As AGI.Ui.Plugins.IAgUiPluginConfigurationPageSite) Implements AGI.Ui.Plugins.IAgUiPluginConfigurationPageActions.OnCreated
        m_site = Site
        m_plugin = m_site.Plugin
        txtBoxDefaultFilePath.Text = m_plugin.filePath
    End Sub
    
    ...
    
End Class
    2. OnCancel is called when you click Cancel, before ODTK closes the Preferences panel.
    3. OnApply is called when you click Apply or OK.
    4. OnOK is called when you click OK, after OnApply is called and before ODTK closes the Preferences panel.

Build your project and then start up ODTK. Click the Edit menu, select Preferences, and then click your config page. The initial value of your filePath string ("Sample string") should appear in the textbox. You can type in the box, but you haven't yet implemented OnOK or OnApply methods to take those edits and pass them back to the plugin filePath property. Do that now, and then rebuild and check your work in ODTK. User changes to the config page will only apply to the current ODTK session. To save user changes to the config page after ODTK is shut down, see the next section.

The Apply button is inactive by default. To enable the Apply button, you must call Site.SetModified(true). Add event handlers that listen for changes to any of the options on your config page, then use those handlers to set that modified flag to true. When you click OK, Apply, or Cancel, ODTK will set the flag back to false.

Also, the Help button is unavailable. To enable the Help button, implement the IAgUiPluginConfigurationPageActions2 interface. IAgUiPluginConfigurationPageActions2 extends IAgUiPluginConfigurationPageActions, meaning it contains all the methods of IAgUiPluginConfigurationPageActions, plus it has the additional method OnHelp. If the plugin implements IAgUiPluginConfigurationPageActions2, the Help button will be enabled. You may use the OnHelp method in any number of forms. For information about loading Microsoft chm (Compiled HTML) Help files, see Link to a .chm Help File.

Related Topics: