Guides and Articles

Use this documentation when building your Tekla Structures apps

Model plug-in dialog design with Windows Forms

Updated: 13 May 2019

PluginFormBase class provides connectivity to Tekla Structures for plug-ins.

Forms that inherit from PluginFormBase are automatically added to the Applications & components catalog if the .dll file is found under nt\bin\plugins folder.

The dialog stays on top of the Tekla Structures main window and closes when Tekla Structures closes.

PluginFormBase adds the following support:

  • .NET dialogs for Tekla Structures plug-ins 

  • Data connection to Tekla Structures plug-ins  

  • Tekla Structures data types and conversions

  • Multiple language support

  • Default storing of values

Tip:

If you are unfamiliar with Windows Forms, you may want to take a look at Getting Started with Windows Forms guide by Microsoft.

Class definition

The plug-in form has to inherit from PluginFormBase:

using Tekla.Structures.Dialog; 

public class MainForm : PluginFormBase 
{ 
    ...

Constructor

Every plug-in needs a constructor. The constructor sets the StructuresData from the interface to be in use of the plug-in. 


The constructor must always be defined as public.

public BeamPlugin(StructuresData data)
{
    TSM.Model M = new TSM.Model();
    Data = data;
}

 

Naming the plug-in

The plug-in name will appear in the Applications & components catalog, and it has to be unique. You cannot have two plug-ins with the same name.

The user interface for the plug-in is defined in a metadata attribute of the plug-in class, PluginUserInterface.

using Tekla.Structures.Plugins; 
 
[Plugin("DialogDemo")]
[PluginUserInterface(typeof(DialogDemo.MainForm))] 
public class MainPlugin : PluginFormBase  
{  
    ...

If the plug-in is inherited from ConnectionBase, the dialog class name must be the same as plug-in name:

[Plugin("SpliceConnection")] 
[PluginUserInterface("SpliceConnection")]

However, plug-ins inherited from PluginBase or DrawingPluginBase do not have this limitation. Their dialog class name does not have to be the same as plug-in name:

[Plugin("FloorToolPlugin")]
[PluginUserInterface("FloorTool.FloorToolForm")]

In both cases interface definition must refer to actual dialog class. Connections class has to be outside namespace and class name must be the same as plug-in name.

Connection dialog class:

public partial class SpliceConnection : PluginFormBase 
{ 
    ...

Plug-in and drawing plug-in dialog class:

namespace FloorTool 
{    
    public partial class FloorToolForm :  PluginFormBase
    {  
        ... 

Note that PluginFormBase dialog class name cannot end with "_01" or similar.

Data connections

Plug-in dialogs save their data to Tekla Structures. The values are then passed to the corresponding plug-in when it runs.

To use a value entered in a dialog control in a plug-in, you need to set the Tekla Structures specific attributes for each control. They can be found for each control in the Microsoft Visual Studio Design view, on the Properties tab, under Tekla Structures (see image below).

Tekla structures Open API model plug-in design windows forms

The data is passed to the plug-in using a class defined by the developer of the plug-in. Its instance must be the only parameter for the plug-in's constructor and it must consist of public fields that have the Tekla.Structures.Plugins.StructuresField attribute. The attribute's parameter is where the binding is done to the dialog field. It must be the same as the name part of the AttributeName property for the field.

using Tekla.Structures.Plugins; 
 
public class StructuresData  
{   
    [StructuresField("length")]
    public double length; 
} 
 
[Plugin("DialogDemo")] 
[PluginUserInterface(typeof(DialogDemo.MainForm))] 
public class DemoPlugin : PluginBase  
{  
    private StructuresData _data;  
    public DialogDemo(StructuresData dialogData)  
    {   
        _data = dialogData;  
    }    
    public override bool Run(List<InputDefinition> input)  
    {   
    try   
        {    
            double Length = _data.length;   
        }   
        catch (Exception e)   
        {    
             […]   
        }   
        return true;   
    }
}

In the Run method (for example) of the plug-in, you can now read the passed dialog values from the _data variable.

Passing data

Plug-ins contain Apply, Modify, Get and Enable/Disable methods for passing data from the dialog to the plug-in. These methods imitate functionality seen in Tekla Structures buttons.

  • Apply method stores/sets new default values but doesn't modify the selected parts

  • Modify modifies the selected parts as was defined in the plug-ins run method

  • The values are saved as with Apply if the dialog is closed with the OK button

AttributeTypeName

AttributeTypeName is the name of the Tekla.Structures.Datatype type for the control's contents. This setting affects the type of the variable (integer, double or string) that you get to the plug-in, as well as automatic formatting and localization of the field. Plug-ins will always receive the data as Tekla Structures standard units, like millimeters for Distance. The following datatypes and attribute type data mappings are used:

DataType            Plug-in attribute field type
Boolean   Integer
Distance   Double
DistanceList   String
Double   Double
Integer   Integer
String   String (max. 80 chars)

 

For example, the Distance type formats the user input like in Tekla Structures and adds the corresponding unit abbreviation according to the current settings. If, for example, feet-inches units are active and the user types 14 in the field, the field will automatically change to 1'-2". All the datatypes are defined in the Tekla.Structures.Datatype namespace in Tekla.Structures.Datatype.dll.

GetAttributeValue and SetAttributeValue

If you use a control property (that is bound to an attribute) directly from code, get and set the property value using GetAttributeValue and SetAttributeValue. Updating the property directly does NOT automatically update the bound attribute which might then be obsolete.

double example = GetAttributeValue<double>(ControlWithAttribute); 
example += 5000.0; 
SetAttributeValue(ControlWithAttribute, example);

 

BindPropertyName

The BindPropertyName sets to which property of the control the attribute binds to. Most controls have default properties where the attributes are bound to. For example TextBox controls have by default Text property bound to attribute and ComboBox controls have SelectedIndex property bound to attribute. Different attribute types (AttributeTypeName) limit to which control properties attributes are able to bind to.

IsFilter

According to the Tekla Structures dialog practice you should create an enable/disable checkbox for each control. If the field's checkbox is unchecked, the value for that attribute will be left unchanged when the user modifies the objects created with the plug-in.

The way to bind the checkbox to the corresponding control is to set the AttributeName property to the same value as the input control's AttributeName. Additionally, you must set the IsFilter property to true. The AttributeTypeName should be left empty (see image below).

Tekla structures Open API model plug-in design windows forms

Default values

Default values for the fields in the dialog can be set with Tekla Structures dialogs. Create a standard file and place it in the environment folder. Note that Tekla Open API dialogs use XML format for their save files instead of the old native format.

Open your dialog from Tekla Structures, set the desired default values for the fields, set the file name to standard, and click Save. The file will be stored under the currently open model's folder, in the attributes subfolder. The name is by default <AssemblyName>.<FormName>.xml. Copy the file from there to the Tekla Structures environment structure.