ZifState

ZifState — A ZifState object allows progress reporting

Synopsis

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

Object Hierarchy

  GObject
   +----ZifState

Signals

  "allow-cancel-changed"                           : Run Last
  "percentage-changed"                             : Run Last
  "subpercentage-changed"                          : Run Last

Description

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


Details

ZifState

typedef struct _ZifState ZifState;


ZifStatePrivate

typedef struct _ZifStatePrivate ZifStatePrivate;


ZifStateClass

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;


zif_state_done()

#define zif_state_done(state, error)			zif_state_done_real(state, error, G_STRLOC)

state :

error :


zif_state_finished()

#define zif_state_finished(state, error)		zif_state_finished_real(state, error, G_STRLOC)

state :

error :


zif_state_set_number_steps()

#define zif_state_set_number_steps(state, steps) zif_state_set_number_steps_real(state, steps, G_STRLOC)

state :

steps :


zif_state_new ()

ZifState *          zif_state_new                       (void);

Returns :

A new ZifState class instance.

Since 0.1.0


zif_state_get_child ()

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.

state :

the ZifState object

Returns :

a new ZifState or NULL for failure

Since 0.1.0


zif_state_set_number_steps_real ()

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.

state :

the ZifState object

steps :

The number of sub-tasks in this transaction

strloc :

Returns :

TRUE for success, FALSE for failure

Since 0.1.0


zif_state_set_percentage ()

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.

state :

the ZifState object

percentage :

A manual percentage value

Returns :

TRUE if the signal was propagated, FALSE for failure

Since 0.1.0


zif_state_get_percentage ()

guint               zif_state_get_percentage            (ZifState *state);

Get the percentage state.

state :

the ZifState object

Returns :

A percentage value, or G_MAXUINT for error

Since 0.1.0


zif_state_done_real ()

gboolean            zif_state_done_real                 (ZifState *state,
                                                         GError **error,
                                                         const gchar *strloc);

Called when the current sub-task has finished.

state :

the ZifState object

error :

A GError or NULL

strloc :

Returns :

TRUE for success, FALSE for failure

Since 0.1.0


zif_state_finished_real ()

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.

state :

the ZifState object

error :

A GError or NULL

strloc :

Returns :

TRUE for success, FALSE for failure

Since 0.1.0


zif_state_reset ()

gboolean            zif_state_reset                     (ZifState *state);

Resets the ZifState object to unset

state :

the ZifState object

Returns :

TRUE for success, FALSE for failure

Since 0.1.0

Signal Details

The "allow-cancel-changed" signal

void                user_function                      (ZifState *zifstate,
                                                        gboolean  arg1,
                                                        gpointer  user_data)      : Run Last

zifstate :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "percentage-changed" signal

void                user_function                      (ZifState *zifstate,
                                                        guint     arg1,
                                                        gpointer  user_data)      : Run Last

zifstate :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "subpercentage-changed" signal

void                user_function                      (ZifState *zifstate,
                                                        guint     arg1,
                                                        gpointer  user_data)      : Run Last

zifstate :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.