FL/Fl_Choice.H

   1 //
   2 // "$Id: Fl_Choice.H 7981 2010-12-08 23:53:04Z greg.ercolano $"
   3 //
   4 // Choice header file for the Fast Light Tool Kit (FLTK).
   5 //
   6 // Copyright 1998-2010 by Bill Spitzak and others.
   7 //
   8 // This library is free software; you can redistribute it and/or
   9 // modify it under the terms of the GNU Library General Public
  10 // License as published by the Free Software Foundation; either
  11 // version 2 of the License, or (at your option) any later version.
  12 //
  13 // This library is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 // Library General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU Library General Public
  19 // License along with this library; if not, write to the Free Software
  20 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  21 // USA.
  22 //
  23 // Please report all bugs and problems on the following page:
  24 //
  25 //     http://www.fltk.org/str.php
  26 //
  27
  28 /* \file
  29    Fl_Choice widget . */
  30
  31 #ifndef Fl_Choice_H
  32 #define Fl_Choice_H
  33
  34 #include "Fl_Menu_.H"
  35
  36 /**
  37   \class Fl_Choice
  38   \brief A button that is used to pop up a menu.
  39
  40   This is a button that, when pushed, pops up a menu (or hierarchy of menus)
  41   defined by an array of Fl_Menu_Item objects.
  42   Motif calls this an OptionButton.
  43
  44   The only difference between this and a Fl_Menu_Button is that the name of
  45   the most recent chosen menu item is displayed inside the box, while the
  46   label is displayed outside the box. However, since the use of this is most
  47   often to control a single variable rather than do individual callbacks,
  48   some of the Fl_Menu_Button methods are redescribed here in those terms.
  49
  50   When the user picks an item off the menu the value() is set to that item
  51   and then the item's callback is done with the menu_button as the
  52   \c Fl_Widget* argument. If the item does not have a callback the
  53   menu_button's callback is done instead.
  54
  55   All three mouse buttons pop up the menu. The Forms behavior of the first
  56   two buttons to increment/decrement the choice is not implemented.  This
  57   could be added with a subclass, however.
  58
  59   The menu will also pop up in response to shortcuts indicated by putting
  60   a '\&' character in the label().  See Fl_Button::shortcut(int s) for a
  61   description of this.
  62
  63   Typing the shortcut() of any of the items will do exactly the same as when
  64   you pick the item with the mouse.  The '\&' character in item names are
  65   only looked at when the menu is popped up, however.
  66
  67   \image html choice.png
  68   \image latex choice.png  "Fl_Choice" width=4cm
  69   \todo Refactor the doxygen comments for Fl_Choice changed() documentation.
  70
  71   \li <tt>int Fl_Widget::changed() const</tt>
  72       This value is true the user picks a different value. <em>It is turned
  73       off by value() and just before doing a callback (the callback can turn
  74       it back on if desired).</em>
  75   \li <tt>void Fl_Widget::set_changed()</tt>
  76       This method sets the changed() flag.
  77   \li <tt>void Fl_Widget::clear_changed()</tt>
  78       This method clears the changed() flag.
  79   \li <tt>Fl_Boxtype Fl_Choice::down_box() const</tt>
  80       Gets the current down box, which is used when the menu is popped up.
  81       The default down box type is \c FL_DOWN_BOX.
  82   \li <tt>void Fl_Choice::down_box(Fl_Boxtype b)</tt>
  83       Sets the current down box type to \p b.
  84  */
  85 class FL_EXPORT Fl_Choice : public Fl_Menu_ {
  86 protected:
  87   void draw();
  88 public:
  89   int handle(int);
  90
  91   Fl_Choice(int X, int Y, int W, int H, const char *L = 0);
  92
  93   /**
  94     Gets the index of the last item chosen by the user.
  95     The index is zero initially.
  96    */
  97   int value() const {return Fl_Menu_::value();}
  98
  99   int value(int v);
 100
 101   int value(const Fl_Menu_Item* v);
 102 };
 103
 104 #endif
 105
 106 //
 107 // End of "$Id: Fl_Choice.H 7981 2010-12-08 23:53:04Z greg.ercolano $".
 108 //