NAME

SYNOPSIS

DESCRIPTION

The Tix Display Items mechanism is devised to
solve a general problem: many Tix widgets (both existing and planned
ones) display many items of many types simutaneously.

For example, a hierarchical listbox widget (HList) can display items
of images, plain text and subwindows in the form of a
hierarchy. Another widget, the tabular listbox, (TList, currently
planned and will be released in Tix 4.1) also display items of the
same types, although it arranges the items in a tabular form. Yet
another widget, the spreadsheet widget, also displays similar types
items, but in yet another format.

In these examples, the display items in different widgets are only
different in how they are arranged by the host widget. In Tix,
display items are clearly separated from the host widgets. The
advantage is two-fold: first, the creation and configuration of
display items become uniform across different host widgets. Second,
new display item types can be added without the need to modify the
existing host widgets.

In a way, Tix display items are similar to the items inside Tk
the canvas widget. However, unlike the Tix display items, the canvas
items are not independent of the canvas widget; this makes it
impossible to use the canvas items inside other types of TK widgets.

The appearance of a display item is controlled by a set of
attributes. It is observed that each the attributes usually fall
into one of two categroies: "individual" or
"collective". For example, the text items inside a HList widget
may all display a different text string; however, in most cases, the
text items share the same color, font and spacing. Instead of keeping
a duplicated version of the same attributes inside each display item,
it will be advantageous to put the collective attributes in a
special object called a display style. First, there is the space
concern: a host widget may have many thousands of items; keeping
dupilcated attributes will be very wasteful. Second, when it becomes
necessary to change a collective attribute, such as changing all the
text items' foreground color to red, it will be more efficient to
change only the display style object than to modify all the text
items one by one.

The attributes of the a display item are thus stored in two places: it
has a set of item options to store its individual attributes. Each
display item is also associated with a display style, which specifies
the collective attributes of all items associated with itself.

The division between the individual and collective attributes are
fixed and cannot be changed. Thus, when it becomes necessary for some
items to differ in their collective attributes, two or more display
styles can be used. For example, suppose you want to display two
columns of text items inside an HList widget, one column in red and
the other in blue. You can create a TextStyle object called "red",
which defines a red foreground, and another called "blue", which
defines a blue foreground. You can then associate all text items of
the first column to "red" and the second column to "blue".

DISPLAY ITEM TYPES AND OPTIONS

Currently there are four types of display items: text,
image, imagetext and window. (TODO: need to document
the "image" item)

IMAGETEXT ITEMS

Display items of the type imagetext are used to display an image
together with a text string. Imagetext items support the following options:

ITEM OPTIONS

[ -bitmap bitmap Bitmap ]
Specifies the bitmap to display in the item.
[ -image image Image ]
Specifies the image to display in the item. When both the
-bitmap and -image options are specified, only the image
will be displayed.
[ -style imageTextStyle ImageTextStyle ]
Specifies the display style to use for this item. Must be the
name of a imagetext display style that has already be created by
the tixDisplayStyle(n) command.
[ -showimage showImage ShowImage ]
A Boolean value that specifies whether the image/bitmap should be
displayed.
[ -showtext showText ShowText ]
A Boolean value that specifies whether the text string should be
displayed.
[ -text text Text ]
Specifies the text string to display in the item.
[ -underline underline Underline ]
Specifies the integer index of a character to underline in the text
string in the item. 0 corresponds to the first character of the text
displayed in the widget, 1 to the next character, and so on.

STYLE OPTIONS

The style information of imagetext items are stored in the
imagetext display style. The following options are supported:

Specifies the distance between the bitmap/image and the text string,
in number of pixels.

TEXT ITEMS

Display items of the type text are used to display a text string
in a widget. Text items support the following options:

ITEM OPTIONS

[ -style textStyle TextStyle ]
Specifies the display style to use for this text item. Must be the
name of a text display style that has already be created by the
tixDisplayStyle(n) command.
[ -text text Text ]
Specifies the text string to display in the item.
[ -underline underline Underline ]
Specifies the integer index of a character to underline in the item.
0 corresponds to the first character of the text displayed in the
widget, 1 to the next character, and so on.

CREATING DISPLAY ITEMS

Display items do not exist on their and thus they cannot be created
independently of the widgets they reside in. As a rule, display items
are created by special widget commands of their "host" widgets. For
example, the HList widgets has a command item which can be used
to create new display items. The following code creates a new imagetext
item at the third column of the entry foo inside an HList widget:

The item create command of the HList widget accepts a variable
number of arguments. The special argument -itemtype specifies
which type of display item to create. Options that are valid for this
type of display items can then be specified by one or more
option-value pairs.

After the display item is created, they can then be configured or
destroyed using the commands provided by the host widget. For example,
the HList widget has the command item configure, item cget
and item delete for accessing the display items.

CREATING AND MANIPULATING DISPLAY STYLES

Display styles are created by the command tixDisplayStyle:

itemType must be one of the existing display items types such as
text, imagetext, window or any new types added by
the user. Additional arguments can be given in one or more
option-value pairs. option can be any of the valid option
for this display style or any of the following:

-stylename name

Specifies a name for this style. If unspecified, then a default name
will be chosen for this style.

-refwindow pathName

Specifies a window to use for determine the default values of the
display type. If unspecified, the main window will be used. Default
values for the display types can be set via the options database. The
following example sets the -disablebackground and
-disabledforeground options of a text display style via
the option database:
option add *table.list*disabledForeground blue
option add *table.list*disabledBackground darkgray
tixDisplayStyle text -refwindow .table.list -fg red

By using the option database to set the options of the display styles,
we can advoid hard-coding the option values and give the user more
flexibility in customization. See option(n) for a detailed description
of the option database.

STYLE COMMAND

The tixDisplayStyle command creates a new Tcl command whose name is the
same as the name of the newly created display style. This command
may be used to invoke various operations on the display style. It has the
following general form:

styleName option ?arg arg ...?

styleName is the name of the command. Option and the
args determine the exact behavior of the command. The following
commands are possible:

styleName cgetoption

Returns the current value of the configuration option given by
option. Option may have any of the valid options of this
display style.

styleName configure ?option? ?value option value ...?

Query or modify the configuration options of the display style. If no
option is specified, returns a list describing all of the
available options for styleName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option-value pairs are specified, then the command
modifies the given option(s) to have the given value(s); in this case
the command returns an empty string. Option may have any of the
valid options of this display style.

styleName delete

Destroy this display style object.

EXAMPLE

The following example creates two columns of data in a HList
widget. The first column is in red and the second column in blue. The
colors of the columns are controlled by two different text
styles. Also, the anchor and font of the second column is chosen so
that the income data is aligned properly.