Grapher class. More...

#include <ilviews/grapher/grapher.h>

Inheritance diagram for IlvGrapher:

Public Member Functions
	IlvGrapher (IlvDisplay *display, int layers=2, IlBoolean useacc=IlTrue, IlUShort maxInList=IlvMaxObjectsInList, IlUShort maxInNode=IlvMaxObjectsInList)
	Constructor. More...

IlvGraphic *	addGhostNode (const IlvPoint &p, int layer=-1)
	Adds an invisible node to the grapher. More...

virtual void	addLink (IlvLinkImage link, IlBoolean redraw=IlTrue, int layer=-1, IlvLinkImage afterFrom=0, IlvLinkImage *afterTo=0)
	Adds a link to the grapher. More...

virtual void	addNode (IlvGraphic *obj, IlBoolean redraw=IlTrue, int layer=-1)
	Adds a node to the grapher. More...

void	applyLinks (IlvGraphic *node, IlvApplyObject f, IlAny arg, IlvLinkType type, IlBoolean reDraw=IlTrue)
	Applies a function to the links connected to a given node. More...

IlBoolean	areLinksEditable () const
	Indicates whether links can be edited interactively. More...

virtual void	changeLink (IlvLinkImage link, IlvLinkImage newLink, IlBoolean redraw=IlFalse)
	Changes the graphic representation of an existing link. More...

virtual void	changeNode (IlvGraphic node, IlvGraphic newNode, IlBoolean redraw=IlFalse)
	Changes the graphic representation of an existing node. More...

const char *	getDefaultLinkClass () const
	Returns name of the default link class used to create links. More...

const char *	getDefaultNodeClass () const
	Returns the name of the default graphic class used to create nodes. More...

IlvLinkImage const	getLinks (int layer, IlUInt &count)
	Returns the links stored in a layer. More...

IlvLinkImage const	getLinks (IlUInt &count)
	Returns all the links stored in the grapher. More...

IlvLinkImage const	getLinks (const IlvGraphic *node, IlUInt &count, IlvLinkType type=IlvLinkAny) const
	Returns the links connected to a node. More...

IlUInt	getLinksCount (const IlvGraphic *node, IlvLinkType type=IlvLinkAny) const
	Returns the number of links connected to a given node. More...

IlvGraphic const	getNodes (int layer, IlUInt &count)
	Returns the nodes stored in a layer. More...

IlvGraphic const	getNodes (IlUInt &count)
	Returns all the nodes stored in the grapher. More...

IlBoolean	isLink (const IlvGraphic *obj) const
	Indicates whether a given graphic object is a link. More...

IlBoolean	isLinkBetween (const IlvGraphic from, const IlvGraphic to) const
	Indicates whether there is a link connecting two given nodes. More...

IlBoolean	isNode (const IlvGraphic *obj) const
	Indicates whether a given graphic object is a node. More...

virtual IlvGrapher *	makeLink (IlvGraphic *obj)
	Transforms a graphic object into a grapher link. More...

virtual IlvGrapher *	makeNode (IlvGraphic *obj)
	Transforms a graphic object into a grapher node. More...

void	mapLinks (IlvGraphic *node, IlvApplyObject f, IlAny arg, IlvLinkType type)
	Applies a function to the links connected to a given node. More...

IlBoolean	nodeHasLinks (const IlvGraphic *node, IlvLinkType type=IlvLinkAny) const
	Indicates whether a given node is connected to links. More...

virtual void	nodeXPretty (IlvGraphic *node, IlvPos xspacing, IlvPos yspacing, IlBoolean redraw=IlTrue, IlvOrientation orientation=IlvCenter)
	Performs a horizontal tree layout of the nodes. More...

virtual void	nodeYPretty (IlvGraphic *node, IlvPos xspacing, IlvPos yspacing, IlBoolean redraw=IlTrue, IlvOrientation orientation=IlvCenter)
	Performs a vertical tree layout of the nodes. More...

virtual void	removeLink (IlvLinkImage *link, IlBoolean redraw=IlTrue, IlBoolean destroyIt=IlTrue)
	Removes a link from the grapher. More...

virtual void	removeNode (IlvGraphic *obj, IlBoolean redraw=IlTrue, IlBoolean destroyIt=IlTrue)
	Removes a node from the grapher. More...

void	setDefaultLinkClass (const char *name)
	Sets the default link class used to create links. More...

void	setDefaultNodeClass (const char *name)
	Sets the default graphic class used to create nodes. More...

void	setLinksEditable (IlBoolean editable)
	Indicates whether links can be edited interactively. More...

Static Public Member Functions
static IlvGrapher *	GetGrapher (const IlvGraphic *obj)
	Returns the grapher managing a given graphic object. More...

Detailed Description

Grapher class.

Library: ilvgrapher

The grapher lets you create graphic programs that represent hierarchical information using graphic objects. The IlvGrapher class is a subtype of the IlvManager class. The grapher library is particularly effective in creating programs that represent large quantities of dynamic, interconnected information, such as network management and file management programs. Through an extensive set of calls to the grapher library, you can create nodes, links, and other graphic objects.

Nodes are the visual reference points in a hierarchy of information. A node is a graphic object - a subtype of the IlvGraphic class - that assumes a particular functionality when added to the grapher via the IlvGrapher::addNode() call. This functionality allows links and nodes to stay together if and when a node is moved.
Links Links are the visual representation of connections between nodes. A link is an instance of the IlvLinkImage class or one of its subclasses. It is added to the grapher with the IlvGrapher::addLink() method. Since links can only exist between two existing nodes, you must create them with two graphic objects that are known as nodes by the grapher.
Graphic objects of the IlvGraphic type, representing neither nodes nor links, can be incorporated into the graphs handled by the grapher.

The figure below illustrates a grapher sample:

- An IlvGrapher -

See also: IlvGraphSelectInteractor, IlvLinkImage, IlvMakeNodeInteractor, IlvMakeLinkInteractor, IlvGrapherPin, IlvGraphNodeSelection.

Constructor & Destructor Documentation

IlvGrapher::IlvGrapher	(	IlvDisplay *	display,
		int	layers = `2`,
		IlBoolean	useacc = `IlTrue`,
		IlUShort	maxInList = `IlvMaxObjectsInList`,
		IlUShort	maxInNode = `IlvMaxObjectsInList`
	)

Constructor.

Initializes an instance of IlvGrapher.

Parameters

display	The display connection used by this instance.
layers	The number of layers in the grapher.
useacc	Indicates whether to install the default accelerators.
maxInList	Specifies the maximum number of objects beyond which a quadtree is used for storage.
maxInNode	The maximum number of objects allowed in the node of a quadtree, before the node is divided into subtrees.

Member Function Documentation

IlvGraphic* IlvGrapher::addGhostNode	(	const IlvPoint &	p,
		int	layer = `-1`
	)

Adds an invisible node to the grapher.

Ghost nodes are instances of the IlvGhostGraphic class. They can be used to create "free-end" links, that is links whose extremities do not appear to be connected to a node. You can test whether a link extremity is a "free-end" with the IlvGhostGraphic::IsGhost() method.

Parameters

p	The coordinates of the new node.
layer	The layer on which the ghost node should be added.

Returns: The created ghost node.

virtual void IlvGrapher::addLink	(	IlvLinkImage *	link,
		IlBoolean	redraw = `IlTrue`,
		int	layer = `-1`,
		IlvLinkImage *	afterFrom = `0`,
		IlvLinkImage *	afterTo = `0`
	)

virtual

Adds a link to the grapher.

Adds the IlvLinkImage object link to the grapher. This object is referred to as a link. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. The layer parameter specifies the layer on which this object is added. If layer is -1, the object is added to the topmost layer.
The default is to add this link as the new first link starting from link->getFrom() and ending on link->getTo(). You can specify the position of this link in the starting and ending node using the afterFrom and afterTo parameters. The afterFrom parameter can be set to a pointer to a link of the starting node after which you want this new link to be inserted. The parameter afterTo can be set to a pointer to a link of the ending node after which you want this new link to be inserted. If the parameter is NULL or if the indicated link cannot be located in the corresponding node, the link is inserted as the first link of this node.

Parameters

link	The link to add.
redraw	A Boolean value indicating whether the drawing should be updated.
layer	The manager layer on which the object should be added.
afterFrom	Specifies the position of the new link in the list of links of the starting node.
afterTo	Specifies the position of the new link in the list of links of the ending node.

virtual void IlvGrapher::addNode	(	IlvGraphic *	obj,
		IlBoolean	redraw = `IlTrue`,
		int	layer = `-1`
	)

virtual

Adds a node to the grapher.

Adds the IlvGraphic object obj to the grapher. This object is referred to as a node. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. The layer parameter specifies the layer on which this object is added. If layer is -1, the object is added to the topmost layer.

Parameters

obj	The graphic object to add as a node.
redraw	A Boolean value indicating whether the drawing should be updated.
layer	The manager layer on which the object should be added.

void IlvGrapher::applyLinks	(	IlvGraphic *	node,
		IlvApplyObject	f,
		IlAny	arg,
		IlvLinkType	type,
		IlBoolean	reDraw = `IlTrue`
	)

Applies a function to the links connected to a given node.

Calls the function f on every link of type type connected to the node node with the optional argument arg. This method ensures the stability of the internal structure of the grapher if the function f modifies the geometry of the links. If f does not modify the geometry of the links, it is more efficient to use the IlvGrapher::mapLinks() method.

Parameters

node	The node being considered.
f	The function to call.
arg	An optional argument that is passed to the function f.
type	The type of links being considered.
reDraw	A Boolean value indicating whether the drawing should be updated.

IlBoolean IlvGrapher::areLinksEditable ( ) const

Indicates whether links can be edited interactively.

Returns: IlTrue if links can be edited, and IlFalse otherwise.

See also: setLinksEditable().

virtual void IlvGrapher::changeLink	(	IlvLinkImage *	link,
		IlvLinkImage *	newLink,
		IlBoolean	redraw = `IlFalse`
	)

virtual

Changes the graphic representation of an existing link.

Replaces link by the IlvLinkImage object referred to as newLink. The nodes of link thereby become the extremities of newLink. newLink must not be stored in any manager or container before changeLink() is called. The object link is removed from the grapher, but not destroyed.

Note: This method does nothing if link is a node.

Parameters

link	The link to replace.
newLink	The new link.
redraw	Specify `IlTrue` to have the grapher update the visible result immediately.

virtual void IlvGrapher::changeNode	(	IlvGraphic *	node,
		IlvGraphic *	newNode,
		IlBoolean	redraw = `IlFalse`
	)

virtual

Changes the graphic representation of an existing node.

Replaces node by the IlvGraphic object referred to as newNode. All the incoming and outgoing links of node are attached to newNode. newNode must not be stored in any manager or container before changeNode() is called. The object node is thereby removed from the grapher, but not destroyed.

Note: This method does nothing if node is a link.

Parameters

node	The node to replace.
newNode	The new node.
redraw	Can be set to `IlTrue` to have the grapher update the visible result immediately.

const char* IlvGrapher::getDefaultLinkClass ( ) const

Returns name of the default link class used to create links.

See also: setDefaultLinkClass().

const char* IlvGrapher::getDefaultNodeClass ( ) const

Returns the name of the default graphic class used to create nodes.

See also: setDefaultNodeClass().

static IlvGrapher* IlvGrapher::GetGrapher ( const IlvGraphic * obj )

static

Returns the grapher managing a given graphic object.

Parameters

obj	The considered graphic object.

Returns: The grapher instance in which obj is stored, or 0 if obj is not stored in a grapher.

IlvLinkImage* const* IlvGrapher::getLinks	(	int	layer,
		IlUInt &	count
	)

Returns the links stored in a layer.

Parameters

layer	The index of the layer.
count	Returns the number of links

Returns: An array of pointers to the links stored in the layer of index layer. The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

IlvLinkImage* const* IlvGrapher::getLinks ( IlUInt & count )

Returns all the links stored in the grapher.

Parameters

count Returns the number of links.

Returns: An array of pointers to all the links stored in the grapher. The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

IlvLinkImage* const* IlvGrapher::getLinks	(	const IlvGraphic *	node,
		IlUInt &	count,
		IlvLinkType	type = `IlvLinkAny`
	)		const

Returns the links connected to a node.

Returns an array of IlvLinkImage objects representing the set of links connected to node node. Only the links matching the type type are taken into account. The default value for the type parameter means that all the links connected to node node are returned.

Note: When you want to carry out a given operation on the links of a node, it is usually more efficient to use the IlvGrapher::applyLinks() and IlvGrapher::mapLinks() methods.

Parameters

node	The considered node.
count	The number of returned links.
type	The type of links (incoming or outgoing) that we want to retrieve.

Returns: The connected links. The array is stored in an internal array that must not be deleted or modified.

See also: applyLinks(), mapLinks().

IlUInt IlvGrapher::getLinksCount	(	const IlvGraphic *	node,
		IlvLinkType	type = `IlvLinkAny`
	)		const

Returns the number of links connected to a given node.

The default value for the type parameter means that all the links connected to node node are considered.

Parameters

node	The node being considered.
type	The type of links being considered.

Returns: The number of links of type type that are connected to node node.

IlvGraphic* const* IlvGrapher::getNodes	(	int	layer,
		IlUInt &	count
	)

Returns the nodes stored in a layer.

Parameters

layer	The index of the layer.
count	Returns the number of nodes.

Returns: An array of pointers to the nodes stored in the layer of index layer. The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

IlvGraphic* const* IlvGrapher::getNodes ( IlUInt & count )

Returns all the nodes stored in the grapher.

Parameters

count Returns the number of nodes.

Returns: An array of pointers to all the nodes stored in the grapher. The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

IlBoolean IlvGrapher::isLink ( const IlvGraphic * obj ) const

Indicates whether a given graphic object is a link.

Returns: IlTrue if the object obj is a link or IlFalse if it is not.

See also: addLink(), makeLink().

IlBoolean IlvGrapher::isLinkBetween	(	const IlvGraphic *	from,
		const IlvGraphic *	to
	)		const

Indicates whether there is a link connecting two given nodes.

Returns: IlTrue when there is a link between the IlvGraphic object from and the IlvGraphic object to, or IlFalse when there is no such link.

IlBoolean IlvGrapher::isNode ( const IlvGraphic * obj ) const

Indicates whether a given graphic object is a node.

Returns: IlTrue if the object obj is a node, or IlFalse if it is not.

See also: addNode(), makeNode().

virtual IlvGrapher* IlvGrapher::makeLink ( IlvGraphic * obj )

virtual

Transforms a graphic object into a grapher link.

Creates an IlvLinkHandle instance referencing the object obj and adds it to the grapher. The created handle is owner of obj. Its initial start and end nodes are ghosts (instances of the IlvGhostGraphic class) that are automatically added to the grapher. If the object obj is not stored in the grapher or if it is already a link, this method does nothing.

Parameters

obj	The considered graphic object.

Returns: The current instance.

virtual IlvGrapher* IlvGrapher::makeNode ( IlvGraphic * obj )

virtual

Transforms a graphic object into a grapher node.

After calling this method, the graphic object obj is referred to as a node by the grapher. If the object is not stored in the grapher or if it is already a node, this method does nothing.

Parameters

obj	The considered graphic object.

Returns: The current instance.

void IlvGrapher::mapLinks	(	IlvGraphic *	node,
		IlvApplyObject	f,
		IlAny	arg,
		IlvLinkType	type
	)

Applies a function to the links connected to a given node.

Calls the function f on every link of type type connected to the node node with the optional argument arg. Do not use this method if the function f can modify the geometry of the links. Instead, use the IlvGrapher::applyLinks() method.

Parameters

node	The node being considered.
f	The function to call.
arg	An optional argument that is passed to the function f.
type	The type of links being considered.

IlBoolean IlvGrapher::nodeHasLinks	(	const IlvGraphic *	node,
		IlvLinkType	type = `IlvLinkAny`
	)		const

Indicates whether a given node is connected to links.

The default value for the type parameter means that the method will search for either outgoing or incoming links.

Parameters

node	The node being considered.
type	The type of links being considered.

Returns: IlTrue when links of type type are connected to node node, or IlFalse when there are no such links.

virtual void IlvGrapher::nodeXPretty	(	IlvGraphic *	node,
		IlvPos	xspacing,
		IlvPos	yspacing,
		IlBoolean	redraw = `IlTrue`,
		IlvOrientation	orientation = `IlvCenter`
	)

virtual

Performs a horizontal tree layout of the nodes.

Rearranges nodes in a horizontal tree structure, starting from node. The parameters xspacing and yspacing specify, respectively, the horizontal and vertical space between node images. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. The valid values for orientation are: IlvTop, IlvCenter (compatible with Rogue Wave Views 2.1), and IlvBottom, which provide the following outputs:

Parameters

node	The starting node for the layout.
xspacing	The horizontal spacing between nodes.
yspacing	The vertical spacing between nodes.
redraw	A Boolean value indicating whether the drawing should be updated.
orientation	Specifies the position of the starting node node.

virtual void IlvGrapher::nodeYPretty	(	IlvGraphic *	node,
		IlvPos	xspacing,
		IlvPos	yspacing,
		IlBoolean	redraw = `IlTrue`,
		IlvOrientation	orientation = `IlvCenter`
	)

virtual

Performs a vertical tree layout of the nodes.

Rearranges nodes in a vertical tree structure, starting from node. The xspacing and yspacing parameters specify, respectively, the horizontal and vertical space between node images. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. The valid values for orientation are: IlvLeft, IlvCenter (compatible with Rogue Wave Views 2.1), and IlvRight, which provide the following outputs:

Parameters

node	The starting node for the layout.
xspacing	The horizontal spacing between nodes.
yspacing	The vertical spacing between nodes.
redraw	A Boolean value indicating whether the drawing should be updated.
orientation	Specifies the position of the starting node node.

virtual void IlvGrapher::removeLink	(	IlvLinkImage *	link,
		IlBoolean	redraw = `IlTrue`,
		IlBoolean	destroyIt = `IlTrue`
	)

virtual

Removes a link from the grapher.

Removes the IlvLinkImage object link from the grapher. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. Set destroyIt to IlFalse to prevent the link from being deleted if you want to use it elsewhere.

Parameters

link	The link to remove.
redraw	A Boolean value indicating whether the drawing should be updated.
destroyIt	A Boolean value indicating whether the object should be deleted.

virtual void IlvGrapher::removeNode	(	IlvGraphic *	obj,
		IlBoolean	redraw = `IlTrue`,
		IlBoolean	destroyIt = `IlTrue`
	)

virtual

Removes a node from the grapher.

Removes the object obj from the grapher and all links that start from, or end at, this node. Specify IlFalse for the redraw parameter to prevent the grapher from updating the visible result immediately. Set destroyIt to IlFalse to prevent the node from being deleted if you want to use it elsewhere. All links related to obj are removed and deleted, regardless of destroyIt.

Parameters

obj	The node to remove.
redraw	A Boolean value indicating whether the drawing should be updated.
destroyIt	A Boolean value indicating whether the object should be deleted.

void IlvGrapher::setDefaultLinkClass ( const char * name )

Sets the default link class used to create links.

The default link class is used by the IlvMakeLinkInteractor class to create links when no factory is defined. The name parameter must be the name of a registered IlvLinkImage subclass. For example: "IlvOneLinkImage".

Parameters

name	The name of the link class.

void IlvGrapher::setDefaultNodeClass ( const char * name )

Sets the default graphic class used to create nodes.

The default node class is used by the IlvMakeNodeInteractor class to create nodes when no factory is defined. The name parameter must be the name of a registered IlvGraphic subclass. For example: "IlvRectangle".

Parameters

name	The name of the node class.

void IlvGrapher::setLinksEditable ( IlBoolean editable )

Indicates whether links can be edited interactively.

When editable is equal to IlTrue, interactors such as IlvGraphSelecInteractor can be used to interactively change the way links are connected. The default mode for an IlvGrapher is to set its links as non-editable.

Parameters

editable A Boolean value indicating whether links can be edited interactively.

See also: areLinksEditable().

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation