1 Introduction

The acronym Tix stands for Tk Interface Extension. Tix is different things for different people.

If you are a GUI application programmer, that is, if you earn a living by building graphical applications, you will appreciate Tix as a library of mega-widgets: widgets made out of other widgets. To use a crude analogy, if the widgets in the standard TK library are bricks and mortars for a builder, the mega-widgets in the Tix library are walls, windows or even pre-build kitchens. Of course, these ``bigger components'' are themselves made of bricks and mortars, but it will take much less effort to put them together than planting bricks on top of each other.

The Tix widgets not only help you speed up the development of your applications, they also help you in the design process. Since the standard Tk widgets are too primitive, they force you to think of your house as, by using the same analogy, millions of bricks. With the help of the Tix mega-widgets, you can design your application is a more structural and coherent manner.

On the other hand, if you are a widget developer, Tix provides an object oriented programming environment, the Tix Intrinsics, that is carefully designed for the development of mega-widgets. If you have developed widgets in C, you will know how slow and painful such a process would be. In recognition of the difficulties in widget development, the Tix Intrinsics includes many tools that dramatically cuts down the efforts required to develop new widgets. With the Tix Intrinsics, the rapid prototyping/development of widgets is finally feasible: you can write a new widgets in the matter of hours or even minutes.

With the Tix Intrinsics, you widget code can readily become reusable. Tix also provides a set of rules and mechanisms that allow you to develop widgets that are inter-operable with other widgets.

In Part I of this manual, we will talk about using the Tix widgets. The discussion of writing new Tix widgets will be carried out in Part II.

Pre-requisites: you should be familiar with Tk widgets and programming, or read the Tk book along with this book

Before delving into the deep philosophy of the Tix widgets, let us first have a quick example to demonstrate the usefulness and convenience of an Tix widget: the TixControl is basically an entry widget that displays a value. Next to the entry, there are two up and down arrow buttons for you to adjust the value inside the entry widget.

The following code demonstrates how to create a TixControl widget and specify its options:

    tixControl .lawyers -label Lawyers: -max 10 -min 0
    .lawyers config -integer true -step 2

As shown in the example, you can create and manipulate a Tix widget in the same manner as the standard Tk widgets. The options of the widget can be specified during the creation of the widget. Alternatively, they can be changed by the configure widget command. In addition, options can also be specified in the option database or as X resources. Here is an example that produces the same result as the previous code fragment:

    option add *lawyers.max 10
    option add *lawyers.min 0
    tixControl .lawyers -label Lawyers: -integer true
    .lawyers config -step 2

The TixControl widget allows the user to input a value. There are several ways to read this value in your program. First of all, TixControl stores the current value in the -value option. You can use query the -value option by calling the command

    .c cget -value

this command will return the current value of the tixContro widget .c. The following command sets the value of the widget to a new number (100):

    .c config -value 100

    .c config -variable myvar
    set myvar 100

    tixControl .c -command valueChanged

Now, if you want to change a value from within the program, you have to disable the callback. The reason is that the callback runs whenever you (as well as the user) makes a change. In particular, if you make a change within the callback procedure and forget to disable the callback, it will recursively call itself and enter an infinite loop. To avoid this problem, you should use the -disablecallback option. Here is an example:

    tixControl .c -command addOne

    proc addOne {value} {
        .c config -disablecallback true
        .c config -value [incr value]
        .c config -disablecallback false
    }

Sometimes it may be necessary to check the user input against certain criteria. For example, you may want to allow only even numbers in a TixControl widget. To do this, you can use the -validatecmd option, which specifies a Tcl command to call whenever the user enters a new value. Here is an example:

    tixControl .c -value 0 -step 2 -validatecmd evenOnly

    proc evenOnly {value} {
        return [expr $value - ($value %2)]
    }

All Tix mega-widgets support the subwidget method. This method takes at least one argument, the name of a subwidget. When you pass only one argument to this method, it returns the pathname of the subwidget which is identified by that name. For example, if .c is the pathname of a TixControl widget, the command:

  .c subwidget entry

If you call the subwidget method with additional arguments, the widget command of the specified subwidget will be called with these arguments. For example, if .c is, again, the pathname of a TixControl widget, the command:

  .c subwidget entry configure -bg gray

  .c.frame.entry configure -bg gray

We can call the subwidget method with other types of arguments to access different methods of the specified subwidget. For example, the following call:

  .c subwidget entry icursor end

As we have seen above, we can use commands like `` subwidget name configure ...'' to set the configuration options of subwidgets. However, this can get quite tedious if we want to configure many options of many subwidgets.

There is a more convenient and terse way to configure the subwidget options without using the subwidget method: the -options switch. All Tix mega-widgets support the -option switch, which can be used during the creation of the mega-widget.

The -options switch is good if you want to specify subwidget options for one or a few mega-widgets. If you want to specify the subwidget for many mega-widgets, it is easier to use the Tk Option Database.

Options in the Tk Option Database can be specified using the option command and the pathname of the widget. For all the Tix mega-widgets, it is guaranteed that the pathname of their subwidgets ends with the name of the subwidgets. For example, if we have a mega widget called .a.b.megaw and it has a subwidget whose name is subw, then we can be sure that the pathname of the subwidget will be something like

  .a.b.megaw.foo.bar.subw

  option add *a.b.megaw*subw.option1 value1
  option add *a.b.megaw*subw.option2 value2

  option add *a.b.megaw.subw.option1 value1
  option add *a.b.megaw.subw.option2 value2

In the current implementation of Tix, there is no limits on how you can access the options of the subwidgets. However, many options of the subwidgets may be already used by the mega-widget in special ways. For example, the -textvariable option of the entry subwidget of TixControl may be used to store some private information for the mega widget. Therefore, you should access the options of the subwidgets with great care. In general you should only access those options that affect the appearance of the subwidgets (such as -font or -foreground) and leave everything else intact. () { In future versions of Tix, there will be explicit restrictions on which subwidget options you can access. Errors will be generated if you try to access restricted subwidget options}

The TixComboBox widget can appear in many different styles. If we set the -dropdown option to true (which is the default), the listbox will only appear when the user presses the arrow button. When -dropdown is set to false, the listbox is always shown and the arrow button will disappear because it is not needed anymore.

There is also an option called -fancy. It is set to false by default. When set to true, a tick button and a cross button will appear next to the entry widget. The tick button allows you to select again the value that's already in the ComboBox. If you press the cross button, the entry widget will be cleared.

The -dropdown and -fancy options are so-called ``static options''. They can only be set during the creation of the ComboBox. Hence this code is valid:

    tixComboBox .c -dropdown true

But the following code will generate an error because it attempts to set the -dropdown option after the ComboBox has already been created.

    TixComboBox .c
    .c config -dropdown true

When the user drags the mouse pointer over the listbox, the listbox item under the pointer will be highlighted and a ``browse event'' will be generated. If you want to keep track of what items the user has browses through, you can use the -browsecmd option. Here is an example:

    tixComboBox .c -browsecmd mybrowse
    ....

    proc mybrowse {item} {
        puts "user has browsed $item"
    }

When the Tcl command specified by the -browsecmd option is called, it will be called with one parameter: the current item that the user has highlighted.

The -browsecmd is useful because it gives the user the possibility of temporarily seeing the results of several choices before committing to a final choice.

For example, we can list a set of image files in a ComboBox. When the user single-clicks on an item on the ComboBox, we want to show a simplified view of that image. After the user has browsed through several images, he can finally decide on which image he wants by double-clicking on that item in the listbox.

The following is some pseudo Tcl code that does this. Please notice that the -browsecmd procedure is called every time the user single-clicks on an item or drags the mouse pointer in the listbox. The -command procedure is only called when the user double-clicks on an item.

tixComboBox .c -dropdown false -browsecmd show_simple -command load_fullsize 
.c insert end "/pkg/images/flowers.gif"
.c insert end "/pkg/images/jimmy.gif"
.c insert end "/pkg/images/ncsa.gif"

proc show_simple {filename} {
    # Load in a simplified version of $filename
}

proc load_fullsize {filename} {
    # Load in the full size image in $filename
}

As we shall see, all Tix widgets that let us do some sort of selections have the -browsecmd option. The -browsecmd option allows us to respond to user events in a simple, straight-forward manner. Of course, you can do the same thing with the Tk bind command, but you don't want to do that unless you are very fond of things like <Control-Shift-ButtonRelease-1> and "%x %X $w %W %w".

For simple selection rules, you can use the -allowzero and -radio options. The -allowzero option specifies whether the user can select none of the choices inside the TixSelect widget. The -radio option controls how many buttons can be selected at once: when set to true, the user can select only one button at a time; when set to false, the user can select as many buttons as he desires.