1tixDisplayStyle(n)           Tix Built-In Commands          tixDisplayStyle(n)
2
3
4

NAME

6       tixDisplayStyle - Create style object for Tix display items.
7

SYNOPSIS

9       tixDisplayStyle   itemType   ?-stylename  name?  ?-refwindow  pathName?
10       ?options value ...?
11

DESCRIPTION

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
17       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
25       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
32       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
37       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
52       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
57       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

DISPLAY ITEM TYPES AND OPTIONS

68       Currently there are four types of display items: text, image, imagetext
69       and window. (TODO: need to document the "image" item)
70

IMAGETEXT ITEMS

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
76       ITEM OPTIONS
77
78              [-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
94       STYLE OPTIONS
95
96       The  style  information  of imagetext items are stored in the imagetext
97       display style. The following options are supported:
98
99              STANDARD OPTIONS
100
101              activeBackground        activeForeground
102              anchor                  background
103              disabledBackground      disabledForeground
104              foreground              font
105              justify                 padX
106              padY                    selectBackground
107              selectForeground        wrapLength
108
109              See the options(n) manual entry  for  details  on  the  standard
110              options.
111
112              STYLE-SPECIFIC OPTIONS
113
114              Name:           gap
115              Class:          Gap
116              Switch:         -gap
117
118                     Specifies  the  distance between the bitmap/image and the
119                     text string, in number of pixels.
120

TEXT ITEMS

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
125       ITEM OPTIONS
126
127              [-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
137              STANDARD OPTIONS
138
139              activeBackground        activeForeground
140              anchor                  background
141              disabledBackground      disabledForeground
142              foreground              font
143              justify                 padX
144              padY                    selectBackground
145              selectForeground        wrapLength
146
147              See the options(n) manual entry  for  details  on  the  standard
148              options.
149

WINDOW ITEMS

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
154       ITEM OPTIONS
155
156              [-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
160              Name:           window
161              Class:          Window
162              Switch:         -window
163              Alias:          -widget
164
165                     Specifies the sub-window to display in the item.
166       STYLE OPTIONS
167
168              STANDARD OPTIONS
169
170              anchor
171              padX                    padY
172
173              See the options(n) manual entry  for  details  on  the  standard
174              options.
175

CREATING DISPLAY ITEMS

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
184        tixHList .h -columns 3
185        .h add foo
186        .h item create foo 2 -itemtype imagetext -text Hello -image image1
187
188       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
193       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

CREATING AND MANIPULATING DISPLAY STYLES

199       Display styles are created by the command tixDisplayStyle:
200
201       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
206              -stylename name
207                     Specifies  a  name for this style. If unspecified, then a
208                     default name will be chosen for this style.
209
210              -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
221              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

STYLE COMMAND

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
235       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
240       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
253       styleName delete
254              Destroy this display style object.
255

EXAMPLE

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
263       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
268       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

KEYWORDS

276       display item, display style, imagetext
277
278
279
280Tix                                   8.0                   tixDisplayStyle(n)
Impressum