A button widget is a button that a user can click on with the left mouse button to indicate an action. When a button is pressed, it is drawn in inverse video and some action takes place.
A button is connected to your code by a callback function which is called when the user clicks on the button widget with the left mouse button.
Widget MakeButton(char *label, ButtonCB func, void *data);
This function creates a small rectangular button which the user can click on. The character string pointed at by "label" will be printed inside the button. If the string has newline characters in it, they will be interpreted properly (i.e. you will get a multiline label). The next two arguments are a callback function, func, and an arbitrary data pointer, data, that will be passed to the function func.
If you plan to attach a bitmap to this widget, you can specify NULL for the label text (see the docs for SetWidgetBitmap() .
When the button is pressed, the function, "func" will be called. The function, func, will have two arguments. The first argument is the widget that user clicked on (which you can ignore if you do not need it). The second argument is the void pointer, 'data', specified in the call to MakeButton(). The function "func" should be declared as follows:
void func(Widget w, void *data)
{
/* your code goes here */
}
The last argument (called "data") is the same as the last argument to the MakeButton() function call. It is declared as a void pointer and you can cast to whatever type you need. Generally you'll have something like:
MyProgram *me = (MyProgram *)data;
You use "buttons" to allow the user to indicate various actions (things like load, save, cut, copy, and paste operations are good examples). The mental model of how a button works is that when the user clicks on the button with the mouse, the function you specify is called.
If something goes wrong in creating the button, a NULL value is returned. This is a rare occurrence, but good code will still check for it.
SEE ALSO : SetWidgetPos() , SetWidgetBitmap() , SetLabel(), SetWidgetFont() , SetFgColor() , SetBgColor() , SetBorderColor()