Home > Essentials > DXCore adornments architecture

DXCore adornments architecture

October 6th, 2010

The Visual Studio 2010 IDE shell has been rewritten using the Windows Presentation Foundation (WPF), in other words, it has a completely different code editor based on the new WPF technology. Earlier versions of DXCore used GDI and Win32 API calls to paint the inside code editor before Visual Studio 2010 release, and would not work inside the new code editor. To bring painting support to Visual Studio 2010 and leave the support of previous Visual Studio versions, DXCore has been also rewritten using the new painting abstraction layer, which has a split code base for different platforms (WPF, GDI). This abstraction layer is called the “Adornments” architecture. This architecture allows having a single code base for all versions of Visual Studio which helps to maintain both graphic platforms at once and have independent painting, non-dependant on the version of IDE used.

There are two main objects of the DXCore adornments architecture used:

  1. TextViewAdornment (for TextView object) – is a base type of a code editor adornment object. An adornment is a graphical object drawn inside code editor. It can be a line, pixel, arrow, string, etc.
  2. TextDocumentAdornment (for TextDocument object). Once it is added to a particular text document, it will create adornments (descendants of the TextViewAdornment) for each currently available (and opened/closed as well) text views of this text document automatically.

So, the TextDocumentAdornment object creates TextViewAdornments for all text views, and the TextViewAdorment object draws the graphical object itself. Having said that, first, you need to create a TextDocumentAdornment descendant object. Once you create it, you have to override the public NewAdornment method, which will create TextViewAdornment objects that has the following signature:

protected abstract TextViewAdornment NewAdornment(string feature, IElementFrame frame);

In this method, you need to create a specific VisualObjectAdornment. This is only one descendant of the TextViewAdornment object. The NewAdornment method must return the newly created VisualObjectAdornment. The VisualObjectAdornment object allows you to paint inside VisualStudio code editor and represent a graphical object (i.e. adornment). To make this happen, you need to override the Render virtual method of this object with the following signature:

public virtual void Render(IDrawingSurface context, ElementFrameGeometry geometry)
{
}

All painting logic must be located in this overridden method. There are two parameters passed to this method which are used to paint on the code editor:

1. The “context” of type “IDrawingSurface”  – the code editor context on which painting happens. It has the following useful painting methods:

  • DrawArrow
  • DrawBezier
  • DrawBezierLine
  • DrawCircumference
  • DrawCorner
  • DrawEllipse
  • DrawImage
  • DrawLine
  • DrawObject
  • DrawPixel
  • DrawPolygon
  • DrawRectangle
  • DrawSelectionBar
  • DrawString
  • etc

All these methods draw the corresponding object of the same method name.

2. The “geometry” of type “ElementFrameGeometry”  – provides geometry information of an adornment (such as its size, bounds, location, start point, end point, etc). This information is calculated inside the TextDocumentAdornment constructors. All constructors accept one or several parameters which specify the coordinates of the text related adornment. So, it means that an adornment is bound to a text (source code) inside a code editor which coordinates are specified by the SourcePoint, SourceRange or DocPoint, DocRange objects. This ElementFrameGeometry is initialized from the “binding” parameter of the “IElementFrame” type of the NewAdornment method, which stores all adornment geometry information passed into TextDocumentAdornment constructors.

There are several CodeRush open source samples which use adornment architecture to paint on the code editor. You might want to take a look at one of the following plug-ins to learn more on how to paint on the code editor: CR_CommentHighlighter, CR_CommentPainter, CR_StructuralHighlighting, CR_XmlDocCommentPainter.

There are also several project item wizards made for simplifying the visual adornments creation process.

—–
Products: DXCore
Versions: 10.1 and up
VS IDEs: any
Updated: Oct/07/2010
ID: D019

Similar Posts: