Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
iwidgets::combobox(1)		[incr Widgets]		 iwidgets::combobox(1)

______________________________________________________________________________

NAME
       iwidgets::combobox - Create and manipulate combination box widgets

SYNOPSIS
       iwidgets::combobox pathName ?options?

INHERITANCE
       itk::Widget <- iwidgets::LabeledWidget <- iwidgets::Entryfield <- iwid-
       gets::Combobox

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

       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 sticky

       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 ar-
	      row button in a normal (not depressed) state. Acceptable	values
	      are raised, sunken, flat,	ridge, and groove.  Sunken is discour-
	      aged 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 al-
	      ways 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 ed-
	      itable by	the user. If true the user can add items to  the  com-
	      bobox by entering	text into the entry area and then pressing Re-
	      turn. 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 de-
	      fault 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  de-
	      fault 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  iwidgets::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 iwidgets::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 iwid-
	      gets::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	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 iwidgets::combobox command.

       pathName	delete component first ?last?
	      Delete  one or more elements from	a given	component, list	or en-
	      try.  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 se-
       lected respectively. Ctl-P and Ctl-N are	similarly mapped for emacs em-
       ulation.

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

EXAMPLE
	package	require	Iwidgets 4.0
	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:"	-selectioncom-
       mand 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							 iwidgets::combobox(1)

NAME | SYNOPSIS | INHERITANCE | STANDARD OPTIONS | ASSOCIATED OPTIONS | INHERITED OPTIONS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | METHODS | ASSOCIATED METHODS | WIDGET-SPECIFIC METHODS | COMPONENTS | DEFAULT BINDINGS | EXAMPLE | ORIGINAL AUTHOR | CURRENT MAINTAINER | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iwidgets_combobox&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help