			INTRODUCTION TO TIX


NOTE
----
	This is only an ALPHA VERSION of TIX 3.6. Things may break, or
they may changing in the upcoming beta version. I disclaim all
warranties with regard to this software, including all implied
warranties of merchantability and fitness. In no event shall I be
liable for any special, indirect or consequential damages or any
damages whatsoever resulting from loss of use, data or profits,
whether in an action of contract, negligence or other tortuous action,
arising out of or in connection with the use or performance of this
software.


TIX 3.6
-------

	TIX 3.6 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 and
other useful compound widgets.


USING TIX
---------

	You first have to ftp the file Tix3.6a.tar.Z from
harbor.ecn.purdue.edu. Uncompress it and install it, probably, in the
directory /usr/local/tcl/Tix3.6/

	The library code of Tix3.6 resides in Tix3.6/library. You have
to append this directory in your auto_path before calling the TIX
commands. E.g:

	lappend auto_path /usr/local/tcl/Tix3.6/library

	The TIX library must be initialized. You can do this by
calling the command "tixInit". "tixInit" takes one argument -- the
directory of the TIX library. For example, if your TIX library is
installed in /usr/local/tcl/Tix3.6/library, you have to call

	tixInit /usr/local/tcl/Tix3.6/library

	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


ALTERNATIVE BINDINGS AND COLOR SCHEMES
--------------------------------------

	The TIX 3.6 package also include a set of alternative bindings
and color schemes for TK. They are optional, but generally by applying
these bindings and color schemes will enhance the feel and look of
your TK applications.

	The bindings are in the directory Tix3.6/bindings. Currently
there is only one binding file, i.e., Motif.tcl. It specifies bindings
that are closer to standard Motif. More default bindings will come in
the next release, such as MotifEmacs, MotifVi, etc.

	The color schemes are in the directory Tix3.6/schemes. This
package defines three color schemes: Gray, SGIGray, and Blue. Each
color scheme support two font sizes: 12-point and 14-point. The
12-point font size is suitable for lower resolution displays and the
14-point font size is suitable for higher resolution displays.

	These alternative bindings and color schemes are in TCL script
files in the directories metioned above. To use them, you can source
in these files in your start-up TCL script.

PUTTING IT TOGETHER: AN EXAMPLE
-------------------------------

	Here is an example file that uses the TIX widgets, the "Motif"
bindings and the "Gray14" color scheme.

#----------------begin-------------------------------------

#  Load the schemes and bindings. Must do this before creating
#  any widgets.
source /home/ioi/jack/tcl/tix/Tix3.6/schemes/Gray14.tcl
source /home/ioi/jack/tcl/tix/Tix3.6/bindings/Motif.tcl


#  Initialize the TIX library
lappend auto_path /home/ioi/jack/tcl/tix/Tix3.6/library
tixInit /home/ioi/jack/tcl/tix/Tix3.6/library

#  Now create my widgets
button .b -text "Open" -command {
    if {![winfo exists .open]} {
        tixMkFileDialog .open okcmd
    } else {
        wm deiconify .open
    }
}

proc okcmd {filename} {
    puts "you have selected $filename"
}

pack .b -expand yes -fill both

#--------------------end------------------------------------

	More examples can be found in the directory Tix3.6/demos:

Tix3.6/demos/
	tour.tcl	: A tour of the TIX widgets
	filebox.tcl	: A demo of the TIX FileSelectBox


THE WIDGETS
-----------

	The following widgets are included in TIX 3.6.

	class name	description
----------------------------------------------------------------------
	tixComboBox	Combo box
	tixDlgBtns	Dialog buttons
	tixFileSelectBox
			Extended Motif-style file selection box.
	tixLabelFrame	LabelFrame
			A frame with labels. 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 a one-out-of-n
			selection.
	tixStdDlgBtns	Standard Motif-style dialog buttons.
	tixValue	Value selector
			It is basically a entry with a "+" and a "-" 
			button for you to enter and manipulate a
			value.

OTHER COMMANDS
--------------

	tixCreatePopupMenu
		Creates a pop-up menu. Please read the accompanying
man page Tix3.6/man/PupMenu.n for more details. Also the file
Tix3.6/demos/popup.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.

[temp]  Read the file Tix3.6/library/Util.tcl for details of the
commands metioned above.

OTHER FEATURES
--------------

	Automatic scrolling
	If you source in the file Tix3.6/bindings/Motif.tcl, you will
get automatic scrolling of 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.

[temp]	Currently listboxes only scroll vertically. This will be fixed
in the next release.


CONFIGURING THE TIX WIDGETS
---------------------------

[temp]	Currently I have prepared only a few man pages for the TIX
widgets. They are in the directory Tix3.6/man. If you want to use a
TIX widget but don't know what widget commands it provides or what
options it supports, don't despair. I will upload full documentation
in about two weeks.

Sub-widget 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 sub-widgets
inside a compound widget is pre-defined and cannot be changed.
However, some of the attributes of the sub-widgets, such as their
fonts and color, can be changed to suit your personal linkings. Most
TIX compound widgets provide "sub-widget configuration specs" for you
to change these attributes of the sub-widgets. 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.

[temp]	If you want to know exactly what options a particular widget
support, you can look into its source code. The complete list of
options of a widget is specified in the command
"tixXxx::CreateClassRec". The meanings of their names should be
straight forward to interpret.



ACCESSING SUBWIDGETS
--------------------

	Usually the sub-widgets inside a compound widget should be
invisible to the user and should be accessed directly. However,
TIX provides a mechanism to access the sub-widgets when it is
necessary. The widgets can be access in two ways according to the type
of the compound widget.

Container widgets
-----------------
	Container widgets, such as the tixDlgBtns widget, contains
subwidgets of the same type. For example, tixDlgBtns contains button
sub-widgets. Each of these sub-widgets has an 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 sub-widgets: "open" and "close". These
widgets can be manipulated using the "button" widget command of .btns.
For example :

	.btns button open

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.


Conglomerate widgets
--------------------
	Conglomerate widgets contain sub-widgets of various types.
Each accessible sub-widget is given an unique identifier. For example,
the tixComboBox has two sub-widgets that are accessible from the user:
the entry and the listbox and 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.

Duplicity and unsafe access of sub-widgets
------------------------------------------
	The alert reader may notice that the command

	.cbox entry config -bg red
	
has the same result as 

	.cbox config -entrybg red.

Currently there are some undesirable duplicities in the manipulation of
the compound widgets. I am still thinking how they can advoided. Also,
when the sub-widgets are exposed to the user, she/he may naively
manipulate the sub-widgets in a dangerous way, such as deleting the
listbox inside the combobox. Currently there is no way to stop this
from happening. All I can do is to provide some guildlines for
accessing the sub-widgets.


TODO
----

	1) Documentation of the widgets. Will come out in two weeks time.
	2) Finish up the missing parts in the widgets.
	3) Write a paper about the TIX intrinsics.
	4) Improve error messages of the compound widgets.
	5) Add chechking routines for the configuration of widget
	   options.


