[incr Widgets] - combobox manpage


       combobox - Create and manipulate combination box widgets


       combobox pathName ?options?


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


       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


       hscrollmode     textBackground textFont        vscrollmode

       See the "scrolledlistbox" manual entry for details on  the
       above inherited options.


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


       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.


       Name:           arrowRelief
       Class:          Relief
       Command-Line Switch:           -arrowrelief

              Specifies the relief style to use  for  a  dropdown
              ridge,  and  groove.  Sunken is discouraged 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 auto­
              matically 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 wid­
              get which displays an entry field and an arrow but­
              ton  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 scrol­
              lable 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 combobox 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

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

              This  option sets the grab scope for the appearance
              of the listbox in drop-down comboboxes.  It can  be

       Class:          Height
       Command-Line Switch:           -listheight

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

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

              Specifies  the  width  in  pixels between the entry
              component and the arrow button for a dropdown  Com­
              bobox  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  Combobox,  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 megaw­
              idget.  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

              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.


       The  combobox command creates an enhanced entry field wid­
       get with an optional associated  label  and  a  scrollable
       list.  When an item is selected in the list area of a Com­
       bobox, 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.


       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

              pathName option ?arg arg ...?

       Option  and  the  args determine the exact behavior of the
       command. The following commands are possible for  Combobox


       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
       pathName cget option
              Returns the  current  value  of  the  configuration
              option given by option.  Option may have any of the
              values accepted by the combobox 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 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
              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  (displayed  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 com­
              ponent,  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 compo­
              nent to the value of the  selected  item.  See  the
              "listbox"  manual entry for more details on parame­
              ter options.


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

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


       The  Combobox  generally has the same bindings as its pri­
       mary 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 key­
       press 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-But­
       ton-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

       [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
               proc selectCmd {} {
                  puts stdout "[.cb2 getcurselection]"

               # Non-editable Dropdown Combobox
               iwidgets::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
               iwidgets::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


       John S. Sigler


       Mitch Gorman (logain@erols.com)


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

Man(1) output converted with man2html