Graph::Easy::Node(3)

NAME
Graph::Easy::Node - Represents a node in a Graph::Easy graph

SYNOPSIS
        use Graph::Easy::Node;

        my $bonn = Graph::Easy::Node->new('Bonn');

        $bonn->set_attribute('border', 'solid 1px black');

        my $berlin = Graph::Easy::Node->new( name => 'Berlin' );

DESCRIPTION
A "Graph::Easy::Node" represents a node in a simple graph. Each node has contents (a text, an image or another graph), and dimension plus an origin. The origin is typically determined by a graph layouter module like Graph::Easy.

METHODS
Apart from the methods of the base class Graph::Easy::Base, a "Graph::Easy::Node" has the following methods:

  new()
        my $node = Graph::Easy::Node->new( name => 'node name' );
        my $node = Graph::Easy::Node->new( 'node name' );

Creates a new node. If you want to add the node to a Graph::Easy object, then please use the following to create the node object:

        my $node = $graph->add_node('Node name');

You can then use "$node->set_attribute();" or "$node->set_attributes();" to set the new Node's attributes.

  as_ascii()
        my $ascii = $node->as_ascii();

Return the node as a little box drawn in ASCII art as a string.

  as_txt()
        my $txt = $node->as_txt();

Return the node in simple txt format, including attributes.

  as_svg()
        my $svg = $node->as_svg();

Returns the node as Scalable Vector Graphic. The actual code for that routine is defined Graph::Easy::As_svg.pm.

  as_graphviz()
For internal use mostly - use at your own risk.

        my $txt = $node->as_graphviz();

Returns the node as graphviz compatible text which can be fed to dot etc to create images.

One needs to load Graph::Easy::As_graphviz first before this method can be called.

  as_graphviz_txt()
For internal use mostly - use at your own risk.

        my $txt = $node->as_graphviz_txt();

Return only the node itself (without attributes) as a graphviz representation.

One needs to load Graph::Easy::As_graphviz first before this method can be called.

  as_pure_txt()
        my $txt = $node->as_pure_txt();

Return the node in simple txt format, without the attributes.

  text_styles_as_css()
        my $styles = $graph->text_styles_as_css();      # or $edge->...() etc.

Return the text styles as a chunk of CSS styling that can be embedded into a " style="" " parameter.

  as_html()
        my $html = $node->as_html();

Return the node as HTML code.

  attribute(), get_attribute()
        $node->attribute('border-style');

Returns the respective attribute of the node or undef if it was not set. If there is a default attribute for all nodes of the specific class the node is in, then this will be returned.

  get_attributes()
        my $att = $object->get_attributes();

Return all effective attributes on this object (graph/node/group/edge) as an anonymous hash ref. This respects inheritance and default values.

Note that this does not include custom attributes.

See also get_custom_attributes and raw_attributes().

  get_custom_attributes()
        my $att = $object->get_custom_attributes();

Return all the custom attributes on this object (graph/node/group/edge) as an anonymous hash ref.

  custom_attributes()
    my $att = $object->custom_attributes();

"custom_attributes()" is an alias for get_custom_attributes.

  raw_attributes()
        my $att = $object->get_attributes();

Return all set attributes on this object (graph/node/group/edge) as an anonymous hash ref. This respects inheritance, but does not include default values for unset attributes.

See also get_attributes().

  default_attribute()
        my $def = $graph->default_attribute($class, 'fill');

Returns the default value for the given attribute in the class of the object.

The default attribute is the value that will be used if the attribute on the object itself, as well as the attribute on the class is unset.

To find out what attribute is on the class, use the three-arg form of attribute on the graph:

        my $g = Graph::Easy->new();
        my $node = $g->add_node('Berlin');

        print $node->attribute('fill'), "\n";           # print "white"
        print $node->default_attribute('fill'), "\n";   # print "white"
        print $g->attribute('node','fill'), "\n";       # print "white"

        $g->set_attribute('node','fill','red');         # class is "red"
        $node->set_attribute('fill','green');           # this object is "green"

        print $node->attribute('fill'), "\n";           # print "green"
        print $node->default_attribute('fill'), "\n";   # print "white"
        print $g->attribute('node','fill'), "\n";       # print "red"

See also raw_attribute().

  attributes_as_txt
        my $txt = $node->attributes_as_txt();

Return the attributes of this node as text description. This is used by the "$graph->as_txt()" code and there should be no reason to use this function on your own.

  set_attribute()
        $node->set_attribute('border-style', 'none');

Sets the specified attribute of this (and only this!) node to the specified value.

  del_attribute()
        $node->del_attribute('border-style');

Deletes the specified attribute of this (and only this!) node.

  set_attributes()
        $node->set_attributes( $hash );

Sets all attributes specified in $hash as key => value pairs in this (and only this!) node.

  border_attribute()
        my $border = $node->border_attribute();

Assembles the "border-width", "border-color" and "border-style" attributes into a string like "solid 1px red".

  color_attribute()
        # returns f.i. #ff0000
        my $color = $node->get_color_attribute( 'fill' );

Just like get_attribute(), but only for colors, and returns them as hex, using the current colorscheme.

  get_color_attribute()
Is an alias for color_attribute().

  raw_attribute(), get_raw_attribute()
        my $value = $object->raw_attribute( $name );

Return the value of attribute $name from the object it this method is called on (graph, node, edge, group etc.). If the attribute is not set on the object itself, returns undef.

This method respects inheritance, so an attribute value of 'inherit' on an object will make the method return the inherited value:

        my $g = Graph::Easy->new();
        my $n = $g->add_node('A');

        $g->set_attribute('color','red');

        print $n->raw_attribute('color');               # undef
        $n->set_attribute('color','inherit');
        print $n->raw_attribute('color');               # 'red'

See also attribute().

  raw_color_attribute()
        # returns f.i. #ff0000
        my $color = $graph->raw_color_attribute('color' );

Just like raw_attribute(), but only for colors, and returns them as hex, using the current colorscheme.

If the attribute is not set on the object, returns "undef".

  text_styles()
        my $styles = $node->text_styles();
        if ($styles->{'italic'})
          {
          print 'is italic\n';
          }

Return a hash with the given text-style properties, aka 'underline', 'bold' etc.

  find_grandparent()
        my $grandpa = $node->find_grandparent();

For a node that has no origin (is not relative to another), returns $node. For all others, follows the chain of origin back until a node without a parent is found and returns this node. This code assumes there are no loops, which "origin()" prevents from happening.

  name()
        my $name = $node->name();

Return the name of the node. In a graph, each node has a unique name, which, unless a node label is set, will be displayed when rendering the graph.

  label()
        my $label = $node->label();
        my $label = $node->label(1);            # raw

Return the label of the node. If no label was set, returns the "name" of the node.

If the optional parameter is true, then the label will returned 'raw', that is any potential escape of the form "\N", "\E", "\G", "\T" or "\H" will not be left alone and not be replaced.

  background()
        my $bg = $node->background();

Returns the background color. This method honours group membership and inheritance.

  quoted_comment()
        my $cmt = $node->comment();

Comment of this object, quoted suitable as to be embedded into HTML/SVG. Returns the empty string if this object doesn't have a comment set.

  title()
        my $title = $node->title();
        my $title = $node->title(1);            # raw

Returns a potential title that can be used for mouse-over effects. If no title was set (or autogenerated), will return an empty string.

If the optional parameter is true, then the title will returned 'raw', that is any potential escape of the form "\N", "\E", "\G", "\T" or "\H" will be left alone and not be replaced.

  link()
        my $link = $node->link();
        my $link = $node->link(1);              # raw

Returns the URL, build from the "linkbase" and "link" (or "autolink") attributes. If the node has no link associated with it, return an empty string.

If the optional parameter is true, then the link will returned 'raw', that is any potential escape of the form "\N", "\E", "\G", "\T" or "\H" will not be left alone and not be replaced.

  dimensions()
        my ($w,$h) = $node->dimensions();

Returns the dimensions of the node/cell derived from the label (or name) in characters. Assumes the label/name has literal '\n' replaced by "\n".

  size()
        my ($cx,$cy) = $node->size();

Returns the node size in cells.

  contents()
        my $contents = $node->contents();

For nested nodes, returns the contents of the node.

  width()
        my $width = $node->width();

Returns the width of the node. This is a unitless number.

  height()
        my $height = $node->height();

Returns the height of the node. This is a unitless number.

  columns()
        my $cols = $node->columns();

Returns the number of columns (in cells) that this node occupies.

  rows()
        my $cols = $node->rows();

Returns the number of rows (in cells) that this node occupies.

  is_multicelled()
        if ($node->is_multicelled())
          {
          ...
          }

Returns true if the node consists of more than one cell. See als rows() and cols().

  is_anon()
        if ($node->is_anon())
          {
          ...
          }

Returns true if the node is an anonymous node. False for "Graph::Easy::Node" objects, and true for "Graph::Easy::Node::Anon".

  pos()
        my ($x,$y) = $node->pos();

Returns the position of the node. Initially, this is undef, and will be set from Graph::Easy::layout(). Only valid during the layout phase.

  offset()
        my ($dx,$dy) = $node->offset();

Returns the position of the node relativ to the origin. Returns "(0,0)" if the origin node was not sset.

  x()
        my $x = $node->x();

Returns the X position of the node. Initially, this is undef, and will be set from Graph::Easy::layout(). Only valid during the layout phase.

  y()
        my $y = $node->y();

Returns the Y position of the node. Initially, this is undef, and will be set from Graph::Easy::layout(). Only valid during the layout phase.

  id()
        my $id = $node->id();

Returns the node's unique, internal ID number.

  connections()
        my $cnt = $node->connections();

Returns the count of incoming and outgoing connections of this node. Self-loops count as two connections, so in the following example, node "N" has four connections, but only three edges:

                    +--+
                    v  |
        +---+     +------+     +---+
        | 1 | --> |  N   | --> | 2 |
        +---+     +------+     +---+

See also edges().

  edges()
        my $edges = $node->edges();

Returns a list of all the edges (as Graph::Easy::Edge objects) at this node, in no particular order.

  predecessors()
        my @pre = $node->predecessors();

Returns all nodes (as objects) that link to us.

  has_predecessors()
        if ($node->has_predecessors())
          {
          ...
          }

Returns true if the node has one or more predecessors. Will return true for nodes with selfloops.

  successors()
        my @suc = $node->successors();

Returns all nodes (as objects) that we are linking to.

  sorted_successors()
        my @suc = $node->sorted_successors();

Return successors of the node sorted by their chain value (e.g. successors with more successors first).

  has_as_successor()
        if ($node->has_as_successor($other))
          {
          ...
          }

Returns true if $other ( a node or group) is a successor of node, that is if there is an edge leading from node to $other.

  has_as_predecessor()
        if ($node->has_as_predecessor($other))
          {
          ...
          }

Returns true if the node has $other (a group or node) as predecessor, that is if there is an edge leading from $other to node.

  edges_to()
        my @edges = $node->edges_to($other_node);

Returns all the edges (as objects) that start at $node and go to $other_node.

  shared_edges()
        my @edges = $node->shared_edges();

Return a list of all edges starting/ending at this node, that share a port with another edge.

  nodes_sharing_start()
        my @nodes = $node->nodes_sharing_start($side, $port);

Return a list of unique nodes that share a start point with an edge from this node, on the specified side (absolute) and port number.

  nodes_sharing_end()
        my @nodes = $node->nodes_sharing_end($side, $port);

Return a list of unique nodes that share an end point with an edge from this node, on the specified side (absolute) and port number.

  edges_at_port()
        my @edges = $node->edges_to('start', 'south', '0');

Returns all the edge objects that share the same "start" or "end" port at the specified side and port number. The side must be one of "south", "north", "west" or "east". The port number must be positive.

  incoming()
        my @edges = $node->incoming();

Return all edges that end at this node.

  outgoing()
        my @edges = $node->outgoing();

Return all edges that start at this node.

  add_to_group()
        $node->add_to_group( $group );

Put the node into this group.

  group()
        my $group = $node->group();

Return the group this node belongs to, or undef.

  parent()
        my $parent = $node->parent();

Returns the parent object of the node, which is either the group the node belongs to, or the graph.

  origin()
        my $origin_node = $node->origin();

Returns the node this node is relativ to, or undef otherwise.

  relative_to()
        $node->relative_to($parent, $dx, $dy);

Sets itself relativ to $parent with the offset "$dx,$dy".

  shape()
        my $shape = $node->shape();

Returns the shape of the node as string, defaulting to 'rect'.

  angle()
        my $angle = $self->rotation();

Return the node's rotation, based on the "rotate" attribute, and in case this is relative, on the node's flow.

  flow()
        my $flow = $node->flow();

Returns the outgoing flow for this node as absolute direction in degrees.

The value is computed from the incoming flow (or the general flow as default) and the flow attribute of this node.

  _extra_params()
        my $extra_params = $node->_extra_params();

The return value of that method is added as extra params to the HTML tag for a node when as_html() is called. Returns the empty string by default, and can be overridden in subclasses. See also use_class().

Overridden method should return a text with a leading space, or the empty string.

Example:

        package Graph::Easy::MyNode;
        use base qw/Graph::Easy::Node/;

        sub _extra_params
          {
          my $self = shift;

          ' ' . 'onmouseover="alert(\'' . $self->name() . '\');"';
          }

        1;

EXPORT
None by default.

SEE ALSO
Graph::Easy.

AUTHOR
Copyright (C) 2004 - 2007 by Tels <http://bloodgate.com>.

See the LICENSE file for more details.