ui/simple_dialog.h

   1 /* simple_dialog.h
   2  * Definitions for alert box routines with toolkit-independent APIs but
   3  * toolkit-dependent implementations.
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __SIMPLE_DIALOG_UI_H__
  13 #define __SIMPLE_DIALOG_UI_H__
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif /* __cplusplus */
  18
  19 /** @file
  20  *  Simple dialog box.
  21  *  @ingroup dialog_group
  22  */
  23
  24
  25 /** Dialog types. */
  26 typedef enum {
  27     ESD_TYPE_INFO,          /**< tells the user something they should know, but not requiring
  28                                     any action; the only button should be "OK" */
  29     ESD_TYPE_WARN,          /**< tells the user about a problem; the only button should be "OK" */
  30     ESD_TYPE_CONFIRMATION,  /**< asks the user for confirmation; there should be more than
  31                                     one button */
  32     ESD_TYPE_ERROR,         /**< tells the user about a serious problem; the only button should be "OK" */
  33     ESD_TYPE_STOP           /**< tells the user a stop action is in progress, there should be no button */
  34 } ESD_TYPE_E;
  35
  36 /** display no buttons at all */
  37 #define ESD_BTN_NONE   0x00
  38 /** display an "Ok" button */
  39 #define ESD_BTN_OK     0x01
  40 /** display a "Cancel" button */
  41 #define ESD_BTN_CANCEL 0x02
  42 /** display a "Yes" button */
  43 #define ESD_BTN_YES    0x04
  44 /** display a "No" button */
  45 #define ESD_BTN_NO     0x08
  46 /** display a "Clear" button */
  47 #define ESD_BTN_CLEAR  0x10
  48 /** display a "Save" button */
  49 #define ESD_BTN_SAVE   0x20
  50 /** display a "Continue without Saving" button */
  51 #define ESD_BTN_DONT_SAVE 0x40
  52 /** display a "Quit without Saving" button */
  53 #define ESD_BTN_QUIT_DONT_SAVE 0x80
  54
  55 /** Standard button combination "Ok" + "Cancel". */
  56 #define ESD_BTNS_OK_CANCEL      (ESD_BTN_OK|ESD_BTN_CANCEL)
  57 /** Standard button combination "Yes" + "No". */
  58 #define ESD_BTNS_YES_NO         (ESD_BTN_YES|ESD_BTN_NO)
  59 /** Standard button combination "Yes" + "No" + "Cancel". */
  60 #define ESD_BTNS_YES_NO_CANCEL  (ESD_BTN_YES|ESD_BTN_NO|ESD_BTN_CANCEL)
  61 /** Standard button combination "No" + "Cancel" + "Save". */
  62 #define ESD_BTNS_SAVE_DONTSAVE  (ESD_BTN_SAVE|ESD_BTN_DONT_SAVE)
  63 #define ESD_BTNS_SAVE_DONTSAVE_CANCEL (ESD_BTN_DONT_SAVE|ESD_BTN_CANCEL|ESD_BTN_SAVE)
  64 /** Standard button combination "Quit without saving" + "Cancel" + "Save". */
  65 #define ESD_BTNS_SAVE_QUIT_DONTSAVE_CANCEL (ESD_BTN_QUIT_DONT_SAVE|ESD_BTN_CANCEL|ESD_BTN_SAVE)
  66 /** Standard button combination "Quit without saving" + "Cancel". */
  67 #define ESD_BTNS_QUIT_DONTSAVE_CANCEL (ESD_BTN_QUIT_DONT_SAVE|ESD_BTN_CANCEL)
  68
  69 /** Create and show a simple dialog.
  70  *
  71  * @param type type of dialog, e.g. ESD_TYPE_WARN
  72  * @param btn_mask The buttons to display, e.g. ESD_BTNS_OK_CANCEL
  73  * @param msg_format Printf like message format. Text must be plain.
  74  * @param ... Printf like parameters
  75  * @return The newly created dialog
  76  */
  77 /*
  78  * XXX This is a bit clunky. We typically pass in:
  79  * - simple_dialog_primary_start
  80  * - The primary message
  81  * - simple_dialog_primary_end
  82  * - Optionally, the secondary message.
  83  *
  84  * In the Qt UI we use primary_start and _end to split the primary and
  85  * secondary messages. They are then added to a QMessageBox via setText and
  86  * setInformativeText respectively. No formatting is applied.
  87  *
  88  * Callers are responsible for wrapping the primary message and formatting
  89  * the message text.
  90  *
  91  * Explicitly passing in separate primary and secondary messages would let us
  92  * get rid of primary_start and primary_end and reduce the amount of
  93  * gymnastics we have to to in the Qt UI.
  94  */
  95 extern gpointer simple_dialog(ESD_TYPE_E type, gint btn_mask,
  96     const gchar *msg_format, ...)
  97     G_GNUC_PRINTF(3, 4);
  98
  99 /** Surround the primary dialog message text by
 100  *  simple_dialog_primary_start() and simple_dialog_primary_end().
 101  */
 102 extern const char *simple_dialog_primary_start(void);
 103 /** Surround the primary dialog message text by
 104  *  simple_dialog_primary_start() and simple_dialog_primary_end().
 105  */
 106 extern const char *simple_dialog_primary_end(void);
 107
 108 /** Escape the message text, if it probably contains Pango escape sequences.
 109  *  For example html like tags starting with a <.
 110  *
 111  * @param msg the string to escape
 112  * @return the escaped message text, must be freed with g_free() later
 113  */
 114 extern char *simple_dialog_format_message(const char *msg);
 115
 116 /*
 117  * Alert box, with optional "don't show this message again" variable
 118  * and checkbox, and optional secondary text.
 119  */
 120 extern void simple_message_box(ESD_TYPE_E type, gboolean *notagain,
 121                                const char *secondary_msg,
 122                                const char *msg_format, ...) G_GNUC_PRINTF(4, 5);
 123
 124 /*
 125  * Error alert box, taking a format and a va_list argument.
 126  */
 127 extern void vsimple_error_message_box(const char *msg_format, va_list ap);
 128
 129 /*
 130  * Error alert box, taking a format and a list of arguments.
 131  */
 132 extern void simple_error_message_box(const char *msg_format, ...) G_GNUC_PRINTF(1, 2);
 133
 134 /*
 135  * Warning alert box, taking a format and a va_list argument.
 136  */
 137 extern void vsimple_warning_message_box(const char *msg_format, va_list ap);
 138
 139 #ifdef __cplusplus
 140 }
 141 #endif /* __cplusplus */
 142
 143 #endif /* __SIMPLE_DIALOG_UI_H__ */
 144
 145 /*
 146  * Editor modelines
 147  *
 148  * Local Variables:
 149  * c-basic-offset: 4
 150  * tab-width: 8
 151  * indent-tabs-mode: nil
 152  * End:
 153  *
 154  * ex: set shiftwidth=4 tabstop=8 expandtab:
 155  * :indentSize=4:tabSize=8:noTabs=true:
 156  */