/ 
IUP-0.304_1
River stage zero No dependents
/ IUP::Toggle

NAME

IUP::Toggle - [GUI element] two-state (on/off) button with a text and/or an image

DESCRIPTION

Creates the toggle interface element. It is a two-state (on/off) button that, when selected, generates an action that activates a function in the associated application. Its visual representation can contain a text or an image.

GTK Motif Windows
Classic		 Windows
XP Style

USAGE

CREATION - new() method

$toggle = IUP::Toggle->new( VALUE=>"ON" );

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 when IMAGE is defined. 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". In Windows works only when Visual Styles is active. Text is always left aligned. (since 3.0)

BGCOLOR

Background color of toggle mark when displaying a text. The text background is transparent, it will use the background color of the native parent. When displaying an image in Windows the background is ignored and the system color is used. Default: the global attribute DLGBGCOLOR.

CANFOCUS

(creation only) (non inheritable)

enables the focus traversal of the control. In Windows the control will still get the focus when clicked. Default: YES.

FGCOLOR

Color of the text shown on the toggle. In Windows, when using Visual Styles FGCOLOR is ignored. Default: the global attribute DLGFGCOLOR.

FLAT

(creation only)

Hides the toggle borders until the mouse enter the toggle area when the toggle is not checked. If the toggle is checked, then the borders will be shown even if flat is enabled. Used only when IMAGE is defined. Can be YES or NO. Default: NO. (since iup-3.3)

IMAGE

(non inheritable) [GTK 2.6]

Image name or IUP::Image reference. When the IMAGE attribute is defined, the TITLE is not shown. This makes the toggle looks just like a button with an image, but its behavior remains the same.

See - Using Images in Other Elements (via IMAGE Attribute)

IMPRESS

(non inheritable) [GTK 2.6]

Image name of the pressed toggle. Unlike buttons, toggles always display the button border when IMAGE and IMPRESS are both defined.

IMINACTIVE

(non inheritable)

Image name of the inactive toggle. If it is not defined but IMAGE is defined then for inactive toggles the colors will be replaced by a modified version of the background color creating the disabled effect. (GTK 2.6)

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 when IMAGE is defined. 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".

RADIO

(read-only)

Returns if the toggle is inside a radio. Can be "YES" or "NO". Valid only after the element is mapped, before returns undef.

RIGHTBUTTON

(Windows Only) (creation only)

Place the check button at the right of the text. Can be "YES" or "NO". Default: "NO".

VALUE

(non inheritable)

Toggle's state. Values can be "ON" or "OFF". If 3STATE=YES then can also be "NOTDEF". Default: "OFF". In GTK if you change the state of a radio, the unchecked toggle will receive an ACTION callback notification.

TITLE

(non inheritable)

Toggle's text. If IMAGE is not defined before map, then the default behavior is to contain 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 or check box if any. 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 toggle can be activated from any control in the dialog using the "Alt+key" combination. (mnemonic support since iup-3.0)

3STATE (creation only)

Enable a three state toggle. Valid for toggles with text only and that do not belong to a radio. Can be "YES" or NO". Default: "NO".

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 toggle's state (on/off) was changed. The callback also receives the toggle's state.

Callback handler prototype:

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

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

    $state: 1 if the toggle's state was shifted to on; 0 if it was shifted to off.

    Returns: IUP_CLOSE will be processed.

VALUECHANGED_CB

Called after the value was interactively changed by the user. Called after the ACTION callback, but under the same context.

Callback handler prototype:

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

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

The following common callbacks are also accepted:

NOTES

Toggle with image or text can not change its behavior after mapped. This is a creation attribute. But after creation the image can be changed for another image, and the text for another text.

Toggles are activated using the Space key.

To build a set of mutual exclusive toggles, insert them in a IUP::Radio container. They must be inserted before creation, and their behavior can not be changed. If you need to dynamically remove toggles that belongs to a radio in Windows, then put the radio inside a IUP::Frame that has a title.

EXAMPLES

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

SEE ALSO

IUP::Image, IUP::Button, IUP::Label, IUP::Radio.

The original doc: iuptoggle.html