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