1tixDisplayStyle(n) Tix Built-In Commands tixDisplayStyle(n)
2
6 tixDisplayStyle - Create style object for Tix display items.
7
9 tixDisplayStyle itemType ?-stylename name? ?-refwindow pathName?
10 ?options value ...?
11
13 The Tix Display Items mechanism is devised to solve a general problem:
14 many Tix widgets (both existing and planned ones) display many items of
15 many types simutaneously.
16 For example, a hierarchical listbox widget (HList) can display items of
18 images, plain text and subwindows in the form of a hierarchy. Another
19 widget, the tabular listbox, (TList, currently planned and will be
20 released in Tix 4.1) also display items of the same types, although it
21 arranges the items in a tabular form. Yet another widget, the spread‐
22 sheet widget, also displays similar types items, but in yet another
23 format.
24 In these examples, the display items in different widgets are only dif‐
26 ferent in how they are arranged by the host widget. In Tix, display
27 items are clearly separated from the host widgets. The advantage is
28 two-fold: first, the creation and configuration of display items become
29 uniform across different host widgets. Second, new display item types
30 can be added without the need to modify the existing host widgets.
31 In a way, Tix display items are similar to the items inside Tk the can‐
33 vas widget. However, unlike the Tix display items, the canvas items are
34 not independent of the canvas widget; this makes it impossible to use
35 the canvas items inside other types of TK widgets.
36 The appearance of a display item is controlled by a set of attributes.
38 It is observed that each the attributes usually fall into one of two
39 categroies: "individual" or "collective". For example, the text items
40 inside a HList widget may all display a different text string; however,
41 in most cases, the text items share the same color, font and spacing.
42 Instead of keeping a duplicated version of the same attributes inside
43 each display item, it will be advantageous to put the collective
44 attributes in a special object called a display style. First, there is
45 the space concern: a host widget may have many thousands of items;
46 keeping dupilcated attributes will be very wasteful. Second, when it
47 becomes necessary to change a collective attribute, such as changing
48 all the text items' foreground color to red, it will be more efficient
49 to change only the display style object than to modify all the text
50 items one by one.
51 The attributes of the a display item are thus stored in two places: it
53 has a set of item options to store its individual attributes. Each dis‐
54 play item is also associated with a display style, which specifies the
55 collective attributes of all items associated with itself.
56 The division between the individual and collective attributes are fixed
58 and cannot be changed. Thus, when it becomes necessary for some items
59 to differ in their collective attributes, two or more display styles
60 can be used. For example, suppose you want to display two columns of
61 text items inside an HList widget, one column in red and the other in
62 blue. You can create a TextStyle object called "red", which defines a
63 red foreground, and another called "blue", which defines a blue fore‐
64 ground. You can then associate all text items of the first column to
65 "red" and the second column to "blue".
66
68 Currently there are four types of display items: text, image, imagetext
69 and window. (TODO: need to document the "image" item)
70
72 Display items of the type imagetext are used to display an image
73 together with a text string. Imagetext items support the following
74 options:
75 ITEM OPTIONS
77 [-bitmap bitmap] Specifies the bitmap to display in the item.
79 [-image image] Specifies the image to display in the item. When
80 both the -bitmap and -image options are specified, only the
81 image will be displayed. [-style imageTextStyle] Specifies the
82 display style to use for this item. Must be the name of a image‐
83 text display style that has already be created by the tixDis‐
84 playStyle(n) command. [-showimage showImage] A Boolean value
85 that specifies whether the image/bitmap should be displayed.
86 [-showtext showText] A Boolean value that specifies whether the
87 text string should be displayed. [-text text] Specifies the
88 text string to display in the item. [-underline underline]
89 Specifies the integer index of a character to underline in the
90 text string in the item. 0 corresponds to the first character
91 of the text displayed in the widget, 1 to the next character,
92 and so on.
93 STYLE OPTIONS
95 The style information of imagetext items are stored in the imagetext
97 display style. The following options are supported:
98 STANDARD OPTIONS
100 activeBackground activeForeground
102 anchor background
103 disabledBackground disabledForeground
104 foreground font
105 justify padX
106 padY selectBackground
107 selectForeground wrapLength
108 See the options(n) manual entry for details on the standard
110 options.
111 STYLE-SPECIFIC OPTIONS
113 Name: gap
115 Class: Gap
116 Switch: -gap
117 Specifies the distance between the bitmap/image and the
119 text string, in number of pixels.
120
122 Display items of the type text are used to display a text string in a
123 widget. Text items support the following options:
124 ITEM OPTIONS
126 [-style textStyle] Specifies the display style to use for this
128 text item. Must be the name of a text display style that has
129 already be created by the tixDisplayStyle(n) command.
130 [-text text] Specifies the text string to display in the item.
131 [-underline underline] Specifies the integer index of a charac‐
132 ter to underline in the item. 0 corresponds to the first char‐
133 acter of the text displayed in the widget, 1 to the next charac‐
134 ter, and so on.
135 STYLE OPTIONS
136 STANDARD OPTIONS
138 activeBackground activeForeground
140 anchor background
141 disabledBackground disabledForeground
142 foreground font
143 justify padX
144 padY selectBackground
145 selectForeground wrapLength
146 See the options(n) manual entry for details on the standard
148 options.
149
151 Display items of the type window are used to display a sub-window in a
152 widget. Window items support the following options:
153 ITEM OPTIONS
155 [-style windowStyle] Specifies the display style to use for this
157 window item. Must be the name of a window display style that has
158 already be created by the tixDisplayStyle(n) command.
159 Name: window
161 Class: Window
162 Switch: -window
163 Alias: -widget
164 Specifies the sub-window to display in the item.
166 STYLE OPTIONS
167 STANDARD OPTIONS
169 anchor
171 padX padY
172 See the options(n) manual entry for details on the standard
174 options.
175
177 Display items do not exist on their and thus they cannot be created
178 independently of the widgets they reside in. As a rule, display items
179 are created by special widget commands of their "host" widgets. For
180 example, the HList widgets has a command item which can be used to cre‐
181 ate new display items. The following code creates a new imagetext item
182 at the third column of the entry foo inside an HList widget:
183 tixHList .h -columns 3
185 .h add foo
186 .h item create foo 2 -itemtype imagetext -text Hello -image image1
187 The item create command of the HList widget accepts a variable number
189 of arguments. The special argument -itemtype specifies which type of
190 display item to create. Options that are valid for this type of display
191 items can then be specified by one or more option-value pairs.
192 After the display item is created, they can then be configured or
194 destroyed using the commands provided by the host widget. For example,
195 the HList widget has the command item configure, item cget and item
196 delete for accessing the display items.
197
199 Display styles are created by the command tixDisplayStyle:
200 itemType must be one of the existing display items types such as text,
202 imagetext, window or any new types added by the user. Additional argu‐
203 ments can be given in one or more option-value pairs. option can be any
204 of the valid option for this display style or any of the following:
205 -stylename name
207 Specifies a name for this style. If unspecified, then a
208 default name will be chosen for this style.
209 -refwindow pathName
211 Specifies a window to use for determine the default val‐
212 ues of the display type. If unspecified, the main window
213 will be used. Default values for the display types can be
214 set via the options database. The following example sets
215 the -disablebackground and -disabledforeground options of
216 a text display style via the option database: option add
217 *table.list*disabledForeground blue option add *ta‐
218 ble.list*disabledBackground darkgray tixDisplayStyle text
219 -refwindow .table.list -fg red
220 By using the option database to set the options of the display
222 styles, we can advoid hard-coding the option values and give the
223 user more flexibility in customization. See option(n) for a
224 detailed description of the option database.
225
227 The tixDisplayStyle command creates a new Tcl command whose name is the
228 same as the name of the newly created display style. This command may
229 be used to invoke various operations on the display style. It has the
230 following general form:
231 styleName option ?arg arg ...?
232 styleName is the name of the command. Option and the args determine the
233 exact behavior of the command. The following commands are possible:
234 styleName cget option
236 Returns the current value of the configuration option given by
237 option. Option may have any of the valid options of this display
238 style.
239 styleName configure ?option? ?value option value ...?
241 Query or modify the configuration options of the display style.
242 If no option is specified, returns a list describing all of the
243 available options for styleName (see Tk_ConfigureInfo for infor‐
244 mation on the format of this list). If option is specified with
245 no value, then the command returns a list describing the one
246 named option (this list will be identical to the corresponding
247 sublist of the value returned if no option is specified). If
248 one or more option-value pairs are specified, then the command
249 modifies the given option(s) to have the given value(s); in this
250 case the command returns an empty string. Option may have any of
251 the valid options of this display style.
252 styleName delete
254 Destroy this display style object.
255
257 The following example creates two columns of data in a HList widget.
258 The first column is in red and the second column in blue. The colors of
259 the columns are controlled by two different text styles. Also, the
260 anchor and font of the second column is chosen so that the income data
261 is aligned properly.
262 set courier {courier 14} set h [tixHList .h -columns 2]; pack $h set
264 red [tixDisplayStyle text -fg #800000] set blue [tixDisplayStyle text
265 -fg #000080 \
266 -anchor e -font $courier]
267 foreach n {{Joe $10,000} {Peter $20,000} {Raj $90,000}} {
269 set entry [$h addchild {}]
270 $h item create $entry 0 -itemtype text \ -text
271 [lindex $n 0] -style $red
272 $h item create $entry 1 -itemtype text \ -text
273 [lindex $n 1] -style $blue }
274
276 display item, display style, imagetext
277Tix 8.0 tixDisplayStyle(n)