IupButton
Definition: |
include pGUI.e
Ihandle ih = IupButton(nullable_string title=NULL, [[nullable_string action=NULL,] cbfunc func=NULL,] string attributes="", dword_seq args={}) |
Description: |
Creates an interface element that is a button. When selected, this element activates a function in the application. The visual presentation can contain text and/or an image. title: Text to be shown to the user. It can be NULL. It will set the TITLE attribute. action: Name of the action generated when the button is selected. It can be NULL. func: a callback address, usually specified as Icallback("name"). For more information on the attributes and args parameters see IupSetAttributes. This is a paranormalised function. Returns the identifier of the created element. |
pwa/p2js: | Supported, but see +x? markers on individual attributes and callbacks. |
See Also: | IupImage, IupToggle, IupLabel, IupFlatButton, IupDropButton, IupGLButton |
Notes: |
Buttons with images and/or texts can not change their behavior after being mapped. This is a creation dependency.
But after creation the image can be changed for another image, and the text for other text.
Buttons are activated using Enter or Space keys. Some examples can be seen in demo\pGUI\sample.exw |
Attributes: | |
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". In GTK, horizontal alignment for multiple lines will align only the text block. |
BGCOLOR? |
Background color. If text and image are not defined, set the button size, otherwise the natural size will be very small. In Windows, the BGCOLOR attribute is ignored if text or image is defined. Default: the global attribute DLGBGCOLOR. BGCOLOR is ignored when FLAT=YES because it will be used the background from the native parent. |
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. |
PROPAGATEFOCUS | (non inheritable) enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23) |
FLAT | (creation only) Hides the button borders until the mouse enter the button area. Can be YES or NO. Default: NO. |
FGCOLOR | Text color. Default: the global attribute DLGFGCOLOR. |
IMAGE? |
(non inheritable) Image name. 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. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. 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 natural size. 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. |
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 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) |
CPADDING | same as PADDING but using the units of the SIZE attribute. It will actually set the PADDING attribute. (since 3.29) |
SPACING |
(creation only) defines the spacing between the image associated and the button’s text. Default: "2".
|
CSPACING |
same as SPACING but using the units of the vertical part of the SIZE attribute. It will actually set the SPACING attribute. (since 3.29)
|
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 of defining a mnemonic. The button can be activated from any control in the dialog using the "Alt+key" combination. In old Motif versions (2.1) using a '\n' causes an invalid memory access inside Motif. (mnemonic support since 3.0) |
also | ACTIVE, FONT, NAME, EXPAND, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP?, SIZE+, RASTERSIZE+, ZORDER, VISIBLE: also accepted. |
Callbacks: |
|
ACTION |
Action generated when the button is selected. This callback is called only after the mouse is released and when it is released inside the button area.
function action_cb(Ihandle ih) ih: identifier of the element that activated the event. Returns: IUP_CLOSE will be processed. Note that IUP_IGNORE removes the callback, and hence effectively disables the button. |
BUTTON_CB |
Action generated when any mouse button is pressed and when it is released. Both calls occur before the ACTION callback when button 1 (left mouse) is being used. |
also | MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported. |