tixItemType(n) Tix (4.0) tixItemType(n)
_________________________________________________________________
NAME
Tix Display Items
_________________________________________________________________
DESCRIPTION
The Tix Display Items and Display Types are 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.
Page 1 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
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 three types of display items: text,
imagetext and window.
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
Name: bitmap
Class: Bitmap
Switch: -bitmap
Specifies the bitmap to display in the item.
Name: image
Class: Image
Switch: -image
Specifies the image to display in the item. When
both the -bitmap and -image options are specified,
only the image will be displayed.
Name: imageTextStyle
Class: ImageTextStyle
Switch: -style
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.
Page 2 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
Name: showImage
Class: ShowImage
Switch: -showimage
A Boolean value that specifies whether the
image/bitmap should be displayed.
Name: showText
Class: ShowText
Switch: -showtext
A Boolean value that specifies whether the text
string should be displayed.
Name: text
Class: Text
Switch: -text
Specifies the text string to display in the item.
Name: underline
Class: Underline
Switch: -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:
STANDARD OPTIONS
activeBackground activeForeground
anchor background
disabledBackground disabledForeground
foreground font
justify padX
padY selectBackground
selectForeground wrapLength
See the options(n) manual entry for details on the
standard options.
STYLE-SPECIFIC OPTIONS
Page 3 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
Name: gap
Class: Gap
Switch: -gap
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
Name: textStyle
Class: TextStyle
Switch: -style
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.
Name: text
Class: Text
Switch: -text
Specifies the text string to display in the item.
Name: underline
Class: Underline
Switch: -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.
STYLE OPTIONS
STANDARD OPTIONS
activeBackground activeForeground
anchor background
disabledBackground disabledForeground
foreground font
justify padX
padY selectBackground
selectForeground wrapLength
See the options(n) manual entry for details on the
standard options.
Page 4 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
WINDOW ITEMS
Display items of the type window are used to display a sub-
window in a widget. Window items support the following
options:
ITEM OPTIONS
Name: windowStyle
Class: WindowStyle
Switch: -style
Specifies the display style to use for this window
item. Must be the name of a window display style
that has already be created by the
tixDisplayStyle(n) command.
Name: window
Class: Window
Switch: -window
Alias: -widget
Specifies the sub-window to display in the item.
STYLE OPTIONS
STANDARD OPTIONS
anchor
padX padY
See the options(n) manual entry for details on the
standard options.
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:
tixHList .h -columns 3
.h add foo
.h item create foo 2 -itemtype imagetext -text Hello -image image1
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
Page 5 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
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:
SYNOPSIS
tixDisplayStyle itemType ?-stylename name? ?-refwindow
pathName? ?options value ...?
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
Page 6 (printed 12/22/98)
tixItemType(n) Tix (4.0) tixItemType(n)
commands are possible:
styleName cget option
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.
set courier -*-courier-medium-r-*-*-14-*-*-*-*-*-*-*
tixHList .h -columns 2; pack .h
set red [tixDisplayStyle text -fg #800000]
set blue [tixDisplayStyle text -fg #000080 -anchor e -font $courier]
foreach n {{Joe $10,000} {Peter $20,000} {Raj $90,000} {Zinh $0}} {
set entry [.h addchild {}]
.h item create $entry 0 -itemtype text \
-text [lindex $n 0] -style $red
.h item create $entry 1 -itemtype text \
-text [lindex $n 1] -style $blue
}
Page 7 (printed 12/22/98)
