The DOM paints itself by using an instance of the NPaintVisitor class. The NPaintVisitor class derives from the NDisplayVisitor class, and inherits the transform and clip management provided by it, as explained in the The Visual Tree topic.

During the pre-visiting step, the paint visitor indirectly calls the OnPrePaint protected virtual method of NVisual. This method should be overriden in descendant classes, that need to paint content that appears under the content rendered by descendant visuals.

During the post-visiting step, the paint visitor indirectly calls the OnPostPaint protected virtual method of NVisual. This method should be overriden in descendant classes, that need to paint content that appears above the content rendered by descendant visuals.

Prior to calling the OnPrePaint and OnPostPaint methods, the paint visitor has already consumed the local transform and clip that the visual may provide, so the painting is performed in local coordinates and with an already applied clip. Both the OnPrePaint and OnPostPaint method receive as argument the NPaintVisitor instance, that currently paints the visual.

The rest of the topic discusses the API available for high level painting with a paint visitor.

The methods that the NPaintVisitor provides, that are related to painting are separated into two distinct groups - styling and geometry/text. The styling methods let you specify the current fill, stroke, shadow and font, that are used to paint the subsequently rendered geometries/texts. The separation between styling and geometry/text allows for multiple geometries and text to be rendered with a single styling configuration.

Typically the start of a new style configuration is marked with a call to the ClearStyles() method, that clears all possible styles from a paint visitor. The following code sample renders a red rectangle with a solid black outline, that is 2 dips wide:

protected override void OnPrePaint(NPaintVisitor visitor)
{
    base.OnPrePaint(visitor);
    visitor.ClearStyles();
    visitor.SetFill(NColor.Red);
    visitor.SetStroke(NColor.Black, 2.0d);
    visitor.PaintRectangle(new NRectangle(10, 10, 100, 100));           
}

The following table outlines the NPaintVisitor methods that alter the respective paint styles:

The following table outlines the NPaintVisitor methods that paint geometries and strings:

We have already seen that the painting of the visual tree is performed by an instance of the NPaintVisitor that "visits" the visuals and asks them to paint themselves. However, when visuals needs to be rendered on screen the repainting of the entire window visuals tree can be quite a complex task. In order to optimize the repaint of visuals that reside in windows, the DOM implements a complex display validation algorithm that is automatically performed

The DOM handles the repaint of the visual trees that reside in windows automatically. It is however up to the develop to inform the DOM that a certain visual needs to be repainted. This is achieved by calling the NVisual-InvalidateDisplay() method. By invalidating the display of the visual, you inform the DOM that the respective visual needs to be repainted on the next window frame.

You need to call the NVisual-InvalidateDisplay() method when there is a chance that the painting code that you have written in the OnPrePaint and OnPostPaint overrides can produce different visual results. Typically in the OnPrePaint and OnPostPaint overrides you will render styles, geometries and text that are exposed by properties of your visual. Such properties can be marked as "affecting the display" of the visual. The DOM will automatically call the NVisual-InvalidateDisplay() method, when the value of these properties changes. To illustrate the approach lets elaborate the paint rectangle example:

public class MyFirstVisual : NVisual
{
 public MyFirstVisual() { }
 static MyFirstVisual() 
 {
  MyFirstVisualSchema = NSchema.Create(typeof(MyFirstVisual), NVisual.NVisualSchema);
  // add the properties
  // note that they are marked as affecting the display of the visual
  RectangleProperty = MyFirstVisualSchema.AddSlot("Rectangle", NDomType.NRectangle, NRectangle.Zero);
  RectangleProperty.SetAffectsDisplay(true);
 
  FillProperty = MyFirstVisualSchema.AddSlot("Fill", typeof(NFill), null);
  FillProperty.SetAffectsDisplay(true);
  StrokeProperty = MyFirstVisualSchema.AddSlot("Stroke", typeof(NStroke), null);
  StrokeProperty.SetAffectsDisplay(true);
 }
 public NRectangle Rectangle { get { return (NRectangle)GetValue(RectangleProperty); } set { SetValue(RectangleProperty, value); } }
 public NFill Fill { get { return (NFill)GetValue(FillProperty); } set { SetValue(FillProperty, value); } }
 public NStroke Stroke { get { return (NStroke)GetValue(StrokeProperty); } set { SetValue(StrokeProperty, value); } }
 protected override void OnPrePaint(NPaintVisitor visitor)
 {
  base.OnPrePaint(visitor);
  // consume the properties values to render a rectangle 
  // note that the properties are marked as affecting the display of the visual
  visitor.ClearStyles();
  visitor.SetFill(Fill);
  visitor.SetStroke(Stroke);
  visitor.PaintRectangle(Rectangle);
 }
 public static readonly NSchema MyFirstVisualSchema;
 public static readonly NProperty RectangleProperty;
 public static readonly NProperty FillProperty;
 public static readonly NProperty StrokeProperty;
}