MicroStation .NET: Highlight an Element

DgnPlatformNet

Introduction

This article is for C# developers who want to write an application for MicroStation CONNECT. It describes a way to highlight or emphasise an element in a DGN model view. This is not a complete application: rather, it describes what might otherwise be a non-intuitive approach to solve a problem.

For a practical demonstration of the technique described here, see the article about Scanning for Tags.

Be Communities

If you want to ask questions about C# development for MicroStation CONNECT, post your question to the MicroStation Programming Forum.

Highlighting an Element

Suppose that your application (or AddIn, in Bentley Systems terminology) is interactive. Your app. works with MicroStation DGN elements in some way. When choosing, modifying or otherwise working with an element you want to indicate to the user which element is of interest.

One way to show that interest is to highlight an element. Highlight means to display the element in a contrasting colour. The colour contrast draws the eye to that element and helps it to stand out among other elements.

ElementAgenda

An ElementAgenda or, to give you its full name, Bentley.DgnPlatformNET.ElementAgenda is a collection of Elements. An ElementAgenda is most commonly found in code that implements a primitive command class. It's used when collecting elements by picking (locating), or in multi-element operations such as selection sets or fence contents.

However, as you can read in the DgnPlatformNet help documentation: Typically, ElementAgendas are created by MicroStation from sources that work on multiple elements such as the SelectionSet and Fences. However, as a general-purpose vector of Elements, ElementAgendas can be created by applications for other purposes as well. ElementAgendas are themselves reference counted.

In this example we adopt that suggestion: use an ElementAgenda to store a list of Elements picked by the user.

ElementAgendaDisplayable

In response to a post on the Be Communities Programming Forum, Bentley Systems' staffer Robert Hook suggested we look at undocumented class ElementAgendaDisplayable.

Class ElementAgendaDisplayable inherits from ElementAgenda. Amongst other functionality, it adds methods to modify an element's highlight state …

ElementAgendaDisplayable.Hilite()
ElementAgendaDisplayable.ClearHilite()

ElementHighlighter class

Here's a complete class for managing element highlighting. I should restate that this class is intended for use outside a primitive command class (such classes manage their own agendæ).

Rather than copy the code below, you can download a complete Visual Studio project. That project is TagScanning. It provides a link to download the project including source code.

using System;
using System.Collections.Generic;
using System.Text;
using BD = Bentley.DgnPlatformNET;
using Bentley.DgnPlatformNET.Elements;

namespace ElementHighlighterExample
{   /// ElementHighlighter exists to manage an element agenda.
    class ElementHighlighter : IDisposable
    {
        /// An element agenda that stores the element whose ID is selected once we've scanned
        /// the active DGN model for tagged elements.
        /// We use this agenda to hilight elements selected in the ListView control.
        BD.ElementAgendaDisplayable elementAgenda_;

        public enum HighlightCriteria
        {
            SingleHighlight,
            MultipleHighlight,
        };
        private HighlightCriteria highlightCriteria_;

        public ElementHighlighter()
        {
            elementAgenda_ = new BD.ElementAgendaDisplayable();
            highlightCriteria_ = HighlightCriteria.SingleHighlight;
        }
        /// Get or set the highlight criteria.
        /// You can select a single element or multiple elements for highlighting.
        public HighlightCriteria Criteria { get { return highlightCriteria_; }  set { highlightCriteria_ = value; }}

        public void Hilite() { elementAgenda_.Hilite(); }
        public void ClearHilite() { elementAgenda_.ClearHilite(); }
        public void Highlight(bool on)
        {
            if (on)
                elementAgenda_.Hilite();
            else
                elementAgenda_.ClearHilite();
        }
        public void Empty()
        {
            elementAgenda_.ClearHilite();
            elementAgenda_.Empty(true);
        }
        public void Dispose()
        {
            Dispose(true);
            GC.SuppressFinalize(this);
        }
        /// Ensure that we clear the currently-highlighted element when we finish with this object.
        protected virtual void Dispose(bool disposing)
        {
            if (disposing)
            {
                if (elementAgenda_ != null)
                {
                    Empty();
                    elementAgenda_.Dispose();
                }
            }
        }
        /// Add an element to our agenda.
        public void AddElement(BD.Elements.Element el)
        {
            if (HighlightCriteria.SingleHighlight == highlightCriteria_)
            {
                elementAgenda_.Empty(true);
            }

            elementAgenda_.Insert(el, true);
        }
        /// Remove an element from our agenda so that it is no longer highlighted.
        public void RemoveElement(BD.Elements.Element el)
        {
            el.Invalidate();
            elementAgenda_.DropInvalidEntries();
        }
    }
}

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.