1listbox(n)                   Tk Built-In Commands                   listbox(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       listbox - Create and manipulate 'listbox' item list widgets
9

SYNOPSIS

11       listbox pathName ?options?
12

STANDARD OPTIONS

14       -background           -borderwidth         -cursor
15       -disabledforeground   -exportselection     -font
16       -foreground           -highlightbackground -highlightcolor
17       -highlightthickness   -justify             -relief
18       -selectbackground     -selectborderwidth   -selectforeground
19       -setgrid              -takefocus           -xscrollcommand
20       -yscrollcommand
21
22       See the options manual entry for details on the standard options.
23

WIDGET-SPECIFIC OPTIONS

25       Command-Line Name:-activestyle
26       Database Name:  activeStyle
27       Database Class: ActiveStyle
28
29              Specifies  the  style in which to draw the active element.  This
30              must be one of dotbox (show a focus ring around the active  ele‐
31              ment),  none (no special indication of active element) or under‐
32              line (underline the active element).  The default  is  underline
33              on Windows, and dotbox elsewhere.
34
35       Command-Line Name:-height
36       Database Name:  height
37       Database Class: Height
38
39              Specifies  the desired height for the window, in lines.  If zero
40              or less, then the desired height for the  window  is  made  just
41              large enough to hold all the elements in the listbox.
42
43       Command-Line Name:-listvariable
44       Database Name:  listVariable
45       Database Class: Variable
46
47              Specifies the name of a global variable.  The value of the vari‐
48              able is a list to be displayed inside the widget; if  the  vari‐
49              able  value  changes  then  the widget will automatically update
50              itself to reflect the new value.  Attempts to assign a  variable
51              with an invalid list value to -listvariable will cause an error.
52              Attempts to unset a variable in use as a -listvariable will fail
53              but will not generate an error.
54
55       Command-Line Name:-selectmode
56       Database Name:  selectMode
57       Database Class: SelectMode
58
59              Specifies  one of several styles for manipulating the selection.
60              The value of the option may be arbitrary, but the default  bind‐
61              ings  expect  it  to  be  either  single,  browse,  multiple, or
62              extended;  the default value is browse.
63
64       Command-Line Name:-state
65       Database Name:  state
66       Database Class: State
67
68              Specifies one of two states for the  listbox:   normal  or  dis‐
69              abled.   If  the  listbox  is  disabled  then  items  may not be
70              inserted or deleted, items are drawn in the  -disabledforeground
71              color, and selection cannot be modified and is not shown (though
72              selection information is retained).
73
74       Command-Line Name:-width
75       Database Name:  width
76       Database Class: Width
77
78              Specifies the desired width for the window  in  characters.   If
79              the  font  does  not  have a uniform width then the width of the
80              character “0” is used in translating  from  character  units  to
81              screen  units.   If zero or less, then the desired width for the
82              window is made just large enough to hold all the elements in the
83              listbox.
84______________________________________________________________________________
85

DESCRIPTION

87       The  listbox  command creates a new window (given by the pathName argu‐
88       ment)  and  makes  it  into  a  listbox  widget.   Additional  options,
89       described  above, may be specified on the command line or in the option
90       database to configure aspects of the listbox such as its colors,  font,
91       text,  and  relief.  The listbox command returns its pathName argument.
92       At the time this command is invoked, there  must  not  exist  a  window
93       named pathName, but pathName's parent must exist.
94
95       A  listbox  is  a widget that displays a list of strings, one per line.
96       When first created, a new listbox has no  elements.   Elements  may  be
97       added  or  deleted using widget commands described below.  In addition,
98       one or more elements may be selected as described below.  If a  listbox
99       is  exporting its selection (see -exportselection option), then it will
100       observe the standard X11 protocols for handling the selection.  Listbox
101       selections  are  available  as  type STRING; the value of the selection
102       will be the text of the selected elements, with newlines separating the
103       elements.
104
105       It is not necessary for all the elements to be displayed in the listbox
106       window at once;  commands described below may be  used  to  change  the
107       view in the window.  Listboxes allow scrolling in both directions using
108       the standard -xscrollcommand and -yscrollcommand  options.   They  also
109       support scanning, as described below.
110

INDICES

112       Many  of  the widget commands for listboxes take one or more indices as
113       arguments.  An index specifies a particular element of the listbox,  in
114       any of the following ways:
115
116       number      Specifies  the element as a numerical index, where 0 corre‐
117                   sponds to the first element in the listbox.
118
119       active      Indicates the element that has the location  cursor.   This
120                   element will be displayed as specified by -activestyle when
121                   the listbox has the keyboard focus,  and  it  is  specified
122                   with the activate widget command.
123
124       anchor      Indicates  the anchor point for the selection, which is set
125                   with the selection anchor widget command.
126
127       end         Indicates the end of the listbox.  For most  commands  this
128                   refers  to  the  last element in the listbox, but for a few
129                   commands such as index and insert it refers to the  element
130                   just after the last one.
131
132       @x,y        Indicates  the element that covers the point in the listbox
133                   window specified by x and y (in pixel coordinates).  If  no
134                   element covers that point, then the closest element to that
135                   point is used.
136
137       In the widget command descriptions below, arguments named index, first,
138       and last always contain text indices in one of the above forms.
139

WIDGET COMMAND

141       The  listbox  command creates a new Tcl command whose name is pathName.
142       This command may be used to invoke various operations  on  the  widget.
143       It has the following general form:
144              pathName option ?arg arg ...?
145       Option  and  the args determine the exact behavior of the command.  The
146       following commands are possible for listbox widgets:
147
148       pathName activate index
149              Sets the active element to the one indicated by index.  If index
150              is outside the range of elements in the listbox then the closest
151              element is activated.  The active element is drawn as  specified
152              by  -activestyle  when  the  widget has the input focus, and its
153              index may be retrieved with the index active.
154
155       pathName bbox index
156              Returns a list of four numbers describing the  bounding  box  of
157              the  text in the element given by index.  The first two elements
158              of the list give the x and y coordinates of the upper-left  cor‐
159              ner  of the screen area covered by the text (specified in pixels
160              relative to the widget) and the last two elements give the width
161              and  height  of  the area, in pixels.  If no part of the element
162              given by index is visible on the screen, or if index refers to a
163              non-existent  element,  then  the result is an empty string;  if
164              the element is partially visible, the result gives the full area
165              of the element, including any parts that are not visible.
166
167       pathName cget option
168              Returns  the  current value of the configuration option given by
169              option.  Option may have any of the values accepted by the list‐
170              box command.
171
172       pathName configure ?option? ?value option value ...?
173              Query  or modify the configuration options of the widget.  If no
174              option is specified, returns a list describing all of the avail‐
175              able  options for pathName (see Tk_ConfigureInfo for information
176              on the format of this list).  If option  is  specified  with  no
177              value,  then the command returns a list describing the one named
178              option (this list will be identical to the corresponding sublist
179              of  the  value  returned  if no option is specified).  If one or
180              more option-value pairs are specified, then the command modifies
181              the  given widget option(s) to have the given value(s);  in this
182              case the command returns an empty string.  Option may  have  any
183              of the values accepted by the listbox command.
184
185       pathName curselection
186              Returns  a  list  containing the numerical indices of all of the
187              elements in the listbox that are currently selected.   If  there
188              are  no elements selected in the listbox then an empty string is
189              returned.
190
191       pathName delete first ?last?
192              Deletes one or more elements of the listbox.  First and last are
193              indices  specifying  the first and last elements in the range to
194              delete.  If last is not specified it defaults to first,  i.e.  a
195              single element is deleted.
196
197       pathName get first ?last?
198              If  last is omitted, returns the contents of the listbox element
199              indicated by first, or an empty string if first refers to a non-
200              existent  element.   If last is specified, the command returns a
201              list whose elements are all  of  the  listbox  elements  between
202              first  and last, inclusive.  Both first and last may have any of
203              the standard forms for indices.
204
205       pathName index index
206              Returns the integer index value that corresponds to  index.   If
207              index  is  end the return value is a count of the number of ele‐
208              ments in the listbox (not the index of the last element).
209
210       pathName insert index ?element element ...?
211              Inserts zero or more new elements in the list  just  before  the
212              element  given  by index.  If index is specified as end then the
213              new elements are added to the end of the list.  Returns an empty
214              string.
215
216       pathName itemcget index option
217              Returns the current value of the item configuration option given
218              by option. Option may have any of the  values  accepted  by  the
219              itemconfigure command.
220
221       pathName itemconfigure index ?option? ?value? ?option value ...?
222              Query  or  modify  the  configuration  options of an item in the
223              listbox.  If no option is specified, returns a  list  describing
224              all  of the available options for the item (see Tk_ConfigureInfo
225              for information on the format of this list).  If option is spec‐
226              ified  with no value, then the command returns a list describing
227              the one named option (this list will be identical to the  corre‐
228              sponding  sublist  of  the value returned if no option is speci‐
229              fied).  If one or more option-value pairs  are  specified,  then
230              the  command  modifies  the  given  widget option(s) to have the
231              given value(s);  in this  case  the  command  returns  an  empty
232              string. The following options are currently supported for items:
233
234              -background color
235                     Color specifies the background color to use when display‐
236                     ing the item. It may have any of the  forms  accepted  by
237                     Tk_GetColor.
238
239              -foreground color
240                     Color specifies the foreground color to use when display‐
241                     ing the item. It may have any of the  forms  accepted  by
242                     Tk_GetColor.
243
244              -selectbackground color
245                     color specifies the background color to use when display‐
246                     ing the item while it is selected. It may have any of the
247                     forms accepted by Tk_GetColor.
248
249              -selectforeground color
250                     color specifies the foreground color to use when display‐
251                     ing the item while it is selected. It may have any of the
252                     forms accepted by Tk_GetColor.
253
254       pathName nearest y
255              Given  a  y-coordinate  within  the listbox window, this command
256              returns the index of the (visible) listbox  element  nearest  to
257              that y-coordinate.
258
259       pathName scan option args
260              This command is used to implement scanning on listboxes.  It has
261              two forms, depending on option:
262
263              pathName scan mark x y
264                     Records x and y and the current view in the listbox  win‐
265                     dow;   used  in  conjunction  with later scan dragto com‐
266                     mands.  Typically this command is associated with a mouse
267                     button press in the widget.  It returns an empty string.
268
269              pathName scan dragto x y.
270                     This  command computes the difference between its x and y
271                     arguments and the x and y arguments to the last scan mark
272                     command  for  the widget.  It then adjusts the view by 10
273                     times the difference in  coordinates.   This  command  is
274                     typically associated with mouse motion events in the wid‐
275                     get, to produce the effect of dragging the list  at  high
276                     speed  through  the window.  The return value is an empty
277                     string.
278
279       pathName see index
280              Adjust the view in the listbox so  that  the  element  given  by
281              index  is  visible.   If the element is already visible then the
282              command has no effect; if the element is near one  edge  of  the
283              window  then  the listbox scrolls to bring the element into view
284              at the edge;  otherwise the listbox scrolls to center  the  ele‐
285              ment.
286
287       pathName selection option arg
288              This  command  is used to adjust the selection within a listbox.
289              It has several forms, depending on option:
290
291              pathName selection anchor index
292                     Sets the selection anchor to the element given by  index.
293                     If index refers to a non-existent element, then the clos‐
294                     est element is used.  The selection anchor is the end  of
295                     the  selection  that is fixed while dragging out a selec‐
296                     tion with the mouse.  The index anchor  may  be  used  to
297                     refer to the anchor element.
298
299              pathName selection clear first ?last?
300                     If any of the elements between first and last (inclusive)
301                     are selected, they are deselected.  The  selection  state
302                     is not changed for elements outside this range.
303
304              pathName selection includes index
305                     Returns  1 if the element indicated by index is currently
306                     selected, 0 if it is not.
307
308              pathName selection set first ?last?
309                     Selects all of the elements in the  range  between  first
310                     and  last,  inclusive,  without  affecting  the selection
311                     state of elements outside that range.
312
313       pathName size
314              Returns a decimal string indicating the total number of elements
315              in the listbox.
316
317       pathName xview ?args
318              This command is used to query and change the horizontal position
319              of the information in the widget's window.  It can take  any  of
320              the following forms:
321
322              pathName xview
323                     Returns  a list containing two elements.  Each element is
324                     a real fraction between 0 and 1;  together they  describe
325                     the  horizontal  span that is visible in the window.  For
326                     example, if the first element is .2 and the  second  ele‐
327                     ment  is  .6,  20% of the listbox's text is off-screen to
328                     the left, the middle 40% is visible in  the  window,  and
329                     40%  of  the  text is off-screen to the right.  These are
330                     the same values passed to scrollbars via the -xscrollcom‐
331                     mand option.
332
333              pathName xview index
334                     Adjusts  the  view  in  the  window so that the character
335                     position given by index is displayed at the left edge  of
336                     the window.  Character positions are defined by the width
337                     of the character 0.
338
339              pathName xview moveto fraction
340                     Adjusts the view in the window so that  fraction  of  the
341                     total  width  of  the  listbox  text is off-screen to the
342                     left.  fraction must be a fraction between 0 and 1.
343
344              pathName xview scroll number what
345                     This command shifts the view in the window left or  right
346                     according to number and what.  Number must be an integer.
347                     What must be either units or pages or an abbreviation  of
348                     one of these.  If what is units, the view adjusts left or
349                     right by number character units (the width of the 0 char‐
350                     acter)  on  the  display;   if  it is pages then the view
351                     adjusts by number screenfuls.  If number is negative then
352                     characters  farther to the left become visible;  if it is
353                     positive then characters farther to the right become vis‐
354                     ible.
355
356       pathName yview ?args?
357              This  command  is used to query and change the vertical position
358              of the text in the widget's window.  It can take any of the fol‐
359              lowing forms:
360
361              pathName yview
362                     Returns a list containing two elements, both of which are
363                     real fractions between 0 and 1.  The first element  gives
364                     the  position  of  the  listbox element at the top of the
365                     window, relative to the listbox as a whole (0.5 means  it
366                     is halfway through the listbox, for example).  The second
367                     element gives the position of the  listbox  element  just
368                     after the last one in the window, relative to the listbox
369                     as a whole.  These are the same values passed to  scroll‐
370                     bars via the -yscrollcommand option.
371
372              pathName yview index
373                     Adjusts  the view in the window so that the element given
374                     by index is displayed at the top of the window.
375
376              pathName yview moveto fraction
377                     Adjusts the view in the window so that the element  given
378                     by  fraction  appears at the top of the window.  Fraction
379                     is a fraction between 0 and 1;   0  indicates  the  first
380                     element  in  the listbox, 0.33 indicates the element one-
381                     third the way through the listbox, and so on.
382
383              pathName yview scroll number what
384                     This command adjusts the view in the window  up  or  down
385                     according to number and what.  Number must be an integer.
386                     What must be either units or pages.  If  what  is  units,
387                     the  view  adjusts  up or down by number lines;  if it is
388                     pages then the view adjusts  by  number  screenfuls.   If
389                     number  is negative then earlier elements become visible;
390                     if it is positive then later elements become visible.
391

DEFAULT BINDINGS

393       Tk automatically creates class bindings for listboxes  that  give  them
394       Motif-like  behavior.   Much of the behavior of a listbox is determined
395       by its -selectmode option, which selects one of four  ways  of  dealing
396       with the selection.
397
398       If  the  selection mode is single or browse, at most one element can be
399       selected in the listbox at once.  In both modes, clicking button  1  on
400       an element selects it and deselects any other selected item.  In browse
401       mode it is also possible to drag the selection with button 1.  On  but‐
402       ton 1, the listbox will also take focus if it has a normal state.
403
404       If  the  selection mode is multiple or extended, any number of elements
405       may be selected at once, including discontiguous ranges.   In  multiple
406       mode, clicking button 1 on an element toggles its selection state with‐
407       out affecting any other elements.  In extended mode, pressing button  1
408       on  an  element  selects  it,  deselects  everything else, and sets the
409       anchor to the element under the mouse;  dragging the mouse with  button
410       1  down  extends  the selection to include all the elements between the
411       anchor and the element under the mouse, inclusive.
412
413       Most people will probably want to use browse mode for single selections
414       and extended mode for multiple selections; the other modes appear to be
415       useful only in special situations.
416
417       Any time the set of selected item(s) in the listbox is updated  by  the
418       user through the keyboard or mouse, the virtual event <<ListboxSelect>>
419       will be generated. This  virtual  event  will  not  be  generated  when
420       adjusting  the  selection  with  the pathName selection  command. It is
421       easiest to bind to this event to be made aware of any user  changes  to
422       listbox selection.
423
424       In addition to the above behavior, the following additional behavior is
425       defined by the default bindings:
426
427       [1]    In extended mode, the selected range can be adjusted by pressing
428              button  1  with the Shift key down:  this modifies the selection
429              to consist of the elements between the anchor  and  the  element
430              under  the  mouse,  inclusive.   The un-anchored end of this new
431              selection can also be dragged with the button down.
432
433       [2]    In extended mode, pressing button 1 with the  Control  key  down
434              starts  a  toggle  operation:  the  anchor is set to the element
435              under the mouse, and  its  selection  state  is  reversed.   The
436              selection  state of other elements is not changed.  If the mouse
437              is dragged with button 1 down, then the selection state  of  all
438              elements  between  the anchor and the element under the mouse is
439              set to match that of the anchor element;  the selection state of
440              all  other elements remains what it was before the toggle opera‐
441              tion began.
442
443       [3]    If the mouse leaves the listbox window with button 1  down,  the
444              window  scrolls  away from the mouse, making information visible
445              that used to be off-screen  on  the  side  of  the  mouse.   The
446              scrolling  continues  until  the mouse re-enters the window, the
447              button is released, or the end of the listbox is reached.
448
449       [4]    Mouse button 2 may be used for scanning.  If it is  pressed  and
450              dragged  over  the  listbox, the contents of the listbox drag at
451              high speed in the direction the mouse moves.
452
453       [5]    If the Up or Down key is pressed, the  location  cursor  (active
454              element) moves up or down one element.  If the selection mode is
455              browse or extended then the new active element is also  selected
456              and all other elements are deselected.  In extended mode the new
457              active element becomes the selection anchor.
458
459       [6]    In extended mode, Shift-Up and Shift-Down move the location cur‐
460              sor  (active element) up or down one element and also extend the
461              selection to that element in a fashion similar to dragging  with
462              mouse button 1.
463
464       [7]    The  Left  and Right keys scroll the listbox view left and right
465              by the width of the character 0.  Control-Left and Control-Right
466              scroll  the listbox view left and right by the width of the win‐
467              dow.  Control-Prior and Control-Next also scroll left and  right
468              by the width of the window.
469
470       [8]    The  Prior  and Next keys scroll the listbox view up and down by
471              one page (the height of the window).
472
473       [9]    The Home and End keys scroll the  listbox  horizontally  to  the
474              left and right edges, respectively.
475
476       [10]   Control-Home  sets  the  location cursor to the first element in
477              the listbox, selects that element, and deselects everything else
478              in the listbox.
479
480       [11]   Control-End  sets the location cursor to the last element in the
481              listbox, selects that element, and deselects everything else  in
482              the listbox.
483
484       [12]   In  extended  mode,  Control-Shift-Home extends the selection to
485              the first element in the listbox and  Control-Shift-End  extends
486              the selection to the last element.
487
488       [13]   In  multiple  mode, Control-Shift-Home moves the location cursor
489              to the first element in the listbox and Control-Shift-End  moves
490              the location cursor to the last element.
491
492       [14]   The  space and Select keys make a selection at the location cur‐
493              sor (active element) just as if mouse button 1 had been  pressed
494              over this element.
495
496       [15]   In  extended  mode,  Control-Shift-space and Shift-Select extend
497              the selection to the active element just as if button 1 had been
498              pressed with the Shift key down.
499
500       [16]   In  extended mode, the Escape key cancels the most recent selec‐
501              tion and restores all the elements  in  the  selected  range  to
502              their previous selection state.
503
504       [17]   Control-slash selects everything in the widget, except in single
505              and browse modes, in which case it selects  the  active  element
506              and deselects everything else.
507
508       [18]   Control-backslash  deselects everything in the widget, except in
509              browse mode where it has no effect.
510
511       [19]   The F16 key (labelled Copy on many Sun workstations)  or  Meta-w
512              copies the selection in the widget to the clipboard, if there is
513              a selection.
514
515       The behavior of listboxes can be changed by defining new  bindings  for
516       individual widgets or by redefining the class bindings.
517

SEE ALSO

519       ttk::treeview(n)
520

KEYWORDS

522       listbox, widget
523
524
525
526Tk                                    8.4                           listbox(n)
Impressum