View Implementations

In terms of the Model-View-Controller (MVC) paradigm, the component that is used to display a graph (i.e., the "model") is a "view." It is responsible for presenting the model to the user and also for propagating events generated by the user to the proper controller classes that handle user interaction. In yFiles for Silverlight, this view is provided by the graph control, an instance of type GraphControl.

Class GraphControl

Class GraphControl is a Silverlight control that presents a graph model to the user. It is a direct descendant of class CanvasControl, which provides generic support for displaying arbitrary graphical objects (see description below). The graph control is also often simply referred to as the "canvas."

Example 4.28, “Abbreviated XAML for GraphControl setup” shows an abbreviated XAML definition which includes the single line that effectively embeds the GraphControl into a Silverlight application's window.

Example 4.28. Abbreviated XAML for GraphControl setup

<UserControl xmlns:controlsToolkit="clr-namespace:System.Windows.Controls;
                                    assembly=System.Windows.Controls.Toolkit"
     ... >
  <controlsToolkit:DockPanel>
    ...
    <Grid>
      ...
      <!-- Embed the GraphControl. -->
      <y:GraphControl x:Name="graphControl" Grid.Column="0" Grid.Row="0"/>
    </Grid>
  </controlsToolkit:DockPanel>
</UserControl>

Figure 4.27, “GraphControl interrelations” depicts the GraphControl interrelations with yFiles for Silverlight types.

Figure 4.27. GraphControl interrelations

GraphControl interrelations.

The graph model is an implementation of interface IGraph, which is the central graph structure type. It represents the "model" in MVC terminology and is registered with the graph control via the Graph property.

// 'gc' is of type yWorks.yFiles.UI.GraphControl.

// Set a new graph with this GraphControl.
gc.Graph = new DefaultGraph();
// Adjust the Selection property appropriately to reflect the new graph model.
gc.Selection = new GraphSelection(gc.Graph);

Similar to its base type, GraphControl does not provide any means for handling user interaction. In order to add support for user interaction, "controllers" can be conveniently registered with a GraphControl instance.

In yFiles for Silverlight, a controller is a so-called input mode, an implementation of interface IInputMode. The InputModes property can be used to register input modes.

The most comprehensive controller type that provides support for handling user interaction is class GraphEditorInputMode, it is a perfect match for the graph control. GraphEditorInputMode is described in the section called “User Interaction”.

// 'gc' is of type yWorks.yFiles.UI.GraphControl.

// Add a GraphEditorInputMode to this control to handle user interaction.
gc.InputModes.Add(new GraphEditorInputMode());

General Features

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

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

  • The FitGraphBounds method adds graph-specific clipping support for presenting the entire graph in the canvas.
  • Distinct canvas object groups in the scene graph into which the canvas objects for actual model items, background graphics, or temporary graphical decorations are installed. See the section called “Scene Graph Addendum”.
  • Advanced application-level support: Undo/Redo and clipboard (which are accessible via WPF-like command bindings, too), and also convenient reading and writing of graph structure data from/to GraphML file format. See the section called “Application-level Features”.
  • Support for querying and modifying the selection state of graph elements through an IGraphSelection object. The Selection property can be used to get and set this object.

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.

Command Support

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 for Silverlight.

Table 4.16, “Command support by class GraphControl” lists the commands supported by class GraphControl.

Table 4.16. Command support by class GraphControl

Command Type Commands
Application commands

Clipboard support via Cut, Copy, and Paste. Undo support via Undo and Redo.

File I/O support via Open, Save, and SaveAs is disabled by default, but can be enabled using property FileOperationsEnabled.

Further command support in GraphControl originates from its superclass CanvasControl.

Scene Graph Addendum

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:

  1. Background graphics can be placed into the BackgroundGroup.
  2. Actual canvas objects for model items are in the ContentGroup.
  3. Graphical decoration to indicate the selection state of model items should be placed into the SelectionGroup.
  4. Temporary graphical decoration that highlights special conditions of model items, in particular during a comprehensive mouse gesture, can be placed into the HighlightGroup.
  5. Temporary graphical decoration needed by input modes can be placed into the InputModeGroup.

Figure 4.28, “Canvas object groups prepared by the GraphControl” depicts the 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 4.28. Canvas object groups prepared by the GraphControl

Canvas object groups prepared by the GraphControl.

The following code snippet shows how to use the BackgroundGroup to add a background image to the GraphControl. The IVisualCreator implementation can be seen in tutorial demo application NodeLabelingWindow.

Example 4.29. Adding a background image to the background group

// 'gc' is of type yWorks.yFiles.UI.GraphControl.

private void btnRefreshBackgroundImage_Click(object sender, EventArgs e) {
  // Adds a background image to the GraphControl.
  gc.Add(new BackgroundVisualCreator(), 
    CanvasObjectDescriptor.Instance, graphControl.BackgroundGroup);
  // Triggers a refresh of the view.
  gc.Invalidate();
}

Using the BackgroundGroup to install background graphics is also presented in tutorial demo application ImageExportWindow.

Application-level Features

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 bitmap format 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. Using further printing options, like scaling or poster printing, is described in the section called “Scaling and Poster Printing”.

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)
Description Overloaded method for reading in the graph model from GraphML.
void ExportToGraphML(string fileName)
void ExportToGraphML(Stream stream)
void ExportToGraphML(TextWriter writer)
Description Overloaded method for writing out the graph model to GraphML.

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 also conveniently accessible via WPF-like command bindings.

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 also conveniently accessible via WPF-like command bindings.

UndoEngine GetUndoEngine()
Description Obtaining the UndoEngine instance bound to the graph.
bool CanUndo()
void Undo()
bool CanRedo()
void Redo()

Class CanvasControl

Class CanvasControl is a full-fledged Silverlight control that can be used to render arbitrary graphical objects in an efficient manner. It provides a versatile supporting infrastructure that allows to conveniently create a model consisting of such objects and modify it freely. CanvasControl also supports high-performance panning and zooming of graphical content.

Figure 4.29. CanvasControl interrelations

CanvasControl interrelations.

CanvasControl is a "view" in MVC terminology, and as such displays a "model." It does not provide any means for handling user interaction. In order to add support for user interaction, "controllers" can be conveniently registered with a CanvasControl instance.

In yFiles for Silverlight, a controller is a so-called input mode, an implementation of interface IInputMode. To install an input mode, CanvasControl's InputModes property can be used as shown in Example 4.30, “Installing multiple input modes”.

The controller types that provide support for handling user interaction are described in the section called “User Interaction”.

Example 4.30. Installing multiple input modes

// 'canvasControl' is of type yWorks.Canvas.CanvasControl.

// Concurrently installs two input modes with the canvas.
canvasControl.InputModes.Add(new MoveViewportInputMode());
canvasControl.InputModes.Add(new MyInputMode());

General Features

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:

Command Support

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 for Silverlight.

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

Table 4.17. Command support by class CanvasControl

Command Type Commands
Application commands Printing support via Print
Component commands ScrollPageUp, ScrollPageDown, ScrollPageLeft, ScrollPageRight
Navigation commands Zoom, IncreaseZoom, DecreaseZoom

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

Table 4.18. CanvasControl commands

Command Name Description
FitContentCommand Adjusts the viewport so that the entire content rectangle is visible.

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

Example 4.31. Command binding in XAML

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

World and View Coordinates

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.

Note

One characteristic of world coordinates is that they can have negative values, while view coordinates are always positive.

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)
Description Coordinate conversion method from world to view coordinates...
PointD ToWorldCoordinates(PointD viewPoint)
Description ...and vice-versa.

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

Example 4.32. Coordinate conversion in detail

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

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

Content Rectangle and Viewport

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()
Description Content rectangle-related methods.

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.

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

Hit-testing

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.

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.

Canvas Redraw

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

void Invalidate()
Description Method for invalidating the entire canvas.

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

void Invalidate(ICanvasObject canvasObject)
Description Method from ICanvasObject for invalidation of a given element in the canvas.

Application-level Features

Class CanvasControl provides convenient application-level functionality for printing the content of the canvas, or for exporting it as a bitmap. The printing methods enable instant printing to a system's default printer:

void Print()
void Print(RectD worldRect, InsetsD? pageMargins)
Description Canvas content printing methods.

Note that the Print commands 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”.

The following methods support the export of the canvas's content to a bitmap. More information on image export is available in the section called “Exporting the Canvas's Content”.

WriteableBitmap ExportToBitmap()
WriteableBitmap ExportToBitmap(RectD worldRect)
Description Overloaded method for exporting the canvas content to bitmap-based graphics file formats.

Scene Graph and Canvas Objects

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.

Note

The scene graph is very similar to the Visual Tree used by the Windows Presentation Foundation.

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 4.30. ICanvasObject and related types

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.

Note

The order in which canvas objects are added to a group (or the root group, when no explicit group is specified) directly influences their rendering order: canvas objects that are added later are rendered in front of those added earlier.

ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor)
ICanvasObject Add(Object userObject, ICanvasObjectDescriptor descriptor,
                  ICanvasObjectGroup group)
Description Overloaded method for adding canvas objects which consist of user object and descriptor.
ICanvasObject Add(IPaintable paintable)
ICanvasObject Add(IPaintable paintable, ICanvasObjectGroup group)
Description Overloaded method for adding IPaintable implementations (simple canvas objects).

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.

Note

The order in which groups are added to another group (or the root group, when no explicit group is specified) directly influences the rendering order: the content of groups that are added later is rendered in front of the content of those added earlier.

ICanvasObjectGroup AddGroup()
Description Method for adding to the root group of the scene graph.
ICanvasObjectGroup AddGroupToGroup(ICanvasObjectGroup group)
Description Method for adding to another group of the scene graph.

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()
Description Methods from ICanvasObject for changing a canvas object's "position" within the group it resides in.
ICanvasObject After(ICanvasObject reference)
ICanvasObject Before(ICanvasObject reference)
Description Methods from ICanvasObject for changing the rendering order of canvas objects. When 'reference' is in another group, the canvas object is moved there.

Class GraphOverviewControl

Class GraphOverviewControl is a Silverlight control that presents an overview of the graph model to the user, that always shows the graph model in its entirety. Typically, it has a GraphControl instance associated and displays the same graph as this instance. The GraphControl instance can be either set at creation time or via the GraphControl property.

Superposed on the presentation of the overview is a visual feedback for the current clipping area of the associated GraphControl instance. This superposed rectangle can be moved using the mouse, thereby moving the clipping area accordingly. GraphOverviewControl also supports mouse wheel zooming and propagates the new zoom to the GraphControl instance it has associated.

Note

To reduce drawing complexity, GraphOverviewControl does not display the graph in the same manner as the associated GraphControl instance. Instead, the graph is displayed with less details: labels are omitted, there are no arrows at the ends of edges and nodes are always drawn as rectangles.

The visualization of the superposed rectangle can be adjusted using a custom <DataTemplate> resource that is registered with the ResourceKey ViewportTemplateKey defined in class OverviewInputMode.

The tutorial demo applications SimpleEditorWindow and GraphEditorWindow demonstrate how a GraphOverviewControl can be instantiated.