int initapp(int argc, char **argv); /* initialise library */ void mainloop(void); /* handle all events */ int peekevent(void); /* is there an event? */ int doevent(void); /* handle one event */ int execapp(char *cmd); /* execute an application */ void exitapp(void); /* exit application */ void apperror(char *msg); /* exit with message */
The program begins in the main function, which can be defined in any of the normal ways.
The function initapp initialises the structures and variables necessary to use the graphics library's interface. It takes parameters argc and argv from the main function and uses them to initialise variables on the X-Windows platform only, stripping X arguments from the argv array in the process and returning the new value of argc, or zero if an error occurred. For many purposes this function need not be explicitly called.
The mainloop function is called after initialisation of graphical objects. It polls the windowing system for events and dispatches them to the appropriate callback functions. The mainloop function will terminate when there are no windows visible. The library arranges for this function to be called before normal program termination, so an explicit call to this function is unnecessary in most cases.
The peekevent is true when there are events to be processed in the event queue. The doevent function is called repeatedly by the mainloop function to process and dispatch single events. It is generally not called explicitly.
The execapp function launches the specified application, returning 1 on success and 0 on failure. This function exists because the standard C function system is not always implemented on all platforms (e.g. MS-Windows).
The exitapp function can be used to terminate the program. This function replaces the normal exit function, since certain platforms require a program to explicitly release the memory used for graphics. The exitapp function is not needed for normal program termination.
The apperror function displays an error message in a window and then stops the application using exitapp.
Here is an example program skeleton:
int main(int argc, char *argv[])
{
/* some initialisation code here */
argc = initapp(argc, argv);
if (argc == 0)
apperror("Couldn't initialise the graphics library.");
/* rest of initialisation and drawing code here */
mainloop();
exitapp();
}
In practice the initapp function is not needed, since the library arranges for it to be called automatically if it hasn't already been called. Both the mainloop and the exitapp functions generally aren't necessary in normal programs either, so the simplest program could be:
void main(void)
{
gprintf("Hello World!");
}
However, it is good practice to call mainloop before the end of the main function. It is also a good idea to call initapp and check the return value, to handle the case that a graphical program is being run on a non-graphical terminal.