PREV NEXT

Generic Logic, Inc. www.genlogic.com


6.5 C/C++ Graph Layout Component

Overview

The GLG Graph Layout Library is a collection of functions implementing the spring embedder graph layout algorithm used for automatic layout of graphs containing nodes connected with edges. The spring embedder algorithm performs a number of iterations optimizing the graph layout and minimizing the number of node intersections. The GLG Graph Layout Demo is an example of an application that creates and automatically lays out a graph containing the connected nodes of a network. The demo's source code may be used as an example of using the Graph Layout module.

As seen in the demo, GLG Graph Layout may be used together with the GLG graphical engine, using GLG to display the graph and its nodes. In this case, the GLG Graphics Builder may be used to define a palette of graphical objects containing icons for the graph's nodes.

The Graph Layout may also be used to lay out non-GLG objects, for example, widgets or controls representing an application's objects. In this case, the application uses the Graph Layout's relative node position output (in the range of 0 to 1) to position an application's objects on the page.

The Graph Layout Component is provided with the GLG Extended API. Java and C#/.NET versions of the Graph Layout are also provided with the corresponding version of the GLG Class Library. This chapter describes the C/C++ version of the Graph Layout Component. The Java and C#/.NET versions of the GraphLayout class are described in Using the Java and C# Versions of the Toolkit.

Data Access Macros

The following macros are defined in the GlgGraphLayout.h file and can be used to access or change data stored in the GlgGraphLayout, GlgGraphNode and GlgGraphEdge structures.

GlgGraphNode Macros

GlgNodeType( node )

Returns the node type (0-based index used to associate the node with the node icon from the palette).

GlgNodeData( node )

Returns the data pointer associated with the node.

GlgNodeDisplayPosition( node )

Returns a pointer to the GlgPoint structure containing the node's display position in GLG coordinates (in the range from -1000 to 1000).

GlgNodePosition( node )

Returns a pointer to the GlgPoint structure containing the node's position in normalized coordinates (in the range from 0 to 1).

GlgNodeGraphics( node )

Returns the GlgObject actually used to display the node.

GlgNodeTemplate( node )

Returns a custom GlgObject used to display the node. If the template is NULL, an icon from the palette is used.

GlgNodeLinkArray( node )

Returns a group (GlgObject) containing the list of links (of the GlgGraphEdge type) attached to this node.

GlgNodeAnchor( node )

Returns the node's anchor flag. Setting this flag to True anchors the node: the node remains stationary, while the rest of the nodes move around it.

GlgGraphEdge Macros

GlgEdgeType( edge )

Returns the edge type (0-based index used to associate the node with the edge icon from the palette). It is 0 in the current implementation.

GlgEdgeData( edge )

Returns the data pointer associated with the edge.

GlgEdgeGraphics( edge )

Returns the GlgObject actually used to display the edge.

GlgEdgeTemplate( edge )

Returns a custom GlgObject used to display the edge. If the template is NULL, an icon from the palette is used.

GlgEdgeStartNode( edge )

Returns the GlgGraphNode the start of the edge is connected to.

GlgEdgeEndNode( edge )

Returns the GlgGraphNode the end of the edge is connected to.

GlgGraphLayout Macros

GlgGraphDefNodeIcons()

Returns a group of node icons to use if no palette is defined (global).

GlgGraphDefEdgeIcon()

Returns an edge icon to use if no palette is defined (global).

GlgGraphDefViewportIcon()

Returns the default viewport to use to render the graph (global).

GlgGraphPalette( graph_layout )

Returns the GlgObject used as the graph's palette.

GlgGraphDimensions( graph_layout )

Returns a pointer to the GlgCube structure that defines the extent of the graph's drawing, [-800;800] by default.

GlgGraphNodeArray( graph_layout )

Returns a group (GlgObject) containing all graph nodes (GlgGraphNode).

GlgGraphEdgeArray( graph_layout )

Returns a group (GlgObject) containing all graph edges (GlgGraphEdge).

GlgGraphEndTemperature( graph_layout )

The final "temperature" of the graph (in the range from 0 to 1) defining the end of the layout process, 0.2 by default. A higher value will result in the process finishing faster but with less precision. A lower value will cause the layout process to last longer, trying to produce a finer layout.

GlgGraphFinished( graph_layout )

Returns True when the graph layout finishes positioning the nodes.

GlgGraphIteration( graph_layout )

Returns the current iteration number.

GlgGraphUpdateRate( graph_layout )

Returns the update rate: the graph is redrawn after each update_rate iterations.

Function Descriptions

To use any of the functions described in this chapter, the application program must include the function definitions from the GLG Graph Layout header file. Use the following line to include these definitions:

#include "GlgGraphLayout.h"

The following section describes the interfaces of the GLG Graph Layout Library:

GlgGraphCreate

Creates a new GlgGraphLayout:

GlgGraphLayout GlgGraphCreate()

GlgGraphDestroy

Destroys all internal structures used by the instance of the graph:

void GlgGraphDestroy( GlgGraphLayout graph )
Parameters
graph
Specifies the graph to destroy.

GlgGraphTerminate

Destroys all internal structures used by the Graph Layout module:

void GlgGraphTerminate()

GlgGraphSetPalette

Sets the graph's icon palette:

void GlgGraphSetPalette( GlgGraphLayout graph, 
						GlgObject palette_drawing )
Parameters
graph
Specifies the graph.
palette_drawing
Specifies the palette to use for the graph.

The palette drawing must contain node icons named Node0, Node1, Node2, etc. Each node must contain a G-type resource named Position, which is used by the graph layout to position the node. The palette must also contain an edge icon (a polygon named Edge), which is used to define the edges' attributes.

GlgGraphSetDefaultPalette

Sets the default palette to be used by all graphs:

void GlgGraphSetDefPalette( GlgObject palette_drawing )
Parameters
palette_drawing
Specifies the palette to use as a default palette.

GlgGraphUnloadDefaultPalette

Resets the default palette to NULL and destroys any stored objects:

void GlgGraphUnloadDefPalette()

GlgGraphCreateGraphics

Loads icons from the palette and creates a GLG drawing to render the graph:

void GlgGraphCreateGraphics( GlgGraphLayout graph, 
				GlgObject viewport)
Parameters
graph
Specifies the graph.
viewport
An optional viewport. If it is not NULL, it is used as a container for the graph's drawing, rendering the graph in the existing object hierarchy. If it is NULL, the graph will create a new viewport to render the graph.

GlgGraphDestroyGraphics

Destroys the graph's drawing and all graphical objects used to render nodes and edges:

void GlgGraphDestroyGraphics( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph.

GlgGraphGetViewport

Returns the viewport of the graph's drawing:

GlgObject GlgGraphGetViewport( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph.

GlgGraphSpringIterate

Performs one iteration of the sprint embedder layout:

GlgBoolean GlgGraphSpringIterate( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph to layout.

This function returns True if the layout process has finished.

GlgGraphUpdate

Updates the display to show the results of the spring layout:

void GlgGraphUpdate( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph to update.

There is no need to update the display after every iteration: it may be updated every N iterations, or just once when the layout is finished.

GlgGraphAddNode

Creates a new node and adds it to the graph:

GlgGraphNode GlgGraphAddNode( GlgGraphLayout graph,
					GlgObject graphics,
					long node_type, 
				void * data )
Parameters:
graph
Specifies the graph.
graphics
An optional custom node icon to override the icon from the palette.
node_type
The palette index which specifies what icon to use from the node palette if no custom graphics is specified.
data
The custom data to attach to the node.

GlgGraphAddEdge

Creates a new edge and adds it to the graph:

GlgGraphEdge GlgGraphAddEdge( GlgGraphLayout graph,
				GlgGraphNode start_node,
			GlgGraphNode end_node,
			GlgObject graphics,
				long edge_type, 
			void * data )
Parameters:
graph
Specifies the graph.
graphics
An optional custom edge icon to override the icon from the palette.
edge_type
The palette index which specifies what icon to use from the edge palette if no custom graphics is specified (reserved for future use).
data
The custom data to attach to the edge.

GlgGraphDeleteNode

Deletes a node from the graph:

void GlgGraphDeleteNode( GlgGraphLayout graph,
				GlgGraphNode node )
Parameters:
graph
Specifies the graph.
node
The node to delete.

GlgGraphDeleteEdge

Deletes an edge from the graph:

void GlgGraphDeleteEdge( GlgGraphLayout graph,
				GlgGraphEdge edge )
Parameters:
graph
Specifies the graph.
edge
The edge to delete.

GlgGraphGetNodePosition

Returns the node position in GLG coordinates (in the range from -1000 to 1000):

void GlgGraphGetNodePosition( GlgGraphLayout graph,
				GlgGraphNode node, 
			double * x, double * y,
			double * z );
Parameters:
graph
Specifies the graph.
node
The node object
x, y, z
The returned coordinate values.

GlgGraphSetNodePosition

Sets the node position in GLG coordinates (in the range from -1000 to 1000):

void GlgGraphSetNodePosition( GlgGraphLayout graph,
				GlgGraphNode node, 
			double x, double y,
			double z );
Parameters:
graph
Specifies the graph.
node
The node object.
x, y, z
The new coordinate values.

GlgGraphFindNode

Finds the node object by its graphics:

GlgGraphNode GlgGraphFindNode( GlgGraphLayout graph,
				GlgObject node_graphics )
Parameters:
graph
Specifies the graph.
node_graphics
The graphical object used to render the node in the drawing.

This function is used to handle mouse selection and returns the node object.

GlgGraphFindEdge

Finds the edge object by its graphics:

GlgGraphNode GlgGraphFindEdge( GlgGraphLayout graph,
				GlgObject edge_graphics )
Parameters:
graph
Specifies the graph.
edge_graphics
The graphical object used to render the edge in the drawing.

This function is used to handle mouse selection and returns the edge object.

GlgGraphNodesConnected

A connectivity test which returns True if there is an edge connecting the two specified nodes:

GlgBoolean GlgGraphNodesConnected( GlgGraphNode node1,
				GlgGraphNode node2 )
Parameters:
graph
Specifies the graph.
node1, node2
The node objects.

GlgGraphIncreaseTemperature

Forces the graph to continue the layout after it is finished by increasing the temperature of the graph by a small increment:

void GlgGraphIncreaseTemperature( GlgGraphLayout graph, 		
				GlgBoolean init )
Parameters:
graph
Specifies the graph.
init
Specifies whether a large increment should be used to re-layout the graph if True.

GlgGraphGetUntangle

Returns True if the untangling algorithm is enabled:

GlgBoolean GlgGraphGetUntangle( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph.

The untangling algorithm helps the graph layout to avoid local minima in the form of intersecting edges. Using it roughly doubles the time it takes to finish the layout.

GlgGraphSetUntangle

Enables or disables the untangling algorithm:

void GlgGraphGetUntangle( GlgGraphLayout graph,
					GlgBoolean untangle )
Parameters:
graph
Specifies the graph.
untangle
Specifies whether untangling should be used.

GlgGraphError

Prints an error message:

void GlgGraphError( char * string )
Parameters:
string
The error message to print.

GlgGraphScramble

Randomly scrambles the graph's nodes:

void GlgGraphScramble( GlgGraphLayout graph )
Parameters:
graph
Specifies the graph to scramble.

This method is used mostly by demo programs.

GlgGraphCreateRandom

The demo constructor which creates and returns a graph layout, populating it with nodes and edges:

GlgGraphLayout GlgGraphCreateRandom( long num_nodes, 
				long num_node_types, 
				GraphType type );
Parameters:
num_nodes
The number of graph nodes to create.
num_node_types
The number of node types to use for rendering.
type
A graph type constant: RANDOM_GRAPH, CIRCULAR_GRAPH or STAR_GRAPH.


Generic Logic, Inc.
www.genlogic.com
PREV NEXT