IupToggle

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.

Creation

Ihandle* IupToggle(const char *title, const char *action); [in C]
iup.toggle{[title = title: string]} -> (ih: ihandle) [in Lua]
toggle(title, action) [in LED]

title: Text to be shown on the toggle. It can be NULL. It will set the TITLE attribute.
action: name of the action generated when the toggle is selected. It can be NULL.

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

Attributes

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 obtained from the default value. 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. (since 3.0)

PROPAGATEFOCUS(non inheritable): enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23)

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

IMAGE (non inheritable): Image name. 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. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. (GTK 2.6)

IMPRESS (non inheritable): Image name of the pressed toggle. Unlike buttons, toggles always display the button border when IMAGE and IMPRESS are both defined. (GTK 2.6)

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 IupHbox and IupVbox containers, but uses a different name to avoid inheritance problems. Default value: "0x0". Value can be DEFAULTBUTTONPADDING, so the global attribute of this name will be used instead (since 3.29). (since 3.0)

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 NULL. (since 3.0)

IGNORERADIO (non inheritable): when set the toggle will not behave as a radio when inside an IupRadio hierarchy. (since 3.21)

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", "OFF" or "TOGGLE". If 3STATE=YES then can also be "NOTDEF". Default: "OFF". The TOGGLE option will invert the current state (since 3.7). In GTK if you change the state of a radio, the unchecked toggle will receive an ACTION callback notification. Can only be set to ON if the toggle is inside a radio, it will automatically set to OFF the previous toggle that was ON in the radio.

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

ACTIVE, FONT, EXPAND, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE, THEME: also accepted.

Callbacks

ACTION: Action generated when the toggle's state (on/off) was changed. The callback also receives the toggle's state.

int function(Ihandle* ih, int state); [in C]
ih:action(state: number) -> (ret: number) [in Lua]

ih: identifier of the element 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. (since 3.0)

int function(Ihandle *ih); [in C]
ih:valuechanged_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

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 an IupRadio 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 an IupFrame that has a title.

A toggle that is a child of an IupRadio automatically receives a name when its is mapped into the native system. (since 3.16)

In GTK uses GtkRadioButton/GtkCheckButton/GtkToggleButton, in Windows uses WC_BUTTON, and in Motif uses xmToggleButton.

Examples

Browse for Example Files