1 // 2 // "$Id$" 3 // 4 // Button header file for the Fast Light Tool Kit (FLTK). 5 // 6 // Copyright 1998-2014 by Bill Spitzak and others. 7 // 8 // This library is free software. Distribution and use rights are outlined in 9 // the file "COPYING" which should have been included with this file. If this 10 // file is missing or damaged, see the license at: 11 // 12 // http://www.fltk.org/COPYING.php 13 // 14 // Please report all bugs and problems on the following page: 15 // 16 // http://www.fltk.org/str.php 17 // 18 19 /* \file 20 Fl_Button widget . */ 21 22 #ifndef Fl_Button_H 23 #define Fl_Button_H 24 25 #ifndef Fl_Widget_H 26 #include "Fl_Widget.H" 27 #endif 28 29 // values for type() 30 #define FL_NORMAL_BUTTON 0 /**< value() will be set to 1 during the press of the button and 31 reverts back to 0 when the button is released */ 32 #define FL_TOGGLE_BUTTON 1 ///< value() toggles between 0 and 1 at every click of the button 33 #define FL_RADIO_BUTTON (FL_RESERVED_TYPE+2) /**< is set to 1 at button press, and all other 34 buttons in the same group with <tt>type() == FL_RADIO_BUTTON</tt> 35 are set to zero.*/ 36 #define FL_HIDDEN_BUTTON 3 ///< for Forms compatibility 37 38 extern FL_EXPORT Fl_Shortcut fl_old_shortcut(const char*); 39 40 class Fl_Widget_Tracker; 41 42 /** 43 \class Fl_Button 44 \brief Buttons generate callbacks when they are clicked by the user. 45 46 You control exactly when and how by changing the values for type() and 47 when(). Buttons can also generate callbacks in response to \c FL_SHORTCUT 48 events. The button can either have an explicit shortcut(int s) value or a 49 letter shortcut can be indicated in the label() with an '\&' character 50 before it. For the label shortcut it does not matter if \e Alt is held 51 down, but if you have an input field in the same window, the user will have 52 to hold down the \e Alt key so that the input field does not eat the event 53 first as an \c FL_KEYBOARD event. 54 55 \todo Refactor the doxygen comments for Fl_Button type() documentation. 56 57 For an Fl_Button object, the type() call returns one of: 58 \li \c FL_NORMAL_BUTTON (0): value() remains unchanged after button press. 59 \li \c FL_TOGGLE_BUTTON: value() is inverted after button press. 60 \li \c FL_RADIO_BUTTON: value() is set to 1 after button press, and all other 61 buttons in the current group with <tt>type() == FL_RADIO_BUTTON</tt> 62 are set to zero. 63 64 \todo Refactor the doxygen comments for Fl_Button when() documentation. 65 66 For an Fl_Button object, the following when() values are useful, the default 67 being \c FL_WHEN_RELEASE: 68 \li \c 0: The callback is not done, instead changed() is turned on. 69 \li \c FL_WHEN_RELEASE: The callback is done after the user successfully 70 clicks the button, or when a shortcut is typed. 71 \li \c FL_WHEN_CHANGED: The callback is done each time the value() changes 72 (when the user pushes and releases the button, and as the mouse is 73 dragged around in and out of the button). 74 */ 75 76 class FL_EXPORT Fl_Button : public Fl_Widget { 77 78 int shortcut_; 79 char value_; 80 char oldval; 81 uchar down_box_; 82 83 protected: 84 85 static Fl_Widget_Tracker *key_release_tracker; 86 static void key_release_timeout(void*); 87 void simulate_key_action(); 88 89 virtual void draw(); 90 91 public: 92 93 virtual int handle(int); 94 95 Fl_Button(int X, int Y, int W, int H, const char *L = 0); 96 97 int value(int v); 98 99 /** 100 Returns the current value of the button (0 or 1). 101 */ value()102 char value() const {return value_;} 103 104 /** 105 Same as \c value(1). 106 \see value(int v) 107 */ set()108 int set() {return value(1);} 109 110 /** 111 Same as \c value(0). 112 \see value(int v) 113 */ clear()114 int clear() {return value(0);} 115 116 void setonly(); // this should only be called on FL_RADIO_BUTTONs 117 118 /** 119 Returns the current shortcut key for the button. 120 \retval int 121 */ shortcut()122 int shortcut() const {return shortcut_;} 123 124 /** 125 Sets the shortcut key to \c s. 126 Setting this overrides the use of '\&' in the label(). 127 The value is a bitwise OR of a key and a set of shift flags, for example: 128 <tt>FL_ALT | 'a'</tt>, or 129 <tt>FL_ALT | (FL_F + 10)</tt>, or just 130 <tt>'a'</tt>. 131 A value of 0 disables the shortcut. 132 133 The key can be any value returned by Fl::event_key(), but will usually be 134 an ASCII letter. Use a lower-case letter unless you require the shift key 135 to be held down. 136 137 The shift flags can be any set of values accepted by Fl::event_state(). 138 If the bit is on, that shift key must be pushed. Meta, Alt, Ctrl, and 139 Shift must be off if they are not in the shift flags (zero for the other 140 bits indicates a "don't care" setting). 141 \param[in] s bitwise OR of key and shift flags 142 */ shortcut(int s)143 void shortcut(int s) {shortcut_ = s;} 144 145 /** 146 Returns the current down box type, which is drawn when value() is non-zero. 147 \retval Fl_Boxtype 148 */ down_box()149 Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;} 150 151 /** 152 Sets the down box type. The default value of 0 causes FLTK to figure out 153 the correct matching down version of box(). 154 155 Some derived classes (e.g. Fl_Round_Button and Fl_Light_Button use 156 down_box() for special purposes. See docs of these classes. 157 158 \param[in] b down box type 159 */ down_box(Fl_Boxtype b)160 void down_box(Fl_Boxtype b) {down_box_ = b;} 161 162 /// (for backwards compatibility) shortcut(const char * s)163 void shortcut(const char *s) {shortcut(fl_old_shortcut(s));} 164 165 /// (for backwards compatibility) down_color()166 Fl_Color down_color() const {return selection_color();} 167 168 /// (for backwards compatibility) down_color(unsigned c)169 void down_color(unsigned c) {selection_color(c);} 170 }; 171 172 #endif 173 174 // 175 // End of "$Id$". 176 // 177