Next: , Previous: , 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: , Previous: , Up: Part VI Images   [Contents][Index]