# iwidgets2.2.0 User Commands - combobox

##

## NAME

         combobox - Create and manipulate combination box widgets

## SYNOPSIS

         combobox pathName ?options?

## INHERITANCE

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

## STANDARD OPTIONS

         background      borderWidth    cursor          exportSelection
         foreground      highlightColor highlightThicknessinsertBackground
         insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
         justify         relief         selectBackgroundselectBorderWidth
         selectForeground               textVariable    width

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

## ASSOCIATED OPTIONS

         hscrollmode     items          textBackground  textFont
         vscrollmode

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

         show            state

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

## 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:           autoClear
         Class:          AutoClear
         Command-Line Switch:           -autoclear

              Boolean value that specifies wheather or not  to  clear
              the entry field as items are added to the list given in
              any of the forms  acceptable  to  Tcl_GetBoolean.   The
              default is true.

         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  values  are  raised,  sunken,  flat,
              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:           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 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.  Given in any of the forms
              acceptable to Tcl_GetBoolean. The default is true.

         Name:           flipArrow
         Class:          FlipArrow
         Command-Line Switch:           -fliparrow

              Boolean describing whether or not the arrow  button  of
              dropdowns  should  be reversed (point up) when the list
              is popped up. Given in any of the forms  acceptable  to
              Tcl_GetBoolean. The default is false.

         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 100 pixels.

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

              Specifies the width in pixels between  the  entry  com-
              ponent  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 0.

         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 accept-
              able 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:           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 it's
         value  is then displayed in the entry field text area. Func-
         tionally  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 opera-
         tions 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. The following commands are possible for Combobox widg-
         ets:

## 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 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 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  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 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 component to
              the value of  the  selected  item.  See  the  "listbox"
              manual entry for more details on parameter options.

## COMPONENTS

         Name:           entry
         Class:          Entryfield

              Text  entry  area  where  the  current   selection   is
              displayed.  If  the  Combobox is editable, 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 press-
              ing  on the arrow button to the right of the entry com-
              ponent. For simple Comboboxes this component is  always
              visible just beneath the entry component.

## DEFAULT BINDINGS

         The Combobox generally has the same bindings as it's primary
         component  items  - the Scrolledlistbox and Entryfield. How-
         ever it also adds these:

         [1] Button-1 mouse press on the arrow key of a dropdown Com-
         bobox  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 Com-
         bobox  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 com-
         boboxes.

         [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 drop-
         down 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 \
                   -items {Jan Feb Mar Apr May June Jul Aug Sept Oct Nov Dec}

               #
               # Editable Dropdown Combobox
               #
               combobox .cb2 -labeltext "Operating System:" \
                  -items {Linux HP-UX SunOS Solaris Irix} -selectioncommand selectCmd

               #
               # Simple Combobox
               #
               combobox .cb3 -labeltext Fonts: -labelpos nw \
                 -dropdown false -listheight 220 -items [exec xlsfonts]

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

## AUTHOR

         John S. Sigler

## KEYWORDS

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