1mNAME0m
       listbox - Create and manipulate listbox widgets

1mSYNOPSIS0m
       1mlistbox 4m22mpathName24m ?4moptions24m?

1mSTANDARD OPTIONS0m
       1m-background           -foreground          -relief-takefocus0m
       1m-borderwidth          -height              -listvar-selectbackground-width0m
       1m-cursor               -highlightbackground -selectborderwidth-xscrollcommand0m
       1m-exportselection      -highlightcolor      -selectforeground-yscrollcommand0m
       1m-font                 -highlightthickness  -setgrid0m

       See the 1moptions 22mmanual entry for details on the standard options.

1mWIDGET-SPECIFIC OPTIONS0m
       Command-Line Name:1m-height0m
       Database Name:  1mheight0m
       Database Class: 1mHeight0m

              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:1m-listvar0m
       Database Name:  1mlistVariable0m
       Database Class: 1mVariable0m

              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:1m-selectmode0m
       Database Name:  1mselectMode0m
       Database Class: 1mSelectMode0m

              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  1msingle22m,  1mbrowse22m,  1mmultiple22m, or
              1mextended22m;  the default value is 1mbrowse22m.

       Command-Line Name:1m-width0m
       Database Name:  1mwidth0m
       Database Class: 1mWidth0m

              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.


1mDESCRIPTION0m
       The  1mlistbox  22mcommand creates a new window (given by the 4mpathName24m 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 1mlistbox 22mcommand returns its 4mpathName24m argument.
       At the time this command is invoked, there  must  not  exist  a  window
       named 4mpathName24m, but 4mpathName24m'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 1mexportSelection 22moption), then it will
       observe the standard X11 protocols for handling the selection.  Listbox
       selections  are  available  as  type 1mSTRING22m; 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 1mxScrollCommand 22mand 1myScrollCommand 22moptions.  They also sup-
       port scanning, as described below.


1mINDICES0m
       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:

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

       1mactive      22mIndicates 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
                   1mactivate 22mwidget command.

       1manchor      22mIndicates  the anchor point for the selection, which is set
                   with the 1mselection anchor 22mwidget command.

       1mend         22mIndicates the end of the listbox.  For most  commands  this
                   refers  to  the  last element in the listbox, but for a few
                   commands such as 1mindex 22mand 1minsert 22mit refers to the  element
                   just after the last one.

       1m@4m22mx24m1m,4m22my24m        Indicates  the element that covers the point in the listbox
                   window specified by 4mx24m and 4my24m (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 4mindex24m, 4mfirst24m,
       and 4mlast24m always contain text indices in one of the above forms.


1mWIDGET COMMAND0m
       The  1mlistbox  22mcommand creates a new Tcl command whose name is 4mpathName24m.
       This command may be used to invoke various operations  on  the  widget.
       It has the following general form:
              4mpathName24m 4moption24m ?4marg24m 4marg24m 4m...24m?
       4mOption24m  and  the 4marg24ms determine the exact behavior of the command.  The
       following commands are possible for listbox widgets:

       4mpathName24m 1mactivate 4m22mindex0m
              Sets the active element to the one indicated by 4mindex24m.  If 4mindex0m
              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 1mactive22m.

       4mpathName24m 1mbbox 4m22mindex0m
              Returns a list of four numbers describing the  bounding  box  of
              the  text in the element given by 4mindex24m.  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 4mindex24m is visible on the screen, or if 4mindex24m 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.

       4mpathName24m 1mcget 4m22moption0m
              Returns  the  current value of the configuration option given by
              4moption24m.  4mOption24m may have any of the values accepted by the 1mlist-0m
              1mbox 22mcommand.

       4mpathName24m 1mconfigure 22m?4moption24m? ?4mvalue24m 4moption24m 4mvalue24m 4m...24m?
              Query  or modify the configuration options of the widget.  If no
              4moption24m is specified, returns a list describing all of the avail-
              able  options for 4mpathName24m (see 1mTk_ConfigureInfo 22mfor information
              on the format of this list).  If 4moption24m  is  specified  with  no
              4mvalue24m,  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 4moption24m is specified).  If one or
              more 4moption-value24m 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.  4mOption24m may  have  any
              of the values accepted by the 1mlistbox 22mcommand.

       4mpathName24m 1mcurselection0m
              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.

       4mpathName24m 1mdelete 4m22mfirst24m ?4mlast24m?
              Deletes one or more elements of the listbox.  4mFirst24m and 4mlast24m are
              indices  specifying  the first and last elements in the range to
              delete.  If 4mlast24m isn't specified it defaults to  4mfirst24m,  i.e.  a
              single element is deleted.

       4mpathName24m 1mget 4m22mfirst24m ?4mlast24m?
              If  4mlast24m is omitted, returns the contents of the listbox element
              indicated by 4mfirst24m, or an empty string if 4mfirst24m refers to a non-
              existent  element.   If 4mlast24m is specified, the command returns a
              list whose elements are all  of  the  listbox  elements  between
              4mfirst24m  and 4mlast24m, inclusive.  Both 4mfirst24m and 4mlast24m may have any of
              the standard forms for indices.

       4mpathName24m 1mindex 4m22mindex0m
              Returns the integer index value that corresponds to  4mindex24m.   If
              4mindex24m  is  1mend 22mthe return value is a count of the number of ele-
              ments in the listbox (not the index of the last element).

       4mpathName24m 1minsert 4m22mindex24m ?4melement24m 4melement24m 4m...24m?
              Inserts zero or more new elements in the list  just  before  the
              element  given  by 4mindex24m.  If 4mindex24m is specified as 1mend 22mthen the
              new elements are added to the end of the list.  Returns an empty
              string.

       4mpathName24m 1mitemcget 4m22mindex24m 4moption0m
              Returns the current value of the item configuration option given
              by 4moption24m. 4mOption24m may have any of the  values  accepted  by  the
              1mlistbox itemconfigure 22mcommand.

       4mpathName24m 1mitemconfigure 4m22mindex24m ?4moption24m? ?4mvalue24m? ?4moption24m 4mvalue24m 4m...24m?
              Query  or  modify  the  configuration  options of an item in the
              listbox.  If no 4moption24m is specified, returns a  list  describing
              all  of the available options for the item (see 1mTk_ConfigureInfo0m
              for information on the format of this list).  If 4moption24m is spec-
              ified  with no 4mvalue24m, 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 4moption24m is speci-
              fied).  If one or more 4moption-value24m 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:

              1m-background 4m22mcolor0m
                     4mColor24m specifies the background color to use when display-
                     ing  the  item.  It may have any of the forms accepted by
                     1mTk_GetColor22m.

              1m-foreground 4m22mcolor0m
                     4mColor24m specifies the foreground color to use when display-
                     ing  the  item.  It may have any of the forms accepted by
                     1mTk_GetColor22m.

              1m-selectbackground 4m22mcolor0m
                     4mcolor24m specifies the background color to use when display-
                     ing the item while it is selected. It may have any of the
                     forms accepted by 1mTk_GetColor22m.

              1m-selectforeground 4m22mcolor0m
                     4mcolor24m specifies the foreground color to use when display-
                     ing the item while it is selected. It may have any of the
                     forms accepted by 1mTk_GetColor22m.

       4mpathName24m 1mnearest 4m22my0m
              Given a y-coordinate within the  listbox  window,  this  command
              returns  the  index  of the (visible) listbox element nearest to
              that y-coordinate.

       4mpathName24m 1mscan 4m22moption24m 4margs0m
              This command is used to implement scanning on listboxes.  It has
              two forms, depending on 4moption24m:

              4mpathName24m 1mscan mark 4m22mx24m 4my0m
                     Records  4mx24m and 4my24m and the current view in the listbox win-
                     dow;  used in conjunction with  later  1mscan  dragto  22mcom-
                     mands.  Typically this command is associated with a mouse
                     button press in the widget.  It returns an empty  string.

              4mpathName24m 1mscan dragto 4m22mx24m 4my24m.
                     This  command computes the difference between its 4mx24m and 4my0m
                     arguments and the 4mx24m and 4my24m arguments to the last 1mscan mark0m
                     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.

       4mpathName24m 1msee 4m22mindex0m
              Adjust the view in the listbox so  that  the  element  given  by
              4mindex24m  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.

       4mpathName24m 1mselection 4m22moption24m 4marg0m
              This  command  is used to adjust the selection within a listbox.
              It has several forms, depending on 4moption24m:

              4mpathName24m 1mselection anchor 4m22mindex0m
                     Sets the selection anchor to the element given by  4mindex24m.
                     If 4mindex24m 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 1manchor  22mmay  be  used  to
                     refer to the anchor element.

              4mpathName24m 1mselection clear 4m22mfirst24m ?4mlast24m?
                     If any of the elements between 4mfirst24m and 4mlast24m (inclusive)
                     are selected, they are deselected.  The  selection  state
                     is not changed for elements outside this range.

              4mpathName24m 1mselection includes 4m22mindex0m
                     Returns  1 if the element indicated by 4mindex24m is currently
                     selected, 0 if it isn't.

              4mpathName24m 1mselection set 4m22mfirst24m ?4mlast24m?
                     Selects all of the elements in the  range  between  4mfirst0m
                     and  4mlast24m,  inclusive,  without  affecting  the selection
                     state of elements outside that range.

       4mpathName24m 1msize0m
              Returns a decimal string indicating the total number of elements
              in the listbox.

       4mpathName24m 1mxview 4m22margs0m
              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:

              4mpathName24m 1mxview0m
                     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 1m-xscrollcom-0m
                     1mmand 22moption.

              4mpathName24m 1mxview 4m22mindex0m
                     Adjusts  the  view  in  the  window so that the character
                     position given by 4mindex24m is displayed at the left edge  of
                     the window.  Character positions are defined by the width
                     of the character 1m022m.

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

              4mpathName24m 1mxview scroll 4m22mnumber24m 4mwhat0m
                     This command shifts the view in the window left or  right
                     according to 4mnumber24m and 4mwhat24m.  4mNumber24m must be an integer.
                     4mWhat24m must be either 1munits 22mor 1mpages 22mor an abbreviation  of
                     one of these.  If 4mwhat24m is 1munits22m, the view adjusts left or
                     right by 4mnumber24m character units (the width of the 1m0 22mchar-
                     acter)  on  the  display;   if  it is 1mpages 22mthen the view
                     adjusts by 4mnumber24m screenfuls.  If 4mnumber24m is negative then
                     characters  farther to the left become visible;  if it is
                     positive then characters farther to the right become vis-
                     ible.

       4mpathName24m 1myview 4m22m?args24m?
              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 fol-
              lowing forms:

              4mpathName24m 1myview0m
                     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 1m-yscrollcommand 22moption.

              4mpathName24m 1myview 4m22mindex0m
                     Adjusts  the view in the window so that the element given
                     by 4mindex24m is displayed at the top of the window.

              4mpathName24m 1myview moveto 4m22mfraction0m
                     Adjusts the view in the window so that the element  given
                     by  4mfraction24m  appears at the top of the window.  4mFraction0m
                     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.

              4mpathName24m 1myview scroll 4m22mnumber24m 4mwhat0m
                     This command adjusts the view in the window  up  or  down
                     according to 4mnumber24m and 4mwhat24m.  4mNumber24m must be an integer.
                     4mWhat24m must be either 1munits 22mor 1mpages22m.  If  4mwhat24m  is  1munits22m,
                     the  view  adjusts  up or down by 4mnumber24m lines;  if it is
                     1mpages 22mthen the view adjusts  by  4mnumber24m  screenfuls.   If
                     4mnumber24m  is negative then earlier elements become visible;
                     if it is positive then later elements become visible.


1mDEFAULT BINDINGS0m
       Tk automatically creates class bindings for listboxes  that  give  them
       Motif-like  behavior.   Much of the behavior of a listbox is determined
       by its 1mselectMode 22moption, which selects one of  four  ways  of  dealing
       with the selection.

       If  the  selection mode is 1msingle 22mor 1mbrowse22m, 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 1mbrowse0m
       mode it is also possible to drag the selection with button 1.

       If the selection mode is 1mmultiple 22mor 1mextended22m, any number  of  elements
       may  be  selected at once, including discontiguous ranges.  In 1mmultiple0m
       mode, clicking button 1 on an element toggles its selection state with-
       out  affecting any other elements.  In 1mextended 22mmode, 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 1mbrowse 22mmode for single selections
       and 1mextended 22mmode 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
       1m<<ListboxSelect>> 22mwill 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 1mextended 22mmode, 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 1mextended 22mmode, 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
              1mbrowse 22mor 1mextended 22mthen the new active element is also  selected
              and all other elements are deselected.  In 1mextended 22mmode the new
              active element becomes the selection anchor.

       [6]    In 1mextended 22mmode, 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 1m022m.  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  1mextended  22mmode,  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  1mmultiple  22mmode, 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  1mextended  22mmode,  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  1mextended 22mmode, 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 1msingle0m
              and 1mbrowse 22mmodes, in which case it selects  the  active  element
              and deselects everything else.

       [18]   Control-backslash  deselects everything in the widget, except in
              1mbrowse 22mmode 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.


1mKEYWORDS0m
