WaitCallbacks are called during long term operations to give the user the opportunity to abort the operation. The default implementation does nothing. But an application can use such a callback to:
Wait callbacks are organized in callback-contexts which must be entered and left.
#define GWEN_WaitCallback_Enter | ( | id | ) | GWEN_WaitCallback_Enter_u(id, __FILE__, __LINE__) |
Enters the callback of the given name. If there is no callback of that name below the currently active callback context then it will be faked. This simply means that a new default context is created which still calls the currently active context (but with level!=0). If the context does exist its function GWEN_WAITCALLBACK_INSTANTIATEFN will be called and the resulting context becomes the active one.
Definition at line 258 of file waitcallback.h.
#define GWEN_WaitCallback_EnterWithText | ( | id, | |||
txt, | |||||
units, | |||||
flags | ) | GWEN_WaitCallback_EnterWithText_u(id, txt, units, flags, __FILE__, __LINE__) |
This macro internally calls GWEN_WaitCallback_EnterWithText_u. It therefore does the same as GWEN_WaitCallback_Enter, but it stores the given text internally to be retrieved by the implemention of a specific callback and presented to the user.
Definition at line 268 of file waitcallback.h.
#define GWEN_WAITCALLBACK_FLAGS_IMMEDIATELY 0x00000002 |
Show the progress window immediately (normally some GUIs hold back the windows until after a few seconds to avoid flickering).
Definition at line 113 of file waitcallback.h.
#define GWEN_WAITCALLBACK_FLAGS_NO_REUSE 0x00000001 |
Normally Gwen tries to reuse already open WaitCallbacks instead of creating new ones. If this flag is given then a new WaitCallback will be created in any case.
Definition at line 107 of file waitcallback.h.
#define GWEN_WAITCALLBACK_ID_FAST "GWEN_WAITCALLBACK_ID_FAST" |
Use this callback id for operations which do not need a GUI. Applications should implement this callback without opening a window.
Definition at line 129 of file waitcallback.h.
#define GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS "GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS" |
This id can be used for any simple progress operation. GUI implementations for this callback might choose to show the associated text (GWEN_WaitCallback_GetText) and provide a simple progress bar.
Definition at line 121 of file waitcallback.h.
#define GWEN_WAITCALLBACK_LEVEL_REUSED 9999 |
This depth level is used upon entering of a waitcallback which is reused (because there already is a waitcallback with the enter-id). In such a case Gwen calls the the log callback function with this level and the text given to .
Definition at line 100 of file waitcallback.h.
#define GWEN_WAITCALLBACK_PROGRESS_NONE ((GWEN_TYPE_UINT64)(-1)) |
This value tells the callback mechanism that there has been no progress. It is used for keep-alive calls.
Definition at line 84 of file waitcallback.h.
#define GWEN_WAITCALLBACK_PROGRESS_ONE ((GWEN_TYPE_UINT64)(-2)) |
This value increments the progress counter by one.
Definition at line 90 of file waitcallback.h.
typedef GWEN_WAITCALLBACK_RESULT(*) GWEN_WAITCALLBACK_CHECKABORTFN(GWEN_WAITCALLBACK *ctx, unsigned int level) |
Checks whether the user wants to abort the current action.
ctx | context This function is optional. | |
level | If the context given to GWEN_WaitCallback_Enter did not exist then a new default context has been created which uses the functions (like this one) of the at that time active context. For such an artificially derived context the level represents the current level below the context given as parameter ctx. So if the level is 0 then the given context actually is the currently active one. |
Definition at line 163 of file waitcallback.h.
typedef GWEN_WAITCALLBACK*(*) GWEN_WAITCALLBACK_INSTANTIATEFN(GWEN_WAITCALLBACK *ctx) |
Uses the given context as a template to instantiate a new context. For GUI callbacks this function can be used to open a window (such as progress dialogs etc). This function must be set.
ctx | context |
Definition at line 176 of file waitcallback.h.
typedef void(*) GWEN_WAITCALLBACK_LOGFN(GWEN_WAITCALLBACK *ctx, unsigned int level, GWEN_LOGGER_LEVEL loglevel, const char *s) |
Logs a message to the given callback. A GUI program could use this function to write the given string to an open window. This function is optional.
ctx | context | |
level | see GWEN_WAITCALLBACK_CHECKABORTFN. If the level value is GWEN_WAITCALLBACK_LEVEL_REUSED then the log message is the text given to GWEN_WaitCallback_EnterWithText for reused callbacks. | |
loglevel | a higher level results in a more detailed output. Loglevels are defined from 0 (the most important level) and 10 (the least important level). Libgwenhywfar itself does not use this function. | |
s | log string |
Definition at line 195 of file waitcallback.h.
Result of GWEN_WAITCALLBACK_CHECKABORTFN.
GWEN_WaitCallbackResult_Continue | tells the caller that it is ok to continue |
GWEN_WaitCallbackResult_Abort | tells the caller to abort |
Definition at line 137 of file waitcallback.h.
GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallback | ( | ) |
Checks whether the user wants to abort the current action. This in fact calls the function GWEN_WAITCALLBACK_CHECKABORTFN stored in the current waitcallback context.
GWENHYWFAR_API void GWEN_WaitCallback_Enter_u | ( | const char * | id, | |
const char * | file, | |||
int | line | |||
) |
Don't call this function directly, better use the macro GWEN_WaitCallback_Enter
GWENHYWFAR_API void GWEN_WaitCallback_EnterWithText_u | ( | const char * | id, | |
const char * | txt, | |||
const char * | units, | |||
GWEN_TYPE_UINT32 | flags, | |||
const char * | file, | |||
int | line | |||
) |
Don't call this function directly, better use the macro GWEN_WaitCallback_EnterWithText
GWENHYWFAR_API void GWEN_WaitCallback_free | ( | GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API int GWEN_WaitCallback_GetDistance | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the proposed distance in milliseconds between two calls to the callback (defaults to 0). You can use the value returned here for a call to select(2).
ctx | context to inspect (if 0 then the currently active one will be inspected) |
GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_WaitCallback_GetFlags | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the flags which were given upon entering of the given context.
GWENHYWFAR_API const char* GWEN_WaitCallback_GetId | ( | const GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API int GWEN_WaitCallback_GetNestingLevel | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Resturns the nesting level of the given context
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressPos | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the current progress position (as set by GWEN_WaitCallback_SetProgressPos). This can be used by the callback context to correctly display a progress bar.
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressTotal | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the progress total (as set by GWEN_WaitCallback_SetProgressTotal). This can be used by the callback context to correctly display a progress bar.
GWENHYWFAR_API const char* GWEN_WaitCallback_GetText | ( | const GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API const char* GWEN_WaitCallback_GetUnits | ( | const GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API time_t GWEN_WaitCallback_LastCalled | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the time when the callback function was last called (or 0 if it has never been called)
GWENHYWFAR_API time_t GWEN_WaitCallback_LastEntered | ( | const GWEN_WAITCALLBACK * | ctx | ) |
Returns the time when the callback context was last entered (or 0 if it never has been).
GWENHYWFAR_API void GWEN_WaitCallback_Leave | ( | ) |
Leaves the currently active context (by freeing it) and reinstates the previously active one.
GWENHYWFAR_API void GWEN_WaitCallback_Log | ( | GWEN_LOGGER_LEVEL | logLevel, | |
const char * | s | |||
) |
Sends the given log string to the currently active context. Internally calls GWEN_WAITCALLBACK_LOGFN.
GWENHYWFAR_API GWEN_WAITCALLBACK* GWEN_WaitCallback_new | ( | const char * | id | ) |
Creates a new callback. This function should only be used by inheriting "classes".
GWENHYWFAR_API int GWEN_WaitCallback_Register | ( | GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API void GWEN_WaitCallback_SetCheckAbortFn | ( | GWEN_WAITCALLBACK * | ctx, | |
GWEN_WAITCALLBACK_CHECKABORTFN | fn | |||
) |
Sets the checkAbort function (see GWEN_WAITCALLBACK_CHECKABORTFN).
GWENHYWFAR_API void GWEN_WaitCallback_SetDistance | ( | GWEN_WAITCALLBACK * | ctx, | |
int | d | |||
) |
Sets the proposed distance in milliseconds between two calls to the callback. This value is never enforced by the callback mechanism itself.
GWENHYWFAR_API void GWEN_WaitCallback_SetInstantiateFn | ( | GWEN_WAITCALLBACK * | ctx, | |
GWEN_WAITCALLBACK_INSTANTIATEFN | fn | |||
) |
Sets the instantiate function (see GWEN_WAITCALLBACK_INSTANTIATEFN).
GWENHYWFAR_API void GWEN_WaitCallback_SetLogFn | ( | GWEN_WAITCALLBACK * | ctx, | |
GWEN_WAITCALLBACK_LOGFN | fn | |||
) |
Sets the log function (see GWEN_WAITCALLBACK_LOGFN).
GWENHYWFAR_API void GWEN_WaitCallback_SetProgressPos | ( | GWEN_TYPE_UINT64 | pos | ) |
You can use this to feed a progress dialog. This value can later be used by the callback function to properly display a progress bar.
pos | current progress position |
GWENHYWFAR_API void GWEN_WaitCallback_SetProgressTotal | ( | GWEN_TYPE_UINT64 | total | ) |
You can use this to initialize a progress dialog. This value can later be used by the callback function to properly display a progress bar. if the special value GWEN_WAITCALLBACK_PROGRESS_NONE is used here then no progress bar is requested. Instead a text box might be implemented by the application which shows the ProgressPos as an absolute number.
GWENHYWFAR_API int GWEN_WaitCallback_Unregister | ( | GWEN_WAITCALLBACK * | ctx | ) |
GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallbackProgress | ( | GWEN_TYPE_UINT64 | pos | ) |
This is basically a combination of the functions GWEN_WaitCallback_SetProgressPos and GWEN_WaitCallback.
pos | current progress position |