doc/progress_callback.txt

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