Class GraphControl offers all the functionality exposed by CanvasControl, including, e.g.:

Additionally, it makes available comfortable graph model-specific functionality:

Tutorial demo application GraphViewerWindow shows how to use class GraphControl to display the visual representation of a graph structure. Using the GraphControl along with a GraphEditorInputMode that handles user interaction is presented in SimpleEditorWindow and also in GraphEditorWindow.

GraphControl supports a number of predefined WPF commands out of the box. Table 2.16, “Support for predefined WPF commands by class GraphControl” lists the commands supported by class GraphControl.

Table 2.16, “Support for predefined WPF commands by class GraphControl” lists the commands supported by class GraphControl.

The GraphControl prepares a set of canvas objects groups beneath the Root group in the scene graph that are designed to hold distinct sets of canvas objects:

Figure 2.28, “Canvas object groups prepared by the GraphControl” depicts the initial order of these groups in the scene graph. The background group is the first child of the Root group, the input mode group is the last child. Consequently, any temporary decorations installed by input modes will be rendered frontmost while background graphics will be rendered behind all other canvas content.

Figure 2.28. Canvas object groups prepared by the GraphControl

The tutorial demo application ImageExportWindow shows how to use the BackgroundGroup to install background graphics.

Class GraphControl provides convenient application-level functionality including clipboard and Undo/Redo support, which, in particular, is accessible via WPF command bindings, too. Printing the content of the canvas and exporting it to a variety of graphics file formats is supported as well. Also, the graph model can be read from and written to the GraphML graph structure exchange file format easily.

Note that the support for printing and exporting the content of the canvas is already provided in the context of class CanvasControl. (See the description in CanvasControl's Application-level Features.) The following GraphControl file I/O methods can be used to read and write a graph from/to GraphML file format:

void ImportFromGraphML(string fileName)
void ImportFromGraphML(Stream stream)
void ImportFromGraphML(TextReader reader)

void ExportToGraphML(string fileName)
void ExportToGraphML(Stream stream)
void ExportToGraphML(TextWriter writer)

By means of a GraphClipboard instance that is associated with a GraphControl, default clipboard support covering Cut, Copy, and Paste actions is provided. For further control, this instance can be obtained via the Clipboard property.

Using the clipboard is shown in the tutorial demo application GraphClipboardWindow.

The following methods are conveniently accessible via WPF command bindings for application commands, too.

void Cut(IGraph sourceGraph, Predicate<IModelItem> filter)
void Copy(IGraph sourceGraph, Predicate<IModelItem> filter)
void Paste(IGraph targetGraph, Predicate<IModelItem> filter)

Class GraphControl offers convenient access to the Undo/Redo functionality provided by the UndoEngine that is bound to the graph. Listed below are the methods that can be used.

Using the graph's Undo/Redo support through the convenience methods provided by the graph control is demonstrated in tutorial demo application GraphUndoWindow.

The Undo and Redo methods are conveniently accessible via WPF command bindings for application commands, too.

UndoEngine GetUndoEngine()

bool CanUndo()
void Undo()
bool CanRedo()
void Redo()

Out-of-the-box, class CanvasControl already supports a wide variety of useful features that can be conveniently enabled/disabled and customized. Included is, for example:

CanvasControl supports a number of predefined WPF commands out of the box. Table 2.17, “Support for predefined WPF commands by class CanvasControl” lists the commands supported by class CanvasControl.

Table 2.17, “Support for predefined WPF commands by class CanvasControl” lists the commands supported by class CanvasControl.

In addition, it makes available further commands that can be used for command binding, too. Table 2.18, “CanvasControl commands” lists the commands provided by class CanvasControl. Note that all commands are of type RoutedUICommand.

Example 2.31, “Command binding in XAML” shows the XAML definition for a command binding that connects a menu item to the fit content command provided by CanvasControl.

<MenuItem Header="View">
  <MenuItem Command="{x:Static y:CanvasControl.FitContentCommand}"/>
</MenuItem>

There are different coordinate spaces used for the model itself and for its presentation in the canvas, the so-called "world coordinates" and the view coordinates.

The common thing to both world and view coordinate space is the way coordinates increase with each direction. Coordinates on computer screens most commonly increase from left to right and from top to bottom. Note that this is diametrical to the normal Cartesian coordinate system known from school where coordinates increase from left to right and from bottom to top.

The view coordinates always start with (0,0) for the upper left corner and increase to the right and to the bottom. The coordinates of the lower right corner accordingly equals to (view_width-1, view_height-1), i.e., the view coordinates directly reflect the viewport's size. (Note that the canvas is also referred to as "the viewport" here. This term is most notably used whenever the dimensions of the canvas are of particular importance or the clipping is discussed, i.e., the visible part of the model.)

The world coordinates, in contrast, are those valid in the model, i.e., they denote the proper locations that are set for a node's upper-left corner or the control points of an edge.

The mapping from one coordinate space to the other happens automatically and is achieved using the notion of the so-called "view point" and scaling. The view point determines the world coordinates that get directly mapped to the upper-left corner of the viewport, i.e., it defines where the view's origin lies in the world coordinates's two-dimensional space. The ViewPoint property can be used to control the view point.

An additional scaling factor that can be applied to the world coordinates determines the zoom level with which the canvas scales the model's presentation. To control the zoom level, CanvasControl provides the Zoom property.

These methods can be used when explicit coordinate conversion is required:

PointD ToViewCoordinates(PointD worldPoint)

PointD ToWorldCoordinates(PointD viewPoint)

Example 2.32, “Coordinate conversion in detail” presents the instructions for coordinate conversion in detail.

// From world to view coordinates...
viewPoint = (worldPoint - gc.ViewPoint) * zoom;

// ...and vice-versa.
worldPoint = viewPoint/zoom + gc.ViewPoint;

The intention of the content rectangle is to specify an "area of interest" within the world coordinate space. This area can then be used by the canvas to determine the actual part of the model to be displayed in response to a call to FitContent, most notably.

The content rectangle can be conveniently specified and modified using the following methods. Note that CanvasControl also provides the ContentRect property to control the content rectangle.

void GrowContentRect(RectD boundsToInclude)
void UpdateContentRect()

The actual clipping of the world coordinate space that is displayed in the canvas can furthermore be modified using the following methods. CanvasControl also provides the Zoom property to control the scaling factor used by the canvas. Additionally, the Viewport property can be used to obtain the dimensions of the currently visible part of the model.

void FitContent()
void ZoomTo(PointD center, double zoom)
void ZoomTo(RectD bounds)

Note that the FitContent method is supported as a routed command, too. Additionally, commands to increase, respectively decrease the zoom factor are accessible via WPF command bindings for navigation commands.

To test whether a canvas object lies at a given coordinate, or to collect all canvas objects at a given coordinate, CanvasControl provides the methods listed below.

Note that hit-testing relies on the availability of an IHitTestable implementation for a canvas object. Normally, such an implementation is returned by a canvas object's descriptor. "Simple" canvas objects, i.e., implementations of interface IVisualCreator, however, do not provide a descriptor and hence do not support hit-testing.

bool IsHit(ICanvasObject canvasObject, PointD point)

ICanvasObject GetCanvasObject(PointD location)
IList<ICanvasObject> GetCanvasObjects(PointD location)

IEnumerator<ICanvasObject> EnumerateHits(PointD location)
IEnumerator<ICanvasObject> EnumerateHits(PointD location,
                                         ICanvasObjectGroup root)
IEnumerator<ICanvasObject> EnumerateHits(PointD location,
                                         ICanvasObjectGroup root,
                                         Predicate<ICanvasObject> filter)

The HitTestRadius property of class CanvasControl can be used to control the hit-testing sensitivity that is used when mouse click events are processed. Note that the value for this property is given in view coordinates rather than world coordinates, which enables precise testing behavior especially with small zoom levels.

To trigger redraw operations in the canvas, class CanvasControl provides:

void Invalidate()

Additionally, elements in the canvas can be marked in need of a redraw using:

void Invalidate(ICanvasObject canvasObject)

Class CanvasControl provides convenient application-level functionality for printing the content of the canvas, or for exporting it to a variety of graphics file formats. The printing methods enable both instant printing to a system's default printer as well as using the full-blown printing user interface:

void Print()
bool Print(RectD worldRect,
           bool showPrintDialog, bool showPreview, InsetsD? pageMargins)

Note that the Print and additionally the PrintPreview command are also accessible via WPF command bindings for application commands.

Using further printing options, like scaling or poster printing, is described in the section called “Scaling and Poster Printing”.

The following methods support the export of the canvas's content to a graphics file format. The available graphics file formats are discussed in the section called “Exporting the Canvas's Content”.

void ExportToBitmap(string file, string format)
void ExportToBitmap(Stream stream, string format, RectD worldRect)

void ExportToXps(string xpsFile)
void ExportToXps(string xpsFile, RectD worldRect)
void ExportToXps(Stream stream)
void ExportToXps(Stream stream, RectD worldRect)

Central to the services that CanvasControl provides is the so-called "scene graph," the supporting infrastructure that holds the model of graphical objects.

The scene graph is a data structure maintained by a CanvasControl object. It is used to hold "canvas objects," elements that provide the logic for rendering graphical objects in the canvas, and also to determine the actual rendering order of these objects.

The scene graph most often is a tree-like structure that consists of inner nodes and leaf nodes. The leaf nodes are always actual canvas objects, which are implementations of interface ICanvasObject. The inner nodes are so-called groups that can be used to partition the set of canvas objects in any suitable manner. Groups are implementations of interface ICanvasObjectGroup. A scene graph has at least one group, the root group, which cannot be removed. It is accessible via the Root property.

Figure 2.30. ICanvasObject and related types

An ICanvasObject bundles a custom so-called user object and an ICanvasObjectDescriptor. The intention of the former is to hold any data specific to a given graphical object, like, e.g. its size and its location in the canvas. The latter is used by the CanvasControl to obtain the actual logic related to all rendering and interaction aspects for the corresponding canvas object.

CanvasControl also supports "simple" canvas objects that provide the rendering logic themselves and can do without an explicit descriptor. These canvas objects consist of an IVisualCreator implementation.

The CanvasControl methods listed below can be used to add canvas objects to the scene graph. To remove a canvas object from the scene graph, the Remove method can be used.

ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor)
ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor,
                  ICanvasObjectGroup group)

ICanvasObject Add(IPaintable paintable)
ICanvasObject Add(IPaintable paintable, ICanvasObjectGroup group)

To add further groups to the scene graph, the CanvasControl methods listed below can be used. To remove a group from the scene graph, the Remove method can be used.

ICanvasObjectGroup AddGroup()

ICanvasObjectGroup AddGroupToGroup(ICanvasObjectGroup group)

The scene graph is also used to determine the rendering order of graphical objects. To this end, it is traversed in depth-first manner when a redraw is requested. The rendering of canvas objects is done in the order they are traversed, i.e., objects that are traversed later are drawn in front of earlier traversed ones.

Initially, the rendering order can be determined by the order in which canvas objects are added to a group and the order in which groups are added to another group. Once groups and canvas objects are in the scene graph, the following methods can be used to change the rendering order easily:

ICanvasObject ToFront()
ICanvasObject ToBack()
ICanvasObject Raise()
ICanvasObject Lower()

ICanvasObject After(ICanvasObject reference)
ICanvasObject Before(ICanvasObject reference)