Guides and Articles

Use this documentation when building your Tekla Structures apps

Direct Manipulation API for plugins

Updated: 7 Aug 2020

Intuitive user interface

The Direct Manipulation API (also known as DM API) allows developers to build plugins that are intuitive to use; what you see is what you get. With direct manipulation the plugin user can easily create and modify objects by simply dragging handles, without using the dialog boxes. This makes plugins significantly easier and faster to use.

Direct manipulation is an intuitive and easy editing of Tekla Structures objects.

Prototype available for testing

We have published the API prototype in Tekla Warehouse in order to get Tekla developer community feedback to improve the API and instructions before the official release.

We are looking forward to receiving your feedback

Feedback is always welcome. Let us know what do you think about the new Direct Manipulation API for plugins - what you liked or disliked. Post your feedback or questions on Tekla Open API discussion forum.

For plugins

The Direct Manipulation API for Tekla Structures plugins provides support for plugins created by implementing the PluginBase class of the Tekla Open API.

The API utilizes Tekla Open API data types for geometry (e.g. Point and LineSegment instead of Vector3 and Segment3) and provides a set of streamlined and well-defined and easy to use features. 

What is a plugin?

Plugins are, in a nutshell, small programs, that are run from inside Tekla Structures.

They are usually created as separate DLL files, that are placed in the environments/common/extensions/ directory, and launched using the Applications & components side pane in the main view of Tekla Structures.

Most plugins in Tekla Structures are simple in the sense that they are simply inherited from the Tekla.Structures.Plugins.PluginBase class and override two key methods: 

  1. DefineInput(), which returns a List<InputDefinition> type of object, and 
  2. Run(List<InputDefinition> input) which returns a boolean.

The first method defines the input of the plugin, and the second defines what the plugin does.

The Run() method is important in the sense that it is not only called once but every time the plugin input is modified.

There is a lot more to plugins than this, such as defining the Data object for communication purposes, using proper attributes like StructuresFieldAttribute, PluginAttribute and PluginUserInterfaceAttribute for important fields and classes, setting up a User Interface for the plugin using Tekla.Structures.Dialog.PluginFormBase or WPF, and utilizing the various methods provided by the Tekla Open API for whatever the plugin requires. Some of these aspects come to play in the examples below as we start using the DM API to create and manipulate plugins in a Tekla Structures model.

Two sub namespaces

The Direct Manipulation API is divided into sub namespaces called Core and Services to be used by plugin developers. 

Core

Core can be thought of as the main body of the Direct Manipulation API that is subject to very little change over time. Any code written against classes in this namespace should be compatible between different versions of the API over time.

Services

The another namespace, Services, is used for other aspects of the Direct Manipulation API that the feature can use, like tools and handles.

 

(There is also a third namespace, Internal, but that is reserved for changes in the Trimble internal implementation of the Direct Manipulation API and can be subject to radical change over time. No feature should be directly dependent on any class or method from this namespace.)

The 4 fundamental concepts of DM API for plugins

When learning to use the Direct Manipulation API, we recommend you follow the order listed below.
 

1. Creation feature

The most fundamental concept in the Direct Manipulation API is the concept of a feature.

Basically a feature is a class which is attached to some plugin by name and is then used by the Direct Manipulation Platform inside Tekla Structures to either create or manipulate the plugin.

Start learning Direct Manipulation API from this guide that focuses on the creation feature: Direct Manipulation API, part 1: Creation feature.

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.

The next part, Direct Manipulation API, part 2: Contextual Toolbar, 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 part.

3. Manipulation feature

Users are able to manipulate the components in the Tekla Structures model. The Direct Manipulation API, part 3: Manipulation feature will focus on implementing the manipulation.

4. Communication

The creation and manipulation feature must at times exchange information with the plugin. The last part, Direct Manipulation API, part 4: Communication, will focus on ways to convey information. 

Code snippets in text not fully runnable

Code snippets included in the above guides are very useful, but not always directly executable.

Consult the API reference (see the top navigation of this page) and general C# guidelines in cases where the text doesn't explain something fully.

Code examples available in GitHub

Take a look at these code examples that show how to use the new Direct Manipulation for plugins API prototype: https://github.com/TrimbleSolutionsCorporation/TSDirectManipulationPluginsExample.

 

What do you think about the Direct Manipulation API prototype?

Post your feedback or questions on Tekla Open API discussion forum.