The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
KMX / IUP-0.305 / lib / IUP / Button.pod 
=for comment based on iup-3.2 - http://www.tecgraf.puc-rio.br/iup/en/elem/iupbutton.html

=head1 NAME

IUP::Button - [GUI element] button decorated with a text and/or an image

=head1 DESCRIPTION

GUI element that is a button. When selected, this
element activates a function in the application. Its visual
presentation can contain a text and/or an image.

=begin HTML

<p>
  <table border="1">
    <col>
    <col style="background-color: rgb(236, 233, 216);">
    <col style="background-color: rgb(212, 208, 200);">
    <col style="background-color: rgb(239, 235, 231);">
    <col style="background-color: rgb(173, 177, 194);">
    <tbody align="center">
      <tr>
        <td style="text-align: center;"></td>
        <td style="text-align: center;">Windows<br>XP Style</td>
        <td style="text-align: center;">Windows<br>Classic</td>
        <td style="text-align: center;">GTK</td>
        <td style="text-align: center;">Motif</td>
      </tr>
      <tr>
        <td>image</td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_winxp_image.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_win2k_image.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_gtk_image.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_mot_image.png"></td>
      </tr>
      <tr>
        <td>text</td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_winxp_text.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_win2k_text.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_gtk_text.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_mot_text.png"></td>
      </tr>
      <tr>
        <td>image+text</td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_winxp_imagetext.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_win2k_imagetext.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_gtk_imagetext.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_mot_imagetext.png"></td>
      </tr>
      <tr>
        <td>background<br>color</td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_winxp_bgcolor.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_win2k_bgcolor.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_gtk_bgcolor.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupbutton_mot_bgcolor.png"></td>
      </tr>
    </tbody>
  </table>
</p>

=end HTML

NOTE: The buttons with image and text simultaneous have PADDING '5x5', the
other buttons have no padding. The buttons with no text and BGCOLOR
defined have their RASTERSIZE set.

=head1 USAGE

=head2 CREATION - new() method

Simple button with text:

 my $button = IUP::Button->new( TITLE=>'Click me' );

Button with image:

 my $img = IUP::Image->new( file=>'icon.png' );
 my $button = IUP::Button->new( IMAGE=>$img );

Button with both text and image:

 my $img = IUP::Image->new( file=>'icon.png' );
 my $button = IUP::Button->new( TITLE=>'Click', IMAGE=>$img );

Button with a image from build-in ImageLibrary - see L<Manual::ImageLibrary|Manual::ImageLibrary>: 

 my $button = IUP::Button->new( IMAGE=>'IUP_Cancel' );

Color button with background color set:

 my $button1 = IUP::Button->new( BGCOLOR=>"0 200 0" ); #defined by RGB values
 my $button2 = IUP::Button->new( BGCOLOR=>IUP_RED );   #build-in constant
 
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 B<ALIGNMENT>

I<(non inheritable)>

Horizontal and vertical alignment.
Possible values: "ALEFT", "ACENTER" and "ARIGHT", combined to "ATOP",
"ACENTER" and "ABOTTOM". Default: "ACENTER:ACENTER". Partial values are
also accepted, like "ARIGHT" or ":ATOP", the other value will be used
from the current alignment. In Motif, vertical alignment is restricted
to "ACENTER". 

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

Background color. 
BGCOLOR is ignored always when FLAT=YES because it will inherit from the
native parent. If text and image are not defined, the BGCOLOR is used to
show a color not necessary as a background color of the button, in this case
set the button size because the natural size will be very small. In
Windows, when using the Windows driver or the GTK driver, the BGCOLOR
attribute is ignored if text or image is defined. Default: the global
attribute DLGBGCOLOR.

=item B<CANFOCUS>

I<(creation only, non inheritable)>

Enables the focus
traversal of the control. In Windows the button will respect CANFOCUS
in opposite to the other controls. Default: YES. 

=item B<FLAT>

I<(creation only)>

Hides the button borders until the mouse enter the button area. Can be YES or NO.

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

Text color. Default: the global attribute DLGFGCOLOR.

=item B<IMAGE>

I<(non inheritable)>

Image name or L<IUP::Image> reference. If set before map defines the
behavior of the button to contain an image. The natural size will be
size of the image in pixels, plus the button borders. 

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

If TITLE is also defined and not empty both will be shown (except in
Motif). (GTK 2.6)

=item B<IMINACTIVE>

I<(non inheritable)>

Image name of the element when
inactive. If it is not defined then the IMAGE is used and the colors
will be replaced by a modified version of the background color creating
the disabled effect. GTK will also change the inactive image to look
like other inactive objects. (GTK 2.6)

=item B<IMPRESS>

I<(non inheritable)>

Image name of the pressed button. If
IMPRESS and IMAGE are defined, the button borders are not shown and not
computed in size computation. When the button is clicked the pressed
image does not offset. In Motif the button will lose its focus feedback
also. (GTK 2.6)

=item B<IMPRESSBORDER>

I<(non inheritable)>

If enabled the button borders will
be shown and computed even if IMPRESS is defined. Can be "YES" or "NO".
Default: "NO".

=item B<IMAGEPOSITION>

I<(non inheritable)>

Position of the image relative to
the text when both are displayed. Can be: LEFT, RIGHT, TOP, BOTTOM.
Default: LEFT.  (GTK 2.10)

=item B<MARKUP>

I<(GTK only)>

allows the title string to contains pango markup
commands. Works only if a mnemonic is NOT defined in the title. Can be
"YES" or "NO". Default: "NO".

=item B<PADDING>

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

=item B<SPACING>

I<(creation only)>

defines the spacing between the image
associated and the button's text. Default: "2".

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

I<(non inheritable)>

Button's text. If
IMAGE is not defined before map, then the default behavior is to
contain only a text. The button behavior can not be changed after map.
The natural size will be larger enough to include all the text in the
selected font, even using multiple lines, plus the button borders. The
'\n' character is accepted for line change. 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.0)

=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<EXPAND|IUP::Manual::03_Attributes/EXPAND>,
L<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
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<SIZE|IUP::Manual::03_Attributes/SIZE>,
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 L<ACTION|IUP::Manual::03_Attributes/ACTION>

Action generated when the button 1
(usually left) is selected. This callback is called only after the
mouse is released and when it is released inside the button area.

B<Callback handler prototype:>

 sub action_handler {
   my ($self) = @_;
   #...
 }

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

B<Returns:> IUP_CLOSE will be processed.

=item L<BUTTON_CB|/BUTTON_CB>

Action generated when any mouse button is pressed and released.

For more details see L<generic description of BUTTON_CB|/BUTTON_CB> callback.

=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

Buttons with images and/or texts can not change its behavior after
mapped. This is a creation dependency. But after creation the image can
be changed for another image, and the text for another text.

Buttons are activated using Enter or Space keys.

=head1 EXAMPLES


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

=over

=item * L<0-basic/button.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/button.pl> - IUP::Button example

=item * L<0-basic/canvas3.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/canvas3.pl> - IUP::Canvas example

=item * L<0-basic/cbox.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/cbox.pl> - IUP::Cbox example

=item * L<0-basic/dialog1.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/dialog1.pl> - IUP::Dialog example

=item * L<0-basic/dialog2.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/dialog2.pl> - IUP::Dialog example

=item * L<0-basic/expander.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/expander.pl> - IUP::Expander example

=item * L<0-basic/fill.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/fill.pl> - IUP::Fill Example

=item * L<0-basic/gauge.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/gauge.pl> - IUP::Gauge example

=item * L<0-basic/gridbox.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/gridbox.pl> - IUP::GridBox example

=item * L<0-basic/hbox.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/hbox.pl> - IUP::Hbox example

=item * L<0-basic/idle.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/idle.pl> - IUP->SetIdle Example

=item * L<0-basic/image.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/image.pl> - IUP::Image example

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

=item * L<0-basic/list2.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/list2.pl> - IUP::List example

=item * L<0-basic/message_clone.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/message_clone.pl>

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

=item * L<0-basic/pre-dialogs.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/pre-dialogs.pl> - IUP::Expander example

=item * L<0-basic/progressbar2.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/progressbar2.pl> - IUP::ProgressBar example

=item * L<0-basic/progressbar3.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/progressbar3.pl> - IUP::ProgressBar example

=item * L<0-basic/sbox1.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/sbox1.pl> - IUP::Sbox example

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

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

=item * L<0-basic/text_format.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/text_format.pl> - IUP::Text (formating) example

=item * L<0-basic/tree_set_attrs.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/tree_set_attrs.pl> - IUP::Tree example (attributes)

=item * L<0-basic/vbox.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/vbox.pl> - IUP::Vbox example

=item * L<0-basic/zbox.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/zbox.pl> - IUP::Zbox example

=item * L<1-apps/app-mdi.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/1-apps/app-mdi.pl> - IUP app example

=item * L<1-apps/app-plot-demo.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/1-apps/app-plot-demo.pl> - dials for zooming

=item * L<1-apps/app-sample1.pl|https://metacpan.org/source/KMX/IUP-0.305/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.305/examples/1-apps/app-sample2.pl> - example based on the original sample.c

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

=back 



=head1 SEE ALSO

L<IUP::Image|IUP::Image>, L<IUP::Toggle|IUP::Toggle>, L<IUP::Button|IUP::Button>

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


=cut