/ 
IUP-0.305
River stage zero No dependents
/ IUP::Button

NAME

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

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.

Windows
XP Style		 Windows
Classic		 GTK Motif
image
text
image+text
background
color

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.

USAGE

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

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

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

ALIGNMENT

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

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.

CANFOCUS

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

FLAT

(creation only)

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

FGCOLOR

Text color. Default: the global attribute DLGFGCOLOR.

IMAGE

(non inheritable)

Image name or 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 - 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)

IMINACTIVE

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

IMPRESS

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

IMPRESSBORDER

(non inheritable)

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

IMAGEPOSITION

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

MARKUP

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

PADDING

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

SPACING

(creation only)

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

TITLE

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

The following common attributes are also accepted:

CALLBACKS

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

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.

Callback handler prototype:

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

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

Returns: IUP_CLOSE will be processed.

BUTTON_CB

Action generated when any mouse button is pressed and released.

For more details see generic description of BUTTON_CB callback.

The following common callbacks are also accepted:

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.

EXAMPLES

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

SEE ALSO

IUP::Image, IUP::Toggle, IUP::Button

The original doc: iupbutton.html