Initialisation and Event Handling

HEADERS

  #include <stdio.h>
  #include <graphapp.h>

OBJECTS

  typedef struct App  App;

  struct App {
    int       gui_available;    /* is the GUI available? */
    Rect      screen_area;      /* screen pixel dimensions */
    Rect      screen_mm;        /* size in millimetres */
    int       num_windows;      /* a list of windows */
    Window ** windows;
    int       visible_windows;  /* how many windows visible */
    int       fonts_loaded;     /* a list of loaded fonts */
    Font **   fonts;
    char *    program_name;     /* absolute path to program */
    int       has_resources;    /* is it a resource file? */
    void *    data;             /* user-defined data */
    void *    extra;            /* platform-specific data */
  };

FUNCTIONS

  int   main(int argc, char **argv);        /* definition of main */

  App * new_app(int argc, char **argv); /* initialise library */
  void  del_app(App *app);              /* shut-down program */

  void  main_loop(App *app);            /* handle all events */
  int   peek_event(App *app);           /* is there an event? */
  int   wait_event(App *app);           /* wait for one event */
  int   do_event(App *app);             /* handle one event */

  int   exec(App *app, char *cmd);      /* execute a program */

  void  error(App *app, char *message); /* exit with message */

NOTES

The two header files which must be included in any GraphApp program are named <stdio.h> and <graphapp.h>, and they must be included in that order, since the GraphApp functions make use of the stdio FILE type. Programs begin, as usual, in the main function, which must be defined as above.

The function new_app initialises the structures and variables necessary to use the graphics library's interface, storing the data into a structure called an App, and returning a pointer to it. This pointer is required by other functions. If there is no memory remaining, NULL will be returned. If the program is being run from a non-graphical terminal, the structure will still be created, the gui_available field will be set to zero, and some functions will still work, such as drawing into images, but functions which require access to the windowing system, such as creating a window, or drawing to a bitmap, will not work.

If the graphical user interface could be initialised, the gui_available field will be set to non-zero. The screen_area field will be initialised to the screen's dimensions in pixels. Typically the x and y fields of this rectangle will be zero, while the width and height fields will contain the size of the screen in pixels. The screen_mm field will contain the dimensions of the screen in millimetres (there are 25.4 millimetres in an inch).

The function takes parameters argc and argv from the main function and searches them for interface-specific options (such as those found in X-Windows environments). If it finds any such initialisation parameters, it removes them from the argv list by moving the next parameters forwards in the list, and argc will be invalid after this process (a NULL value in the argv array now signals the end of parameters).

The del_app function is called at the end of the program. It closes all windows and releases from the memory the App structure.

The main_loop function is called after creation of graphical objects, such as windows and controls. It polls the windowing system for events and dispatches them to the appropriate callback functions. The function will terminate when there are no windows visible. It is thus possible to call this function again if other windows become visible.

The peek_event is true when there are events to be processed in the event queue. It is rarely used, since it polls the windowing system each time.

The do_event function checks if there is an event to be processed, and if there is, dispatches it. It returns zero only if there are no more events possible, for instance, if there are no visible windows. It is generally not used, since it polls the windowing system each time it is called.

The wait_event function waits until an event is available, then handles that event using do_event. If there are no more events possible, it returns zero. It is called repeatedly by the main_loop function to handle events.

The exec 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 error function displays an error message in a window and then stops the application.

EXAMPLES

Here is an example program skeleton:

  #include <stdio.h>
  #include <graphapp.h>

  int main(int argc, char *argv[])
  {
    App *app;

    /* some initialisation code here */
    app = new_app(argc, argv);
    if ((app == NULL) || (app->gui_available == 0))
      error(app, "Couldn't initialise the graphics library.");
    /* rest of initialisation and drawing code here */
    main_loop(app);
    del_app(app);
    return 0;
  }