


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


NAME
       listbox - Create and manipulate listbox widgets

SYNOPSIS
       (listbox                     widget-name                     ?options?)
       :background    :foreground    :relief   :takefocus
       :borderwidth   :height   :selectbackground   :width
       :cursor   :highlightbackground     :selectborderwidth  :xscrollcommand
       :exportselection    :highlightcolor     :selectforeground   :yscroll-
       command :font     :highlightthickness :setgrid

WIDGET-SPECIFIC OPTIONS
       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.   Speifies  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.  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 procedure creates a new window (given  by  the  widget-name
       argument)  and  makes  it  into  a listbox widget.  Additional options,
       described above, may be specified on  the  procedure  line  or  in  the
       option database to configure aspects of the listbox such as its colors,
       font, text, and relief.  The listbox procedure returns its  widget-name
       argument.   At the time this procedure is invoked, there must not exist
       a window named widget-name, but widget-name'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 procedures 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;  procedures described below may be used to change the
       view in the window.  Listboxes allow scrolling in both directions using
       the  standard xScrollProcedure and yScrollProcedure options.  They also
       support scanning, as described below.


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



STk                            3.1                              1





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


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

       anchor      Indicates the anchor point for the selection, which is  set
                   with the ``selection anchor'' widget procedure.

       end         Indicates  the end of the listbox.  For most procedure this
                   refers to the last element in the listbox, but  for  a  few
                   procedure 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  procedure  descriptions  below, arguments named index,
       first, and last always contain text indices in one of the above  forms.


WIDGET PROCEDURE
       The  listbox  procedure  creates a new STk procedure whose name is wid-
       get-name.  This procedure may be used to invoke various  operations  on
       the  widget.   It  has  the following general form: (widget-name option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       procedure.  The following procedures are possible for listbox widgets:

       (widget-name '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.

       (widget-name '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 list;  if  the
              element  is partially visible, the result gives the full area of
              the element, including any parts that are not visible.





STk                            3.1                              2





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


       (widget-name '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 procedure.

       (widget-name '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 widget-name (see Tk_ConfigureInfo for  informa-
              tion  on  the format of this list).  If option is specified with
              no value, then the procedure 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 procedure
              modifies the given widget option(s) to have the given  value(s);
              in  this  case  the procedure returns an empty list.  Option may
              have any of the values accepted by the listbox procedure.

       (widget-name '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 #f is returned.

       (widget-name 'delete first)

       (widget-name '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.

       (widget-name 'get first)

       (widget-name 'get first last)
              If  last is omitted, returns the contents of the listbox element
              indicated by first, or an empty list if first refers to  a  non-
              existent element.  If last is specified, the procedure 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.

       (widget-name '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).

       (widget-name '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
              list.

       (widget-name 'nearest y)
              Given  a  y-coordinate within the listbox window, this procedure



STk                            3.1                              3





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


              returns the index of the (visible) listbox  element  nearest  to
              that y-coordinate.

       (widget-name 'scan option args)
              This  procedure  is used to implement scanning on listboxes.  It
              has two forms, depending on option:

              (widget-name 'scan 'mark x y)
                     Records x and y and the current view in the listbox  win-
                     dow;   used  in conjunction with later scan dragto proce-
                     dures.  Typically this procedure  is  associated  with  a
                     mouse  button  press  in the widget.  It returns an empty
                     list.

              (widget-name 'scan 'dragto x y)
                     This procedure computes the difference between its x  and
                     y  arguments  and  the x and y arguments to the last scan
                     mark procedure for the widget.  It then adjusts the  view
                     by  10  times the difference in coordinates.  This proce-
                     dure 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 list.

       (widget-name '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
              procedure  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.

       (widget-name 'selection option arg)
              This procedure is used to adjust the selection within a listbox.
              It has several forms, depending on option:

              (widget-name '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.

              (widget-name 'selection 'clear first)

              (widget-name '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.

              (widget-name 'selection 'includes index)
                     Returns #t if the element indicated by index is currently
                     selected, #f if it isn't.



STk                            3.1                              4





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


              (widget-name 'selection 'set first)

              (widget-name '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.

       (widget-name 'size)
              Returns a decimal string indicating the total number of elements
              in the listbox.

       (widget-name 'xview args)
              This procedure is used to query and change the horizontal  posi-
              tion of the information in the widget's window.  It can take any
              of the following forms:

              (widget-name '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 :xscrollpro-
                     cedure option.

              (widget-name '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.

              (widget-name '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.

              (widget-name 'xview 'scroll number what)
                     This  procedure  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 abbre-
                     viation 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 visi-
                     ble;   if  it  is positive then characters farther to the
                     right become visible.

       (widget-name 'yview ?args?)
              This procedure 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:



STk                            3.1                              5





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


              (widget-name '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 :yscrollprocedure option.

              (widget-name 'yview index)
                     Adjusts the view in the window so that the element  given
                     by index is displayed at the top of the window.

              (widget-name '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.

              (widget-name 'yview 'scroll number what)
                     This  procedure 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



STk                            3.1                              6





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


       useful only in special situations.

       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.




STk                            3.1                              7





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


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


EXAMPLE
       Herafter is an example of a listbox connected to a scrollbar ;;  Create
       list  box  and  scrollbar (listbox   '.l :height 5             :yscroll
       (lambda l (apply .s 'set l))) (scrollbar '.s :command (lambda l  (apply
       .l 'yview l)))

       ;;  Set  some  elements  in  the listbox (.l 'insert 0 'one 'two 'three
       'four 'five 'six 'seven 'eight)

       ;; Pack elements (pack .l :side "left" :expand #t  :fill "both")  (pack



STk                            3.1                              8





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


       .s :side "right" :expand #f :fill "y")


SEE ALSO
       scrollbar




















































STk                            3.1                              9


