summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Tree.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Tree.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Tree.pod274
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
+