Basic Widget Methods

Widget implementation class. This class is used as a mixin by all widget classes.

Registers an alarm callback that is called after a given time.

This method registers a callback function that will be called after a given number of milliseconds. tkinter only guarantees that the callback will not be called earlier than that; if the system is busy, the actual delay may be much longer.

The callback is only called once for each call to this method. To keep calling the callback, you need to reregister the callback inside itself:

class App:
    def __init__(self, master):
        self.master = master
        self.poll() # start polling

    def poll(self):
        ... do something ...
        self.master.after(100, self.poll)

You can also omit the callback. If you do, this method simply waits for the given number of milliseconds, without serving any events (same as time.sleep(delay_ms*0.001)).

delay_ms

Delay, in milliseconds.

callback

The callback. This can be any callable object.

*args

Optional arguments that are passed to the callback.

Returns:

An alarm identifier.

Cancels an alarm callback.

id

Alarm identifier.

Registers a callback that is called when the system is idle. The callback will be called there are no more events to process in the mainloop. The callback is only called once for each call to after_idle.

callback

The callback. This can be any callable object.

*args

Optional arguments that are passed to the callback.

Returns:

An alarm identifier.

The bbox method.

column

row

col2

row2

Generate a system-dependent sound (typically a short beep).

displayof

Adds an event binding to this widget. Usually, the new binding replaces any existing binding for the same event sequence. By passing in “+” as the third argument, the new callback is added to the existing binding.

Adds an event binding to the application level. Usually, the new binding replaces any existing binding for the same event sequence. By passing in “+” as the third argument, the new function is added to the existing binding.

Adds an event binding to the given widget class. Usually, the new binding replaces any existing binding for the same event sequence. By passing in “+” as the third argument, the new function is added to the existing binding.

Sets or gets the binding search order for this widget.

If called without an argument, this method returns a tuple containing the binding search order used for this widget. By default, this tuple contains the widget’s name (str(self)), the widget class (e.g. Button), the root window’s name, and finally the special name all which refers to the application level.

Returns the current value for an option.

Note that option values are always returned as strings (also if you gave a nonstring value when you configured the widget). Use int and float where appropriate.

Adds text to the clipboard.

string

The text to add.

**options

Clears the clipboard.

**options

The colormodel method.

value

The columnconfigure method.

index

cnf

**kw

Modifies one or more widget options.

If called without an argument, this method returns a dictionary containing the current settings for all widget options. For each option key in the dictionary, the value is either a five-tuple (option, option database key, option database class, default value, current value), or a two-tuple (option alias, option). The latter case is used for aliases like bg (background) and bd (borderwidth).

Note that the value fields aren’t correctly formatted for some option types. See the description of the keys method for more information, and a workaround.

Same as config.

The deletecommand method.

name

Destroys the widget. The widget is removed from the screen, and all resources associated with the widget are released.

The event_add method.

virtual

*sequences

The event_delete method.

virtual

*sequences

The event_generate method.

sequence

**kw

The event_info method.

virtual

The focus method.

The focus_displayof method.

The focus_force method.

The focus_get method.

The focus_lastfor method.

Moves the keyboard focus to this widget. This means that all keyboard events sent to the application will be routed to this widget.

(Internal) Converts a Tk string to a boolean (flag) value.

The getvar method.

name

The grab_current method.

Releases the event grab.

Routes all events for this application to this widget.

Routes all events for the entire screen to this widget.

This should only be used in very special circumstances, since it blocks all other applications running on the same screen. And that probably includes your development environment, so you better make sure your application won’t crash or lock up until it has properly released the grab.

The grab_status method.

The image_names method.

The image_types method.

Returns a tuple containing the options available for this widget. You can use cget to get the corresponding value for each option.

Note that the tuple currently include option aliases (like bd, bg, and fg). To avoid this, you can use config instead. On the other hand, config doesn’t return valid option values for some option types (such as font names), so the best way is to use a combination of config and cget:

for item in w.config():
    if len(item) == 5:
        option = item[0]
        value = w.cget(option)
        print option, value

Moves the widget to the top of the window stack. If the widget is a child window, it is moved to the top of it’s toplevel window. If it is a toplevel window (the root or a Toplevel window), it is moved in front of all other windows on the display. If an argument is given, the widget (or window) is moved so it’s just above the given widget (window).

Moves the window to the bottom of the window stack. Same as lift, but moves the widget to the bottom of the stack (or places it just under the belowThis widget).

Enters tkinter’s main event loop. To leave the event loop, use the quit method. Event loops can be nested; it’s ok to call mainloop from within an event handler.

Gets the widget object corresponding to a widget name.

name

The widget name.

Returns:

The corresponding widget object, if known.

Raises KeyError:

If the widget could not be found.

The option_add method.

pattern

value

priority

The option_clear method.

The option_get method.

name

className

The option_readfile method.

fileName

priority

The pack_propagate method.

flag

The pack_slaves method.

The place_slaves method.

The propagate method.

flag

The quit method.

Registers a Tcl to Python callback. Returns the name of a Tcl wrapper procedure. When that procedure is called from a Tcl program, it will call the corresponding Python function with the arguments given to the Tcl procedure. Values returned from the Python callback are converted to strings, and returned to the Tcl program.

The rowconfigure method.

index

cnf

**kw

The selection_clear method.

**kw

The selection_get method.

**kw

The selection_handle method.

command

**kw

The selection_own method.

**kw

The selection_own_get method.

**kw

The send method.

interp

cmd

*args

The setvar method.

name

value

The size method.

The slaves method.

The tk_bisque method.

The tk_focusFollowsMouse method.

Returns the next widget (following self) that should have focus. This is used by the default bindings for the Tab key.

Returns the previous widget (preceding self) that should have focus. This is used by the default bindings for the Shift-Tab key.

The tk_menuBar method.

*args

The tk_setPalette method.

*args

**kw

The tk_strictMotif method.

boolean

The tkraise method.

aboveThis

Removes any bindings for the given event sequence, for this widget.

The unbind_all method.

sequence

The unbind_class method.

className

sequence

Processes all pending events, calls event callbacks, completes any pending geometry management, redraws widgets as necessary, and calls all pending idle tasks. This method should be used with care, since it may lead to really nasty race conditions if called from the wrong place (from within an event callback, for example, or from a function that can in any way be called from an event callback, etc.). When in doubt, use update_idletasks instead.

Calls all pending idle tasks, without processing any other events. This can be used to carry out geometry management and redraw widgets if necessary, without calling any callbacks.

Waits for the given tkinter variable to change. This method enters a local event loop, so other parts of the application will still be responsive. The local event loop is terminated when the variable is updated (setting it to it’s current value also counts).

Wait for the given widget to become visible. This is typically used to wait until a new toplevel window appears on the screen. Like wait_variable, this method enters a local event loop, so other parts of the application will still work as usual.

Waits for the given widget to be destroyed. This is typically used to wait until a destroyed window disappears from the screen. Like wait_variable and wait_visibility, this method enters a local event loop, so other parts of the application will still work as usual.

The waitvar method.

name

Maps the given string to a unique integer. Every time you call this method with the same string, the same integer will be returned.

Returns the string corresponding to the given integer (obtained by a call to winfo_atom). If the integer isn’t in use, tkinter raises a TclError exception. Note that tkinter predefines a bunch of integers (typically 1-80 or so). If you’re curious, you can use this method to find out what they are used for.

Returns the number of “cells” in the color map for self. This is typically a value between 2 and 256 (also for true color displays, for some odd reason).

Returns a list containing widget instances for all children of this widget. The windows are returned in stacking order from bottom to top. If the order doesn’t matter, you can get the same information from the children widget attribute (it’s a dictionary mapping Tk widget names to widget instances, so widget.children.values() gives you a list of instances).

Returns the tkinter widget class name for this widget. If the widget is a tkinter base widget, widget.winfo_class() is the same as widget.__class__.__name__.

Returns true if the color map for this widget is full.

Returns the widget at the given position, or None if there is no such window, or it isn’t owned by this application. The coordinates are given relative to the screen’s upper left corner.

rootX

rootY

displayof

Returns the bit depth used to display this widget. This is typically 8 for a 256-color display device, 15 or 16 for a “hicolor” display, and 24 or 32 for a true color display.

Returns true if there is Tk window corresponding to this widget. Unless you’ve done something really strange, this method should always return true.

Converts the given distance (in any form accepted by tkinter) to the corresponding number of pixels.

distance

The screen distance.

Returns:

The corresponding number of screen pixels, as a floating point number.

Returns a string describing the widget’s “geometry”. The string has the following format:

"%dx%d%+d%+d" % (width, height, xoffset, yoffset)

Get the height of this widget, in pixels. Note that if the window isn’t managed by a geometry manager, this method returns 1. To you get the real value, you may have to call update_idletasks first. You can also use winfo_reqheight to get the widget’s requested height (that is, the “natural” size as defined by the widget itself based on it’s contents).

Returns:

The widget’s current height, in pixels.

Get a system-specific window identifier for this widget. For Unix, this is the X window identifier. For Windows, this is the HWND cast to a long integer.

Returns:

The window identifier.

The winfo_interps method.

displayof

Check if the window has been created. This method checks if tkinter has created a window corresponding to the widget in the underlying window system (an X window, a Windows HWND, etc).

Returns:

A true value if a window has been created.

Return the name of the geometry manager used to keep manage this widget (typically one of grid, pack, place, canvas, or text).

Get the Tk widget name. This is the same as the last part of the full widget name (which you can get via str(widget)).

Returns:

The widget name.

Get the full widget name of this widget’s parent. This method returns an empty string if the widget doesn’t have a parent (if it’s a root window or a toplevel, that is).

To get the widget instance instead, you can simply use the master attribute instead of calling this method (the master attribute is None for the root window). Or if you insist, use nametowidget to map the full widget name to a widget instance.

Returns:

The widget name, as a string.

Get the full window name for the window having the given identity (see winfo_id for details). If the window doesn’t exist, or it isn’t owned by this application, tkinter raises a TclError exception.

To convert the full name to a widget instance, use nametowidget.

id

The window identifier.

displayof

Convert the given distance (in any form accepted by tkinter) to the corresponding number of pixels.

distance

The screen distance.

Returns:

The corresponding number of screen pixels, as an integer.

The winfo_pointerx method.

The winfo_pointerxy method.

The winfo_pointery method.

Returns the “natural” height for this widget. The natural size is the minimal size needed to display the widget’s contents, including padding, borders, etc. This size is calculated by the widget itself, based on the given options. The actual widget size is then determined by the widget’s geometry manager, based on this value, the size of the widget’s master, and the options given to the geometry manager.

Returns the “natural” width for this widget. The natural size is the minimal size needed to display the widget’s contents, including padding, borders, etc. This size is calculated by the widget itself, based on the given options. The actual widget size is then determined by the widget’s geometry manager, based on this value, the size of the widget’s master, and the options given to the geometry manager.

Convert a color string (in any form accepted by tkinter) to an RGB tuple.

color

A colour string. This can be a colour name, a string containing an rgb specifier (“#rrggbb”), or any other syntax supported by tkinter.

Returns:

A 3-tuple containing the corresponding red, green, and blue components. Note that the tuple contains 16-bit values (0..65535).

Get the pixel coordinate for the widget’s left edge, relative to the screen’s upper left corner.

Returns:

The root coordinate.

Get the pixel coordinates for the widget’s upper edge, relative to the screen’s upper left corner.

Returns:

The root coordinate.

Get the X window screen name for the current window. The screen name is a string having the format “:display.screen”, where display and screen are decimal numbers.

On Windows and Macintosh, this is always “:0.0”.

Returns:

The screen name.

Get the number of “color cells” in the default color map for this widget’s screen.

Returns:

The number of color cells.

Get the default bit depth for this widget’s screen.

Returns:

The bit depth.

Get the height of this widget’s screen, in pixels.

Returns:

The height, in pixels.

Get the height of this widget’s screen, in millimetres. This may not be accurate on all platforms.

Returns:

The height, in millimetres.

Get the width of this widget’s screen, in millimetres. This may not be accurate on all platforms.

Returns:

The width, in millimetres.

Get the “visual” type used for this widget. This is typically “pseudocolor” (for 256-color displays) or “truecolor” (for 16- or 24-bit displays).

Returns:

A string containing the visual type. This is one of “pseudocolor”, “truecolor”, “directcolor”, “staticcolor”, “grayscale”, or “staticgray”.

Get the width of this widget’s screen, in pixels.

Returns:

The width, in pixels.

The winfo_server method.

Get the toplevel window (or root) window for this widget, as a widget instance.

Returns:

The toplevel parent widget. This is either a Tk instance, or a Toplevel instance.

The winfo_viewable method.

Same as winfo_screenvisual.

The winfo_visualid method.

The winfo_visualsavailable method.

includeids

The winfo_vrootheight method.

The winfo_vrootwidth method.

The winfo_vrootx method.

The winfo_vrooty method.

Get the width of this widget, in pixels. Note that if the window isn’t managed by a geometry manager, this method returns 1. To you get the real value, you may have to call update_idletasks first. You can also use winfo_reqwidth to get the widget’s requested width (that is, the “natural” size as defined by the widget itself based on it’s contents).

Returns:

The widget’s current width, in pixels.

Returns the pixel coordinates for the widgets’s left corner, relative to its parent’s left corner.

Returns the pixel coordinates for the widgets’s upper corner, relative to its parent’s upper corner.