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

Next: Simple Image Processing, Previous: Supported Image Formats, Up: Part VI Images [Contents][Index]

### 37.6 Setup and Configuration

Although the image support is designed with integration into a GUI system in mind, it neither assumes what the GUI system is nor does it need a GUI system to work. As a matter of fact, for the most part it doesn’t even need an X connection to work (obviously without a connection, you won’t be able to display images). For this reason, some of the typical (and necessary) tasks, such as progress and error reporting, are by default implemented only to use text output (i.e., to `stderr`). Obviously, with a GUI in place this is not quite adequate. Hooks are available for application program to re-define what to do with these tasks.

The interface to the library configuration is as follows

    void flimage_setup(FLIMAGE_SETUP *setup);

where the parameter `setup` is a pointer to a structure defined as follows:

    typedef struct {
        void       * app_data;
        int          (*visual_cue) (FL_IMAGE *im, const char *msg);
        void         (*error_message) (FL_IMAGE *im, const char *msg);
        const char * rgbfile;
        int          do_not_clear;
        int          max_frames;
        int          delay;
        int          double_buffer;
        int          add_extension;
    } FLIMAGE_SETUP;

with

`app_data`

  The application can use this field to set a value so the field `image->app_data` in all image structures returned by the library will have this value. It’s most useful to set this field to something that’s persistent during the application run, such as the `fdui` structure of the main control panel.

  Note that `image->app_data` is different from `image->u_vdata` in that all image structures returned by the library have the same value of `image->app_data`, which is set by the library. In contrast, `image->u_vdata` is set by the application on an image-by-image basis.

`visual_cue`

  This is the function that will be called by all image reading, writing and processing routines. The function is meant to give the user some visual feedback about what is happening. For lengthy tasks, this function is called repeatedly and periodically to indicate what percentage of the task is completed and to give the application program a chance to check and process GUI activities (for example, via `fl_check_forms()`).

  The first parameter to the function is the image currently being worked on and the second parameter is a short message, indicating the name of the task, such as "Reading JPG" etc.

  Two fields in the image structure can be used to obtain progress information. The member fields `image->total` indicates the total amount of work to be done in some arbitrary units (usually number of rows in the image). `image->completed` indicates how much of the task has been completed. The percentage of how much is completed is then simply the ratio of `image->completed` and `image->total`, multiplied by 100.

  At the begin of a task `image->completed` is set to a value less or equal 1, and at the end of the task, `image->completed` is set to `image->total`.

  A special value of -1 for `image->completed` may be used to indicate a task of unknown length.

`error_message`

  This is a function that is called when an error (of all severities) has occurred inside the library. It is recommanded that the application provide a means to show the messages to the user by sypplying this function.

  The first parameter is a pointer to the image that’s being worked on, and the second parameter is a brief message, such as "memory allocation failed" etc.

  A convenience function, `flimage_error()`, is provided to call the error message handler.

`rgbfile`

  This field should be set to the full path to the color name database (`rgb.txt`) if your system has it in non-standard locations. On most systems, this file is `/usr/lib/X11/rgb.txt`, which is the default if this field is not set.17

`do_not_clear`

  By default, `flimage_display()` clears the window before displaying the image. Set this member to 1 to disable window clearing.

`no_auto_extension`

  By default, `flimage_dump()` changes the filename extension to reflect the format. Set this member to 1 to disable extension substitution.

`double_buffer`

  If set, all image display will by default double-buffered. Double-buffering an image is very expensive (in terms of both resource and speed) as the backbuffer is simulated using a pixmap. If there are no annotations, double-buffering an image does not really improve anything.

  It is far better to turn double-buffering on and off on a image-by-image basis using the `image->double_bufffer` field.

`max_frames`

  This field specifies the maximum number of frames to read by `flimage_load()`. The default maximum is 30 frames.

`delay`

  This field specifies the delay (in milliseconds) between successive frames. It is used by the `flimage_display()` routine.

Note that it is always a good idea to clear the setup structure before initializing and using it

    FLIMAGE_SETUP mysetup;
    memset(mysetup, 0, sizeof mysetup);

    mysetup.max_frames = 100;
    mysetup.delay      = 10;

    flimage_setup(&mysetup);

It is possible to modify the image loading process by utilizing the following routines `flimage_load()` is based on:

    FL_IMAGE *flimage_open(const char *name);

This function takes a file name and returns an image sturcture pointer if the file is a recognized image file. Otherwise `NULL` is returned.

The function

    FL_IMAGE *flimage_read(FL_IMAGE *im);

takes an image structure returned by `flimage_open()` and fills the image structure. Between `flimage_open()` and `flimage_read()` you can inspect or modify fields in the image structure.

    int flimage_close(FL_IMAGE *im);

This function closes all file streams used to create the image.

#### Footnotes

### (17)

The routine where this field is used searches some more locations than the default and should work on most systems automagically.

Next: Simple Image Processing, Previous: Supported Image Formats, Up: Part VI Images [Contents][Index]