Widget Bindings

From Agar

This section was marked as being a stub. You are welcome to help expand it.

Agar widget bindings (also referred to as binders in some toolkits) provide a powerful and convenient mechanism for eliminating redundant/trivial event handler routines and other unnecessary complexity in a GUI application.

Widget bindings allow widget states to be associated with typed pointers. Widgets will then dereference the data directly. A given state can be associated with variables of different types (or more complex items such as string buffers, or specific bits in a word). The task of properly dereferencing, reading and writing the data is handled by the widget implementation itself.

Binding an integer to a button

Using widget bindings, setting the value of an integer to 1 or 0 using an AG_Button(3) widget is trivial:

 int myInt = 0;
 AG_ButtonNewInt(parent, 0, "State of myInt", &myInt);

Here, the AG_ButtonNewInt() function is simply provided by the AG_Button API as a shorthand. A more explicit way of binding to this variable would be:

 int myInt = 0;
 AG_Button *btn;
 
 btn = AG_ButtonNew(parent, 0, "State of myInt");
 AG_BindInt(btn, "state", &myInt);

The second argument to AG_BindInt() is the name of the binding (in this case "state"). Binding names are always documented in the BINDINGS section of the widget's manual page.

Binding a bit to a button

Boolean options are commonly represented using individual bits in a word. It is possible to create widget bindings to specific bits as well:

Uint32 myFlags = 0;
AG_ButtonNewFlag32(parent, 0, "Bit 1", &myFlags, 0x01);
AG_ButtonNewFlag32(parent, 0, "Bit 2", &myFlags, 0x02);

Again, AG_ButtonNewFlag32() is simply a shorthand for:

btn = AG_ButtonNew(parent, 0, "State of bit 1");
AG_BindFlag32(btn, "state", &myFlags, 0x01);
btn = AG_ButtonNew(parent, 0, "State of bit 2");
AG_BindFlag32(btn, "state", &myFlags, 0x02);

Binding a string to a Textbox

The following code fragment binds a AG_Textbox(3) to a C string contained in a fixed-size buffer. Note that the string may contain characters in UTF-8 and the textbox will display them properly.

char myString[32];
AG_Textbox *tb;
tb = AG_TextboxNew(parent, 0, "My string: ");
AG_TextboxBindUTF8(tb, myString, sizeof(myString));

Binding numbers to a Slider

The AG_Slider(3) widget is a good example of a widget supporting multiple bindings. The value, min and max bindings can be associated with floating-point numbers or integers:

int myMin = 0, myMax = 100, myValue = 50;
AG_Slider *sl;
sl = AG_SliderNew(parent, 0, AG_SLIDER_HORIZ, 0);
AG_BindInt(sl, "min", &myMin);
AG_BindInt(sl, "max", &myMax);
AG_BindInt(sl, "value", &myValue);

Floating-point numbers are handled in the same manner:

float myMin = 0.0, myMax = 100.0, myValue = 50.0;
AG_Slider *sl;
sl = AG_SliderNew(parent, 0, AG_SLIDER_HORIZ, 0);
AG_BindFloat(sl, "min", &myMin);
AG_BindFloat(sl, "max", &myMax);
AG_BindFloat(sl, "value", &myValue);

See also

• Writing thread-safe widgets
• AG_Object(3), AG_Variable(3), AG_Widget(3), AG_Button(3), AG_Slider(3), AG_Textbox(3)