Class Hierarchy
Fl_Widget
|
+----Fl_Box, Fl_Browser_, Fl_Button, Fl_Chart, Fl_Clock,
Fl_Free, Fl_Group, Fl_Input, Fl_Menu_, Fl_Positioner,
Fl_Timer, Fl_Valuator
Include Files
#include <FL/Fl_Widget.H>
Description
Fl_Widget is the base class for all widgets in FLTK. You can't
create one of these because the constructor is not public. However you
can subclass it.
All "property" accessing methods, such as color(),
parent(), or argument() are implemented as trivial inline
functions and thus are as fast and small as accessing fields in a
structure. Unless otherwise noted, the property setting methods such as
color(n) or label(s) are also trivial inline functions,
even if they change the widget's appearance. It is up to the user code
to call redraw() after these.
Methods
Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char*
label=0);
This is the protected constructor for an Fl_Widget, but all derived
widgets have a matching public constructor. It takes a value for x(),
y(), w(), h(), and an optional value for label().
virtual Fl_Widget::~Fl_Widget();
Destroying single widgets is not very common. It is your
responsibility to either remove() them from any enclosing group, or to
destroy that group immediately after destroying the children.
uchar Fl_Widget::type() const;
This value is used for Forms compatability and to simulate RTTI.
The position of the upper-left corner of the widget in its enclosing
Fl_Window (not its parent if that is not an Fl_Window), and its
width and height.
Returns h() (or w()), but if the current value is zero it calls
layout() before returning the value. Using these calls allows a
widget to delay the calculation of size until it is needed.
Change the size or position of the widget. Nothing is done if the
passed size and position are the same as before. If the size changes,
this sets a flag so that the virtual function layout() is called
before the next draw(). position(x,y) is a shortcut for
resize(x,y,w(),h()), and size(w,h) is a shortcut for
resize(x(),y(),w,h).
This is a virtual function
so the widget may implement its own handling of resizing. The default
version does not do redraw(), that is the parent widget's
responsibility (this is because the parent may know a faster way to
update the display, such as scrolling from the old position).
Return a pointer to the Fl_Window
that this widget is in (it will skip any and all parent widgets
between this and the window). Returns NULL if none. Note:
for an Fl_Window, this returns its parent window (if
any), not this window.
const Fl_Style* Fl_Widget::style() const
Return the Fl_Style structure used by this
widget. Normally this structure is shared with many other widgets.
Fl_Style* Fl_Widget::wstyle();
Returns a "writable" style. If the current value of style() is shared then a unique copy is made and
returned. This may be modified without changing other widgets.
bool Fl_Widget::style(Fl_Style* s);
bool Fl_Widget::style(Fl_Style& s);
Set the style to this shared style. If this style has never
been used before fltk adds it as a child of the current style and
returns true (this allows the calling code to initialize it).
Copy the style from another widget. If it is not shared then a copy
is made, otherwise the pointer is just copied. This is done so that
either widget may be destroyed without deleting the style used by the
other one.
Return the given field out of the style().
void Fl_Widget::box(Fl_Boxtype);
void Fl_Widget::text_box(Fl_Boxtype);
void Fl_Widget::glyph(Fl_Glyph);
void Fl_Widget::label_font(Fl_Font);
void Fl_Widget::text_font(Fl_Font);
void Fl_Widget::label_type(Fl_Labeltype);
void Fl_Widget::color(Fl_Color);
void Fl_Widget::label_color(Fl_Color);
void Fl_Widget::highlight_color(Fl_Color);
void Fl_Widget::highlight_label_color(Fl_Color);
void Fl_Widget::text_background(Fl_Color);
void Fl_Widget::text_color(Fl_Color);
void Fl_Widget::selection_color(Fl_Color);
void Fl_Widget::selection_text_color(Fl_Color);
void Fl_Widget::label_size(unsigned);
void Fl_Widget::text_size(unsigned);
void Fl_Widget::leading(unsigned);
These all create a writable Fl_Style with wstyle() and set the given field in it.
The label is printed somewhere on the widget or next to it. The
string passed to label() is not copied, it simply replaces the
value currently in the widget.
The passed string is copied to private storage and used to set the
label. The memory will be freed when the widget is destroyed or when
copy_label is called again. You can pass NULL and
it will set label() to NULL.
Don't call label(string) after this, as it replaces the pointer
without checking.
Fl_Image to draw as part of the label.
Each widget, and many of the drawing functions, take a bitmask of
flags that indicate the current state and exactly how to draw
things. The following flags are defined:
- FL_INACTIVE - does not get events, gray it out
- FL_INVISIBLE - does not get events, does not draw
- FL_OUTPUT - does not get events
- FL_VALUE - value(), indicates true/down/on state
- FL_CHANGED - changed(), value changed since last callback
- FL_COPIED_LABEL - destructor will delete label()
- FL_FOCUSED - draw with keyboard focus
- FL_HIGHLIGHT - draw highlighted
- FL_FRAME_ONLY - don't draw interior of boxes
- FL_SELECTED - draw using selection colors
- FL_NO_SHORTCUT_LABEL - don't draw &x in label as underscore
- FL_MENU_STAYS_UP - dont exit menu when picked
- FL_OPEN - this group in a Fl_Browser is open
- FL_ALIGN_* - label alignment, see below.
Forces the values of all the FL_ALIGN_* flags to the passed
value. This determines how the label is printed next to or inside the
widget. The default value is FL_ALIGN_CENTER, which centers
the label. The value can be any of these constants or'd together:
- FL_ALIGN_CENTER
- FL_ALIGN_TOP
- FL_ALIGN_BOTTOM
- FL_ALIGN_LEFT
- FL_ALIGN_RIGHT
- FL_ALIGN_INSIDE
- FL_ALIGN_CLIP
- FL_ALIGN_WRAP
Each widget has a single callback. You can set it or examine it with
these methods.
You can also just change the void* second argument to the
callback with the user_data methods.
For convenience you can also define the callback as taking a long
integer argument. This is implemented by casting the function to a
Fl_Callback and casting the long to a void
* and may not be portable to some machines.
void Fl_Widget::callback(void (*)(Fl_Widget*))
For convenience you can also define the callback as taking only one
argument. This is implemented by casting this to a Fl_Callback
and may not be portable to some machines.
You can cause a widget to do its callback at any time, and even pass
arbitrary arguments.
Fl_Widget::changed() is a flag that is turned on when the user
changes the value stored in the widget. This is only used by
subclasses of Fl_Widget that store values, but is in the base
class so it is easier to scan all the widgets in a panel and
do_callback() on the changed ones in response to an "OK" button.
Most widgets turn this flag off when they do the callback, and when
the program sets the stored value.
Fl_Widget::when() is a set of bitflags used by subclasses of
Fl_Widget to decide when to do the callback. If the value is zero
then the callback is never done. Other values are described in the
individual widgets. This field is in the base class so that you can
scan a panel and do_callback() on all the ones that don't do
their own callbacks in response to an "OK" button.
The default callback does nothing. callback()
is initialized to this.
An invisible widget never gets redrawn and does not get events. The
visible() method returns true if the widget is set to be
visible.The visible_r() method returns true if the widget and
all of its parents are visible. A widget is only visible if
visible() is true on it and all of its parents.
Changing it will send FL_SHOW or FL_HIDE
events to the widget. Do not change it if the parent is not
visible, as this will send false FL_SHOW or FL_HIDE
events to the widget. redraw() is called if necessary on
this or the parent.
Fl_Widget::active() returns whether the widget is active.
Fl_Widget::active_r() returns whether the widget and all of
its parents are active. An inactive widget does not get any events,
but it does get redrawn. A widget is only active if active() is
true on it and all of its parents.
Changing this value will send FL_ACTIVATE or
FL_DEACTIVATE to the widget if active_r() is true.
Currently you cannot deactivate Fl_Window widgets.
output() means the same as !active() except it does
not change how the widget is drawn. The widget will not recieve any
events. This is useful for making scrollbars or buttons that work as
displays rather than input devices.
This is the same as (active() && visible() &&
!output()) but is faster.
Mark the widget as needing its draw() method called. The
passed bits are or'd into the value of damage(). All parents then have
damage(FL_DAMAGE_CHILD) called on them, and a global flag is
set indicating that fltk should search for damaged widgets.
Indicate that an outside labels needs to be redrawn. This does nothing
if the label is inside the widget or there is no label. If the label
is outside, the enclosing group is flagged to redraw it.
Same as damage(FL_DAMAGE_ALL). This is the normal call to
make to indicate damage.
Indicate that the outside label needs to be redrawn. This
causes the parent widget to be redrawn in order to erase the old label
and then produce the new one.
Returns a pointer to the parent widget. Usually this is a Fl_Group or Fl_Window. Returns
NULL if none.
Returns true if b is a child of this widget, or is equal to
this widget. Returns false if b is NULL.
Returns true if this is a child of a, or is equal to
a. Returns false if a is NULL.
Tries to make this widget be the Fl::focus() widget, by first
sending it an FL_FOCUS event, and if it returns non-zero,
setting Fl::focus() to this widget. You should use this
method to assign the focus to an widget. Returns true if the widget
accepted the focus.
Methods for subclasses to use
You should not call the methods in this section except from a subclass
of Fl_Widget. See Adding and
Extending Widgets.
The 'or' of all the calls to damage(n) done since the last
draw(). Cleared to zero after draw() is
called.
When redrawing your widgets you should look at the damage bits to
see what parts of your widget need redrawing. The handle()
method can then set individual damage bits to limit the amount of drawing
that needs to be done:
MyClass::handle(int event) {
...
if (change_to_part1) damage(1);
if (change_to_part2) damage(2);
if (change_to_part3) damage(4);
}
MyClass::draw() {
if (damage() & FL_DAMAGE_ALL) {
... draw frame/box and other static stuff ...
}
if (damage() & (FL_DAMAGE_ALL | 1)) draw_part1();
if (damage() & (FL_DAMAGE_ALL | 2)) draw_part2();
if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3();
}
The first form indicates that a partial update of the object is
needed. The bits in mask are OR'd into damage(). Your
draw() routine can examine these bits to limit what it is
drawing. The public method Fl_Widget::redraw() simply does
Fl_Widget::damage(FL_DAMAGE_ALL), but the implementation of
your widget can call the private damage(n).
The second form indicates that a region is damaged. If only these
calls are done in a window (no calls to damage(n)) then FLTK
will clip to the union of all these calls before drawing anything.
This can greatly speed up incremental displays. The mask bits are
OR'd into damage().
Calls box()->draw() with the given
arguments, to draw the box in the given rectangle. The flags may be
used to cause box effects such as making it inactive or selected.
Calls draw_box(x(),y(),y(),h(),f) where f is the
current flags() plus:
- FL_INACTIVE if !active_r()
Returns the resulting flags so you can pass them to another function.
Standard routine for drawing Fl_Button and similar widgets. Calls
draw_box() but with the following bits 'or'd into the flags:
- FL_SELECTED if FL_VALUE is on and
selected_color is set in this widget's style (not
inherited).
- FL_INACTIVE if !active_r()
- FL_HIGHLIGHT if belowmouse()
- FL_FOCUSED if focused()
Returns the resulting flags so you can pass them to another function.
Same as draw_button() but starts with f instead of
flags(). This can be used to force FL_VALUE on or
off.
Draws text_box() with the FL_FRAME_ONLY flag turned
on (so only the edge is drawn). Also turns on FL_INACTIVE if
!active_r().
Calls draw_text_frame() and then draws a rectangle of
text_background() color inside it. It uses
text_box()->inset() to figure out where to draw the
rectangle.
Calls the glyph() function with the given arguments (the
caller must figure out inactive and selected, this is best done by
using the return value from draw_box()).
Returns the correct color to draw a glyph, based on the values of
FL_INACTIVE, FL_SELECTED, FL_HIGHLIGHT of the flags and the
text_color(), selection_text_color(), highlight_label_color()
of this widget.
Returns the correct color to draw the interior of a box, based on the
values of FL_SELECTED, FL_HIGHLIGHT of the flags and the
color(), selection_color(), highlight_color() of this widget.
Return in w and h the size that the widget's label() and
image() will take.
This is the usual function for a draw() method to call to
draw the widget's label. It does not draw the label if it is supposed
to be outside the box (on the assumption that the enclosing group will
draw those labels).
The label consists of the value for label() and the value
for image(). The alignment flags control how they are
arranged next to each other in the box. The color to draw the label is
determined by the settings of the flags, the active_r()
value, and the label_color(), selection_text_color(),
highlight_label_color() of this widget.
The second form uses the passed bounding box instead of the widget's
bounding box. This allows the widget to draw the label somewhere other
than centered on itself.
The third form lets you force FL_VALUE or
FL_SELECTED on or off (passed alignment flags are 'or'd with
the widget's flags).
Draws the label anywhere. This ignores the FL_ALIGN_INSIDE
and always draws the label inside the passed bounding box.
This is used by Fl_Group and Fl_Tabs to draw outside labels.
Fast inline versions of Fl_Widget::hide() and
Fl_Widget::show(). These do not send the FL_HIDE and
FL_SHOW events to the widget.
Tests the value of shortcut() and the value of
label() (if FL_NO_SHORTCUT_LABEL is not set) against
the current event (which must be a FL_SHORTCUT or FL_KEYBOARD
event). Returns 1 if it matches shortcut(), returns 2 if it matches
the label(), and returns 0 if there is no match.
Modifies draw_label() so that '&' characters do not get
translated into an underscore under the next letter. This flag also
stops Fl_Widget::test_shortcut from looking
at the label for this letter.
The property Fl_Widget::type() can return an arbitrary 8-bit
identifier, and can be set with the protected method type(uchar
t). This value had to be provided for Forms compatibility, but
you can use it for any purpose you want (mostly for "bad object
oriented programming" where you insert some subclass functionality
into the base class). Try to keep the value less than 100 to not
interfere with reserved values.
For portability FLTK does not use RTTI (Run Time Typing Infomation)
internally (you are free to use it, though). If you don't have RTTI you can
use the clumsy FLTK mechanisim, by having type() use a unique
value. These unique values must be greater than the symbol
FL_RESERVED_TYPE (which is 100). Look through the header
files for FL_RESERVED_TYPE to find an unused number. If you
make a subclass of Fl_Window you must use FL_WINDOW +
n (n must be in the range 1 to 7), if you
make a subclass of Fl_Group you must use FL_GROUP +
n (n must be in the range 1 to 7) (fltk needs to be able
to identify Fl_Window and Fl_Group subclasses internally).