00001 /** \file
00002  * \brief Processing Counter
00003  *
00004  * See Copyright Notice in im_lib.h
00005  */
00006 
00007 #ifndef __IM_COUNTER_H
00008 #define __IM_COUNTER_H
00009 
00010 #if defined(__cplusplus)
00011 extern "C" {
00012 #endif
00013 
00014 
00015 /** \defgroup counter Counter 
00016  * \par
00017  * Used to notify the application that a step in the loading, saving or processing operation has been performed.
00018  * \par
00019  * See \ref im_counter.h
00020  * \ingroup util */
00021 
00022 /** Counter callback, informs the progress of the operation to the client. \n
00023  * Text contains a constant string that is NULL during normal counting, a title in the begining of a sequence 
00024  * and a message in the begining of a count.
00025  * Counter id identifies diferrent counters. \n
00026  * Progress in a count reports a value from 0 to 1000. If -1 indicates the start of a sequence of operations, 1001 ends the sequence. \n
00027  * If returns 0 the client should abort the operation. \n
00028  * If the counter is aborted, the callback will be called one last time at 1001.
00029  * \ingroup counter */
00030 typedef int (*imCounterCallback)(int counter, void* user_data, const char* text, int progress);
00031 
00032 /** Changes the counter callback. Returns old callback. \n
00033  * User data is changed only if not NULL.
00034  * \ingroup counter */
00035 imCounterCallback imCounterSetCallback(void* user_data, imCounterCallback counter_func);
00036 
00037 /** Begins a new count, or a partial-count in a sequence. \n
00038  * Calls the callback with "-1" and text=title, if it is at the top level. \n     
00039  * This is to be used by the operations. Returns a counter Id.
00040  * \ingroup counter */
00041 int imCounterBegin(const char* title);
00042 
00043 /** Ends a count, or a partial-count in a sequence. \n
00044  * Calls the callback with "1001", text=null, and releases the counter if it is at top level count. \n
00045  * \ingroup counter */
00046 void imCounterEnd(int counter);
00047 
00048 /** Increments a count. Must set the total first. \n
00049  * Calls the callback, text=message if it is the first increment for the count. \n
00050  * Returns 0 if the callback aborted, 1 if returns normally.
00051  * \ingroup counter */
00052 int imCounterInc(int counter);
00053 
00054 /** Set a specific count. Must set the total first. \n
00055  * Calls the callback, text=message if it is the first increment for the count. \n
00056  * Returns 0 if the callback aborted, 1 if returns normally.
00057  * \ingroup counter */
00058 int imCounterIncTo(int counter, int count);
00059 
00060 /** Sets the total increments of a count.
00061  * \ingroup counter */
00062 void imCounterTotal(int counter, int total, const char* message);
00063 
00064 
00065 #if defined(__cplusplus)
00066 }
00067 #endif
00068 
00069 #endif