ReqTools tagging systemReqTools APIsHis fear was already gone; it had slipped away from him as easily as a nightmare slips away from a man who awakes, cold-skinned and gasping, from its grip; who feels his body and stares at his surroundings to make sure that none of it ever happened and who then begins at once to forget it. Half is gone by the time his feet hit the floor; three-quarters of it by the time he emerges from the shower and begins to towel off; all of it by the time he finishes his breakfast. All gone... until the next time, when, in the grip of the nightmare, all fears will be remembered. | ||
| --Stephen King, IT | ||
Implementing Reqtools inside your own program should be fairy simple, because all requesters
are created using one single call, which is: reqtools_requester().
As you'll see, it is a pretty flexible function that, using TAGS, can be customized at your will.
Before going every further into details, let's see a small example that will show you how to use Reqtools to generate the classical Easy Requester.
Example 2-1. Reqtools Easy Request (full example)
#include <reqtools/reqtools.h>
int main ()
{
AFC * afc;
Reqtools * rt;
int res;
afc = afc_new (); /* Needed by AFC */
rt = reqtools_new ( afc ); /* Alloc the Reqtools instance */
gtk_init ( NULL, NULL ); /* Needed by GTK+ */
res = reqtools_requester ( rt, REQTOOLS_EASY_REQUEST,
REQTOOLS_TAG_TITLE, "Easy Requester",
REQTOOLS_TAG_TEXT, "This is en Easy Reqyester. Do you like it?",
REQTOOLS_TAG_BUTTONS, "Great!|Yes|Not very much|Not at all",
REQTOOLS_TAG_WINDOW_WIDTH, 0,
REQTOOLS_TAG_WINDOW_HEIGHT, 0,
REQTOOLS_TAG_DEFAULT_BUTTON, 2,
REQTOOLS_TAG_END, REQTOOLS_TAG_END ) );
printf ( "Result: %d\n", res );
reqtools_delete ( rt );
afc_delete ( afc );
return ( 0 );
}
|
As you can see from the listing, the first thing you need to do is init AFC, ReqTools
and GTK+ (which is used by ReqTools).
These lines of code should appear at the very beginning of your program, and they should appear
only once.
The next line of our example, is already showing you a requester. Here you can see the tagging technique, presented in the features section.
The function synopsis for reqtools_requester is the following:
Pointer to a valid ReqTools instance.
The requester you intend to display
Tagged values you want to pass to the requester
reqtools_requester function works.
As you can see from the function prototype, reqtools_requester always returns an int.
You'll learn about it later, but you should know that it rappresents the user choice. All requester should
have at least an OK and Cancel button. The return code of
reqtools_requester is always 0 when the user aborted the requester
(by clicking on cancel, or closing the window) and the ordinal number of the button
pressed in case the user selected something.
So, to follow our example, if the user pressed Great!, the return value would be 1,
and it he/she pressed Not very much, the return value would be 3.