FreeBSD Manual Pages
AG_BUTTON(3) BSD Library Functions Manual AG_BUTTON(3) NAME AG_Button -- agar button widget SYNOPSIS #include <agar/core.h> #include <agar/gui.h> DESCRIPTION The AG_Button widget implements a simple push-button displaying an image or a text label. AG_Button can be used to trigger events, or control a boolean value. INHERITANCE HIERARCHY AG_Object(3) -> AG_Widget(3) -> AG_Button. INTERFACE AG_Button * AG_ButtonNew(AG_Widget *parent, Uint flags, const char *format, ...) AG_Button * AG_ButtonNewS(AG_Widget *parent, Uint flags, const char *label) AG_Button * AG_ButtonNewFn(AG_Widget *parent, Uint flags, const char *label, void (*fn)(AG_Event *), const char *fnArgs, ...) AG_Button * AG_ButtonNew{Int,Uint8,Uint16,Uint32}(AG_Widget *parent, Uint flags, const char *label, _Type_ *p) AG_Button * AG_ButtonNew{Flag,Flag8,Flag16,Flag32}(AG_Widget *parent, Uint flags, const char *label, Uint *p, _Type_ bitmask) void AG_ButtonSetPadding(AG_Button *button, int lPad, int rPad, int tPad, int bPad) void AG_ButtonSetFocusable(AG_Button *button, int flag) void AG_ButtonSetSticky(AG_Button *button, int flag) void AG_ButtonInvertState(AG_Button *button, int flag) void AG_ButtonJustify(AG_Button *button, enum ag_text_justify justify) void AG_ButtonValign(AG_Button *button, enum ag_text_valign valign) void AG_ButtonSetRepeatMode(AG_Button *button, int repeat_flag) void AG_ButtonSurface(AG_Button *button, const AG_Surface *su) void AG_ButtonSurfaceNODUP(AG_Button *button, AG_Surface *su) void AG_ButtonText(AG_Button *button, const char *format, ...) void AG_ButtonTextS(AG_Button *button, const char *label) The AG_ButtonNew() function allocates, initializes, and attaches a AG_Button widget. If the label argument is given, it sets a default text caption. For the list of acceptable flags, see BUTTON FLAGS section. The AG_ButtonNewFn() variant creates a button and implicitely sets a callback (event handler) function to be executed whenever the button is pressed. See AG_Event(3) for details on Agar event handlers. Since function-triggering buttons rarely make use of the "state" binding, AG_ButtonNewFn() implies AG_BUTTON_EXCL (unless AG_BUTTON_NOEXCL is passed). The AG_ButtonNew{Int,Uint8,Uint16,Uint32}() functions tie the state of the button (the `state' binding) with the given integer variable, where 1 = True and 0 = False. The AG_ButtonNew{Flag,Flag8,Flag16,Flag32}(), functions tie the state of the button with the state of the bits described by bitmask in the speci- fied integer variable. AG_ButtonNewFlag() binds to an int, AG_ButtonNewFlag8() binds to an Uint8, etc. The AG_ButtonSetPadding() function sets the padding around the label in pixels. If a parameter is -1, its current value is preserved. Note that when using a text label, this setting is independent from that of the la- bel (use AG_LabelSetPadding(3) on the lbl member of the AG_Button to con- figure the text label padding as well). The AG_ButtonSetFocusable() function with an argument of 0 prevents the button from gaining focus. The default is to allow buttons to gain fo- cus. The AG_ButtonSetSticky() function enables or disable sticky mode. Under sticky mode, the button will not spring back to its previous state fol- lowing a click event. This mode is mostly useful when the button's state is bound to a boolean variable. The AG_ButtonInvertState() function defines whether to invert the meaning of the boolean variable bound to the button. AG_ButtonJustify() sets the justification for the button text label (or icon): enum ag_text_justify { AG_TEXT_LEFT, AG_TEXT_CENTER, AG_TEXT_RIGHT }; AG_ButtonValign() sets the vertical alignment for the button text label (or icon): enum ag_text_valign { AG_TEXT_TOP, AG_TEXT_MIDDLE, AG_TEXT_BOTTOM }; The AG_ButtonSetRepeatMode() flag enables or disables repeat mode. Re- peat mode causes multiple `button-pushed' events to be posted periodi- cally for as long as the button is triggered. Repeat mode is used no- tably by AG_Numerical(3). AG_ButtonSurface() sets the button label to a copy of the given surface. The AG_ButtonSurfaceNODUP() variant uses the given surface as source without copying. If a text label currently exists, it is removed. AG_ButtonText() sets the label of the button from the specified text string. If a surface is currently set, it is removed. BUTTON FLAGS The following flags are provided: AG_BUTTON_STICKY Prevent the button from springing back to its pre- vious state following a click. Set on initializa- tion or by AG_ButtonSetSticky(). AG_BUTTON_MOUSEOVER The cursor is over the button area (read-only). AG_BUTTON_REPEAT Repeat mode is enabled (read-only, see AG_ButtonSetRepeatMode()). AG_BUTTON_INVSTATE Invert the interpretation of the "state" binding. By default, a value of 1 causes the button to be pressed. AG_BUTTON_EXCL Disable the test for redrawing the button upon ex- ternal changes to the "state" binding. AG_BUTTON_HFILL Expand horizontally in parent (equivalent to invok- ing AG_ExpandHoriz(3)). AG_BUTTON_VFILL Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)). AG_BUTTON_EXPAND Shorthand for AG_BUTTON_HFILL|AG_BUTTON_VFILL. EVENTS The AG_Button widget generates the following events: button-pushed(int new_state) The button was pressed. If using AG_BUTTON_STICKY, the new_state ar- gument indicates the new state of the button. BINDINGS The AG_Button widget provides the following bindings. In all cases, a value of 1 is considered boolean TRUE, and a value of 0 is considered boolean FALSE. BOOL *state Value (1/0) of natural integer INT *state Value (1/0) of natural integer UINT8 *state Value (1/0) of 8-bit integer UINT16 *state Value (1/0) of 16-bit integer UINT32 *state Value (1/0) of 32-bit integer FLAGS *state Bits in an int FLAGS8 *state Bits in 8-bit word FLAGS16 *state Bits in 16-bit word FLAGS32 *state Bits in 32-bit word EXAMPLES The following code fragment creates a button and sets a handler function for the `button-pushed' event: void MyHandlerFn(AG_Event *event) { AG_TextMsg(AG_MSG_INFO, "Hello, %s!", AG_STRING(1)); } ... AG_ButtonNewFn(parent, 0, "Hello", MyHandlerFn, "%s", "world"); The following code fragment uses buttons to control specific bits in a 32-bit word: Uint32 MyFlags = 0; AG_ButtonNewFlag32(parent, 0, "Bit 1", &MyFlags, 0x01); AG_ButtonNewFlag32(parent, 0, "Bit 2", &MyFlags, 0x02); The following code fragment uses a button to control an int protected by a mutex device: int MyInt = 0; AG_Mutex MyMutex; AG_Button *btn; AG_MutexInit(&MyMutex); btn = AG_ButtonNew(parent, 0, "Mutex-protected flag"); AG_BindIntMp(btn, "state", &MyInt, &MyMutex); SEE ALSO AG_Event(3), AG_Intro(3), AG_Surface(3), AG_Toolbar(3), AG_Widget(3), AG_Window(3) HISTORY The AG_Button widget first appeared in Agar 1.0. BSD August 20, 2002 BSD
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INTERFACE | BUTTON FLAGS | EVENTS | BINDINGS | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Button&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>