ABCDEFGHIJKLMNOPQRSTUVWXYZ

listbox

listbox(n)                   Tk Built-In Commands                   listbox(n)



______________________________________________________________________________

NAME
       listbox - Create and manipulate listbox widgets

SYNOPSIS
       listbox pathName ?options?

STANDARD OPTIONS
       -background           -foreground          -relief-takefocus
       -borderwidth          -height              -listvar-selectbackground-width
       -cursor               -highlightbackground -selectborderwidth-xscrollcommand
       -exportselection      -highlightcolor      -selectforeground-yscrollcommand
       -font                 -highlightthickness  -setgrid

       See the options manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-height
       Database Name:  height
       Database Class: Height

              Specifies  the desired height for the window, in lines.  If zero
              or less, then the desired height for the  window  is  made  just
              large enough to hold all the elements in the listbox.

       Command-Line Name:-listvar
       Database Name:  listVariable
       Database Class: Variable

              Specifies  the name of a variable.  The value of the variable is
              a list to be displayed inside the widget;  if the variable value
              changes  then  the  widget  will  automatically update itself to
              reflect the new value.  Attempts to assign a bad list value to a
              variable  in  use as a listvar will cause an error.  Attempts to
              unset a variable in use as a listvar will fail but will not gen-
              erate an error.

       Command-Line Name:-selectmode
       Database Name:  selectMode
       Database Class: SelectMode

              Specifies  one of several styles for manipulating the selection.
              The value of the option may be arbitrary, but the default  bind-
              ings  expect  it  to  be  either  single,  browse,  multiple, or
              extended;  the default value is browse.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies the desired width for the window  in  characters.   If
              the  font  doesn't  have  a  uniform width then the width of the
              character ``0'' is used in translating from character  units  to
              screen  units.   If zero or less, then the desired width for the
              window is made just large enough to hold all the elements in the
              listbox.
_________________________________________________________________


DESCRIPTION
       The  listbox  command creates a new window (given by the pathName argu-
       ment)  and  makes  it  into  a  listbox  widget.   Additional  options,
       described  above, may be specified on the command line or in the option
       database to configure aspects of the listbox such as its colors,  font,
       text,  and  relief.  The listbox command returns its pathName argument.
       At the time this command is invoked, there  must  not  exist  a  window
       named pathName, but pathName's parent must exist.

       A  listbox  is  a widget that displays a list of strings, one per line.
       When first created, a new listbox has no  elements.   Elements  may  be
       added  or  deleted using widget commands described below.  In addition,
       one or more elements may be selected as described below.  If a  listbox
       is  exporting  its selection (see exportSelection option), then it will
       observe the standard X11 protocols for handling the selection.  Listbox
       selections  are  available  as  type STRING; the value of the selection
       will be the text of the selected elements, with newlines separating the
       elements.

       It is not necessary for all the elements to be displayed in the listbox
       window at once;  commands described below may be  used  to  change  the
       view in the window.  Listboxes allow scrolling in both directions using
       the standard xScrollCommand and yScrollCommand options.  They also sup-
       port scanning, as described below.


INDICES
       Many  of  the widget commands for listboxes take one or more indices as
       arguments.  An index specifies a particular element of the listbox,  in
       any of the following ways:

       number      Specifies  the element as a numerical index, where 0 corre-
                   sponds to the first element in the listbox.

       active      Indicates the element that has the location  cursor.   This
                   element  will be displayed with an underline when the list-
                   box has the keyboard focus, and it is  specified  with  the
                   activate widget command.

       anchor      Indicates  the anchor point for the selection, which is set
                   with the selection anchor widget command.

       end         Indicates the end of the listbox.  For most  commands  this |
                   refers  to  the  last element in the listbox, but for a few |
                   commands such as index and insert it refers to the  element |
                   just after the last one.

       @x,y        Indicates  the element that covers the point in the listbox
                   window specified by x and y (in pixel coordinates).  If  no
                   element covers that point, then the closest element to that
                   point is used.

       In the widget command descriptions below, arguments named index, first,
       and last always contain text indices in one of the above forms.


WIDGET COMMAND
       The  listbox  command creates a new Tcl command whose name is pathName.
       This command may be used to invoke various operations  on  the  widget.
       It has the following general form:
              pathName option ?arg arg ...?
       Option  and  the args determine the exact behavior of the command.  The
       following commands are possible for listbox widgets:

       pathName activate index
              Sets the active element to the one indicated by index.  If index |
              is outside the range of elements in the listbox then the closest |
              element is activated.  The  active  element  is  drawn  with  an
              underline when the widget has the input focus, and its index may
              be retrieved with the index active.

       pathName bbox index
              Returns a list of four numbers describing the  bounding  box  of
              the  text in the element given by index.  The first two elements
              of the list give the x and y coordinates of the upper-left  cor-
              ner  of the screen area covered by the text (specified in pixels
              relative to the widget) and the last two elements give the width
              and  height  of  the area, in pixels.  If no part of the element
              given by index is visible on the screen, or if index refers to a |
              non-existent  element,  then  the result is an empty string;  if
              the element is partially visible, the result gives the full area
              of the element, including any parts that are not visible.

       pathName cget option
              Returns  the  current value of the configuration option given by
              option.  Option may have any of the values accepted by the list-
              box command.

       pathName configure ?option? ?value option value ...?
              Query  or modify the configuration options of the widget.  If no
              option is specified, returns a list describing all of the avail-
              able  options for pathName (see Tk_ConfigureInfo for information
              on the format of this list).  If option  is  specified  with  no
              value,  then the command returns a list describing the one named
              option (this list will be identical to the corresponding sublist
              of  the  value  returned  if no option is specified).  If one or
              more option-value pairs are specified, then the command modifies
              the  given widget option(s) to have the given value(s);  in this
              case the command returns an empty string.  Option may  have  any
              of the values accepted by the listbox command.

       pathName curselection
              Returns  a  list  containing the numerical indices of all of the
              elements in the listbox that are currently selected.   If  there
              are  no elements selected in the listbox then an empty string is
              returned.

       pathName delete first ?last?
              Deletes one or more elements of the listbox.  First and last are
              indices  specifying  the first and last elements in the range to
              delete.  If last isn't specified it defaults to  first,  i.e.  a
              single element is deleted.

       pathName get first ?last?
              If  last is omitted, returns the contents of the listbox element
              indicated by first, or an empty string if first refers to a non- |
              existent  element.   If last is specified, the command returns a
              list whose elements are all  of  the  listbox  elements  between
              first  and last, inclusive.  Both first and last may have any of
              the standard forms for indices.

       pathName index index
              Returns the integer index value that corresponds to  index.   If |
              index  is  end the return value is a count of the number of ele- |
              ments in the listbox (not the index of the last element).

       pathName insert index ?element element ...?
              Inserts zero or more new elements in the list  just  before  the
              element  given  by index.  If index is specified as end then the
              new elements are added to the end of the list.  Returns an empty
              string.

       pathName itemcget index option
              Returns the current value of the item configuration option given
              by option. Option may have any of the  values  accepted  by  the
              listbox itemconfigure command.

       pathName itemconfigure index ?option? ?value? ?option value ...?
              Query  or  modify  the  configuration  options of an item in the
              listbox.  If no option is specified, returns a  list  describing
              all  of the available options for the item (see Tk_ConfigureInfo
              for information on the format of this list).  If option is spec-
              ified  with no value, then the command returns a list describing
              the one named option (this list will be identical to the  corre-
              sponding  sublist  of  the value returned if no option is speci-
              fied).  If one or more option-value pairs  are  specified,  then
              the  command  modifies  the  given  widget option(s) to have the
              given value(s);  in this  case  the  command  returns  an  empty
              string. The following options are currently supported for items:

              -background color
                     Color specifies the background color to use when display-
                     ing  the  item.  It may have any of the forms accepted by
                     Tk_GetColor.

              -foreground color
                     Color specifies the foreground color to use when display-
                     ing  the  item.  It may have any of the forms accepted by
                     Tk_GetColor.

              -selectbackground color
                     color specifies the background color to use when display-
                     ing the item while it is selected. It may have any of the
                     forms accepted by Tk_GetColor.

              -selectforeground color
                     color specifies the foreground color to use when display-
                     ing the item while it is selected. It may have any of the
                     forms accepted by Tk_GetColor.

       pathName nearest y
              Given a y-coordinate within the  listbox  window,  this  command
              returns  the  index  of the (visible) listbox element nearest to
              that y-coordinate.

       pathName scan option args
              This command is used to implement scanning on listboxes.  It has
              two forms, depending on option:

              pathName scan mark x y
                     Records  x and y and the current view in the listbox win-
                     dow;  used in conjunction with  later  scan  dragto  com-
                     mands.  Typically this command is associated with a mouse
                     button press in the widget.  It returns an empty  string.

              pathName scan dragto x y.
                     This  command computes the difference between its x and y
                     arguments and the x and y arguments to the last scan mark
                     command  for  the widget.  It then adjusts the view by 10
                     times the difference in  coordinates.   This  command  is
                     typically associated with mouse motion events in the wid-
                     get, to produce the effect of dragging the list  at  high
                     speed  through  the window.  The return value is an empty
                     string.

       pathName see index
              Adjust the view in the listbox so  that  the  element  given  by
              index  is  visible.   If the element is already visible then the
              command has no effect; if the element is near one  edge  of  the
              window  then  the listbox scrolls to bring the element into view
              at the edge;  otherwise the listbox scrolls to center  the  ele-
              ment.

       pathName selection option arg
              This  command  is used to adjust the selection within a listbox.
              It has several forms, depending on option:

              pathName selection anchor index
                     Sets the selection anchor to the element given by  index. |
                     If index refers to a non-existent element, then the clos- |
                     est element is used.  The selection anchor is the end  of
                     the  selection  that is fixed while dragging out a selec-
                     tion with the mouse.  The index anchor  may  be  used  to
                     refer to the anchor element.

              pathName selection clear first ?last?
                     If any of the elements between first and last (inclusive)
                     are selected, they are deselected.  The  selection  state
                     is not changed for elements outside this range.

              pathName selection includes index
                     Returns  1 if the element indicated by index is currently
                     selected, 0 if it isn't.

              pathName selection set first ?last?
                     Selects all of the elements in the  range  between  first
                     and  last,  inclusive,  without  affecting  the selection
                     state of elements outside that range.

       pathName size
              Returns a decimal string indicating the total number of elements
              in the listbox.

       pathName xview args
              This command is used to query and change the horizontal position
              of the information in the widget's window.  It can take  any  of
              the following forms:

              pathName xview
                     Returns  a list containing two elements.  Each element is
                     a real fraction between 0 and 1;  together they  describe
                     the  horizontal  span that is visible in the window.  For
                     example, if the first element is .2 and the  second  ele-
                     ment  is  .6,  20% of the listbox's text is off-screen to
                     the left, the middle 40% is visible in  the  window,  and
                     40%  of  the  text is off-screen to the right.  These are
                     the same values passed to scrollbars via the -xscrollcom-
                     mand option.

              pathName xview index
                     Adjusts  the  view  in  the  window so that the character
                     position given by index is displayed at the left edge  of
                     the window.  Character positions are defined by the width
                     of the character 0.

              pathName xview moveto fraction
                     Adjusts the view in the window so that  fraction  of  the
                     total  width  of  the  listbox  text is off-screen to the
                     left.  fraction must be a fraction between 0 and 1.

              pathName xview scroll number what
                     This command shifts the view in the window left or  right
                     according to number and what.  Number must be an integer.
                     What must be either units or pages or an abbreviation  of
                     one of these.  If what is units, the view adjusts left or
                     right by number character units (the width of the 0 char-
                     acter)  on  the  display;   if  it is pages then the view
                     adjusts by number screenfuls.  If number is negative then
                     characters  farther to the left become visible;  if it is
                     positive then characters farther to the right become vis-
                     ible.

       pathName yview ?args?
              This  command  is used to query and change the vertical position
              of the text in the widget's window.  It  can  take  any  of  the
              following forms:

              pathName yview
                     Returns a list containing two elements, both of which are
                     real fractions between 0 and 1.  The first element  gives
                     the  position  of  the  listbox element at the top of the
                     window, relative to the listbox as a whole (0.5 means  it
                     is halfway through the listbox, for example).  The second
                     element gives the position of the  listbox  element  just
                     after the last one in the window, relative to the listbox
                     as a whole.  These are the same values passed to  scroll-
                     bars via the -yscrollcommand option.

              pathName yview index
                     Adjusts  the view in the window so that the element given
                     by index is displayed at the top of the window.

              pathName yview moveto fraction
                     Adjusts the view in the window so that the element  given
                     by  fraction  appears at the top of the window.  Fraction
                     is a fraction between 0 and 1;   0  indicates  the  first
                     element  in  the listbox, 0.33 indicates the element one-
                     third the way through the listbox, and so on.

              pathName yview scroll number what
                     This command adjusts the view in the window  up  or  down
                     according to number and what.  Number must be an integer.
                     What must be either units or pages.  If  what  is  units,
                     the  view  adjusts  up or down by number lines;  if it is
                     pages then the view adjusts  by  number  screenfuls.   If
                     number  is negative then earlier elements become visible;
                     if it is positive then later elements become visible.


DEFAULT BINDINGS
       Tk automatically creates class bindings for listboxes  that  give  them
       Motif-like  behavior.   Much of the behavior of a listbox is determined
       by its selectMode option, which selects one of  four  ways  of  dealing
       with the selection.

       If  the  selection mode is single or browse, at most one element can be
       selected in the listbox at once.  In both modes, clicking button  1  on
       an element selects it and deselects any other selected item.  In browse
       mode it is also possible to drag the selection with button 1.

       If the selection mode is multiple or extended, any number  of  elements
       may  be  selected at once, including discontiguous ranges.  In multiple
       mode, clicking button 1 on an element toggles its selection state with-
       out  affecting any other elements.  In extended mode, pressing button 1
       on an element selects it,  deselects  everything  else,  and  sets  the
       anchor  to the element under the mouse;  dragging the mouse with button
       1 down extends the selection to include all the  elements  between  the
       anchor and the element under the mouse, inclusive.

       Most people will probably want to use browse mode for single selections
       and extended mode for multiple selections; the other modes appear to be
       useful only in special situations.

       Any  time  the  selection  changes  in  the  listbox, the virtual event
       <<ListboxSelect>> will be generated.  It is easiest  to  bind  to  this
       event to be made aware of any changes to listbox selection.

       In addition to the above behavior, the following additional behavior is
       defined by the default bindings:

       [1]    In extended mode, the selected range can be adjusted by pressing
              button  1  with the Shift key down:  this modifies the selection
              to consist of the elements between the anchor  and  the  element
              under  the  mouse,  inclusive.   The un-anchored end of this new
              selection can also be dragged with the button down.

       [2]    In extended mode, pressing button 1 with the  Control  key  down
              starts  a  toggle  operation:  the  anchor is set to the element
              under the mouse, and  its  selection  state  is  reversed.   The
              selection  state  of other elements isn't changed.  If the mouse
              is dragged with button 1 down, then the selection state  of  all
              elements  between  the anchor and the element under the mouse is
              set to match that of the anchor element;  the selection state of
              all  other elements remains what it was before the toggle opera-
              tion began.

       [3]    If the mouse leaves the listbox window with button 1  down,  the
              window  scrolls  away from the mouse, making information visible
              that used to be off-screen  on  the  side  of  the  mouse.   The
              scrolling  continues  until  the mouse re-enters the window, the
              button is released, or the end of the listbox is reached.

       [4]    Mouse button 2 may be used for scanning.  If it is  pressed  and
              dragged  over  the  listbox, the contents of the listbox drag at
              high speed in the direction the mouse moves.

       [5]    If the Up or Down key is pressed, the  location  cursor  (active
              element) moves up or down one element.  If the selection mode is
              browse or extended then the new active element is also  selected
              and all other elements are deselected.  In extended mode the new
              active element becomes the selection anchor.

       [6]    In extended mode, Shift-Up and Shift-Down move the location cur-
              sor  (active element) up or down one element and also extend the
              selection to that element in a fashion similar to dragging  with
              mouse button 1.

       [7]    The  Left  and Right keys scroll the listbox view left and right
              by the width of the character 0.  Control-Left and Control-Right
              scroll  the listbox view left and right by the width of the win-
              dow.  Control-Prior and Control-Next also scroll left and  right
              by the width of the window.

       [8]    The  Prior  and Next keys scroll the listbox view up and down by
              one page (the height of the window).

       [9]    The Home and End keys scroll the  listbox  horizontally  to  the
              left and right edges, respectively.

       [10]   Control-Home  sets  the location cursor to the the first element
              in the listbox, selects that element, and  deselects  everything
              else in the listbox.

       [11]   Control-End  sets the location cursor to the the last element in
              the listbox, selects that element, and deselects everything else
              in the listbox.

       [12]   In  extended  mode,  Control-Shift-Home extends the selection to
              the first element in the listbox and  Control-Shift-End  extends
              the selection to the last element.

       [13]   In  multiple  mode, Control-Shift-Home moves the location cursor
              to the first element in the listbox and Control-Shift-End  moves
              the location cursor to the last element.

       [14]   The  space and Select keys make a selection at the location cur-
              sor (active element) just as if mouse button 1 had been  pressed
              over this element.

       [15]   In  extended  mode,  Control-Shift-space and Shift-Select extend
              the selection to the active element just as if button 1 had been
              pressed with the Shift key down.

       [16]   In  extended mode, the Escape key cancels the most recent selec-
              tion and restores all the elements  in  the  selected  range  to
              their previous selection state.

       [17]   Control-slash selects everything in the widget, except in single
              and browse modes, in which case it selects  the  active  element
              and deselects everything else.

       [18]   Control-backslash  deselects everything in the widget, except in
              browse mode where it has no effect.

       [19]   The F16 key (labelled Copy on many Sun workstations)  or  Meta-w
              copies the selection in the widget to the clipboard, if there is
              a selection.


       The behavior of listboxes can be changed by defining new  bindings  for
       individual widgets or by redefining the class bindings.


KEYWORDS
       listbox, widget



Tk                                    8.0                           listbox(n)