/ 
graph-modules-1.001
/ Graph::Element

NAME

Graph::Element - base class for elements of a directed graph

SYNOPSIS

$object->setAttribute('ATTR_NAME', $value);
$value = $object->getAttribute('ATTR_NAME');

DESCRIPTION

The Graph::Element module implements the base class for elements of a directed graph. It is subclassed by the Graph::Node and Graph::Edge modules. This module provides a constructor, and attribute setting mechanisms.

If you want to inherit this class, see the section below, INHERITING THIS CLASS.

CONSTRUCTOR

$edge = new Graph::Element( . . . );

This creates a new instance of the Graph::Element object class, which is the base class for Graph::Node and Graph::Edge.

You can set attributes of new object by passing arguments to the constructor.

   $element = new Graph::Element('ATTR1'  => $value1,
		         	 'ATTR2'  => $value2
			        );

If you not set the ID attribute at creation time a unique value will be automatically assigned.

METHODS

This module provide three methods, described in separate sections below:

  • setAttribute(), which is used to change the value of one or more attribute.

  • getAttribute(), which is used to get the value of exactly one attribute.

  • addAttributeCallback(), which is used to associate a function with a particular object. The function is then invoked whenever the attribute's is changed.

setAttribute - change an attribute of an object

$object->setAttribute('ATTR_A' => $valueA,
                      'ATTR_B' => $valueB);

This method is used to set user-defined attributes on an object. These are different from the standard attributes, such as ID and LABEL.

getAttribute - query the value of a object's attribute

$value = $object->getAttribute('ATTRIBUTE_NAME');

This method is used to get the value of a single attribute defined on an object. If the attribute name given has not been previously set on the object, undef is returned.

addAttributeCallback - add an attribute callback to object

$object->addAttributeCallback('ATTR_NAME', \&callback_function);

sub callback_function
{
    my $self       = shift;
    my $attr_name  = shift;       # name of attribute which changed
    my $attr_value = shift;       # new value of attribute

    # do some stuff here
}

This is used to add a callback function to an object, associated with a particular attribute. Whenever the attribute is changed, the callback function is invoked, with the attribute name and new value passed as arguments.

VIRTUAL METHODS FOR ACCESSING ATTRIBUTES

In addition to the getAttribute and setAttribute methods, this class also supports virtual methods for accessing attributes.

For example, if you have set an attribute FOOBAR, then you can call method foobar() on the object:

$object->setAttribute('FOOBAR', $value);
$value = $object->foobar;

This capability assumes that all attribute names will be in UPPER CASE; the resulting method names will be all lower case.

This feature is particularly useful for manipulating the ID, LABEL, FROM, and TO attributes:

$node->label('label for my node');
$id = $node->id;
$edge-to($node);

NOTE: this feature won't work if you use an attribute name which is the same as an existing method for your object class, such as new, or DESTROY.

INHERITING THIS CLASS

If you want to provide attribute methods for your class, you just need the following lines in your module:

use Graph::Element;
@ISA = qw(Graph::Element);

This will give your objects the getAttribute(), setAttribute(), and addAttributeCallback() methods.

When subclassing Graph::Element you shouldn't need to over-ride the constructor (new()), but should be able to get away with over-riding the initialise() function.

RESTRICTIONS

This class assumes that the object instance for your class is a blessed hash (associative array) reference.

SEE ALSO

Graph::Node

for a description of the Node class.

Graph::Edge

for a description of the Edge class.

AUTHOR

Neil Bowers <neilb@cre.canon.co.uk>

COPYRIGHT

Copyright (c) 1997 Canon Research Centre Europe. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.