fltk::Widget

fltk::Widget Class Reference

Inheritance diagram for fltk::Widget:

[legend]Collaboration diagram for fltk::Widget:


Public Member Functions
	Widget (int, int, int, int, const char *=0)
virtual	~Widget ()
virtual void	draw ()
virtual int	handle (int)
int	send (int event)
virtual void	layout ()
Group *	parent () const
Window *	window () const
uchar	type () const
bool	is_group () const
bool	is_window () const
bool	resize (int x, int y, int w, int h)
bool	position (int x, int y)
bool	resize (int w, int h)
void	get_absolute_rect (Rectangle *rect) const
void	label (const char *a)
void	copy_label (const char *a)
const Symbol *	image (Flags flags=NO_FLAGS) const
void	image (const Symbol *a, Flags flags=NO_FLAGS)
void	image (const Symbol &a, Flags flags=NO_FLAGS)
void	image (const Symbol noflags, const Symbol disabled, const Symbol belowmouse=0, const Symbol pushedopen=0)
void	callback (Callback c, void p)
void	callback (Callback *c)
void	callback (Callback1 *c, long p=0)
void	user_data (void *v)
void	argument (long v)
void	when (uchar i)
void	do_callback ()
void	do_callback (Widget o, void arg=0)
void	do_callback (Widget *o, long arg)
bool	contains (const Widget *) const
bool	pushed () const
bool	focused () const
bool	belowmouse () const
Flags	flags () const
void	setonly ()
bool	visible_r () const
void	show ()
void	hide ()
bool	active () const
bool	active_r () const
void	activate ()
void	deactivate ()
bool	output () const
bool	horizontal () const
bool	vertical () const
void	set_horizontal ()
void	set_vertical ()
void	redraw ()
void	redraw (uchar c)
void	redraw_label ()
void	redraw_highlight ()
void	redraw (const Rectangle &)
uchar	damage () const
void	set_damage (uchar c)
void	relayout ()
uchar	layout_damage () const
void	layout_damage (uchar c)
void	add_timeout (float)
void	repeat_timeout (float)
void	remove_timeout ()
void	draw_background () const
Static Public Member Functions
static void	default_callback (Widget , void )

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.

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

Member Function Documentation

void Widget::activate ( )

If active() is false, this turns it on. If active_r() is now true send() an fltk::ACTIVATE event.

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(). Or inside draw() events you can test flags()&INACTIVE_R.

bool Widget::active_r ( ) const

Returns whether the widget is active. This is true if active() is true for this and all parent widgets. An inactive widget does not get any events, but it does get redrawn.

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

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.

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::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::Callback * c,

void * p

) [inline]

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.

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.

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.
Reimplemented in fltk::Window.

void Widget::deactivate ( )

If active() is true, this turns it off. If active_r() was true send() an fltk::DEACTIVATE event.

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.

void Widget::do_callback ( Widget * o,

long arg

) [inline]

You can also call the callback function with arbitrary arguments.

void Widget::do_callback ( Widget * o,

void * arg = 0

) [inline]

You can also call the callback function with arbitrary arguments.

void Widget::do_callback ( ) [inline]

You can cause a widget to do its callback at any time. The callback function is called with this and user_data() as arguments.

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.

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 flags for values.

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.

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.

void Widget::hide ( )

If visible() is true, turn it off. If visible_r() was true then send() a fltk::HIDE event, and redraw() the parent if necessary.
Reimplemented in fltk::DockWindow.

void Widget::image ( const Symbol * noflags,

const Symbol * disabled,

const Symbol * belowmouse = 0,

const Symbol * pushedopen = 0

)

get the image relative to a particular event/state convenient way to set several images at once

void fltk::Widget::image ( const Symbol & a,

Flags flags = NO_FLAGS

) [inline]

set the image Symbol according to the desired state (NO_FLAGS, INACTIVE, BELOWMOUSE, PUSHED or OPENED)

void Widget::image ( const Symbol * a,

Flags flags = NO_FLAGS

)

set the image Symbol according to the desired state (NO_FLAGS, INACTIVE, BELOWMOUSE, PUSHED or OPENED)

const Symbol * Widget::image ( Flags flags = NO_FLAGS ) const

get the image Symbol according to the desired state (NO_FLAGS, INACTIVE, BELOWMOUSE, PUSHED or OPENED)

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

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.

void Widget::label ( const char * s )

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, and fltk::ToolWindow.

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

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

Returns a pointer to the parent widget. Usually this is a fltk::Group or fltk::Window. Returns NULL if none.

bool Widget::pushed ( ) const

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.

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.

void Widget::setonly ( )

sets the VALUE to only one on the widget, other widgets in the same group get VALUE cleared

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.

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.
Reimplemented in fltk::GripperBar.

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

Set the second argument to the callback.

bool Widget::visible_r ( ) const

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

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.

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.

fltk::Widget Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation