Introduction
A MicroStation DGN file is a container: it contains one or more DGN models. A DGN model is also a container: it contains DGN elements, reference attachments and other objects.
DgnLinks
This article provides a note about DgnLinks. A DgnLink is a form of hyperlink. It connects a MicroStation object, such as a DGN element, with an external object. That external object might be a file or web page. Here's a link to a folder, added to a DGN line element: MicroStation displays a small image (in this case, a folder icon) over an element that has a DgnLink …
As a programmer, you may like to know that the small image is called a view decorator.
A DgnLink promotes project collaboration and joins MicroStation with external data. MicroStation provides the opportunity to create Links to Files, Contents of Files, and Folders.
This article describes a C++ project that uses the MicroStationAPI to perform CRUD operations with DgnLinks attached to a DGN element. The app. can create a DgnLink of one of the following …
- A URL (e.g. https://www.bbc.co.uk)
- A file
- A folder
A number of other DgnLink types are defined but not used in this app.
Search for DGNLINK_TYPEKEY_URLLink in DgnPlatform/DgnLinkManager.h.
Once a link is added to a DGN element, MicroStation automatically shows a small icon (a view decorator). For example, here's how a folder link appears …
When you remove a DgnLink, that icon is removed automatically.
Create a DgnLink
This comment about creating a DgnLink is hidden in the MicroStationAPI help document …
The typical workflow in creating a new link node is:
- Call a method which allocates and returns a
DgnLinkTreeNode, which is owned by noDgnLinkTreeBranch - Possibly modify the returned
DgnLinkTreeNode- 3a. If desired, add the node to a parent
DgnLinkTreeBranchwhich assumes ownership
or
- 3b. Free the
DgnLinkTreeNode.TempObjectOwner<DgnLinkTreeNode>solves the problem of ensuring that in step 3b, the object is freed reliably and automatically. - 3c. Give the new node a name
- 3a. If desired, add the node to a parent
DgnLinkTreeNode Name
What MicroStationAPI help fails to mention is that the new leaf node must be given a name
using DgnLinkTreeNode::SetName(nodeName, checkForDuplicateNames).
The name should, preferably, be unique in the tree structure.
DgnLink Types
This demonstration can create one of three DgnLink types …
- A URL link
- A file link
- A folder link
For example, the tool settings changes when a Folder link is chosen …
Using MicroStation tools, you can create a DgnLink to many more kinds of objects. Those are not covered in this example app.
Commands
The DgnLink app includes a command table. Key a command into MicroStation's key-in window, to start an action. Available commands include …
| Command | Action | Comment |
|---|---|---|
| DGNLINK ADD LINK | Prompts user to pick a DGN element | Pops Tool Settings dialog |
| DGNLINK DELETE | Prompts user to pick a DGN element | Removes a DgnLink from an element |
| DGNLINK QUERY | Prompts user to pick a DGN element | Display link information |
| DGNLINK HELP ABOUT | Displays brief product information | |
| DGNLINK HELP DOCUMENT | Shows relevant content in your default web browser | |
| DGNLINK FILE EXIT | Exits the app |
To load the app, key-in mdl load DgnLink.
DgnLinkHelper
Most of the work concerning DgnLinks is performed by the DgnLinkHelper class, which lives in the LASolutions namespace.
Source code of the DgnLinkHelper class is supplied with the example project that you can download.
That, in turn, relies heavily on the DgnPlatform::DgnLinkManager class, delivered with the MicroStation CONNECT SDK.
Download the DgnLink Example
The DgnLink example code is provided as-is and without guarantee of
suitability for any particular purpose.
The source code is available in this MicroStation
C++ project.
Unpack the ZIP archive and copy the source code to your preferred folder.
A good place to copy it, if you're using MicroStation CONNECT,
would be ..\SDK\Examples\Miscellaneous.
You can then build it from the SDK command shell.
MicroStation and Application Development
MicroStation® is a computer-aided-design (CAD) tool produced by Bentley Systems. It is used by engineers, architects, and draughting technicians to create 3D models and 2D drawings.
MicroStation can be customised. Bentley Systems themselves have many applications for specialised markets that use MicroStation as a platform. Third-parties likewise may use MicroStation as a platform on which to develop their application software. Bentley Systems provide the MicroStation Software Development Kit (SDK) that software developers use to create their applications.
The CONNECT SDK has several libraries …
- the MicroStationAPI is a C++ library
- the DgnPlatformNet, MstnPlatformNet and some others are .NET libraries
This article concerns the MicroStationAPI. The MicroStationAPI contains thousands of functions that provide a C++ interface.
Acknowledgements
This article was stimulated by a post on the Be Communities MicroStation Programming Forum by YongAn Fu. It would not have progressed without additional help and comments by Robert Hook and Jan Šlegr: my thanks go to all of them.
Questions
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.
