ABCDEFGHIJKLMNOPQRSTUVWXYZ

combobox

combobox(1)                     [incr Widgets]                     combobox(1)



______________________________________________________________________________

NAME
       combobox - Create and manipulate combination box widgets

SYNOPSIS
       combobox pathName ?options?

INHERITANCE
       itk::Widget <- LabeledWidget <- Entryfield <- Combobox

STANDARD OPTIONS
       background      borderWidth    cursor          justify
       exportSelection foreground     highlightColor  highlightThickness
       relief          width          insertWidth     insertBackground
       insertOffTime   insertOnTime   insertWidth     insertBorderWidth
       selectForeground               selectBackground
       selectBorderWidth              textVariable

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

ASSOCIATED OPTIONS
       hscrollmode     textBackground textFont        vscrollmode

       See  the "scrolledlistbox" manual entry for details on the above inher-
       ited options.

       show

       See the "entry" manual entry for details on the above inherited option.

INHERITED OPTIONS
       childSitePos    command        fixed           focusCommand
       invalid         textBackground textFont        validate

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

       labelBitmap     labelFont      labelImage      labelMargin
       labelPos        labelText      labelVariable

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

WIDGET-SPECIFIC OPTIONS
       Name:           arrowRelief
       Class:          Relief
       Command-Line Switch:           -arrowrelief

              Specifies  the  relief  style  to  use for a dropdown Combobox's
              arrow button in a normal (not depressed) state. Acceptable  val-
              ues are raised, sunken, flat, ridge, and groove.  Sunken is dis-
              couraged as this is the relief  used  to  indicate  a  depressed
              state.  This  option  has  no  effect  on simple Comboboxes. The
              default is raised.

       Name:           completion
       Class:          Completion
       Command-Line Switch:           -completion

              Boolean given in any of the forms acceptable  to  Tcl_GetBoolean
              which  determines  whether  insertions  into  the  entry  field,
              whether from the keyboard or  programmatically  via  the  insert
              method, are automatically completed with the first matching item
              from the listbox.  The default is true.

       Name:           dropdown
       Class:          Dropdown
       Command-Line Switch:           -dropdown

              Boolean describing the Combobox layout style given in any of the
              forms  acceptable  to Tcl_GetBoolean. If true, the Combobox will
              be a dropdown style widget which displays an entry field and  an
              arrow  button which when activated will pop up a scrollable list
              of items. If false, a simple Combobox style will be  used  which
              has  an  entry  field  and a scrollable list beneath it which is
              always visible. Both styles allow  an  optional  label  for  the
              entry field area. The default is true.

       Name:           editable
       Class:          Editable
       Command-Line Switch:           -editable

              Boolean  describing  whether  or  not  the  text  entry  area is
              editable by the user. If true the user can add items to the com-
              bobox  by  entering  text  into the entry area and then pressing
              Return. If false, the list of items is non-editable and can only
              be  changed  by calling the insert or delete methods. (The value
              in the entry field can still be modified by selecting  from  the
              list.)   Given in any of the forms acceptable to Tcl_GetBoolean.
              The default is true.

       Name:           grab
       Class:          Grab
       Command-Line Switch:           -grab

              This option sets the grab scope for the appearance of the  list-
              box  in drop-down comboboxes.  It can be either global or local.
              The default is local.

       Name:           listHeight
       Class:          Height
       Command-Line Switch:           -listheight

              Height of the listbox specified in any of the  forms  acceptable
              to Tk_GetPixels.  The default is 150 pixels.

       Name:           margin
       Class:          Margin
       Command-Line Switch:           -margin

              Specifies  the  width  in pixels between the entry component and
              the arrow button for a dropdown Combobox given  in  any  of  the
              forms acceptable to Tk_GetPixels. This option has no effect on a
              simple Combobox. The default is 1.

       Name:           popupCursor
       Class:          Cursor
       Command-Line Switch:           -popupcursor

              Specifies the cursor to be used for  dropdown  style  listboxes.
              The  value may have any of the forms acceptable to Tk_GetCursor.
              The default is arrow.

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

              Specifies a Tcl command procedure which is called when  an  item
              in  the  listbox  area is selected. The item will be selected in
              the list, the listbox will be removed if it is a  dropdown  Com-
              bobox,  and  the  selected item's text will be inserted into the
              entry field before the -selectioncommand  proc  is  called.  The
              default is {}.

       Name:           state
       Class:          State
       Command-Line Switch:           -state

              Specifies  the overall state of the Combobox megawidget.  Can be
              either normal or disabled.  If the Combobox is disabled, no text
              can be entered into the entry field, no selection can be made in
              the listbox,  and  the  arrowBtn  component  is  disabled.   The
              default is normal.

       Name:           unique
       Class:          Unique
       Command-Line Switch:           -unique

              Boolean describing whether or not duplicate items are allowed in
              the combobox list. If true, then duplicates are not  allowed  to
              be inserted. If false, a duplicate entry causes selection of the
              item. Given in any of the forms  acceptable  to  Tcl_GetBoolean.
              The default is true.
______________________________________________________________________________


DESCRIPTION
       The  combobox  command  creates  an enhanced entry field widget with an
       optional associated label and  a  scrollable  list.  When  an  item  is
       selected in the list area of a Combobox, its value is then displayed in
       the entry field text area. Functionally similar to an  Optionmenu,  the
       Combobox adds (optional) list scrolling and (optional) item editing and
       inserting capabilities.

       There are two basic styles of Comboboxes (determined by  the  -dropdown
       option):  dropdown  and simple. The dropdown style adds an arrow button
       to the right of the entry field which when activated will pop  up  (and
       down)  the  scrolled  listbox beneath the entry field. The simple (non-
       dropdown) Combobox permanently displays the listbox beneath  the  entry
       field  and  has  no arrow button. Either style allows an optional entry
       field label.

METHODS
       The combobox 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 Combobox widgets:

ASSOCIATED METHODS
       icursor         scan

       See  the  "entry"  manual  entries  for details on the above associated
       methods.

       curselection    index          see             size
       xview           yview

       See the "listbox" manual entries for details on  the  above  associated
       methods.

       getcurselection justify        sort

       See the "scrolledlistbox" manual entries for details on the above asso-
       ciated 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 com-
              bobox command.

       pathName clear ?component?
              Clears the contents from one or both components. Valid component
              values  are  list,  or entry.  With no component specified, both
              are cleared.

       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 avail-
              able 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 corresponding sublist
              of the value returned if no option is  specified).   If  one  or
              more option-value pairs are specified, then the command modifies
              the given widget option(s) to have the given value(s);  in  this
              case  the  command returns an empty string.  Option may have any
              of the values accepted by the combobox command.

       pathName delete component first ?last?
              Delete one or more elements from  a  given  component,  list  or
              entry.  If a list item to be removed is currently selected (dis-
              played in the  entry  field  area),  the  entry  field  will  be
              cleared.

       pathName get ?index?
              With  no  arguments, returns the contents currently in the entry
              field area. With a single argument, returns the contents of  the
              listbox item at the indicated index.

       pathName insert component index element ?element element ...?
              Insert  one  or more new elements into the given component, list
              or entry, just before the element given by index.

       pathName selection option first ?last?
              Adjust the selection within the listbox  component  and  updates
              the  contents  of  the entry field component to the value of the
              selected item. See the "listbox" manual entry for  more  details
              on parameter options.

COMPONENTS
       Name:           entry
       Class:          Entry

              Text entry area where the current selection is displayed. If the
              Combobox is editable and its state is normal, the user can  edit
              the contents of this item.

       Name:           list
       Class:          Scrolledlistbox

              Scrollable  list  which  stores all the items which the user can
              select from. For dropdown Comboboxes, this component  is  hidden
              until the user pops it up by pressing on the arrow button to the
              right of the entry component. For simple Comboboxes this  compo-
              nent is always visible just beneath the entry component.

DEFAULT BINDINGS
       The  Combobox  generally has the same bindings as its primary component
       items - the Scrolledlistbox and Entryfield. However it also adds these:

       [1] Button-1 mouse press on the arrow key of a dropdown Combobox causes
       the list to be popped up. If the combobox is non-editable,  a  Button-1
       press on the entry field area will also pop up the list.

       [2]  Button-1  mouse  press  anywhere on the display removes a dropdown
       listbox which has been popped up, unless the keypress is  upon  one  of
       the  Combobox  scrollbars which scrolls the list. If it is pressed upon
       an item in the list area, that item will be selected before the list is
       removed.

       [3] Button-3 mouse press on the arrow key of a dropdown Combobox causes
       the next item to be selected. Shift-Button-3 causes the  previous  item
       to be selected.

       [4] Escape keypress removes a dropdown list which has been popped up.

       [5]  The  <space> and <Return> keystrokes select the current item. They
       also remove the popped up list for dropdown comboboxes.

       [6] Up and Down arrow keypresses from the entry field and arrow  button
       component  cause  the  previous  and  next  items  in the listbox to be
       selected respectively. Ctl-P and Ctl-N are similarly mapped  for  emacs
       emulation.

       [7]  Entry  field  and  arrow  button component Shift-Up and Shift-Down
       arrow keys pop up and down the listbox  of  a  dropdown  Combobox.  The
       arrow button component also maps <Return> and <space> similarly.


EXAMPLE
               proc selectCmd {} {
                  puts stdout "[.cb2 getcurselection]"
               }

               #
               # Non-editable Dropdown Combobox
               #
               combobox .cb1 -labeltext Month: \
                   -selectioncommand {puts "selected: [.cb1 getcurselection]"} \
                   -editable false -listheight 185 -popupcursor hand1
               .cb1 insert list end Jan Feb Mar Apr May June Jul Aug Sept Oct Nov Dec

               #
               # Editable Dropdown Combobox
               #
               combobox .cb2 -labeltext "Operating System:" -selectioncommand selectCmd
               .cb2 insert list end Linux HP-UX SunOS Solaris Irix
               .cb2 insert entry end L

               pack .cb1 -padx 10 -pady 10 -fill x
               pack .cb2 -padx 10 -pady 10 -fill x



ORIGINAL AUTHOR
       John S. Sigler

CURRENT MAINTAINER
       Mitch Gorman (logain@erols.com)

KEYWORDS
       combobox,  entryfield,  scrolledlistbox,  itk::Widget,  entry, listbox,
       widget, iwidgets



Tk                                                                 combobox(1)