# iwidgets2.2.0 User Commands - scrolledlistbox

##

## NAME

         scrolledlistbox - Create  and  manipulate  scrolled  listbox
         widgets

## SYNOPSIS

         scrolledlistbox pathName ?options?

## INHERITANCE

         itk::Widget <- Labeledwidget <- Scrolledlistbox

## STANDARD OPTIONS

         activeBackground               background      borderWidthcursor
         exportSelection foreground     highlightColor  highlightThickness
         relief          repeatDelay    repeatInterval  selectBackground
         selectBorderWidth              selectForeground

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

## ASSOCIATED OPTIONS

         selectMode

         See the "listbox" widget manual entry  for  details  on  the
         above associated options.

         activeRelief    elementBorderwidth             jumptroughColor

         See the "scrollbar" widget manual entry for details  on  the
         above associated options.

## INHERITED OPTIONS

         labeledBitmap   labelFont      labelImage      labelMargin
         labelPos        labelText      labelVariable

         See the "labeledwidget" class manual entry  for  details  on
         the inherited options.

## WIDGET-SPECIFIC OPTIONS

         Name:           dblClickCommand
         Class:          Command
         Command-Line Switch:           -dblclickcommand

              Specifies a Tcl command procedure which is called  when
              an  item is double clicked.  Typically this occurs when
              mouse button 1 is double clicked over an item.   Selec-
              tion policy does not matter.

         Name:           height
         Class:          Height
         Command-Line Switch:           -height
              Specifies the height of the scrolled  list  box  as  an
              entire  unit.  The value may be specified in any of the
              forms acceptable to Tk_GetPixels.  Any additional space
              needed  to display the other components such as labels,
              margins,  and  scrollbars  force  the  listbox  to   be
              compressed.   A value of zero along with the same value
              for the width causes the  value  given  for  the  visi-
              bleitems   option   to  be  applied  which  administers
              geometry  constraints  in  a  different  manner.    The
              default height is zero.

         Name:           hscrollMode
         Class:          ScrollMode
         Command-Line Switch:           -hscrollmode

              Specifies the the display mode to be used for the  hor-
              izontal scrollbar: static, dynamic, or none.  In static
              mode,  the  scroll  bar  is  displayed  at  all  times.
              Dynamic  mode  displays the scroll bar as required, and
              none disables the scroll bar display.  The  default  is
              static.

         Name:           items
         Class:          Items
         Command-Line Switch:           -items

              Specifies the contents of the listbox as a proper  list
              of elements.

         Name:           sbWidth
         Class:          Width
         Command-Line Switch:           -sbwidth

              Specifies the width of the  scrollbar  in  any  of  the
              forms acceptable to Tk_GetPixels.  The default width is
              15 pixels..

         Name:           scrollMargin
         Class:          Margin
         Command-Line Switch:           -scrollmargin

              Specifies  the  distance  between   the   listbox   and
              scrollbar   in   any   of   the   forms  acceptable  to
              Tk_GetPixels.  The default is 3 pixels.

         Name:           selectionCommand
         Class:          Command
         Command-Line Switch:           -selectioncommand

              Specifies a Tcl command procedure which is called  when
              an item is selected.  Selection policy does not matter.

         Name:           textBackground
         Class:          Background
         Command-Line Switch -textbackground

              Specifies the background color for the  listbox.   This
              allows  the  background  within  the listbox to be dif-
              ferent from the normal background color.

         Name:           textFont
         Class:          Font
         Command-Line Switch:           -textfont

              Specifies the font to be used for text in the  listbox.
              This  allows for the font associated with text internal
              to the scrolled listbox to be different than  the  font
              for labels.

         Name:           visibleitems
         Class:          VisibleItems
         Command-Line Switch:           -visibleitems

              Specifies the widthxheight in characters and lines  for
              the  listbox.   This option is only administered if the
              width and height options are both set to  zero,  other-
              wise they take precedence.  The default value is 20x10.
              With the visibleitems  option  engaged,  geometry  con-
              straints  are maintained only on the listbox.  The size
              of the other components such as  labels,  margins,  and
              scroll  bars,  are  additive and independent, effecting
              the overall size of the scrolled  list  box.   In  con-
              trast,  should  the  width  and height options have non
              zero values, they are applied to the scrolled list  box
              as  a  whole.  The listbox is compressed or expanded to
              maintain the geometry constraints.

         Name:           vscrollMode
         Class:          ScrollMode
         Command-Line Switch:           -vscrollmode

              Specifies the the display mode to be used for the vert-
              ical  scrollbar:  static,  dynamic, or none.  In static
              mode,  the  scroll  bar  is  displayed  at  all  times.
              Dynamic  mode  displays the scroll bar as required, and
              none disables the scroll bar display.  The  default  is
              static.

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

              Specifies the width of the  scrolled  list  box  as  an
              entire  unit.  The value may be specified in any of the
              forms acceptable to Tk_GetPixels.  Any additional space
              needed  to display the other components such as labels,
              margins,  and  scrollbars  force  the  listbox  to   be
              compressed.   A value of zero along with the same value
              for the height causes the value  given  for  the  visi-
              bleitems   option   to  be  applied  which  administers
              geometry  constraints  in  a  different  manner.    The
              default width is zero.

##

## DESCRIPTION

         The scrolledlistbox command creates a scrolled listbox  with
         additional   options   to  manage  horizontal  and  vertical
         scrollbars.   This  includes  options   to   control   which
         scrollbars  are displayed and the method, i.e. statically or
         dynamically.

## METHODS

         The scrolledlistbox command creates a new Tcl command  whose
         name  is pathName.  This command may be used to invoke vari-
         ous operations on the widget.  It has the following  general
         form:

              pathName option ?arg arg ...?

         Option and the args determine the exact behavior of the com-
         mand.

         Many of the widget commands for a  scrolledlistbox  take  as
         one  argument an indicator of which entry of the list box to
         operate on.  These indicators are called indexes and may  be
         specified in any of the following forms:

         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 cur-
                     sor.   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 com-
                     mands  this  means  just after the last element;
                     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.

         pattern     If the index doesn't satisfy one  of  the  above
                     forms  then  this  form  is  used.   Pattern  is
                     pattern-matched against the items  in  the  list
                     box,  in order from the top down, until a match-
                     ing   entry   is   found.     The    rules    of
                     Tcl_StringMatch are used.

         The following widget commands are possible for scrolledlist-
         box widgets:

## ASSOCIATED METHODS

         activate        bbox           curselection    delete
         get             index          insert          nearest
         scan            see            selection       size
         xview           yview

         See the "listbox" manual entry for details on the associated
         methods.

## WIDGET-SPECIFIC METHODS

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

         pathName clear
              Clears the listbox of all items.

         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  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  correspond-
              ing  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 scrolledlistbox command.

         pathName getcurselection
              Returns the contents of the listbox  element  indicated
              by the current selection indexes.  Short cut version of
              get and curselection command combination.

         pathName justify direction
              Justifies the list contents via teh scroll bars in  one
              of four directions:  left, right, top, or bottom.

         pathName selecteditemcount
              Returns the number of items currently selected  in  the
              list.

         pathName sort order
              Sort the current list in either ascending or descending
              order.  The  values  increasing and decreasing are also
              accepted.

## COMPONENTS

         Name:           listbox
         Class:          listbox

              The listbox component is the listbox widget.   See  the
              "listbox"  widget manual entry for details on the list-
              box component item.

         Name:           horizsb
         Class:          Scrollbar

              The horizsb component is  the  horizontal  scroll  bar.
              See  the "scrollbar" widget manual entry for details on
              the horizsb component item.

         Name:           vertsb
         Class:          Scrollbar

              The vertsb component is the vertical scroll  bar.   See
              the  "scrollbar" widget manual entry for details on the
              vertsb component item.

## EXAMPLE

              wm minsize . 0 0
              option add *textBackground white
              proc selCmd {} {
                  puts stdout "[.slb getcurselection]"
              }
              proc defCmd {} {
                  puts stdout "Double Click"
                  return [selCmd]
              }
              scrolledlistbox .slb -selection single \
                  -items {Hello {Out There} World} \
                  -vscrollmode static -hscrollmode dynamic -labeltext "List" \
                  -selectioncommand selCmd -dblclickcommand defCmd
              pack .slb -padx 10 -pady 10 -fill both -expand yes

## AUTHOR

         Mark L. Ulferts

## KEYWORDS

         scrolledlistbox, listbox, widget