• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`tkinter.tix` --- Extension widgets for Tk
2===============================================
3
4.. module:: tkinter.tix
5   :synopsis: Tk Extension Widgets for Tkinter
6
7.. sectionauthor:: Mike Clarkson <mikeclarkson@users.sourceforge.net>
8
9**Source code:** :source:`Lib/tkinter/tix.py`
10
11.. index:: single: Tix
12
13.. deprecated:: 3.6
14   This Tk extension is unmaintained and should not be used in new code.  Use
15   :mod:`tkinter.ttk` instead.
16
17--------------
18
19The :mod:`tkinter.tix` (Tk Interface Extension) module provides an additional
20rich set of widgets. Although the standard Tk library has many useful widgets,
21they are far from complete. The :mod:`tkinter.tix` library provides most of the
22commonly needed widgets that are missing from standard Tk: :class:`HList`,
23:class:`ComboBox`, :class:`Control` (a.k.a. SpinBox) and an assortment of
24scrollable widgets.
25:mod:`tkinter.tix` also includes many more widgets that are generally useful in
26a wide range of applications: :class:`NoteBook`, :class:`FileEntry`,
27:class:`PanedWindow`, etc; there are more than 40 of them.
28
29With all these new widgets, you can introduce new interaction techniques into
30applications, creating more useful and more intuitive user interfaces. You can
31design your application by choosing the most appropriate widgets to match the
32special needs of your application and users.
33
34.. seealso::
35
36   `Tix Homepage <http://tix.sourceforge.net/>`_
37      The home page for :mod:`Tix`.  This includes links to additional documentation
38      and downloads.
39
40   `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_
41      On-line version of the man pages and reference material.
42
43   `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_
44      On-line version of the programmer's reference material.
45
46   `Tix Development Applications <http://tix.sourceforge.net/Tixapps/src/Tide.html>`_
47      Tix applications for development of Tix and Tkinter programs. Tide applications
48      work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to
49      remotely modify and debug Tix/Tk/Tkinter applications.
50
51
52Using Tix
53---------
54
55
56.. class:: Tk(screenName=None, baseName=None, className='Tix')
57
58   Toplevel widget of Tix which represents mostly the main window of an
59   application. It has an associated Tcl interpreter.
60
61   Classes in the :mod:`tkinter.tix` module subclasses the classes in the
62   :mod:`tkinter`. The former imports the latter, so to use :mod:`tkinter.tix`
63   with Tkinter, all you need to do is to import one module. In general, you
64   can just import :mod:`tkinter.tix`, and replace the toplevel call to
65   :class:`tkinter.Tk` with :class:`tix.Tk`::
66
67      from tkinter import tix
68      from tkinter.constants import *
69      root = tix.Tk()
70
71To use :mod:`tkinter.tix`, you must have the Tix widgets installed, usually
72alongside your installation of the Tk widgets. To test your installation, try
73the following::
74
75   from tkinter import tix
76   root = tix.Tk()
77   root.tk.eval('package require Tix')
78
79
80Tix Widgets
81-----------
82
83`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_
84introduces over 40 widget classes to the :mod:`tkinter` repertoire.
85
86
87Basic Widgets
88^^^^^^^^^^^^^
89
90
91.. class:: Balloon()
92
93   A `Balloon
94   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that
95   pops up over a widget to provide help.  When the user moves the cursor inside a
96   widget to which a Balloon widget has been bound, a small pop-up window with a
97   descriptive message will be shown on the screen.
98
99.. Python Demo of:
100.. \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
101
102
103.. class:: ButtonBox()
104
105   The `ButtonBox
106   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_
107   widget creates a box of buttons, such as is commonly used for ``Ok Cancel``.
108
109.. Python Demo of:
110.. \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
111
112
113.. class:: ComboBox()
114
115   The `ComboBox
116   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_
117   widget is similar to the combo box control in MS Windows. The user can select a
118   choice by either typing in the entry subwidget or selecting from the listbox
119   subwidget.
120
121.. Python Demo of:
122.. \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
123
124
125.. class:: Control()
126
127   The `Control
128   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_
129   widget is also known as the :class:`SpinBox` widget. The user can adjust the
130   value by pressing the two arrow buttons or by entering the value directly into
131   the entry. The new value will be checked against the user-defined upper and
132   lower limits.
133
134.. Python Demo of:
135.. \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
136
137
138.. class:: LabelEntry()
139
140   The `LabelEntry
141   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_
142   widget packages an entry widget and a label into one mega widget. It can
143   be used to simplify the creation of "entry-form" type of interface.
144
145.. Python Demo of:
146.. \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
147
148
149.. class:: LabelFrame()
150
151   The `LabelFrame
152   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_
153   widget packages a frame widget and a label into one mega widget.  To create
154   widgets inside a LabelFrame widget, one creates the new widgets relative to the
155   :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget.
156
157.. Python Demo of:
158.. \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
159
160
161.. class:: Meter()
162
163   The `Meter
164   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget
165   can be used to show the progress of a background job which may take a long time
166   to execute.
167
168.. Python Demo of:
169.. \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
170
171
172.. class:: OptionMenu()
173
174   The `OptionMenu
175   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_
176   creates a menu button of options.
177
178.. Python Demo of:
179.. \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
180
181
182.. class:: PopupMenu()
183
184   The `PopupMenu
185   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_
186   widget can be used as a replacement of the ``tk_popup`` command. The advantage
187   of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code
188   to manipulate.
189
190.. Python Demo of:
191.. \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
192
193
194.. class:: Select()
195
196   The `Select
197   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget
198   is a container of button subwidgets. It can be used to provide radio-box or
199   check-box style of selection options for the user.
200
201.. Python Demo of:
202.. \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
203
204
205.. class:: StdButtonBox()
206
207   The `StdButtonBox
208   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_
209   widget is a group of standard buttons for Motif-like dialog boxes.
210
211.. Python Demo of:
212.. \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
213
214
215File Selectors
216^^^^^^^^^^^^^^
217
218
219.. class:: DirList()
220
221   The `DirList
222   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_
223   widget displays a list view of a directory, its previous directories and its
224   sub-directories. The user can choose one of the directories displayed in the
225   list or change to another directory.
226
227.. Python Demo of:
228.. \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
229
230
231.. class:: DirTree()
232
233   The `DirTree
234   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_
235   widget displays a tree view of a directory, its previous directories and its
236   sub-directories. The user can choose one of the directories displayed in the
237   list or change to another directory.
238
239.. Python Demo of:
240.. \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
241
242
243.. class:: DirSelectDialog()
244
245   The `DirSelectDialog
246   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm>`_
247   widget presents the directories in the file system in a dialog window.  The user
248   can use this dialog window to navigate through the file system to select the
249   desired directory.
250
251.. Python Demo of:
252.. \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
253
254
255.. class:: DirSelectBox()
256
257   The :class:`DirSelectBox` is similar to the standard Motif(TM)
258   directory-selection box. It is generally used for the user to choose a
259   directory.  DirSelectBox stores the directories mostly recently selected into
260   a ComboBox widget so that they can be quickly selected again.
261
262
263.. class:: ExFileSelectBox()
264
265   The `ExFileSelectBox
266   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm>`_
267   widget is usually embedded in a tixExFileSelectDialog widget. It provides a
268   convenient method for the user to select files. The style of the
269   :class:`ExFileSelectBox` widget is very similar to the standard file dialog on
270   MS Windows 3.1.
271
272.. Python Demo of:
273.. \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
274
275
276.. class:: FileSelectBox()
277
278   The `FileSelectBox
279   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_
280   is similar to the standard Motif(TM) file-selection box. It is generally used
281   for the user to choose a file. FileSelectBox stores the files mostly recently
282   selected into a :class:`ComboBox` widget so that they can be quickly selected
283   again.
284
285.. Python Demo of:
286.. \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
287
288
289.. class:: FileEntry()
290
291   The `FileEntry
292   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_
293   widget can be used to input a filename. The user can type in the filename
294   manually. Alternatively, the user can press the button widget that sits next to
295   the entry, which will bring up a file selection dialog.
296
297.. Python Demo of:
298.. \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
299
300
301Hierarchical ListBox
302^^^^^^^^^^^^^^^^^^^^
303
304
305.. class:: HList()
306
307   The `HList
308   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget
309   can be used to display any data that have a hierarchical structure, for example,
310   file system directory trees. The list entries are indented and connected by
311   branch lines according to their places in the hierarchy.
312
313.. Python Demo of:
314.. \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
315
316
317.. class:: CheckList()
318
319   The `CheckList
320   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_
321   widget displays a list of items to be selected by the user. CheckList acts
322   similarly to the Tk checkbutton or radiobutton widgets, except it is capable of
323   handling many more items than checkbuttons or radiobuttons.
324
325.. Python Demo of:
326.. \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
327.. Python Demo of:
328.. \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
329.. Python Demo of:
330.. \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
331
332
333.. class:: Tree()
334
335   The `Tree
336   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget
337   can be used to display hierarchical data in a tree form. The user can adjust the
338   view of the tree by opening or closing parts of the tree.
339
340.. Python Demo of:
341.. \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
342.. Python Demo of:
343.. \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
344
345
346Tabular ListBox
347^^^^^^^^^^^^^^^
348
349
350.. class:: TList()
351
352   The `TList
353   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget
354   can be used to display data in a tabular format. The list entries of a
355   :class:`TList` widget are similar to the entries in the Tk listbox widget.  The
356   main differences are (1) the :class:`TList` widget can display the list entries
357   in a two dimensional format and (2) you can use graphical images as well as
358   multiple colors and fonts for the list entries.
359
360.. Python Demo of:
361.. \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
362.. Python Demo of:
363.. \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
364.. Grid has yet to be added to Python
365.. \subsubsection{Grid Widget}
366.. Python Demo of:
367.. \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
368.. Python Demo of:
369.. \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
370.. Python Demo of:
371.. \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
372
373
374Manager Widgets
375^^^^^^^^^^^^^^^
376
377
378.. class:: PanedWindow()
379
380   The `PanedWindow
381   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_
382   widget allows the user to interactively manipulate the sizes of several panes.
383   The panes can be arranged either vertically or horizontally.  The user changes
384   the sizes of the panes by dragging the resize handle between two panes.
385
386.. Python Demo of:
387.. \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
388
389
390.. class:: ListNoteBook()
391
392   The `ListNoteBook
393   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_
394   widget is very similar to the :class:`TixNoteBook` widget: it can be used to
395   display many windows in a limited space using a notebook metaphor. The notebook
396   is divided into a stack of pages (windows). At one time only one of these pages
397   can be shown. The user can navigate through these pages by choosing the name of
398   the desired page in the :attr:`hlist` subwidget.
399
400.. Python Demo of:
401.. \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
402
403
404.. class:: NoteBook()
405
406   The `NoteBook
407   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_
408   widget can be used to display many windows in a limited space using a notebook
409   metaphor. The notebook is divided into a stack of pages. At one time only one of
410   these pages can be shown. The user can navigate through these pages by choosing
411   the visual "tabs" at the top of the NoteBook widget.
412
413.. Python Demo of:
414.. \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
415
416.. \subsubsection{Scrolled Widgets}
417.. Python Demo of:
418.. \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
419.. Python Demo of:
420.. \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
421.. Python Demo of:
422.. \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
423.. Python Demo of:
424.. \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
425
426
427Image Types
428^^^^^^^^^^^
429
430The :mod:`tkinter.tix` module adds:
431
432* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_
433  capabilities to all :mod:`tkinter.tix` and :mod:`tkinter` widgets to create
434  color images from XPM files.
435
436  .. Python Demo of:
437  .. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
438  .. Python Demo of:
439  .. \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
440
441* `Compound
442  <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image
443  types can be used to create images that consists of multiple horizontal lines;
444  each line is composed of a series of items (texts, bitmaps, images or spaces)
445  arranged from left to right. For example, a compound image can be used to
446  display a bitmap and a text string simultaneously in a Tk :class:`Button`
447  widget.
448
449  .. Python Demo of:
450  .. \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
451  .. Python Demo of:
452  .. \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
453  .. Python Demo of:
454  .. \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
455  .. Python Demo of:
456  .. \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
457
458
459Miscellaneous Widgets
460^^^^^^^^^^^^^^^^^^^^^
461
462
463.. class:: InputOnly()
464
465   The `InputOnly
466   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_
467   widgets are to accept inputs from the user, which can be done with the ``bind``
468   command (Unix only).
469
470
471Form Geometry Manager
472^^^^^^^^^^^^^^^^^^^^^
473
474In addition, :mod:`tkinter.tix` augments :mod:`tkinter` by providing:
475
476
477.. class:: Form()
478
479   The `Form
480   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry
481   manager based on attachment rules for all Tk widgets.
482
483
484Tix Commands
485------------
486
487
488.. class:: tixCommand()
489
490   The `tix commands
491   <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide
492   access to miscellaneous elements of :mod:`Tix`'s internal state and the
493   :mod:`Tix` application context.  Most of the information manipulated by these
494   methods pertains to the application as a whole, or to a screen or display,
495   rather than to a particular window.
496
497   To view the current settings, the common usage is::
498
499      from tkinter import tix
500      root = tix.Tk()
501      print(root.tix_configure())
502
503
504.. method:: tixCommand.tix_configure(cnf=None, **kw)
505
506   Query or modify the configuration options of the Tix application context. If no
507   option is specified, returns a dictionary all of the available options.  If
508   option is specified with no value, then the method returns a list describing the
509   one named option (this list will be identical to the corresponding sublist of
510   the value returned if no option is specified).  If one or more option-value
511   pairs are specified, then the method modifies the given option(s) to have the
512   given value(s); in this case the method returns an empty string. Option may be
513   any of the configuration options.
514
515
516.. method:: tixCommand.tix_cget(option)
517
518   Returns the current value of the configuration option given by *option*. Option
519   may be any of the configuration options.
520
521
522.. method:: tixCommand.tix_getbitmap(name)
523
524   Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap
525   directories (see the :meth:`tix_addbitmapdir` method).  By using
526   :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap
527   files in your application. When successful, it returns the complete pathname of
528   the bitmap file, prefixed with the character ``@``.  The returned value can be
529   used to configure the ``bitmap`` option of the Tk and Tix widgets.
530
531
532.. method:: tixCommand.tix_addbitmapdir(directory)
533
534   Tix maintains a list of directories under which the :meth:`tix_getimage` and
535   :meth:`tix_getbitmap` methods will search for image files.  The standard bitmap
536   directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method
537   adds *directory* into this list. By using this method, the image files of an
538   applications can also be located using the :meth:`tix_getimage` or
539   :meth:`tix_getbitmap` method.
540
541
542.. method:: tixCommand.tix_filedialog([dlgclass])
543
544   Returns the file selection dialog that may be shared among different calls from
545   this application.  This method will create a file selection dialog widget when
546   it is called the first time. This dialog will be returned by all subsequent
547   calls to :meth:`tix_filedialog`.  An optional dlgclass parameter can be passed
548   as a string to specified what type of file selection dialog widget is desired.
549   Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``.
550
551
552.. method:: tixCommand.tix_getimage(self, name)
553
554   Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or
555   :file:`name.ppm` in one of the bitmap directories (see the
556   :meth:`tix_addbitmapdir` method above). If more than one file with the same name
557   (but different extensions) exist, then the image type is chosen according to the
558   depth of the X display: xbm images are chosen on monochrome displays and color
559   images are chosen on color displays. By using :meth:`tix_getimage`, you can
560   avoid hard coding the pathnames of the image files in your application. When
561   successful, this method returns the name of the newly created image, which can
562   be used to configure the ``image`` option of the Tk and Tix widgets.
563
564
565.. method:: tixCommand.tix_option_get(name)
566
567   Gets the options maintained by the Tix scheme mechanism.
568
569
570.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio])
571
572   Resets the scheme and fontset of the Tix application to *newScheme* and
573   *newFontSet*, respectively.  This affects only those widgets created after this
574   call.  Therefore, it is best to call the resetoptions method before the creation
575   of any widgets in a Tix application.
576
577   The optional parameter *newScmPrio* can be given to reset the priority level of
578   the Tk options set by the Tix schemes.
579
580   Because of the way Tk handles the X option database, after Tix has been has
581   imported and inited, it is not possible to reset the color schemes and font sets
582   using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions`
583   method must be used.
584