[OpenSPARC-T2-DV] / tools / perl-5.8.0 / lib / site_perl / 5.8.0 / sun4-solaris / Tk / Tree.pod


=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<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<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 the the entry. If I<mode> is set to
B<close>, a (-) indicator is drawn next the 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.

=head1 ACKNOWLEDGEMENTS

Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help.

=cut
Commit	Line	Data
86530b38 AT	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