Progress indicators
Prev | Chapter 2. LqR library API user manual | Next

## Progress indicators

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)

### Progress update step

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%).

Prev | Up | Next
Attaching extra images | Home | Releasing the memory