[Python-checkins] r63172 - sandbox/trunk/ttk-gsoc/Doc/library/ttk.rst
guilherme.polo
python-checkins at python.org
Mon May 12 18:55:51 CEST 2008
Author: guilherme.polo
Date: Mon May 12 18:55:50 2008
New Revision: 63172
Log:
Reformatted the doc;
Documented Ttk Notebook, Progressbar, Separator and Sizegrip;
Updated Combobox and Widget docs;
Modified:
sandbox/trunk/ttk-gsoc/Doc/library/ttk.rst
Modified: sandbox/trunk/ttk-gsoc/Doc/library/ttk.rst
==============================================================================
--- sandbox/trunk/ttk-gsoc/Doc/library/ttk.rst (original)
+++ sandbox/trunk/ttk-gsoc/Doc/library/ttk.rst Mon May 12 18:55:50 2008
@@ -82,14 +82,21 @@
l1 = Ttk.Label(text="Test", style="BW.TLabel")
l2 = Ttk.Label(text="Test", style="BW.TLabel")
-
For more information about TtkStyling_ read the :class:`Style` class
documentation.
+Widget
+------
+
+:class:`Ttk.Widget` defines standard options and methods supported by Tk
+themed widgets.
-.. class:: Widget
- Accepts the following options:
+Standard Options
+^^^^^^^^^^^^^^^^
+
+:class:`Ttk.Widget` accepts the following options, aswell all the other Ttk
+widgets:
+-----------+--------------------------------------------------------------+
| Option | Description |
@@ -115,38 +122,82 @@
| style | May be used to specify a custom widget style |
+-----------+--------------------------------------------------------------+
- And the new methods:
- .. method:: identify(x, y)
+Scrollable Widget Options
+^^^^^^^^^^^^^^^^^^^^^^^^^
- Returns the name of the element at position *x* *y*, or the empty string
- if the point does not lie within any element.
+The following options are supported by widgets that are controlled by a
+scrollbar.
- *x* and *y* are pixel coordinates relative to the widget.
+ +----------------+-------------+
+ | option | description |
+ +================+=============+
+ | xscrollcommand | XXX |
+ +----------------+-------------+
+ | yscrollcommand | XXX |
+ +----------------+-------------+
- .. method:: instate(statespec[, callback=None[, *args]])
+Label Options
+^^^^^^^^^^^^^
- Test the widget's state. If a callback is not specified, returns 1
- if the widget state matches *statespec* and 0 otherwise. If callback
- is specified then it is called with args if widget state matches
- *statespec*.
+The following options are supported by labels, buttons and other button-like
+widgets.
+ +--------------+-----------------------------------------------------------+
+ | option | description |
+ +==============+===========================================================+
+ | text | Specifies a text string to be displayed inside the widget.|
+ +--------------+-----------------------------------------------------------+
+ | textvariable | Specifies a name whose value will be used in place of the |
+ | | text option resource. |
+ +--------------+-----------------------------------------------------------+
+ | underline | If set, specifies the index (0-based) of a character to |
+ | | underline in the text string. The underline character is |
+ | | used for mnemonic activation. |
+ +--------------+-----------------------------------------------------------+
+ | image | Specifies an image to display. This is a list of 1 or more|
+ | | elements. The first element is the default image name. The|
+ | | rest of the list if a sequence of statespec/value pairs as|
+ | | defined by :meth:`Style.map`, specifying different images |
+ | | to use when the widget is in a particular state or a |
+ | | combination of states. All images in the list should have |
+ | | the same size. |
+ +--------------+-----------------------------------------------------------+
+ | compound | Specifies how to display the image relative to the text, |
+ | | in the case both text and images options are present. |
+ | | Valid values are: |
+ | | |
+ | | * text: display text only |
+ | | * image: display image only |
+ | | * top, bottom, left, right: display image above, below, |
+ | | left of, or right of the text, respectively. |
+ | | * none: the default. display the image if present, |
+ | | otherwise the text. |
+ +--------------+-----------------------------------------------------------+
+ | width | If greather than zero, specifies how much space, in |
+ | | character widths, to allocate for the text label, if less |
+ | | than zero, specifies a minimum width. If zero or |
+ | | unspecified, the natural width of the text label is used. |
+ +--------------+-----------------------------------------------------------+
- .. method:: state([statespec=None])
- Modify or inquire widget state. If *statespec* is specified, sets the
- widget state according to it and return a new *statespec* indicating
- which flags were changed. If *statespec* is not specified, returns
- the currently-enabled state flags.
-
- Note that *statespec* is always expected to be a sequence.
+Compatibility Options
+^^^^^^^^^^^^^^^^^^^^^
+ +--------+----------------------------------------------------------------+
+ | option | description |
+ +========+================================================================+
+ | state | May be set to "normal" or "disabled" to control the "disabled" |
+ | | state bit. This is a write-only option: setting it changes the |
+ | | widget state, but the :meth:`Widget.state` method does not |
+ | | affect this option. |
+ +--------+----------------------------------------------------------------+
Widget States
^^^^^^^^^^^^^
- The widget state is a bitmap of independent state flags.
+The widget state is a bitmap of independent state flags.
+------------+-------------------------------------------------------------+
| flag | description |
@@ -175,20 +226,61 @@
| invalid | The widget's value is invalid |
+------------+-------------------------------------------------------------+
- A state specification is a sequence of state names, optionally prefixed with
- an exclamation point indicating that the bit is off.
+A state specification is a sequence of state names, optionally prefixed with
+an exclamation point indicating that the bit is off.
-New Widgets
-^^^^^^^^^^^
+Ttk.Widget
+^^^^^^^^^^
+
+Besides the methods described below, :class:`Ttk.Widget` supports the
+methods :meth:`Tkinter.Widget.cget` and :meth:`Tkinter.Widget.configure`.
+
+.. class:: Widget
-:class:`Combobox`, :class:`Notebook`, :class:`Progressbar`, :class:`Separator`, :class:`Sizegrip` and :class:`Treeview`.
+ .. method:: identify(x, y)
-.. class:: Combobox
+ Returns the name of the element at position *x* *y*, or the empty string
+ if the point does not lie within any element.
+
+ *x* and *y* are pixel coordinates relative to the widget.
+
+
+ .. method:: instate(statespec[, callback=None[, *args]])
+
+ Test the widget's state. If a callback is not specified, returns 1
+ if the widget state matches *statespec* and 0 otherwise. If callback
+ is specified then it is called with args if widget state matches
+ *statespec*.
+
+
+ .. method:: state([statespec=None])
+
+ Modify or inquire widget state. If *statespec* is specified, sets the
+ widget state according to it and return a new *statespec* indicating
+ which flags were changed. If *statespec* is not specified, returns
+ the currently-enabled state flags.
+
+ Note that *statespec* is always expected to be a sequence.
+
+
+Combobox
+--------
+
+Ttk Combobox widget combines a text field with a pop-down list of values,
+it inherits :class:`Entry`.
- Ttk Combobox widget combines a text field with a pop-down list of values,
- it inherits :class:`Entry`. This widget accepts the following specific
- options:
+Besides the methods inherited from :class:`Widget`: :meth:`Widget.cget`,
+:meth:`Widget.configure`, :meth:`Widget.identify`, :meth:`Widget.instate`
+and :meth:`Widget.state`, and the following inherited from :class:`Entry`:
+:meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`,
+:meth:`Entry.index`, :meth:`Entry.inset`, :meth:`Entry.selection`,
+:meth:`Entry.xview`, it has some other methods, described at `Ttk.Combobox`_.
+
+Options
+^^^^^^^
+
+This widget accepts the following specific options:
+-----------------+--------------------------------------------------------+
| option | description |
@@ -223,13 +315,18 @@
+-----------------+--------------------------------------------------------+
- Besides the methods inherited from :class:`Widget`: :meth:`Widget.cget`,
- :meth:`Widget.configure`, :meth:`Wiget.identify`, :meth:`Widget.instate`
- and :meth:`Widget.state`, and the following inherited from :class:`Entry`:
- :meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`,
- :meth:`Entry.index`, :meth:`Entry.inset`, :meth:`Entry.selection`,
- :meth:`Entry.xview`, it has these other methods:
+Virtual events
+^^^^^^^^^^^^^^
+
+The combobox widgets generates a **<<ComboboxSelected>>** virtual event
+when the user selects an element from the list of values.
+
+Ttk.Combobox
+^^^^^^^^^^^^
+
+.. class:: Combobox
+
.. method:: current([newindex=None])
If newindex is specified, sets the combobox value to the element position
@@ -247,22 +344,204 @@
Sets the value of the combobox to value.
- The combobox widgets generates a **<<ComboboxSelected>>** virtual event
- when the user selects an element from the list of values.
+Notebook
+--------
+
+Ttk Notebook widget manages a collection of windows and displays a single
+one at a time. Each child window is associated with a tab, which the user
+may select to change the currently-displayed window.
+
+Options
+^^^^^^^
+
+This widget accepts the following specific options:
+
+ +---------+----------------------------------------------------------------+
+ | option | description |
+ +=========+================================================================+
+ | height | If present and greater than zero, specifies the desired height |
+ | | of the pane area (not including internal padding or tabs). |
+ | | Otherwise, the maximum height of all panes is used. |
+ +---------+----------------------------------------------------------------+
+ | padding | Specifies the amount of extra space to add around the outside |
+ | | of the notebook. The padding is a list up to four length |
+ | | specifications left top right bottom. If fewer than four |
+ | | elements are specified, bottom defaults to top, right defaults |
+ | | to left, and top defaults to left. |
+ +---------+----------------------------------------------------------------+
+ | width | If present and greater than zero, specified the desired width |
+ | | of the pane area (not including internal padding). Otherwise, |
+ | | the maximum width of all panes is used. |
+ +---------+----------------------------------------------------------------+
+
+
+Tab Options
+^^^^^^^^^^^
+
+There are also specific options for tabs:
+
+ +-----------+--------------------------------------------------------------+
+ | option | description |
+ +===========+==============================================================+
+ | state | Either "normal", "disabled" or "hidden". If "disabled", then |
+ | | the tab is not selectable. If "hidden", then the tab is not |
+ | | shown. |
+ +-----------+--------------------------------------------------------------+
+ | sticky | Specifies how the child window is positioned within the pane |
+ | | area. Value is a string containing zero or more of the |
+ | | characteres "n", "s", "e" or "w". Each letter refers to a |
+ | | side (north, south, east or west) that the child window will |
+ | | stick to, as per the :meth:`grid` geometry manager. |
+ +-----------+--------------------------------------------------------------+
+ | padding | Specifies the amount of extra space to add between the |
+ | | notebook and this pane. Syntax is the same as for the option |
+ | | padding used by this widget. |
+ +-----------+--------------------------------------------------------------+
+ | text | Specifies a text to be displayed in the tab. |
+ +-----------+--------------------------------------------------------------+
+ | image | Specifies an image to display in the tab. See the option |
+ | | image described in :class:`Widget`. |
+ +-----------+--------------------------------------------------------------+
+ | compound | Specifies how to display the image relative to the text, in |
+ | | the case both options text and image are present. See |
+ | | label(n) for legal values. XXX |
+ +-----------+--------------------------------------------------------------+
+ | underline | Specifies the index (0-based) of a character to underline in |
+ | | the text string. The underlined character is used for |
+ | | mnemonic activation if :meth:`Notebook.enable_traversal` is |
+ | | called. |
+ +-----------+--------------------------------------------------------------+
+
+
+Tab Identifiers
+^^^^^^^^^^^^^^^
+
+The tab_id present in several methods of :class:`Ttk.Notebook` may take any
+of the following forms:
+
+* An integer between zero and the number of tabs
+* The name of a child window
+* A positional specification of the form "@x,y", which identifies the tab
+* The literal string "current", which identifies the currently-selected tab
+* The literal string "end", which returns the numer of tabs (only valid for
+ :meth:`Notebook.index`)
+
+
+Virtual Events
+^^^^^^^^^^^^^^
+
+This widget generates a **<<NotebookTabChanged>>** virtual event after a new
+tab is selected.
+
+
+Ttk.Notebook
+^^^^^^^^^^^^
.. class:: Notebook
+ .. method:: add(child, **kw)
-.. class:: Progressbar
+ Adds a new tab to the notebook.
+
+ If window is currently managed by the notebook but hidden, it is
+ restored to its previous position.
+
+ See `Tab Options`_ for the list of available options.
+
+
+ .. method:: forget(tab_id)
+
+ Removes the tab specified by *tab_id*, unmaps and unmanages the
+ associated window.
+
+
+ .. method:: hide(tab_id)
+
+ Hides the tab specified by *tab_id*.
+
+ The tab will not be displayed, but the associated window remains
+ managed by the notebook and its configuration remembered. Hidden tabs
+ may be restored with the add command.
+
+
+ .. method:: identify(x, y)
+
+ Returns the name of the tab element at position *x*, *y*, or the empty
+ string if none.
+
+
+ .. method:: index(tab_id)
+
+ Returns the numeric index of the tab specified by *tab_id*, or the total
+ number of tabs if *tab_id* is the string "end".
+
+
+ .. method:: insert(pos, child, **kw)
+
+ Inserts a pane at the specified position.
- Ttk Progressbar widget shows the status of a long-running operation. They
- can operate in two modes: determinate mode shows the amount completed
- relative to the total amount of work to be done, and indeterminate mode
- provides an animated display to let the user know that something is
- happening.
+ *pos* is either the string end, an integer index, or the name of a
+ managed child. If *child* is already managed by the notebook, moves it to
+ the specified positon.
- This widget accepts the following specific options:
+ See `Tab Options`_ for the list of available options.
+
+
+ .. method:: select([tab_id])
+
+ Selects the specified *tab_id*.
+
+ The associated child window will be displayed, and the
+ previously-selected window (if different) is unmapped. If *tab_id* is
+ omitted, returns the widget name of the currently selected pane.
+
+
+ .. method:: tab(tab_id, **kw)
+
+ Query or modify the options of the specific *tab_id*.
+
+ If no option is specified, returns a dictionary of the tab option values.
+ If one option is specified, returns the value of that option. Otherwise,
+ sets the options to the corresponding values.
+
+
+ .. method:: tabs()
+
+ Returns a list of windows managed by the notebook.
+
+
+ .. method:: enable_traversal()
+
+ Enable keyboard traversal for a toplevel window containing this notebook.
+
+ This will extend the bindings for the toplevel window containing the
+ notebook as follows:
+
+ * Control-Tab: selects the tab following the currently selected one
+ * Shift-Control-Tab: selects the tab preceding the currently selected one
+ * Alt-K: where K is the mnemonic (underlined) character of any tab, will
+ select that tab.
+
+ Multiple notebooks in a single toplevel may be enabled for traversal,
+ including nested notebooks. However, notebook traversal only works
+ properly if all panes have as master the notebook they are in.
+
+
+Progressbar
+-----------
+
+Ttk Progressbar widget shows the status of a long-running operation. They
+can operate in two modes: determinate mode shows the amount completed
+relative to the total amount of work to be done, and indeterminate mode
+provides an animated display to let the user know that something is
+happening.
+
+
+Options
+^^^^^^^
+
+This widget accepts the following specific options:
+----------+---------------------------------------------------------------+
| option | description |
@@ -294,7 +573,10 @@
+----------+---------------------------------------------------------------+
- And the following methods:
+Ttk.Progressbar
+^^^^^^^^^^^^^^^
+
+.. class:: Progressbar
.. method:: start([interval])
@@ -316,11 +598,18 @@
:meth:`Progressbar.start` for this progressbar.
-.. class:: Separator
+Separator
+---------
- Ttk Separator widget displays a horizontal or vertical separator bar.
+Ttk Separator widget displays a horizontal or vertical separator bar.
- This widget accepts the following specific option:
+It has no other method besides the ones inherited from :class:`Ttk.Widget`.
+
+
+Options
+^^^^^^^
+
+This widget accepts the following specific option:
+--------+----------------------------------------------------------------+
| option | description |
@@ -329,30 +618,40 @@
| | the separator. |
+--------+----------------------------------------------------------------+
- It has no specific methods.
-
-.. class:: Sizegrip
+Sizegrip
+--------
- Ttk Sizegrip widget (also known as grow box) allows the user to resize the
- containing toplevel window by pressing and dragging the grip.
+Ttk Sizegrip widget (also known as grow box) allows the user to resize the
+containing toplevel window by pressing and dragging the grip.
- This widget has no specific options neither specific methods,
+This widget has no specific options neither specific methods, besides the
+ones inherited from `Widget`_.
- Platform-specific notes:
- * On Mac OSX, toplevel windows automatically include a built-in size grip
- by default. Adding a Sizegrip there is harmless, since the built-in
- grip will just mask the widget.
+Platform-specific notes
+^^^^^^^^^^^^^^^^^^^^^^^
- Bugs:
+* On Mac OSX, toplevel windows automatically include a built-in size grip
+ by default. Adding a Sizegrip there is harmless, since the built-in
+ grip will just mask the widget.
+
+
+Bugs
+^^^^
- * If the containing toplevel's position was specified relative to the right
- or bottom of the screen (e.g. ....), the Sizegrip widget will not resize
- the window.
+* If the containing toplevel's position was specified relative to the right
+ or bottom of the screen (e.g. ....), the Sizegrip widget will not resize
+ the window.
+* This widget supports only "southeast" resizing.
+
+
+Treeview
+--------
- * This widget supports only "southeast" resizing.
+Ttk.Treeview
+^^^^^^^^^^^^
.. class:: Treeview
More information about the Python-checkins
mailing list