lib/IUP/Tabs.pod - metacpan.org

=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/elem/iuptabs.html

=head1 NAME

IUP::Tabs - [GUI element] allows a single dialog to have several screens, grouping options

=head1 DESCRIPTION 

Creates a Tabs element. Allows a single dialog to have several screens,
grouping options. The grouping is done in a single line of tabs
arranged according to the tab type. Also known as Notebook in native
systems.

=begin HTML

<p>
  <table border="1">
    <col style="background-color: rgb(212, 208, 200);" width="350">
    <col style="background-color: rgb(236, 233, 216);" width="350">
    <tbody align="center">    
      <tr>
        <th>Windows Classic</th>
        <th>Windows w/ Style</th>
      </tr>
      <tr>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_win2k_top.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_winxp_top.png"></td>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_win2k_left.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_winxp_left.png"></td>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_win2k_top_multi.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_winxp_top_multi.png"></td>
      </tr>
    </tbody>
  </table>
  <p>
  <table border="1">
    <col style="background-color: rgb(239, 235, 231);" width="350">
    <col style="background-color: rgb(239, 235, 231);" width="350">
    <tbody align="center">
      <tr>
        <th colspan="2">GTK</th>
      </tr>
      <tr>          
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_gtk_top.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_gtk_left.png"></td>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_gtk_top_vert.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_gtk_left_vert.png"></td>
      </tr>
    </tbody>
  </table>
  <p>
  <table border="1">
    <col style="background-color: rgb(173, 177, 194);" width="350">
    <col style="background-color: rgb(173, 177, 194);" width="350">
    <tbody align="center">
      <tr>
        <th colspan="2">Motif</th>
      </tr>
      <tr>          
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_mot_top.png"></td>
	<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iuptabs_mot_left.png"></td>
      </tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $tabs = IUP::Tabs->new( child=>[$elem1,$elem2], EXPAND=>'YES' );

B<child:> (named parameter) List of the elements that will be placed in the box.

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.)
see L<IUP::Manual::03_Attributes|IUP::Manual::03_Attributes>. Attributes specific to this element:

=over

=item L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>

In Windows and in GTK when in
Windows, the tab buttons background it will be always defined by the
system. In Windows the default background is different from the dialog
background. Default: the global attribute DLGBGCOLOR.

=item B<COUNT>

I<(read-only) (non inheritable)>

Returns the number of tabs.
Same value returned by L<GetChildCount|IUP::Manual::02_Elements/"GetChildCount()">. (since iup-3.3)

=item L<EXPAND|IUP::Manual::03_Attributes/EXPAND>

I<(non inheritable)>

The default value is "YES".

=item L<FGCOLOR|IUP::Manual::03_Attributes/FGCOLOR>

Tabs title color. Default: the global attribute DLGFGCOLOR.

=item B<MULTILINE>

I<[Windows Only] (non inheritable)>

Enable multiple lines
of tab buttons. This will hide the tab scroll and fits to make all tab
buttons visible. Can be "YES" or "NO". Default "NO". It is always
enabled when TABTYPE=LEFT or TABTYPE=RIGHT. 

=item B<PADDING>

I<(non inheritable)>

Internal margin of the tab title. Works
just like the MARGIN attribute of the L<IUP::Hbox> and L<IUP::Vbox> containers,
but uses a different name to avoid inheritance problems.
Default value: "0x0". 

=item L<SIZE|IUP::Manual::03_Attributes/SIZE>

I<(non inheritable)>

The default size is
the smallest size that fits its largest child. All child elements are
considered even invisible ones.

=item B<< TABIMAGE(n) >>(non inheritable)

E<lt>nE<gt> starts at 0. 

Image name or L<IUP::Image> reference to be used in the respective tab.

See - L<Using Images in Other Elements (via IMAGE Attribute)|IUP::Image/"Using Images in Other Elements (via IMAGE Attribute)">

In Motif, the image is shown only if B<< TABTITLE(n) >> is C<undef>.
In Windows and Motif set the BGCOLOR attribute before setting the image. 

=item B<TABORIENTATION>

I<(non inheritable)>

Indicates the orientation of tab
text, which can be "HORIZONTAL" or "VERTICAL". Default is "HORIZONTAL".
VERTICAL is supported only in GTK and in Windows. In Windows, VERTICAL
is only supported when TABTYPE=LEFT or TABTYPE=RIGHT. (GTK 2.6)

=item B<< TABTITLE(n) >> (non inheritable)

Contains the text to be shown in the
respective tab title. n starts at 0. If this value is C<undef>, it will
remain empty. The "&" character can be used to define a mnemonic, the
next character will be used as key. Use "&&" to show the "&" character
instead on defining a mnemonic. The button can be activated from any
control in the dialog using the "Alt+key" combination. (mnemonic
support since iup-3.3) 

=item B<TABTYPE>

I<(non inheritable, creation only in Windows)>

Indicates the
type of tab, which can be "TOP", "BOTTOM", "LEFT" or "RIGHT". Default
is "TOP". In Windows, if LEFT or RIGHT, then MULTILINE=YES and
TABORIENTATIONB<=>VERTICAL always. In Windows, when not TOP, then
visual style is removed from tabs.

=item B<VALUE>

I<(non inheritable)>

Changes the active tab.  The value passed must be the name (see L<SetName|IUP::Manual::02_Elements/"SetName()">) of one of 
the elements contained in the tabs or a reference to such an element.

=item B<VALUE_HANDLE>

I<(non inheritable)>

Changes the active tab by its
handle. The value passed must be the handle of a child contained in the
tabs. When the tabs is created, the first element inserted is set as
the visible child. 

=item B<VALUEPOS>

I<(non inheritable)>

Changes the active tab by its position,
starting at 0. When the tabs is created, the first element inserted is
set as the visible child. In GTK, inside the callback the returned
value is still the previous one. 

=back

The following L<common attributes|IUP::Manual::03_Attributes/Common Attributes> are also accepted:

=over

=item * L<ACTIVE|IUP::Manual::03_Attributes/ACTIVE>, L<FONT|IUP::Manual::03_Attributes/FONT>,
L<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<CLIENTSIZE|IUP::Manual::03_Attributes/CLIENTSIZE>,
L<CLIENTOFFSET|IUP::Manual::03_Attributes/CLIENTOFFSET>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>, L<WID|IUP::Manual::03_Attributes/WID>,
L<TIP|IUP::Manual::03_Attributes/TIP>,
L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE>,
L<ZORDER|IUP::Manual::03_Attributes/ZORDER>,
L<VISIBLE|IUP::Manual::03_Attributes/VISIBLE>

=back

=head2 CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.)
see L<IUP::Manual::04_Callbacks|IUP::Manual::04_Callbacks>. Callbacks specific to this element:

=over

=item B<TABCHANGE_CB>

Callback called when the user shifts the active tab.

B<Callback handler prototype:>

 sub tabchange_cb_handler {
   my ($self, $new_tab, $old_tab) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::Tabs) that activated the event

B<$new_tab:> the new tab selected by the user

B<$old_tab:> the previously selected tab

=back

=item B<TABCHANGEPOS_CB>

Callback called when the user shifts the active
tab. Called only when TABCHANGE_CB is not defined. (since iup-3.3)

B<Callback handler prototype:>

 sub tabchangepos_cb_handler {
   my ($self, $new_tab, $old_tab) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::Tabs) that activated the event

B<$new_pos:> the new tab position selected by the user

B<$old_pos:> the previously selected tab position

=back

=back

The following L<common callbacks|IUP::Manual::04_Callbacks/Common Callbacks> are also accepted:

=over

=item * L<MAP_CB|IUP::Manual::04_Callbacks/MAP_CB>,
L<UNMAP_CB|IUP::Manual::04_Callbacks/UNMAP_CB>,
L<GETFOCUS_CB|IUP::Manual::04_Callbacks/GETFOCUS_CB>,
L<KILLFOCUS_CB|IUP::Manual::04_Callbacks/KILLFOCUS_CB>,
L<ENTERWINDOW_CB|IUP::Manual::04_Callbacks/ENTERWINDOW_CB>,
L<LEAVEWINDOW_CB|IUP::Manual::04_Callbacks/LEAVEWINDOW_CB>,
L<K_ANY|IUP::Manual::04_Callbacks/K_ANY>, L<HELP_CB|IUP::Manual::04_Callbacks/HELP_CB>

=back

=head1 NOTES

The Tabs can be created with no children and be dynamic filled using
L<Append|IUP::Manual::02_Elements/"Append()">.

The ENTERWINDOW_CB and LEAVEWINDOW_CB callbacks are called only when
the mouse enter or leaves the tabs buttons area.

The Tabs children, differently from a L<IUP::Zbox|IUP::Zbox>, automatically
receives a name if does not already have one when it is appended to the
tabs in the native system. Also L<IUP::Tabs|IUP::Tabs> does NOT depends on the
VISIBLE attribute.

In GTK, when the tabs buttons are scrolled, the active tab is also
changed.

When you change the active tab the focus is usually not changed. If you
want to control the focus behavior call L<SetFocus|IUP::Manual::02_Elements/"SetFocus()"> in the
TABCHANGE_CB callback.

=head2 Utility Functions

These functions can be used to set and get attributes from the element:

 $elem->SetAttributeId($name, $id, $value);
 $elem->GetAttributeId($name, $id);

They work just like the respective traditional set and get functions.
But the attribute string is complemented with the id value. For ex:

 $elem->SetAttributeId("TABTITLE", 3, $value) ~~ $elem->SetAttribute("TABTITLE3", $value)

But these functions are faster than the traditional functions because
they do not need to parse the attribute name string and the application
does not need to concatenate the attribute name with the id.

=head1 EXAMPLES


The element B<IUP::Tabs> is used in the following sample scripts:

=over

=item * L<0-basic/layoutdialog.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/0-basic/layoutdialog.pl> - IUP::LayoutDialog example

=item * L<0-basic/plot_advanced.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/0-basic/plot_advanced.pl> - Plot controls

=item * L<0-basic/tabs1.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/0-basic/tabs1.pl> - IUP::Tabs example 

=item * L<0-basic/tabs2.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/0-basic/tabs2.pl> - IUP::Tabs example

=item * L<0-basic/tabs3.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/0-basic/tabs3.pl> - IUP::Tabs example 

=item * L<1-apps/app-sample1.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/1-apps/app-sample1.pl> - example used for screenshot - IUP.pod

=item * L<1-apps/app-sample2.pl|https://metacpan.org/source/KMX/IUP-0.201/examples/1-apps/app-sample2.pl> - example based on the original sample.c

=back 



=head1 SEE ALSO

The original doc: L<iuptabs.html|http://www.tecgraf.puc-rio.br/iup/en/elem/iuptabs.html>
 

=cut
	Global
`s`	Focus search bar
`?`	Bring up this help dialog
	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)
	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse
	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)