Next Previous Contents

14.6 Progress bar support

Introduction

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

PROGRESS_SENSITIVITY

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

PROGRESS_CALLBACK_FORCE()

redraw progress bar

PROGRESS_CALLBACK()

redraw progress bar if changed more than PROGRESS_SENSITIVITY

PROGRESS_CALLBACK_DECL(name)

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.

PROGRESS_ENDSUBSECTION()

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

PROGRESS_MESSAGE(message...)

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

PROGRESS_STATE(value)

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.

PROGRESS_SUB_STATE(value)

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

PROGRESS_FINISH()

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

PROGRESS_SKIP(w)

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

PROGRESS_PARAM

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

PROGRESS_PASS

passes progress to call, corresponding parameter was declared by PROGRESS_PARAM

PROGRESS_ABORTING()

return boolean if Partition Surprise is aborting.

PROGRESS_CHECK(error)

report error if Partition Surprise is aborting

PROGRESS_BREAK

break cycle if PS is aborting

PROGRESS_INIT_DECL

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.

PROGRESS_DONE()

free memory and cleanup in global structure

PROGRESS_GET()

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

PROGRESS_ON()

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;
};

ps_is_subsection

flag if subsection or section only

ps_title

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

ps_weight

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.

ps_value

value of this section, between ps_min and ps_max

ps_progress

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

ps_prev_progress

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

ps_parent

pointer to parent section or NULL for root section

ps_lastsub

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

ps_sub

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

ps_next

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 */
};

ps_current

current section, changing by PROGRESS_STATE()

ps_topsubsection

toplevel subsection, this is subsection which contains ps_current section.

ps_root

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

ps_abort

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

ps_callback

pointer to callback function in client

ps_buf

supplementar buffer

ps_message

message which may be passed to user through client

Next Previous Contents