FL/Fl_Menu_Item.H

   1 //
   2 // "$Id: Fl_Menu_Item.H 7983 2010-12-09 00:04:06Z AlbrechtS $"
   3 //
   4 // Menu item 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 #ifndef Fl_Menu_Item_H
  29 #define Fl_Menu_Item_H
  30
  31 #  include "Fl_Widget.H"
  32 #  include "Fl_Image.H"
  33
  34 #  if defined(__APPLE__) && defined(check)
  35 #    undef check
  36 #  endif
  37
  38 enum { // values for flags:
  39   FL_MENU_INACTIVE = 1,         ///< Deactivate menu item (gray out)
  40   FL_MENU_TOGGLE= 2,            ///< Item is a checkbox toggle (shows checkbox for on/off state)
  41   FL_MENU_VALUE = 4,            ///< The on/off state for checkbox/radio buttons (if set, state is 'on')
  42   FL_MENU_RADIO = 8,            ///< Item is a radio button (one checkbox of many can be on)
  43   FL_MENU_INVISIBLE = 0x10,     ///< Item will not show up (shortcut will work)
  44   FL_SUBMENU_POINTER = 0x20,    ///< Indicates user_data() is a pointer to another menu array
  45   FL_SUBMENU = 0x40,            ///< This item is a submenu to other items
  46   FL_MENU_DIVIDER = 0x80,       ///< Creates divider line below this item. Also ends a group of radio buttons.
  47   FL_MENU_HORIZONTAL = 0x100    ///< ??? -- reserved
  48 };
  49
  50 extern FL_EXPORT Fl_Shortcut fl_old_shortcut(const char*);
  51
  52 class Fl_Menu_;
  53
  54 /**
  55   The Fl_Menu_Item structure defines a single menu item that
  56   is used by the Fl_Menu_ class.
  57   \code
  58   struct Fl_Menu_Item {
  59    const char*          text;     // label()
  60    ulong                shortcut_;
  61    Fl_Callback*         callback_;
  62    void*                user_data_;
  63    int                  flags;
  64    uchar                labeltype_;
  65    uchar                labelfont_;
  66    uchar                labelsize_;
  67    uchar                labelcolor_;
  68   };
  69
  70   enum { // values for flags:
  71    FL_MENU_INACTIVE     = 1,      // Deactivate menu item (gray out)
  72    FL_MENU_TOGGLE       = 2,      // Item is a checkbox toggle (shows checkbox for on/off state)
  73    FL_MENU_VALUE        = 4,      // The on/off state for checkbox/radio buttons (if set, state is 'on')
  74    FL_MENU_RADIO        = 8,      // Item is a radio button (one checkbox of many can be on)
  75    FL_MENU_INVISIBLE    = 0x10,   // Item will not show up (shortcut will work)
  76    FL_SUBMENU_POINTER   = 0x20,   // Indicates user_data() is a pointer to another menu array
  77    FL_SUBMENU           = 0x40,   // This item is a submenu to other items
  78    FL_MENU_DIVIDER      = 0x80,   // Creates divider line below this item. Also ends a group of radio buttons.
  79    FL_MENU_HORIZONTAL   = 0x100   // ??? -- reserved
  80   };
  81   \endcode
  82   Typically menu items are statically defined; for example:
  83   \code
  84   Fl_Menu_Item popup[] = {
  85    {"&alpha",   FL_ALT+'a', the_cb, (void*)1},
  86    {"&beta",    FL_ALT+'b', the_cb, (void*)2},
  87    {"gamma",    FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER},
  88    {"&strange",  0,   strange_cb},
  89    {"&charm",    0,   charm_cb},
  90    {"&truth",    0,   truth_cb},
  91    {"b&eauty",   0,   beauty_cb},
  92    {"sub&menu",  0,   0, 0, FL_SUBMENU},
  93    {"one"},
  94    {"two"},
  95    {"three"},
  96    {0},
  97    {"inactive", FL_ALT+'i', 0, 0, FL_MENU_INACTIVE|FL_MENU_DIVIDER},
  98    {"invisible",FL_ALT+'i', 0, 0, FL_MENU_INVISIBLE},
  99    {"check",    FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE},
 100    {"box",      FL_ALT+'i', 0, 0, FL_MENU_TOGGLE},
 101    {0}};
 102   \endcode
 103   produces:
 104
 105   \image html   menu.png
 106   \image latex  menu.png "menu" width=10cm
 107
 108   A submenu title is identified by the bit FL_SUBMENU in the
 109   flags field, and ends with a label() that is NULL.
 110   You can nest menus to any depth.  A pointer to the first item in the
 111   submenu can be treated as an Fl_Menu array itself.  It is also
 112   possible to make separate submenu arrays with FL_SUBMENU_POINTER flags.
 113
 114   You should use the method functions to access structure members and
 115   not access them directly to avoid compatibility problems with future
 116   releases of FLTK.
 117 */
 118 struct FL_EXPORT Fl_Menu_Item {
 119   const char *text;         ///< menu item text, returned by label()
 120   int shortcut_;            ///< menu item shortcut
 121   Fl_Callback *callback_;   ///< menu item callback
 122   void *user_data_;         ///< menu item user_data for the menu's callback
 123   int flags;                ///< menu item flags like FL_MENU_TOGGLE, FL_MENU_RADIO
 124   uchar labeltype_;         ///< how the menu item text looks like
 125   Fl_Font labelfont_;       ///< which font for this menu item text
 126   Fl_Fontsize labelsize_;   ///< size of menu item text
 127   Fl_Color labelcolor_;     ///< menu item text color
 128
 129   // advance N items, skipping submenus:
 130   const Fl_Menu_Item *next(int=1) const;
 131
 132   /**
 133     Advances a pointer by n items through a menu array, skipping
 134     the contents of submenus and invisible items. There are two calls so
 135     that you can advance through const and non-const data.
 136   */
 137   Fl_Menu_Item *next(int i=1) {
 138     return (Fl_Menu_Item*)(((const Fl_Menu_Item*)this)->next(i));}
 139
 140   /** Returns the first menu item, same as next(0). */
 141   const Fl_Menu_Item *first() const { return next(0); }
 142
 143   /** Returns the first menu item, same as next(0). */
 144   Fl_Menu_Item *first() { return next(0); }
 145
 146   // methods on menu items:
 147   /**
 148     Returns the title of the item.
 149     A NULL here indicates the end of the menu (or of a submenu).
 150     A '&' in the item will print an underscore under the next letter,
 151     and if the menu is popped up that letter will be a "shortcut" to pick
 152     that item.  To get a real '&' put two in a row.
 153   */
 154   const char* label() const {return text;}
 155
 156   /**    See const char* Fl_Menu_Item::label() const   */
 157   void label(const char* a) {text=a;}
 158
 159   /**    See const char* Fl_Menu_Item::label() const   */
 160   void label(Fl_Labeltype a,const char* b) {labeltype_ = a; text = b;}
 161
 162   /**
 163     Returns the menu item's labeltype.
 164     A labeltype identifies a routine that draws the label of the
 165     widget.  This can be used for special effects such as emboss, or to use
 166     the label() pointer as another form of data such as a bitmap.
 167     The value FL_NORMAL_LABEL prints the label as text.
 168   */
 169   Fl_Labeltype labeltype() const {return (Fl_Labeltype)labeltype_;}
 170
 171   /**
 172     Sets the menu item's labeltype.
 173     A labeltype identifies a routine that draws the label of the
 174     widget.  This can be used for special effects such as emboss, or to use
 175     the label() pointer as another form of data such as a bitmap.
 176     The value FL_NORMAL_LABEL prints the label as text.
 177   */
 178   void labeltype(Fl_Labeltype a) {labeltype_ = a;}
 179
 180   /**
 181     Gets the menu item's label color.
 182     This color is passed to the labeltype routine, and is typically the
 183     color of the label text.  This defaults to FL_BLACK.  If this
 184     color is not black fltk will \b not use overlay bitplanes to draw
 185     the menu - this is so that images put in the menu draw correctly.
 186   */
 187   Fl_Color labelcolor() const {return labelcolor_;}
 188
 189   /**
 190     Sets the menu item's label color.
 191     \see Fl_Color Fl_Menu_Item::labelcolor() const
 192   */
 193   void labelcolor(Fl_Color a) {labelcolor_ = a;}
 194   /**
 195     Gets the menu item's label font.
 196     Fonts are identified by small 8-bit indexes into a table. See the
 197     enumeration list for predefined fonts. The default value is a
 198     Helvetica font. The function Fl::set_font() can define new fonts.
 199   */
 200   Fl_Font labelfont() const {return labelfont_;}
 201
 202   /**
 203     Sets the menu item's label font.
 204     Fonts are identified by small 8-bit indexes into a table. See the
 205     enumeration list for predefined fonts. The default value is a
 206     Helvetica font.  The function Fl::set_font() can define new fonts.
 207   */
 208   void labelfont(Fl_Font a) {labelfont_ = a;}
 209
 210   /** Gets the label font pixel size/height. */
 211   Fl_Fontsize labelsize() const {return labelsize_;}
 212
 213   /** Sets the label font pixel size/height.*/
 214   void labelsize(Fl_Fontsize a) {labelsize_ = a;}
 215
 216   /**
 217     Returns the callback function that is set for the menu item.
 218     Each item has space for a callback function and an argument for that
 219     function. Due to back compatibility, the Fl_Menu_Item itself
 220     is not passed to the callback, instead you have to get it by calling
 221     ((Fl_Menu_*)w)->mvalue() where w is the widget argument.
 222   */
 223   Fl_Callback_p callback() const {return callback_;}
 224
 225   /**
 226     Sets the menu item's callback function and userdata() argument.
 227     \see Fl_Callback_p Fl_MenuItem::callback() const
 228   */
 229   void callback(Fl_Callback* c, void* p) {callback_=c; user_data_=p;}
 230
 231   /**
 232     Sets the menu item's callback function.
 233     This method does not set the userdata() argument.
 234     \see Fl_Callback_p Fl_MenuItem::callback() const
 235    */
 236   void callback(Fl_Callback* c) {callback_=c;}
 237
 238   /**
 239     Sets the menu item's callback function.
 240     This method does not set the userdata() argument.
 241     \see Fl_Callback_p Fl_MenuItem::callback() const
 242    */
 243   void callback(Fl_Callback0*c) {callback_=(Fl_Callback*)c;}
 244
 245   /**
 246     Sets the menu item's callback function and userdata() argument.
 247     This method does not set the userdata() argument.
 248     The argument \p is cast to void* and stored as the userdata()
 249     for the menu item's callback function.
 250     \see Fl_Callback_p Fl_MenuItem::callback() const
 251    */
 252   void callback(Fl_Callback1*c, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;}
 253
 254   /**
 255     Gets the user_data() argument that is sent to the callback function.
 256   */
 257   void* user_data() const {return user_data_;}
 258   /**
 259     Sets the user_data() argument that is sent to the callback function.
 260   */
 261   void user_data(void* v) {user_data_ = v;}
 262   /**
 263     Gets the user_data() argument that is sent to the callback function.
 264     For convenience you can also define the callback as taking a long
 265     argument.  This method casts the stored userdata() argument to long
 266     and returns it as a \e long value.
 267   */
 268   long argument() const {return (long)(fl_intptr_t)user_data_;}
 269   /**
 270     Sets the user_data() argument that is sent to the callback function.
 271     For convenience you can also define the callback as taking a long
 272     argument.  This method casts the given argument \p v to void*
 273     and stores it in the menu item's userdata() member.
 274     This may not be portable to some machines.
 275   */
 276   void argument(long v) {user_data_ = (void*)v;}
 277
 278   /** Gets what key combination shortcut will trigger the menu item. */
 279   int shortcut() const {return shortcut_;}
 280
 281   /**
 282     Sets exactly what key combination will trigger the menu item.  The
 283     value is a logical 'or' of a key and a set of shift flags, for instance
 284     FL_ALT+'a' or FL_ALT+FL_F+10 or just 'a'.  A value of
 285     zero disables the shortcut.
 286
 287     The key can be any value returned by Fl::event_key(), but will usually
 288     be an ASCII letter. Use a lower-case letter unless you require the shift
 289     key to be held down.
 290
 291     The shift flags can be any set of values accepted by Fl::event_state().
 292     If the bit is on that shift key must be pushed.  Meta, Alt, Ctrl,
 293     and Shift must be off if they are not in the shift flags (zero for the
 294     other bits indicates a "don't care" setting).
 295   */
 296   void shortcut(int s) {shortcut_ = s;}
 297   /**
 298     Returns true if either FL_SUBMENU or FL_SUBMENU_POINTER
 299     is on in the flags. FL_SUBMENU indicates an embedded submenu
 300     that goes from the next item through the next one with a NULL
 301     label(). FL_SUBMENU_POINTER indicates that user_data()
 302     is a pointer to another menu array.
 303   */
 304   int submenu() const {return flags&(FL_SUBMENU|FL_SUBMENU_POINTER);}
 305   /**
 306     Returns true if a checkbox will be drawn next to this item.
 307     This is true if FL_MENU_TOGGLE or FL_MENU_RADIO is set in the flags.
 308   */
 309   int checkbox() const {return flags&FL_MENU_TOGGLE;}
 310   /**
 311     Returns true if this item is a radio item.
 312     When a radio button is selected all "adjacent" radio buttons are
 313     turned off.  A set of radio items is delimited by an item that has
 314     radio() false, or by an item with FL_MENU_DIVIDER turned on.
 315   */
 316   int radio() const {return flags&FL_MENU_RADIO;}
 317   /** Returns the current value of the check or radio item. */
 318   int value() const {return flags&FL_MENU_VALUE;}
 319   /**
 320     Turns the check or radio item "on" for the menu item. Note that this
 321     does not turn off any adjacent radio items like set_only() does.
 322   */
 323   void set() {flags |= FL_MENU_VALUE;}
 324
 325   /** Turns the check or radio item "off" for the menu item. */
 326   void clear() {flags &= ~FL_MENU_VALUE;}
 327
 328   void setonly();
 329
 330   /** Gets the visibility of an item. */
 331   int visible() const {return !(flags&FL_MENU_INVISIBLE);}
 332
 333   /** Makes an item visible in the menu. */
 334   void show() {flags &= ~FL_MENU_INVISIBLE;}
 335
 336   /** Hides an item in the menu. */
 337   void hide() {flags |= FL_MENU_INVISIBLE;}
 338
 339   /** Gets whether or not the item can be picked. */
 340   int active() const {return !(flags&FL_MENU_INACTIVE);}
 341
 342   /** Allows a menu item to be picked. */
 343   void activate() {flags &= ~FL_MENU_INACTIVE;}
 344   /**
 345     Prevents a menu item from being picked. Note that this will also cause
 346     the menu item to appear grayed-out.
 347   */
 348   void deactivate() {flags |= FL_MENU_INACTIVE;}
 349   /** Returns non 0 if FL_INACTIVE and FL_INVISIBLE are cleared, 0 otherwise. */
 350   int activevisible() const {return !(flags & (FL_MENU_INACTIVE|FL_MENU_INVISIBLE));}
 351
 352   // compatibility for FLUID so it can set the image of a menu item...
 353
 354   /** compatibility api for FLUID, same as a->label(this) */
 355   void image(Fl_Image* a) {a->label(this);}
 356
 357   /** compatibility api for FLUID, same as a.label(this) */
 358   void image(Fl_Image& a) {a.label(this);}
 359
 360   // used by menubar:
 361   int measure(int* h, const Fl_Menu_*) const;
 362   void draw(int x, int y, int w, int h, const Fl_Menu_*, int t=0) const;
 363
 364   // popup menus without using an Fl_Menu_ widget:
 365   const Fl_Menu_Item* popup(
 366     int X, int Y,
 367     const char *title = 0,
 368     const Fl_Menu_Item* picked=0,
 369     const Fl_Menu_* = 0) const;
 370   const Fl_Menu_Item* pulldown(
 371     int X, int Y, int W, int H,
 372     const Fl_Menu_Item* picked = 0,
 373     const Fl_Menu_* = 0,
 374     const Fl_Menu_Item* title = 0,
 375     int menubar=0) const;
 376   const Fl_Menu_Item* test_shortcut() const;
 377   const Fl_Menu_Item* find_shortcut(int *ip=0, const bool require_alt = false) const;
 378
 379   /**
 380     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
 381     The callback is called with the stored user_data() as its second argument.
 382     You must first check that callback() is non-zero before calling this.
 383   */
 384   void do_callback(Fl_Widget* o) const {callback_(o, user_data_);}
 385
 386   /**
 387     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
 388     This call overrides the callback's second argument with the given value \p arg.
 389     You must first check that callback() is non-zero before calling this.
 390   */
 391   void do_callback(Fl_Widget* o,void* arg) const {callback_(o, arg);}
 392
 393   /**
 394     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
 395     This call overrides the callback's second argument with the
 396     given value \p arg. long \p arg is cast to void* when calling
 397     the callback.
 398     You must first check that callback() is non-zero before calling this.
 399   */
 400   void do_callback(Fl_Widget* o,long arg) const {callback_(o, (void*)arg);}
 401
 402   // back-compatibility, do not use:
 403
 404   /** back compatibility only \deprecated. */
 405   int checked() const {return flags&FL_MENU_VALUE;}
 406
 407   /** back compatibility only \deprecated. */
 408   void check() {flags |= FL_MENU_VALUE;}
 409
 410   /** back compatibility only \deprecated. */
 411   void uncheck() {flags &= ~FL_MENU_VALUE;}
 412
 413   int insert(int,const char*,int,Fl_Callback*,void* =0, int =0);
 414   int add(const char*, int shortcut, Fl_Callback*, void* =0, int = 0);
 415
 416   /** See int add(const char*, int shortcut, Fl_Callback*, void*, int) */
 417   int add(const char*a, const char* b, Fl_Callback* c,
 418           void* d = 0, int e = 0) {
 419     return add(a,fl_old_shortcut(b),c,d,e);}
 420
 421   int size() const ;
 422 };
 423
 424 typedef Fl_Menu_Item Fl_Menu; // back compatibility
 425
 426 enum {  // back-compatibility enum:
 427   FL_PUP_NONE   = 0,
 428   FL_PUP_GREY   = FL_MENU_INACTIVE,
 429   FL_PUP_GRAY   = FL_MENU_INACTIVE,
 430   FL_MENU_BOX   = FL_MENU_TOGGLE,
 431   FL_PUP_BOX    = FL_MENU_TOGGLE,
 432   FL_MENU_CHECK = FL_MENU_VALUE,
 433   FL_PUP_CHECK  = FL_MENU_VALUE,
 434   FL_PUP_RADIO  = FL_MENU_RADIO,
 435   FL_PUP_INVISIBLE = FL_MENU_INVISIBLE,
 436   FL_PUP_SUBMENU = FL_SUBMENU_POINTER
 437 };
 438
 439 #endif
 440
 441 //
 442 // End of "$Id: Fl_Menu_Item.H 7983 2010-12-09 00:04:06Z AlbrechtS $".
 443 //