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 gen
eral 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 dis
play 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 usu
ally 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. Sec
ond, when it becomes necessary to change a collective
attribute, such as changing all the text items' foreground
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 associ
ated 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 col
lective 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
play 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 sup
ported:
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.
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 dis
play 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
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.
Command-Line Name:-window or -widget
Database Name: window
Database Class: Window
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 com
mands of their "host" widgets. For example, the HList wid
gets 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
variable number of arguments. The special argument -item
type 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 con
figured 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 unspeci
fied, 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 dis
play 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
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 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
Man(1) output converted with
man2html