Next Previous Contents

14.6 Progress bar support


Progress bar support is set of macros which allow simple usage of progress bar in the Partition Surprise, for passing progress information from low level to client interface.

Macros are defined in include/surprise/progress.h, some supplementary functions used by macros are in libsurprise/lib/progress.c

Description of macros


constant, the smallest change requested to redraw progress bar, value is in percentage.


redraw progress bar


redraw progress bar if changed more than PROGRESS_SENSITIVITY


declaration of callback function, this is client function and is called from low levels. Also used for passing this callback function:

int (name)(struct progress_struct *progress_struct, const char *progress_message, ERR_PARAM)

PROGRESS_SUBSECTION(w, min, max, title...)

create new subsection with title obtained by printf-like function of title..., with weight w (in parent subsection), values between min and max. Subsection must be closed by PROGRESS_ENDSUBSECTION, progress can't be changed directly, must be used PROGRESS_SKIP() or PROGRESS_SECTION().

PROGRESS_SECTION(w, min, max, title...)

create new section with title obtained by printf-like function of title..., with weight w in parent subsection, with values between min and max, changing by PROGRESS_STATE(), PROGRESS_FINISH(). Has NO closing macro. Note: PROGRESS_SECTION() and PROGRESS_SUBSECTION() macros can be used without title, e.g. PROGRESS_SECTION(20.0,0.0,100.0), this creates an anonymous section.


close top-level (current) subsection, finish all sections inside.


pass printf-like formatted message to user, for passing to client is used callback function


change status of current section previously openned by PROGRESS_SECTION(), can't be used for subsection, for subsection is similiar macro PROGRESS_SUB_STATE() which is quite different and assumed for occasional use.


change status of subsection, use ocassionally only, especially intented for increasing lucidity. Callback function is always called.


finish current section, state of section is set simly to its maximal value


create anonymous and empty section, used if some section has no meaning and may be skipped, weight of this anonymous section is w.


for passing progress status information through calls, this is declaration in function header, function obtains pointer to global structure progress_struct


passes progress to call, corresponding parameter was declared by PROGRESS_PARAM


return boolean if Partition Surprise is aborting.


report error if Partition Surprise is aborting


break cycle if PS is aborting


declaration of global structure which is everywhere passed through calls.

PROGRESS_INIT(callback, title)

initialize global progress structure, callback is callback redrawing function of client which is occasionally called from lower levels. Also creates main subsection with specified title.


free memory and cleanup in global structure


return progress of the main subsection, it is main progress bar.


check, if progress is passed, passing progress is not mandatory but optional

Description of structures

Structure struct progress_section represents one section or subsection and in section tree and linklist.

struct progress_section {
        int ps_is_subsection:1;         /* flag for subsection */
        char *ps_title;
        float ps_weight;
        float ps_min, ps_max;
        float ps_value;
        float ps_progress, ps_prev_progress;

        struct progress_section *ps_parent;
        struct progress_section *ps_lastsub;
        struct progress_section *ps_sub;
        struct progress_section *ps_next;


flag if subsection or section only


title of this section, client may show this title together with this progress bar


weight of the section in its parent section, changes of progress of this section also change progress of parent section.

ps_min, ps_max

minimal and maximal value of the section, corresponding to macro PROGRESS_STATE() etc.


value of this section, between ps_min and ps_max


progress corresponding to ps_value, simply computed from ps_value, ps_min, ps_max


progress during last call callback function, used for testing if progress changed enough to redraw it, see PROGRESS_SENSITIVITY


pointer to parent section or NULL for root section


last child section, tail of linklist, needed to join next section


first child section, head of linklist, for logical browsing the section tree


next section in parent linklist

Structure struct progress_struct contains global information about status of progress, is passed everywhere where is progress used by macros PROGRESS_PARAM and PROGRESS_PASS, also this structure is passed to callback function, therefore the client can used full information about status.

This is description of the tree of sections, new level is created as subsection by PROGRESS_SUBSECTION(), common section by PROGRESS_SECTION or PROGRESS_SKIP().

struct progress_struct {
        struct progress_section *ps_current;    /* current section... changed by PROGRESS_STATE() */
        struct progress_section *ps_topsubsection;      /* top subsection */
        struct progress_section *ps_root;       /* root of the section tree */

        int ps_abort:1;                         /* flag to be aborted */

        PROGRESS_CALLBACK_DECL(*ps_callback);   /* callback */
        char ps_buf[1024];                      /* NULL_SNPRINTF passing buffer */

        char *ps_message;                       /* current message passed to user */


current section, changing by PROGRESS_STATE()


toplevel subsection, this is subsection which contains ps_current section.


root subsection, this is main progress bar, value returns PROGRESS_GET()


flag if Partition Surprise is aborting, flag is set if callback function (client) return non-zero value


pointer to callback function in client


supplementar buffer


message which may be passed to user through client

Next Previous Contents