6. Goodies

A number of special routines are provided that make working with simple forms even simpler. All these routines build simple forms and handle the interaction with the user.

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_msg(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 expansion of 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 coordinate (relative to the root window) the message should be placed. Note that multi-line message is possible by embedding the newline character in 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 expansion of the format string using the rest of the arguents 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.

6.2 Command Log

In a number of situations, a GUI is created specifically to make an existing command-line oriented program easier to use. For stylistic considerations, you probably don't want to have the output (stderr and stdout) as a result of running the command printed on the terminal. Rather you want to log all the messages to a browser so the user can decide if and when to view the log. For this, a goodie is available

long fl_exe_command(const char *cmd, int block);

This function, similar to a system(3) call, forks a new process that runs the command cmd, which must be a (null-terminated) string containing a shell command line. The output (both stderr and stdout) of cmd is logged into a browser, which can be presented to the user when appropriate (see below). The block argument is a flag indicating if the function should wait for the child process to finish. If the argument block is true (non-zero), the function waits until the command cmd completes and then returns the exit status of the command cmd. If the argument block is false (0), the function returns immediately without waiting for the command to finish. In this case, the function returns the process ID of the child process or -1 if an error occured.

Unlike other goodies, fl_exe_command() does not deactivate other forms even in blockng mode. This means that the user can interact with the GUI while fl_exe_command() waits for the child process to finish. If this is not desired, you can use fl_deactivate_all_forms() and fl_activate_all_forms() to wrap the function.

If fl_exe_command() is called in non-blocking mode, the following function should be called to clean up related processes and resources before the caller exits (otherwise a zombie process may result)

int fl_end_command(long pid);

where pid is the process ID returned by fl_exe_command(). The function suspends the current process and waits until the child process is completed, then it returns the exit status of the child process or -1 if an error has occurred.

There is another routine that will wait for all the child processes initiated by fl_exe_command() to complete

int fl_end_all_command(void)

The function returns the status of the last child process.

You can also poll the status of a child process using the following routine

int fl_check_command(long pid);

where pid is the process ID returned by fl_exe_command(). The function returns the following values: 0 if the child process is finished; 1 if the child process still exists (running or stopped) and -1 if an error has occurred inside the function.

If some interaction with the command being executed is desired, the following functions may be more appropriate. These functions operates almost exactly as the popen(3) and pclose(3) functions:

FILE *fl_popen(const char *command, const char *type);
int fl_pclose(FILE *stream);

The fl_popen() function executes the command in a child process, and logs the stderr messages into the command log. Further, if type is "w", stdout will also be logged into the command browser. fl_pclose() should be used to clean up the child process.

To show or hide the logs of the command output, use the following functions

int fl_show_command_log(int border);
void fl_hide_command_log(void);

where border is the same as that used in fl_show_form(). These two routines can be called anytime anywhere after fl_initialize() has been invoked.

The command log is by default placed at the top-right corner of the screen. To change the default placement, use the following routine

void fl_set_command_log_position(int x, int y);

where x and y are the coordinates of the upper-left corner of the form relative to the root window. The logging of the output is accumulative, i.e. fl_exe_command() does not clear the browser. To clear the browser, use the following routine

void fl_clear_command_log(void);

It is possible to add arbitrary text to the command browser via the following routine

void fl_addto_command_log(const char *s);

where s is a (null-terminated) string with possible embedded newlines. The string s is added to the browser using fl_addto_browser_chars(), i.e. the string is appended after the last line in the browser.

Finally, there is a routine that can be used to obtain the GUI structure of the command browser

typedef struct {
    FL_FORM   * form;           /* the form */
    FL_OBJECT * browser;        /* the browser */
    FL_OBJECT * close_browser;  /* the Close button */
    FL_OBJECT * clear_browser;  /* the Clear button */
} FD_CMDLOG;

FD_CMDLOG *fl_get_command_log_fdstruct(void);

From the information returned, the application program can change various attributes of the command browser and its associated objects. Note however, that you should not hide/show the form or free any member of the structure.

6.3 Colormap

In a number of applications the user has to select a color from the colormap. For this a goody has been created. It shows the first 64 entries of the colormap. The user can scroll through the colormap to see more entries. Once the user presses the mouse one of the entries the corresponding index is returned and the colormap is removed from the screen. To display the colormap use the routine

int fl_show_colormap(int oldcol);

oldcol should be the current or default color. The user can decide not to change this color by pressing the Cancel button in the form. The procedure returns the index of the color selected (or the index of the old color).

6.4 File Selector

The most extended predefined form is the file selector. It provides an easy and interactive way to let the user select files. It is called as follows:

const char *fl_show_fselector(const char *message, 
                              const char *directory,
                              const char *pattern,
                              const char *default);

A form will be shown in which all files in directory directory are listed that satisfy the pattern pattern (see Fig 6.1). pattern can be any kind of regular expression, e.g. [a-f]*.c, which would list all files starting with a letter between a and f and ending with .c. default is the default file name. message is the message string placed at the top of the form. The user can choose a file from the list given and the function then returns a pointer to a static buffer that contains the filename selected, or NULL if the Cancel button is pressed (see below).

The user can also walk through the directory structure, either by clicking on the box with the name of the currently displayed directory to edit it manually, or by double-clicking on the name of a directory (shown with a 'D' in front of it) shown in the list. If the directory content changes while it is being displayed in the file selector the ReScan button can be used to request a rescan of the directory.

In a typical application, once the file selector goodie is shown, it is up to the user when the file selector should be dismissed by pushing Ready or Cancel button. In some situations the application may want to remove the file selector on it's own. To this end, the following routine is available

void fl_hide_fselector(void);

The effect of removing the file selector programmatically is the same as pushing the Cancel button. There are total of FL_MAX_FSELECTOR (6) file selectors in the Forms Library with each having its own current directory and content cache. All the file selector functions documented manipulate the currently active file selector, which can be set using the following routine

int fl_use_fselector(int n);

where n is a number between 0 and FL_MAX_FSELECTOR - 1.

To change the font the file selector uses, the following routine can be used:

void fl_set_fselector_fontsize(int font_size);
void fl_set_fselector_fontstyle(int font_style);

These routines change the font for all the objects on the form. It is possible to change the font for some of the objects (e.g., browser only) using fl_get_fselector_fdstruct() explained later.

The window title of the file selector can be changed anytime using the following routine

void fl_set_fselector_title(const char *title);

To force an update programmatically, call

void fl_invalidate_fselector_cache(void);

before fl_show_fselector(). Note that this call only forces an update once, and on the directory that is to be browsed. To disable caching altogether, the following routine can be used:

void fl_disable_fselector_cache(int yes);

A false (0) parameter (re)enables directory caching.

The user can also change the pattern by clicking the mouse on top of it it. Note that directories are shown independent of whether they satisfy the pattern. He can also type in a file name directly.

Complete keyboard navigation is built-in. E.g., you can use <Alt>d to change the directory instead of using the mouse.

When the user is satisfied, i.e., found the correct directory and indicated the file name required, he can press the button labeled Ready or press the <Return> key. He can also double click on the file name in the browser. The full path to the filename is returned by the procedure. If the user presses the Cancel button NULL is returned.

It is also possible to set a callback routine so that whenever the user double clicks on a filename, instead of returning the filename, the callback routine is invoked with the filename as the argument. To set such a callback, use the following routine

void fl_set_fselector_callback(int (*callback)(const char *, void *),
                               void *user_data);

where the second argument of the callback is the user data. The return value of the callback function is currently not used. Note that the behavior of the file selector is slightly different when a callback is present. Without the callback, a file selector is always modal.

Please note that when a file selector has a callback installed the field for manually entering a file name isn't shown.

The placement of the file selector is by default centered on the screen, which can be changed by the following routine

void fl_set_fselector_placement(int place);

where place is the placement request same as in fl_show_form(). The default is FL_PLACE_CENTER | FL_FREE_SIZE.

By default, an fselector is displayed with transient property set. To change the default, use the following routine

void fl_set_fselector_border(int border);

The border request by this function is the same as in fl_show_form(), but FL_NOBORDER is ignored.

If the arguments directory, pattern or default passed to fl_show_form() are empty strings or NULL, the previous value is used (with some reasonable defaults getting used when this happens the first time). Thus the file selector "remembers" all the settings the selector had last time. The application program can figure out the directory, pattern and file name (without the path) after the user changed them using the routines

const char *fl_get_directory(void);
const char *fl_get_pattern(void);
const char *fl_get_filename(void);

It is also possible to programatically set new values for the default directory and pattern by using the functions

int fl_set_directory( const char * dir );
void fl_set_pattern( const char * pattern );

fl_set_directory() returns 0 on success and 1 on failure, either because the argument was a NULL pointer or not a valid directory.

There are other routines that make the fselector more flexible. The most important of which is the ability to accommodate up to three application specific button:

void fl_add_fselector_appbutton(const char *label,
                                void (*callback)(void *),
                                 void *data);

The argument data is passed to the callback. Whenever this application specific button is pushed, the callback function is invoked.

To remove an application specific button, use the following routine

void fl_remove_fselector_appbutton(const char *label);

Within the callback function, in addition to using the routines mentioned above, the following routines can be used:

void fl_refresh_fselector(void);

This function causes the file selector to re-scan the current directory and to list all entries in it.

If, for whatever reasons, there is a need to get the fselector's form the following routine can be used:

FL_FORM *fl_get_fselector_form(void);

See `fbrowse.c' for the use of the file selector.

Although discouraged, it is recognized that direct access to the individual objects of a fselector's form maybe necessary. To this end, the following routine exists

typedef struct {
    FL_FORM   * fselect;
    void      * vdata;
    char      * cdata;
    long        ldata;
    FL_OBJECT * browser,
              * input,
              * prompt,
              * resbutt;
    FL_OBJECT * patbutt,
              * dirbutt,
              * cancel,
              * ready;
    FL_OBJECT * dirlabel,
              * patlabel;
    FL_OBJECT * appbutt[3];
} FD_FSELECTOR;

FD_FSELECTOR *fl_get_fselector_fdstruct(void);

You can, for example, change the default label strings of various buttons via members of the FD_FSELECTOR structure:

FD_FSELECTOR *fs = fl_get_fselector_fdstruct();

fl_set_object_label(fs->ready, "Go !");
fl_fit_object_label(fs->ready, 1, 1);

Since the return value of fl_get_fselector_fdstruct() is a pointer to an internal structures, the members of this structure should not be modified.

In the listing of files in a directory special files are marked with a prefix in the browser (for example, D for directories, p for pipes etc.). To change the prefix, use the following routine

void fl_set_fselector_filetype_marker(int dir,
                                      int fifo,
                                      int socket,
                                      int cdev,
                                      int bdev);

where dir is the marker character for directories, fifo the marker for pipes and FIFOs, socket the marker for sockets, cdev the marker for character device files and, finally, bdev the marker character for block device files.

Although file systems under Unix are similar, they are not identical. In the implementation of the file selector, the subtle differences in directory structures are isolated and conditionally compiled so an apparent uniform interface to the underlying directory structure is achieved.

To facilitate alternative implementations of file selectors, the following (internal) routines can be freely used:

To get a directory listing, the following routine can be used

const FL_Dirlist *fl_get_dirlist(const char *dirname,
                                 const char *pattern,
                                 int *nfiles, int rescan);

where dirname is the directory name; pattern is a regular expression that is used to filter the directory entries; nfiles on return is the total number of entries in directory dirname that match the pattern specified by pattern (not exactly true, see below). The function returns the address of an array of type FL_Dirlist with nfiles if successful and NULL otherwise. By default, directory entries are cached. Passing the function a true (non-zero) value for the rescan argument requests a re-read.

FL_Dirlist is a structure defined as follows

typedef struct {
    char          * name;        /* file name */
    int             type;        /* file type */
    long            dl_mtime;    /* file modification time */
    unsigned long   dl_size;     /* file size in bytes */
} FL_Dirlist;

where type is one of the following file types

FT_FILE

a regular file

FT_DIR

a directory

FT_SOCK

a socket

FT_FIFO

a pipe or FIFO

FT_LINK

a symbolic link

FT_BLK

a block device

FT_CHR

a character device

FT_OTHER

?

To free the list cache returned by fl_get_dirlist(), use the following call

void fl_free_dirlist(FL_Dirlist *dl);

Note that a cast may be required to get rid of compiler warnings due to the const qualifier of the return value of fl_get_dirlist(). See demo program `dirlist.c' for an example use of fl_get_dirlist().

Per default not all types of files are returned by fl_get_dirlist(). The specific rules for which types of file are returned are controlled by an additional filter after the pattern filter. It has the type

int default_filter(const char *name, int type);

and is called for each entry found in the directory that matched the pattern. This filter function should return true (non-zero) if the entry is to be included in the directory list. The default filter is similar to the following

int ffilter(const char *name, int type) {
    return type == FT_DIR || type == FT_FILE || type == FT_LINK;
}

i.e. per default only directories, normal files and symbolic links are shown (the first argument of the function, the file name, isn't used by the default filter).

To change the default filter, use the following routine

typedef int (*FL_DIRLIST_FILTER)(const char *, int);
FL_DIRLIST_FILTER fl_set_dirlist_filter(FL_DIRLIST_FILTER filter);

As noted before, directories are by default not subject to filtering. If, for any reason, it is desirable to filter also directories, use the following routine with a true flag

int fl_set_dirlist_filterdir(int flag);

The function returns the old setting. Since there is only one filter active at any time in XForms, changing the filter affects all subsequent uses of file browsers.

By default, the files returned are sorted alphabetically. You can change the default sorting using the following routine:

int fl_set_dirlist_sort(int method);

where method can be one of the following

FL_NONE

Don't sort the entries

FL_ALPHASORT

Sort the entries in alphabetic order - this is the default

FL_RALPHASORT

Sort the entries in reverse alphabetic order

FL_MTIMESORT

Sort the entries according to the modification time

FL_RMTIMESORT

Sort the entries according to the modification time, but reverse the order, i.e., latest first.

FL_SIZESORT

Sort the entries in increasing size order

FL_RSIZESORT

Sort the entries in decreasing size order

FL_CASEALPHASORT

Sort the entries in alphabetic order with no regard to case

FL_RCASEALPHASORT

Sort the entries in reverse alphabetic order with no regard to case.

The function returns the old sort method. For directories having large numbers of files, reading the directory can take quite a long time due to sorting and filtering. Electing not to sort and (to a lesser degree) not to filter the directory entries (by setting the filter to NULL) can speed up the directory reading considerably.

This document was generated on March 19, 2014 using texi2html 1.82.