NAME

FLTK::Group - Base class for all container widgets

Description

The FLTK::Group class is the FLTK container widget. It maintains an array of child widgets. These children can themselves be any widget including FLTK::Group, nesting groups allows much more control over layout and resize behavior. Nested groups are also necessary to group radio buttons together.

By default FLTK::Group preserves the positions and sizes of all it's children, they do not move no matter what sizes or other children are added or removed.

Setting resizable() will change the layout behavior so that it responds to resizing by moving or resizing the children to fit. See below for details.

You may want to use an FLTK::Pack or a FLTK::Scroll to get other common layout behavior that can respond to changes in the sizes of child widgets.

The most-used subclass of FLTK::Group is FLTK::Window, all the rules about resizing apply to windows. Setting resizable() on a window will allow the user to resize it. If you want different behavior (such as from FLTK::Pack) for your window you should make the window have that as a single resizable child that fills it.

FLTK::Menu is a subclass and thus all menus and browsers are groups and the items in them are widgets.

Functions

add

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

The widget is removed from its current group (if any) and then added to the end of this group.

add_resizable

$group->add_resizable( $widget );

Adds a widget and sets it as the resizer in one fell swoop.

begin

$group->begin( );

Sets the current group so you can build the widget tree by just constructing the widgets. begin() is exactly the same as $W->current($W).

Don't forget to end() the group or window!

child

my $kid = $group->child( $index );

Returns a child, index >= 0 && index < children(). Range checking is done internally!

children

my $kids = $group->children( );

Returns how many child widgets the group has.

clear

$group->clear( );

Deletes all children from the group and makes it empty. This calls the destructor on all the children.

See remove_all()

current

my $group = $group->current( );

Returns the group being currently built. The Widget constructor automatically does current()->add($widget) if this is not undef. To prevent new widgets from being added to a group, call FLTK::Group::current(0).

$group->current( $group );

Sets the group being currently built.

end

$group->end( );

Exactly the same as $W->current($W->parent()). Any new widgets added to the widget tree will be added to the parent of the group.

find

my $index = $group->find( $widget );

Searches the children for widget, returns the index of widget or of a parent of widget that is a child() of this. Returns children() if the widget is undef or not found.

fix_old_positions

$group->fix_old_positions( );

If this is a Group and not a Window, subtract x() and y() from the position of all children. This will fix the positions of widgets created for fltk1.1 that are inside a group.

focus_index

$group->focus_index( $index );

The index of the widget that contains the focus. You can initialize this before the group is displayed. Changing it while it is displayed does not work, use $widget->take_focus() instead.

For some subclasses such as TabGroup, a negative number indicates that the group itself has the focus. In most cases any illegal value means it will search for any widget that accepts focus.

This is also used by Menu to locate the item selected by the user. See Menu::get_item().

my $index = $group->focus_index( );

Returns the index of the widget currently having focus.

init_sizes

$group->init_sizes( );

Indicate that all the remembered child sizes should be reinitialized.

The group remembers the initial size of itself and all it's children, so that the layout can be restored even if the group is resized so that some children go to zero or negative sizes.

This can produce unwanted behavior if you try to rearrange the child widgets yourself, as the next resize will put them right back where they were initially. Call this to make it forget all the saved sizes and reinitialize them during the next layout().

This is automatically done when any child is added or removed.

insert

my $widget = $group->insert( $widget, $index );

Inserts widget in the <index>th position of this group's stack.

my $widget = $group->insert( $widget, $before );

This does $G->insert($widget, $G->find($beforethis)). This will append the widget if $beforethis is not in the group.

navigation_key

my $key = $group->navigation_key( );

Turn Tab into Right or Left for keyboard navigation.

new

my $grp = $group->new( $x, $y, $w, $h, $label, $begin );

Creates a new FLTK::Group widget using the given position, size, and label string. The default boxtype is NO_BOX.

remove

$group->remove( $index );

Remove the indexth widget from the group.

$group->remove( $widget );

Removes a widget from the group. This does nothing if the widget is not currently a child of this group.

remove_all

$group->remove_all( );

Removes all widgets from the group. This does not call the destructor on the child widget.

See clear())

replace

my $widget_b = $group->replace( $index, $widget_b );

Remove the indexth widget and inserts widget_b in its place.

my $widget_b = $group->replace( $widget, $widget_b );

Remove the widget and inserts widget_b in its place.

resizable

$group->resizable( $widget );

Sets the resizing widget.

my $elastic = $group->resizable( );

The resizable widget defines the resizing box for the group. When the group is resized it calculates a new size and position for all of its children. Widgets that are horizontally or vertically inside the dimensions of the box are scaled to the new size. Widgets outside the box are moved.

The resizable may be set to the group itself, in which case all the contents are resized. If the resizable is undef (the default) then all widgets remain a fixed size and distance from the top-left corner.

It is possible to achieve any type of resize behavior by using an InvisibleBox as the resizable and/or by using a hierarchy of child Group's.

resize_align

my $flags = $group->resize_align( );

$group->resize_align( $flags );

set_focus

$group->set_focus( $widget );

Same as focus_index( $index ).

swap

$group->swap( $indexA, $indexB );

Swaps the indexAth widget with the indexBth widget.

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