1DItem(3)              User Contributed Perl Documentation             DItem(3)
2
3
4

NAME

6       Tk::DItem - Tix Display Items
7

SYNOPSIS

DESCRIPTION

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
14       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
22       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
29       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
34       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
49       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
54       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

DISPLAY ITEM TYPES AND OPTIONS

65       Currently there are three types of display items: text, imagetext and
66       window.
67

IMAGETEXT ITEMS

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
73   Imagetext Item Options
74       Name:     bitmap
75       Class:    Bitmap
76       Switch:   -bitmap
77           Specifies the bitmap to display in the item.
78
79       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
85       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
92       Name:     showImage
93       Class:    ShowImage
94       Switch:   -showimage
95           A Boolean value that specifies whether the image/bitmap should be
96           displayed.
97
98       Name:     showText
99       Class:    ShowText
100       Switch:   -showtext
101           A Boolean value that specifies whether the text string should be
102           displayed.
103
104       Name:     text
105       Class:    Text
106       Switch:   -text
107           Specifies the text string to display in the item.
108
109       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
116   Imagetext Style Options
117       The style information of imagetext items are stored in the imagetext
118       display style. The following options are supported:
119
120       STANDARD OPTIONS
121
122       -activebackground   -activeforeground -anchor   -background
123       -disabledbackground -disabledforeground -foreground    -font
124       -justify  -padx -pady     -selectbackground
125       -selectforeground   -wraplength
126
127       See Tk::options for details of the standard options.
128
129       STYLE-SPECIFIC OPTIONS
130
131       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
137       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
144           n       Text is centred above the image.
145
146           s       Text is centred below the image
147
148           e       Text is centred to right of the image.
149
150           w       Text is centred to left of the image.
151
152           c       Text is centred over the image.
153
154           The sw, se, ne, and b<nw> cases look rather odd.
155
156           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

TEXT ITEMS

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
164   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
172       Name:     text
173       Class:    Text
174       Switch:   -text
175           Specifies the text string to display in the item.
176
177       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
184   Text Style Options
185       STANDARD OPTIONS
186
187       -activebackground   -activeforeground -anchor   -background
188       -disabledbackground -disabledforeground -foreground    -font
189       -justify  -padx -pady     -selectbackground
190       -selectforeground   -wraplength
191
192       See Tk::options for details of the standard options.
193

WINDOW ITEMS

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
198   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
206       Name:     window
207       Class:    Window
208       Switch:   -window
209       Alias:    -widget
210           Specifies the sub-window to display in the item.
211
212   Window Style Options
213       STYLE STANDARD OPTIONS
214
215       -anchor   -padx     -pady
216
217       See Tk::options for details of the standard options.
218

CREATING DISPLAY ITEMS

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
227        my $hlist = $parent->HList(-columns=>3);
228        $hlist->add('foo');
229        $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');
230
231       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
236       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

CREATING AND MANIPULATING ITEM STYLES

242       Item styles are created with ItemStyle:
243

SYNOPSIS

245          $widget->ItemStyle(itemType ?,-stylename=>name?
246       ?,-refwindow=>pathName? ?,option=>value, ...>?);
247
248       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
253       -stylename => name
254           Specifies a name for this style. If unspecified, then a default
255           name will be chosen for this style.
256
257       -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
265             $widget->optionAdd('*table.list*disabledForeground' => 'blue');
266             $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
267             $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');
268
269           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

STYLE METHODS

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
279       The following additional methods are available for item styles:
280
281       $style->delete
282           Destroy this display style object.
283

EXAMPLE

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
291          use strict;
292          use Tk;
293          use Tk::HList;
294          use Tk::ItemStyle;
295
296          my $mw = MainWindow->new();
297
298          my $hlist = $mw->HList(-columns=>2)->pack;
299
300          my $red  = $hlist->ItemStyle('text', -foreground=>'#800000');
301          my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');
302
303          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
313          Tk::MainLoop;
314

SEE ALSO

316       Tk::HList Tk::TixGrid Tk::TList
317

KEYWORDS

319       display item, display style, item style
320
321
322
323perl v5.12.0                      2010-05-13                          DItem(3)
Impressum