<title> Buttons </title>

<ul>
 <li> <a href="#IB"> Introduction to Buttons </a>
 <li> <a href="#fMB"> MakeButton </a>
</ul>
<p>
<h2> <a name="IB"> Introduction to Buttons </a> </h2>
<p>
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.
<p>
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.  
<hr>
<p>
<a name="fMB">
<b> Widget MakeButton(char *label, ButtonCB func, void *data); </b>
</a>
<p>
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.
<p>
If you plan to attach a bitmap to this widget, you can specify NULL
for the label text (see the docs for 
<a href="misc.html#fSWB">         SetWidgetBitmap() </a>.
<p>
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 <tt>MakeButton()</tt>.  The function "func" should be declared as
follows:
<p>
<pre>
    void func(Widget w, void *data)
     {
          /* your code goes here */
     }
</pre>
<p>
The last argument (called "data") is the same as the last argument to
the <tt>MakeButton()</tt> function call.  It is declared as a void pointer and
you can cast to whatever type you need.  Generally you'll have
something like:
<p>
<pre>
    MyProgram *me = (MyProgram *)data;
</pre>
<p>
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.
<p>
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.
<p>
SEE ALSO :  
<a href="misc.html#fSWP">         SetWidgetPos() </a>, 
<a href="misc.html#fSWB">         SetWidgetBitmap() </a>, 
<a href="label.html#fSL">	SetLabel()</a>,
<a href="font.html#fSWF">         SetWidgetFont() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSBC2">        SetBorderColor() </a>