Skip to content

General Graph Support

Jump to bottom
Gary edited this page Mar 10, 2015 · 2 revisions

Table of Contents

This section covers classes that offer general graph support. It's split in two parts by these assemblies:

  • Atf.Gui: Graph element classes and interfaces that are UI-platform-agnostic (such as Windows® Forms or WPF).
  • Atf.Gui.WinForms: Classes for working with graph elements, including adapters, renderers, documents, and validators that are dependent on Windows® Forms.
Most of ATF's graph support classes are for specific graph types. For more information, see Circuit Graph Support and Statechart Graph Support.

Atf.Gui Assembly Graph Support

The Atf.Gui assembly contains all the graph interfaces. For details on these, see ATF Graph Interfaces.

It also provides DOM-based default interface implementations of the circuit model (Element, Pin, Wire, Group, and Circuit). For information on circuits, see Circuit Graph Support.

The rest of this section discusses non-interface items in the assembly.

D2dGraphRenderer Class

D2dGraphRenderer is an abstract base class for graph renderers, which render and hit-test a graph. It derives from another abstract class, DiagramRenderer in the Sce.Atf.Controls.Adaptable namespace, which is the base class for diagram renderers that render and hit-test diagrams.

Several specific type of graph renderers derive from this class to render circuits and statecharts: D2dCircuitRenderer and D2dStatechartRenderer. Several control adapters require a D2dGraphRenderer in their constructors: D2dGraphAdapter and D2dGraphEdgeEditAdapter. For information on these adapters, see Direct2D Adapters.

D2dGraphRenderer contains several abstract Draw() methods to draw nodes and edges, which are overridden in the renderers D2dCircuitRenderer and D2dStatechartRenderer. Draw() is called in the adapter D2dGraphAdapter's OnRender() method for specific renderers.

Similarly, D2dGraphRenderer offers Pick() methods to find a node or edge hit by the given point. These are overridden in D2dCircuitRenderer, D2dStatechartRenderer, D2dDigraphRenderer, and D2dSubCircuitRenderer. Pick() is called in the adapter D2dGraphAdapter for specific renderers.

The Print() method uses a Draw() method to draw a graph in a printer-friendly way.

GraphHitRecord Class

GraphHitRecord is a generic class that specifies the node, edge, and in/out edge routes from a graph picking operation, and is returned by some D2dGraphRenderer.Pick() methods. Additionally, an IGraphNode or IGraphEdge may be specified as the item that was hit in the various GraphHitRecord constructor forms. GraphHitRecord has methods to retrieve the hit IGraphNode or IGraphEdge. GraphHitRecord also includes the hit path for renderers that support hierarchical picking, such as the circuit renderer, which needs to transverse up or down the hit path along the expanded group hierarchy.

EdgeStyleData Class

EdgeStyleData contains information on edge styles:

  • EdgeShape enumeration for the shape of an edge. It includes alternatives, such as a line, a Bezier curve or spline, or not drawn at all.
  • ShapeType: Property to get or set the edge's EdgeShape.
  • Thickness: Property to get or set line thickness.
  • EdgeData: Property to get or set the edge data that represents the edge shape.

Atf.Gui.WinForms Assembly Graph Support

The Atf.Gui.WinForms assembly contains control adapters, utilities, and Direct2D handling classes that, one way or another, reference types in the Windows® Forms API. For example, all control adapters operate on an adapted control that derives from the System.Windows.Forms.Control class.

Adapter and Utility Classes

Control Adapter Classes

Control adapters add capabilities to adaptable controls. For a discussion of how adapters are used on a D2dAdaptableControl to handle circuits in the ATF Circuit Editor Sample, see Circuit Document Display.

KeyboardGraphNavigator Class

KeyboardGraphNavigator is a ControlAdapter derived class that adapts a control for navigating a graph using the arrow keys. It subscribes the control to key press events. When a key is pressed, it finds the nearest node to the starting node in the desired direction using its FindNearestElement() method, and selects that node. It uses the standard Windows® convention of using the Control key to toggle the selection of the given item, the Shift key to add the item to the selection, and otherwise to set the selection to the item.

If the graph has inputs and outputs on specific sides of the nodes, as for a circuit, consider using the KeyboardIOGraphNavigator class instead.

It is used by the ATF Fsm Editor Sample and the ATF State Chart Editor Sample.

KeyboardIOGraphNavigator Class

KeyboardIOGraphNavigator is a ControlAdapter that operates similarly to KeyboardGraphNavigator, except that it navigates an "input-output" graph that has inputs and outputs on specific sides of the nodes, as in a circuit graph. It changes selection using the arrow keys, with the Shift key adding to the selection.

It is used by the ATF Circuit Editor Sample.

Utility Classes

GraphViewCommands Class

The GraphViewCommands component is the command client for zoom commands, implementing ICommandClient. It creates the View > Zoom menu items and their corresponding commands:

  • Zoom In
  • Zoom Out
  • Zoom Reset
GraphViewCommands is used by the ATF Circuit Editor Sample.
NumberedRoute Class

NumberedRoute is used to route directed graph edges, so that multiple edges connecting the same nodes do not overlap in rendering. An index indicates the degree of curving: route 0 is a straight line between nodes, route 1 is a slight arc, route 2 is a more curved arc, and so on. This illustration shows how multiple edges are displayed in the ATF FSM Editor Sample between "State1" and "State2" in the group of nodes at the bottom:

Direct2D Classes

These classes are control adapters and renderers for Direct2D controls, such as D2dAdaptableControl. For more information about Direct2D, see the MSDN article About Direct2D.

Direct2D Adapters

Several control adapters work with Direct2D.

D2dGraphAdapter Class

D2dGraphAdapter is the key adapter here, because it adapts a control to displaying a graph. It also provides hit testing with its Pick() method. D2dGraphAdapter does not render a graph itself, but uses the D2dGraphRenderer passed in its constructor: 

public D2dGraphAdapter(D2dGraphRenderer<TNode, TEdge, TEdgeRoute> renderer,
    ITransformAdapter transformAdapter)

D2dGraphAdapter's OnRender() method is called to actually render the graph. OnRender() calls the renderer's Draw() methods to draw the nodes and edges of the graphs. D2dGraphAdapter may be used as is, or overridden. For example, the ATF State Chart Editor Sample derives its own StatechartGraphAdapter from D2dGraphAdapter and also overrides its OnRender() method.

The adapter D2dSubgraphAdapter derives from D2dGraphAdapter and has the same purpose, except that it works with a subgraph.

D2dGraphAdapter is required by the other adapters D2dGraphEdgeEditAdapter and D2dGraphNodeEditAdapter in their constructors. For example: 

public D2dGraphEdgeEditAdapter(
    D2dGraphRenderer<TNode, TEdge, TEdgeRoute> renderer,
    D2dGraphAdapter<TNode, TEdge, TEdgeRoute> graphAdapter,
    ITransformAdapter transformAdapter)

Both the D2dGraphEdgeEditAdapter and D2dGraphNodeEditAdapter constructors also require a D2dGraphRenderer.

D2dGraphEdgeEditAdapter Class

D2dGraphEdgeEditAdapter adds graph edge dragging capabilities to an adapted control. It derives from DraggingControlAdapter, which is the base class for control adapters that handle mouse dragging, and overrides its methods to handle mouse manipulation.

Edges can be moved, disconnected, and reconnected to other nodes. D2dGraphEdgeEditAdapter has methods like CanConnectTo(), CanConnectFrom(), and MakeConnection() to check if connections can be made and make them.

The ATF Circuit Editor Sample, the ATF Fsm Editor Sample, and the ATF State Chart Editor Sample all use D2dGraphEdgeEditAdapter, varying the constructor type parameters according to their graph model. For example, CircuitEditor does this to fit its variant of IGraph: 

var circuitConnectionEditAdapter =
    new D2dGraphEdgeEditAdapter<Module, Connection, ICircuitPin>(m_circuitRenderer, circuitAdapter, transformAdapter);

Because it uses states as nodes and transitions as edges, State Chart Editor does this: 

var statechartTransitionEditAdapter =
    new D2dGraphEdgeEditAdapter<StateBase, Transition, BoundaryRoute>(m_statechartRenderer, statechartAdapter, transformAdapter);
D2dGraphNodeEditAdapter Class

D2dGraphNodeEditAdapter complements D2dGraphEdgeEditAdapter by adding graph node dragging capabilities to an adapted control. D2dGraphNodeEditAdapter also derives from DraggingControlAdapter, overriding its methods. Dragging nodes does not change edge connections, but it does move the edges along with the nodes. This class does not handle dragging nodes out of groups of nodes; that is handled by the IEditableGraphContainer interface. For more information on using IEditableGraphContainer, see CircuitEditingContext Class. D2dGraphNodeEditAdapter is used as an adapter for node dragging in the ATF Circuit Editor Sample, the ATF Fsm Editor Sample, and the ATF State Chart Editor Sample. In constructing D2dGraphNodeEditAdapter, these samples vary the type parameters, depending on the graph model, just as for D2dGraphEdgeEditAdapter.

Direct2D Renderers

ATF provides renderers for different types of graphs. The most general one is the abstract class D2dGraphRenderer, already discussed in D2dGraphRenderer Class. The other graph rendering classes derive from D2dGraphRenderer.

Renderers are used with control adapters. For instance, D2dGraphAdapter and D2dGraphEdgeEditAdapter.require a D2dGraphRenderer in their constructors.

Renderers use a D2dGraphics object to do the actual drawing. D2dGraphics represents an object that can receive drawing commands and uses Direct2D for drawing.

D2dDigraphRenderer is a fairly general graph rendering class derived from D2dGraphRenderer. It is a standard directed graph renderer that renders nodes as disks and edges as lines or arcs. Edge routes have integer indices, indicating which line or arc to draw for the edge, and this allows multiple edges between a pair of nodes to be distinguished.

D2dDigraphRenderer has Draw() methods for nodes and edges that use a D2dGraphics object to do the actual drawing. It also has Pick() methods to find the node and/or edge hit by a given point, returning a GraphHitRecord object. D2dDigraphRenderer is the renderer used in the ATF Fsm Editor Sample.

The other renderers are specific to the type of graph:

Obsolete Classes

Do not use the following obsolete classes, which have been superseded by their Direct2D equivalents with a "D2d" prefix:

Obsolete class Direct2D class to use Comment
CircuitRenderer D2dCircuitRenderer
DigraphRenderer D2dDigraphRenderer
GraphAdapter D2dGraphAdapter
GraphEdgeEditAdapter D2dGraphEdgeEditAdapter
GraphNodeEditAdapter D2dGraphNodeEditAdapter
GraphRenderer D2dGraphRenderer GraphRenderer is referenced only in the obsolete classes. D2dGraphRenderer is in the Atf.Gui assembly.
StatechartRenderer D2dStatechartRenderer

Topics in this section

Graphs in ATF

About

Learning

© 2014-2015, Sony Computer Entertainment America LLC
Clone this wiki locally