NAME

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

DERIVED FROM

    Wx::EvtHandler

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

SYNOPSIS

    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

(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