diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Tree.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Tree.pod | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Tree.pod b/Master/tlpkg/tlperl/lib/Tk/Tree.pod new file mode 100644 index 00000000000..445d2f0765b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Tree.pod @@ -0,0 +1,274 @@ + +=head1 NAME + +Tk::Tree - Create and manipulate Tree widgets + +=for pm Tixish/Tree.pm + +=for category Tix Extensions + +=head1 SYNOPSIS + +S< >B<use Tk::Tree;> + +S< >I<$tree> = I<$parent>-E<gt>B<Tree>(?I<options>?); + +=head1 SUPER-CLASS + +The B<Tree> class is derived from the L<HList|Tk::HList> class and inherits all +the methods, options and subwidgets of its super-class. A B<Tree> widget is +not scrolled by default. + +=head1 STANDARD OPTIONS + +B<Tree> supports all the standard options of an HList widget. +See L<Tk::options> for details on the standard options. + +=head1 WIDGET-SPECIFIC OPTIONS + +=over 4 + +=item Name: B<browseCmd> + +=item Class: B<BrowseCmd> + +=item Switch: B<-browsecmd> + +Specifies a L<callback|Tk::callbacks> to call whenever the user browses on an entry +(usually by single-clicking on the entry). The callback is called with +one argument, the pathname of the entry. + +=item Name: B<closeCmd> + +=item Class: B<CloseCmd> + +=item Switch: B<-closecmd> + +Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be closed (See +L<"BINDINGS"> below). This method is called with one argument, +the pathname of the entry. This method should perform appropriate +actions to close the specified entry. If the B<-closecmd> option +is not specified, the default closing action is to hide all child +entries of the specified entry. + +=item Name: B<command> + +=item Class: B<Command> + +=item Switch: B<-command> + +Specifies a L<callback|Tk::callbacks> to call whenever the user activates an entry +(usually by double-clicking on the entry). The callback +is called with one argument, the pathname of the entry. + +=item Name: B<ignoreInvoke> + +=item Class: B<IgnoreInvoke> + +=item Switch: B<-ignoreinvoke> + +A Boolean value that specifies when a branch should be opened or +closed. A branch will always be opened or closed when the user presses +the (+) and (-) indicators. However, when the user invokes a branch +(by doublc-clicking or pressing E<lt>ReturnE<gt>), the branch will be opened +or closed only if B<-ignoreinvoke> is set to false (the default +setting). + +=item Name: B<openCmd> + +=item Class: B<OpenCmd> + +=item Switch: B<-opencmd> + +Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be opened (See +L<"BINDINGS"> below). This method is called with one argument, +the pathname of the entry. This method should perform appropriate +actions to open the specified entry. If the B<-opencmd> option +is not specified, the default opening action is to show all the child +entries of the specified entry. + +=back + +=head1 DESCRIPTION + +The B<Tree> method creates a new window and makes it into a Tree widget +and return a reference to it. Additional options, described above, may +be specified on the command line or in the option database to configure +aspects of the Tree widget such as its cursor and relief. + +The Tree widget can be used to display hierarchical data in a tree +form. The user can adjust the view of the tree by opening or closing +parts of the tree. + +To display a static tree structure, you can add the entries into the +Tree widget and hide any entries as desired. Then you can call +the B<autosetmode> method. This will set up the Tree widget so that it +handles all the I<open> and I<close> events automatically. +the demonstration program F<Tixish/examples/perl-tix-tree>). + +The above method is not applicable if you want to maintain a dynamic tree +structure, i.e, you do not know all the entries in the tree and you need +to add or delete entries subsequently. To do this, you should first create +the entries in the Tree widget. Then, use the B<setmode> method to +indicate the entries that can be opened or closed, and use the B<-opencmd> +and B<-closecmd> options to handle the opening and closing events. (Please +see the demonstration program F<Tixish/examples/perl-tix-dyntree>). + +Use either + +S< >I<$parent>-E<gt>B<Scrolled>(B<'Tree'>, ... ); + +or + +S< >I<$parent>-E<gt>B<ScrlTree>( ... ); + +to create a scrolled B<Tree>. See L<Tk::Scrolled> for details. + +=head1 WIDGET METHODS + +The B<Tree> method creates a widget object. +This object supports the B<configure> and B<cget> methods +described in L<Tk::options> which can be used to enquire and +modify the options described above. +The widget also inherits all the methods provided by the generic +L<Tk::Widget|Tk::Widget> class. + +The following additional methods are available for Tree widgets: + +=over 4 + +=item I<$tree-E<gt>>B<add_pathimage>(I<treeRegExp [, openImg, closeImg]>) + +This method defines images for a given path (images must be in xpm +format). The path can be determined by a simplified regular +expression. There are just three metasymbols: + +=over + +=item ^ + +at the beginning of the C<treeRegExp> same as in Perl regular +expressions + +=item * + +anything + +=item $ + +at the end of the C<TreeRegExp>, the same as in Perl regular +expressions + +=back + +Examples: + + $tree->add_pathimage('^root','openfolder','folder'); + +matches C<root>, C<root.foo>, C<root.bar>, but not C<foo.root> + + $tree->add_pathimage('root.*.class','openfolder','folder'); + +matches all paths containing C<< root.<anything>.class >>, but not +C<< root.<anything>.<anything>.class >> C<*> is one part of the path. If +you want to use a wildcard for two steps, you have to use C<*.*>. + + $tree->add_pathimage('class$','openfolder','folder'); + +This matches all path with C<class> at the end. + +=item I<$tree>-E<gt>B<autosetmode> + +This method calls the B<setmode> method for all the entries in +this Tree widget: if an entry has no child entries, its mode is set to +B<none>. Otherwise, if the entry has any hidden child entries, its +mode is set to B<open>; otherwise its mode is set to B<close>. + +=item I<$tree-E<gt>>B<child_entries>([$path][,$depth]) + +This method returns in list context an array that contains all +pathnames of subentries within the given path. In scalar context it +returns the number of subentries in the given path. + + Example: + root + | foo + | bar + | | bar1 + | | bar2 + + my @childentries = $tree->child_entries('root.bar'); + # returns (root.bar.bar1, root.bar.bar2) + + my $nr_of_subentries = $tree->child_entries('root',2); + # returns 4 + +If C<$path> is omitted, all it is assumed, that the entry above +'root' is meant. C<$depth> defines the numbers of levels. + +=item I<$tree>-E<gt>B<close>(I<entryPath>) + +Close the entry given by I<entryPath> if its I<mode> is B<close>. + +=item I<$tree>-E<gt>B<getmode>(I<entryPath>) + +Returns the current I<mode> of the entry given by I<entryPath>. + +=item I<$tree>-E<gt>B<open>(I<entryPath>) + +Open the entry given by I<entryPath> if its I<mode> is B<open>. + +=item I<$tree>-E<gt>B<setmode>(I<entryPath, mode>) + +This method is used to indicate whether the entry given by +I<entryPath> has children entries and whether the children are +visible. I<mode> must be one of B<open>, +B<close> or B<none>. If I<mode> is set to B<open>, a (+) +indicator is drawn next to the entry. If I<mode> is set to +B<close>, a (-) indicator is drawn next to the entry. If +I<mode> is set to B<none>, no indicators will be drawn for this +entry. The default I<mode> is none. The B<open> mode indicates +the entry has hidden children and this entry can be opened by the +user. The B<close> mode indicates that all the children of the entry +are now visible and the entry can be closed by the user. + +=back + +=head1 BINDINGS + +The basic mouse and keyboard bindings of the Tree widget are the same +as the L<bindings of the HList|Tk::HList/"BINDINGS"> widget. +In addition, the entries can be opened or closed under the following +conditions: + +=over 4 + +=item [1] + +If the I<mode> of the entry is B<open>, it can be opened by clicking +on its (+) indicator. + +=item [2] + +If the I<mode> of the entry is B<close>, it can be closed by clicking +on its (-) indicator. + +=back + +=head1 SEE ALSO + +L<Tk::HList|Tk::HList> + +=head1 AUTHOR + +Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix +version by Ioi Kim Lam. + +Additions by Renee Baecker <module@renee-baecker.de> + +=head1 ACKNOWLEDGEMENTS + +Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help. + +=cut + |