doc/progress_callback.txt

   1 Progress Callback
   2 -----------------
   3
   4 The 'GP_ProgressCallback' is a structure that stores user-defined callback
   5 function and user-defined pointer and percentage.
   6
   7 It is passed as last parameter to functions that would take some time to
   8 complete and adds capability to track the operation progress as well as to
   9 abort the operation.
  10
  11 Currently it's used in link:filters.html[filters] and
  12 link:loaders.html[loaders].
  13
  14 [source,c]
  15 -------------------------------------------------------------------------------
  16 typdedef struct GP_ProgressCallback {
  17         float percentage;
  18         int (*callback)(struct GP_ProgressCallback *self);
  19         void *priv;
  20 } GP_ProgressCallback;
  21 -------------------------------------------------------------------------------
  22
  23 The 'callback' pointer is a pointer to user defined callback function.
  24
  25 The 'priv' pointer can be used to pass a pointer to the callback function and
  26 can accessed inside of the callback by defererencin the 'self' argument.
  27
  28 The 'percentage' field is updated by the function the callback was passed to
  29 and is increased monotonically till it reaches 100.
  30
  31 If 'non-NULL' progress callback structure is passed to a function, it's called
  32 periodically and the percentage field is updated.
  33
  34 The return value from callback could abort the execution. If a non-zero value
  35 is returned operation is aborted, all memory freed etc., in case of pixmap
  36 loaders errno is set to 'ECANCELED' and in case of pixmap savers the newly
  37 created file is removed too.
  38
  39 The callback, if supported, is the last parameter of a function.
  40
  41 TIP: For example usage see progress callback
  42 link:example_loaders_progress_callback.html[example].