The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
SANKO / FLTK-0.532009 / lib / FLTK / TabGroup.pod 
=pod

=head1 NAME

FLTK::TabGroup - For Making a 'Tabbed' Dialog Boxes

=head1 Description

This is the "file card tabs" interface to allow you to put lots and lots of
buttons and switches in a panel. This first appeared in NeXTStep, but is best
known from Windows control panesl. FLTK's version draws in a style more
reminiscent of NeXT or PageMaker, and avoids the confusing multiple-lines of
Windows by drawing overlapping tabs.

Each child widget is a card, and it's L<C<label()>|FLTK::Widget/"label"> is
printed on the card tab (including the label font and style). The
L<C<color()>|FLTK::Widget/"color"> of the child is used to color the tab as
well.

The size of the tabs is controlled by the bounding box of the children (there
should be some space between the children and the edge of this widget). If
there is a larger gap on the bottom than the top, the tabs are placed
"inverted" along the bottom.

Clicking the tab makes that child L<C<visible()>|FLTK::Widget/"visible"> and
hides all the other children. If the widget with the focus does not consume
them, the C<Ctrl+Tab> and C<Ctrl+Shift+Tab> keys will also switch tabs. The
user can also navigate the focus to the tabs and change them with the arrow
keys.

The L<C<callback()>|FLTK::Widget/"callback"> of the L<TabGroup|FLTK::TabGroup>
widget is called when the user changes the visible tab, and C<SHOW> and
C<HIDE> events are passed to the children.

=head1 Functions

=head2 C<default_pager>
X<default_pager>

=over

=item C<$tabgroup-E<gt>default_pager( $value );>X<_tabgroup_E_gt_default_pager_value_>

Sets the default pager for future L<TabGroup|FLTK::TabGroup>s. By design, the
defualt pager is never undefined.

=for hackers xs/TabGroup.xs line 210

=item C<$tabgroup-E<gt>default_pager( $value );>X<_tabgroup_E_gt_default_pager_value_>

Sets the default pager from the built-in ones.

The current built-in pagers are...

=over 

=item Menu
Displays two left and right buttons and provides 'prev page' and 'next page'
functionality. This is the new default.

Pass C<0> for this type.

=item Shrink
Tabs outside the rectangle are shrunken to very small slice to fit. This is
the original default.

Pass C<1> for this type.

=back 

=for hackers xs/TabGroup.xs line 215

=back

=head2 C<default_style>
X<default_style>

=over

=item C<my $style = $tabgroup-E<gt>default_style( );>X<my_style_tabgroup_E_gt_default_style_>

The default style has a gray L<C<color( )>|FLTK::Widget/"color"> and the
L<C<box( )>|FLTK::Widget/"box"> is set to C<THIN_UP_BOX>. The
L<C<box( )>|FLTK::Widget/"box"> is used to draw the edge around the cards,
including the top edge, but the tab itself is designed only to match
C<THIN_UP_BOX>. You can also use C<FLAT_BOX> and it will look correct if the
tabs fill the entire width of a window or parent box.

=for hackers xs/TabGroup.xs line 75

=item C<$tabgroup-E<gt>default_style( $style );>X<_tabgroup_E_gt_default_style_style_>

Set the style.

=for hackers xs/TabGroup.xs line 84

=back

=head2 C<draw_tab>
X<draw_tab>

=over

=item C<$tabgroup-E<gt>draw_tab( $x1, $x2, $W, $H, $o, $sel );>X<_tabgroup_E_gt_draw_tab_x1_x2_W_H_o_sel_>


=for hackers xs/TabGroup.xs line 288

=back

=head2 C<draw_tab_background>
X<draw_tab_background>

=over

=item C<$tabgroup-E<gt>draw_tab_background( );>X<_tabgroup_E_gt_draw_tab_background_>


=pod 

=for hackers xs/TabGroup.xs line 296

=back

=head2 C<new>
X<new>

=over

=item C<my $group = $tabgroup-E<gt>new( $x, $y, $w, $h, $label, $begin );>X<my_group_tabgroup_E_gt_new_x_y_w_h_label_begin_>

Creates a new L<TabGroup|FLTK::TabGroup> widget using the given position,
size, and label string. Use L<C<add(widget)>|FLTK::Group/"add"> to add each
child. Each child is probably an L<FLTK::Group|FLTK::Group> widget containing
the actual widgets the user sees. The children should be sized to stay away
from the top or bottom edge of the L<FLTK::Tab|FLTK::Tab>s, which is where the
tabs are drawn.

=for hackers xs/TabGroup.xs line 55

=back

=head2 C<pager>
X<pager>

=over

=item C<$tabgroup-E<gt>pager( $value );>X<_tabgroup_E_gt_pager_value_>

Sets the pager to a L<TabGroup|FLTK::TabGroup>. By design, pager is B<never>
undefined.

=for hackers xs/TabGroup.xs line 189

=item C<my $pager = $tabgroup-E<gt>pager( );>X<my_pager_tabgroup_E_gt_pager_>


=for hackers xs/TabGroup.xs line 194

=back

=head2 C<selected_child>
X<selected_child>

=over

=item C<my $child = $tabgroup-E<gt>selected_child( );>X<my_child_tabgroup_E_gt_selected_child_>

Returns C<$tabgroup->child($tabgroup->value())> or an undefined value if no
children exist.

=for hackers xs/TabGroup.xs line 147

=item C<my $new = $tabgroup-E<gt>selected_child( $newval );>X<my_new_tabgroup_E_gt_selected_child_newval_>

Switches to this child widget, or to a child that
L<C<contains( )>|FLTK::Widget/"contians"> this widget. Returns true if this is
a different selection than before. Does not do the
L<C<callback( )>|FLTK::Widget/"callback">. If the widget is null or not a
descendent of this, the last child is selected.

=for hackers xs/TabGroup.xs line 152

=back

=head2 C<set_draw_outline>
X<set_draw_outline>

=over

=item C<$tabgroup-E<gt>set_draw_outline( $draw_outline );>X<_tabgroup_E_gt_set_draw_outline_draw_outline_>



=for hackers xs/TabGroup.xs line 180

=back

=head2 C<tab_height>
X<tab_height>

=over

=item C<my $height = $tabgroup-E<gt>tab_height( );>X<my_height_tabgroup_E_gt_tab_height_>

Returns the space needed for tabs. Negative values will place tabs on the
bottom.

=for hackers xs/TabGroup.xs line 248

=back

=head2 C<tab_positions>
X<tab_positions>

=over

=item C<my $index = $tabgroup-E<gt>tab_positions( );>X<my_index_tabgroup_E_gt_tab_positions_>

Returns the index of the selected item, the left edges of each tab (plus a
fake left edge for a tab past the right-hand one). These positions are
actually of the left edge of the slope. They are either seperated by the
correct distance or by C<$tabgroup->pager->slope( )> or by zero.

Return value is the index of the selected item.

=for hackers xs/TabGroup.xs line 258

=back

=head2 C<value>
X<value>

=over

=item C<my $val = $tabgroup-E<gt>value( );>X<my_val_tabgroup_E_gt_value_>

Returns the index of the first L<C<visible( )>|FLTK::Widget/"visible"> child,
which is normally the one the user selected.

This will automatically force a single child to be
L<C<visible( )>|FLTK::Widget/"visible"> if more than one is, or if none are.
If more than one is visible all except the first is hidden. If none are, the
last one is made visible. The resulting visible child's index is returned.
This behavior allows new TabGroups to be created with all children visible,
and allows children to be deleted, moved to other groups, and
L<C<show( )>|FLTK::Widget/"show">/L<C<hide( )>|FLTK::Widget/"hide"> called on
them without the display ever looking wrong to the user.

If there are no children then C<-1> is returned.

=for hackers xs/TabGroup.xs line 101

=item C<$tabgroup-E<gt>value( $newval );>X<_tabgroup_E_gt_value_newval_>

Switch so index C<$newval> is selected. If n is less than zero selects zero,
if C<$newval> is greater than the children, it selects the last one. Returns
true if this is a different child than last time. Does not do the
L<C<callback( )>|FLTK::Widget/"callback">.

=for hackers xs/TabGroup.xs line 117

=back

=head2 C<which>
X<which>

=over

=item C<my $index = $tabgroup-E<gt>which( $event_x, $event_y );>X<my_index_tabgroup_E_gt_which_event_x_event_y_>

Returns the child index that would be selected by a click at the given mouse
position. Returns C<-1> if the mouse position is not in a tab.

=for hackers xs/TabGroup.xs line 137

=back

=head1 Author

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

=head1 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
L<The Artistic License 2.0|http://www.perlfoundation.org/artistic_license_2_0>.
See the F<LICENSE> file included with this distribution or
L<notes on the Artistic License 2.0|http://www.perlfoundation.org/artistic_2_0_notes>
for clarification.

When separated from the distribution, all original POD documentation is
covered by the
L<Creative Commons Attribution-Share Alike 3.0 License|http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>.
See the
L<clarification of the CCA-SA3.0|http://creativecommons.org/licenses/by-sa/3.0/us/>.


=for git $Id: TabGroup.xs 88858e0 2011-04-19 00:47:41Z sanko@cpan.org $

=cut