fltk::Widget Class Reference

Inherits fltk::Rectangle.

Inherited by AnsiWidget, fltk::Button, fltk::ccCellBox, fltk::ccHueBox, fltk::ccValueBox, fltk::ClockOutput, fltk::Divider, fltk::Group, fltk::Input, fltk::InvisibleBox, fltk::Item, fltk::ProgressBar, and fltk::Valuator.

List of all members.

Public Types


Public Member Functions

void activate (int b)
void activate ()
bool active () const
bool active_r () const
void add (const AssociationType &, void *data)
bool add_shortcut (unsigned key)
void add_timeout (float)
void align (unsigned a)
Flags align () const
bool all_of (unsigned f) const
bool any_of (unsigned f) const
void argument (long v)
long argument () const
bool belowmouse () const
void box (Box *)
Boxbox () const
void buttonbox (Box *)
Boxbuttonbox () const
void buttoncolor (Color)
Color buttoncolor () const
void callback (Callback1 *c, long p=0)
void callback (Callback0 *c)
void callback (Callback *c)
void callback (Callback *c, void *p)
Callback_p callback () const
bool changed () const
bool clear ()
void clear_changed ()
void clear_click_to_focus ()
void clear_flag (unsigned f)
void clear_output ()
void clear_selected ()
void clear_tab_to_focus ()
void clear_visible ()
bool click_to_focus ()
void color (Color)
Color color () const
bool contains (const Widget *) const
void copy_label (const char *a)
bool copy_style (const Style *s)
void cursor (Cursor *) const
uchar damage () const
void deactivate ()
void do_callback (Widget *o, long arg)
void do_callback (Widget *o, void *arg=0)
void do_callback ()
virtual void draw ()
void draw_background () const
void draw_box (const Rectangle &r) const
void draw_box () const
void draw_frame () const
void draw_glyph (int, const Rectangle &) const
void draw_label (const Rectangle &, Flags) const
void draw_label () const
bool find (const AssociationType &, void *data) const
bool flag (unsigned f) const
void flags (Flags f)
Flags flags () const
bool focused () const
void * foreach (const AssociationType &, AssociationFunctor &) const
void * get (const AssociationType &) const
void get_absolute_rect (Rectangle *rect) const
void glyph (Symbol *)
Symbolglyph () const
virtual int handle (int)
void hide ()
void highlight_color (Color)
Color highlight_color () const
void highlight_textcolor (Color)
Color highlight_textcolor () const
bool horizontal () const
void image (const Symbol &a)
void image (const Symbol *a)
const Symbolimage () const
bool inside (const Widget *o) const
void invert_flag (unsigned f)
bool is_group () const
bool is_window () const
void label (const char *a)
const char * label () const
unsigned label_shortcut () const
void labelcolor (Color)
Color labelcolor () const
void labelfont (Font *)
Fontlabelfont () const
void labelsize (float a)
float labelsize () const
void labeltype (LabelType *)
LabelType * labeltype () const
virtual void layout ()
void layout_damage (uchar c)
uchar layout_damage () const
void leading (float a)
float leading () const
void make_current () const
void measure_label (int &, int &) const
bool output () const
void parent (Group *w)
Groupparent () const
bool position (int x, int y)
bool pushed () const
void redraw (const Rectangle &)
void redraw (uchar c)
void redraw ()
void redraw_highlight ()
void redraw_label ()
void relayout (uchar damage)
void relayout ()
bool remove (const AssociationType &, void *data)
bool remove_shortcut (unsigned key)
void remove_shortcuts ()
void remove_timeout ()
void repeat_timeout (float)
bool resize (int w, int h)
bool resize (int x, int y, int w, int h)
void scrollbar_align (unsigned char)
unsigned char scrollbar_align () const
void scrollbar_width (unsigned char)
unsigned char scrollbar_width () const
bool selected () const
void selection_color (Color)
Color selection_color () const
void selection_textcolor (Color)
Color selection_textcolor () const
int send (int event)
void set (const AssociationType &, void *data)
bool set ()
void set_changed ()
void set_click_to_focus ()
void set_damage (uchar c)
void set_flag (unsigned f, bool b)
void set_flag (unsigned f)
void set_horizontal ()
void set_output ()
void set_selected ()
void set_tab_to_focus ()
void set_vertical ()
void set_visible ()
void setonly ()
void shortcut (unsigned key)
unsigned shortcut () const
void show ()
bool state (bool)
bool state () const
void style (const Style &s)
void style (const Style *s)
const Stylestyle () const
bool tab_to_focus ()
bool take_focus ()
bool takesevents () const
bool test_label_shortcut () const
bool test_shortcut (bool) const
bool test_shortcut () const
void textcolor (Color a)
Color textcolor () const
void textfont (Font *)
Fonttextfont () const
void textsize (float a)
float textsize () const
void throw_focus ()
void tooltip (const char *t)
const char * tooltip () const
void type (uchar t)
uchar type () const
void user_data (void *v)
void * user_data () const
bool vertical () const
bool visible () const
bool visible_r () const
void when (uchar i)
uchar when () const
 Widget (int, int, int, int, const char *=0)
Windowwindow () const
virtual ~Widget ()

Static Public Member Functions

static void default_callback (Widget *, void *)

Static Public Attributes

static Symboldefault_glyph
static NamedStyledefault_style


Detailed Description

The base class for all widgets in FLTK. The basic Widget draws an empty box() and the label(), and ignores all events. This can be useful for making decorations or providing areas that pop up a tooltip().

Constructor & Destructor Documentation

Widget::Widget ( int  X,
int  Y,
int  W,
int  H,
const char *  L = 0 
)

Standard constructor for a widget. The default constructor takes a value for x(), y(), w(), and h(), and an optional value for label(). All subclasses must provide an identical constructor in order to work with Fluid. They may also provide alternative constructors.

If Group::begin() has been called, this widget is added as a new child of that group, and parent() is set to the group. If Group::begin() has not been called, or Group::end() has been called, or Group::current(0), then the parent() is set to null. In this case you must add the widget yourself in order to see it.

References fltk::Group::add(), fltk::CLICK_TO_FOCUS, fltk::Group::current(), fltk::DAMAGE_ALL, default_callback(), fltk::LAYOUT_DAMAGE, and fltk::TAB_TO_FOCUS.

Widget::~Widget (  )  [virtual]

The destructor is virtual. The base class removes itself from the parent widget (if any), and destroys any label made with copy_label().

References fltk::COPIED_LABEL, fltk::Style::dynamic(), fltk::Group::remove(), remove_timeout(), and throw_focus().


Member Function Documentation

void Widget::draw ( void   )  [virtual]

Fltk calls this virtual function to draw the widget, after setting up the graphics (current window, xy translation, etc) so that any drawing functions will go into this widget.

User code should not call this! You probably want to call redraw().

The default version calls draw_box() and draw_label(), thus drawing the box() to fill the widget and putting the label() and image() inside it to fill it, unless the align() flags are set to put it outside.

Information on how to write your own version is here.

Reimplemented in fltk::Choice, fltk::GlutWindow, fltk::Input, fltk::InvisibleBox, fltk::Item, fltk::PopupMenu, and fltk::WizardGroup.

References fltk::ALIGN_CENTER, fltk::ALIGN_INSIDE, clear_flag(), draw_background(), draw_box(), draw_label(), fltk::HIGHLIGHT, and fltk::NO_BOX.

Referenced by fltk::Choice::draw(), fltk::Group::draw_child(), fltk::Menu::draw_in(), and fltk::Group::update_child().

int Widget::handle ( int  event  )  [virtual]

Handle an event. Returns non-zero if the widget understood and used the event.

The event numbers are listed in <fltk/events.h> . All other information about the current event (like mouse position) is accessed by various functions listed in the same header file.

The default version returns true for fltk::ENTER and fltk::MOVE events, this is done so you can put tooltips on the base widget. All other events return zero.

If you want to send an event to a widget you probably want to call send(), not handle(). Send will do extra work with each event before calling this, such as turning HIGHLIGHT and FOCUSED flags on/off.

Reimplemented in fltk::Divider, fltk::Group, fltk::Input, fltk::InvisibleBox, fltk::Item, fltk::ItemGroup, fltk::NumericInput, and fltk::Valuator.

References belowmouse(), fltk::DND_DRAG, fltk::ENTER, fltk::LEAVE, fltk::MOVE, and redraw_highlight().

Referenced by activate(), fltk::belowmouse(), deactivate(), fltk::focus(), fltk::handle(), fltk::Group::handle(), hide(), fltk::Group::insert(), fltk::paste(), send(), show(), and take_focus().

int Widget::send ( int  event  ) 

Wrapper for handle(). This should be called to send events. It does a few things:

References fltk::ACTIVATE, active(), belowmouse(), fltk::belowmouse(), clear_flag(), contains(), fltk::DEACTIVATE, fltk::DND_DRAG, fltk::DND_ENTER, fltk::DND_LEAVE, fltk::ENTER, fltk::event_state(), fltk::focus(), fltk::FOCUS, fltk::FOCUSED, handle(), fltk::HIDE, fltk::HIGHLIGHT, fltk::INACTIVE_R, fltk::INVISIBLE, fltk::LEAVE, fltk::MOVE, fltk::OUTPUT, parent(), fltk::PUSH, pushed(), fltk::pushed(), set_flag(), fltk::SHORTCUT, fltk::SHOW, take_focus(), throw_focus(), fltk::Rectangle::x(), and fltk::Rectangle::y().

Referenced by fltk::handle(), and fltk::Group::handle().

void Widget::layout (  )  [virtual]

Virtual function to respond to layout_damage(), it should calculate the correct size of this widget and all it's children. This function is called by fltk or by the layout() method in other widgets. User programs should not call it.

A widget is allowed to alter it's own size in a layout() method, to indicate a size that the data will fit in. A parent widget is then expected to rearrange itself to accomodate the new size. This may mean it will move the widget and thus layout() will be called again.

You can look at layout_damage() to find out why this is being called.

The base class redraws the widget.

Reimplemented in fltk::Divider, fltk::Item, fltk::Menu, and fltk::Tooltip.

References fltk::LAYOUT_CHILD, and redraw().

Referenced by fltk::Choice::draw(), fltk::Menu::draw_in(), fltk::Menu::find_selected(), fltk::Menu::get_location(), fltk::Group::layout(), and fltk::Menu::layout_in().

bool Widget::copy_style ( const Style t  ) 

Copy the Style from another widget. Copying a style pointer from another widget is not safe if that style is dynamic() because it may change or be deleted. This makes another dynamic() copy if necessary. For non-dynamic styles the pointer is copied.

References fltk::Style::dynamic(), and fltk::Style::parent_.

Group * Widget::parent (  )  const [inline]

Window * Widget::window (  )  const

Return a pointer to the fltk::Window this widget is in. (it will skip any and all parent widgets between this and the window). Returns NULL if none. Note: for an fltk::Window, this returns the parent window (if any), not this window.

References parent().

Referenced by fltk::Window::child_of(), fltk::Window::destroy(), fltk::Window::first(), fltk::focus(), fltk::handle(), make_current(), fltk::Window::next(), redraw_label(), fltk::Window::show(), and fltk::WizardGroup::value().

uchar Widget::type (  )  const [inline]

8-bit identifier that controls how widget works. 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). Widget subclasses may store values in the range 0-99 here (larger values are reserved for use by FLTK).

The fltk::PackedGroup widget uses the low bit of the type() of each child to indicate HORIZONTAL (1) or VERTICAL (0).

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 Widget::RESERVED_TYPE (which is 100). Look through the header files for Widget::RESERVED_TYPE to find an unused number. If you make a subclass of fltk::Window you must use Widget::WINDOW_TYPE+n (n must be in the range 1 to 7) so that is_window() will work, if you make a subclass of fltk::Group you must use Widget::GROUP_TYPE+n (n must be in the range 1 to 7) so that is_group() will work.

Referenced by fltk::Input::copy(), fltk::Slider::draw(), fltk::PopupMenu::draw(), fltk::Item::draw(), fltk::Input::draw(), fltk::Group::Group(), fltk::Item::handle(), fltk::Input::handle(), fltk::Input::handle_key(), fltk::Item::layout(), fltk::Input::line_end(), fltk::Input::line_start(), fltk::Input::mouse_position(), fltk::PopupMenu::popup(), fltk::Menu::popup(), fltk::Input::replace(), setonly(), fltk::Input::static_text(), fltk::Input::up_down_position(), fltk::Input::word_end(), and fltk::Input::word_start().

bool Widget::is_group (  )  const [inline]

Returns true for subclasses of fltk::Group. If so you can cast it to a group with (fltk::Group*)(widget). This is done by using type(), but if your compiler supports RTTI you may want to safer dynamic_cast<fltk::Group*>(widget).

Referenced by fltk::List::child(), fltk::List::children(), fltk::Menu::get_item(), fltk::Menu::handle_shortcut(), fltk::Menu::set_item(), fltk::Window::show(), and fltk::Menu::try_popup().

bool Widget::is_window (  )  const [inline]

Returns true for subclasses of fltk::Window. If so you can cast it to a window with (fltk::Window*)(widget). This is done by using type(), but if your compiler supports RTTI you may want to safer dynamic_cast<fltk::Window*>(widget). If this is true, is_group() is also true.

Referenced by fltk::Group::draw_child(), fltk::Group::fix_old_positions(), fltk::focus(), fltk::Group::layout(), make_current(), redraw(), fltk::Window::system_layout(), and fltk::Group::update_child().

bool Widget::resize ( int  x,
int  y,
int  w,
int  h 
)

Change the size or position of the widget. Nothing is done if the passed size and position are the same as before. If there is a change then relayout() is called so that the virtual function layout() is called before the next draw().

References flags(), fltk::Rectangle::h(), fltk::LAYOUT_CHILD, fltk::LAYOUT_DAMAGE, fltk::LAYOUT_H, fltk::LAYOUT_W, fltk::LAYOUT_X, fltk::LAYOUT_Y, parent(), relayout(), set(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

Referenced by fltk::handle(), fltk::Tooltip::layout(), position(), resize(), fltk::Window::show(), and fltk::StatusBarGroup::update_box().

bool Widget::position ( int  x,
int  y 
)

Same as resize() to x, y, w(), h()

Reimplemented in fltk::Input.

References fltk::Rectangle::h(), resize(), and fltk::Rectangle::w().

Referenced by fltk::Window::hotspot().

bool Widget::resize ( int  w,
int  h 
)

Same as resize() to x(), y(), w, h

References resize(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Widget::get_absolute_rect ( Rectangle rect  )  const

Fills the Rectangle pointed to by rect with the widget's rectangle expressed in absolute (i.e. screen) coordinates.

References fltk::Rectangle::h(), parent_, fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Widget::label ( const char *  s  ) 

bool Widget::inside(const Widget* a) const Returns true if this is a child of a, or is equal to a. Returns false if a is NULL.

Sets the label directly to a string. The label is printed somewhere on the widget or next to it. The string passed to label() is not copied, instead the pointer to the string is stored. If copy_label() was called earlier the old string's memory is freed.

Reimplemented in fltk::Window.

References fltk::COPIED_LABEL.

void Widget::copy_label ( const char *  s  ) 

Sets the label to a copy of the string. 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, or label(const char*) is called.

Passing NULL will set label() to NULL.

References fltk::COPIED_LABEL, and newstring().

Referenced by fltk::StatusBarGroup::set().

unsigned Widget::shortcut (  )  const

Returns one of the add_shortcut() assignments for this widget, or returns zero if there are none. If you want to look at more than onle you must use fltk::list_shortcuts(this).

Referenced by fltk::Menu::draw_in(), fltk::Item::Item(), and fltk::Menu::layout_in().

void Widget::shortcut ( unsigned  key  ) 

Same as remove_shortcuts(), add_shortcut(key) except it may be implemented in a more efficient way. The result is exactly one shortcut (or none if key is zero).

bool Widget::add_shortcut ( unsigned  key  ) 

Add a new shortcut assignment. Returns true if successful. If key is zero or the assignment already exists this does nothing and returns false.

There can be any number of shortcut assignments, fltk stores them in internal tables shared by all widgets. A widget can have any number of shortcuts (though most have zero or one), and a given shortcut value can be assigned to more than one widget.

If you only want one shortcut use shortcut() to assign it.

The shortcut value is a bitwise OR (or sum) of a any set of shift flags returned by fltk::event_state(), and either a key symbol returned by fltk::event_key(), or an ASCII character from fltk::event_text(). Examples:

For letters, 'A' will only match if the Shift key is not held down, and fltk::SHIFT+'a' will only match if the shift key is held down. Case (and thus Caps Lock) is ignored. The case does control how the shortcut is displayed in a menu so you will want to choose based on the style of your application.

Non-letters without fltk::SHIFT will match whether or not Shift is held down. Since both fltk::event_key() and fltk::event_text()[0] are matched, the '#' can be specified by any of fltk::SHIFT+'3', fltk::SHIFT+'#', or by '#'. You can choose based on how you want the shortcut to appear in menus and how you want to map to foreign keyboards.

When FLTK gets a keystroke, it sends it to the fltk::focus() widget. If that widget's handle() returns 0, it will also send the keystroke to all parents of that widget (this is mostly for keyboard navigation to work). If all of them return 0, or the fltk::focus() is null, then it will try sending a SHORTCUT event to every single widget inside the same window as the focus until one of them returns non-zero. In most cases widgets will call Widget::test_shortcut() to see if the keystroke is registered here (many widgets will also directly test the key to see if it is something they are interested in).

References find().

bool Widget::remove_shortcut ( unsigned  key  ) 

Delete a shortcut assignment. Returns true if it actually existed.

void Widget::remove_shortcuts (  ) 

Remove all shortcuts for the widget. This is automatically done by the Widget destructor.

unsigned Widget::label_shortcut (  )  const

Returns a value that can be passed to add_shortcut() so that this widget has a real shortcut assignment to match any &x in it's label(). The returned value is ACCELERATOR|c where c is the character after the first '&' in the label (except '&&' is ignored), or zero if there isn't any '&' sign or if flag(RAW_LABEL) is on.

References fltk::ACCELERATOR, flag(), and fltk::RAW_LABEL.

bool Widget::test_label_shortcut (  )  const

Test to see if the current KEY or SHORTCUT event matches a shortcut specified with &x in the label.

This will match if the character in the label() after a '&' matches event_text()[0]. Case is ignored. The caller may want to check if ACCELERATOR or some other shift key is held down before calling this so that plain keys do not do anything, and should certainly make sure no other widgets want the shortcut.

This is ignored if flag(RAW_LABEL) is on (which stops the &x from printing as an underscore. The sequence "&&" is ignored as well because that is used to print a plain '&' in the label.

References fltk::CTRL, fltk::event_state(), fltk::event_text(), flag(), and fltk::RAW_LABEL.

Referenced by test_shortcut().

bool Widget::test_shortcut (  )  const

Same as test_shortcut(true)

Referenced by fltk::Menu::handle_shortcut().

bool Widget::test_shortcut ( bool  test_label  )  const

Returns true if the current event matches one of the assignements made with add_shortcut(), or if test_label is true and test_label_shortcut() returns true. Normally a widget calls this in response to a SHORTCUT event to see if the shortcut key is assigned to it.

References test_label_shortcut().

void Widget::callback ( fltk::Callback *  c,
void *  p 
) [inline]

void Widget::image(Image*) Sets the image. The image is drawn as part of the label, usually to the left of the text. This is designed for icons on menu items. If you want to replace the entire background of the widget with a picture you should set box() instead. Notice that you can also get images into labels by putting '@' commands into the label().

void Widget::tooltip(const char*) Set the string used as the pop-up tooltip. The pointer to the passed string is stored, it is not copied! Passing null indicates that the tooltip of the parent() should be used (or no tooltip if no parent has one). If you want to disable the tooltip but let the parent have one, set this tooltip to "".

Putting '@' commands in to bring up Symbol objects will allow a lot of interesting things to be put into the tooltip.

Each widget has a single callback. You can set it or examine it with these methods. The callback is called with the widget as the first argument and the void* as the second argument. It is called in response to user events, but exactly whe depends on the widget. For instance a button calls it when the button is released.

void Widget::callback ( Callback *  c  )  [inline]

For convenience you can also define the callback as taking only the Widget as an argument. This is implemented by casting this to a fltk::Callback and may not be portable to some machines.

void Widget::callback ( fltk::Callback1 *  c,
long  p = 0 
) [inline]

For convenience you can also define the callback as taking a long integer argument. This is implemented by casting the function to a fltk::Callback and casting the long to a void* and may not be portable to some machines.

void Widget::user_data ( void *  v  )  [inline]

Set the second argument to the callback.

void Widget::argument ( long  v  )  [inline]

Sets the second argument to the callback to a number. This is done by casting the long to a void*.

void Widget::when ( uchar  i  )  [inline]

Flags indicating when to do the callback(). 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 following constants can be used, their exact meaning depends on the widget's implementation:

  • fltk::WHEN_NEVER - Never call the callback (0).
  • fltk::WHEN_CHANGED - Do the callback each time the widget's value is changed by the user (many callbacks may be done as the user drags the mouse)
  • fltk::WHEN_RELEASE - Each keystroke that modifies the value, or when the mouse is released and the value has changed, causes the callback (some widgets do not implement this and act like fltk::WHEN_CHANGED)
  • fltk::WHEN_RELEASE_ALWAYS - Each recognized keystroke and the mouse being released will cause the callback, even if the value did not change. (some widgets do not implement this and act like fltk::WHEN_RELEASE)
  • fltk::WHEN_ENTER_KEY - Do the callback when the user presses the ENTER key and the value has chagned (used by fltk::Input and fltk::Browser.
  • fltk::WHEN_ENTER_KEY_ALWAYS - Do the callback when the user presses the ENTER key, even if the value has not changed. -fltkWHEN_ENTER_KEY_CHANGED - Do the callback when the user presses the ENTER key and each time the value changes.

void Widget::default_callback ( Widget w,
void *   
) [static]

This is the initial value for callback(). It does set_changed() on the widget, thus recording the fact that the callback was done. Do not set the callback to zero, use this if you want no action.

Reimplemented in fltk::Menu.

References set_changed().

Referenced by Widget().

void Widget::do_callback (  )  [inline]

void Widget::do_callback ( Widget o,
void *  arg = 0 
) [inline]

You can also call the callback function with arbitrary arguments.

References fltk::arg().

void Widget::do_callback ( Widget o,
long  arg 
) [inline]

You can also call the callback function with arbitrary arguments.

bool Widget::contains ( const 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.

References parent_.

Referenced by fltk::belowmouse(), fltk::Window::child_of(), fltk::focus(), fltk::handle(), fltk::TabGroup::selected_child(), send(), fltk::Browser::set_focus(), take_focus(), and throw_focus().

bool Widget::pushed (  )  const

bool Widget::takesevents() const This is the same as (active() && visible() && !output()) but faster. send() uses this to decide whether or not to call handle() for most events.

bool Widget::click_to_focus() const If true then clicking on this widget will give it the focus (the handle() method must also return non-zero for fltk::PUSH and for fltk::FOCUS events).

By default fltk only turns this on on certain widgets such as fltk::Input. Turning this on on all widgets will make the user interface match Windows more closely.

bool Widget::tab_to_focus() const If true then this widget can be given focus by keyboard navigation. (the handle() method must also return non-zero for fltk::FOCUS events).

Turning this off with clear_tab_to_focus() will also turn off the click_to_focus() flag. This is for compatability in case we change the default to a more Windows-like style where all widgets get the focus on clicks.

For historical reasons this flag is true on many more widgets than it should be, and FLTK relies on handle() returing 0 for FOCUS. This may change in the future so that more widgets have this flag off.

bool Widget::changed() const

The default callback() turns this flag on. This can be used to find what widgets have had their value changed by the user, for instance 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.

bool Widget::value() const A true/false flag used by fltk::Button to indicate the current state and by "parent" items in a hierarchial fltk::Browser to indicate if they are open. Many widgets will draw pushed-in or otherwise indicate that this flag is on.

bool Widget::selected() const A true/false flag used to mark widgets currently selected in fltk::Menu and fltk::Browser widgets. Some widgets will draw with much different colors if this is on.

Returns true if this is equal to fltk::pushed(), meaning it has responded to an fltk::PUSH event and the mouse is still held down. Using this function avoids the need to include the <fltk/Fl.h> header file.

Referenced by fltk::Input::draw(), fltk::Valuator::handle_drag(), fltk::Valuator::handle_release(), and send().

bool Widget::focused (  )  const

Returns true if this is equal to fltk::focus(), meaning it has the keyboard focus and fltk::KEY events will be sent to this widget. Using this function avoids the need to include the <fltk/Fl.h> header file.

References fltk::focus().

Referenced by fltk::Input::draw(), fltk::Choice::draw(), fltk::NumericInput::handle(), fltk::Input::handle(), fltk::TabGroup::selected_child(), and take_focus().

bool Widget::belowmouse (  )  const

Returns true if this is equal to fltk::belowmouse(), meaning it has the keyboard focus and fltk::MOVE or fltk::PUSH events will be sent to this widget. Using this function avoids the need to include the <fltk/Fl.h> header file.

Referenced by handle(), fltk::Input::handle(), and send().

Flags Widget::flags (  )  const [inline]

Each Widget, and most drawing functions, take a bitmask of flags that indicate the current state and exactly how to draw things. See <fltk/Flags.h> for values. This is for copying the flag values, use flag(c) to test them.

Referenced by fltk::CreatedWindow::create(), fltk::PopupMenu::draw(), fltk::Item::draw(), fltk::Input::draw(), fltk::Choice::draw(), fltk::Button::draw(), fltk::Menu::draw_in(), draw_label(), fltk::Group::draw_outside_label(), fltk::Tooltip::layout(), fltk::Group::layout(), measure_label(), redraw_label(), resize(), and fltk::Window::show().

void Widget::flags ( Flags  f  )  [inline]

Replace flags(). This is for constructors, don't use it elsewhere.

void Widget::set_flag ( unsigned  f  )  [inline]

void Widget::clear_flag ( unsigned  f  )  [inline]

void Widget::invert_flag ( unsigned  f  )  [inline]

Flip the result of flag(f) if f is a single bit. If you or together bits it will flip them all.

Referenced by fltk::Menu::handle_shortcut(), and fltk::Menu::popup().

void Widget::set_flag ( unsigned  f,
bool  b 
) [inline]

Make flag(f) return b. Same as b ? set_flag(f) : clear_flag(f).

bool Widget::flag ( unsigned  f  )  const [inline]

bool Widget::any_of ( unsigned  f  )  const [inline]

Returns true if any of the bits in f are on. Actually this is the same function as flag(f) but using this may make the code more readable.

Referenced by active_r(), fltk::Choice::draw(), and fltk::Window::show().

bool Widget::all_of ( unsigned  f  )  const [inline]

Returns true if all of the bits in f are on. f should be several bits or'd together, otherwise this is the same as flag(f).

bool Widget::state (  )  const [inline]

Widgets have space in them to store a single true/false value (put into the STATE bit of flags()). This is used by buttons and checkmarks and radio menu items.

References fltk::STATE.

Referenced by fltk::Button::draw(), fltk::Window::exec(), and fltk::Item::handle().

bool Widget::state ( bool  v  ) 

Change the state(). Also calls clear_changed(). If the state is different, redraw(DAMAGE_VALUE) is called and true is returned. If the state is the same then false is returned and the widget is not redrawn.

References fltk::DAMAGE_VALUE, redraw(), and fltk::STATE.

bool Widget::set (  )  [inline]

Same as state(true). If you know the widget will already be redrawn, or it is not displayed, it is faster to call the inline set_flag(STATE) function.

Referenced by resize().

bool Widget::clear (  )  [inline]

Same as state(false). If you know the widget will already be redrawn, or it is not displayed, it is faster to call the inline clear_flag(STATE) function.

Reimplemented in fltk::Group.

Referenced by setonly().

void Widget::setonly (  ) 

Calls set() on this widget and calls clear() on all adjacent widgets in the same parent Group that have the type() set to RADIO.

References fltk::Group::child(), fltk::Group::children(), clear(), fltk::Group::find(), parent(), and type().

Referenced by fltk::Menu::popup().

bool Widget::visible_r (  )  const

bool Widget::visible() const Returns true if the widget is visible (flag(INVISIBLE) is false)

Returns true if the widget and all of its parents are visible. Only if this is true can the user see the widget.

Referenced by hide(), fltk::Group::insert(), fltk::GlWindow::mode(), fltk::Group::remove(), and show().

void Widget::show (  ) 

If visible() is false, turn it on. If visible_r() is then true, send() a fltk::SHOW event.

Reimplemented in fltk::Window.

References clear_flag(), handle(), fltk::INVISIBLE, redraw(), redraw_label(), relayout(), fltk::SHOW, and visible_r().

Referenced by fltk::TabGroup::selected_child(), fltk::WizardGroup::value(), and fltk::TabGroup::value().

void Widget::hide (  ) 

bool Widget::active (  )  const [inline]

Returns true if deactivate() has not been called, or activate() has been called since then.

Parents may also be deactivated, in which case this widget will not get events even if this is true. You can test for this with !active_r().

References fltk::INACTIVE.

Referenced by activate(), fltk::Menu::handle_shortcut(), fltk::Group::insert(), redraw_highlight(), and send().

bool Widget::active_r (  )  const

Returns true if active() is true for this and all parent widgets. This is actually the INACTIVE_R bit in flags(), fltk keeps this up to date as widgets are deactivated and/or added to inactive parents.

References any_of(), fltk::INACTIVE, and fltk::INACTIVE_R.

Referenced by activate(), deactivate(), and fltk::Group::insert().

void Widget::activate (  ) 

void Widget::deactivate (  ) 

bool Widget::output (  )  const [inline]

This flag is similar to !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.

Set or clear this flag with set_output() and clear_output().

References fltk::OUTPUT.

bool Widget::horizontal (  )  const [inline]

Return true if this widget has a horizontal orientation and fltk::Pack will position it against the top or bottom edge. This is the default.

References fltk::LAYOUT_VERTICAL.

Referenced by fltk::Menu::draw_in(), fltk::Menu::find_selected(), fltk::Menu::get_location(), fltk::Menu::layout_in(), and fltk::Menu::try_popup().

bool Widget::vertical (  )  const [inline]

Same as !horizontal().

References fltk::LAYOUT_VERTICAL.

Referenced by fltk::Scrollbar::value().

void Widget::set_horizontal (  )  [inline]

Undoes set_vertical() and makes horizontal() return true. This will affect how a surrounding fltk::Pack (or similar group) will place the widget, but you must call relayout() to indicate that this must be recalculated.

References fltk::LAYOUT_VERTICAL.

void Widget::set_vertical (  )  [inline]

Makes vertical() return true. This will affect how a surrounding fltk::Pack (or similar group) will place the widget, but you must call relayout() to indicate that this must be recalculated.

Some widgets classes such as fltk::MenuBar or fltk::Slider will draw differently if this is turned on, in a vertical arrangement.

References fltk::LAYOUT_VERTICAL.

Referenced by fltk::Browser::Browser().

bool Widget::take_focus (  ) 

Tries to make this widget be the keyboard focus widget, by first sending it an fltk::FOCUS event, and if it returns non-zero, setting fltk::focus() to this widget. You should use this method to assign the focus to a widget. Returns true if the widget accepted the focus.

On current systems fltk does not force the window system to set the focus. If the window does not have focus it will usually switch back to the previous window when the user types a key.

References contains(), fltk::focus(), fltk::FOCUS, focused(), and handle().

Referenced by activate(), fltk::Input::handle(), fltk::Group::handle(), fltk::TabGroup::selected_child(), send(), and fltk::Browser::set_focus().

void Widget::throw_focus (  ) 

This function is called by ~Widget() and by deactivate() and by hide(). It indicates that the widget does not want to receive any more events, and also removes all global variables that point at the widget (not just the fltk::focus(), but the fltk::belowmouse(), fltk::modal(), and some internal pointers). Unlike older versions of fltk, no events (i.e. fltk::LEAVE or fltk::UNFOCUS) are sent to the widget.

References fltk::belowmouse(), clear_flag(), contains(), fltk::Group::current(), fltk::Tooltip::current_widget(), fltk::exit_modal(), fltk::Window::first(), fltk::FOCUSED, fltk::HIGHLIGHT, and fltk::pushed().

Referenced by deactivate(), fltk::Window::destroy(), hide(), send(), and ~Widget().

void Widget::redraw (  ) 

void Widget::redraw ( uchar  flags  ) 

Indicates that draw() should be called, and turns on the given bits in damage(). At least these bits, and possibly others, will still be on when draw() is called.

References fltk::damage(), fltk::DAMAGE_CHILD, and parent().

void Widget::redraw_label (  ) 

Indicates that the label() should be redrawn. This does nothing if there is no label. If it is an outside label (see align()) then the parent() is told to redraw it. Otherwise redraw() is called.

References fltk::ALIGN_INSIDE, fltk::DAMAGE_CHILD_LABEL, flag(), flags(), redraw(), and window().

Referenced by activate(), deactivate(), and show().

void Widget::redraw_highlight (  ) 

Causes a redraw if highlighting changes.

Calls redraw(DAMAGE_HIGHLIGHT) if this widget has a non-zero highlight_color(). This is designed to be called in response to ENTER and EXIT events and not redraw the widget if the no highlight color is being used.

References active(), fltk::DAMAGE_HIGHLIGHT, fltk::NO_BOX, and redraw().

Referenced by handle(), and fltk::Valuator::handle().

void Widget::redraw ( const Rectangle r1  ) 

Indicates that a rectangular region is damaged. draw() will be called later with damage() set to fltk::DAMAGE_ALL|fltkDAMAGE_EXPOSE and with FLTK's clipping set to at least the given rectangle. Normally this is called more than once and the clip region will be the union of all these calls. In addition damage from the operating system (ie from overlapping windows) will increase the clipping region.

This can be used to get speed up and improve complex displays of many overlapping and changing objects. Even if you do nothing else about it, it is usually faster to do a drawing operation that is clipped than one that appears, so display will be faster. You can also check to see if anything by testing fltk::not_clipped(x,y,w,h) or fltk::clip_box(...) and skipping unnecessary drawing calls completely. Also if your normal drawing causes blinking (due to overlapping objects) this can make the display look much better by limiting the blinking to the small area that is actually changing.

References fltk::Rectangle::b(), fltk::DAMAGE_EXPOSE, fltk::Rectangle::empty(), fltk::CreatedWindow::expose(), find(), fltk::Rectangle::h(), is_window(), fltk::Rectangle::move(), parent(), fltk::Rectangle::r(), fltk::Rectangle::set_b(), fltk::Rectangle::set_r(), fltk::Rectangle::set_x(), fltk::Rectangle::set_y(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

uchar Widget::damage (  )  const [inline]

void Widget::set_damage ( uchar  c  )  [inline]

Directly change the value returned by damage(). Note that this replaces the value, it does not turn bits on. Use redraw() to turn bits on.

Referenced by fltk::Group::draw_child(), fltk::Window::erase_overlay(), fltk::Window::flush(), fltk::Window::redraw_overlay(), and fltk::Group::update_child().

void Widget::relayout (  ) 

uchar Widget::layout_damage (  )  const [inline]

The 'or' of all the calls to relayout() or resize() done since the last time layout() was called.

A typical layout function does not care about the widget moving, an easy way to skip it is as follows:

MyClass::layout() {
  if (!(layout_damage() & ~LAYOUT_XY)) return;
  do_expensive_layout();
  redraw();
}

Referenced by fltk::Browser::goto_index(), fltk::Browser::goto_position(), fltk::handle(), fltk::Menu::layout(), fltk::Group::layout(), fltk::Browser::make_item_visible(), and fltk::Window::system_layout().

void Widget::layout_damage ( uchar  c  )  [inline]

Directly change the value returned by layout_damage().

void Widget::add_timeout ( float  time  ) 

Call handle(TIMEOUT) at the given time in the future. This will happen exactly once. To make it happen repeatedly, call repeat_timeout() from inside handle(TIMEOUT).

Referenced by fltk::Tooltip::enter(), fltk::Tooltip::exit(), and fltk::Input::handle().

void Widget::repeat_timeout ( float  time  ) 

Call handle(TIMEOUT) at the given time interval since the last timeout. This will produce much more accurate time intervals than add_timeout().

void Widget::remove_timeout (  ) 

Cancel any and all pending handle(TIMEOUT) callbacks.

Referenced by fltk::Tooltip::enter(), fltk::Tooltip::exit(), fltk::Input::handle(), and ~Widget().

void Widget::make_current (  )  const

Make the fltk drawing functions draw into this widget. The transformation is set so 0,0 is at the upper-left corner of the widget and 1 unit equals one pixel. The transformation stack is empied, and all other graphics state is left in unknown settings.

The equivalent of this is already done before a Widget::draw() function is called. The only reason to call this is for incremental updating of widgets without using redraw(). This will crash if the widget is not in a currently shown() window. Also this may not work correctly for double-buffered windows.

References find(), fltk::CreatedWindow::frontbuffer, fltk::Rectangle::h(), is_window(), parent(), fltk::translate(), fltk::Rectangle::w(), window(), fltk::Rectangle::x(), fltk::CreatedWindow::xid, and fltk::Rectangle::y().

void Widget::draw_background (  )  const

Draw what would be in the area of the widget if the widget was not there. By calling this in draw(), a widgets can redraw as though they are partially transparent, or more complicated shapes than rectangles. Note that only parent widgets are drawn, not underlapping ones.

If DAMAGE_EXPOSE is on in damage() then the window (or at least some region of it) is being completely redrawn. Normally FLTK will have already drawn the background, so to avoid redundant drawing this will return immediatly without drawing anything. However FLTK may be compiled with USE_CLIPOUT (an option to reduce blinking in single-buffered windows) and in that case the widget must draw any visible background. In this case this function always draws the background.

References damage(), fltk::DAMAGE_EXPOSE, draw_background(), draw_box(), draw_label(), fltk::Rectangle::h(), parent(), fltk::pop_clip(), fltk::pop_matrix(), fltk::push_clip(), fltk::push_matrix(), fltk::translate(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

Referenced by draw(), fltk::PopupMenu::draw(), fltk::Button::draw(), and draw_background().

void Widget::draw_frame (  )  const

Same as draw_box() but draws only the boundary of the box() by calling it's draw routine with the INVISIBLE flag set. This only works for rectangular boxes. This is useful for avoiding blinking during update for widgets that erase their contents as part of redrawing them anyway (ie anything displaying text).

References fltk::Symbol::draw(), fltk::drawstyle(), fltk::Rectangle::h(), fltk::INVISIBLE, fltk::OUTPUT, fltk::Rectangle::Rectangle(), fltk::setdrawflags(), and fltk::Rectangle::w().

Referenced by fltk::Input::draw(), and fltk::Choice::draw().

void Widget::draw_box (  )  const

Draw the widget's box() such that it fills the entire area of the widget. If the box is not rectangluar, this also draws the area of the parent widget that is exposed.

This also does drawstyle(style(),flags()&~OUTPUT) and thus the colors and font are set up for drawing text in the widget.

References fltk::Rectangle::h(), fltk::Rectangle::Rectangle(), and fltk::Rectangle::w().

Referenced by draw(), and draw_background().

void Widget::draw_label (  )  const

Calls draw_label() with the area inside the box() and with the alignment stored in flags(). The labelfont() and labelcolor() are used. For historic reasons if the OUTPUT flag is on then the textfont() and textcolor() are used.

References fltk::ALIGN_INSIDE, fltk::drawstyle(), flags(), fltk::Rectangle::h(), fltk::Symbol::inset(), fltk::OUTPUT, fltk::Rectangle::r(), and fltk::Rectangle::w().

Referenced by draw(), fltk::PopupMenu::draw(), fltk::Item::draw(), fltk::Button::draw(), and draw_background().

void Widget::draw_label ( const Rectangle ir,
Flags  flags 
) const

Draws labels inside the widget using the current font and color settings. XYWH is the bounding box to fit the label into, flags is used to align in that box.

If the flags contain any ALIGN flags and don't have ALIGN_INSIDE then the label() is not drawn. Instead the image() is drawn to fill the box (most image() types will center the picture).

Otherwise it tries to put both the label() and the image() into the box in a nice way. The image() is put against the side that any ALIGN flags say, and then the label() is put next to that.

References fltk::ALIGN_BOTTOM, fltk::ALIGN_CENTER, fltk::ALIGN_CLIP, fltk::ALIGN_INSIDE, fltk::ALIGN_LEFT, fltk::ALIGN_POSITIONMASK, fltk::ALIGN_RIGHT, fltk::ALIGN_TOP, fltk::Rectangle::b(), fltk::Symbol::draw(), fltk::Rectangle::h(), fltk::measure(), fltk::Symbol::measure(), fltk::Rectangle::move_r(), fltk::Rectangle::move_x(), fltk::Rectangle::move_y(), fltk::pop_clip(), fltk::push_clip(), fltk::Rectangle::r(), fltk::RESIZE_FILL, fltk::RESIZE_FIT, fltk::Rectangle::set_b(), fltk::Rectangle::set_r(), fltk::Rectangle::set_x(), fltk::Rectangle::set_y(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Widget::draw_glyph ( int  which,
const Rectangle rectangle 
) const

Changes the lower 5 bits (the "align" bits) of drawflags() to be the value of which, then draws the glyph(), then put drawflags() back. This is a convienence function for widgets that actually need to draw several different glyphs. They have to define a glyph whicy draws a different image depending on the align flags. This allows the style to be changed by replacing the glyph function, though the replacement should draw the same things for the align flags, perhaps by being an fltk::MultiImage.

References fltk::ALIGN_MASK, and fltk::Symbol::draw().

Referenced by fltk::Slider::draw(), fltk::PopupMenu::draw(), fltk::Item::draw(), fltk::Choice::draw(), and fltk::Menu::draw_in().

void Widget::cursor ( Cursor *  c  )  const

Change the cursor being displayed on the screen. A widget should do this in response to fltk::ENTER and fltk::MOVE events. FLTK will change it back to fltk::CURSOR_DEFAULT if the mouse is moved outside this widget, unless another widget calls this.

On X you can mess with the colors by setting the Color variables fl_cursor_fg and fl_cursor_bg to the colors you want, before calling this.

Referenced by fltk::dnd(), and fltk::WizardGroup::value().

void Widget::measure_label ( int &  w,
int &  h 
) const

Replace w and h with the size of the area the label will take up. This is the size of the draw_outside_label() and thus does not include any image() and always uses the labelfont even if the OUTPUT flag is set.

If the ALIGN_WRAP flag is set this chooses the rather arbitrary width of 300 to wrap the label at. Ideally this should have been passed in w but is not for back-compatability reasons.

References flags(), fltk::measure(), and fltk::setfont().

Referenced by fltk::StatusBarGroup::update_box().

void Widget::add ( const AssociationType at,
void *  data 
)

Add an association to a this widget. The associated data is of the given association type. The associated data must not be NULL. NULL is simply not added as association.

void Widget::set ( const AssociationType at,
void *  data 
)

Removes all associations of the given assiciation type from this widget and, if data is not NULL, add the given data pointer as a new association.

The removed data is freed by calling the destroy method of the association type.

void * Widget::get ( const AssociationType at  )  const

Returns the first association of the given type that is connected with this widget. Returns NULL if none.

void * Widget::foreach ( const AssociationType at,
AssociationFunctor fkt 
) const

Call the functor for each piece of data of the give AssociationType. This is a wrapper for foreach(&at, this, fkt).

bool Widget::remove ( const AssociationType at,
void *  data 
)

tries to remove one association from a widget, if it exists it is removed and the function returns true, if such an association doesn't exist false is returned and nothing is changed

bool Widget::find ( const AssociationType at,
void *  data 
) const

tries to find an association of this type with the given data if found the function returns true, else false

Referenced by add_shortcut(), make_current(), and redraw().


Member Data Documentation

This is the value of glyph() in the Widget::default_style. It is an internal symbol called "@widget;". It draws a number of small buttons with arrows on them. The direction of the arrows are determined by the align values in fltk::setflags():

Only one arrow direction at a time is currently supported. This may be improved in the future.


Wed Jun 17 08:53:25 2009. FLTK ©2007 Bill Spitzak and others.
Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.