			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] <Enter> "+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.
