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
17 displays items of the same types, although it arranges the items in a
18 tabular form. Yet another widget, the spreadsheet widget (see
19 Tk::TixGrid), also displays similar types items, but in yet another
20 format.
21 In these examples, the display items in different widgets are only
23 different in how they are arranged by the host widget. In Tix, display
24 items are clearly separated from the host widgets. The advantage is
25 two-fold: first, the creation and configuration of display items become
26 uniform across different host widgets. Second, new display item types
27 can be added without the need to modify the existing host widgets.
28 In a way, Tix display items are similar to the items inside Tk the
30 canvas widget. However, unlike the Tix display items, the canvas items
31 are not independent of the canvas widget; this makes it impossible to
32 use the canvas items inside other types of TK widgets.
33 The appearance of a display item is controlled by a set of attributes.
35 It is observed that each the attributes usually fall into one of two
36 categroies: ``individual'' or ``collective''. For example, the text
37 items inside a HList widget may all display a different text string;
38 however, in most cases, the text items share the same color, font and
39 spacing. Instead of keeping a duplicated version of the same attributes
40 inside each display item, it will be advantageous to put the collective
41 attributes in a special object called a display style. First, there is
42 the space concern: a host widget may have many thousands of items;
43 keeping dupilcated attributes will be very wasteful. Second, when it
44 becomes necessary to change a collective attribute, such as changing
45 all the text items' foreground color to red, it will be more efficient
46 to change only the display style object than to modify all the text
47 items one by one.
48 The attributes of the a display item are thus stored in two places: it
50 has a set of item options to store its individual attributes. Each
51 display item is also associated with a display style, which specifies
52 the collective attributes of all items associated with itself.
53 The division between the individual and collective attributes are fixed
55 and cannot be changed. Thus, when it becomes necessary for some items
56 to differ in their collective attributes, two or more display styles
57 can be used. For example, suppose you want to display two columns of
58 text items inside an HList widget, one column in red and the other in
59 blue. You can create a TextStyle object called ``$red'' which defines a
60 red foreground, and another called ``$blue'', which defines a blue
61 foreground. You can then associate all text items of the first column
62 to ``$red'' and the second column to ``$blue''
63
65 Currently there are three types of display items: text, imagetext and
66 window.
67
69 Display items of the type imagetext are used to display an image
70 together with a text string. Imagetext items support the following
71 options:
72 Imagetext Item Options
74 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
90 ItemStyle.
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
118 display style. The following options are supported:
119 STANDARD OPTIONS
121 -activebackground -activeforeground -anchor -background
123 -disabledbackground -disabledforeground -foreground -font
124 -justify -padx -pady -selectbackground
125 -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
166 Class: TextStyle
167 Switch: -style
168 Specifies the display style to use for this text item. Must be the
169 name of a text display style that has already be created with
170 ItemStyle.
171 Name: text
173 Class: Text
174 Switch: -text
175 Specifies the text string to display in the item.
176 Name: underline
178 Class: Underline
179 Switch: -underline
180 Specifies the integer index of a character to underline in the
181 item. 0 corresponds to the first character of the text displayed
182 in the widget, 1 to the next character, and so on.
183 Text Style Options
185 STANDARD OPTIONS
186 -activebackground -activeforeground -anchor -background
188 -disabledbackground -disabledforeground -foreground -font
189 -justify -padx -pady -selectbackground
190 -selectforeground -wraplength
191 See Tk::options for details of the standard options.
193
195 Display items of the type window are used to display a sub-window in a
196 widget. Window items support the following options:
197 Window Item Options
199 Name: windowStyle
200 Class: WindowStyle
201 Switch: -style
202 Specifies the display style to use for this window item. Must be
203 the name of a window display style that has already be created with
204 the ItemStyle method.
205 Name: window
207 Class: Window
208 Switch: -window
209 Alias: -widget
210 Specifies the sub-window to display in the item.
211 Window Style Options
213 STYLE STANDARD OPTIONS
214 -anchor -padx -pady
216 See Tk::options for details of the standard options.
218
220 Display items do not exist on their and thus they cannot be created
221 independently of the widgets they reside in. As a rule, display items
222 are created by special methods of their ``host'' widgets. For example,
223 the HList widgets has a method item which can be used to create new
224 display items. The following code creates a new text item at the third
225 column of the entry foo inside an HList widget:
226 my $hlist = $parent->HList(-columns=>3);
228 $hlist->add('foo');
229 $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');
230 The itemCreate method of the HList widget accepts a variable number of
232 arguments. The special argument -itemtype specifies which type of
233 display item to create. Options that are valid for this type of display
234 items can then be specified by one or more option-value pairs.
235 After the display item is created, they can then be configured or
237 destroyed using the methods provided by the host widget. For example,
238 the HList widget has the methods itemConfigure, itemCget and itemDelete
239 for accessing the display items.
240
242 Item styles are created with ItemStyle:
243
245 $widget->ItemStyle(itemType ?,-stylename=>name?
246 ?,-refwindow=>pathName? ?,option=>value, ...>?);
247 itemType must be one of the existing display items types such as text,
249 imagetext, window or any new types added by the user. Additional
250 arguments can be given in one or more option-value pairs. option can be
251 any of the valid option for this display style or any of the following:
252 -stylename => name
254 Specifies a name for this style. If unspecified, then a default
255 name will be chosen for this style.
256 -refwindow => $otherwidget
258 Specifies a window to use for determine the default values of the
259 display type. If unspecified, the $widget will be used. Default
260 values for the display types can be set via the options database.
261 The following example sets the -disablebackground and
262 -disabledforeground options of a text display style via the option
263 database:
264 $widget->optionAdd('*table.list*disabledForeground' => 'blue');
266 $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
267 $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');
268 By using the option database to set the options of the display
270 styles, we can advoid hard-coding the option values and give the
271 user more flexibility in customization. See Tk::option for a
272 detailed description of the option database.
273
275 The ItemStyle method creates an object. This object supports the
276 configure and cget methods described in Tk::options which can be used
277 to enquire and modify the options described above.
278 The following additional methods are available for item styles:
280 $style->delete
282 Destroy this display style object.
283
285 The following example creates two columns of data in a HList widget.
286 The first column is in red and the second column in blue. The colors of
287 the columns are controlled by two different text styles. Also, the
288 anchor and font of the second column is chosen so that the income data
289 is aligned properly.
290 use strict;
292 use Tk;
293 use Tk::HList;
294 use Tk::ItemStyle;
295 my $mw = MainWindow->new();
297 my $hlist = $mw->HList(-columns=>2)->pack;
299 my $red = $hlist->ItemStyle('text', -foreground=>'#800000');
301 my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');
302 my $e;
304 foreach ([Joe => '$10,000'], [Peter => '$20,000'],
305 [Raj => '$90,000'], [Zinh => '$0']) {
306 $e = $hlist->addchild("");
307 $hlist->itemCreate($e, 0, -itemtype=>'text',
308 -text=>$_->[0], -style=>$red );
309 $hlist->itemCreate($e, 1, -itemtype=>'text',
310 -text=>$_->[1], -style=>$blue);
311 }
312 Tk::MainLoop;
314
316 Tk::HList Tk::TixGrid Tk::TList
317
319 display item, display style, item style
320perl v5.38.0 2023-07-21 DItem(3)