1Widget(3)             User Contributed Perl Documentation            Widget(3)
2
3
4

NAME

6       Tk::Widget - Base class of all widgets
7

SYNOPSIS

9          package Tk::Whatever;
10          require Tk::Widget;
11          @ISA = qw(Tk::Widget);
12          Construct Tk::Widget 'Whatever';
13
14          sub Tk_cmd { \&Tk::whatever }
15
16          $widget->method(?arg, arg, ...?)
17

DESCRIPTION

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

CAVEATS

551       The above documentaion on generic methods is incomplete.
552

KEYWORDS

554       atom, children, class, geometry, height, identifier, information,
555       interpreters, mapped, parent, path name, screen, virtual root, width,
556       window
557
558
559
560perl v5.38.0                      2023-07-21                         Widget(3)
Impressum