1DItem(3) User Contributed Perl Documentation DItem(3)
2
6 Tk::DItem - Tix Display Items
7
10 The Tix Display Items and Display Types are devised to solve a general
11 problem: many Tix widgets (both existing and planned ones) display many
12 items of many types simultaneously.
13 For example, a hierarchical listbox widget (see Tk::HList) can display
15 items of images, plain text and subwindows in the form of a hierarchy.
16 Another widget, the tabular listbox widget (see Tk::TList) also dis‐
17 plays items of the same types, although it arranges the items in a tab‐
18 ular form. Yet another widget, the spreadsheet widget (see Tk::Tix‐
19 Grid), also displays similar types items, but in yet another format.
20 In these examples, the display items in different widgets are only dif‐
22 ferent in how they are arranged by the host widget. In Tix, display
23 items are clearly separated from the host widgets. The advantage is
24 two-fold: first, the creation and configuration of display items become
25 uniform across different host widgets. Second, new display item types
26 can be added without the need to modify the existing host widgets.
27 In a way, Tix display items are similar to the items inside Tk the can‐
29 vas widget. However, unlike the Tix display items, the canvas items are
30 not independent of the canvas widget; this makes it impossible to use
31 the canvas items inside other types of TK widgets.
32 The appearance of a display item is controlled by a set of attributes.
34 It is observed that each the attributes usually fall into one of two
35 categroies: ``individual'' or ``collective''. For example, the text
36 items inside a HList widget may all display a different text string;
37 however, in most cases, the text items share the same color, font and
38 spacing. Instead of keeping a duplicated version of the same attributes
39 inside each display item, it will be advantageous to put the collective
40 attributes in a special object called a display style. First, there is
41 the space concern: a host widget may have many thousands of items;
42 keeping dupilcated attributes will be very wasteful. Second, when it
43 becomes necessary to change a collective attribute, such as changing
44 all the text items' foreground color to red, it will be more efficient
45 to change only the display style object than to modify all the text
46 items one by one.
47 The attributes of the a display item are thus stored in two places: it
49 has a set of item options to store its individual attributes. Each dis‐
50 play item is also associated with a display style, which specifies the
51 collective attributes of all items associated with itself.
52 The division between the individual and collective attributes are fixed
54 and cannot be changed. Thus, when it becomes necessary for some items
55 to differ in their collective attributes, two or more display styles
56 can be used. For example, suppose you want to display two columns of
57 text items inside an HList widget, one column in red and the other in
58 blue. You can create a TextStyle object called ``$red'' which defines a
59 red foreground, and another called ``$blue'', which defines a blue
60 foreground. You can then associate all text items of the first column
61 to ``$red'' and the second column to ``$blue''
62
64 Currently there are three types of display items: text, imagetext and
65 window.
66
68 Display items of the type imagetext are used to display an image
69 together with a text string. Imagetext items support the following
70 options:
71 Imagetext Item Options
73 Name: bitmap
75 Class: Bitmap
76 Switch: -bitmap
77 Specifies the bitmap to display in the item.
78 Name: image
80 Class: Image
81 Switch: -image
82 Specifies the image to display in the item. When both the -bitmap
83 and -image options are specified, only the image will be displayed.
84 Name: imageTextStyle
86 Class: ImageTextStyle
87 Switch: -style
88 Specifies the display style to use for this item. Must be the name
89 of a imagetext display style that has already be created with Item‐
90 Style.
91 Name: showImage
93 Class: ShowImage
94 Switch: -showimage
95 A Boolean value that specifies whether the image/bitmap should be
96 displayed.
97 Name: showText
99 Class: ShowText
100 Switch: -showtext
101 A Boolean value that specifies whether the text string should be
102 displayed.
103 Name: text
105 Class: Text
106 Switch: -text
107 Specifies the text string to display in the item.
108 Name: underline
110 Class: Underline
111 Switch: -underline
112 Specifies the integer index of a character to underline in the text
113 string in the item. 0 corresponds to the first character of the
114 text displayed in the widget, 1 to the next character, and so on.
115 Imagetext Style Options
117 The style information of imagetext items are stored in the imagetext
119 display style. The following options are supported:
120 STANDARD OPTIONS
122 -activebackground -activeforeground -anchor -background -disabled‐
124 background -disabledforeground -foreground -font -justify -padx
125 -pady -selectbackground -selectforeground -wraplength
126 See Tk::options for details of the standard options.
128 STYLE-SPECIFIC OPTIONS
130 Name: gap
132 Class: Gap
133 Switch: -gap
134 Specifies the distance between the bitmap/image and the text
135 string, in number of pixels.
136 Name: textAnchor
138 Class: TextAnchor
139 Switch: -textanchor
140 The anchor position on the image to which text part is attached.
141 This is a perl/Tk addition. Defaults to e for compatibility with
142 standard Tix. The interesting cases are
143 n Text is centred above the image.
145 s Text is centred below the image
147 e Text is centred to right of the image.
149 w Text is centred to left of the image.
151 c Text is centred over the image.
153 The sw, se, ne, and b<nw> cases look rather odd.
155 To get items to line up correctly it will usually be necessary to
157 specify -anchor as well. e.g. with default e then anchoring item as
158 a whole w lines images up down left with text stuck to right side.
159
161 Display items of the type text are used to display a text string in a
162 widget. Text items support the following options:
163 Text Item Options
165 Name: textStyle
167 Class: TextStyle
168 Switch: -style
169 Specifies the display style to use for this text item. Must be the
170 name of a text display style that has already be created with Item‐
171 Style.
172 Name: text
174 Class: Text
175 Switch: -text
176 Specifies the text string to display in the item.
177 Name: underline
179 Class: Underline
180 Switch: -underline
181 Specifies the integer index of a character to underline in the
182 item. 0 corresponds to the first character of the text displayed
183 in the widget, 1 to the next character, and so on.
184 Text Style Options
186 STANDARD OPTIONS
188 -activebackground -activeforeground -anchor -background -disabled‐
190 background -disabledforeground -foreground -font -justify -padx
191 -pady -selectbackground -selectforeground -wraplength
192 See Tk::options for details of the standard options.
194
196 Display items of the type window are used to display a sub-window in a
197 widget. Window items support the following options:
198 Window Item Options
200 Name: windowStyle
202 Class: WindowStyle
203 Switch: -style
204 Specifies the display style to use for this window item. Must be
205 the name of a window display style that has already be created with
206 the ItemStyle method.
207 Name: window
209 Class: Window
210 Switch: -window
211 Alias: -widget
212 Specifies the sub-window to display in the item.
213 Window Style Options
215 STYLE STANDARD OPTIONS
217 -anchor -padx -pady
219 See Tk::options for details of the standard options.
221
223 Display items do not exist on their and thus they cannot be created
224 independently of the widgets they reside in. As a rule, display items
225 are created by special methods of their ``host'' widgets. For example,
226 the HList widgets has a method item which can be used to create new
227 display items. The following code creates a new text item at the third
228 column of the entry foo inside an HList widget:
229 my $hlist = $parent->HList(-columns=>3);
231 $hlist->add('foo');
232 $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');
233 The itemCreate method of the HList widget accepts a variable number of
235 arguments. The special argument -itemtype specifies which type of dis‐
236 play item to create. Options that are valid for this type of display
237 items can then be specified by one or more option-value pairs.
238 After the display item is created, they can then be configured or
240 destroyed using the methods provided by the host widget. For example,
241 the HList widget has the methods itemConfigure, itemCget and itemDelete
242 for accessing the display items.
243
245 Item styles are created with ItemStyle:
246
248 $widget->ItemStyle(itemType ?,-stylename=>name? ?,-refwindow=>path‐
249 Name? ?,option=>value, ...>?);
250 itemType must be one of the existing display items types such as text,
252 imagetext, window or any new types added by the user. Additional argu‐
253 ments can be given in one or more option-value pairs. option can be any
254 of the valid option for this display style or any of the following:
255 -stylename => name
257 Specifies a name for this style. If unspecified, then a default
258 name will be chosen for this style.
259 -refwindow => $otherwidget
261 Specifies a window to use for determine the default values of the
262 display type. If unspecified, the $widget will be used. Default
263 values for the display types can be set via the options database.
264 The following example sets the -disablebackground and -disabled‐
265 foreground options of a text display style via the option database:
266 $widget->optionAdd('*table.list*disabledForeground' => 'blue');
268 $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
269 $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');
270 By using the option database to set the options of the display
272 styles, we can advoid hard-coding the option values and give the
273 user more flexibility in customization. See Tk::option for a
274 detailed description of the option database.
275
277 The ItemStyle method creates an object. This object supports the con‐
278 figure and cget methods described in Tk::options which can be used to
279 enquire and modify the options described above.
280 The following additional methods are available for item styles:
282 $style->delete
284 Destroy this display style object.
285
287 The following example creates two columns of data in a HList widget.
288 The first column is in red and the second column in blue. The colors of
289 the columns are controlled by two different text styles. Also, the
290 anchor and font of the second column is chosen so that the income data
291 is aligned properly.
292 use strict;
294 use Tk;
295 use Tk::HList;
296 use Tk::ItemStyle;
297 my $mw = MainWindow->new();
299 my $hlist = $mw->HList(-columns=>2)->pack;
301 my $red = $hlist->ItemStyle('text', -foreground=>'#800000');
303 my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');
304 my $e;
306 foreach ([Joe => '$10,000'], [Peter => '$20,000'],
307 [Raj => '$90,000'], [Zinh => '$0']) {
308 $e = $hlist->addchild("");
309 $hlist->itemCreate($e, 0, -itemtype=>'text',
310 -text=>$_->[0], -style=>$red );
311 $hlist->itemCreate($e, 1, -itemtype=>'text',
312 -text=>$_->[1], -style=>$blue);
313 }
314 Tk::MainLoop;
316
318 Tk::HList Tk::TixGrid Tk::TList
319
321 display item, display style, item style
322perl v5.8.8 2008-02-05 DItem(3)