1listbox(n) Tk Built-In Commands listbox(n)
2______________________________________________________________________________
6
8 listbox - Create and manipulate 'listbox' item list widgets
9
11 listbox pathName ?options?
12
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 See the options manual entry for details on the standard options.
23
25 Command-Line Name:-activestyle
26 Database Name: activeStyle
27 Database Class: ActiveStyle
28 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 Command-Line Name:-height
36 Database Name: height
37 Database Class: Height
38 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 Command-Line Name:-listvariable
44 Database Name: listVariable
45 Database Class: Variable
46 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 Command-Line Name:-selectmode
56 Database Name: selectMode
57 Database Class: SelectMode
58 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 Command-Line Name:-state
65 Database Name: state
66 Database Class: State
67 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 Command-Line Name:-width
75 Database Name: width
76 Database Class: Width
77 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
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 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 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
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 number Specifies the element as a numerical index, where 0 corre‐
117 sponds to the first element in the listbox.
118 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 anchor Indicates the anchor point for the selection, which is set
125 with the selection anchor widget command.
126 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 @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 In the widget command descriptions below, arguments named index, first,
138 and last always contain text indices in one of the above forms.
139
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 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 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 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 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 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 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 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 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 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 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 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 -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 -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 -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 -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 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 pathName scan option args
260 This command is used to implement scanning on listboxes. It has
261 two forms, depending on option:
262 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 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 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 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 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 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 pathName selection includes index
305 Returns 1 if the element indicated by index is currently
306 selected, 0 if it is not.
307 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 pathName size
314 Returns a decimal string indicating the total number of elements
315 in the listbox.
316 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 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 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 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 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 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 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 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 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 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
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 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 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 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 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 In addition to the above behavior, the following additional behavior is
425 defined by the default bindings:
426 [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 [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 [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 [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 [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 [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 [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 [8] The Prior and Next keys scroll the listbox view up and down by
471 one page (the height of the window).
472 [9] The Home and End keys scroll the listbox horizontally to the
474 left and right edges, respectively.
475 [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 [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 [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 [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 [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 [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 [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 [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 [18] Control-backslash deselects everything in the widget, except in
509 browse mode where it has no effect.
510 [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 The behavior of listboxes can be changed by defining new bindings for
516 individual widgets or by redefining the class bindings.
517
519 ttk::treeview(n)
520
522 listbox, widget
523Tk 8.4 listbox(n)