FLTK matrix user chat room
(using Element browser app)   FLTK gitter user chat room   GitHub FLTK Project   FLTK News RSS Feed  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  ]

class Fl_Widget

Class Hierarchy

Include Files

    #include <FL/Fl_Widget.H>


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.


protected Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char* label=0);

Creates a widget at the given position and size. The Fl_Widget is a protected constructor, 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();

Destroys the widget. Destroying single widgets is not very common, and it is your responsibility to either remove() them from any enclosing group or destroy that group immediately after destroying the children. You almost always want to destroy the parent group instead which will destroy all of the child widgets and groups in that group.

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. Inactive widgets will be drawn "grayed out", e.g. with less contrast than the active widget. Inactive widgets will not receive any keyboard or mouse button events. Other events (including FL_ENTER, FL_MOVE, FL_LEAVE, FL_SHORTCUT, and others) will still be sent. 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.

Fl_Align Fl_Widget::align() const
void Fl_Widget::align(Fl_Align)

Gets or sets the label alignment, which controls how the label is displayed next to or inside the widget. The default value is FL_ALIGN_CENTER, which centers the label inside the widget. The value can be any of these constants bitwise-OR'd together:


long Fl_Widget::argument() const
void Fl_Widget::argument(long)

Gets or sets the current user data (long) argument that is passed to the callback function.


This is implemented by casting the long value to a void * and may not be portable on some machines.

Fl_Boxtype Fl_Widget::box() const
void Fl_Widget::box(Fl_Boxtype)

Gets or sets the box type for the widget, which identifies a routine that draws the background of the widget. See Box Types for the available types. The default depends on the widget, but is usually FL_NO_BOX or FL_UP_BOX.

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

Gets or sets the current callback function for the widget. Each widget has a single callback.

int Fl_Widget::changed() const
void Fl_Widget::clear_changed()
void Fl_Widget::set_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.

void Fl_Widget::clear_visible();

Hides the widget; you must still redraw the parent to see a change in the window. Normally you want to use the hide() method instead.

void Fl_Window::clear_visible_focus();

Disables keyboard focus navigation with this widget; normally, all widgets participate in keyboard focus navigation.

Fl_Color Fl_Widget::color() const
void Fl_Widget::color(Fl_Color)
void Fl_Widget::color(Fl_Color, Fl_Color)

Gets or sets the background color of the widget. The color is passed to the box routine. The color is either an index into an internal table of RGB colors or an RGB color value generated using fl_rgb_color(). The default for most widgets is FL_BACKGROUND_COLOR. See the enumeration list for predefined colors. Use Fl::set_color() to redefine colors.

The two color form sets both the background and selection colors. See the description of the selection_color() method for more information.

int Fl_Widget::contains(Fl_Widget* b) const

Returns 1 if b is a child of this widget, or is equal to this widget. Returns 0 if b is NULL.

void Fl_Widget::copy_label(const char*)

Sets the current label. Unlike label(), this method allocates a copy of the label string instead of using the original string pointer.

uchar Fl_Widget::damage() const
void damage(uchar c);
void damage(uchar c, int X, int Y, int W, int H);

The first version returns non-zero if draw() needs to be called. The damage value is actually a bit field that the widget subclass can use to figure out what parts to draw.

The last two forms set the damage bits for the widget; the last form damages the widget within the specified bounding box.

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

The default callback, which puts a pointer to the widget on the queue returned by Fl::readqueue(). You may want to call this from your own callback.

Fl_Image* Fl_Widget::deimage()
void Fl_Widget::deimage(Fl_Image* a)
void Fl_Widget::deimage(Fl_Image& a)

Gets or sets the image to use as part of the widget label. This image is used when drawing the widget in the inactive state.

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

Causes a widget to invoke its callback function, optionally with arbitrary arguments.

virtual int Fl_Widget::handle(int event)

Handles the specified event. You normally don't call this method directly, but instead let FLTK do it when the user interacts with the widget.

When implemented in a new widget, this function must return 0 if the widget does not use the event or 1 if it uses the event.

Fl_Image* Fl_Widget::image()
void Fl_Widget::image(Fl_Image* a)
void Fl_Widget::image(Fl_Image& a)

Gets or sets the image to use as part of the widget label. This image is used when drawing the widget in the active state.

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

Returns 1 if this widget is a child of a, or is equal to a. Returns 0 if a is NULL.

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

Get or set the current label pointer. The label is shown somewhere on or next to the widget. The passed pointer is stored unchanged in the widget (the string is not copied), so if you need to set the label to a formatted value, make sure the buffer is static, global, or allocated. The copy_label() method can be used to make a copy of the label string automatically.

Fl_Color Fl_Widget::labelcolor() const
void Fl_Widget::labelcolor(Fl_Color)

Gets or sets the label color. The default color is FL_FOREGROUND_COLOR.

Fl_Font Fl_Widget::labelfont() const
void Fl_Widget::labelfont(Fl_Font)

Gets or sets the font to use. Fonts are identified by small 8-bit indexes into a table. See the enumeration list for predefined typefaces. The default value uses a Helvetica typeface (Arial for Microsoft® Windows®). The function Fl::set_font() can define new typefaces.

uchar Fl_Widget::labelsize() const
void Fl_Widget::labelsize(uchar)

Gets or sets the font size in pixels. The default size is 14 pixels.

void Fl_Widget::label(Fl_Labeltype, const char*)
uchar Fl_Widget::labeltype() const
void Fl_Widget::labeltype(Fl_Labeltype)

Gets or sets the labeltype which identifies the function that draws the label of the widget. This is generally used for special effects such as embossing or for using the label() pointer as another form of data such as an icon. The value FL_NORMAL_LABEL prints the label as plain text.

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

output() means the same as !active() except it does not change how the widget is drawn. The widget will not receive any events. This is useful for making scrollbars or buttons that work as displays rather than input devices.

Fl_Group *Fl_Widget::parent() const

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

void Fl_Widget::redraw()

Marks the widget as needing its draw() routine called.

void Fl_Widget::redraw_label()

Marks the widget or the parent as needing a redraw for the label area of a widget.

virtual 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. This is a virtual function so that the widget may implement its own handling of resizing. The default version does not call the redraw() method, but instead relies on the parent widget to do so because the parent may know a faster way to update the display, such as scrolling from the old position.

Some window managers under X11 call resize a lot more often than needed. Please verify that the position or size of a widget did actually change before doing any extensiive calculations.

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

Fl_Color Fl_Widget::selection_color() const
void Fl_Widget::selection_color(Fl_Color)

Gets or sets the selection color, which is defined for Forms compatibility and is usually used to color the widget when it is selected, although some widgets use this color for other purposes. You can set both colors at once with color(a,b).

int Fl_Widget::takesevents() const

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

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.

const char *Fl_Widget::tooltip()
void Fl_Widget::tooltip(const char *t)

Gets or sets a string of text to display in a popup tooltip window when the user hovers the mouse over the widget. The string is not copied, so make sure any formatted string is stored in a static, global, or allocated buffer.

If no tooltip is set, the tooltip of the parent is inherited. Setting a tooltip for a group and setting no tooltip for a child will show the group's tooltip instead. To avoid this behavior, you can set the child's tooltip to an empty string ("").

uchar Fl_Widget::type() const;

Returns the widget type value, which is used for Forms compatability and to simulate RTTI.

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

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

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

Gets or sets the current user data (void *) argument that is passed to the callback function.

Fl_Window* Fl_Widget::window() const;

Returns a pointer to the primary Fl_Window widget. Returns NULL if no window is associated with this widget. Note: for an Fl_Window widget, this returns its parent window (if any), not this window.

void Fl_Widget::set_visible();

Makes the widget visible; you must still redraw the parent widget to see a change in the window. Normally you want to use the show() method instead.

void Fl_Widget::set_visible_focus();

Enables keyboard focus navigation with this widget; note, however, that this will not necessarily mean that the widget will accept focus, but for widgets that can accept focus, this method enables it if it has been disabled.

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.

void Fl_Widget::visible_focus(int);
int Fl_Widget::visible_focus();

Modifies keyboard focus navigation. See set_visible_focus() and clear_visible_focus(). The second form returns non-zero if this widget will participate in keyboard focus navigation.

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.

User Comments [ Add Comment ]

From Anonymous, 19:51 Jun 10, 2004 (score=4)

The effect of the align() function is not clear from just the names of the arguments.  Pictures (or word pictures) are needed to explain what these names mean.

It is particularly unclear how these interact with an image drawn on the button, as adding an image makes the label move.
Reply ]

From Mark T., 11:27 Sep 16, 2004 (score=3)

It is not documented what the second argument in this call is for:

void Fl_Widget::callback(Fl_Callback*, void* = 0)

I assume that it serves the same purpose as the user_data(void*) function, but there is no indication that this is true nor explanation of how the two might interact (does one take precedence?).
Reply ]

From greg.ercolano, 16:58 Jun 07, 2006 (score=3)

> I assume that it serves the same purpose as the user_data(void*)


> does one take precedence?

    Which ever method is called last takes precedence.

    In other words, callback(foo,(void*)data) will stay in
    effect until changed with user_data(newdata);
Reply ]


Comments are owned by the poster. All other content is copyright 1998-2023 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to ''.