By default, the resizing is performed silently. However, it is possible to define progress report
functions, to receive feedback while the resizing is in progress. This is done through the LqrProgress
objects.
Creating and attaching a progress report object
A LqrProgress object is created through the function:
LqrProgress* lqr_progress_new( | void); | |
and can be associated to an LqrCarver object through this function:
void lqr_carver_set_progress( | LqrCarver* carver, |
| | LqrProgress* p); |
Setting up progress hooks
Newly created progress objects are inactive, and need to be set up.
First, hook functions have to be set, which specify the action to take as the rescaling process
starts, progresses, and ends, by using the functions:
LqrRetVal lqr_progress_set_init (LqrProgress * p, LqrProgressFuncInit init_func)
LqrRetVal lqr_progress_set_update (LqrProgress * p, LqrProgressFuncUpdate update_func)
LqrRetVal lqr_progress_set_end (LqrProgress * p, LqrProgressFuncEnd end_func)
as in this sample piece of code:
Example 2.12. Setting progress hooks
LqrProgress *p;
p = lqr_progress_new();
lqr_progress_set_init (p, my_init);
lqr_progress_set_update (p, my_update);
lqr_progress_set_end (p, my_end);
The above example requires that the hook functions my_init,
my_update and my_end are defined as in the following
sample declarations:
Example 2.13. Progress hooks declaration
LqrRetVal my_init (const gchar *init_message);
LqrRetVal my_update (gdouble percentage);
LqrRetVal my_end (const gchar *end_message);
Initial and ending progress messages
The init and end hooks will be called at the beginning and at the end of each rescaling operation by
function lqr_carver_resize. The messages that will be passed to these hooks
will change, depending if the resizing is occurring in the horizontal or in the vertical direction.
The defaults for newly created LqrProgress objects are:
Table 2.2. Default progress messages
| | init | end |
|---|
| horizontal | "Resizing width..." | "done" |
| vertical | "Resizing height..." | "done" |
These can be changed using these functions:
LqrRetVal lqr_progress_set_init_width_message (LqrProgress *p, const gchar * message)
LqrRetVal lqr_progress_set_init_height_message (LqrProgress *p, const gchar * message)
LqrRetVal lqr_progress_set_end_width_message (LqrProgress *p, const gchar * message)
LqrRetVal lqr_progress_set_end_height_message (LqrProgress *p, const gchar * message)
The update hook will be called at regular intervals, and it will be passed the completion percentage
as the argument.
The update step can be specified through:
LqrRetVal lqr_progress_set_update_step( | LqrProgress* p, |
| | gfloat update_step); |
The default step is 0.02 (i.e. 2%).