| 1 | |
| 2 | =head1 NAME |
| 3 | |
| 4 | Tk::Tree - Create and manipulate Tree widgets |
| 5 | |
| 6 | =for pm Tixish/Tree.pm |
| 7 | |
| 8 | =for category Tix Extensions |
| 9 | |
| 10 | =head1 SYNOPSIS |
| 11 | |
| 12 | S< >B<use Tk::Tree;> |
| 13 | |
| 14 | S< >I<$tree> = I<$parent>-E<gt>B<Tree>(?I<options>?); |
| 15 | |
| 16 | =head1 SUPER-CLASS |
| 17 | |
| 18 | The B<Tree> class is derived from the L<HList|Tk::HList> class and inherits all |
| 19 | the methods, options and subwidgets of its super-class. A B<Tree> widget is |
| 20 | not scrolled by default. |
| 21 | |
| 22 | =head1 STANDARD OPTIONS |
| 23 | |
| 24 | B<Tree> supports all the standard options of an HList widget. |
| 25 | See L<Tk::options> for details on the standard options. |
| 26 | |
| 27 | =head1 WIDGET-SPECIFIC OPTIONS |
| 28 | |
| 29 | =over 4 |
| 30 | |
| 31 | =item Name: B<browseCmd> |
| 32 | |
| 33 | =item Class: B<BrowseCmd> |
| 34 | |
| 35 | =item Switch: B<-browsecmd> |
| 36 | |
| 37 | Specifies a L<callback|Tk::callbacks> to call whenever the user browses on an entry |
| 38 | (usually by single-clicking on the entry). The callback is called with |
| 39 | one argument, the pathname of the entry. |
| 40 | |
| 41 | =item Name: B<closeCmd> |
| 42 | |
| 43 | =item Class: B<CloseCmd> |
| 44 | |
| 45 | =item Switch: B<-closecmd> |
| 46 | |
| 47 | Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be closed (See |
| 48 | L<"BINDINGS"> below). This method is called with one argument, |
| 49 | the pathname of the entry. This method should perform appropriate |
| 50 | actions to close the specified entry. If the B<-closecmd> option |
| 51 | is not specified, the default closing action is to hide all child |
| 52 | entries of the specified entry. |
| 53 | |
| 54 | =item Name: B<command> |
| 55 | |
| 56 | =item Class: B<Command> |
| 57 | |
| 58 | =item Switch: B<-command> |
| 59 | |
| 60 | Specifies a L<callback|Tk::callbacks> to call whenever the user activates an entry |
| 61 | (usually by double-clicking on the entry). The callback |
| 62 | is called with one argument, the pathname of the entry. |
| 63 | |
| 64 | =item Name: B<ignoreInvoke> |
| 65 | |
| 66 | =item Class: B<IgnoreInvoke> |
| 67 | |
| 68 | =item Switch: B<-ignoreinvoke> |
| 69 | |
| 70 | A Boolean value that specifies when a branch should be opened or |
| 71 | closed. A branch will always be opened or closed when the user presses |
| 72 | the (+) and (-) indicators. However, when the user invokes a branch |
| 73 | (by doublc-clicking or pressing E<lt>ReturnE<gt>), the branch will be opened |
| 74 | or closed only if B<-ignoreinvoke> is set to false (the default |
| 75 | setting). |
| 76 | |
| 77 | =item Name: B<openCmd> |
| 78 | |
| 79 | =item Class: B<OpenCmd> |
| 80 | |
| 81 | =item Switch: B<-opencmd> |
| 82 | |
| 83 | Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be opened (See |
| 84 | L<"BINDINGS"> below). This method is called with one argument, |
| 85 | the pathname of the entry. This method should perform appropriate |
| 86 | actions to open the specified entry. If the B<-opencmd> option |
| 87 | is not specified, the default opening action is to show all the child |
| 88 | entries of the specified entry. |
| 89 | |
| 90 | =back |
| 91 | |
| 92 | =head1 DESCRIPTION |
| 93 | |
| 94 | The B<Tree> method creates a new window and makes it into a Tree widget |
| 95 | and return a reference to it. Additional options, described above, may |
| 96 | be specified on the command line or in the option database to configure |
| 97 | aspects of the Tree widget such as its cursor and relief. |
| 98 | |
| 99 | The Tree widget can be used to display hierarchical data in a tree |
| 100 | form. The user can adjust the view of the tree by opening or closing |
| 101 | parts of the tree. |
| 102 | |
| 103 | To display a static tree structure, you can add the entries into the |
| 104 | Tree widget and hide any entries as desired. Then you can call |
| 105 | the B<autosetmode> method. This will set up the Tree widget so that it |
| 106 | handles all the I<open> and I<close> events automatically. |
| 107 | the demonstration program F<Tixish/examples/perl-tix-tree>). |
| 108 | |
| 109 | The above method is not applicable if you want to maintain a dynamic tree |
| 110 | structure, i.e, you do not know all the entries in the tree and you need |
| 111 | to add or delete entries subsequently. To do this, you should first create |
| 112 | the entries in the Tree widget. Then, use the B<setmode> method to |
| 113 | indicate the entries that can be opened or closed, and use the B<-opencmd> |
| 114 | and B<-closecmd> options to handle the opening and closing events. (Please |
| 115 | see the demonstration program F<Tixish/examples/perl-tix-dyntree>). |
| 116 | |
| 117 | Use either |
| 118 | |
| 119 | S< >I<$parent>-E<gt>B<Scrolled>(B<'Tree'>, ... ); |
| 120 | |
| 121 | or |
| 122 | |
| 123 | S< >I<$parent>-E<gt>B<ScrlTree>( ... ); |
| 124 | |
| 125 | to create a scrolled B<Tree>. See L<Tk::Scrolled> for details. |
| 126 | |
| 127 | =head1 WIDGET METHODS |
| 128 | |
| 129 | The B<Tree> method creates a widget object. |
| 130 | This object supports the B<configure> and B<cget> methods |
| 131 | described in L<Tk::options> which can be used to enquire and |
| 132 | modify the options described above. |
| 133 | The widget also inherits all the methods provided by the generic |
| 134 | L<Tk::Widget|Tk::Widget> class. |
| 135 | |
| 136 | The following additional methods are available for Tree widgets: |
| 137 | |
| 138 | =over 4 |
| 139 | |
| 140 | =item I<$tree>-E<gt>B<autosetmode> |
| 141 | |
| 142 | This method calls the B<setmode> method for all the entries in |
| 143 | this Tree widget: if an entry has no child entries, its mode is set to |
| 144 | B<none>. Otherwise, if the entry has any hidden child entries, its |
| 145 | mode is set to B<open>; otherwise its mode is set to B<close>. |
| 146 | |
| 147 | =item I<$tree>-E<gt>B<close>(I<entryPath>) |
| 148 | |
| 149 | Close the entry given by I<entryPath> if its I<mode> is B<close>. |
| 150 | |
| 151 | =item I<$tree>-E<gt>B<getmode>(I<entryPath>) |
| 152 | |
| 153 | Returns the current I<mode> of the entry given by I<entryPath>. |
| 154 | |
| 155 | =item I<$tree>-E<gt>B<open>(I<entryPath>) |
| 156 | |
| 157 | Open the entry given by I<entryPath> if its I<mode> is B<open>. |
| 158 | |
| 159 | =item I<$tree>-E<gt>B<setmode>(I<entryPath, mode>) |
| 160 | |
| 161 | This method is used to indicate whether the entry given by |
| 162 | I<entryPath> has children entries and whether the children are |
| 163 | visible. I<mode> must be one of B<open>, |
| 164 | B<close> or B<none>. If I<mode> is set to B<open>, a (+) |
| 165 | indicator is drawn next the the entry. If I<mode> is set to |
| 166 | B<close>, a (-) indicator is drawn next the the entry. If |
| 167 | I<mode> is set to B<none>, no indicators will be drawn for this |
| 168 | entry. The default I<mode> is none. The B<open> mode indicates |
| 169 | the entry has hidden children and this entry can be opened by the |
| 170 | user. The B<close> mode indicates that all the children of the entry |
| 171 | are now visible and the entry can be closed by the user. |
| 172 | |
| 173 | =back |
| 174 | |
| 175 | =head1 BINDINGS |
| 176 | |
| 177 | The basic mouse and keyboard bindings of the Tree widget are the same |
| 178 | as the L<bindings of the HList|Tk::HList/"BINDINGS"> widget. |
| 179 | In addition, the entries can be opened or closed under the following |
| 180 | conditions: |
| 181 | |
| 182 | =over 4 |
| 183 | |
| 184 | =item [1] |
| 185 | |
| 186 | If the I<mode> of the entry is B<open>, it can be opened by clicking |
| 187 | on its (+) indicator. |
| 188 | |
| 189 | =item [2] |
| 190 | |
| 191 | If the I<mode> of the entry is B<close>, it can be closed by clicking |
| 192 | on its (-) indicator. |
| 193 | |
| 194 | =back |
| 195 | |
| 196 | =head1 SEE ALSO |
| 197 | |
| 198 | L<Tk::HList|Tk::HList> |
| 199 | |
| 200 | =head1 AUTHOR |
| 201 | |
| 202 | Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix |
| 203 | version by Ioi Kim Lam. |
| 204 | |
| 205 | =head1 ACKNOWLEDGEMENTS |
| 206 | |
| 207 | Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help. |
| 208 | |
| 209 | =cut |
| 210 | |