Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "WIDGET 1" | |
132 | .TH WIDGET 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::Widget \- Base class of all widgets | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 4 | |
138 | \& package Tk::Whatever; | |
139 | \& require Tk::Widget; | |
140 | \& @ISA = qw(Tk::Widget); | |
141 | \& Construct Tk::Widget 'Whatever'; | |
142 | .Ve | |
143 | .PP | |
144 | .Vb 1 | |
145 | \& sub Tk_cmd { \e&Tk::whatever } | |
146 | .Ve | |
147 | .PP | |
148 | \&\ \fI$widget\fR\->\fImethod\fR(?\fIarg, arg, ...\fR?) | |
149 | .SH "DESCRIPTION" | |
150 | .IX Header "DESCRIPTION" | |
151 | The \fBTk::Widget\fR is an abstract base class for all Tk widgets. | |
152 | .PP | |
153 | Generic methods available to all widgets include the methods based on core | |
154 | \&\f(CW\*(C`winfo\*(C'\fR mechanism and are used to retrieve information about windows managed by | |
155 | Tk. They can take any of a number of different forms, depending on the \fImethod\fR. | |
156 | The legal forms are: | |
157 | .IP "\fI$widget\fR\->\fBappname\fR?(\fInewName\fR)?" 4 | |
158 | .IX Item "$widget->appname?(newName)?" | |
159 | If \fInewName\fR isn't specified, this method returns the name | |
160 | of the application (the name that may be used in \fBsend\fR | |
161 | commands to communicate with the application). | |
162 | If \fInewName\fR is specified, then the name of the application | |
163 | is changed to \fInewName\fR. | |
164 | If the given name is already in use, then a suffix of the form | |
165 | ``\fB #2\fR'' or ``\fB #3\fR'' is appended in order to make the name unique. | |
166 | The method's result is the name actually chosen. | |
167 | \&\fInewName\fR should not start with a capital letter. | |
168 | This will interfere with option processing, since names starting with | |
169 | capitals are assumed to be classes; as a result, Tk may not | |
170 | be able to find some options for the application. | |
171 | If sends have been disabled by deleting the \fBsend\fR command, | |
172 | this command will reenable them and recreate the \fBsend\fR | |
173 | command. | |
174 | .IP "\fI$widget\fR\->\fBatom\fR(\fIname\fR)" 4 | |
175 | .IX Item "$widget->atom(name)" | |
176 | Returns a decimal string giving the integer identifier for the | |
177 | atom whose name is \fIname\fR. If no atom exists with the name | |
178 | \&\fIname\fR then a new one is created. | |
179 | .IP "\fI$widget\fR\->\fBatomname\fR(\fIid\fR)" 4 | |
180 | .IX Item "$widget->atomname(id)" | |
181 | Returns the textual name for the atom whose integer identifier is | |
182 | \&\fIid\fR. | |
183 | This command is the inverse of the \fI$widget\fR\->\fBatom\fR command. | |
184 | It generates an error if no such atom exists. | |
185 | .IP "\fI$widget\fR\->\fBbell\fR" 4 | |
186 | .IX Item "$widget->bell" | |
187 | This command rings the bell on the display for \fI$widget\fR and | |
188 | returns an empty string. | |
189 | The command uses the current bell-related settings for the display, which | |
190 | may be modified with programs such as \fBxset\fR. | |
191 | .Sp | |
192 | This command also resets the screen saver for the screen. Some | |
193 | screen savers will ignore this, but others will reset so that the | |
194 | screen becomes visible again. | |
195 | .IP "\fI$widget\fR\->\fBBusy\fR?(?\-recurse => 1?\fI\-option =\fR value>?)?" 4 | |
196 | .IX Item "$widget->Busy?(?-recurse => 1?-option = value>?)?" | |
197 | This method \fBconfigure\fRs a \fB\-cursor\fR option for \fI$widget\fR and | |
198 | (if \fB\-recurse =\fR 1> is specified) all its descendants. The cursor to | |
199 | be set may be passed as \fB\-cursor\fR\ = \fIcursor\fR> or defaults to 'watch'. | |
200 | Additional \fBconfigure\fR options are applied to \fI$widget\fR only. | |
201 | It also adds a special tag \fB'Busy'\fR to the \fBbindtags\fR of the widgets so | |
202 | configured so that \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR and | |
203 | \&\fBButtonRelease\fR events are ignored (with press events generating a call to | |
204 | \&\fBbell\fR). It then acquires a local \fBgrab\fR for \fI$widget\fR. | |
205 | The state of the widgets and the grab is restored by a call to | |
206 | \&\fI$widget\fR\->\fBUnbusy\fR. | |
207 | .IP "\fI$widget\fR\->\fBcells\fR" 4 | |
208 | .IX Item "$widget->cells" | |
209 | Returns a decimal string giving the number of cells in the | |
210 | color map for \fI$widget\fR. | |
211 | .IP "\fI$widget\fR\->\fBchildren\fR" 4 | |
212 | .IX Item "$widget->children" | |
213 | \&\fI$widget\-\fR>\fBchildren\fR | |
214 | Returns a list containing all the children | |
215 | of \f(CW$widget\fR. The list is in stacking order, with the lowest | |
216 | window first. Top-level windows are returned as children | |
217 | of their logical parents. | |
218 | .IP "\fI$widget\fR\->\fBclass\fR" 4 | |
219 | .IX Item "$widget->class" | |
220 | Returns the class name for \fI$widget\fR. | |
221 | .IP "\fI$widget\fR\->\fBcolormapfull\fR" 4 | |
222 | .IX Item "$widget->colormapfull" | |
223 | Returns 1 if the colormap for \fI$widget\fR is known to be full, 0 | |
224 | otherwise. The colormap for a window is ``known'' to be full if the last | |
225 | attempt to allocate a new color on that window failed and this | |
226 | application hasn't freed any colors in the colormap since the | |
227 | failed allocation. | |
228 | .IP "\fI$widget\fR\->\fBcontaining\fR(\fIrootX,rootY\fR)" 4 | |
229 | .IX Item "$widget->containing(rootX,rootY)" | |
230 | Returns the window containing the point given | |
231 | by \fIrootX\fR and \fIrootY\fR. | |
232 | \&\fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. | |
233 | any form acceptable to \fBTk_GetPixels\fR) in the coordinate | |
234 | system of the root window (if a virtual-root window manager is in | |
235 | use then the coordinate system of the virtual root window is used). | |
236 | If no window in this application contains the point then an empty | |
237 | string is returned. | |
238 | In selecting the containing window, children are given higher priority | |
239 | than parents and among siblings the highest one in the stacking order is | |
240 | chosen. | |
241 | .IP "\fI$widget\fR\->\fBdepth\fR" 4 | |
242 | .IX Item "$widget->depth" | |
243 | Returns a decimal string giving the depth of \fI$widget\fR (number | |
244 | of bits per pixel). | |
245 | .IP "\fI$widget\fR\->\fBdestroy\fR" 4 | |
246 | .IX Item "$widget->destroy" | |
247 | This command deletes the window related to | |
248 | \&\fI$widget\fR, plus all its descendants. | |
249 | If all the \fBMainWindows\fR are deleted then the entire application | |
250 | will be destroyed. | |
251 | .Sp | |
252 | The perl object \fI$widget\fR continues to exist while references | |
253 | to it still exist, e.g. until variable goes out of scope. | |
254 | However any attempt to use Tk methods on the object will fail. | |
255 | \&\fBExists\fR(\fI$widget\fR) will return false on such objects. | |
256 | .Sp | |
257 | Note however that while a window exists for \fI$widget\fR the | |
258 | perl object is maintained (due to \*(L"references\*(R" in perl/Tk internals) | |
259 | even though original variables may have gone out of scope. | |
260 | (Normally this is intuitive.) | |
261 | .IP "\fBExists\fR(\fI$widget\fR)" 4 | |
262 | .IX Item "Exists($widget)" | |
263 | Returns 1 if there exists a window for \fI$widget\fR, 0 if no such | |
264 | window exists. | |
265 | .IP "\fI$widget\fR\->\fBfont\fR(\fIoption\fR?, \fIarg, arg, ...\fR?)" 4 | |
266 | .IX Item "$widget->font(option?, arg, arg, ...?)" | |
267 | Create and inspect fonts. See Tk::Font for further details. | |
268 | .IP "\fI$widget\fR\->\fBfpixels\fR(\fInumber\fR)" 4 | |
269 | .IX Item "$widget->fpixels(number)" | |
270 | Returns a floating-point value giving the number of pixels | |
271 | in \fI$widget\fR corresponding to the distance given by \fInumber\fR. | |
272 | \&\fINumber\fR may be specified in any of the forms acceptable | |
273 | to \fBTk_GetScreenMM\fR, such as ``2.0c'' or ``1i''. | |
274 | The return value may be fractional; for an integer value, use | |
275 | \&\fI$widget\fR\->\fBpixels\fR. | |
276 | .IP "\fI$widget\fR\->\fBGetimage\fR(\fIname\fR)" 4 | |
277 | .IX Item "$widget->Getimage(name)" | |
278 | Given \fIname\fR, look for an image file with that base name and return | |
279 | a Tk::Image. File extensions are tried in this order: \fIxpm\fR, | |
280 | \&\fIgif\fR, \fIppm\fR, \fIxbm\fR until a valid iamge is found. If no image is | |
281 | found, try a builtin image with that name. | |
282 | .IP "\fI$widget\fR\->\fBgeometry\fR" 4 | |
283 | .IX Item "$widget->geometry" | |
284 | Returns the geometry for \fI$widget\fR, in the form | |
285 | \&\fIwidth\fR\fBx\fR\fIheight\fR\fB+\fR\fIx\fR\fB+\fR\fIy\fR. All dimensions are | |
286 | in pixels. | |
287 | .IP "\fI$widget\fR\->\fBheight\fR" 4 | |
288 | .IX Item "$widget->height" | |
289 | Returns a decimal string giving \fI$widget\fR's height in pixels. | |
290 | When a window is first created its height will be 1 pixel; the | |
291 | height will eventually be changed by a geometry manager to fulfill | |
292 | the window's needs. | |
293 | If you need the true height immediately after creating a widget, | |
294 | invoke \fBupdate\fR to force the geometry manager to arrange it, | |
295 | or use \fI$widget\fR\->\fBreqheight\fR to get the window's requested height | |
296 | instead of its actual height. | |
297 | .IP "\fI$widget\fR\->\fBid\fR" 4 | |
298 | .IX Item "$widget->id" | |
299 | Returns a hexadecimal string giving a low-level platform-specific | |
300 | identifier for \f(CW$widget\fR. On Unix platforms, this is the X | |
301 | window identifier. Under Windows, this is the Windows | |
302 | \&\s-1HWND\s0. On the Macintosh the value has no meaning outside Tk. | |
303 | .IP "\fI$widget\fR\->\fBidletasks\fR" 4 | |
304 | .IX Item "$widget->idletasks" | |
305 | One of two methods which are used to bring the application ``up to date'' | |
306 | by entering the event loop repeated until all pending events | |
307 | (including idle callbacks) have been processed. | |
308 | .Sp | |
309 | If the \fBidletasks\fR method is specified, then no new events or errors | |
310 | are processed; only idle callbacks are invoked. This causes operations | |
311 | that are normally deferred, such as display updates and window layout | |
312 | calculations, to be performed immediately. | |
313 | .Sp | |
314 | The \fBidletasks\fR command is useful in scripts where changes have been | |
315 | made to the application's state and you want those changes to appear | |
316 | on the display immediately, rather than waiting for the script to | |
317 | complete. Most display updates are performed as idle callbacks, so | |
318 | \&\fBidletasks\fR will cause them to run. However, there are some kinds of | |
319 | updates that only happen in response to events, such as those | |
320 | triggered by window size changes; these updates will not occur in | |
321 | \&\fBidletasks\fR. | |
322 | .IP "\fI$widget\fR\->\fBinterps\fR" 4 | |
323 | .IX Item "$widget->interps" | |
324 | Returns a list whose members are the names of all Tcl interpreters | |
325 | (e.g. all Tk-based applications) currently registered for | |
326 | a particular display. | |
327 | The return value refers | |
328 | to the display of \fI$widget\fR. | |
329 | .IP "\fI$widget\fR\->\fBismapped\fR" 4 | |
330 | .IX Item "$widget->ismapped" | |
331 | Returns \fB1\fR if \fI$widget\fR is currently mapped, \fB0\fR otherwise. | |
332 | .IP "\fI$widget\-\fR>\fBlower\fR(?\fIbelowThis\fR?)" 4 | |
333 | .IX Item "$widget->lower(?belowThis?)" | |
334 | If the \fIbelowThis\fR argument is omitted then the command lowers | |
335 | \&\f(CW$widget\fR so that it is below all of its siblings in the stacking | |
336 | order (it will be obscured by any siblings that overlap it and | |
337 | will not obscure any siblings). | |
338 | If \fIbelowThis\fR is specified then it must be the path name of | |
339 | a window that is either a sibling of \f(CW$widget\fR or the descendant | |
340 | of a sibling of \f(CW$widget\fR. | |
341 | In this case the \fBlower\fR command will insert | |
342 | \&\f(CW$widget\fR into the stacking order just below \fIbelowThis\fR | |
343 | (or the ancestor of \fIbelowThis\fR that is a sibling of \f(CW$widget\fR); | |
344 | this could end up either raising or lowering \f(CW$widget\fR. | |
345 | .IP "\fI$widget\fR\->\fBMapWindow\fR" 4 | |
346 | .IX Item "$widget->MapWindow" | |
347 | Cause \fI$widget\fR to be \*(L"mapped\*(R" i.e. made visible on the display. | |
348 | May confuse the geometry manager (pack, grid, place, ...) | |
349 | that thinks it is managing the widget. | |
350 | .IP "\fI$widget\fR\->\fBmanager\fR" 4 | |
351 | .IX Item "$widget->manager" | |
352 | Returns the name of the geometry manager currently | |
353 | responsible for \fI$widget\fR, or an empty string if \fI$widget\fR | |
354 | isn't managed by any geometry manager. | |
355 | The name is usually the name of the method for the geometry | |
356 | manager, such as \fBpack\fR or \fBplace\fR. | |
357 | If the geometry manager is a widget, such as canvases or text, the | |
358 | name is the widget's class command, such as \fBcanvas\fR. | |
359 | .IP "\fI$widget\fR\->\fBname\fR" 4 | |
360 | .IX Item "$widget->name" | |
361 | Returns \fI$widget\fR's name (i.e. its name within its parent, as opposed | |
362 | to its full path name). | |
363 | The command \fI$mainwin\fR\->\fBname\fR will return the name of the application. | |
364 | .IP "\fI$widget\fR\->\fBOnDestroy\fR(\fIcallback\fR);" 4 | |
365 | .IX Item "$widget->OnDestroy(callback);" | |
366 | OnDestroy accepts a standard perl/Tk \fIcallback\fR. | |
367 | When the window associated with \fI$widget\fR is destroyed then | |
368 | the callback is invoked. Unlike \fI$widget\-\fR>bind('<Destroy>',...) | |
369 | the widgets methods are still available when \fIcallback\fR is executed, | |
370 | so (for example) a \fBText\fR widget can save its contents to a file. | |
371 | .Sp | |
372 | OnDestroy was required for new \fBafter\fR mechanism. | |
373 | .IP "\fI$widget\fR\->\fBparent\fR" 4 | |
374 | .IX Item "$widget->parent" | |
375 | Returns \fI$widget\fR's parent, or an empty string | |
376 | if \fI$widget\fR is the main window of the application. | |
377 | .IP "\fI$widget\fR\->\fBPathName\fR" 4 | |
378 | .IX Item "$widget->PathName" | |
379 | Returns the tk path name of \fI$widget\fR. (This is an import from the | |
380 | C interface.) | |
381 | .IP "\fI$widget\fR\->\fBpathname\fR(\fIid\fR)" 4 | |
382 | .IX Item "$widget->pathname(id)" | |
383 | Returns an object whose X identifier is \fIid\fR. | |
384 | The identifier is looked up on the display of \fI$widget\fR. | |
385 | \&\fIId\fR must be a decimal, hexadecimal, or octal integer and must | |
386 | correspond to a window in the invoking application, or an error | |
387 | occurs which can be trapped with \f(CW\*(C`eval { }\*(C'\fR or \f(CW\*(C`Tk::catch { }\*(C'\fR. | |
388 | If the window belongs to the application, but is not an object | |
389 | (for example wrapper windows, HList header, etc.) then \f(CW\*(C`undef\*(C'\fR | |
390 | is returned. | |
391 | .IP "\fI$widget\fR\->\fBpixels\fR(\fInumber\fR)" 4 | |
392 | .IX Item "$widget->pixels(number)" | |
393 | Returns the number of pixels in \fI$widget\fR corresponding | |
394 | to the distance given by \fInumber\fR. | |
395 | \&\fINumber\fR may be specified in any of the forms acceptable | |
396 | to \fBTk_GetPixels\fR, such as ``2.0c'' or ``1i''. | |
397 | The result is rounded to the nearest integer value; for a | |
398 | fractional result, use \fI$widget\fR\->\fBfpixels\fR. | |
399 | .IP "\fI$widget\fR\->\fBpointerx\fR" 4 | |
400 | .IX Item "$widget->pointerx" | |
401 | If the mouse pointer is on the same screen as \fI$widget\fR, returns the | |
402 | pointer's x coordinate, measured in pixels in the screen's root window. | |
403 | If a virtual root window is in use on the screen, the position is | |
404 | measured in the virtual root. | |
405 | If the mouse pointer isn't on the same screen as \fI$widget\fR then | |
406 | \&\-1 is returned. | |
407 | .IP "\fI$widget\fR\->\fBpointerxy\fR" 4 | |
408 | .IX Item "$widget->pointerxy" | |
409 | If the mouse pointer is on the same screen as \fI$widget\fR, returns a list | |
410 | with two elements, which are the pointer's x and y coordinates measured | |
411 | in pixels in the screen's root window. | |
412 | If a virtual root window is in use on the screen, the position | |
413 | is computed in the virtual root. | |
414 | If the mouse pointer isn't on the same screen as \fI$widget\fR then | |
415 | both of the returned coordinates are \-1. | |
416 | .IP "\fI$widget\fR\->\fBpointery\fR" 4 | |
417 | .IX Item "$widget->pointery" | |
418 | If the mouse pointer is on the same screen as \fI$widget\fR, returns the | |
419 | pointer's y coordinate, measured in pixels in the screen's root window. | |
420 | If a virtual root window is in use on the screen, the position | |
421 | is computed in the virtual root. | |
422 | If the mouse pointer isn't on the same screen as \fI$widget\fR then | |
423 | \&\-1 is returned. | |
424 | .IP "\fI$widget\fR\->\fBraise\fR(?\fIaboveThis\fR?)" 4 | |
425 | .IX Item "$widget->raise(?aboveThis?)" | |
426 | If the \fIaboveThis\fR argument is omitted then the command raises | |
427 | \&\f(CW$widget\fR so that it is above all of its siblings in the stacking | |
428 | order (it will not be obscured by any siblings and will obscure | |
429 | any siblings that overlap it). | |
430 | If \fIaboveThis\fR is specified then it must be the path name of | |
431 | a window that is either a sibling of \f(CW$widget\fR or the descendant | |
432 | of a sibling of \f(CW$widget\fR. | |
433 | In this case the \fBraise\fR command will insert | |
434 | \&\f(CW$widget\fR into the stacking order just above \fIaboveThis\fR | |
435 | (or the ancestor of \fIaboveThis\fR that is a sibling of \f(CW$widget\fR); | |
436 | this could end up either raising or lowering \f(CW$widget\fR. | |
437 | .IP "\fI$widget\fR\->\fBreqheight\fR" 4 | |
438 | .IX Item "$widget->reqheight" | |
439 | Returns a decimal string giving \fI$widget\fR's requested height, | |
440 | in pixels. This is the value used by \fI$widget\fR's geometry | |
441 | manager to compute its geometry. | |
442 | .IP "\fI$widget\fR\->\fBreqwidth\fR" 4 | |
443 | .IX Item "$widget->reqwidth" | |
444 | Returns a decimal string giving \fI$widget\fR's requested width, | |
445 | in pixels. This is the value used by \fI$widget\fR's geometry | |
446 | manager to compute its geometry. | |
447 | .IP "\fI$widget\fR\->\fBrgb\fR(\fIcolor\fR)" 4 | |
448 | .IX Item "$widget->rgb(color)" | |
449 | Returns a list containing three decimal values, which are the | |
450 | red, green, and blue intensities that correspond to \fIcolor\fR in | |
451 | the window given by \fI$widget\fR. \fIColor\fR | |
452 | may be specified in any of the forms acceptable for a color | |
453 | option. | |
454 | .IP "\fI$widget\fR\->\fBrootx\fR" 4 | |
455 | .IX Item "$widget->rootx" | |
456 | Returns a decimal string giving the x\-coordinate, in the root | |
457 | window of the screen, of the | |
458 | upper-left corner of \fI$widget\fR's border (or \fI$widget\fR if it | |
459 | has no border). | |
460 | .IP "\fI$widget\fR\->\fBrooty\fR" 4 | |
461 | .IX Item "$widget->rooty" | |
462 | Returns a decimal string giving the y\-coordinate, in the root | |
463 | window of the screen, of the | |
464 | upper-left corner of \fI$widget\fR's border (or \fI$widget\fR if it | |
465 | has no border). | |
466 | .IP "\fBscaling\fR" 4 | |
467 | .IX Item "scaling" | |
468 | .PD 0 | |
469 | .IP "\fI$widget\fR\->\fBscaling\fR?(\fInumber\fR)?" 4 | |
470 | .IX Item "$widget->scaling?(number)?" | |
471 | .PD | |
472 | Sets and queries the current scaling factor used by Tk to convert between | |
473 | physical units (for example, points, inches, or millimeters) and pixels. The | |
474 | \&\fInumber\fR argument is a floating point number that specifies the number of | |
475 | pixels per point on \f(CW$widget\fR's display. If the \fInumber\fR argument is | |
476 | omitted, the current value of the scaling factor is returned. | |
477 | .Sp | |
478 | A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor | |
479 | of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard | |
480 | 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, | |
481 | which is the setting for a 90 dpi monitor; setting the scaling factor to | |
482 | 1.25 on a 72 dpi monitor would cause everything in the application to be | |
483 | displayed 1.25 times as large as normal. The initial value for the scaling | |
484 | factor is set when the application starts, based on properties of the | |
485 | installed monitor (as reported via the window system), | |
486 | but it can be changed at any time. Measurements made | |
487 | after the scaling factor is changed will use the new scaling factor, but it | |
488 | is undefined whether existing widgets will resize themselves dynamically to | |
489 | accomodate the new scaling factor. | |
490 | .IP "\fI$widget\fR\->\fBscreen\fR" 4 | |
491 | .IX Item "$widget->screen" | |
492 | Returns the name of the screen associated with \fI$widget\fR, in | |
493 | the form \fIdisplayName\fR.\fIscreenIndex\fR. | |
494 | .IP "\fI$widget\fR\->\fBscreencells\fR" 4 | |
495 | .IX Item "$widget->screencells" | |
496 | Returns a decimal string giving the number of cells in the default | |
497 | color map for \fI$widget\fR's screen. | |
498 | .IP "\fI$widget\fR\->\fBscreendepth\fR" 4 | |
499 | .IX Item "$widget->screendepth" | |
500 | Returns a decimal string giving the depth of the root window | |
501 | of \fI$widget\fR's screen (number of bits per pixel). | |
502 | .IP "\fI$widget\fR\->\fBscreenheight\fR" 4 | |
503 | .IX Item "$widget->screenheight" | |
504 | Returns a decimal string giving the height of \fI$widget\fR's screen, | |
505 | in pixels. | |
506 | .IP "\fI$widget\fR\->\fBscreenmmheight\fR" 4 | |
507 | .IX Item "$widget->screenmmheight" | |
508 | Returns a decimal string giving the height of \fI$widget\fR's screen, | |
509 | in millimeters. | |
510 | .IP "\fI$widget\fR\->\fBscreenmmwidth\fR" 4 | |
511 | .IX Item "$widget->screenmmwidth" | |
512 | Returns a decimal string giving the width of \fI$widget\fR's screen, | |
513 | in millimeters. | |
514 | .IP "\fI$widget\fR\->\fBscreenvisual\fR" 4 | |
515 | .IX Item "$widget->screenvisual" | |
516 | Returns one of the following strings to indicate the default visual | |
517 | class for \fI$widget\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, | |
518 | \&\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or | |
519 | \&\fBtruecolor\fR. | |
520 | .IP "\fI$widget\fR\->\fBscreenwidth\fR" 4 | |
521 | .IX Item "$widget->screenwidth" | |
522 | Returns a decimal string giving the width of \fI$widget\fR's screen, | |
523 | in pixels. | |
524 | .IP "\fI$widget\fR\->\fBserver\fR" 4 | |
525 | .IX Item "$widget->server" | |
526 | Returns a string containing information about the server for | |
527 | \&\fI$widget\fR's display. The exact format of this string may vary | |
528 | from platform to platform. For X servers the string | |
529 | has the form ``\fBX\fR\fImajor\fR\fBR\fR\fIminor vendor vendorVersion\fR'' | |
530 | where \fImajor\fR and \fIminor\fR are the version and revision | |
531 | numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR | |
532 | is the name of the vendor for the server, and \fIvendorRelease\fR | |
533 | is an integer release number provided by the server. | |
534 | .IP "\fI$widget\fR\->\fBtoplevel\fR" 4 | |
535 | .IX Item "$widget->toplevel" | |
536 | Returns the reference of the top-level window containing \fI$widget\fR. | |
537 | .IP "\fI$widget\fR\->\fBUnmapWindow\fR" 4 | |
538 | .IX Item "$widget->UnmapWindow" | |
539 | Cause \fI$widget\fR to be \*(L"unmapped\*(R" i.e. removed from the display. | |
540 | This does for any widget what \fI$widget\fR\->withdraw does for | |
541 | toplevel widgets. May confuse the geometry manager (pack, grid, place, ...) | |
542 | that thinks it is managing the widget. | |
543 | .IP "\fI$widget\fR\->\fBupdate\fR" 4 | |
544 | .IX Item "$widget->update" | |
545 | One of two methods which are used to bring the application ``up to date'' | |
546 | by entering the event loop repeated until all pending events | |
547 | (including idle callbacks) have been processed. | |
548 | .Sp | |
549 | The \fBupdate\fR method is useful in scripts where you are performing a | |
550 | long-running computation but you still want the application to respond | |
551 | to events such as user interactions; if you occasionally call | |
552 | \&\fBupdate\fR then user input will be processed during the next call to | |
553 | \&\fBupdate\fR. | |
554 | .IP "\fI$widget\fR\->\fBUnbusy\fR" 4 | |
555 | .IX Item "$widget->Unbusy" | |
556 | Restores widget state after a call to \fI$widget\fR\->\fBBusy\fR. | |
557 | .IP "\fI$widget\fR\->\fBviewable\fR" 4 | |
558 | .IX Item "$widget->viewable" | |
559 | Returns 1 if \fI$widget\fR and all of its ancestors up through the | |
560 | nearest toplevel window are mapped. Returns 0 if any of these | |
561 | windows are not mapped. | |
562 | .IP "\fI$widget\fR\->\fBvisual\fR" 4 | |
563 | .IX Item "$widget->visual" | |
564 | Returns one of the following strings to indicate the visual | |
565 | class for \fI$widget\fR: \fBdirectcolor\fR, \fBgrayscale\fR, | |
566 | \&\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or | |
567 | \&\fBtruecolor\fR. | |
568 | .IP "\fI$widget\fR\->\fBvisualid\fR" 4 | |
569 | .IX Item "$widget->visualid" | |
570 | Returns the X identifier for the visual for \f(CW$widget\fR. | |
571 | .IP "\fI$widget\fR\->\fBvisualsavailable\fR(?\fBincludeids\fR?)" 4 | |
572 | .IX Item "$widget->visualsavailable(?includeids?)" | |
573 | Returns a list whose elements describe the visuals available for | |
574 | \&\fI$widget\fR's screen. | |
575 | Each element consists of a visual class followed by an integer depth. | |
576 | The class has the same form as returned by \fI$widget\fR\->\fBvisual\fR. | |
577 | The depth gives the number of bits per pixel in the visual. | |
578 | In addition, if the \fBincludeids\fR argument is provided, then the | |
579 | depth is followed by the X identifier for the visual. | |
580 | .IP "\fI$widget\fR\->\fBvrootheight\fR" 4 | |
581 | .IX Item "$widget->vrootheight" | |
582 | Returns the height of the virtual root window associated with \fI$widget\fR | |
583 | if there is one; otherwise returns the height of \fI$widget\fR's screen. | |
584 | .IP "\fI$widget\fR\->\fBvrootwidth\fR" 4 | |
585 | .IX Item "$widget->vrootwidth" | |
586 | Returns the width of the virtual root window associated with \fI$widget\fR | |
587 | if there is one; otherwise returns the width of \fI$widget\fR's screen. | |
588 | .IP "\fI$widget\fR\->\fBvrootx\fR" 4 | |
589 | .IX Item "$widget->vrootx" | |
590 | Returns the x\-offset of the virtual root window associated with \fI$widget\fR, | |
591 | relative to the root window of its screen. | |
592 | This is normally either zero or negative. | |
593 | Returns 0 if there is no virtual root window for \fI$widget\fR. | |
594 | .IP "\fI$widget\fR\->\fBvrooty\fR" 4 | |
595 | .IX Item "$widget->vrooty" | |
596 | Returns the y\-offset of the virtual root window associated with \fI$widget\fR, | |
597 | relative to the root window of its screen. | |
598 | This is normally either zero or negative. | |
599 | Returns 0 if there is no virtual root window for \fI$widget\fR. | |
600 | .IP "\fI$widget\-\fR>\fBwaitVariable\fR(\e$\fIname\fR)" 4 | |
601 | .IX Item "$widget->waitVariable($name)" | |
602 | .PD 0 | |
603 | .IP "\fI$widget\-\fR>\fBwaitVisibility\fR" 4 | |
604 | .IX Item "$widget->waitVisibility" | |
605 | .IP "\fI$widget\-\fR>\fBwaitWindow\fR" 4 | |
606 | .IX Item "$widget->waitWindow" | |
607 | .PD | |
608 | The \fBtk wait\fR methods wait for one of several things to happen, | |
609 | then it returns without taking any other actions. | |
610 | The return value is always an empty string. | |
611 | \&\fBwaitVariable\fR expects a reference to a perl | |
612 | variable and the command waits for that variable to be modified. | |
613 | This form is typically used to wait for a user to finish interacting | |
614 | with a dialog which sets the variable as part (possibly final) | |
615 | part of the interaction. | |
616 | \&\fBwaitVisibility\fR waits for a change in \fI$widget\fR's | |
617 | visibility state (as indicated by the arrival of a VisibilityNotify | |
618 | event). This form is typically used to wait for a newly-created | |
619 | window to appear on the screen before taking some action. | |
620 | \&\fBwaitWindow\fR waits for \fI$widget\fR to be destroyed. | |
621 | This form is typically used to wait for a user to finish interacting | |
622 | with a dialog box before using the result of that interaction. | |
623 | Note that creating and destroying the window each time a dialog is required | |
624 | makes code modular but imposes overhead which can be avoided by \fBwithdrawing\fR | |
625 | the window instead and using \fBwaitVisibility\fR. | |
626 | .Sp | |
627 | While the \fBtk wait\fR methods are waiting they processes events in | |
628 | the normal fashion, so the application will continue to respond | |
629 | to user interactions. | |
630 | If an event handler invokes \fBtkwait\fR again, the nested call | |
631 | to \fBtkwait\fR must complete before the outer call can complete. | |
632 | .IP "\fI$widget\fR\->\fBwidth\fR" 4 | |
633 | .IX Item "$widget->width" | |
634 | Returns a decimal string giving \fI$widget\fR's width in pixels. | |
635 | When a window is first created its width will be 1 pixel; the | |
636 | width will eventually be changed by a geometry manager to fulfill | |
637 | the window's needs. | |
638 | If you need the true width immediately after creating a widget, | |
639 | invoke \fBupdate\fR to force the geometry manager to arrange it, | |
640 | or use \fI$widget\fR\->\fBreqwidth\fR to get the window's requested width | |
641 | instead of its actual width. | |
642 | .IP "\fI$widget\fR\->\fBx\fR" 4 | |
643 | .IX Item "$widget->x" | |
644 | Returns a decimal string giving the x\-coordinate, in \fI$widget\fR's | |
645 | parent, of the upper-left corner of \fI$widget\fR's border (or \fI$widget\fR | |
646 | if it has no border). | |
647 | .IP "\fI$widget\fR\->\fBy\fR" 4 | |
648 | .IX Item "$widget->y" | |
649 | Returns a decimal string giving the y\-coordinate, in \fI$widget\fR's | |
650 | parent, of the | |
651 | upper-left corner of \fI$widget\fR's border (or \fI$widget\fR if it | |
652 | has no border). | |
653 | .SH "CAVEATS" | |
654 | .IX Header "CAVEATS" | |
655 | The above documentaion on generic methods is incomplete. | |
656 | .SH "KEYWORDS" | |
657 | .IX Header "KEYWORDS" | |
658 | atom, children, class, geometry, height, identifier, information, interpreters, | |
659 | mapped, parent, path name, screen, virtual root, width, window |