Provided by: tix-dev_8.4.3-7_amd64 
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 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] Specifies the bitmap to display in the item. [-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]
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] A Boolean value that specifies whether the image/bitmap
should be displayed. [-showtext showText] A Boolean value that specifies whether
the text string should be displayed. [-text text] Specifies the text string to
display in the item. [-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:
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
[-style 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] Specifies the text string to display in
the item. [-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.
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
[-style 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 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 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 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