2
// "$Id: Fl_Button.H 7903 2010-11-28 21:06:39Z matt $"
4
// Button header file for the Fast Light Tool Kit (FLTK).
6
// Copyright 1998-2010 by Bill Spitzak and others.
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.
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.
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
23
// Please report all bugs and problems on the following page:
25
// http://www.fltk.org/str.php
35
#include "Fl_Widget.H"
39
#define FL_NORMAL_BUTTON 0 /**< value() will be set to 1 during the press of the button and
40
reverts back to 0 when the button is released */
41
#define FL_TOGGLE_BUTTON 1 ///< value() toggles between 0 and 1 at every click of the button
42
#define FL_RADIO_BUTTON (FL_RESERVED_TYPE+2) /**< is set to 1 at button press, and all other
43
buttons in the same group with <tt>type() == FL_RADIO_BUTTON</tt>
45
#define FL_HIDDEN_BUTTON 3 ///< for Forms compatibility
47
extern FL_EXPORT Fl_Shortcut fl_old_shortcut(const char*);
49
class Fl_Widget_Tracker;
53
\brief Buttons generate callbacks when they are clicked by the user.
55
You control exactly when and how by changing the values for type() and
56
when(). Buttons can also generate callbacks in response to \c FL_SHORTCUT
57
events. The button can either have an explicit shortcut(int s) value or a
58
letter shortcut can be indicated in the label() with an '\&' character
59
before it. For the label shortcut it does not matter if \e Alt is held
60
down, but if you have an input field in the same window, the user will have
61
to hold down the \e Alt key so that the input field does not eat the event
62
first as an \c FL_KEYBOARD event.
64
\todo Refactor the doxygen comments for Fl_Button type() documentation.
66
For an Fl_Button object, the type() call returns one of:
67
\li \c FL_NORMAL_BUTTON (0): value() remains unchanged after button press.
68
\li \c FL_TOGGLE_BUTTON: value() is inverted after button press.
69
\li \c FL_RADIO_BUTTON: value() is set to 1 after button press, and all other
70
buttons in the current group with <tt>type() == FL_RADIO_BUTTON</tt>
73
\todo Refactor the doxygen comments for Fl_Button when() documentation.
75
For an Fl_Button object, the following when() values are useful, the default
76
being \c FL_WHEN_RELEASE:
77
\li \c 0: The callback is not done, instead changed() is turned on.
78
\li \c FL_WHEN_RELEASE: The callback is done after the user successfully
79
clicks the button, or when a shortcut is typed.
80
\li \c FL_WHEN_CHANGED: The callback is done each time the value() changes
81
(when the user pushes and releases the button, and as the mouse is
82
dragged around in and out of the button).
84
class FL_EXPORT Fl_Button : public Fl_Widget {
93
static Fl_Widget_Tracker *key_release_tracker;
94
static void key_release_timeout(void*);
95
void simulate_key_action();
101
virtual int handle(int);
103
Fl_Button(int X, int Y, int W, int H, const char *L = 0);
108
Returns the current value of the button (0 or 1).
110
char value() const {return value_;}
116
int set() {return value(1);}
122
int clear() {return value(0);}
124
void setonly(); // this should only be called on FL_RADIO_BUTTONs
127
Returns the current shortcut key for the button.
130
int shortcut() const {return shortcut_;}
133
Sets the shortcut key to \c s.
134
Setting this overrides the use of '\&' in the label().
135
The value is a bitwise OR of a key and a set of shift flags, for example:
136
<tt>FL_ALT | 'a'</tt>, or
137
<tt>FL_ALT | (FL_F + 10)</tt>, or just
139
A value of 0 disables the shortcut.
141
The key can be any value returned by Fl::event_key(), but will usually be
142
an ASCII letter. Use a lower-case letter unless you require the shift key
145
The shift flags can be any set of values accepted by Fl::event_state().
146
If the bit is on, that shift key must be pushed. Meta, Alt, Ctrl, and
147
Shift must be off if they are not in the shift flags (zero for the other
148
bits indicates a "don't care" setting).
149
\param[in] s bitwise OR of key and shift flags
151
void shortcut(int s) {shortcut_ = s;}
154
Returns the current down box type, which is drawn when value() is non-zero.
157
Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;}
160
Sets the down box type. The default value of 0 causes FLTK to figure out
161
the correct matching down version of box().
162
\param[in] b down box type
164
void down_box(Fl_Boxtype b) {down_box_ = b;}
166
/// (for backwards compatibility)
167
void shortcut(const char *s) {shortcut(fl_old_shortcut(s));}
169
/// (for backwards compatibility)
170
Fl_Color down_color() const {return selection_color();}
172
/// (for backwards compatibility)
173
void down_color(unsigned c) {selection_color(c);}
179
// End of "$Id: Fl_Button.H 7903 2010-11-28 21:06:39Z matt $".