class Fl_Widget


Class Hierarchy

Include Files

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.

int Fl_Widget::x() const
int Fl_Widget::y() const
int Fl_Widget::w() const
int Fl_Widget::h() const

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.

int Fl_Widget::height()
int Fl_Widget::width()

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.

void Fl_Widget::resize(int x, int y, int w, int h)
void Fl_Widget::position(short x, short y)
void Fl_Widget::size(short w, short h)

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).

virtual void Fl_Widget::layout()

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).

Fl_Window* Fl_Widget::window() const;

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).

bool copy_style(const Fl_Style* s);

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.

Fl_Boxtype Fl_Widget::box();
Fl_Boxtype Fl_Widget::text_box();
Fl_Glyph Fl_Widget::glyph();
Fl_Font Fl_Widget::label_font();
Fl_Font Fl_Widget::text_font();
Fl_Labeltype Fl_Widget::label_type();
Fl_Color Fl_Widget::color();
Fl_Color Fl_Widget::label_color();
Fl_Color Fl_Widget::highlight_color();
Fl_Color Fl_Widget::highlight_label_color();
Fl_Color Fl_Widget::text_background();
Fl_Color Fl_Widget::text_color();
Fl_Color Fl_Widget::selection_color();
Fl_Color Fl_Widget::selection_text_color();
unsigned Fl_Widget::label_size();
unsigned Fl_Widget::text_size();
unsigned Fl_Widget::leading();

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.

const char* Fl_Widget::label() const
void Fl_Widget::label(const char*)

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.

void Fl_Widget::copy_label(const char*)

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* Fl_Widget::image() const
void Fl_Widget::image(Fl_Image*)

Fl_Image to draw as part of the label.

Fl_Flags Fl_Widget::flags() const; void Fl_Widget::set_flag(Fl_Flags); void Fl_Widget::clear_flag(Fl_Flags);

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:

void Fl_Widget::align(Fl_Flags);

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_Callback* Fl_Widget::callback() const
void Fl_Widget::callback(Fl_Callback*, void* = 0)

Each widget has a single callback. You can set it or examine it with these methods.

void* Fl_Widget::user_data() const
void Fl_Widget::user_data(void*)

You can also just change the void* second argument to the callback with the user_data methods.

void Fl_Widget::callback(void (*)(Fl_Widget*, long), long = 0)
long Fl_Widget::argument() const
void Fl_Widget::argument(long)

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.

void Fl_Widget::do_callback()
void Fl_Widget::do_callback(Fl_Widget*, void* = 0)
void Fl_Widget::do_callback(Fl_Widget*, long)

You can cause a widget to do its callback at any time, and even pass arbitrary arguments.

int Fl_Widget::changed() const
void Fl_Widget::set_changed()
void Fl_Widget::clear_changed()

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_When Fl_Widget::when() const
void Fl_Widget::when(Fl_When)

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.

static void Fl_Widget::default_callback(Fl_Widget*, void*)

The default callback does nothing. callback() is initialized to this.

int Fl_Widget::visible() const
int Fl_Widget::visible_r() const
void Fl_Widget::show()
void Fl_Widget::hide()

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.

int Fl_Widget::active() const
int Fl_Widget::active_r() const
void Fl_Widget::activate()
void Fl_Widget::deactivate()

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.

int Fl_Widget::output() const
void Fl_Widget::set_output()
void Fl_Widget::clear_output()

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.

int Fl_Widget::takesevents() const

This is the same as (active() && visible() && !output()) but is faster.

void Fl_Widget::damage(uchar flags)

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.

void Fl_Widget::damage_label()

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.

void Fl_Widget::redraw()

Same as damage(FL_DAMAGE_ALL). This is the normal call to make to indicate damage.

uchar Fl_Widget::damage_label()

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.

Fl_Widget* Fl_Widget::parent() const

Returns a pointer to the parent widget. Usually this is a Fl_Group or Fl_Window. Returns NULL if none.

int Fl_Widget::contains(Fl_Widget* b) const

Returns true if b is a child of this widget, or is equal to this widget. Returns false if b is NULL.

int Fl_Widget::inside(const Fl_Widget* a) const

Returns true if this is a child of a, or is equal to a. Returns false if a is NULL.

int Fl_Widget::take_focus()

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.

uchar Fl_Widget::damage() const

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:

void Fl_Widget::damage(uchar mask)
void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)

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().

void Fl_Widget::draw_box(int x, int y, int w, int h, Fl_Flags f) const;

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.

Fl_Flags Fl_Widget::draw_box() const;

Calls draw_box(x(),y(),y(),h(),f) where f is the current flags() plus: Returns the resulting flags so you can pass them to another function.

Fl_Flags Fl_Widget::draw_button() const;

Standard routine for drawing Fl_Button and similar widgets. Calls draw_box() but with the following bits 'or'd into the flags: Returns the resulting flags so you can pass them to another function.

Fl_Flags Fl_Widget::draw_button(Fl_Flags f) const;

Same as draw_button() but starts with f instead of flags(). This can be used to force FL_VALUE on or off.

Fl_Flags Fl_Widget::draw_text_frame() const;
Fl_Flags Fl_Widget::draw_text_frame(int x, int y, int w, int h) const ;

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().

Fl_Flags Fl_Widget::draw_text_box() const;
Fl_Flags Fl_Widget::draw_text_box(int x, int y, int w, int h) const ;

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.

void Fl_Widget::draw_glyph(int type, int x,int y,int w,int h, Fl_Flags f) const

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()).

Fl_Color Fl_WIdget::glyph_color(Fl_Flags f) const ;

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.

Fl_Color Fl_WIdget::box_color(Fl_Flags f) const ;

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.

void Fl_Widget::measure_label(int& w, int& h) const ;

Return in w and h the size that the widget's label() and image() will take.

void Fl_Widget::draw_inside_label() const
void Fl_Widget::draw_inside_label(int x, int y, int w, int h) const
void Fl_Widget::draw_inside_label(int x, int y, int w, int h, Fl_Flags f) const

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).

void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Flags f) const

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.

void Fl_Widget::set_visible()
void Fl_Widget::clear_visible()

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.

int Fl_Widget::test_shortcut() const

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.

void Fl_Widget::set_flag(FL_NO_SHORTCUT_LABEL)

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.

uchar Fl_Widget::type() const
void Fl_Widget::type(uchar t)

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).