Wx::Perl::VirtualTreeCtrl - Build a tree control on demand

Wx-Perl-VirtualTreeCtrl documentation Contained in the Wx-Perl-VirtualTreeCtrl distribution.

Index

Code Index:

NAME

Top

Wx::Perl::VirtualTreeCtrl - Build a tree control on demand

DERIVED FROM

Top

    Wx::EvtHandler

Standard Wx::TreeCtrl and Wx::Window methods can be used with a virtual tree control.

SYNOPSIS

Top

    use Wx::Perl::VirtualTreeCtrl 'EVT_POPULATE_TREE_ITEM';

    my $tree = new Wx::Perl::VirtualTreeCtrl($tree_ctrl);
    EVT_POPULATE_TREE_ITEM($self, $tree, \&AddChildren);
    my $root = $tree->AddRoot($name, $data);
    $tree->Expand($root);

    sub AddChildren {
        my ($self, $event) = @_;

        my $tree = $event->GetEventObject;
        my $item = $event->GetItem;
        my $item_data = $tree->GetPlData($item);

        if ($tree->GetChildrenCount($item, 0)) {
            # update existing children ...

            my ($child, $cookie) = $tree->GetFirstChild($item);
            while ($child && $child->IsOk) {
                my $child_data = $tree->GetPlData($child);
                # synchronise deletions
                if (child_was_deleted($child_data)) {
                    $tree->Delete($child);
                }

                ($child, $cookie) = $tree->GetNextChild($child, $cookie);
            }

        } else {
            # add children for the first time

            my @child_data = expensive_process_to_get_children($item_data);
            foreach (@child_data) {
                my $child = $tree->AppendItem($item, $_->{name});
                # make item expandable if it's a folder
                $tree->SetItemHasChildren($child, 1) if ...;
            }
        }
    }

DESCRIPTION

This module implements a tree like the Wx::TreeCtrl except that it populates its items dynamically when nodes in the tree are expanded. You may prefer this control over the standard tree control when you are populating your tree from a remote source such as a database, or when your tree is very large.

This module implements the same interface as a standard Wx::TreeCtrl.

METHODS

new ($parent, $id, $pos = wxDefaultPosition, $size = wxDefaultSize, ...)

Returns a new Wx::Perl::VirtualTreeCtrl object. The parameters are the same as those required by a standard Wx::TreeCtrl.

new ($tree_ctrl)

Returns a Wx::Perl::VirtualTreeCtrl object that uses an existing Wx::TreeCtrl instead of creating its own. You may use this method when your interface is built using Wx::XRC resources or a third-party tool like wxGlade.

GetPath($item)

Returns a list of item labels from the root item down the provided path

GetTree()

Returns a Wx::TreeCtrl suitable for regular wxTreeEvents and Wx::Sizer operations

    # Add a virtual tree to a sizer
    $sizer->Add($vtree->GetTree, 1, wxALL|wxGROW, 4);

    # Attach event listener for tree item activation (e.g. double click)
    EVT_TREE_ITEM_ACTIVATED($win, $vtree->GetTree, \&onActivateItem);

EVENTS

EVT_POPULATE_TREE_ITEM($event_handler, $virtual_tree, \&event_callback)

The item is being expanded and the control is requesting that part of the tree be populated.

Your event callback will be passed the $event_handler and event object, as with other wxCommand events. The event object has the following accessors:

    $event->GetEventObject() # returns the virtual tree control
    $event->GetItem()        # returns the tree item id that is being populated

See the example in "SYNOPSIS".

For further information, see the wxCommandEvent documentation, and the Event handling overview from the wxWidgets documentation.

EVT_TREE_*

Standard wxTreeEvents can be used with a virtual tree control. See "GetTree()" for examples.

SEE ALSO

Wx::TreeCtrl

The standard tree control from which this object is derived.

Wx::Perl::TreeChecker

A tree control with checkboxes that is compatible with this module (you can have a virtual tree checker)

wxWidgets

http://www.wxwidgets.org

wxPerl

http://wxperl.sourceforge.net

AUTHOR

Simon Flack <cpan _at_ bbc _dot_ co _dot_ uk>

COPYRIGHT

Top

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

Wx-Perl-VirtualTreeCtrl documentation Contained in the Wx-Perl-VirtualTreeCtrl distribution. 
#############################################################################
## Name:        Wx::Perl::VirtualTreeCtrl
## Purpose:     TreeCtrl that populates it's children on demand
## Author:      Simon Flack
## Modified by: $Author: andreww $ on $Date: 2006/10/05 14:22:34 $
## Created:     08/10/2002
## RCS-ID:      $Id: VirtualTreeCtrl.pm,v 1.17 2006/10/05 14:22:34 andreww Exp $
#############################################################################

package Wx::Perl::VirtualTreeCtrl;
use strict;
use Exporter;
use Wx;
use Wx::Event 'EVT_TREE_ITEM_EXPANDING';
use Carp;

use vars qw($VERSION @EXPORT_OK @ISA $AUTOLOAD);

@ISA = qw(Wx::EvtHandler Exporter);
@EXPORT_OK = 'EVT_POPULATE_TREE_ITEM';
$VERSION = sprintf'%d.%03d', q$Revision: 1.17 $ =~ /: (\d+)\.(\d+)/;

use constant POPULATE_TREE_ITEM_EVENT => Wx::NewEventType;

sub new {
    my $class = shift;
    my $tree;
    if (@_ == 1) {
        $tree = shift;
        croak "Supplied tree control is not a Wx::TreeCtrl"
            unless ref $tree && $tree->isa('Wx::TreeCtrl');
    } elsif (@_ > 1) {
        $tree = Wx::TreeCtrl->new(@_);
    } else {
        croak "USAGE: $class->new(\$parent, \$id, \$pos, \$size, ...)\n"
            . "or $class->new(\$treectrl)";
    }

    my $self = $class->SUPER::new(); # Wx::EvtHandler
    $self->{_tree_ctrl} = $tree;
    $self->{_tree_ctrl}->PushEventHandler($self);
    return $self;
}

sub EVT_POPULATE_TREE_ITEM ($$$) {
    my ($evt_handler, $self, $callable) = @_;
    my $real_tree = $self->{_tree_ctrl};
    $evt_handler->Connect($real_tree, -1, POPULATE_TREE_ITEM_EVENT, $callable);
    EVT_TREE_ITEM_EXPANDING($self, $real_tree, \&_onExpandItem);
}

# Proxy Wx::TreeCtrl methods to the aggregated tree control
sub AUTOLOAD {
    my $self = shift;
    my ($method) = $AUTOLOAD =~ /.*:(.*)/;
    my $tctl = $self->{_tree_ctrl};
    my $class = ref $tctl;
    croak "Undefined method '$method' in class '$class'"
        unless $tctl->can($method);
    return $tctl->$method(@_);
}

sub AddRoot {
    my $self = shift;
    my $id = $self->GetTree->AddRoot(@_);
    $self->SetItemHasChildren($id, 1);
    return $id;
}

sub GetTree {
    my $self = shift;
    return $self->{_tree_ctrl};
}

sub GetPath {
    my $self = shift;
    my ($item) = @_;

    my @path;
    push @path, $self->{_tree_ctrl}->GetItemText($item);

    my $parent = $self->{_tree_ctrl}->GetItemParent($item);
    while ($parent && $parent->IsOk) {
        push @path, $self->{_tree_ctrl}->GetItemText($parent);
        $parent = $self->{_tree_ctrl}->GetItemParent($parent);
    }
    return reverse @path;
}

# When a Tree item is expanded, trigger a POPULATE_TREE_ITEM_EVENT
sub _onExpandItem {
    my $self = shift;
    my ($event) = @_;

    my $item = $event->GetItem;
    my $populate_evt = $self->_populate_event($item);
    $self->ProcessEvent($populate_evt);

    $event->Skip;
}

sub _populate_event {
    my $self = shift;
    my $item = shift;

    my $event = Wx::Perl::VirtualTreeCtrl::Event->new(
        $self->GetId, POPULATE_TREE_ITEM_EVENT, $item
    );
    $event->SetEventObject($self);

    return $event;
}


############################################################################

package Wx::Perl::VirtualTreeCtrl::Event;

use vars '@ISA';
@ISA = 'Wx::PlCommandEvent';

sub new {
    my $class = shift;
    my ($id, $event_id, $item) = @_;
    my $self = $class->SUPER::new($event_id, $id);
    $self->{_item} = $item;
    return bless $self, $class;
}

# Implement things missing from Wx::PlCommandEvent

sub SetEventObject {
    my $self = shift;
    $self->{_event_object} = shift;
}

sub GetEventObject {
    my $self = shift;
    return $self->{_event_object};
}

sub GetItem {
    my $self = shift;
    return ($self->{_item} || -1);
}

1;