NAME

FLTK::Widget - Base class for all widgets in the Fast Light Toolkit

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

Functions

DAMAGE_ALL

DAMAGE_ALL( );

This bit is set by redraw() and indicates that all of the widget (but not "holes" where the background shows through) needs to be redraw.

DAMAGE_CHILD

DAMAGE_CHILD( );

A child of this group widget needs to be redrawn (non-group widgets can use this bit for their own purposes).

DAMAGE_CHILD_LABEL

DAMAGE_CHILD_LABEL( );

An outside label of this widget needs to be redrawn. This is handled (and this bit is cleared) by the parent group.

Because anti-aliasing cannot be redrawn atop itself, this is not used anymore. Instead if an outside label needs to change the entire parent widget is redrawn.

DAMAGE_CONTENTS

DAMAGE_CONTENTS( );

Same as FLTK::DAMAGE_EXPOSE but if FLTK::DAMAGE_ALL is off a widget can use this for it's own purposes.

DAMAGE_EXPOSE

DAMAGE_EXPOSE( );

Damage caused by damage() or by expose events from the operating system. If this and FLTK::DAMAGE_ALL is on the widget should draw every pixel inside it's region.

DAMAGE_HIGHLIGHT

DAMAGE_HIGHLIGHT( );

A widget may use this to indicate that the mouse has entered/exited part of the widget.

DAMAGE_OVERLAY

DAMAGE_OVERLAY( );

Same value as FLTK::DAMAGE_SCROLL.

DAMAGE_PUSHED

DAMAGE_PUSHED( );

A widget may use this to indicate that the user has pushed or released a button.

DAMAGE_SCROLL

DAMAGE_SCROLL( );

A widget may use this to indicate that the displayed data has scrolled moved horizontally and/or vertically.

DAMAGE_VALUE

DAMAGE_VALUE( );

A widget may use this to indicate that the displayed value has changed.

GROUP_TYPE

GROUP_TYPE( );

RADIO

RADIO( );

RESREVED_TYPE

my $type = $widget->RESREVED_TYPE( );

TOGGLE

TOGGLE( );

WHEN_CHANGED

my $when = $widget->WHEN_CHANGED( );

WHEN_ENTER_KEY

my $when = $widget->WHEN_ENTER_KEY( );

WHEN_ENTER_KEY_ALWAYS

my $when = $widget->WHEN_ENTER_KEY_ALWAYS( );

WHEN_ENTER_KEY_CHANGED

my $when = $widget->WHEN_ENTER_KEY_CHANGED( );

WHEN_NEVER

my $when = $widget->WHEN_NEVER( );

WHEN_NOT_CHANGED

my $when = $widget->WHEN_NOT_CHANGED( );

WHEN_RELEASE

my $when = $widget->WHEN_RELEASE( );

WHEN_RELEASE_ALWAYS

my $when = $widget->WHEN_RELEASE_ALWAYS( );

WINDOW_TYPE

WINDOW_TYPE( );

activate

$widget->activate( );

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

$widget->activate( $b );

Toggle between activate() and deactivate().

active

my $ret = $widget->active( );

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

active_r

my $ret = $widget->active_r( );

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.

add_shortcut

my $ret = $widget->add_shortcut( $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. You can examine the assignments with FLTK::list_shortcuts().

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. Examples:

FLTK::CTRL + 'a'

FLTK::ACCELERATOR + FLTK::CTRL + 'A'

just 'a'

FLTK::SHIFT + '#'

FLTK::SHIFT + FLTK::UpKey See FLTK::list_matching_shortcuts() for the exact rules for how a KEY event is matched to a shortcut assignment. Case is ignored (the lower-case version of any letter is actually put in the table).

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

add_timeout

$widget->add_timeout( $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).

align

$widget->align( $flags );

Forces the values of all the FLTK::ALIGN_* flags to the passed value. This determines how the label is printed next to or inside the widget. The default value is FLTK::ALIGN_CENTER, which centers the label. The value can be any of the ALIGN flags or'd together.

my $flags = $widget->align( );

all_of

my $on = $widget->all_of( $f );

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

any_of

my $on = $widget->any_of( $f );

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.

argument

$widget->argument( $arg );

Set the second argument to the callback to a number.

See Also: callback, user_data.

my $data = $widget->argument( );

Returns the second argument to the callback.

belowmouse

my $ret = $widget->belowmouse( );

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.

box

my $b = $widget->box( );

The type of box to draw around the outer edge of the widget (for the majority of widgets, some classes ignore this or use it to draw only text fields inside the widget). The default is FLTK::DOWN_BOX.

$widget->box( $b );

Sets the type of box to draw around the outer edge of widget.

buttonbox

my $bb = $widget->buttonbox( );

The type of box to draw buttons internal the widget (notice that FLTK::Button uses box, however). The default is FLTK::UP_BOX.

$widget->buttonbox( $bb );

Returns the type of box to draw buttions internal the widget.

buttoncolor

my $color = $widget->buttoncolor( );

Color used when drawing buttons. Default is FLTK::GRAY75.

$widget->buttoncolor( $color );

callback

$widget->callback( \&coderef, $args );

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 any data in args as the second argument. It is called in response to user events, but exactly when depends on the widget. For instance a button calls it when the button is released.

NOTE: To make use of callbacks, your perl must be recent enough to support weak references.

$widget->callback( \&coderef );

For convenience you can also define the callback as taking only the Widget as an argument.

NOTE: This may not be portable to some machines.

changed

my $ret = $widget->changed( );

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.

clear

my $ret = $widget->clear( );

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.

clear_changed

$widget->clear_changed( );

clear_click_to_focus

$widget->clear_click_to_focus( );

clear_flag

$widget->clear_flag( $f );

Make flag(f) return false by turning off that bit. You can turn off multiple bits by or'ing them toegher.

clear_output

$widget->clear_output( );

clear_selected

$widget->clear_selected( );

clear_tab_to_focus

$widget->clear_tab_to_focus( );

clear_visible

$widget->clear_visible( );

click_to_focus

my $ret = $widget->click_to_focus( );

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.

color

my $color = $widget->color( );

Color of the widgets. The default is FLTK::WHITE. You may think most widgets are gray, but this is because Group and Window have their own Style with this set to FLTK::GRAY75, and also because many parts of widgets are drawn with the buttoncolor().

If you want to change the overall color of all the gray parts of the interface you want to call FLTK::set_background(color) instead, as this will set the entry for FLTK::GRAY75 and also set the "gray ramp" so that the edges of buttons are the same color.

$widget->color( $color );

contains

my $ret = $widget->contains( $child );

Returns a true value if widget child is a child of this widget, or is equal to this widget. Returns a false value if child is undefined.

copy_label

$widget->copy_label( $string );

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 undef will set label() to undef.

copy_style

my $ret = $widget->copy_style( $s );

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.

cursor

$widget->cursor( $c );

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

damage

my $c = $widget->damage( );

The 'or' of all the calls to redraw() done since the last draw(). Cleared to zero after draw() is called.

deactivate

$widget->deactivate( );

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

default_style

my $style = $widget->default_style( );

Get the style

$widget->default_style( $style );

Set the style.

destroy

$widget->destroy( );

Destroy the widget.

do_callback

$widget->do_callback( );

You can cause a widget to do its callback at any time.

$widget->do_callback( $widget, $args );

You can also call the callback function with arbitrary arguments.

draw_background

$widget->draw_background( );

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.

draw_box

$widget->draw_box( );

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.

$widget->draw_box( $rect );

Draw the widget's box() such that it fills the entire area of rect.

draw_frame

$widget->draw_frame( );

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 redrawnig them anyway (ie anything displaying text).

draw_glyph

$widget->draw_glyph( $which, $rect );

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 which 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|FLTK::MultiImage>.

draw_label

$widget->draw_label( );

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.

$widget->draw_label( $ir, $flags );

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.

flag

my $on = $widget->flag( $f );

Returns true if the bit for f is on.

flags

my $f = $widget->flags( );

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.

$widget->flags( $f );

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

focused

my $ret = $widget->focused( );

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.

get_absolute_rect

$widget->get_absolute_rect( $rect );

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

glyph

my $image = $widget->glyph( );

A small image that some Widgets use to draw part of themselves. For instance the FLTK::CheckButton class has this set to a Symbol that draws the white box and the checkmark if VALUE is true.

Im most cases the FLTK::drawflags() are examined to decide between differnt symbols. The default value draws empty squares and arrow buttons if ALIGN flags are on, see Widget::default_glpyh.

$widget->glyph( $image );

Sets a small image that some Widgets use to draw part of themselves.

hide

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

highlight_color

my $color = $widget->highlight_color( );

The color to draw the widget when the mouse is over it (for scrollbars and sliders this is used to color the buttons). Depending on the widget this will either recolor the buttons that are normally colored with buttoncolor(), or will recolor the main area that is normally colored with color().

The default value is zero, which indicates that highlighting is disabled.

$widget->highlight_color( $color );

highlight_textcolor

my $color = $widget->highlight_textcolor( );

Color used to draw the labels or text when the background is drawn in the highlight_color. The default of zero indicates that fltk will choose a contrasting color (either the same as the original color or white or black). I recommend you use the default if possible.

$widget->highlight_textcolor( $color );

horizontal

my $ret = $widget->horizontal( );

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

See also: vertical()

image

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

my $img = $widget->image( );

inside

my $ret = $widget->inside( $parent );

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

invert_flag

$widget->invert_flag( $f );

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

is_group

my $ret = $widget->is_group( );

Returns a true value for subclasses of FLTK::Group.

is_window

my $ret = $widget->is_window( );

Returns a true value for subclasses of FLTK::Window. If this is true, is_group() is also true.

label

$widget->label( $string );

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.

label_shortcut

my $key = $widget->label_shortcut( );

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 ALT|c where c is the character after the first '&' in the label, or zero if there isn't any '&' sign or if flag(RAW_LABEL) is on.

labelcolor

my $color = $widget->labelcolor( );

Color used to draw labels. Default is FLTK::BLACK.

$widget->labelcolor( $color );

labelfont

my $font = $widget->labelfont( );

The font used to draw the label. Default is FLTK::HELVETICA.

$widget->labelfont( $Font );

labelsize

my $size = $widget->labelsize( );

Size of labelfont(). Default is 12.

$widget->labelsize( $size );

labeltype

my $type = $widget->labeltype( );

How to draw the label. This provides things like inset, shadow, and the symbols. FLTK::NORMAL_LABEL.

$widget->labeltype( $type );

layout_damage

my $flags = $widget->layout_damage( );

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:

package MyWidget; # XXX - Untested
{ # ... ISA stuff, etc. ...
    sub layout {
        my ($self) = @_;
        return if !($self->layout_damage() & ~LAYOUT_XY);
        do_expensive_layout( );
        $self->redraw( );
    }
}

$widget->layout_damage( $flag );

Directly change the value returned by layout_damage().

leading

my $size = $widget->leading( );

Extra spacing added between text lines or other things that are stacked vertically. The default is 2. The function FLTK::drawtext() will use the value from Widget::default_style, but text editors and browsers and menus and similar widgets will use the local value.

$widget->leading( $size );

make_current

$widget->make_current( );

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.

measure_label

my @wh = $widget->measure_label( );

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.

new

my $widget = $widget->new( $x, $y, $w, $h, $label );

The default constructor takes a value for x(), y(), w(), and h(), and an optional value for label(). Not that all subclasses provide an identical constructor and may also provide alternative constructors.

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

output

my $ret = $widget->output( );

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

parent

my $group = $widget->parent( );

Returns the parent widget. Usually this is a FLTK::Group or FLTK::Window. Returns undef if this is an orphan widget.

$widget->parent( $group );

Sets the parent.

positon

my $ret = $widget->positon( $x, $y );

Same as resize( X, Y, w(), h() )

pushed

my $ret = $widget->pushed( );

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.

redraw

$widget->redraw( );

Same as redraw(DAMAGE_ALL). This bit is used by most widgets to indicate that they should not attempt any incremental update, and should instead completely draw themselves.

$widget->redraw( $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.

$widget->redraw( $rect );

redraw_highlight

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

redraw_label

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

relayout

$widget->relayout( );

Same as relayout(LAYOUT_DAMAGE), indicates that data inside the widget may have changed, but the size did not change. This flag is also on when the widget is initially created.

$widget->relayout( $flags );

Cause layout() to be called later. Turns on the specified flags in layout_damage(), and turns on LAYOUT_CHILD in all parents of this widget. flags cannot be zero, the maaning of the flags is listed under fltk/layout.h.

remove_shortcut

my $ret = $widget->remove_shortcut( $key );

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

remove_shortcuts

$widget->remove_shortcuts( );

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

remove_timeout

$widget->remove_timeout( );

Cancel any and all pending handle(TIMEOUT) callbacks.

repeat_timeout

$widget->repeat_timeout( $time );

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

resize

my $ret = $widget->resize( $x, $y, $w, $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().

my $ret = $widget->resize( $w, $h );

Same as resize( x(), y(), $W, $H).

scrollbar_align

my $align = $widget->scrollbar_align( );

Where to place scrollbars around a Browser or other scrolling widget. The default is FLTK::ALIGN_RIGHT|FLTK::ALIGN_BOTTOM.

$widget->scrollbar_align( $align );

scrollbar_width

my $width = $widget->scrollbar_width( );

How wide the scrollbars are around a Browser or other scrolling widget. The default is 15.

$widget->scrollbar_width( $width );

selected

my $ret = $widget->selected( );

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.

selection_color

my $color = $widget->selection_color( );

Color drawn behind selected text in inputs, or selected browser or menu items, or lit light buttons. The default is FLTK::WINDOWS_BLUE.

$widget->selection_color( $color );

selection_textcolor

my $color = $widget->selection_textcolor( );

The color to draw text atop the selection_color. The default of zero indicates that fltk will choose a contrasting color (either the same as the original color or white or black). I recommend you use the default if possible.

$widget->selection_textcolor( $color );

send

my $return = $widget->send( $event );

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

It calculates event_x() and event_y() to be relative to the widget. The previous values are restored before this returns.

It makes sure the widget is active and/or visible if the event requres this.

If this is not the FLTK::belowmouse() widget then it changes FLTK::MOVE into FLTK::ENTER and turns FLTK::DND_DRAG into FLTK::DND_ENTER. If this is the FLTK::belowmouse() widget then the opposite conversion is done.

For move, focus, and push events if handle() returns true it sets the FLTK::belowmouse() or FLTK::focus() or FLTK::pushed() widget to reflect this.

set

my $ret = $widget->set( );

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.

set_changed

$widget->set_changed( );

set_click_to_focus

$widget->set_click_to_focus( );

set_damage

$widget->set_damage( $c );

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.

set_flag

$widget->set_flag( $f );

Make flag(f) return true by turning on that bit. You can set more than one by or'ing them together.

$widget->set_flag( $f, $b );

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

set_horizontal

$widget->set_horizontal( );

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.

set_output

$widget->set_output( );

set_tab_to_focus

$widget->set_tab_to_focus( );

set_vertical

$widget->set_vertical( );

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.

set_visible

$widget->set_visible( );

setonly

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

shortcut

my $key = $widget->shortcut( );

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

$widget->shortcut( $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). Return value is intended to indicate if the shortcut changed, but that is nyi.

show

$widget->show( );

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

state

my $value = $widget->state( );

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.

$widget->state( $value );

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.

tab_to_focus

my $ret = $widget->tab_to_focus( );

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.

take_focus

my $ret = $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.

takesevents

my $ret = $widget->takesevents( );

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

test_labe_shortcut

my $ret = $widget->test_labe_shortcut( );

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.

test_shortcut

my $ret = $widget->test_shortcut( );

Same as test_shortcut(true).

my $ret = $widget->test_shortcut( $test_label );

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.

This is done by doing list_matching_shortcuts() and seeing if this widget is in the returned list. If the list is empty and test_label is true, it will return test_label_shortcut().

If the current event matches a different widget "better" than this one, then false is returned. For instance if this widget has 'x' as a shortcut, this will return true if the user types 'X'. But if another widget has 'X' then this will return false. See FLTK::list_matching_shortcuts() for the rules about what ones are "better".

textcolor

my $color = $widget->textcolor( );

Color to draw text inside the widget. Default is black. This is also used by many widgets to control the color when they draw the glyph(), thus it can control the color of checkmarks in FLTK::CheckButton.

$widget->textcolor( $color );

textfont

my $font = $widget->textfont( );

Font to use to draw information inside the widget, such as the text in a text editor or menu or browser. Default is FLTK::HELVETICA.

$widget->textfont( $font );

textsize

my $size = $widget->textsize( );

Size of textfont(). This is also used by many Widgets to control the size they draw the glyph(). Default is 12.

$widget->textsize( $size );

throw_focus

$widget->throw_focus( );

This function is called by the destructor 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.

tooltip

$widget->tooltip( $string );

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.

type

my $ret = $widget->type( );

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

$widget->type( $value );

user_data

$widget->user_data( $args );

Set the second argument to the callback.

See Also: callback, argument.

my $data = $widget->user_data( );

Returns the second argument to the callback.

vertical

my $ret = $widget->vertical( );

Same as !horizontal()

visible

my $ret = $widget->visible( );

Returns true if the widget is visible (flag(INVISIBLE) is false).

visible_r

my $ret = $widget->visible_r( );

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

when

$widget->when( $flag );

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.

FLTK::WHEN_ENTER_KEY_CHANGED

Do the callback when the user presses the ENTER key and each time the value changes.

window

my $win = $widget->window( );

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 undef if none. Note: for an FLTK::Window, this returns the parent window (if any), not this window.

Subclassing Widgets

Blah, blah, blah...

Methods to Override

handle( event )

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

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

License and Legal

Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

cpanm FLTK

perl -MCPAN -e shell
install FLTK