iwidgets2.2.0 User Commands - optionmenu






NAME

     optionmenu - Create and manipulate a option menu widget


SYNOPSIS

     optionmenu pathName ?options?


INHERITANCE

     itk::Widget <- Labeledwidget <- optionmenu


STANDARD OPTIONS

     activeBackground               activeBorderWidthactiveForegroundbackground
     borderWidth     cursor         disabledForegroundfont
     foreground      highlightColor highlightThicknessrelief

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


INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "LabeledWidget" manual  entry  for  details  on  the
     inherited options.


WIDGET-SPECIFIC OPTIONS

     Name:           clickTime
     Class:          ClickTime
     Command-Line Switch:           -clicktime

          Interval time, in msec, used to determine that a single
          mouse  click  has  occurred.  Used  to  post  menu on a
          "quick" mouse click.  Note:  changing  this  value  may
          cause  the  sigle-click functionality to not work prop-
          erly.  The default is 150 msec.

     Name:           command
     Class:          Command
     Command-Line Switch:           -command

          Specifies a Tcl command procedure to be evaluated  fol-
          lowing a  change in the current option menu selection.

     Name:           cyclicOn
     Class:          CyclicOn
     Command-Line Switch:           -cyclicon

          Turns on/off the 3rd mouse button capability. The value
          may  be  specified  in  any  of the forms acceptable to
          Tcl_GetBoolean.  This feature allows  the  right  mouse
          button  to  cycle  through  the popup menu list without
          poping it up. The right mouse button cycles through the
          menu in reverse order.  The default is true.

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

          Sepcifies the list of items  to  be  displayed  in  the
          menu.

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

          Specifies  the mouse cursor to be used  for  the  popup
          menu.  The value may have any of the  forms  acceptable
          to Tk_GetCursor.

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

          Specified one of two states for the optionmenu: normal,
          or  disabled.   If  the  optionmenu  is  disabled, then
          option menu selection is ignored.

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

          Specifies a fixed size for the menu button label in any
          of  the  forms acceptable to Tk_GetPixels.  If the text
          is too small to fit in the label, the text is  clipped.
          Note:  Normally,  when  a  new  list is created, or new
          items are added to an existing list,  the  menu  button
          label  is  resized  automatically.  Setting this option
          overrides that functionality.






DESCRIPTION

     The optionmenu command creates an option  menu  widget  with
     options  to manage it.  An option menu displays a frame con-
     taining a label and a button.  A pop-up menu will allow  for
     the value of the button to change.



METHODS

     The optionmenu 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 com-
     mand.

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

     number      Specifies  the  entry   numerically,   where   0
                 corresponds  to the top-most entry of the option
                 menu, 1 to the entry below it, and so on.

     end         Indicates the bottommost entry in the menu.   If
                 there  are  no  entries in the menu then zero is
                 returned.

     select      Returns the numerical  index  of  the  currently
                 selected option menu entry.  If no entries exist
                 in the menu, then -1 is returned.

     pattern     If the index doesn't satisfy one  of  the  above
                 forms  then  this  form  is  used.   Pattern  is
                 pattern-matched against the label of each  entry
                 in  the option menu, in order from the top down,
                 until a matching entry is found.  The  rules  of
                 Tcl_StringMatch are used.

     The following widget commands are  possible  for  optionmenu
     widgets:



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 optionmenu command.

     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 optionmenu command.

     pathName delete first ?last?
          Delete all of the option menu entries between first and
          last inclusive.  If last is omitted then it defaults to
          first.

     pathName disable index
          Disable the option menu entry specified by index. Disa-
          bling a menu item will prevent the user from being able
          to select this item from the menu.  This  only  effects
          the  state  of  the  item  in the menu, in other words,
          should the item be the  currently  selected  item,  the
          programmer  is  responsible for determining this condi-
          tion and taking appropriate action.

     pathName enable index
          Enable the option menu entry specified by index.   Ena-
          bling  a  menu item allows the user to select this item
          from the menu.

     pathName get
          Returns the currently selected option menu item.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index string ?string?
          Insert an item, or list of  items,  into  the  menu  at
          location index.

     pathName select index
          Select an item from the option menu to be displayed  as
          the currently selected item.

     pathName sort mode
          Sort the current menu in either ascending, or  descend-
          ing  order.   The  values increasing, or decreasing are
          also accepted.



COMPONENTS

     Name:           menuBtn
     Class:          Frame

          The menuBtn component is the option menu  button  which
          displays  the  current choice from the popup menu.  See
          the "frame" widget manual  entry  for  details  on  the
          menuBtn component item.

     Name:           menuLabel
     Class:          Label

          The menuLabel component is the label whose text is  the
          currently selected choice from the popup menu.  See the
          "label" widget manual entry for details on the  menuLa-
          bel component item.

     Name:           popupMenu
     Class:          Menu

          The popupMenu component is menu displayed  upon  selec-
          tion of the menu button.  The menu contains the choices
          for the option menu.   See  the  "menu"  widget  manual
          entry for details on the popupMenu component item.



EXAMPLE

           optionmenu .om -labelmargin 5 \
               -labelon true -labelpos w -labeltext "Operating System :" \
               -items {Unix VMS Linux OS/2 {Windows NT} DOS}

           .om insert end CPM {MS DOS} HP/UX
           .om sort ascending
           .om select Linux

           pack .om  -padx 10 -pady 10



ACKNOWLEDGEMENTS:

     Michael J. McLennan

          Borrowed some ideas (next & previous) from OptionButton
          class.

     Steven B. Jaggers

          Provided an initial prototype in [incr Tcl].

     Bret Schuhmacher

          Helped with popup menu functionality.


AUTHOR

     Alfredo Jahn


KEYWORDS

     optionmenu, widget