Solstice::Tree - A basic tree object.

  use Tree;

  my $tree = new Tree;

  my $child1 = new Tree;

  $tree->addChild($child1);
  $count = $tree->getChildCount();
  my @children = $tree->getChildren();
  my $child = $tree->getChild(0);

  my $parent = $tree->getParent();

  my $child2 = new Tree;
  $tree->addChild($child2);
  $tree->removeChild(1);

  my $boolean = $tree->isRoot();
  my $boolean = $tree->isLeaf();

  my $uniquelabelstring = $tree->getLabel();

  $child1->setValue("sample text");
  $child2->setValue(\$objectref);

  $tree->setValue("root");

  $tree->destroy();

package Solstice::Tree;

# $Id: Tree.pm 2412 2005-07-28 16:28:57Z mcrawfor $

use 5.006_000;
use strict;
use warnings;

use base qw(Solstice);

use Solstice::List;

use constant TRUE  => 1;
use constant FALSE => 0;

our ($VERSION) = ('$Revision: 2412 $' =~ /^\$Revision:\s*([\d.]*)/);

sub new {
    my $class = shift;
    my $self = $class->SUPER::new();
    
    $self->{'_parent'} = undef;
    $self->{'_children'} = Solstice::List->new();
    $self->{'_position'} = 0;

    return $self;
}

sub getParent {
    my $self = shift;
    return defined $self->{'_parent'} ? $self->{'_parent'} : $self;
}

sub getChildren {
    my $self = shift;
    
    # This is to ensure that during global destruction 
    # we don't get errors if things are destroyed out 
    # of order.
    if (defined $self->{'_children'}) {
        return @{$self->{'_children'}->getAll()};
    }
    return ();
}

sub iterator {
    my $self = shift;
    if (defined $self->{'_children'}) {
        return $self->{'_children'}->iterator();
    }
}

sub childExists {
    my $self     = shift;
    my $position = shift;

    return $self->{'_children'}->exists($position);
}

sub addChild {
    my $self = shift;
    my ($child, $position) = @_;
    
    if (!defined $child) {
        $self->warn('addChild(): Child is undefined');
        return FALSE;
    }

    if (!$self->isValidObject($child, 'Solstice::Tree')) {
        $self->warn('addChild(): Child is not a Solstice::Tree');
        return FALSE;
    }

    if (defined $position) {
        $self->{'_children'}->add($position, $child);
        
        for my $i ($position + 1 .. $self->{'_children'}->size() - 1) {
            my $current = $self->getChild($i);
            $current->{'_position'}++;
        }
    } else {
        $self->{'_children'}->push($child);
        $position = $self->{'_children'}->size() - 1;
    }
    $child->_setParent($self, $position);
    
    return TRUE;
}

sub removeChild {
    my $self = shift;
    my ($position, $return) = @_;

    return FALSE unless $self->childExists($position);
    
    my $child = $self->getChild($position);
    
    # Remove the child from the list, and decriment the position 
    # of any children after it in the list.
    $self->{'_children'}->remove($position);
    for my $i ($position .. $self->{'_children'}->size() - 1) {
        my $current = $self->getChild($i);
        $current->{'_position'}--;
    }
    
    if ($return) {
        $child->_setParent($child, 0);
        return $child;
    }
    $child->destroy();
    
    return TRUE;
}

sub addChildren {
    my $self = shift;
    my $list = shift;
    
    return FALSE unless defined $list;

    if ($self->isValidObject($list, 'Solstice::List')) {
        $list = $list->getAll();
    } else {
        return FALSE unless $self->isValidArrayRef($list);
    }

    for my $item (@$list) {
        $self->addChild($item);
    }
    
    return TRUE;
}

sub removeChildren {
    my $self = shift;
    
    $self->{'_children'}->clear();
    
    return TRUE;
}

sub moveChild {
    my $self = shift;
    my ($oldposition, $newposition) = @_;

    return FALSE unless ($self->childExists($oldposition) and $self->childExists($newposition));
    return TRUE if ($oldposition == $newposition);

    if ($oldposition < $newposition) {
        for my $i ($oldposition .. $newposition) {
            $self->getChild($i)->{'_position'}--;
        }
    } else {
        for my $i ($newposition .. $oldposition - 1) {
            $self->getChild($i)->{'_position'}++;
        }
    }
    $self->getChild($oldposition)->{'_position'} = $newposition;
    
    $self->{'_children'}->move($oldposition, $newposition);

    return TRUE;
}

sub destroy {
    my $self = shift;
    
    if (defined $self->{'_children'}) {
        # In case things get destroyed out of order.
        for my $child (@{$self->{'_children'}->getAll()}) {
            if (defined $child) {
                $child->destroy();
            }
        }
        $self->{'_children'}->clear();
    }
    $self->{'_parent'} = undef;
    $self = undef;
    
    return TRUE;
}

sub getChildCount {
    my $self = shift;
    return $self->{'_children'}->size();
}

sub getTotalChildCount {
    my $self = shift;
    
    return 0 if $self->isLeaf();
    
    my $count = 0;
    foreach my $child ($self->getChildren()) {
        $count += $child->getTotalChildCount();
        $count++;
    }
    return $count;
}

sub getChild {
    my $self     = shift;
    my $position = shift;
    return $self->{'_children'}->get($position);
}

sub getPosition {
    my $self = shift;
    return $self->{'_position'};
}

sub getRoot {
    my $self = shift;
    return $self if $self->isRoot();
    return $self->getParent()->getRoot();
}

sub isRoot {
    my $self = shift;
    return ($self == $self->getParent());
}

sub isLeaf {
    my $self = shift;
    return !$self->{'_children'}->size();
}

sub isFirstChild {
    my $self = shift;
    return ($self->{'_position'} == 0);
}

sub isLastChild {
    my $self = shift;
    return TRUE if $self->isRoot();
    return ($self->{'_position'} == ($self->getParent()->getChildCount() - 1));
}

sub getLabel {
    my $self = shift;
    return '1' if $self->isRoot();
    return $self->getParent()->getLabel().'_'.$self->{'_position'};
}

sub setValue {
    my $self  = shift;
    $self->{'_value'} = shift;
}

sub getValue {
    my $self = shift;
    return $self->{'_value'};
}

sub _setParent {
    my $self = shift;
    my ($parent, $position) = @_;

    $self->{'_parent'} = $parent;
    $self->{'_position'} = $position;
}

sub DESTROY {
    my $self = shift;
    $self->destroy();
}


1;

__END__