


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


NAME
       listbox - Create and manipulate listbox widgets

SYNOPSIS
       listbox pathName ?options?

STANDARD OPTIONS
       background      font           relief          takeFocus
       borderWidth     height         selectBackgroundwidth
       cursor          highlightBackground            selectBorderWidthxScrollCommand
       exportSelection highlightColor selectForegroundyScrollCommand
       foreground      highlightThickness             setGrid

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

WIDGET-SPECIFIC OPTIONS
       Name:           height
       Class:          Height
       Command-Line Switch:-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.

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

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

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

              Specifies the desired width for the window in char-
              acters.  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 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



Tk                                                              1





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


       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.  Elements may be added or deleted using widget com-
       mands 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  corresponds  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 listbox 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  some
                   commands  this  means just after the last ele-
                   ment; for other commands  it  means  the  last
                   element.

       @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.



Tk                                                              2





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


       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.   The active element is drawn with an under-
              line 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 corner of the
              screen  area covered by the text (specified in pix-
              els relative to the widget) and the last  two  ele-
              ments  give  the  width  and height of the area, in
              pixels.  If no part of the element given  by  index
              is  visible  on  the  screen  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 listbox 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 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



Tk                                                              3





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


              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  cur-
              rently 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 ele-
              ment is deleted.

       pathName get first ?last?
              If last is omitted, returns  the  contents  of  the
              listbox  element  indicated  by  first.  If last is
              specified, the command returns a  list  whose  ele-
              ments 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  a  decimal string giving the integer index
              value that corresponds to index.

       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 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



Tk                                                              4





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


                     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 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 element.

       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.  The selection anchor is the
                     end of the selection  that  is  fixed  while
                     dragging  out  a  selection  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 des-
                     elected.  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  num-
              ber of elements in the listbox.

       pathName xview args
              This  command  is  used  to  query  and  change the



Tk                                                              5





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


              horizontal position of the information in the  wid-
              get'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  horizon-
                     tal span that is visible in the window.  For
                     example, if the first element is .2 and  the
                     second  element  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
                     -xscrollcommand option.

              pathName xview index
                     Adjusts the view in the window so  that  the
                     character  position  given  by index is dis-
                     played 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 frac-
                     tion  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 character) 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 visi-
                     ble.

       pathName yview ?args?
              This command is used to query and change the verti-
              cal 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



Tk                                                              6





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


                     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 val-
                     ues  passed  to scrollbars via the -yscroll-
                     command 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 ele-
                     ment in the listbox, 0.33 indicates the ele-
                     ment  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 num-
                     ber 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 des-
       elects 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 discontigu-
       ous ranges.  In multiple mode, clicking  button  1  on  an
       element  toggles its selection state without affecting any
       other elements.  In extended mode, pressing button 1 on an
       element  selects  it,  deselects everything else, and sets



Tk                                                              7





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


       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 sin-
       gle selections and extended mode for multiple  selections;
       the other modes appear to be useful only in special situa-
       tions.

       In addition to the above  behavior,  the  following  addi-
       tional 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 Con-
              trol 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
              operation 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 cur-
              sor  (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.




Tk                                                              8





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


       [6]    In extended mode, Shift-Up and Shift-Down move  the
              location  cursor  (active  element)  up or down one
              element and also extend the selection to that  ele-
              ment  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 window.
              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  horizon-
              tally 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 cursor (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  selection  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



Tk                                                              9





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


              else.

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

       [19]   The F16 key (labelled Copy  on  many  Sun  worksta-
              tions) 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
