Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1997 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Widget - Base class of all widgets | |
11 | ||
12 | =for pm Tk/Widget.pm | |
13 | ||
14 | =for category Tk Generic Methods | |
15 | ||
16 | =head1 SYNOPSIS | |
17 | ||
18 | package Tk::Whatever; | |
19 | require Tk::Widget; | |
20 | @ISA = qw(Tk::Widget); | |
21 | Construct Tk::Widget 'Whatever'; | |
22 | ||
23 | sub Tk_cmd { \&Tk::whatever } | |
24 | ||
25 | S< >I<$widget>-E<gt>I<method>(?I<arg, arg, ...>?) | |
26 | ||
27 | =head1 DESCRIPTION | |
28 | ||
29 | The B<Tk::Widget> is an abstract base class for all Tk widgets. | |
30 | ||
31 | Generic methods available to all widgets include the methods based on core | |
32 | C<winfo> mechanism and are used to retrieve information about windows managed by | |
33 | Tk. They can take any of a number of different forms, depending on the I<method>. | |
34 | The legal forms are: | |
35 | ||
36 | =over 4 | |
37 | ||
38 | =item I<$widget>-E<gt>B<appname>?(I<newName>)? | |
39 | ||
40 | If I<newName> isn't specified, this method returns the name | |
41 | of the application (the name that may be used in B<send> | |
42 | commands to communicate with the application). | |
43 | If I<newName> is specified, then the name of the application | |
44 | is changed to I<newName>. | |
45 | If the given name is already in use, then a suffix of the form | |
46 | ``B< #2>'' or ``B< #3>'' is appended in order to make the name unique. | |
47 | The method's result is the name actually chosen. | |
48 | I<newName> should not start with a capital letter. | |
49 | This will interfere with L<option|Tk::option> processing, since names starting with | |
50 | capitals are assumed to be classes; as a result, Tk may not | |
51 | be able to find some options for the application. | |
52 | If sends have been disabled by deleting the B<send> command, | |
53 | this command will reenable them and recreate the B<send> | |
54 | command. | |
55 | ||
56 | =item I<$widget>-E<gt>B<atom>(I<name>) | |
57 | ||
58 | Returns a decimal string giving the integer identifier for the | |
59 | atom whose name is I<name>. If no atom exists with the name | |
60 | I<name> then a new one is created. | |
61 | ||
62 | =item I<$widget>-E<gt>B<atomname>(I<id>) | |
63 | ||
64 | Returns the textual name for the atom whose integer identifier is | |
65 | I<id>. | |
66 | This command is the inverse of the I<$widget>-E<gt>B<atom> command. | |
67 | It generates an error if no such atom exists. | |
68 | ||
69 | =item I<$widget>-E<gt>B<bell> | |
70 | ||
71 | This command rings the bell on the display for I<$widget> and | |
72 | returns an empty string. | |
73 | The command uses the current bell-related settings for the display, which | |
74 | may be modified with programs such as B<xset>. | |
75 | ||
76 | This command also resets the screen saver for the screen. Some | |
77 | screen savers will ignore this, but others will reset so that the | |
78 | screen becomes visible again. | |
79 | ||
80 | =item I<$widget>-E<gt>B<Busy>?(?-recurse => 1?I<-option => value>?)? | |
81 | ||
82 | This method B<configure>s a B<-cursor> option for I<$widget> and | |
83 | (if B<-recurse => 1> is specified) all its descendants. The cursor to | |
84 | be set may be passed as S<B<-cursor> => I<cursor>> or defaults to 'watch'. | |
85 | Additional B<configure> options are applied to I<$widget> only. | |
86 | It also adds a special tag B<'Busy'> to the B<bindtags> of the widgets so | |
87 | configured so that B<KeyPress>, B<KeyRelease>, B<ButtonPress> and | |
88 | B<ButtonRelease> events are ignored (with press events generating a call to | |
89 | B<bell>). It then acquires a local B<grab> for I<$widget>. | |
90 | The state of the widgets and the grab is restored by a call to | |
91 | I<$widget>-E<gt>B<Unbusy>. | |
92 | ||
93 | ||
94 | =item I<$widget>-E<gt>B<cells> | |
95 | ||
96 | Returns a decimal string giving the number of cells in the | |
97 | color map for I<$widget>. | |
98 | ||
99 | =item I<$widget>-E<gt>B<children> | |
100 | ||
101 | I<$widget->>B<children> | |
102 | Returns a list containing all the children | |
103 | of $widget. The list is in stacking order, with the lowest | |
104 | window first. Top-level windows are returned as children | |
105 | of their logical parents. | |
106 | ||
107 | =item I<$widget>-E<gt>B<class> | |
108 | ||
109 | Returns the class name for I<$widget>. | |
110 | ||
111 | =item I<$widget>-E<gt>B<colormapfull> | |
112 | ||
113 | Returns 1 if the colormap for I<$widget> is known to be full, 0 | |
114 | otherwise. The colormap for a window is ``known'' to be full if the last | |
115 | attempt to allocate a new color on that window failed and this | |
116 | application hasn't freed any colors in the colormap since the | |
117 | failed allocation. | |
118 | ||
119 | =item I<$widget>-E<gt>B<containing>(I<rootX,rootY>) | |
120 | ||
121 | Returns the window containing the point given | |
122 | by I<rootX> and I<rootY>. | |
123 | I<RootX> and I<rootY> are specified in screen units (i.e. | |
124 | any form acceptable to B<Tk_GetPixels>) in the coordinate | |
125 | system of the root window (if a virtual-root window manager is in | |
126 | use then the coordinate system of the virtual root window is used). | |
127 | If no window in this application contains the point then an empty | |
128 | string is returned. | |
129 | In selecting the containing window, children are given higher priority | |
130 | than parents and among siblings the highest one in the stacking order is | |
131 | chosen. | |
132 | ||
133 | =item I<$widget>-E<gt>B<depth> | |
134 | ||
135 | Returns a decimal string giving the depth of I<$widget> (number | |
136 | of bits per pixel). | |
137 | ||
138 | =item I<$widget>-E<gt>B<destroy> | |
139 | ||
140 | This command deletes the window related to | |
141 | I<$widget>, plus all its descendants. | |
142 | If all the B<MainWindows> are deleted then the entire application | |
143 | will be destroyed. | |
144 | ||
145 | The perl object I<$widget> continues to exist while references | |
146 | to it still exist, e.g. until variable goes out of scope. | |
147 | However any attempt to use Tk methods on the object will fail. | |
148 | B<Exists>(I<$widget>) will return false on such objects. | |
149 | ||
150 | Note however that while a window exists for I<$widget> the | |
151 | perl object is maintained (due to "references" in perl/Tk internals) | |
152 | even though original variables may have gone out of scope. | |
153 | (Normally this is intuitive.) | |
154 | ||
155 | =item B<Exists>(I<$widget>) | |
156 | ||
157 | Returns 1 if there exists a window for I<$widget>, 0 if no such | |
158 | window exists. | |
159 | ||
160 | =item I<$widget>-E<gt>B<font>(I<option>?, I<arg, arg, ...>?) | |
161 | ||
162 | Create and inspect fonts. See L<Tk::Font> for further details. | |
163 | ||
164 | =item I<$widget>-E<gt>B<fpixels>(I<number>) | |
165 | ||
166 | Returns a floating-point value giving the number of pixels | |
167 | in I<$widget> corresponding to the distance given by I<number>. | |
168 | I<Number> may be specified in any of the forms acceptable | |
169 | to B<Tk_GetScreenMM>, such as ``2.0c'' or ``1i''. | |
170 | The return value may be fractional; for an integer value, use | |
171 | I<$widget>-E<gt>B<pixels>. | |
172 | ||
173 | =item I<$widget>-E<gt>B<Getimage>(I<name>) | |
174 | ||
175 | Given I<name>, look for an image file with that base name and return | |
176 | a L<Tk::Image>. File extensions are tried in this order: F<xpm>, | |
177 | F<gif>, F<ppm>, F<xbm> until a valid iamge is found. If no image is | |
178 | found, try a builtin image with that name. | |
179 | ||
180 | =item I<$widget>-E<gt>B<geometry> | |
181 | ||
182 | Returns the geometry for I<$widget>, in the form | |
183 | I<width>B<x>I<height>B<+>I<x>B<+>I<y>. All dimensions are | |
184 | in pixels. | |
185 | ||
186 | =item I<$widget>-E<gt>B<height> | |
187 | ||
188 | Returns a decimal string giving I<$widget>'s height in pixels. | |
189 | When a window is first created its height will be 1 pixel; the | |
190 | height will eventually be changed by a geometry manager to fulfill | |
191 | the window's needs. | |
192 | If you need the true height immediately after creating a widget, | |
193 | invoke B<update> to force the geometry manager to arrange it, | |
194 | or use I<$widget>-E<gt>B<reqheight> to get the window's requested height | |
195 | instead of its actual height. | |
196 | ||
197 | =item I<$widget>-E<gt>B<id> | |
198 | ||
199 | Returns a hexadecimal string giving a low-level platform-specific | |
200 | identifier for $widget. On Unix platforms, this is the X | |
201 | window identifier. Under Windows, this is the Windows | |
202 | HWND. On the Macintosh the value has no meaning outside Tk. | |
203 | ||
204 | =item I<$widget>-E<gt>B<idletasks> | |
205 | ||
206 | One of two methods which are used to bring the application ``up to date'' | |
207 | by entering the event loop repeated until all pending events | |
208 | (including idle callbacks) have been processed. | |
209 | ||
210 | If the B<idletasks> method is specified, then no new events or errors | |
211 | are processed; only idle callbacks are invoked. This causes operations | |
212 | that are normally deferred, such as display updates and window layout | |
213 | calculations, to be performed immediately. | |
214 | ||
215 | The B<idletasks> command is useful in scripts where changes have been | |
216 | made to the application's state and you want those changes to appear | |
217 | on the display immediately, rather than waiting for the script to | |
218 | complete. Most display updates are performed as idle callbacks, so | |
219 | B<idletasks> will cause them to run. However, there are some kinds of | |
220 | updates that only happen in response to events, such as those | |
221 | triggered by window size changes; these updates will not occur in | |
222 | B<idletasks>. | |
223 | ||
224 | =item I<$widget>-E<gt>B<interps> | |
225 | ||
226 | Returns a list whose members are the names of all Tcl interpreters | |
227 | (e.g. all Tk-based applications) currently registered for | |
228 | a particular display. | |
229 | The return value refers | |
230 | to the display of I<$widget>. | |
231 | ||
232 | =item I<$widget>-E<gt>B<ismapped> | |
233 | ||
234 | Returns B<1> if I<$widget> is currently mapped, B<0> otherwise. | |
235 | ||
236 | =item I<$widget->>B<lower>(?I<belowThis>?) | |
237 | ||
238 | If the I<belowThis> argument is omitted then the command lowers | |
239 | $widget so that it is below all of its siblings in the stacking | |
240 | order (it will be obscured by any siblings that overlap it and | |
241 | will not obscure any siblings). | |
242 | If I<belowThis> is specified then it must be the path name of | |
243 | a window that is either a sibling of $widget or the descendant | |
244 | of a sibling of $widget. | |
245 | In this case the B<lower> command will insert | |
246 | $widget into the stacking order just below I<belowThis> | |
247 | (or the ancestor of I<belowThis> that is a sibling of $widget); | |
248 | this could end up either raising or lowering $widget. | |
249 | ||
250 | =item I<$widget>-E<gt>B<MapWindow> | |
251 | ||
252 | Cause I<$widget> to be "mapped" i.e. made visible on the display. | |
253 | May confuse the geometry manager (pack, grid, place, ...) | |
254 | that thinks it is managing the widget. | |
255 | ||
256 | =item I<$widget>-E<gt>B<manager> | |
257 | ||
258 | Returns the name of the geometry manager currently | |
259 | responsible for I<$widget>, or an empty string if I<$widget> | |
260 | isn't managed by any geometry manager. | |
261 | The name is usually the name of the method for the geometry | |
262 | manager, such as B<pack> or B<place>. | |
263 | If the geometry manager is a widget, such as canvases or text, the | |
264 | name is the widget's class command, such as B<canvas>. | |
265 | ||
266 | =item I<$widget>-E<gt>B<name> | |
267 | ||
268 | Returns I<$widget>'s name (i.e. its name within its parent, as opposed | |
269 | to its full path name). | |
270 | The command I<$mainwin>-E<gt>B<name> will return the name of the application. | |
271 | ||
272 | =item I<$widget>-E<gt>B<OnDestroy>(I<callback>); | |
273 | ||
274 | OnDestroy accepts a standard perl/Tk I<callback>. | |
275 | When the window associated with I<$widget> is destroyed then | |
276 | the callback is invoked. Unlike I<$widget->>bind('E<lt>DestroyE<gt>',...) | |
277 | the widgets methods are still available when I<callback> is executed, | |
278 | so (for example) a B<Text> widget can save its contents to a file. | |
279 | ||
280 | OnDestroy was required for new B<after> mechanism. | |
281 | ||
282 | =item I<$widget>-E<gt>B<parent> | |
283 | ||
284 | Returns I<$widget>'s parent, or an empty string | |
285 | if I<$widget> is the main window of the application. | |
286 | ||
287 | =item I<$widget>-E<gt>B<PathName> | |
288 | ||
289 | Returns the tk path name of I<$widget>. (This is an import from the | |
290 | C interface.) | |
291 | ||
292 | =item I<$widget>-E<gt>B<pathname>(I<id>) | |
293 | ||
294 | Returns an object whose X identifier is I<id>. | |
295 | The identifier is looked up on the display of I<$widget>. | |
296 | I<Id> must be a decimal, hexadecimal, or octal integer and must | |
297 | correspond to a window in the invoking application, or an error | |
298 | occurs which can be trapped with C<eval { }> or C<Tk::catch { }>. | |
299 | If the window belongs to the application, but is not an object | |
300 | (for example wrapper windows, HList header, etc.) then C<undef> | |
301 | is returned. | |
302 | ||
303 | =item I<$widget>-E<gt>B<pixels>(I<number>) | |
304 | ||
305 | Returns the number of pixels in I<$widget> corresponding | |
306 | to the distance given by I<number>. | |
307 | I<Number> may be specified in any of the forms acceptable | |
308 | to B<Tk_GetPixels>, such as ``2.0c'' or ``1i''. | |
309 | The result is rounded to the nearest integer value; for a | |
310 | fractional result, use I<$widget>-E<gt>B<fpixels>. | |
311 | ||
312 | =item I<$widget>-E<gt>B<pointerx> | |
313 | ||
314 | If the mouse pointer is on the same screen as I<$widget>, returns the | |
315 | pointer's x coordinate, measured in pixels in the screen's root window. | |
316 | If a virtual root window is in use on the screen, the position is | |
317 | measured in the virtual root. | |
318 | If the mouse pointer isn't on the same screen as I<$widget> then | |
319 | -1 is returned. | |
320 | ||
321 | =item I<$widget>-E<gt>B<pointerxy> | |
322 | ||
323 | If the mouse pointer is on the same screen as I<$widget>, returns a list | |
324 | with two elements, which are the pointer's x and y coordinates measured | |
325 | in pixels in the screen's root window. | |
326 | If a virtual root window is in use on the screen, the position | |
327 | is computed in the virtual root. | |
328 | If the mouse pointer isn't on the same screen as I<$widget> then | |
329 | both of the returned coordinates are -1. | |
330 | ||
331 | =item I<$widget>-E<gt>B<pointery> | |
332 | ||
333 | If the mouse pointer is on the same screen as I<$widget>, returns the | |
334 | pointer's y coordinate, measured in pixels in the screen's root window. | |
335 | If a virtual root window is in use on the screen, the position | |
336 | is computed in the virtual root. | |
337 | If the mouse pointer isn't on the same screen as I<$widget> then | |
338 | -1 is returned. | |
339 | ||
340 | =item I<$widget>-E<gt>B<raise>(?I<aboveThis>?) | |
341 | ||
342 | If the I<aboveThis> argument is omitted then the command raises | |
343 | $widget so that it is above all of its siblings in the stacking | |
344 | order (it will not be obscured by any siblings and will obscure | |
345 | any siblings that overlap it). | |
346 | If I<aboveThis> is specified then it must be the path name of | |
347 | a window that is either a sibling of $widget or the descendant | |
348 | of a sibling of $widget. | |
349 | In this case the B<raise> command will insert | |
350 | $widget into the stacking order just above I<aboveThis> | |
351 | (or the ancestor of I<aboveThis> that is a sibling of $widget); | |
352 | this could end up either raising or lowering $widget. | |
353 | ||
354 | =item I<$widget>-E<gt>B<reqheight> | |
355 | ||
356 | Returns a decimal string giving I<$widget>'s requested height, | |
357 | in pixels. This is the value used by I<$widget>'s geometry | |
358 | manager to compute its geometry. | |
359 | ||
360 | =item I<$widget>-E<gt>B<reqwidth> | |
361 | ||
362 | Returns a decimal string giving I<$widget>'s requested width, | |
363 | in pixels. This is the value used by I<$widget>'s geometry | |
364 | manager to compute its geometry. | |
365 | ||
366 | =item I<$widget>-E<gt>B<rgb>(I<color>) | |
367 | ||
368 | Returns a list containing three decimal values, which are the | |
369 | red, green, and blue intensities that correspond to I<color> in | |
370 | the window given by I<$widget>. I<Color> | |
371 | may be specified in any of the forms acceptable for a color | |
372 | option. | |
373 | ||
374 | =item I<$widget>-E<gt>B<rootx> | |
375 | ||
376 | Returns a decimal string giving the x-coordinate, in the root | |
377 | window of the screen, of the | |
378 | upper-left corner of I<$widget>'s border (or I<$widget> if it | |
379 | has no border). | |
380 | ||
381 | =item I<$widget>-E<gt>B<rooty> | |
382 | ||
383 | Returns a decimal string giving the y-coordinate, in the root | |
384 | window of the screen, of the | |
385 | upper-left corner of I<$widget>'s border (or I<$widget> if it | |
386 | has no border). | |
387 | ||
388 | =item B<scaling> | |
389 | ||
390 | =item I<$widget>-E<gt>B<scaling>?(I<number>)? | |
391 | ||
392 | Sets and queries the current scaling factor used by Tk to convert between | |
393 | physical units (for example, points, inches, or millimeters) and pixels. The | |
394 | I<number> argument is a floating point number that specifies the number of | |
395 | pixels per point on $widget's display. If the I<number> argument is | |
396 | omitted, the current value of the scaling factor is returned. | |
397 | ||
398 | A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor | |
399 | of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard | |
400 | 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, | |
401 | which is the setting for a 90 dpi monitor; setting the scaling factor to | |
402 | 1.25 on a 72 dpi monitor would cause everything in the application to be | |
403 | displayed 1.25 times as large as normal. The initial value for the scaling | |
404 | factor is set when the application starts, based on properties of the | |
405 | installed monitor (as reported via the window system), | |
406 | but it can be changed at any time. Measurements made | |
407 | after the scaling factor is changed will use the new scaling factor, but it | |
408 | is undefined whether existing widgets will resize themselves dynamically to | |
409 | accomodate the new scaling factor. | |
410 | ||
411 | =item I<$widget>-E<gt>B<screen> | |
412 | ||
413 | Returns the name of the screen associated with I<$widget>, in | |
414 | the form I<displayName>.I<screenIndex>. | |
415 | ||
416 | =item I<$widget>-E<gt>B<screencells> | |
417 | ||
418 | Returns a decimal string giving the number of cells in the default | |
419 | color map for I<$widget>'s screen. | |
420 | ||
421 | =item I<$widget>-E<gt>B<screendepth> | |
422 | ||
423 | Returns a decimal string giving the depth of the root window | |
424 | of I<$widget>'s screen (number of bits per pixel). | |
425 | ||
426 | =item I<$widget>-E<gt>B<screenheight> | |
427 | ||
428 | Returns a decimal string giving the height of I<$widget>'s screen, | |
429 | in pixels. | |
430 | ||
431 | =item I<$widget>-E<gt>B<screenmmheight> | |
432 | ||
433 | Returns a decimal string giving the height of I<$widget>'s screen, | |
434 | in millimeters. | |
435 | ||
436 | =item I<$widget>-E<gt>B<screenmmwidth> | |
437 | ||
438 | Returns a decimal string giving the width of I<$widget>'s screen, | |
439 | in millimeters. | |
440 | ||
441 | =item I<$widget>-E<gt>B<screenvisual> | |
442 | ||
443 | Returns one of the following strings to indicate the default visual | |
444 | class for I<$widget>'s screen: B<directcolor>, B<grayscale>, | |
445 | B<pseudocolor>, B<staticcolor>, B<staticgray>, or | |
446 | B<truecolor>. | |
447 | ||
448 | =item I<$widget>-E<gt>B<screenwidth> | |
449 | ||
450 | Returns a decimal string giving the width of I<$widget>'s screen, | |
451 | in pixels. | |
452 | ||
453 | =item I<$widget>-E<gt>B<server> | |
454 | ||
455 | Returns a string containing information about the server for | |
456 | I<$widget>'s display. The exact format of this string may vary | |
457 | from platform to platform. For X servers the string | |
458 | has the form ``B<X>I<major>B<R>I<minor vendor vendorVersion>'' | |
459 | where I<major> and I<minor> are the version and revision | |
460 | numbers provided by the server (e.g., B<X11R5>), I<vendor> | |
461 | is the name of the vendor for the server, and I<vendorRelease> | |
462 | is an integer release number provided by the server. | |
463 | ||
464 | =item I<$widget>-E<gt>B<toplevel> | |
465 | ||
466 | Returns the reference of the top-level window containing I<$widget>. | |
467 | ||
468 | =item I<$widget>-E<gt>B<UnmapWindow> | |
469 | ||
470 | Cause I<$widget> to be "unmapped" i.e. removed from the display. | |
471 | This does for any widget what I<$widget>-E<gt>withdraw does for | |
472 | toplevel widgets. May confuse the geometry manager (pack, grid, place, ...) | |
473 | that thinks it is managing the widget. | |
474 | ||
475 | =item I<$widget>-E<gt>B<update> | |
476 | ||
477 | One of two methods which are used to bring the application ``up to date'' | |
478 | by entering the event loop repeated until all pending events | |
479 | (including idle callbacks) have been processed. | |
480 | ||
481 | The B<update> method is useful in scripts where you are performing a | |
482 | long-running computation but you still want the application to respond | |
483 | to events such as user interactions; if you occasionally call | |
484 | B<update> then user input will be processed during the next call to | |
485 | B<update>. | |
486 | ||
487 | =item I<$widget>-E<gt>B<Unbusy> | |
488 | ||
489 | Restores widget state after a call to I<$widget>-E<gt>B<Busy>. | |
490 | ||
491 | =item I<$widget>-E<gt>B<viewable> | |
492 | ||
493 | Returns 1 if I<$widget> and all of its ancestors up through the | |
494 | nearest toplevel window are mapped. Returns 0 if any of these | |
495 | windows are not mapped. | |
496 | ||
497 | =item I<$widget>-E<gt>B<visual> | |
498 | ||
499 | Returns one of the following strings to indicate the visual | |
500 | class for I<$widget>: B<directcolor>, B<grayscale>, | |
501 | B<pseudocolor>, B<staticcolor>, B<staticgray>, or | |
502 | B<truecolor>. | |
503 | ||
504 | =item I<$widget>-E<gt>B<visualid> | |
505 | ||
506 | Returns the X identifier for the visual for $widget. | |
507 | ||
508 | =item I<$widget>-E<gt>B<visualsavailable>(?B<includeids>?) | |
509 | ||
510 | Returns a list whose elements describe the visuals available for | |
511 | I<$widget>'s screen. | |
512 | Each element consists of a visual class followed by an integer depth. | |
513 | The class has the same form as returned by I<$widget>-E<gt>B<visual>. | |
514 | The depth gives the number of bits per pixel in the visual. | |
515 | In addition, if the B<includeids> argument is provided, then the | |
516 | depth is followed by the X identifier for the visual. | |
517 | ||
518 | =item I<$widget>-E<gt>B<vrootheight> | |
519 | ||
520 | Returns the height of the virtual root window associated with I<$widget> | |
521 | if there is one; otherwise returns the height of I<$widget>'s screen. | |
522 | ||
523 | =item I<$widget>-E<gt>B<vrootwidth> | |
524 | ||
525 | Returns the width of the virtual root window associated with I<$widget> | |
526 | if there is one; otherwise returns the width of I<$widget>'s screen. | |
527 | ||
528 | =item I<$widget>-E<gt>B<vrootx> | |
529 | ||
530 | Returns the x-offset of the virtual root window associated with I<$widget>, | |
531 | relative to the root window of its screen. | |
532 | This is normally either zero or negative. | |
533 | Returns 0 if there is no virtual root window for I<$widget>. | |
534 | ||
535 | =item I<$widget>-E<gt>B<vrooty> | |
536 | ||
537 | Returns the y-offset of the virtual root window associated with I<$widget>, | |
538 | relative to the root window of its screen. | |
539 | This is normally either zero or negative. | |
540 | Returns 0 if there is no virtual root window for I<$widget>. | |
541 | ||
542 | =item I<$widget->>B<waitVariable>(\$I<name>) | |
543 | ||
544 | =item I<$widget->>B<waitVisibility> | |
545 | ||
546 | =item I<$widget->>B<waitWindow> | |
547 | ||
548 | The B<tk wait> methods wait for one of several things to happen, | |
549 | then it returns without taking any other actions. | |
550 | The return value is always an empty string. | |
551 | B<waitVariable> expects a reference to a perl | |
552 | variable and the command waits for that variable to be modified. | |
553 | This form is typically used to wait for a user to finish interacting | |
554 | with a dialog which sets the variable as part (possibly final) | |
555 | part of the interaction. | |
556 | B<waitVisibility> waits for a change in I<$widget>'s | |
557 | visibility state (as indicated by the arrival of a VisibilityNotify | |
558 | event). This form is typically used to wait for a newly-created | |
559 | window to appear on the screen before taking some action. | |
560 | B<waitWindow> waits for I<$widget> to be destroyed. | |
561 | This form is typically used to wait for a user to finish interacting | |
562 | with a dialog box before using the result of that interaction. | |
563 | Note that creating and destroying the window each time a dialog is required | |
564 | makes code modular but imposes overhead which can be avoided by B<withdrawing> | |
565 | the window instead and using B<waitVisibility>. | |
566 | ||
567 | While the B<tk wait> methods are waiting they processes events in | |
568 | the normal fashion, so the application will continue to respond | |
569 | to user interactions. | |
570 | If an event handler invokes B<tkwait> again, the nested call | |
571 | to B<tkwait> must complete before the outer call can complete. | |
572 | ||
573 | =item I<$widget>-E<gt>B<width> | |
574 | ||
575 | Returns a decimal string giving I<$widget>'s width in pixels. | |
576 | When a window is first created its width will be 1 pixel; the | |
577 | width will eventually be changed by a geometry manager to fulfill | |
578 | the window's needs. | |
579 | If you need the true width immediately after creating a widget, | |
580 | invoke B<update> to force the geometry manager to arrange it, | |
581 | or use I<$widget>-E<gt>B<reqwidth> to get the window's requested width | |
582 | instead of its actual width. | |
583 | ||
584 | =item I<$widget>-E<gt>B<x> | |
585 | ||
586 | Returns a decimal string giving the x-coordinate, in I<$widget>'s | |
587 | parent, of the upper-left corner of I<$widget>'s border (or I<$widget> | |
588 | if it has no border). | |
589 | ||
590 | =item I<$widget>-E<gt>B<y> | |
591 | ||
592 | Returns a decimal string giving the y-coordinate, in I<$widget>'s | |
593 | parent, of the | |
594 | upper-left corner of I<$widget>'s border (or I<$widget> if it | |
595 | has no border). | |
596 | ||
597 | =back | |
598 | ||
599 | =head1 CAVEATS | |
600 | ||
601 | The above documentaion on generic methods is incomplete. | |
602 | ||
603 | =head1 KEYWORDS | |
604 | ||
605 | atom, children, class, geometry, height, identifier, information, interpreters, | |
606 | mapped, parent, path name, screen, virtual root, width, window | |
607 | ||
608 | =cut | |
609 |