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

NAME

6       tixTList - Create and manipulate Tix Tabular List widgets
7

SYNOPSIS

9       tixTList    pathName   ?options?    -background    -borderWidth   -cur‐
10       sor   -foreground -font     -height   -highlightColor  -highlightThick‐
11       ness       -relief   -selectBackground   -selectForeground -xScrollCom‐
12       mand     -yScrollCommand     -width
13

WIDGET-SPECIFIC OPTIONS

15       [-browsecmd browsecmd] Specifies a TCL command to be executed when  the
16       user  browses  through the entries in the TList widget.  [-command com‐
17       mand] Specifies the TCL command to be executed when the user invokes  a
18       list  entry in the TList widget. Normally the user invokes a list entry
19       by double-clicking it or pressing the Return  key.   [-foreground fore‐
20       ground]  Specifies  the  default foreground color for the list entries.
21       [-height height] Specifies the desired height for the window in  number
22       of characters.  [-itemtype itemType] Specifies the default type of dis‐
23       play item for this TList widget. When you call the insert  widget  com‐
24       mands,  display  items  of  this  type will be created if the -itemtype
25       option is not specified .  [-orient orient] Specifies the order of tab‐
26       ularizing  the  list  entries.  When set to "vertical", the entries are
27       arranged in a column, from top to bottom. If the entries cannot be con‐
28       tained in one column, the remaining entries will go to the next column,
29       and so on. When set to "horizontal", the entries are arranged in a row,
30       from  left to right. If the entries cannot be contained in one row, the
31       remaining entries will go to the next row, and so on.  [-padx padX] The
32       default  horizontal padding for list entries.  [-padx padY] The default
33       vertical  padding  for  list  entries.   [-selectbackground selectBack‐
34       ground]  Specifies  the background color for the selected list entries.
35       [-selectborderwidth selectBorderWidth] Specifies a  non-negative  value
36       indicating  the  width of the 3-D border to draw around selected items.
37       The value may  have  any  of  the  forms  acceptable  to  Tk_GetPixels.
38       [-selectforeground selectForeground] Specifies the foreground color for
39       the selected list entries.  [-selectmode selectMode] Specifies  one  of
40       several styles for manipulating the selection.  The value of the option
41       may be arbitrary, but the default bindings expect it to be either  sin‐
42       gle,  browse,  multiple,  or  extended;  the  default  value is single.
43       [-sizecmd sizeCmd] Specifies a TCL script to  be  called  whenever  the
44       TList  widget changes its size. This command can be useful to implement
45       "user scroll bars  when  needed"  features.   [-state state]  Specifies
46       whether  the  TList  command  should react to user actions. When set to
47       "normal", the TList reacts to user actions in the normal way. When  set
48       to  "disabled",  the TList can only be scrolled, but its entries cannot
49       be selected or activated.  [-width width] Specifies the  desired  width
50       for the window in characters.
51

DESCRIPTION

53       The  tixTList command creates a new window (given by the pathName argu‐
54       ment) and makes it into a TList widget.  Additional options,  described
55       above,  may  be specified on the command line or in the option database
56       to configure aspects of the TList widget such as its cursor and relief.
57
58       The TList widget can be used to display data in a tabular  format.  The
59       list  entries  of  a  TList widget are similar to the entries in the Tk
60       listbox widget. The main differences are (1) the TList widget can  dis‐
61       play  the  list entries in a two dimensional format and (2) you can use
62       graphical images as well as multiple colors  and  fonts  for  the  list
63       entries.
64
65       Each  list entry is identified by an index, which can be in the follow‐
66       ing forms:
67
68              number An integer that indicates the position of  the  entry  in
69                     the  list. 0 means the first position, 1 means the second
70                     position, and so on.
71
72              end    Indicates the end of the listbox. For some commands  this
73                     means  just  after  the last entry; for other commands it
74                     means the last entry.
75
76              @x,y   Indicates the element that covers the point in the  list‐
77                     box  window  specified by x and y (in pixel coordinates).
78                     If no element covers that point, then the closest element
79                     to that point is used.
80

DISPLAY ITEMS

82       Each  list  entry in an TList widget is associated with a display item.
83       The display item determines what visual information should be displayed
84       for  this  list entry. Please see the tixDisplayStyle manual page for a
85       list of all display items.
86
87       When a list entry is created by the insert command,  the  type  of  its
88       display item is determined by the -itemtype option passed to these com‐
89       mands. If the -itemtype is omitted, then by default the type  specified
90       by this TList widget's -itemtype option is used.
91

WIDGET COMMAND

93       The  tixTList  command creates a new Tcl command whose name is the same
94       as the path name of the TList widget's window.   This  command  may  be
95       used  to invoke various operations on the widget.  It has the following
96       general form:
97              pathName option ?arg arg ...?
98       PathName is the name of the command, which is the  same  as  the  TList
99       widget's  path  name.  Option and the args determine the exact behavior
100       of the command.  The following commands are possible for TList widgets:
101
102       pathName anchor set index
103              Sets the anchor to the  list  entry  identified  by  index.  The
104              anchor  is the end of the selection that is fixed while dragging
105              out a selection with the mouse.
106
107       pathName anchor clear
108              Removes the anchor, if any, from this TList  widget.  This  only
109              removes  the surrounding highlights of the anchor entry and does
110              not affect its selection status.
111
112       pathName cget option
113              Returns the current value of the configuration option  given  by
114              option.  Option  may  have  any  of  the  values accepted by the
115              tixTList command.
116
117       pathName configure ?option? ?value option value ...?
118              Query or modify the configuration options of the widget.  If  no
119              option is specified, returns a list describing all of the avail‐
120              able options for pathName (see Tk_ConfigureInfo for  information
121              on  the  format  of  this  list). If option is specified with no
122              value, then the command returns a list describing the one  named
123              option (this list will be identical to the corresponding sublist
124              of the value returned if no option is  specified).   If  one  or
125              more option-value pairs are specified, then the command modifies
126              the given widget option(s) to have the given value(s);  in  this
127              case  the  command returns an empty string.  Option may have any
128              of the values accepted by the tixTList command.
129
130       pathName delete from ?to?
131              Deletes one or more list entries between the two entries  speci‐
132              fied by the indices from and to. If to is not specified, deletes
133              the single entry specified by from.
134
135       pathName dragsite set index
136              Sets the dragsite to the list entry  identified  by  index.  The
137              dragsite  is  used  to  indicate  the  source of a drag-and-drop
138              action.  Currently  drag-and-drop  functionality  has  not  been
139              implemented in Tix yet.
140
141       pathName dragsite clear
142              Remove  the  dragsite,  if any, from the this TList widget. This
143              only removes the surrounding highlights of  the  dragsite  entry
144              and does not affect its selection status.
145
146       pathName dropsite set index
147              Sets  the  dropsite  to  the list entry identified by index. The
148              dropsite is used to  indicate  the  target  of  a  grag-and-drop
149              action.  Currently  drag-and-drop  functionality  has  not  been
150              implemented in Tix yet.
151
152       pathName dropsite clear
153              Remove the dropsite, if any, from the this  TList  widget.  This
154              only  removes  the  surrounding highlights of the dropsite entry
155              and does not affect its selection status.
156
157       pathName entrycget index option
158              Returns the current value of the configuration option  given  by
159              option for the entry indentfied by index. Option may have any of
160              the values accepted by the insert widget command.
161
162       pathName entryconfigure index ?option? ?value option value ...?
163              Query or modify the configuration  options  of  the  list  entry
164              indentfied  by  index. If no option is specified, returns a list
165              describing all of the available options for index  (see  Tk_Con‐
166              figureInfo  for  information  on  the  format  of this list). If
167              option is specified with no value, then the  command  returns  a
168              list  describing the one named option (this list will be identi‐
169              cal to the corresponding sublist of the  value  returned  if  no
170              option  is  specified).  If  one  or more option-value pairs are
171              specified, then the command modifies the given option(s) to have
172              the  given  value(s);  in this case the command returns an empty
173              string.  Option may have any  of  the  values  accepted  by  the
174              insert  widget  command. The exact set of options depends on the
175              value of the -itemtype option passed to the  the  insert  widget
176              command when this list entry is created.
177
178       pathName insert index ?option value ...?
179              Creates a new list entry at the position indicated by index. The
180              following configuration options can be given  to  configure  the
181              list entry:
182
183              -itemtype type
184                     Specifies  the type of display item to be display for the
185                     new list entry. type must be a valid display  item  type.
186                     Currently  the  available  display  item types are image,
187                     imagetext, text, and window. If this option is not speci‐
188                     fied,  then  by  default the type specified by this TList
189                     widget's -itemtype option is used.
190
191              -state Specifies whether this entry can be selected  or  invoked
192                     by the user.  Must be either normal or disabled.
193       The  insert  widget command accepts additional configuration options to
194       configure the display item associated with this list entry. The set  of
195       additional  configuration  options  depends  on the type of the display
196       item given by the -itemtype option. Please see the tixDisplayStyle man‐
197       ual  page  for a list of the configuration options for each of the dis‐
198       play item types.
199
200       pathName info option arg ...
201              Query information about the TList widget. option can be  one  of
202              the following:
203
204              pathName info anchor index
205                     ; Returns the index of the current anchor, if any, of the
206                     TList widget. If the anchor is not set, returns the empty
207                     string.
208
209              pathName info dragsite index
210                     Returns the index of the current dragsite, if any, of the
211                     TList widget. If the dragsite is  not  set,  returns  the
212                     empty string.
213
214              pathName info dropsite index
215                     Returns the index of the current dropsite, if any, of the
216                     TList widget. If the dropsite is  not  set,  returns  the
217                     empty string.
218
219              pathName info selection
220                     Returns  a list of selected elements in the TList widget.
221                     If no entries are selectd, returns an empty string.
222
223       pathName nearest x y
224              Given an (x,y) coordinate within the TList window, this  command
225              returns  the  index of the TList element nearest to that coordi‐
226              nate.
227
228       pathName see index
229              Adjust the view in the TList so that the entry given by index is
230              visible. If the entry is already visible then the command has no
231              effect; if the entry is near one edge of  the  window  then  the
232              TList scrolls to bring the element into view at the edge; other‐
233              wise the TList widget scrolls to center the entry.
234
235       pathName selection option arg ...
236              This command is used to adjust the selection within a TList wid‐
237              get. It has several forms, depending on option:
238
239              pathName selection clear ?from? ?to?
240                     When  no  extra arguments are given, deselects all of the
241                     list entrie(s) in this TList widget. When  only  from  is
242                     given,  only  the  list entry identified by from is dese‐
243                     lected. When both from and to are given, deselects all of
244                     the  list  entrie(s)  between between from and to, inclu‐
245                     sive, without affecting the selection  state  of  entries
246                     outside that range.
247
248              pathName selection includes index
249                     Returns  1  if  the list entry indicated by index is cur‐
250                     rently selected; returns 0 otherwise.
251
252              pathName selection set from ?to?
253                     Selects all of the list entrie(s)  between  between  from
254                     and  to, inclusive, without affecting the selection state
255                     of entries outside that range. When only from  is  given,
256                     only the list entry identified by from is selected.
257
258       pathName xview args
259              This command is used to query and change the horizontal position
260              of the information in the widget's window. It can  take  any  of
261              the following forms:
262
263              pathName xview
264                     Returns  a list containing two elements.  Each element is
265                     a real fraction between 0 and 1; together  they  describe
266                     the  horizontal  span that is visible in the window.  For
267                     example, if the first element is .2 and the  second  ele‐
268                     ment  is  .6, 20% of the TList entry is off-screen to the
269                     left, the middle 40% is visible in the window, and 40% of
270                     the  entry is off-screen to the right. These are the same
271                     values  passed  to  scrollbars  via  the  -xscrollcommand
272                     option.
273
274              pathName xview index
275                     Adjusts  the  view  in  the window so that the list entry
276                     identified by index is aligned to the left  edge  of  the
277                     window.
278
279              pathName xview moveto fraction
280                     Adjusts  the  view  in the window so that fraction of the
281                     total width of the TList is off-screen to the left. frac‐
282                     tion must be a fraction between 0 and 1.
283
284              pathName xview scroll number what
285                     This  command shifts the view in the window left or right
286                     according to number and what. Number must be an  integer.
287                     What  must be either units or pages or an abbreviation of
288                     one of these. If what is units, the view adjusts left  or
289                     right by number character units (the width of the 0 char‐
290                     acter) on the display; if  it  is  pages  then  the  view
291                     adjusts  by number screenfuls. If number is negative then
292                     characters farther to the left become visible; if  it  is
293                     positive then characters farther to the right become vis‐
294                     ible.
295
296       pathName yview ?args?
297              This command is used to query and change the  vertical  position
298              of  the  entries  in the widget's window. It can take any of the
299              following forms:
300
301              pathName yview
302                     Returns a list containing two elements, both of which are
303                     real  fractions between 0 and 1.  The first element gives
304                     the position of the list element at the top of  the  win‐
305                     dow,  relative  to  the TList as a whole (0.5 means it is
306                     halfway through the TList, for example).  The second ele‐
307                     ment  gives the position of the list entry just after the
308                     last one in the window, relative to the TList as a whole.
309                     These  are  the  same values passed to scrollbars via the
310                     -yscrollcommand option.
311
312              pathName yview index
313                     Adjusts the view in the window so  that  the  list  entry
314                     given by index is displayed at the top of the window.
315
316              pathName yview moveto fraction
317                     Adjusts  the  view  in  the window so that the list entry
318                     given by fraction appears at the top of the window. Frac‐
319                     tion is a fraction between 0 and 1; 0 indicates the first
320                     entry in the TList, 0.33 indicates  the  entry  one-third
321                     the way through the TList, and so on.
322
323              pathName yview scroll number what
324                     This  command  adjust  the  view in the window up or down
325                     according to number and what.  Number must be an integer.
326                     What  must  be  either units or pages.  If what is units,
327                     the view adjusts up or down by number  lines;  if  it  is
328                     pages  then  the  view  adjusts by number screenfuls.  If
329                     number is negative then earlier entries  become  visible;
330                     if it is positive then later entries become visible.
331

BINDINGS

333       [1]    If  the  -selectmode  is "browse", when the user drags the mouse
334              pointer over the list entries, the entry under the pointer  will
335              be  highlighted and the -browsecmd procedure will be called with
336              one parameter, the index of  the  highlighted  entry.  Only  one
337              entry  can be highlighted at a time. The -command procedure will
338              be called when the user double-clicks on a list entry.
339
340       [2]    If the -selectmode is "single", the entries will only  be  high‐
341              lighted by mouse <ButtonRelease-1> events. When a new list entry
342              is highlighted, the -browsecmd procedure will be called with one
343              parameter  indicating  the  highlighted list entry. The -command
344              procedure will be called when the user double-clicks on  a  list
345              entry.
346
347       [3]    If  the -selectmode is "multiple", when the user drags the mouse
348              pointer over the list entries, all the entries under the pointer
349              will  be  highlighted. However, only a contiguous region of list
350              entries can be selected. When the highlighted area  is  changed,
351              the -browsecmd procedure will be called with an undefined param‐
352              eter. It is the responsibility of the  -browsecmd  procedure  to
353              find out the exact highlighted selection in the TList. The -com‐
354              mand procedure will be called when the user double-clicks  on  a
355              list entry.
356
357       [4]    If  the -selectmode is "extended", when the user drags the mouse
358              pointer over the list entries, all the entries under the pointer
359              will  be  highlighted.  The user can also make disjointed selec‐
360              tions using <Control-ButtonPress-1>. When the  highlighted  area
361              is  changed,  the  -browsecmd  procedure  will be called with an
362              undefined parameter. It is the responsibility of the  -browsecmd
363              procedure  to  find  out  the exact highlighted selection in the
364              TList. The -command procedure will be called when the user  dou‐
365              ble-clicks on a list entry.
366

EXAMPLE

368       This  example  demonstrates how to use an TList to store a list of num‐
369       bers:
370
371       set image [tix getimage folder] set t [tixTList .t -orient vertical] $t
372       insert  end  -itemtype  imagetext -image $image -text one $t insert end
373       -itemtype imagetext -image $image -text two  $t  insert  end  -itemtype
374       imagetext  -image  $image -text three $t insert end -itemtype imagetext
375       -image $image -text four  $t  insert  end  -itemtype  imagetext  -image
376       $image -text five $t insert end -itemtype imagetext -image $image -text
377       six pack $t -expand yes -fill both
378

KEYWORDS

380       Tix(n), Tabular Listbox, Display Items
381
382
383
384
385
386
387Tix                                   4.0                          tixTList(n)
Impressum