Messages and Questions (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Command Log, 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: Command Log, Up: Part I Goodies [Contents][Index]