diff options
| -rw-r--r-- | progress_dlg.h | 49 | ||||
| -rw-r--r-- | simple_dialog.h | 112 |
2 files changed, 117 insertions, 44 deletions
diff --git a/progress_dlg.h b/progress_dlg.h index 2cac3c0c76..34d2ae37d4 100644 --- a/progress_dlg.h +++ b/progress_dlg.h @@ -1,7 +1,7 @@ /* progress_dlg.h * Definitions for progress dialog box routines * - * $Id: progress_dlg.h,v 1.6 2004/01/21 22:00:28 ulfl Exp $ + * $Id: progress_dlg.h,v 1.7 2004/06/04 20:04:34 ulfl Exp $ * * Ethereal - Network traffic analyzer * By Gerald Combs <gerald@ethereal.com> @@ -25,47 +25,62 @@ #ifndef __PROGRESS_DLG_H__ #define __PROGRESS_DLG_H__ -/* - * Progress (modal) dialog box routines. +/** @file + * Progress (modal) dialog box routines. + * @ingroup dialog_group */ +/** Progress dialog data. */ struct progdlg; +/** Progress dialog data. */ typedef struct progdlg progdlg_t; -/* - * Create and pop up the progress dialog; allocate a "progdlg_t" +/** + * Create and pop up the progress dialog. Allocates a "progdlg_t" * and initialize it to contain all information the implementation * needs in order to manipulate the dialog, and return a pointer to * it. * - * The first argument is the task to do, e.g. "Loading". - * The second argument is the item to do, e.g. "capture.cap". - * The third argument is a pointer to a Boolean variable that will be - * set to TRUE if the user hits that button. + * @param task_title the task to do, e.g. "Loading" + * @param item_title the item to do, e.g. "capture.cap" + * @param stop_flag a pointer to a Boolean variable that will be + * set to TRUE if the user hits that button + * @return the newly created progress dialog */ progdlg_t *create_progress_dlg(const gchar *task_title, const gchar *item_title, gboolean *stop_flag); -/* Create a progress dialog, but only if it's not likely to disappear - * immediately, which can be disconcerting for the user. +/** + * Create a progress dialog, but only if it's not likely to disappear + * immediately. This can be disconcerting for the user. * - * The first three arguments are as for create_progress_dlg(). - * Following those is a pointer to a GTimeVal structure which holds - * the time at which the caller started to process the data, and the - * current progress (0..1). + * @param task_title the task to do, e.g. "Loading" + * @param item_title the item to do, e.g. "capture.cap" + * @param stop_flag a pointer to a Boolean variable that will be + * set to TRUE if the user hits that button + * @param start_time a pointer to a GTimeVal structure which holds + * the time at which the caller started to process the data + * @param progress the current progress (0..1) + * @return the newly created progress dialog */ progdlg_t * delayed_create_progress_dlg(const gchar *task_title, const gchar *item_title, gboolean *stop_flag, const GTimeVal *start_time, gfloat progress); -/* +/** * Update the progress information of the progress dialog box. + * + * @param dlg the progress dialog from create_progress_dlg() + * @param percentage the current percentage value (0..1) + * @param status the new status string to show, e.g. "3000KB of 6000KB" */ void update_progress_dlg(progdlg_t *dlg, gfloat percentage, gchar *status); -/* +/** * Destroy the progress bar. + * + * @param dlg the progress dialog from create_progress_dlg() */ void destroy_progress_dlg(progdlg_t *dlg); diff --git a/simple_dialog.h b/simple_dialog.h index 2719ef2546..8cda259cf9 100644 --- a/simple_dialog.h +++ b/simple_dialog.h @@ -2,7 +2,7 @@ * Definitions for alert box routines with toolkit-independent APIs but * toolkit-dependent implementations. * - * $Id: simple_dialog.h,v 1.13 2004/05/01 22:55:22 obiot Exp $ + * $Id: simple_dialog.h,v 1.14 2004/06/04 20:04:34 ulfl Exp $ * * Ethereal - Network traffic analyzer * By Gerald Combs <gerald@ethereal.com> @@ -30,59 +30,117 @@ extern "C" { #endif /* __cplusplus */ -/* Dialog type. - - INFO: tells the user something they should know, but not requiring - any action; the only button should be "OK". +/** @file + * Simple dialog box. + * @ingroup dialog_group + */ - WARN: tells the user about a problem; the only button should be "OK" - CONFIRMATION: asks the user for confirmation; there should be more than - one button - - ERROR: tells the user about a serious problem; the only button should be - "OK". */ -#define ESD_TYPE_INFO 0x00 -#define ESD_TYPE_WARN 0x01 -#define ESD_TYPE_CONFIRMATION 0x02 -#define ESD_TYPE_ERROR 0x03 +/** Dialog types. */ +typedef enum { + ESD_TYPE_INFO, /**< tells the user something they should know, but not requiring + any action; the only button should be "OK" */ + ESD_TYPE_WARN, /**< tells the user about a problem; the only button should be "OK" */ + ESD_TYPE_CONFIRMATION, /**< asks the user for confirmation; there should be more than + one button */ + ESD_TYPE_ERROR /**< tells the user about a serious problem; the only button should be "OK" */ +} ESD_TYPE_E; -/* Which buttons to display. */ -#define ESD_BTN_OK 0x01 -#define ESD_BTN_CANCEL 0x02 -#define ESD_BTN_YES 0x04 -#define ESD_BTN_NO 0x08 -#define ESD_BTN_CLEAR 0x10 +/** display an "Ok" button */ +#define ESD_BTN_OK 0x01 +/** display a "Cancel" button */ +#define ESD_BTN_CANCEL 0x02 +/** display a "Yes" button */ +#define ESD_BTN_YES 0x04 +/** display a "No" button */ +#define ESD_BTN_NO 0x08 +/** display a "Clear" button */ +#define ESD_BTN_CLEAR 0x10 +/** Standard button combination "Ok" + "Cancel". */ #define ESD_BTNS_OK_CANCEL (ESD_BTN_OK|ESD_BTN_CANCEL) +/** Standard button combination "Yes" + "No". */ #define ESD_BTNS_YES_NO (ESD_BTN_YES|ESD_BTN_NO) +/** Standard button combination "Yes" + "No" + "Cancel". */ #define ESD_BTNS_YES_NO_CANCEL (ESD_BTN_YES|ESD_BTN_NO|ESD_BTN_CANCEL) -/* show a simple dialog */ #if __GNUC__ >= 2 -extern gpointer simple_dialog(gint type, gint btn_mask, +/** Create and show a simple dialog. + * + * @param type type of dialog + * @param btn_mask the buttons to display + * @param msg_format printf like message format + * @param ... printf like parameters + * @return the newly created dialog + */ +extern gpointer simple_dialog(ESD_TYPE_E type, gint btn_mask, const gchar *msg_format, ...) __attribute__((format (printf, 3, 4))); +/** Create and show a simple dialog using a va_list. + * + * @param type type of dialog + * @param btn_mask the buttons to display + * @param msg_format printf like message format + * @param ap parameters + * @return the newly created dialog + */ extern gpointer vsimple_dialog(gint type, gint btn_mask, const gchar *msg_format, va_list ap); #else +/** Create and show a simple dialog. + * + * @param type type of dialog + * @param btn_mask the buttons to display + * @param msg_format printf like message format + * @param ... printf like parameters + * @return the newly created dialog + */ extern gpointer simple_dialog(gint type, gint btn_mask, const gchar *msg_format, ...); +/** Create and show a simple dialog using a va_list. + * + * @param type type of dialog + * @param btn_mask the buttons to display + * @param msg_format printf like message format + * @param ap parameters + * @return the newly created dialog + */ extern gpointer vsimple_dialog(gint type, gint btn_mask, const gchar *msg_format, va_list ap); #endif -/* callback function type */ +/** Callback function type for simple_dialog_set_cb() */ typedef void (* simple_dialog_cb_t) (gpointer dialog, gint btn, gpointer data); -/* set the callback function, which has to be called when a button was pressed */ +/** Set the callback function for the dialog, called when a button was pressed. + * + * @param dialog the dialog from simple_dialog() + * @param callback_fct the callback function to set + * @param data data to be passed to the callback function + */ extern void simple_dialog_set_cb(gpointer dialog, simple_dialog_cb_t callback_fct, gpointer data); +/** Surround the primary dialog message text by + * simple_dialog_primary_start() and simple_dialog_primary_end(). + * To highlight the first sentence (will take effect on GTK2 only). + */ extern char *simple_dialog_primary_start(void); -extern char *simple_dialog_format_message(const char *msg); +/** Surround the primary dialog message text by + * simple_dialog_primary_start() and simple_dialog_primary_end(). + * To highlight the first sentence (will take effect on GTK2 only). + */ extern char *simple_dialog_primary_end(void); -/* +/** Escape the message text, if it probably contains Pango escape sequences. + * For example html like tags starting with a <. + * + * @param msg the string to escape + * @return the escaped message text, must be freed with g_free() later + */ +extern char *simple_dialog_format_message(const char *msg); + +/** + * Display all queued messages. * If a routine is called to display a dialog before there are any windows * open, information to use to display the dialog is queued up. This * routine should be called once there are windows open, so that the queued |