Next: , Up: Part I Goodies   [Contents][Index]


6.1 Messages and Questions

The following routines are meant to give messages to the user and to ask simple questions:

void fl_show_message(const char *s1, const char *s2, const char *s3);

It shows a simple form with three lines of text and a button labeled OK on it. The form is so shown such that the mouse pointer is on the button.

Sometimes, it may be more convenient to use the following routine

void fl_show_messages(const char *str);

when the message is a single line or when you know the message in advance. Embed newlines in str to get multi-line messages.

As a third alternative you can also use

void fl_show_messages_f(const char * fmt, ...);

The only required argument fmt is a format string as you would use it for e.g., printf(3), which then is followed by as many arguments as there are format specifiers in the format string. The string resulting from expanding the format string, using the remaining arguments, can have arbitrary length and embedded newline characters ('\n'), producing line breaks. The size of the message box is automatically made to fit the whole text.

Both of the message routines block execution and do not return immediately (but idle callbacks and asynchronous IO continue to be run and checked). Execution resumes when the OK button is pressed or <Return> is hit, or when the message form is removed from the screen by the following routine (for example, triggered by a timeout or idle callback):

void fl_hide_message(void)

There is also a routine that can be used to show a one-line message that can only be removed programmatically

void fl_show_oneliner(const char *str, FL_Coord x, FL_Coord y);
void fl_hide_oneliner(void);

where str is the message and x and y are the coordinates (relative to the root window) the message should be placed. Note that multi-line messages are possible by embedding the newline character into str. See the demo program preemptive.c for an example of its use.

By default, the background of the message is yellow and the text black. To change this default, use the following routine

void fl_set_oneliner_color(FL_COLOR background, FL_COLOR textcol);

A similar routine exists to change the font style and size

void fl_set_oneliner_font(int style, int size);
void fl_show_alert(const char *s1, const char *s2, const char *s3,
                   int centered);
void fl_hide_alert(void);

work the same as fl_show_messages() goodie except that an alert icon (!) is added and the first string is shown bold-faced. The extra parameter centered controls whether to display the form centered on the screen.

As in the case of messages also another function is avaialble

void fl_show_alert2(int centered, const char *fmt, ...);

centered controls if the alert message is centered and fmt must be a format string as e.g., used for printf(3). After the format string as many further arguments are required as there are format specifiers in the format string. The string resulting from expanding the format string, using the rest of the arguments, can have arbitrary length and the first embedded form-feed character ('\f') is used as the separator between the title string and the message of the alert box. Embedded newline characters ('\n') produce line breaks.

In combination with fl_add_timeout(), it is easy to develop a timed alert routine that goes away when the user pushes the OK button or when a certain time has elapsed:

static void dismiss_alert(int ID, void *data) {
    fl_hide_alert();
}

void show_timed_alert(const char *s1, const char *s2,
                      const char *s3, int centered) {
    fl_add_timeout( 10000, dismiss_alert, 0 ); /* ten seconds */

    /* fl_show_alert blocks, and returns only when the OK button
       is pushed or when the timeout, in this case, 10 seconds,
       has elapsed */

    fl_show_alert(s1, s2, s3, centered);
}

Then you can use show_timed_alert() just as fl_show_alert() but with added functionality that the alert will remove itself after 10 seconds even if the user does not push the OK button.

int fl_show_question(const char *message, int def);
void fl_hide_question(void);

Again shows a message (with possible embedded newlines in it) but this time with a Yes and a No button. def controls which button the mouse pointer should be on: 1 for Yes, 0 for No and any other value causes the form to be shown so the mouse pointer is at the center of the form. It returns whether the user pushed the Yes button. The user can also press the <Y> key to mean Yes and the <N> key to mean No.

If the question goodie is removed programmatically via fl_hide_question(), the default def as given in fl_show_question() is taken. If no default is set, 0 is returned by fl_show_question(). The following code segment shows one way of using fl_hide_question()

void timeout_yesno(int id, void *data) {
    fl_hide_question();
}

...

fl_add_timeout(5000, timeout_yesno, 0);

/* show_question blocks until either timeouts or
   one of the buttons is pushed */

if (fl_show_question("Want to Quit ?", 1))
    exit(0);

/* no is selected, continue */

...  /* rest of the code *.

In the above example, the user is given 5 seconds to think if he wants to quit. If within the 5 seconds he can’t decide what to do, the timeout is triggered and fl_show_question() returns 1. If, on the other hand, he pushes the No button before the timeout triggers, fl_show_question() returns normally and fl_hide_question() becomes a no-op.

int fl_show_choice(const char *s1, const char *s2, const char *s3,
                   int numb, const char *b1, const char *b2,
                   const char *b3, int def);

int fl_show_choices(const char *s, int numb,
                    const char *b1, const char *b2, const char *b3,
                    int def);

void fl_set_choices_shortcut(const char *s1, const char *s2,
                             const char *s3);

void fl_hide_choice(void);

The first routine shows a message (up to three lines) with one, two or three buttons. numb indicates the number of buttons. b1, b2 and b3 are the labels of the buttons. def can be 1, 2 or 3, indicating the default choice. The second routine is similar to the first except that the message is passed as a single string with possible embedded newlines in it. Both routines return the number of the button pressed (1, 2 or 3). The user can also press the <1>, <2> or <3> key to indicate the first, second, or third button. More mnemonic hotkeys can be defined using the shortcut routine, s1, s2 and s3 are the shortcuts to bind to the three buttons. If the choice goodie is removed by fl_hide_choice(), the default def is returned.

To change the font used in all messages, use the following routine

void fl_set_goodies_font(int style, int size);

To obtain some text from the user, use the following routine

const char *fl_show_input(const char *str1, const char *defstr);
void fl_hide_input(void);

This shows a box with one line of message (indicated by str1), and an input field into which the user can enter a string. defstr is the default input string placed in the input box. In addition, three buttons, labeled Cancel, OK and Clear respectively, are added. The button labeled Clear deletes the string in the input field. The routine returns the string in the input field when the user presses the OK button or the <Return> key. The function also returns when button Cancel is pressed. In this case, instead of returning the text in the input field, NULL is returned. This routine can be used to have the user provide all kinds of textual input.

Removing the input field programmatically by calling fl_hide_input() results in NULL being returned by fl_show_input(), i.e., it’s equivalent to pressing the Cancel button.

A similar but simpler routine can also be used to obtain textual input

const char *fl_show_simple_input(const char *str1, const char *defstr);

The form shown in this case only has the OK button. The example program goodies.c shows you these goodies.

It is possible to change some of the built-in button labels via the following resource function with proper resource names

void fl_set_resource(const char *res_str, const char *value)

To, for example, change the label of the Dismiss button to "Go" in the alert form, code similar to the following can be used after calling fl_initialize() but before any use of the alert goodie:

fl_set_resource("flAlert.dismiss.label", "Go");

Currently the following goodies resources are supported:

flAlert.title

The window title of the alert goodie

flAlert.dismiss.label

The label of the Dismiss button

flQuestion.yes.label

The label of the Yes button

flQuestion.no.label

The label of the No button

flQuestion.title

The window title of the Question goodie

flChoice.title

The window title of the Choice goodie

*.ok.label

The label of the OK button

Note that all goodies are shown with FL_TRANSIENT and not all window managers decorate such forms with titles. Thus the title setting in the above listing may not apply.


Next: , Up: Part I Goodies   [Contents][Index]