Direct Manipulation API for plugins

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.

Do you have questions or feedback?

Feedback is always welcome. Let us know what do you think about the Direct Manipulation API for plugins - what you liked or disliked. Post your feedback or questions on the forum dedicated to direct manipulation plugin API.

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, 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 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, and 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 into 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

The 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 with different versions of the API over time.

Services

The other 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 that 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 the 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 can 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 are 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 on GitHub

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