Direct Manipulation API, part 2: Contextual toolbar

The contextual toolbar is a small helper toolbar that appears on screen every time an object in Tekla Structures has been selected.

This Direct Manipulation API guide will focus on the various aspects of defining the controls for a feature in the contextual toolbar. However, since some controls rely on information flow from and to the plugin, we will leave that discussion for later in the Communication guide.

There are two ways to create a Contextual Toolbar. The first way will be discussed here, the second will be left for later.

Creating a Contextual Toolbar

To create a Contextual Toolbar for a feature the optional value useFeatureContextualToolBar in the constructor of the PluginCreationFeatureBase needs to be set to true and the method DefineFeatureContextualToolbar(IToolbar toolbar) should be overridden. The trick here is to use the parameter toolbar in the overriding.

The interface Tekla.Structures.Plugins.DirectManipulation.Core.IToolbar defines a group of factory methods to create various controls for different uses. These are:

• ButtonControl CreateButton(). Creates a button control. The optional parameters allow the user to define a text and image element within the control.
• CheckBoxControl CreateCheckBox(). Creates a check box control. The optional parameters allow the user to define a text and image element associated with the control.
• DropDownListControl CreateDropDown(). Creates a drop-down list control. We will shortly go over some of the idiosyncrasies related to these controls with more information.
• LabelControl CreateLabel(). Creates a label control. The optional parameters allow the user to define a text and image element within the control.
• RadioButtonControl CreateRadioButton(). Creates a radio button control. The optional parameters allow the user to define a text and image element associated with the control along with a related control group.
• TextBoxControl CreateTextBox(). Creates a text box control. The optional parameters allow the user to define a text and image element within the control.
• ValueBoxControl CreateValueTextBox(). Creates a text box control for values of type double. The optional parameters allow the user to define the default starting value along with the representation type of the value. This can be either Distance or Angle.
• Remove(): Removes the control from the Contextual Toolbar.

A control is always added to the toolbar when calling one of these factory methods.

User interface controls

Let us now go through some of these controls. A reader who is mostly familiar with these kinds of UI controls can mostly skip this part.

• ButtonControl: As the name suggests, the control is a basic button, that can have text and an image as internal elements. The most useful aspect of the button control is the Clicked event, which gets invoked when the button is clicked.
• LabelControl:A simple label control, that can contain text, an image, or both. There are no attached events to this control.
• CheckBoxControl: A small check box that can have its own label or image. This control supports a StateChanged event, that gets invoked any time the state of the box changes.
• DropDownListControl: This control is used to open a list of items to show various options to the user. There is an Add() method for adding new items as well as a StateChanges event that gets invoked any time the user changes the selection in the list.
• RadioButtonControl: This control is used in a situation, where there are multiple excluding options to choose from. The control is usually attached to a group of other same-typed controls, where one of them is active and the rest are inactive. Access to the current group of the control can be obtained through the Group property of this control. To get or set the buttons checked state the IsChecked property can be used. A text and image element can be associated with the control. The RadioButtonControl also supports the StateChanged event.IsChecked
• TextBoxControl: A simple text box that can contain any text content. This control can be associated with a title text using the property Title. The title text will appear as a non-modifiable stylized text on the left side of the box. This can be used to give context to the value. The TextBoxControl supports StateChanged, GotKeyboardFocus, and LostKeyboardFocus events.
• ValueBoxControl: A text box control, that is used to input and output values of type double. This control can also be associated with a title text using the property Title. The value of the control can be gotten and set through the Value property. The ValueBoxControl also supports StateChanged, GotKeyboardFocus, and LostKeyboardFocus events.

All of these controls are inherited from a single base class called Tekla.Structures.Plugins.DirectManipulation.Core.ControlBase. The base class provides access to shared properties of the controls, such as Tooltip, Tag, Image, and Text.

The visibility of the control can also be set using the Visible property. It is also possible to add custom properties in the control as an object of type Dictionary<object, object> using the CustomProperties property.

Setting up Contextual Toolbar in a feature

Now that we are familiar with all the different sorts of controls available to us, let us look at setting up the contextual toolbar in a feature.

It is also possible to have backing fields for all controls in the feature class and simply turn off their visibility when they should not be shown.

Continuing with the examples from the Direct Manipulation API, part 1: Creation feature, instead of starting the picking session at the initialization phase, let us have the session start when a button is clicked on the contextual toolbar.

Code example 4

namespace MyPluginFeatures
{
    // All prior using directives.
    using MyPluginNamespace;
    public sealed class MyPluginCreationFeature : PluginCreationFeatureBase
    {
        // All prior private fields.
        private ButtonControl button;  // Backing field for the button.
        // All prior Constructor(s) and Properties
        protected override void DefineFeatureContextualToolbar(IToolbar toolbar)
        {
            this.button = toolbar.CreateButton("Start picking!");
            button.Tooltip = "Helpful tooltips for everyone!";
            button.Clicked += (sender, eventArgs) =>
            {
                this.pickingTool?.StartPickingSession("Pick two points.");
            };
        }
        // Rest of the code.
    }
}

This is now somewhat more useful since the feature is now capable of starting multiple picking sessions instead of having to reinitialize the whole feature to start again.