![]() |
![]() |
![]() |
ZIF Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Signals |
ZifStateZifState — A ZifState object allows progress reporting |
ZifState; ZifStatePrivate; ZifStateClass; #define zif_state_done (state, error) #define zif_state_finished (state, error) #define zif_state_set_number_steps (state, steps) ZifState * zif_state_new (void
); ZifState * zif_state_get_child (ZifState *state
); gboolean zif_state_set_number_steps_real (ZifState *state
,guint steps
,const gchar *strloc
); gboolean zif_state_set_percentage (ZifState *state
,guint percentage
); guint zif_state_get_percentage (ZifState *state
); gboolean zif_state_done_real (ZifState *state
,GError **error
,const gchar *strloc
); gboolean zif_state_finished_real (ZifState *state
,GError **error
,const gchar *strloc
); gboolean zif_state_reset (ZifState *state
);
"allow-cancel-changed" : Run Last "percentage-changed" : Run Last "subpercentage-changed" : Run Last
Objects can use zif_state_set_percentage()
if the absolute percentage
is known. Percentages should always go up, not down.
Modules usually set the number of steps that are expected using
zif_state_set_number_steps()
and then after each section is completed,
the zif_state_done()
function should be called. This will automatically
call zif_state_set_percentage()
with the correct values.
ZifState allows sub-modules to be "chained up" to the parent module so that as the sub-module progresses, so does the parent. The child can be reused for each section, and chains can be deep.
To get a child object, you should use zif_state_get_child()
and then
use the result in any sub-process. You should ensure that the child object
is not re-used without calling zif_state_done()
.
There are a few nice touches in this module, so that if a module only has one progress step, the child progress is used for updates.
Example 1. Using a ZifState.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
static void _do_something (ZifState *state) { ZifState *state_local; // setup correct number of steps zif_state_set_number_steps (state, 2); // we can't cancel this function zif_state_set_allow_cancel (state, FALSE); // run a sub function state_local = zif_state_get_child (state); _do_something_else1 (state_local); // this section done zif_state_done (state); // run another sub function state_local = zif_state_get_child (state); _do_something_else2 (state_local); // this section done (all complete) zif_state_done (state); } |
typedef struct { GObjectClass parent_class; /* Signals */ void (* percentage_changed) (ZifState *state, guint value); void (* subpercentage_changed) (ZifState *state, guint value); void (* allow_cancel_changed) (ZifState *state, gboolean allow_cancel); /* Padding for future expansion */ void (*_zif_reserved1) (void); void (*_zif_reserved2) (void); void (*_zif_reserved3) (void); void (*_zif_reserved4) (void); } ZifStateClass;
#define zif_state_done(state, error) zif_state_done_real(state, error, G_STRLOC)
|
|
|
#define zif_state_finished(state, error) zif_state_finished_real(state, error, G_STRLOC)
|
|
|
#define zif_state_set_number_steps(state, steps) zif_state_set_number_steps_real(state, steps, G_STRLOC)
|
|
|
ZifState * zif_state_new (void
);
Returns : |
A new ZifState class instance. |
Since 0.1.0
ZifState * zif_state_get_child (ZifState *state
);
Monitor a child state and proxy back up to the parent state.
Yo udo not have to g_object_unref()
this value.
Since 0.1.0
gboolean zif_state_set_number_steps_real (ZifState *state
,guint steps
,const gchar *strloc
);
Sets the number of sub-tasks, i.e. how many times the zif_state_done()
function will be called in the loop.
|
the ZifState object |
|
The number of sub-tasks in this transaction |
|
|
Returns : |
TRUE for success, FALSE for failure
|
Since 0.1.0
gboolean zif_state_set_percentage (ZifState *state
,guint percentage
);
Set a percentage manually. NOTE: this must be above what was previously set, or it will be rejected.
|
the ZifState object |
|
A manual percentage value |
Returns : |
TRUE if the signal was propagated, FALSE for failure
|
Since 0.1.0
guint zif_state_get_percentage (ZifState *state
);
Get the percentage state.
|
the ZifState object |
Returns : |
A percentage value, or G_MAXUINT for error |
Since 0.1.0
gboolean zif_state_done_real (ZifState *state
,GError **error
,const gchar *strloc
);
Called when the current sub-task has finished.
|
the ZifState object |
|
A GError or NULL
|
|
|
Returns : |
TRUE for success, FALSE for failure
|
Since 0.1.0
gboolean zif_state_finished_real (ZifState *state
,GError **error
,const gchar *strloc
);
Called when the current sub-task wants to finish early and still complete.
|
the ZifState object |
|
A GError or NULL
|
|
|
Returns : |
TRUE for success, FALSE for failure
|
Since 0.1.0
"allow-cancel-changed"
signalvoid user_function (ZifState *zifstate, gboolean arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"percentage-changed"
signalvoid user_function (ZifState *zifstate, guint arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |