1 :mod:`Tix` --- Extension widgets for Tk
2 =======================================
5 :synopsis: Tk Extension Widgets for Tkinter
6 .. sectionauthor:: Mike Clarkson <mikeclarkson@users.sourceforge.net>
11 The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set
12 of widgets. Although the standard Tk library has many useful widgets, they are
13 far from complete. The :mod:`Tix` library provides most of the commonly needed
14 widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`,
15 :class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets.
16 :mod:`Tix` also includes many more widgets that are generally useful in a wide
17 range of applications: :class:`NoteBook`, :class:`FileEntry`,
18 :class:`PanedWindow`, etc; there are more than 40 of them.
20 With all these new widgets, you can introduce new interaction techniques into
21 applications, creating more useful and more intuitive user interfaces. You can
22 design your application by choosing the most appropriate widgets to match the
23 special needs of your application and users.
27 :mod:`Tix` has been renamed to :mod:`tkinter.tix` in Python 3.0. The
28 :term:`2to3` tool will automatically adapt imports when converting your
33 `Tix Homepage <http://tix.sourceforge.net/>`_
34 The home page for :mod:`Tix`. This includes links to additional documentation
37 `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_
38 On-line version of the man pages and reference material.
40 `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_
41 On-line version of the programmer's reference material.
43 `Tix Development Applications <http://tix.sourceforge.net/Tixapps/src/Tide.html>`_
44 Tix applications for development of Tix and Tkinter programs. Tide applications
45 work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to
46 remotely modify and debug Tix/Tk/Tkinter applications.
53 .. class:: Tix(screenName[, baseName[, className]])
55 Toplevel widget of Tix which represents mostly the main window of an
56 application. It has an associated Tcl interpreter.
58 Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter`
59 module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all
60 you need to do is to import one module. In general, you can just import
61 :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with
65 from Tkconstants import *
68 To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually
69 alongside your installation of the Tk widgets. To test your installation, try
74 root.tk.eval('package require Tix')
76 If this fails, you have a Tk installation problem which must be resolved before
77 proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the
78 installed :mod:`Tix` library directory, and make sure you have the dynamic
79 object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same
80 directory that contains your Tk dynamic object library (:file:`tk8183.dll` or
81 :file:`libtk8183.so`). The directory with the dynamic object library should also
82 have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the
85 package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
91 `Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_
92 introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a
93 demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the
94 standard distribution.
96 .. The Python sample code is still being added to Python, hence commented out
106 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that
107 pops up over a widget to provide help. When the user moves the cursor inside a
108 widget to which a Balloon widget has been bound, a small pop-up window with a
109 descriptive message will be shown on the screen.
112 .. \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
115 .. class:: ButtonBox()
118 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_
119 widget creates a box of buttons, such as is commonly used for ``Ok Cancel``.
122 .. \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
125 .. class:: ComboBox()
128 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_
129 widget is similar to the combo box control in MS Windows. The user can select a
130 choice by either typing in the entry subwdget or selecting from the listbox
134 .. \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
140 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_
141 widget is also known as the :class:`SpinBox` widget. The user can adjust the
142 value by pressing the two arrow buttons or by entering the value directly into
143 the entry. The new value will be checked against the user-defined upper and
147 .. \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
150 .. class:: LabelEntry()
153 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_
154 widget packages an entry widget and a label into one mega widget. It can be used
155 be used to simplify the creation of "entry-form" type of interface.
158 .. \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
161 .. class:: LabelFrame()
164 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_
165 widget packages a frame widget and a label into one mega widget. To create
166 widgets inside a LabelFrame widget, one creates the new widgets relative to the
167 :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget.
170 .. \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
176 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget
177 can be used to show the progress of a background job which may take a long time
181 .. \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
184 .. class:: OptionMenu()
187 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_
188 creates a menu button of options.
191 .. \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
194 .. class:: PopupMenu()
197 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_
198 widget can be used as a replacement of the ``tk_popup`` command. The advantage
199 of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code
203 .. \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
209 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget
210 is a container of button subwidgets. It can be used to provide radio-box or
211 check-box style of selection options for the user.
214 .. \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
217 .. class:: StdButtonBox()
220 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_
221 widget is a group of standard buttons for Motif-like dialog boxes.
224 .. \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
234 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_
235 widget displays a list 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.
240 .. \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
246 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_
247 widget displays a tree view of a directory, its previous directories and its
248 sub-directories. The user can choose one of the directories displayed in the
249 list or change to another directory.
252 .. \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
255 .. class:: DirSelectDialog()
258 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm>`_
259 widget presents the directories in the file system in a dialog window. The user
260 can use this dialog window to navigate through the file system to select the
264 .. \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
267 .. class:: DirSelectBox()
269 The :class:`DirSelectBox` is similar to the standard Motif(TM)
270 directory-selection box. It is generally used for the user to choose a
271 directory. DirSelectBox stores the directories mostly recently selected into
272 a ComboBox widget so that they can be quickly selected again.
275 .. class:: ExFileSelectBox()
278 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm>`_
279 widget is usually embedded in a tixExFileSelectDialog widget. It provides an
280 convenient method for the user to select files. The style of the
281 :class:`ExFileSelectBox` widget is very similar to the standard file dialog on
285 .. \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
288 .. class:: FileSelectBox()
291 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_
292 is similar to the standard Motif(TM) file-selection box. It is generally used
293 for the user to choose a file. FileSelectBox stores the files mostly recently
294 selected into a :class:`ComboBox` widget so that they can be quickly selected
298 .. \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
301 .. class:: FileEntry()
304 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_
305 widget can be used to input a filename. The user can type in the filename
306 manually. Alternatively, the user can press the button widget that sits next to
307 the entry, which will bring up a file selection dialog.
310 .. \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
320 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget
321 can be used to display any data that have a hierarchical structure, for example,
322 file system directory trees. The list entries are indented and connected by
323 branch lines according to their places in the hierarchy.
326 .. \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
329 .. class:: CheckList()
332 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_
333 widget displays a list of items to be selected by the user. CheckList acts
334 similarly to the Tk checkbutton or radiobutton widgets, except it is capable of
335 handling many more items than checkbuttons or radiobuttons.
338 .. \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
340 .. \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
342 .. \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
348 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget
349 can be used to display hierarchical data in a tree form. The user can adjust the
350 view of the tree by opening or closing parts of the tree.
353 .. \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
355 .. \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
365 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget
366 can be used to display data in a tabular format. The list entries of a
367 :class:`TList` widget are similar to the entries in the Tk listbox widget. The
368 main differences are (1) the :class:`TList` widget can display the list entries
369 in a two dimensional format and (2) you can use graphical images as well as
370 multiple colors and fonts for the list entries.
373 .. \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
375 .. \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
376 .. Grid has yet to be added to Python
377 .. \subsubsection{Grid Widget}
379 .. \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
381 .. \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
383 .. \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
390 .. class:: PanedWindow()
393 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_
394 widget allows the user to interactively manipulate the sizes of several panes.
395 The panes can be arranged either vertically or horizontally. The user changes
396 the sizes of the panes by dragging the resize handle between two panes.
399 .. \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
402 .. class:: ListNoteBook()
405 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_
406 widget is very similar to the :class:`TixNoteBook` widget: it can be used to
407 display many windows in a limited space using a notebook metaphor. The notebook
408 is divided into a stack of pages (windows). At one time only one of these pages
409 can be shown. The user can navigate through these pages by choosing the name of
410 the desired page in the :attr:`hlist` subwidget.
413 .. \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
416 .. class:: NoteBook()
419 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_
420 widget can be used to display many windows in a limited space using a notebook
421 metaphor. The notebook is divided into a stack of pages. At one time only one of
422 these pages can be shown. The user can navigate through these pages by choosing
423 the visual "tabs" at the top of the NoteBook widget.
426 .. \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
428 .. \subsubsection{Scrolled Widgets}
430 .. \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
432 .. \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
434 .. \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
436 .. \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
442 The :mod:`Tix` module adds:
444 * `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_
445 capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images
449 .. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
451 .. \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
454 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image
455 types can be used to create images that consists of multiple horizontal lines;
456 each line is composed of a series of items (texts, bitmaps, images or spaces)
457 arranged from left to right. For example, a compound image can be used to
458 display a bitmap and a text string simultaneously in a Tk :class:`Button`
462 .. \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
464 .. \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
466 .. \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
468 .. \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
471 Miscellaneous Widgets
472 ^^^^^^^^^^^^^^^^^^^^^
475 .. class:: InputOnly()
478 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_
479 widgets are to accept inputs from the user, which can be done with the ``bind``
483 Form Geometry Manager
484 ^^^^^^^^^^^^^^^^^^^^^
486 In addition, :mod:`Tix` augments :mod:`Tkinter` by providing:
492 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry
493 manager based on attachment rules for all Tk widgets.
501 .. class:: tixCommand()
504 <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide
505 access to miscellaneous elements of :mod:`Tix`'s internal state and the
506 :mod:`Tix` application context. Most of the information manipulated by these
507 methods pertains to the application as a whole, or to a screen or display,
508 rather than to a particular window.
510 To view the current settings, the common usage is::
514 print root.tix_configure()
517 .. method:: tixCommand.tix_configure([cnf,] **kw)
519 Query or modify the configuration options of the Tix application context. If no
520 option is specified, returns a dictionary all of the available options. If
521 option is specified with no value, then the method returns a list describing the
522 one named option (this list will be identical to the corresponding sublist of
523 the value returned if no option is specified). If one or more option-value
524 pairs are specified, then the method modifies the given option(s) to have the
525 given value(s); in this case the method returns an empty string. Option may be
526 any of the configuration options.
529 .. method:: tixCommand.tix_cget(option)
531 Returns the current value of the configuration option given by *option*. Option
532 may be any of the configuration options.
535 .. method:: tixCommand.tix_getbitmap(name)
537 Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap
538 directories (see the :meth:`tix_addbitmapdir` method). By using
539 :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap
540 files in your application. When successful, it returns the complete pathname of
541 the bitmap file, prefixed with the character ``@``. The returned value can be
542 used to configure the ``bitmap`` option of the Tk and Tix widgets.
545 .. method:: tixCommand.tix_addbitmapdir(directory)
547 Tix maintains a list of directories under which the :meth:`tix_getimage` and
548 :meth:`tix_getbitmap` methods will search for image files. The standard bitmap
549 directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method
550 adds *directory* into this list. By using this method, the image files of an
551 applications can also be located using the :meth:`tix_getimage` or
552 :meth:`tix_getbitmap` method.
555 .. method:: tixCommand.tix_filedialog([dlgclass])
557 Returns the file selection dialog that may be shared among different calls from
558 this application. This method will create a file selection dialog widget when
559 it is called the first time. This dialog will be returned by all subsequent
560 calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed
561 as a string to specified what type of file selection dialog widget is desired.
562 Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``.
565 .. method:: tixCommand.tix_getimage(self, name)
567 Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or
568 :file:`name.ppm` in one of the bitmap directories (see the
569 :meth:`tix_addbitmapdir` method above). If more than one file with the same name
570 (but different extensions) exist, then the image type is chosen according to the
571 depth of the X display: xbm images are chosen on monochrome displays and color
572 images are chosen on color displays. By using :meth:`tix_getimage`, you can
573 avoid hard coding the pathnames of the image files in your application. When
574 successful, this method returns the name of the newly created image, which can
575 be used to configure the ``image`` option of the Tk and Tix widgets.
578 .. method:: tixCommand.tix_option_get(name)
580 Gets the options maintained by the Tix scheme mechanism.
583 .. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio])
585 Resets the scheme and fontset of the Tix application to *newScheme* and
586 *newFontSet*, respectively. This affects only those widgets created after this
587 call. Therefore, it is best to call the resetoptions method before the creation
588 of any widgets in a Tix application.
590 The optional parameter *newScmPrio* can be given to reset the priority level of
591 the Tk options set by the Tix schemes.
593 Because of the way Tk handles the X option database, after Tix has been has
594 imported and inited, it is not possible to reset the color schemes and font sets
595 using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions`