NAME
       listbox - Create and manipulate listbox widgets

SYNOPSIS
       listbox pathName ?options?

STANDARD OPTIONS
       background      foreground     selectBackgroundxScrollCommand
       borderWidth     font           selectBorderWidthyScrollCommand
       cursor          geometry       selectForeground
       exportSelection relief         setGrid

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       None.


DESCRIPTION
       The listbox command creates a new  window  (given  by  the
       pathName  argument)  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 argu-
       ment.  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 ele-
       ments in its list.  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  han-
       dling  the selection;  listbox selections are available as
       type STRING, consisting of a Tcl list with one  entry  for
       each selected element.

       For large lists only a subset of the list elements will be
       displayed  in  the  listbox  window  at  once;    commands
       described below may be used to change the view in the win-
       dow.  Listboxes allow scrolling in both  directions  using
       the  standard  xScrollCommand  and yScrollCommand options.
       They also support scanning, as described below.


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 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 available options for path-
              Name (see Tk_ConfigureInfo for information  on  the
              format  of this list).  If option is specified with
              no value, then the command returns a list  describ-
              ing the one named option (this list will be identi-
              cal 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 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?
              Delete  one or more elements of the listbox.  First
              and last give the integer indices of the first  and
              last  elements in the range to be deleted.  If last
              isn't specified it defaults to first, i.e. a single
              element  is  deleted.  An index of 0 corresponds to
              the first element in the listbox.  Either first  or
              last  may  be  specified  as  end, in which case it
              refers to the last element of  the  listbox.   This
              command returns an empty string

       pathName get index
              Return  the  contents  of the listbox element indi-
              cated by index.  Index must be a non-negative inte-
              ger  (0  corresponds  to  the  first element in the
              listbox), or it may also be  specified  as  end  to
              indicate the last element in the listbox.

       pathName insert index ?element element ...?
              Insert  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 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 list-
              boxes.  It has two forms, depending on option:

              pathName scan mark x y
                     Records  x and y and the current view in the
                     listbox window;  used  in  conjunction  with
                     later  scan dragto commands.  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 argu-
                     ments 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 widget, to produce  the
                     effect  of  dragging  the list at high speed
                     through the window.  The return value is  an
                     empty string.

       pathName select option arg
              This command is used to adjust the selection within
              a listbox.  It  has  several  forms,  depending  on
              option.   In  all of the forms the index end refers
              to the last element in the listbox.

              pathName select adjust index
                     Locate the end of the selection  nearest  to
                     the  element given by index, and adjust that
                     end of the selection to  be  at  index  (i.e
                     including  but not going beyond index).  The
                     other end  of  the  selection  is  made  the
                     anchor  point for future select to commands.
                     If the  selection  isn't  currently  in  the
                     listbox,  then  this command is identical to
                     the select from widget command.  Returns  an
                     empty string.

              pathName select clear
                     If  the selection is in this listbox then it
                     is cleared so that  none  of  the  listbox's
                     elements are selected anymore.

              pathName select from index
                     Set  the  selection  to  consist  of element
                     index, and make index the anchor  point  for
                     future  select  to widget commands.  Returns
                     an empty string.
              pathName select to index
                     Set the selection to consist of the elements
                     from  the  anchor  point  to  element index,
                     inclusive.  The anchor point  is  determined
                     by  the  most  recent  select from or select
                     adjust  command  in  this  widget.   If  the
                     selection isn't in this widget, this command
                     is identical to  select  from.   Returns  an
                     empty string.

       pathName size
              Returns  a decimal string indicating the total num-
              ber of elements in the listbox.

       pathName xview index
              Adjust the view in the listbox  so  that  character
              position index is displayed at the left edge of the
              widget.  Returns an empty string.

       pathName yview index
              Adjust the view in  the  listbox  so  that  element
              index  is  displayed  at the top of the widget.  If
              index is specified as end  it  indicates  the  last
              element of the listbox.  Returns an empty string.


DEFAULT BINDINGS
       Tk automatically creates class bindings for listboxes that
       give them the following default behavior:

       [1]    When button 1 is pressed over a listbox,  the  ele-
              ment  underneath the mouse cursor is selected.  The
              mouse can be dragged to select a range of elements.

       [2]    The  ends of the selection can be adjusted by drag-
              ging with mouse button 1 while  the  shift  key  is
              down;   this  will  adjust the end of the selection
              that was nearest to the mouse cursor when button  1
              was pressed.

       [3]    The view in the listbox can be adjusted by dragging
              with mouse button 2.

       The behavior of listboxes can be changed by  defining  new
       bindings for individual widgets or by redefining the class
       bindings.       In      addition,      the       procedure
       tk_listboxSingleSelect  may  be  invoked to change listbox
       behavior so that only a single element may be selected  at
       once.


KEYWORDS
       listbox, widget
