Plugin Basics

Plug-in Basics
 What is a Plugin?

Architecture of Plugin
Implementation

How to Create Detailing

Components

Cases of Model-Plugin Usage

User Meeting 2012 / Iiro Ojala

2
Objective
§ Understand the basics of Plug-ins
– Plug-in types
– How to define each type
– How to add your Plug-in to Tekla Structures
– How to debug a Plug-in
§ Understand Plug-in logical structure
– StructuresData
– Input
 Definition of a plugin
§ “A small piece of software that adds
a feature to a larger program or
makes a program work better”
- Merriam-Webster

§ Host application needs to specify an

API for the plugin

§ In Tekla Structures, plugins must

conform to certain Tekla interfaces

4
Plug-in Types
§ PluginBase
– Like a generic component (Stairs, ladders, truss, etc.)
– Input can be freely defined
§ Any number or type of objects
§ Any number of points
– Can be dependant or non dependant on input.
§ ConnectionBase
– Details (base plate, lifting hooks, etc.)
§ One part & one point
– Connections (clip angle, bracing, welded joints, etc.)
§ One or more secondary parts
 Characteristics of Tekla plugins
§ A custom entity in the model (component)

§ Has a dialog of its own

§ Can create new model objects (even other plugins)

§ Can be a connection, detail or generic component

6
 Benefits of using plugins
§ Plugins are an extremely powerful way to customize Tekla
Structures

§ Model API is robust, reliable and comprehensive

§ Tekla uses internally the same API to provide out-of-the-box

connections, details and components

7
 Accessing plugins
§ Component Catalog
§ Installed
§ Downloaded

8
 Issues to consider before starting
§ Unlike Custom Components, plugins need programming
skills, preferably C#

§ Might be overkill for simplest needs

– Instead record macros, use custom components

§ Need good understanding of Tekla modeling system

– Programming interfaces are very similar to Tekla model object user
interfaces

9
 What is a Plugin?

Architecture of Plugin
Implementation

How to Create Detailing

Components

Cases of Model-Plugin Usage

User Meeting 2012 / Iiro Ojala

10
 Tekla Structures Plugin Architecture
§ Inserting plugin into a model
– Input sequence, user interface attributes

§ Running a plugin

§ Modifying a plugin
– Via user interface or by dependent input object

§ What is not allowed

– Changing existing objects, changing input data

11
 Inserting new plugin into model
§ New Plugin is started
– Constructor method runs
– Input prompted from user
§ Applied values taken from dialog
§ Plugin Run() when input complete
– Both the StructuresData and the Input are stored to the Tekla model database

PLUGIN
User UI (Dialog) .
StructuresData

Input Objects Input Objects StructuresData

12
 User Interface Data Changed
§ User modifies Plugin UI attributes
– New values are read from dialog
– Dialog data passed to Run code
– Plugin Run() executes with new data

PLUGIN
User UI (Dialog) .
StructuresData

Input Objects Input Objects StructuresData

13
 Plugin automatically re-runs, input was changed

§ Input object is modified, moved or otherwise changed

– Plugin Run() executes with the changed input object(s)
– Dialog is not shown, new parameters are not read
– E.g. Column size changed, => Cap plate gets bigger...

PLUGIN
User UI (Dialog) .
StructuresData

Input Objects Input Objects StructuresData

14
 Plugin Updates when needed automatically
§ Plugin works like any system connection: If input objects are
modified or user clicks ’modify’ on the dialog, it re-executes
§ In general, modify works without any extra work
§ Tekla system executes Run() method with modified
parameters (DefineInput() is never re-executed)
§ Plugin is executed just as it was added to the model
– System automatically takes care of modifying existing parts instead
of creating new ones

15
 Input and Data are one-way
§ Plugin Run() cannot communicate via the UI
§ Plugin cannot change the content of the StructuresData
stored in the model (e.g. make default values explicit)
§ Plugin is not allowed to modify input objects
– Can lead to an infinite loop

PLUGIN
User UI (Dialog) .
StructuresData

Input Objects Input Objects StructuresData

16
 Default values and storage
§ Example
– If attribute P1 in the dialog is left blank (default)
– Then default hard coded value is used
> If(IsDefaultValue(P1))
> P1 = 10;

– The assigned default value of P1 is not stored into StructuresData

PLUGIN
User UI (Dialog) .
StructuresData

Input Objects Input Objects StructuresData

17
 Plugin Architecture Summary
§ Two separate sources of input
1. Input objects and points from user selection
2. Dialog Attributes (UI)
– Both are one-way only
– Stored to plugin instance in model database
§ DefineInput() asks user to pick points or objects to interact
with from model
§ Run() code
– does work of plugin
– cannot ask for user input

18
 What is a Plugin?

Architecture of Plugin
Implementation

How to Create Detailing

Components

Cases of Model-Plugin Usage

User Meeting 2012 / Iiro Ojala

19
 Objectives
§ Understand the basics of plugin implementation
– Plugin types
– How to define each type

§ Understand Plugin logical structure

– StructuresData
– Input

20
 Tekla Structures Plugin Fundamentals
§ All plugins need to inherit from Tekla provided base class

§ Base classes are deployed in Tekla.Structures.Plugins.dll

– Comes with Tekla Structures standard installation

§ Two different types of plugins; two different ways of

implementing input sequences

21
Available Plugin Types

PluginBase ConnectionBase
§ Like a generic component § Connections (clip angle,
(Stairs, ladders, truss, etc.) bracing, welded joints, etc.)
§ Input can be freely defined – Main part and one or more
– Any number or type of secondary parts
objects § Details (base plate, lifting
– Any number of points hooks, etc.)
§ Can be dependent or non- – Main part and one point
dependent on input

User Meeting 2012 / Iiro Ojala 22

 Basic requirements of PluginBase
§ StructuresData
– Defines the data that can be passed from the UI
§ Constructor
– Initializes the Plug-in
– Takes the currently applied StructuresData
§ Class attributes
– Define the name and UI
§ Base class has two methods to implement
– DefineInput()
§ Defines the input the Plug-in requires
– Run()
§ Executes after input has been received
§ Contains plugin’s ”business logic”

23
 Plugin required attribute definitions
[Plugin(“PluginName1")]
- The name in the catalog - Must be unique

[PluginUserInterface(“PluginName1.MainF
orm”)]
- Points to the Form/INP definition of the UI

24
 User Meeting 2012 / Iiro Ojala
25
 Basic requirements of ConnectionBase
§ StructuresData
– Defines the data that can be passed from the UI
§ Constructor
– Initializes the connection
– Takes the currently applied StructuresData
§ Class attributes
– Define the name, UI, number of secondaries, collision type, auto up direction
§ Base class has one method to implement
– Run()
§ Executes after input has been received
§ Contains plugin’s ”business logic”
§ Input is defined by plugin attributes, and it is managed by Tekla
Structures

26
 Connection required attribute definitions
[Plugin("ConnectionName1")]
- The name in the catalog - Must be unique
[PluginUserInterface(“ConnectionName1.MainForm”)]
- Points to the Form/INP definition of the UI
[SecondaryType(ConnectionBase.SecondaryType)]
- The number of secondaries required
- Setting number of secondaries to zero makes it a detail
[AutoDirectionType(AutoDirectionTypeEnum)]
- Auto up direction type
[PositionType(PositionTypeEnum)]
- Connection origin type*

User Meeting 2012 / Iiro Ojala

27
 User Meeting 2012 / Iiro Ojala
28
 Basic
Requirements PluginBase ConnectionBase
Defines the data that can be
StructuresData
passed from the UI
Initializes & takes the currently
Constructor
applied StructuresData
Define the name, UI,
number of
Class Attributes Define the name & UI secondaries, collision
type, auto up
direction
Executes after input has been received and
Run()
contains plugin’s ”business logic”

Defines the input the

DefineInput() –
Plugin requires
User Meeting 2012 / Iiro Ojala
29
Plug-in dependency
§ Plug-ins cannot modify their inputs.
§ Plug-ins dependency can be set with the attribute
InputObjectDependency.
– Dependent: updated when input changes.
– Non-Dependent: doesn’t update when input changes.
– Geometrically-Dependent: Plug-in updates when the input part
geometry changes. This Plug-in cannot create any boolean objects to
the input part, since it would cause and endless loop.
– Non-Dependant-Modifiable*Next: No dependency on input but the
instance is modifiable in the model. The created objects have a
relation to the plug-in. The plug-in dialog can be opened from the
created objects.
Running and Debugging a Plug-in
§ Preparation
– Copy the project dll and pdb file to the Plug-ins folder
or a sub folder
– Run Tekla Structures
– Set breakpoints in the code
§ Debugging
– Debug > Attach to process
– Run or modify the Plug-in
– Debug > Stop debugging
§ Changes
– On the fly code changes are not possible
– A new dll requires a restart of Tekla Structures
Plug-in User Interface
§ Forms
– Includes save & load, apply, get, etc. functionality
– Supports selecting from catalogs (bolt, profile, etc.)
– Support for distance (units), double, int, and string only
– More powerful than INP.
§ INP
– Same format used for custom components & system components
– Includes save & load, apply, get, etc. functionality
– Supports selecting from catalogs (bolt, profile, etc.)
– Supports all data types and type checking
– See the online help for the details of INP files
Notes
§ Visual Studio
– Plug-in projects are a ‘Class Library’ (e.g. dll)
§ Plug-in dlls
– More than one Plug-in can be created in the same dll under the same
project
§ Avoid message boxes and pop-up dialogs
– If the input is modified, any dialogs and message boxes will be shown
again for each Plug-in instance
§ A Plug-in sets the workplane automatically to local coordinate
system when Run is called.
– Local coordinate system: first picked part coordinate system, or coordinate
system with origin in the first picked point.
Notes
§ Do not use Model.CommitChanges() in a Plug-in
– Executed by Tekla Structures when Run() completes
– Would set a ‘strange’ undo point
– Can ruin the keep ID processing
§ Consistent IDs under modify
– Tekla Structures keeps IDs the same (where possible) during modify just
like system components
§ Trouble shooting
– Information about problems
loading Plug-ins or problems with
the dialog can be found in the
session history log
Limitations and known problems
§ Component Types
§ Seams and Details can be created with ConnectionBase while
CustomPartBase has currently limitation that it always requires two
input points
§ Both can be done as PluginBase
§ AutoDefault & AutoConnection
– Plug-in connections cannot be used in AutoDefault or
AutoConnection prior to 16.1.
– AutoDefault works in Forms starting in 17.0
 Implementation summary
§ Dialog attributes defined in code (StructuresData)
§ User input is stored to model with plugin
§ Two base classes available
– PluginBase
§ Input explicitly defined in code
– ConnectionBase
§ Fixed input like connection or detail
§ Detail or Connection Type is set in header attributes for class
§ Run() code contains main logic, but can not ask for user
input

37
 Case: Layout Point in Depth
38
 Layout Point and Layout Line
§ Included in Tekla Structures installation
§ Purpose is to help modeling field layout inside Tekla model
§ Implemented as Plugin
§ Allows user to create layout points in the Tekla model
§ Layout points can in turn be used as input to Layout Lines

39
 Open Applications & components
§ Plugins
§ LayoutPoint and
LayoutLine

40
 Layout Point

41
 Layout Point

42
 Layout Point

43
 Layout Point

User Meeting 2012 / Iiro Ojala

44
 Layout Point

45
 Layout Point

46
 Layout Point

47
 Layout Point

48
 Layout Point

User Meeting 2012 / Iiro Ojala

49
 Layout Point

50
 Layout Point – Case summary
§ Plugin input definition
– DefineInput() in PluginBase and attributes in ConnectionBase

§ Plugin dialog attributes

– [StructuresField(”param”)]

§ Executing and modifying a plugin

– Run()
– Input definitions
– Dialog parameters

51
 Layout Point – Case summary
§ Utilizes Tekla Plugins and Tekla Model APIs
§ Only a few hundred lines of code
§ Very simple yet powerful plugin
§ Fits a specific need

52
Plugin Basics

Non-dependent plug-ins
Objective
§ Understand the basics of Non-dependent plug-ins
– Definition
– How to execute
§ Understand where to use of Non-dependent plug-ins
§ Difference between Applications and Plug-ins.
How non-dependent plug-ins work?
§ Plug-in dialog is opened from
component catalog and
executed from dialog
§ Values can be applied from
dialog normally
§ Plug-in instance is deleted
after execution
§ Plug-in dialog cannot be
opened from created objects
§ Created objects are saved to
database as native objects
Where to use non-dependent plug-ins?
§ Can be used in tools where a lot of model information needs to
be fetched or set
§ Data is transferred in-process through API, remoting not used
– 20x faster execution when compared to applications
§ Typically used in
– import and export functionality
– Status-checking tools
§ Also useful in tools where model information needs to be
consistent
– Tekla Structures UI is “frozen” during plug-in execution
– External applications cannot modify data during execution
 Setup
§ Virtually the same as normal model plug-in
§ Has Run and define input override
§ Receives data the same way from user interface

57 Tekla Open API: Modeling Tools & Plug-Ins

Setup
§ Input not mandatory
– Empty list returned from DefineInput()

§ Forms and inp can be used for dialog definition

– Modify()-method executes plug-in if Forms is used
 Example Non-Dependent Plug-in
59 Tekla Open API: Modeling Tools & Plug-Ins
 Use Cases
§ Applicator tool
§ Run tasks very quickly

60 Tekla Open API: Modeling Tools & Plug-Ins

 Define Input

61 Tekla Open API: Modeling Tools & Plug-Ins

 Run

62 Tekla Open API: Modeling Tools & Plug-Ins

 Data Storage Class

63 Tekla Open API: Modeling Tools & Plug-Ins

 Insert Existing Detail
§ Use Detail, Custom Part, Seam, Connection, and
Component classes to insert existing custom
components, system components, and plug-ins
§ Insert new instance of your plug-ins or Tekla plug-ins

64 Tekla Open API: Modeling Tools & Plug-Ins

 Drawing Plugins Types
/// <summary>
/// The plug-in is never updated.
/// Plug-ins are executed from the plug-in dialog instead of the component catalog.
/// The created objects do not have any relation to the plug-in anymore.
/// The plug-in dialog cannot be opened from the created objects.
/// </summary>
CREATE_ONLY = 0,

/// <summary>
/// The plug-in is updated when the input is a point and the point is moved or when the input is an object and the object
/// changes. The plug-in is executed when the input is an object and its properties are changed in the drawing editor.
/// This mode is the default which is used if the update mode is not defined in the plug-in source.
/// </summary>
INPUT_CHANGED = 1,

/// <summary>
/// The plug-in is updated also when a drawing is opened.
/// The plug-in is executed when the input is changed or during drawing opening.
/// </summary>
DRAWING_OPENED = 2

65 [Date] [Subject / Author, edit by clicking Insert > Header & Footer]
Tekla Open API

Dialog basics
§ Tekla Open API: Plug-ins & Dialogs
Objective
§ Understand the basics of Dialogs
– Attribute binding.
– Use of Distance/DistanceList
§ Understand the use of UIControls
– How the controls work.
§ Difference between Applications and Plug-ins.
§ Difference between INP and Forms dialogs.

Tekla Open API: Plug-ins & Dialogs

Dialog Types
§ FormBase class provides localization, unit conversion and
data storage among other things. Abstract class: should not
be directly inherited
§ ApplicationFormBase: Defines forms for Applications.
§ PluginFormBase: Defines forms for Plug-ins.
§ Inheriting from this Forms enables structuresExtender which
adds extra properties to the controls.

Tekla Open API: Plug-ins & Dialogs

Attribute Binding
§ Attributes: pass data from the Form
into the Plug-in.
§ StructuresData: defines all the data
(Attributes) that can be pass from the
UI.
§ Check boxes: filter attributes.

§ BindPropertyName: bind to other

property than the default one of the
control (e.g: combobox SelectedIndex)

Tekla Open API: Plug-ins & Dialogs

INP notes
§ General tab in Connections
§ Access to Component Catalog

Tekla Open API: Plug-ins & Dialogs

Avoid deadlocks in Plug-ins
§ Picker: must be launched in a separate thread when called in
the Run or in the Form.
§ MessageBox: stops the Plug-in until clicked. In Form plugins
must be launched in a separate thread when called in the
Run.

Tekla Open API: Plug-ins & Dialogs

ApplicationFormBase vs PluginFormBase
§ ApplicationFormBase implements less methods: no
need for Modify, Get,…
§ Applications have to call base.InitializeForm() to
initialize the data storage.

Tekla Open API: Plug-ins & Dialogs

UIControls
§ Contains custom controls to ease the implementation of
dialogs.
§ Can be found in Tekla.Structures.Dialog.UIControls

Tekla Open API: Plug-ins & Dialogs

Adding UIControls to the Toolbox

Tekla Open API: Plug-ins & Dialogs

UIControls: Catalogs
§ Access to catalogs: Bolt, Material, Mesh, Profile and
Reinforcement.

Tekla Open API: Plug-ins & Dialogs

UIControls: SaveLoad

§ SaveLoad: represents a Save-Load-Save As group of

controls including the functionality.
§ No need to set up, just drag and drop into the Form.
§ Only controls bound to an attribute and user attributes
(not bound to controls) will be saved.
§ The attribute file is saved in the <model>\attributes
folder.
§ The file extension is <namespace>.<FormName>.xml.
E.g. standard.Splice.Attributes.xml

Tekla Open API: Plug-ins & Dialogs

Notes
§ Beware of typos in the
Attributes names, they have
to be the same in the control
and in the StructuresData.
§ Attribute name cannot be
more than 18 characters
§ String Attributes value
cannot be more than 79
characters.

Tekla Open API: Plug-ins & Dialogs

 SaveLoad and DataGrid

§ SaveLoad + DataGrid: not direct support. Needs to use User

Attributes.
§ You can find more information in the forum:
– https://extranet.tekla.com/FORUM/default.aspx?g=posts&t=4193
– https://extranet.tekla.com/FORUM/default.aspx?g=posts&m=17938#post1793

Tekla Open API: Plug-ins & Dialogs

Tekla Open API: Plug-ins & Dialogs
Tekla Open API: Plug-ins & Dialogs
DistanceList
§ Control properties set
as DistanceList.
§ StructuresData
Attribute set as string.
§ Parse the Attribute
into a DistanceList.
§ Loop through the
values in the distance
list when using them.

Tekla Open API: Plug-ins & Dialogs

 Thank You
82 [Date] [Subject / Author, edit by clicking Insert > Header & Footer]