NAME

Wx::Perl::TreeChecker - Tree Control with checkbox functionality

SYNOPSIS

use Wx::Perl::TreeChecker;
my $tree = new Wx::Perl::TreeChecker( ... );
$tree -> allow_multiple(0);
$tree -> items_only(1);
# use tree like a normal treectrl

my $tree = new Wx::TreeCtrl();
Wx::Perl::TreeChecker->Convert($tree, $options)

my @selection = $tree->GetSelection();

DESCRIPTION

Wx::Perl::TreeChecker is a tree control with check boxes so users can select parts of the tree.

A typical use would be a file-selector for backup / archive.

EXPORTS

Exports TC_SELECTED and TC_PART_SELECTED which correspond to the status returned by

$tree -> IsSelected($item)

TC_SEL_FULL and TC_SEL_COMPACT are also exported. See "GetSelection(STYLE)" for more information.

You can export these constants with the ':status' import tag:

use Wx::Perl::TreeChecker ':status';

METHODS

The methods listed here are only where there are syntactic differences to Wx::TreeCtrl

new (@std_args, \%treechecker)

Where @std_args are the regular arguments that you would pass to Wx::TreeCtrl->new().

%treechecker is an optional hash of options that customise the way that Wx::Perl::TreeChecker behaves. Valid keys:

allow_multiple      # can multiple selections be made (default: TRUE)
containers_only     # user can only select containers (default: FALSE)
items_only          # user can only select items      (default: FALSE)
no_recurse          # no recursion when user selects node (default: FALSE)
image_list          # Wx::ImageList to use for checkbox icons
                    #     (default provided)

Convert (Wx::TreeCtrl, HASHREF)

Converts a standard Wx::TreeCtrl into a Wx::Perl::TreeChecker

The first argument is a Wx::TreeCtrl. The seconds argument is an optional hashref as new().

AddRoot ($text, $data)

Add a root to the control. Returns root id.

As Wx::TextCtrl::AddRoot, but image indices are removed

AppendItem ($parent, $text, $data)

Add an item to the control as the last child of $parent. Returns item id.

As Wx::TextCtrl::AppendItem, but image indices are removed

AppendContainer ($parent, $text, $data)

Add a container to the control as the last child of $parent. This does the same as AppendItem() but marks the node as a container.

PrependItem ($parent, $text, $data)

Add an item to the control as the first child of $parent. Returns item id.

PrependContainer ($parent, $text, $data)

Add a container to the control as the first child of $parent.

InsertItem ($parent, $before | $previous, $text, $data)

Inserts an item after a given one (previous) or before one identified by its position (before).

InsertContainer ($parent, $before | $previous, $text, $data)

See InsertItem().

GetSelection(STYLE)

Returns a list of selected Wx::TreeItemIds. The behaviour can be controlled by the STYLE and the behaviour of the object (containers_only, no_recurse, etc).

Allowed styles are;

TC_SEL_FULL

The default if GetSelection is called without a STYLE. It returns all tree items that are checked (TC_SELECTED and TC_PART_SELECTED)

TC_SEL_COMPACT

This returns a compact list. If a Container item is TC_SELECTED, it will be returned in place of it's child items. Containers that are TC_PART_SELECTED are not returned.

IsSelected ($item)

returns the selection status of the item. See Exported flags.

IsContainer ($item)

returns TRUE if the item is a container

SelectItem ($item)

Select the item, returns TRUE if the item was selected.

UnSelectItem ($item)

Clear the selction of the item

UnselectAll()

Clear the selections on the tree

allow_multiple (BOOL)

see new()

containers_only (BOOL)

see new()

items_only (BOOL)

see new()

no_recurse (BOOL)

see new()

XRC

See Wx::Perl::TreeChecker::XmlHandler

CHECKBOX IMAGES

A default set of checkbox icons are included. You can override these by supplying a Wx::ImageList to the constructor or the SetImageList method.

std_icons()

This class method returns the three standard icons that you can mix with your own icons.

my ($empty, $ticked, $part_selected) = Wx::Perl::TreeChecker->std_icons();

The Image list must contain 8 icons, 16 x 16 pixels:

Image number             Image description
------------------------------------------------------------------------
    0                    The root icon
    1                    Selected root icon
    2                    Part-selected root icon
    3                    Container icon
    4                    Selected container icon
    5                    Part-selected container icon
    6                    Item icon
    7                    Selected item icon

EXAMPLES

See demo/treechecker.pl

AUTHOR

Simon Flack <simonflk _AT_ cpan.org>

BUGS

I can squash more bugs with your help. Please let me know if you spot something that doesn't work as expected.

You can report bugs via the CPAN RT: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Wx-Perl-TreeChecker

If possible, please provide a diff against the test files or sample script that demonstrates the bug(s).

SEE ALSO

wxWindows: wxTreeCtrl

wxPerl http://wxperl.sourceforge.net

COPYRIGHT

Copyright (c) 2003, 2004, 2005 Simon Flack <simonflk _AT_ cpan.org>. All rights reserved

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

cpanm Wx::Perl::TreeChecker

perl -MCPAN -e shell
install Wx::Perl::TreeChecker