INTRODUCTION TO TIX TABLE OF CONTENTS ----------------- 1.0 About This Version 2.0 What is Tix 2.1 Getting Tix 2.2 Installing Tix 3.0 Getting Started 3.1 The Widgets 3.2 Using the Tix Widgets 3.3 Configuring the Tix Widgets 3.3.1 Subwidget Options 3.3.2 Using the Options Database 3.4 Alternative Bindings and Color Schemes 3.5 Othet Commands 3.6 Other Features 3.7 Using Tix Interactively 4.0 Accessing Subwidgets 4.0.1 Container Widgets 4.0.2 Conglomerate Widgets 4.1 Unsafe Access to Subwidgets 5.0 To Tix or not to Tix 5.1 More Documentation ... 5.2 Acknowledgement 1.0 ABOUT THIS VERSION ---------------------- This is Tix version 3.6c. It is a "more or less stable release version". Feel free to play with it and report any problems to ioi@graphics.cis.upenn.edu. 2.0 WHAT IS TIX --------------- TIX 3.6c is a set of compound widgets based on TK. It is written completely in TCL and requires no extension to the C source of TK. You can use the TIX widgets directly in your TCL scripts without having to recompile wish. It includes a Combobox, a FileSelectbox, other useful compound widgets and a bunch of extensions to TK. Tix has a more-or-less object oriented architecture. It is not based on an object oriented language: i.e., you don't need to have [incr tcl] in order to use Tix. This will ensure that Tix can be seamlessly integrated into the standard TCL/TK distribution. Tix uses object oriented concepts but it is implemented using a conventional language. This is very much like the design of the Xt Intrinsics in the X Toolkit, so I call the core of Tix "Intrinsics". (There will be a detailed description of the Tix Intrinsics in the "fully-documented release" 2.1 GETTING TIX ---------------- 1) ftp://harbor.ecn.purdue.edu/pub/tcl/extensions/Tix3.6c.tar.Z 2) http://www.seas.upenn.edu/~ioi/gui/tix.html 2.2 INSTALLING TIX ------------------- 1) Unpack the file at a proper place. It will create a directory Tix3.6c/ % tar xvf Tix3.6c.tar 2) Edit the Makefile to indicate where you want to put the Tix library files (the default location is /usr/local/lib/tix.) 3) Inside the directory Tix3.6c/ do % make install This will install the tix library to /usr/local/lib/tix and the man-pages to /usr/local/man. 3.0 GETTING STARTED -------------------- To use the Tix library in your program, you have to append the library directory of TIX to the auto-load path by using the following command: (assuming that you have installed TIX in /usr/local/lib/tix) lappend auto_path /usr/local/lib/tix You have to call the command tixInit to initialize Tix before you can use the functionalities of Tix. There are a few optional arguments to this command. For example, Tix comes with some pre-defined color schemes, font sets, and bindings. You can, but are not required to, call tixInit with appropriate arguments to activate these options. Please read the manpage Tix3.6c/man/Tix.n for detailed description of these options. SYNOPSIS tixInit ?-libdir path? ?-scheme sName? ?-fontset fName? ?-binding bName? The following is a sample start-up code of programs that uses Tix. This program is also in Tix3.6c/demo/startup.tcl ---------------------------------------------------------------------- #!/usr/local/bin/wish -f set TIX_LIBRARY /usr/local/lib/tix lappend auto_path $TIX_LIBRARY tixInit -libdir $TIX_LIBRARY -scheme Gray -fontset 14Point -binding Motif # At here, jump to the start of your program ---------------------------------------------------------------------- 3.1 THE WIDGETS ---------------- The following widgets are included in TIX 3.6. class name description ---------------------------------------------------------------------- TixCombobox Combobox, similar to the MS Windows Combo box. TixControl Value selector. It is basically a entry with a "+" and a "-" button for you to enter and manipulate a value. TixDlgBtns Buttonss for dialog boxes TixFileSelectbox Extended Motif-style file selection box. TixLabelFrame LabelFrame A frame with a label. Can be used to group related items together. TixScrolledListbox Listbox with scrollbars. You can select which scrollbar(s) you need. TixSelect A group of buttons for radiobox or checkbox style selection. TixStdDlgBtns Standard Motif-style dialog buttons. Detailed descriptions of these widgets are provided in the man-pages in Tix3.6c/man 3.2 USING THE TIX WIDGETS -------------------------- After its initialization, you can use the widgets and commands provided by TIX. All TIX commands and widgets begin with the prefix "tix". The TIX widgets work the same way as normal TK widgets. For example, to create a TIX combobox, tixCombobox .cbox The configuration of the TIX widgets can be specified in the creation command, using "config" widget command or specified in the option database. The following three segments of code are equivalent: 1) tixCombobox .cbox -height 5 2) tixCombobox .cbox .cbox config -height 5 3) option add *cbx.height 5 tixCombobox .cbox 3.3 CONFIGURING THE TIX WIDGETS -------------------------------- 3.3.1 SUBWIDGET OPTIONS This section explains the basics of configuring the TIX widgets. Since the TIX widgets are all compound widgets, they all consist of more than one widgets. Usually, the behavior subwidgets inside a compound widget is pre-defined and cannot be changed. However, some of the attributes of the subwidgets, such as their fonts and color, can be changed to suit your personal linkings. Most TIX compound widgets provide "subwidget configuration specs" for you to change these attributes of the subwidgets. For examples, many TIX widgets support the options "-entrybg", "-listboxbg" and "-buttonbg" tha can be used to change the background color of the widgets of the specific type. 3.3.2 USING THE OPTIONS DATABASE You have to take great care when you use the wildcard feature of the options database. The Tix widget are compound widgets. If you try to config the height of the Combobox using the following command: options add *Combobox*height 100 That will cause all the subwidgets in the Combobox to have a height of 100, which is of course not what you want. Use this command instead: options add *Combobox.height 100 This will only affect the "-height" option of the main Combobox widget and not all its subwidgets. 3.4 ALTERNATIVE BINDINGS AND COLOR SCHEMES ------------------------------------------- The TIX 3.6 package also include a set of alternative bindings, color schemes and fontsets for TK. They are optional, but generally by applying these bindings and color schemes will enhance the feel and look of your TK applications and make them look more professional and more Motif-like. The bindings are in the directory Tix3.6c/library/bindings. Currently there are two available bindings. The "Motif" binding makes your program behave similarly to standard Motif programs. The "TK" binding sets the standard bindings in TK. The color schemes and font schemes are in the directory Tix3.6c/library/schemes. This package defines four color schemes: "Gray", "SGIGray", "Blue" and "TK". It also defines three fontsets: "14Point", "12Point" and "TK". The 12-point font size is suitable for lower esolution displays and the 14-point font size is suitable for higher resolution displays. 3.5 OTHER COMMANDS ------------------- tixCreatePopupMenu Creates a pop-up menu. Please read the accompanying man page Tix3.6c/man/PupMenu.n for more details. Also the file Tix3.6c/demos/popup.tcl. tixAddBalloon Adds balloon help to a widget. See Tix3.6c/man/Balloon.n Also Tix3.6c/demos/balloon.tcl. tixDescendants Returns all the descendents of a widget. tixDisableAll Disables all the descendants of a widget, if they support the -state option. tixEnableAll Enables all the descendants of a widget, if they support the -state option. tixListGetSingle Get the first selection in a listbox. If no item is currently selected, returns empty string. tixSetEntry Sets the text inside an entry. These utility commands are documented in Tix3.6c/man/Utils.n 3.6 OTHER FEATURES ------------------- Automatic scrolling If you use the Motif bindings, you can perform automatic scrolling in entries, listboxes and texts. For example, if you hold down the mouse inside a text widget and drag below the bottom edge of the text, the text will automatically scroll up. The same is true for entries, but they scroll horizontally. 3.7 USING TIX INTERACTIVELY --------------------------- This section describes how you can use the Tix widgets inside an interactive wish. Add the following section into your ~/.wishrc ------------------------------------------------------------ catch { if {[lindex $argv 0] == "-tix"} { source ~/.tixrc } } ------------------------------------------------------------ Also, create the file .tixrc in your home directory: ------------------------------------------------------------ set TIX_LIBRARY /usr/local/lib/tix lappend auto_path $TIX_LIBRARY tixInit -libdir $TIX_LIBRARY -scheme SGIGray -fontset \ 14Point -binding Motif ------------------------------------------------------------ Now you can run wish interactively and use Tix as soon as you get the wish prompt. Here is an example session. '$' is the Unix prompt. '%' is the wish prompt. $ wish -tix % tixCombobox .cbx .cbx % pack .cbx % 4.0 ACCESSING SUBWIDGETS ------------------------- Usually the subwidgets inside a compound widget should be invisible to the user and should be accessed directly. However, TIX provides a mechanism to access the subwidgets when it is necessary. The widgets can be access in two ways according to the type of the compound widget. 4.0.1 CONTAINER WIDGETS Container widgets, such as the TixDlgBtns widget and the TixSelect widget, contains subwidgets of the same type. For example, TixDlgBtns contains button subwidgets. Each of these sub-widgets has a unique name. In the following code: tixDlgBtns .btns .btns add open -text "Open" -command "open_proc" .btns add close -text "CLose" -command "close_proc" The container .btns has two subwidgets: "open" and "close". These widgets can be manipulated using the "button" widget command of .btns. For example : set w [.btns button open] $w config -fg red returns the path name of the "Open" button. When supplied with extra arguments, these arguments are treated as widget command for the sub-widget. For example, the following commands .btns button open config -fg red .btns button open invoke config and invoke the particular subwidget. Currently the subwidgets inside a container widget cannot be destroyed or unmapped. Attempting to to that may compromise the integrity of the Tix toolkit. This problem will be fixed in a future release. 4.0.2 CONGLOMERATE WIDGETS Conglomerate widgets are special purpose, pre-packaged compound widgets. They contain subwidgets of various types. Since the behavior of the subwidgets inside a conglomerate widget are usually fixed and should not be changed, most of the subwidgets cannot be accessed. Ocassionaly it is desirable to made some subwidgets inside a conglomerate widget to be accessible. These are called "public subwidgets". Each public subwidget has a unique identifier. For example, the Combobox has two public subwidgets: the entry and the listbox. They are identified by the widget commands "entry" and "listbox". For example, if we have a combobox .cbx, the command: [.cbx entry] returns the path name of the entry widget. When supplied with extra arguments, these arguments are treated as widget command for the entry. For example, the following commands .cbox entry config -bg red .cbox listbox delete 0 will config the background of the entry in the combobox and delete the first item in the listbox of the combobox, respectively. 4.1 UNSAFE ACCESS TO SUBWIDGETS -------------------------------- Currently you can access the public subwidgets any way you like. This is potentially dangerous: all the subwidgets inside a comglomerate widget have default bindings so that they can cooperate. If you change those bindings, the comglomerate widget may stop functioning correctly. In a future release, access to public subwidgets will be restricted. Before that date comes, though, please be careful when you access the public subwidgets. Advoid it if possible and, in any case, do *not* change any binding of the public subwidgets. Even adding bindings using bind [.cbox entry] "+myproc" can be dangerous! If it seems to work fine now, it will break in the near future. You have been warned. 5.0 TO TIX OR NOT TO TIX ------------------------- Tix is still an envolving product. The following section discuss the stability of various parts of this package. It will help you decide whether you should include these features into critical applications. 1) The widgets The widgets included in this version have been pretty much throughly debugged, although no 100% correctness can be guaranteed. The interface (i.e., the widget commands and configuration options) to these widgets are more or less stable and they won't dramatically change in the near future. Hence, the Tix widgets are the safest parts of this version to be included in you programs. 2) The Tix Intrinsics The Tix Intrinsics, much like the Xt InTrinsics, is the interface on which the Tix widgets are build. The current version of the Tix Intrinsics is believed to be stable. However, it lacks important functionality such as inheritance and private data protection. As planned, a future version of Tix will provide these features and that will drastically change the Tix Intrinsics mechanisms. It is *not* safe to depend on the Tix Intrinsics functionality in your program. 3) Color Schemes They just add a few options into the options library. These are the options that I like, although you may find them awful, especially if you prefer to have red text on top of a green foreground. In any case, using the Tix color schemes won't do harm to your programs. 4) Motif bindings The bindings have not been tested thoroughly and bugs have been reported on various platforms not accessible by the author. It is *not* safe to depend on the functionality provided by the Motif binding files. 5) Other ocumented features The features documented by this paper, such as the Popup Menu and Balloon Help, are believed to be safe and stable. 6) Undocumented features If you find some undocumented functions and features (including the Intrinsics) inside Tix, they are probably unstable and unsafe. Do not use them. Also, if you think you are writing a critical application and you will want to sue people when undesirable things happen, please take a few minutes to read the file README.COPYRIGHT. 5.1 MORE DOCUMENTATION ----------------------- This release of Tix 3.6c will give you enough information to use the Tix widgets and extensions in your applications. In a few weeks, possible at the beginning of september, I'll release a "fully documented release" to include more information, such how the Tix Intrinsics works so you can write your new Tix conformant widget. There will also be a PS formatted version of this paper that include some screen dumps. 5.2 ACKNOWLEDGEMENT -------------------- I have to thank the many people who have given me advices, bug reports, hard time, etc. I love to have see those mails. I have to send my special thanks to Shannon Jaeger, the correspondence with who who has given me enough enthusiasm to continue with the Tix project.