GnuDOS library version 1.0: Dialogs

Next: Screen, Previous: Kbd, Up: Top [Contents][Index]

## 5 Using the Dialogs utility

The Dialogs utility provides three types of dialog boxes: simple dialog boxes, input boxes, and empty boxes.

### Simple Dialog Box

The function to draw a simple dialog box is defined in "dialogs.h" as:

    int msgBox(char *msg, int buttons, msgtype tmsg);

Where:

- msg: is a pointer to the string that will be the output message of the dialog box
- buttons: an integer value defining the number and type of buttons to be displayed (see below)
- tmsg: a value of type "msgtype" (see below) defining the type of dialog box. This will be the title of the dialog

The value of `buttons` can be: OK, OK|CANCEL, or YES|NO. Note when using two buttons they need to be ORed with the vertical bar. The macros defining those buttons are declared in "dialogs.h" as:

    //buttons used in message boxes//
    #define OK	1	//00000001
    #define YES	2	//00000010
    #define CANCEL	4	//00000100
    #define NO	8	//00001000

The value of `tsmg` can be:

- - INFO: This is an information box. The title will be "INFORMATION"
- - ERROR: This is an error message box. The title will be "ERROR"
- - CONFIRM: This is a confirmation dialog box. The title will be "CONFIRMATION"

### Input boxes

The function to draw a simple dialog box is defined in "dialogs.h" as:

    char* inputBox(char *msg, char *title);

Where:

- msg: is a pointer to the string that will be the output message of the dialog box
- title: is a pointer to the string that will be the title of the input box

The function returns the user input as a char pointer. If the user entered nothing, or pressed CANCEL button or ESC, the function returns NULL. You can also access the return value in the globally accessed variable ’input’, which is defined:

    char input[MAX_INPUT_MSG_LEN+1];	//input string returned by inputBox() function

Another function for drawing input boxes is defined:

    char* inputBoxI(char *msg, char *inputValue, char *title);

The only difference is that it takes as the second parameter a string that will be displayed in the input box as an initial input value for the user. This is helpful if you want to give the user a default value for whatever input is required from the user. The user can change the input or just press ENTER and accept the default value.

### Empty boxes

Drawing empty boxes or windows is done via one of two functions:

    void drawBox(int x1, int y1, int x2, int y2, char *title, int clearArea);
    void drawBoxP(point p1, point p2, char *title, int clearArea);

They basically do the same thing, except that drawBoxP() accepts the window coordinates as two ’point’ structures which are defined as:

    typedef struct { int row; int col; } point;

Whereas the drawBox() function accepts coordinates as four integer values. The explanation of the parameters to the two functions is as follows:

- x1: The x-coordinate (row) of the upper left corner
- y1: The y-coordinate (column) of the upper left corner
- x2: The x-coordinate (row) of the lower right corner
- y2: The y-coordinate (column) of the lower right corner
- char *title: A string pointer to the title of the dialog box
- int clearArea: A boolean value indicating whether to clear the box area (YES=clear, NO=don’t clear). Not clearing the box area can be handy when, for example, you need to redraw the window frame but leave the window contents intact.

Other things of concern are:

    int MAX_MSG_BOX_W;
    int MAX_MSG_BOX_H;
    #define MAX_INPUT_MSG_LEN 100

The first two are global variables used to determine the maximum size of a dialog box. MAX_MSG_BOX_W defines the maximum width (columns) and MAX_MSG_BOX_H the maxium height (rows). Their values are calculated in the msgBox() and inputBox() functions as:

    MAX_MSG_BOX_W = SCREEN_W-2;
    MAX_MSG_BOX_H = SCREEN_H-2;

The last one, MAX_INPUT_MSG_LEN is a macro defining the maximum length of the input string returned by an input box. Currently it is restricted to 100 chars.

### The catchSignals() function

The last two functions of "dialogs.h" are:

    int catchSignals();
    int catchAllSignals();

Which are handy and so important. Remember that after a call to initTerminal() the terminal will be in an intermediate state, which is not of much use to the user. Calling restoreTerminal() is an important step to do before leaving your program. But what if your program crashed for whatever reason? (bad things happen all the time), or if a system administrator decided to kill your process?. Here is what catchSignals() does: it catches all the important signals (namely: SIGINT, SIGQUIT, SIGABRT, and SIGTERM) and passes them to a signal handler, which you will define as:

    void sighandler(int signo)
    {
        //do what ever needs to be done here. The following line is just an example.
        fprintf(stderr, "SIGNAL %d received\n", signo);
    }

The catchAllSignals() does the same, except it tries to catch also SIGSTP, SIGKILL, and SIGSTOP. It is a futile effort of course, as these signals can’t be caught, it is just included for convenience.
If either function succeeds in catching the signals, it will return 1. Otherwise, 0. Expect catchAllSignals() to return 0 at all times because of the reason above.
Note that you will need to define the signal handler even if you will not use the catchSignals() function (which is, by the way, not recommended at all! We explained the reasons several times above). It can be defined as an empty function as:

    void sighandler(int signo)
    {
    }

Again, please define the signal handler in a proper way whenever possible.

Next: Screen, Previous: Kbd, Up: Top [Contents][Index]