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

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

Tutorial demo application GraphViewer 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 SimpleEditorForm and also in GraphEditorForm.

GraphControl provides support for a number of WPF-like commands which rely on a commanding infrastructure very similar in concept and usage to that present in Windows Presentation Foundation. The classes that make up this support are CommandManager, CommandBinding, and RoutedCommand from the yWorks.Support.Windows namespace. Together, they realize the command pattern and the necessary command binding support for WPF-like commands in yFiles.NET.

Table 2.16, “Command support 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.27, “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.27. Canvas object groups prepared by the GraphControl

The tutorial demo application ImageExportForm 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-like 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.) GraphControl's file I/O methods that can be used to read and write a graph to GraphML file format are listed in API Excerpt 2.21, “Methods for reading and writing the graph structure”.

// Reading in the graph model from GraphML.
void ImportFromGraphML(string fileName)
void ImportFromGraphML(Stream stream)
void ImportFromGraphML(TextReader reader)

// Writing out the graph model to GraphML.
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 GraphClipboardForm.

The methods listed in API Excerpt 2.22, “Clipboard-related methods” are also conveniently accessible via WPF-like command bindings.

void Cut()
void Copy()
void Paste()

Class GraphControl offers convenient access to the Undo/Redo functionality provided by the UndoEngine that is bound to the graph. API Excerpt 2.23, “Undo/Redo-related methods” lists 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 GraphUndoForm.

The Undo and Redo methods listed in API Excerpt 2.23, “Undo/Redo-related methods” are also conveniently accessible via WPF-like command bindings.

// Obtaining the UndoEngine instance bound to the graph.
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 provides support for a number of WPF-like commands which rely on a commanding infrastructure very similar in concept and usage to that present in Windows Presentation Foundation. The classes that make up this support are CommandManager, CommandBinding, and RoutedCommand from the yWorks.Support.Windows namespace. Together, they realize the command pattern and the necessary command binding support for WPF-like commands in yFiles.NET.

Table 2.17, “Command support by class CanvasControl” lists the commands supported by class CanvasControl.

In addition, it makes available further commands that can be used for WPF-like command binding, too. Table 2.18, “CanvasControl commands” lists the commands provided by class CanvasControl.

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.

API Excerpt 2.24, “Coordinate conversion methods” lists the methods that can be used when explicit coordinate conversion is required.

// From world to view coordinates...
PointD ToViewCoordinates(PointD worldPoint)

// ...and vice-versa.
PointD ToWorldCoordinates(PointD viewPoint)

Example 2.26, “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 methods listed in API Excerpt 2.25, “Content rectangle-related 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 methods shown in API Excerpt 2.26, “Methods that affect the viewport”. 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)

Commands to increase, respectively decrease the zoom factor are also accessible via WPF-like command bindings.

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 in API Excerpt 2.27, “Methods for collecting hit elements”.

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 IPaintable, 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> GetCanvasObject(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 the methods listed in API Excerpt 2.28, “Invalidation methods”.

// Invalidates the entire canvas.
void Invalidate()

// Selective invalidation in world coordinate space.
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 listed in API Excerpt 2.29, “Canvas content printing methods” enable both instant printing to a system's default printer as well as using the full-blown printing user interface.

// Printing the canvas content.
void Print()
bool Print(RectD worldRect,
           bool showPrintDialog, bool showPageSetupDialog, bool showPreview)

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

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

API Excerpt 2.30, “Canvas content image export methods” lists the methods that 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”.

// Exporting the canvas content to bitmap-based graphics file formats.
void ExportToBitmap(string file, string format)
void ExportToBitmap(Stream stream, string format, RectD worldRect)

// Exporting the canvas content to vector-based graphics file format EMF.
void ExportToEmf(string emfFile)
void ExportToEmf(string emfFile, RectD worldRect)
void ExportToEmf(Stream stream)
void ExportToEmf(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.29. 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 IPaintable implementation.

API Excerpt 2.31, “Methods for adding canvas objects to the scene graph” lists the CanvasControl methods that 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.

// Adding canvas objects which consist of user object and descriptor.
ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor)
ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor, 
                  ICanvasObjectGroup group)

// Adding IPaintable implementations (simple canvas objects).
ICanvasObject Add(IPaintable paintable)
ICanvasObject Add(IPaintable paintable, ICanvasObjectGroup group)

To add further groups to the scene graph, the CanvasControl methods listed in API Excerpt 2.32, “Methods for adding groups to the scene graph” can be used. To remove a group from the scene graph, the Remove method can be used.

// Adding to the root group of the scene graph.
ICanvasObjectGroup AddGroup()

// Adding to another group of the scene graph.
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 methods listed in API Excerpt 2.33, “Methods from ICanvasObjects for changing the rendering order of canvas objects” can be used to change the rendering order easily.

// Changing a canvas object's "position" within the group it resides in.
ICanvasObject ToFront()
ICanvasObject ToBack()
ICanvasObject Raise()
ICanvasObject Lower()

// When 'reference' is in another group, the canvas object is moved there.
ICanvasObject After(ICanvasObject reference)
ICanvasObject Before(ICanvasObject reference)