diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index b0421721bf8d7e..86075baadc6ad0 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -1266,11 +1266,19 @@ Base and mixin classes If *belowThis* is given, the widget is moved to be just below it in the stacking order instead. + :meth:`tkraise`/:meth:`lift` and :meth:`lower` are overridden by the + :class:`Canvas` widget, + where they restack canvas items instead. + .. method:: image_names() Return the names of all images that currently exist in the Tcl interpreter. + This is overridden by the :class:`Text` widget, + where :meth:`!image_names` returns the names of its embedded images + instead. + .. method:: image_types() Return the available image types, such as ``'photo'`` and ``'bitmap'``. @@ -1303,7 +1311,11 @@ Base and mixin classes column 0 to that cell; if *col2* and *row2* are also given, it spans from the cell (*column*, *row*) to the cell (*col2*, *row2*). - :meth:`bbox` is an alias of :meth:`!grid_bbox`. + :meth:`bbox` is an alias of :meth:`!grid_bbox`, + except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`, + :class:`Text`, :class:`ttk.Entry ` and + :class:`ttk.Treeview `, + which provide their own :meth:`!bbox` method. .. method:: columnconfigure(index, cnf={}, **kw) :no-typesetting: @@ -1378,7 +1390,9 @@ Base and mixin classes Return the size of the grid managed by this container as a ``(columns, rows)`` tuple. - :meth:`size` is an alias of :meth:`!grid_size`. + :meth:`size` is an alias of :meth:`!grid_size`, + except on the :class:`Listbox` widget, + which provides its own :meth:`!size` method. .. method:: grid_slaves(row=None, column=None) @@ -1681,7 +1695,10 @@ Base and mixin classes widget's display, the widget is remembered as the focus window for its top level, and the focus will be redirected to it the next time the window manager gives the focus to the top level. - :meth:`focus` is an alias of :meth:`!focus_set`. + :meth:`focus` is an alias of :meth:`!focus_set`, + except on the :class:`Canvas` and + :class:`ttk.Treeview ` widgets, + which provide their own :meth:`!focus` method. .. method:: focus_force() @@ -1783,6 +1800,10 @@ Base and mixin classes The *displayof* keyword argument names a widget that determines the display on which to operate, and defaults to this widget. + This is overridden by the :class:`Entry`, :class:`Listbox` and + :class:`Spinbox` widgets, + where :meth:`!selection_clear` clears the widget's own selection instead. + .. method:: selection_get(**kw) Return the contents of the current X selection. @@ -1860,7 +1881,7 @@ Base and mixin classes first and ``STRING`` is used as a fallback. The *displayof* keyword argument names a widget that determines the display, and defaults to the root window of the application. - This is equivalent to ``selection_get(selection= 'CLIPBOARD')``. + This is equivalent to ``selection_get(selection='CLIPBOARD')``. .. method:: option_add(pattern, value, priority=None) @@ -2546,6 +2567,8 @@ Base and mixin classes widget is managed again. :meth:`wm_forget` is an alias of :meth:`!forget`. + Not to be confused with :meth:`Pack.forget`. + .. versionadded:: 3.3 .. method:: wm_frame() @@ -2591,6 +2614,8 @@ Base and mixin classes string if the window is not gridded. :meth:`wm_grid` is an alias of :meth:`!grid`. + Not to be confused with the grid geometry manager :meth:`Grid.grid`. + .. method:: wm_group(pathName=None) :no-typesetting: @@ -2828,6 +2853,9 @@ Base and mixin classes :meth:`iconwindow`); the ``'icon'`` state cannot be set. :meth:`wm_state` is an alias of :meth:`!state`. + Not to be confused with :meth:`ttk.Widget.state + `. + .. method:: wm_title(string=None) :no-typesetting: @@ -2879,6 +2907,21 @@ Base and mixin classes *pack* geometry manager. See also :ref:`pack-the-packer`. + .. note:: + + :class:`Pack`, :class:`Place` and :class:`Grid` all define the short + method names :meth:`!forget`, :meth:`!info`, :meth:`!slaves`, + :meth:`!content` and :meth:`!propagate`. + On a widget the bare names resolve to the *pack* manager's versions, + since :class:`Pack` and :class:`Misc` precede :class:`Place` and + :class:`Grid` in the method resolution order, + whatever manager actually manages the widget; + and :meth:`!configure`/:meth:`!config` configure the widget's options, + not its geometry. + Use the explicit ``pack_*``, ``grid_*`` and ``place_*`` methods + (and ``pack``, ``grid``, ``place`` for geometry configuration) + to act on a specific geometry manager. + .. method:: configure(cnf={}, **kw) :no-typesetting: @@ -2941,7 +2984,13 @@ Base and mixin classes Unmap the widget and remove it from the packing order, forgetting its packing options. It can be packed again later with :meth:`pack_configure`. - :meth:`forget` is an alias of :meth:`!pack_forget`. + :meth:`forget` is an alias of :meth:`!pack_forget`, + except on :class:`PanedWindow`, + :class:`ttk.Notebook ` and + :class:`ttk.PanedWindow `, + which provide their own :meth:`!forget` method. + + Not to be confused with :meth:`Wm.forget`. .. method:: info() :no-typesetting: @@ -3048,7 +3097,6 @@ Base and mixin classes Unmap the widget and remove it from the placement, forgetting its place options. - :meth:`forget` is an alias of :meth:`!place_forget`. .. method:: info() :no-typesetting: @@ -3056,7 +3104,6 @@ Base and mixin classes .. method:: place_info() Return a dictionary of the widget's current place options. - :meth:`info` is an alias of :meth:`!place_info`. .. method:: slaves() :no-typesetting: @@ -3065,7 +3112,6 @@ Base and mixin classes Same as :meth:`Misc.place_slaves`: return the list of widgets placed in this widget. - :meth:`slaves` is an alias of :meth:`!place_slaves`. .. method:: content() :no-typesetting: @@ -3073,7 +3119,6 @@ Base and mixin classes .. method:: place_content() Same as :meth:`Misc.place_content`. - :meth:`content` is an alias of :meth:`!place_content`. .. versionadded:: 3.15 @@ -3095,6 +3140,9 @@ Base and mixin classes grid(cnf={}, **kw) Position the widget in a cell of its container's grid. + + Not to be confused with :meth:`Wm.grid`. + The supported options are: *row*, *column* @@ -3139,7 +3187,6 @@ Base and mixin classes Unmap the widget and remove it from the grid, forgetting its grid options. - :meth:`forget` is an alias of :meth:`!grid_forget`. .. method:: grid_remove() @@ -3152,7 +3199,6 @@ Base and mixin classes .. method:: grid_info() Return a dictionary of the widget's current grid options. - :meth:`info` is an alias of :meth:`!grid_info`. .. method:: bbox(column=None, row=None, col2=None, row2=None) :no-typesetting: @@ -3160,7 +3206,11 @@ Base and mixin classes .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) Same as :meth:`Misc.grid_bbox`. - :meth:`bbox` is an alias of :meth:`!grid_bbox`. + :meth:`bbox` is an alias of :meth:`!grid_bbox`, + except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`, + :class:`Text`, :class:`ttk.Entry ` and + :class:`ttk.Treeview `, + which provide their own :meth:`!bbox` method. .. method:: columnconfigure(index, cnf={}, **kw) :no-typesetting: @@ -3196,7 +3246,9 @@ Base and mixin classes Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving the size of the grid. - :meth:`size` is an alias of :meth:`!grid_size`. + :meth:`size` is an alias of :meth:`!grid_size`, + except on the :class:`Listbox` widget, + which provides its own :meth:`!size` method. .. method:: propagate() propagate(flag) @@ -3206,7 +3258,6 @@ Base and mixin classes grid_propagate(flag) Same as :meth:`Misc.grid_propagate`. - :meth:`propagate` is an alias of :meth:`!grid_propagate`. .. method:: slaves(row=None, column=None) :no-typesetting: @@ -3215,7 +3266,6 @@ Base and mixin classes Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid, optionally restricted to a *row* and/or *column*. - :meth:`slaves` is an alias of :meth:`!grid_slaves`. .. method:: content(row=None, column=None) :no-typesetting: @@ -3223,7 +3273,6 @@ Base and mixin classes .. method:: grid_content(row=None, column=None) Same as :meth:`Misc.grid_content`. - :meth:`content` is an alias of :meth:`!grid_content`. .. versionadded:: 3.15 @@ -3825,6 +3874,14 @@ Widget classes This has no effect on embedded window items. :meth:`lower` is an alias of :meth:`!tag_lower`. + .. note:: + + On a :class:`Canvas`, :meth:`tkraise`/:meth:`lift` and :meth:`lower` + restack canvas items, + shadowing the inherited :meth:`Misc.tkraise`/:meth:`Misc.lift` and + :meth:`Misc.lower` methods that restack the widget itself, + which are therefore not available. + .. method:: tag_bind(tagOrId, sequence=None, func=None, add=None) Bind the callback *func* to the event *sequence* for all items given by @@ -3860,6 +3917,9 @@ Widget classes Return ``None`` if no item matches or the matching items have nothing to display. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~Misc.grid_bbox` for the grid bounding box. + .. method:: canvasx(screenx, gridspacing=None) Given a window x-coordinate *screenx*, return the canvas x-coordinate @@ -3886,6 +3946,9 @@ Widget classes An item only displays the insertion cursor when both it is the focus item and its canvas has the input focus. + This shadows the inherited :meth:`!Misc.focus`; + use :meth:`~Misc.focus_set` to focus the widget itself. + .. method:: icursor(tagOrId, index, /) Set the insertion cursor of the items given by *tagOrId* to just before @@ -4083,6 +4146,12 @@ Widget classes If the selection is not in this widget the method has no effect. :meth:`select_clear` is an alias of :meth:`!selection_clear`. + .. note:: + + This shadows the inherited :meth:`Misc.selection_clear`, + which clears the X selection; + that method is not available on an :class:`Entry`. + .. method:: select_from(index) :no-typesetting: @@ -4222,6 +4291,9 @@ Widget classes Return the total number of items in the listbox. + This shadows the inherited :meth:`!Misc.size`; + use :meth:`~Misc.grid_size` for the grid size. + .. method:: index(index) Return the integer index value corresponding to *index*, or ``None`` if @@ -4238,6 +4310,9 @@ Widget classes visible, the result still gives the full area of the item, including the parts that are not visible. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~Misc.grid_bbox` for the grid bounding box. + .. method:: nearest(y) Given a y-coordinate within the listbox window, return the index of the @@ -4286,6 +4361,12 @@ Widget classes The selection state of items outside this range is not changed. :meth:`select_clear` is an alias of :meth:`!selection_clear`. + .. note:: + + This shadows the inherited :meth:`Misc.selection_clear`, + which clears the X selection; + that method is not available on a :class:`Listbox`. + .. method:: select_includes(index) :no-typesetting: @@ -4670,6 +4751,9 @@ Widget classes Remove the pane containing *child* from the panedwindow. All geometry management options for *child* are forgotten. :meth:`forget` is an alias of :meth:`!remove`. + This shadows the inherited geometry-manager :meth:`!forget`; + use :meth:`~Pack.pack_forget`, :meth:`~Grid.grid_forget` or + :meth:`~Place.place_forget` to remove the widget itself from its manager. .. method:: panes() @@ -4961,6 +5045,9 @@ Widget classes The bounding box may refer to a region outside the visible area of the window. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~Misc.grid_bbox` for the grid bounding box. + .. method:: identify(x, y) Return the name of the window element at the pixel coordinates *x*, *y*: @@ -5022,6 +5109,12 @@ Widget classes Clear the selection if it is currently in this widget. If the selection is not in this widget, the method has no effect. + .. note:: + + This shadows the inherited :meth:`Misc.selection_clear`, + which clears the X selection; + that method is not available on a :class:`Spinbox`. + .. method:: selection_element(element=None) Set or get the currently selected element. @@ -5179,6 +5272,9 @@ Widget classes pixels, of the visible part of the character at *index*, or ``None`` if that character is not visible on the screen. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~Misc.grid_bbox` for the grid bounding box. + .. method:: dlineinfo(index) Return a tuple ``(x, y, width, height, baseline)`` describing the display @@ -5433,6 +5529,12 @@ Widget classes Return a tuple of the names of all images embedded in the widget. + .. note:: + + This shadows the inherited :meth:`Misc.image_names`, + which returns the names of all images in the Tcl interpreter; + that method is not available on a :class:`Text`. + .. method:: window_create(index, cnf={}, **kw) Embed a window (any widget) at *index*. @@ -5641,6 +5743,7 @@ Variable classes .. method:: set(value) Set the variable to *value*. + :meth:`initialize` is an alias of :meth:`!set`. .. versionadded:: 3.3 The *initialize* spelling. @@ -5687,6 +5790,7 @@ Variable classes *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for read, write or unset. Return the internal name of the registered callback. + :meth:`trace` is an alias of :meth:`!trace_variable`. .. deprecated:: 3.6 Use :meth:`trace_add` instead. This method wraps a Tcl feature that @@ -5758,6 +5862,7 @@ Variable classes .. method:: set(value) Set the variable to *value*, converting it to a boolean. + :meth:`initialize` is an alias of :meth:`!set`. .. versionadded:: 3.3 The *initialize* spelling. diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index 9d90770a5840ee..0f5a8da1445784 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -289,6 +289,8 @@ the methods :meth:`tkinter.Widget.cget ` and which flags were changed. If *statespec* is not specified, returns the currently enabled state flags. + Not to be confused with :meth:`Wm.state `. + *statespec* will usually be a list or a tuple. @@ -590,6 +592,11 @@ ttk.Notebook Removes the tab specified by *tab_id*, unmaps and unmanages the associated window. + This shadows the inherited geometry-manager :meth:`!forget`; + use :meth:`~tkinter.Pack.pack_forget`, :meth:`~tkinter.Grid.grid_forget` + or :meth:`~tkinter.Place.place_forget` to remove the widget itself from + its manager. + .. method:: hide(tab_id) @@ -988,6 +995,9 @@ ttk.Treeview *item* is not visible (that is, if it is a descendant of a closed item or is scrolled offscreen), returns an empty string. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~tkinter.Misc.grid_bbox` for the grid bounding box. + .. method:: get_children(item=None) @@ -1061,6 +1071,9 @@ ttk.Treeview If *item* is specified, sets the focus item to *item*. Otherwise, returns the current focus item, or '' if there is none. + This shadows the inherited :meth:`!Misc.focus`; + use :meth:`~tkinter.Misc.focus_set` to focus the widget itself. + .. method:: heading(column, option=None, **kw) @@ -1681,6 +1694,9 @@ and inherits the common methods of :class:`Widget`. Return a tuple ``(x, y, width, height)`` giving the bounding box of the character at the given *index*. + This shadows the inherited :meth:`!Misc.bbox`; + use :meth:`~tkinter.Misc.grid_bbox` for the grid bounding box. + .. method:: identify(x, y) Return the name of the element under the point given by *x* and *y*, or @@ -1774,6 +1790,11 @@ and inherits the common methods of :class:`Widget`. Remove *child*, which may be either an integer index or the name of a managed subwindow, from the panes. + This shadows the inherited geometry-manager :meth:`!forget`; + use :meth:`~tkinter.Pack.pack_forget`, :meth:`~tkinter.Grid.grid_forget` + or :meth:`~tkinter.Place.place_forget` to remove the widget itself from + its manager. + .. method:: pane(pane, option=None, **kw) Query or modify the options of the specified *pane*, where *pane* is diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py index ba8365f56c37a7..b0152778cb5485 100644 --- a/Lib/tkinter/__init__.py +++ b/Lib/tkinter/__init__.py @@ -3011,7 +3011,7 @@ def addtag_withtag(self, newtag, tagOrId): """Add tag NEWTAG to all items with TAGORID.""" self.addtag(newtag, 'withtag', tagOrId) - def bbox(self, *args): + def bbox(self, *args): # overrides Misc.bbox """Return a tuple of X1,Y1,X2,Y2 coordinates for a rectangle which encloses all items with tags specified as arguments.""" return self._getints( @@ -3150,7 +3150,7 @@ def find_withtag(self, tagOrId): """Return all items with TAGORID.""" return self.find('withtag', tagOrId) - def focus(self, *args): + def focus(self, *args): # overrides Misc.focus """Set focus to the first item specified in ARGS.""" return self.tk.call((self._w, 'focus') + args) @@ -3196,7 +3196,7 @@ def tag_lower(self, *args): (optional below another item).""" self.tk.call((self._w, 'lower') + args) - lower = tag_lower + lower = tag_lower # overrides Misc.lower def move(self, *args): """Move an item TAGORID given in ARGS.""" @@ -3224,7 +3224,7 @@ def tag_raise(self, *args): (optional above another item).""" self.tk.call((self._w, 'raise') + args) - lift = tkraise = tag_raise + lift = tkraise = tag_raise # overrides Misc.tkraise def scale(self, *args): """Scale item TAGORID with XORIGIN, YORIGIN, XSCALE, YSCALE.""" @@ -3369,7 +3369,7 @@ def selection_adjust(self, index): select_adjust = selection_adjust - def selection_clear(self): + def selection_clear(self): # overrides Misc.selection_clear """Clear the selection if it is in this widget.""" self.tk.call(self._w, 'selection', 'clear') @@ -3463,7 +3463,7 @@ def activate(self, index): """Activate item identified by INDEX.""" self.tk.call(self._w, 'activate', index) - def bbox(self, index): + def bbox(self, index): # overrides Misc.bbox """Return a tuple of X1,Y1,X2,Y2 coordinates for a rectangle which encloses the item identified by the given index.""" return self._getints(self.tk.call(self._w, 'bbox', index)) or None @@ -3519,7 +3519,7 @@ def selection_anchor(self, index): select_anchor = selection_anchor - def selection_clear(self, first, last=None): + def selection_clear(self, first, last=None): # overrides Misc.selection_clear """Clear the selection from FIRST to LAST (included).""" self.tk.call(self._w, 'selection', 'clear', first, last) @@ -3540,7 +3540,7 @@ def selection_set(self, first, last=None): select_set = selection_set - def size(self): + def size(self): # overrides Misc.size """Return the number of elements in the listbox.""" return self.tk.getint(self.tk.call(self._w, 'size')) @@ -3856,7 +3856,7 @@ def __init__(self, master=None, cnf={}, **kw): """ Widget.__init__(self, master, 'text', cnf, kw) - def bbox(self, index): + def bbox(self, index): # overrides Misc.bbox """Return a tuple of (x,y,width,height) which gives the bounding box of the visible part of the character at the given index.""" return self._getints( @@ -4041,7 +4041,7 @@ def image_create(self, index, cnf={}, **kw): self._w, "image", "create", index, *self._options(cnf, kw)) - def image_names(self): + def image_names(self): # overrides Misc.image_names """Return all names of embedded images in this widget.""" return self.tk.call(self._w, "image", "names") @@ -4716,7 +4716,7 @@ def __init__(self, master=None, cnf={}, **kw): """ Widget.__init__(self, master, 'spinbox', cnf, kw) - def bbox(self, index): + def bbox(self, index): # overrides Misc.bbox """Return a tuple of X1,Y1,X2,Y2 coordinates for a rectangle which encloses the character given by index. @@ -4825,7 +4825,7 @@ def selection_adjust(self, index): """ return self.selection("adjust", index) - def selection_clear(self): + def selection_clear(self): # overrides Misc.selection_clear """Clear the selection If the selection isn't in this widget then the @@ -4922,7 +4922,7 @@ def remove(self, child): """ self.tk.call(self._w, 'forget', child) - forget = remove + forget = remove # overrides Pack.forget def identify(self, x, y): """Identify the panedwindow component at point x, y diff --git a/Lib/tkinter/ttk.py b/Lib/tkinter/ttk.py index 5c5ef11ae05ba6..cb66420d1cd129 100644 --- a/Lib/tkinter/ttk.py +++ b/Lib/tkinter/ttk.py @@ -646,7 +646,7 @@ def __init__(self, master=None, widget=None, **kw): Widget.__init__(self, master, widget or "ttk::entry", kw) - def bbox(self, index): + def bbox(self, index): # overrides Misc.bbox """Return a tuple of (x, y, width, height) which describes the bounding box of the character given by index.""" return self._getints(self.tk.call(self._w, "bbox", index)) @@ -824,7 +824,7 @@ def add(self, child, **kw): self.tk.call(self._w, "add", child, *(_format_optdict(kw))) - def forget(self, tab_id): + def forget(self, tab_id): # overrides Pack.forget """Removes the tab specified by tab_id, unmaps and unmanages the associated window.""" self.tk.call(self._w, "forget", tab_id) @@ -1187,7 +1187,7 @@ def __init__(self, master=None, **kw): Widget.__init__(self, master, "ttk::treeview", kw) - def bbox(self, item, column=None): + def bbox(self, item, column=None): # overrides Misc.bbox """Returns the bounding box (relative to the treeview widget's window) of the specified item in the form x y width height. @@ -1246,7 +1246,7 @@ def exists(self, item): return self.tk.getboolean(self.tk.call(self._w, "exists", item)) - def focus(self, item=None): + def focus(self, item=None): # overrides Misc.focus """If item is specified, sets the focus item to item. Otherwise, returns the current focus item, or '' if there is none.""" return self.tk.call(self._w, "focus", item)