The Dialogs utility provides three types of dialog boxes: simple dialog boxes,
input boxes, and empty boxes.
The function to draw a simple dialog box is defined in "dialogs.h" as:
int msgBox(char *msg, int buttons, msgtype tmsg);
Where:
The value of buttons can be: OK, OK|CANCEL, YES|NO, or OK|CANCEL|ALL.
Note when using two or more 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 #define ALL 16 //00010000 #define ABORT 32 //00100000
The value of tsmg can be:
The function to draw a simple dialog box is defined in "dialogs.h" as:
char* inputBox(char *msg, char *title);
Where:
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.
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:
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 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.