tixDisplayStyle
tixDisplayStyle(n) Tix Built-In Commands tixDisplayStyle(n)
______________________________________________________________________________
NAME
tixDisplayStyle - Create style object for Tix display items.
SYNOPSIS
tixDisplayStyle itemType ?-stylename name? ?-refwindow pathName?
?options value ...?
_________________________________________________________________
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 spread-
sheet widget, also displays similar types items, but in yet another
format.
In these examples, the display items in different widgets are only dif-
ferent 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 can-
vas 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 dis-
play 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
Command-Line Name:-bitmap
Database Name: bitmap
Database Class: Bitmap
Specifies the bitmap to display in the item.
Command-Line Name:-image
Database Name: image
Database Class: Image
Specifies the image to display in the item. When both the
-bitmap and -image options are specified, only the image
will be displayed.
Command-Line Name:-style
Database Name: imageTextStyle
Database Class: 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.
Command-Line Name:-showimage
Database Name: showImage
Database Class: ShowImage
A Boolean value that specifies whether the image/bitmap
should be displayed.
Command-Line Name:-showtext
Database Name: showText
Database Class: ShowText
A Boolean value that specifies whether the text string
should be displayed.
Command-Line Name:-text
Database Name: text
Database Class: Text
Specifies the text string to display in the item.
Command-Line Name:-underline
Database Name: underline
Database Class: 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
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
Command-Line Name:-style
Database Name: textStyle
Database Class: 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.
Command-Line Name:-text
Database Name: text
Database Class: Text
Specifies the text string to display in the item.
Command-Line Name:-underline
Database Name: underline
Database Class: 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.
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
Command-Line Name:-style
Database Name: windowStyle
Database Class: WindowStyle
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 cre-
ate 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 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 argu-
ments 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 val-
ues 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 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 infor-
mation 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 14}
set h [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}} {
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
}
KEYWORDS
display item, display style, imagetext
Tix 8.0 tixDisplayStyle(n)
