aboutsummaryrefslogtreecommitdiffstats
path: root/simple_dialog.h
blob: 1e788173e856e4087b607d4dfec5944185900875 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
/* simple_dialog.h
 * Definitions for alert box routines with toolkit-independent APIs but
 * toolkit-dependent implementations.
 *
 * $Id$
 *
 * Ethereal - Network traffic analyzer
 * By Gerald Combs <gerald@ethereal.com>
 * Copyright 1998 Gerald Combs
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

#ifndef __DIALOG_H__
#define __DIALOG_H__

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** @file
 *  Simple dialog box.
 *  @ingroup dialog_group
 */


/** 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_STOP           /**< tells the user a stop action is in progress, there should be no button */
} ESD_TYPE_E;

/** display no buttons at all */
#define ESD_BTN_NONE   0x00
/** 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
/** display a "Save" button */
#define ESD_BTN_SAVE   0x20
/** display a "Continue without Saving" button */
#define ESD_BTN_DONT_SAVE 0x40 

/** 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)
/** Standard button combination "No" + "Cancel" + "Save". */
#define ESD_BTNS_SAVE_DONTSAVE_CANCEL (ESD_BTN_DONT_SAVE|ESD_BTN_CANCEL|ESD_BTN_SAVE)

#if __GNUC__ >= 2
/** 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(ESD_TYPE_E 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(ESD_TYPE_E 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(ESD_TYPE_E type, gint btn_mask,
    const gchar *msg_format, va_list ap);
#endif

/** Callback function type for simple_dialog_set_cb() */
typedef void (* simple_dialog_cb_t) (gpointer dialog, gint btn, gpointer data);

/** 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);

/** Close the dialog, useful for "no button" dialogs.
 *
 * @param dialog the dialog to close from simple_dialog()
 */
extern void simple_dialog_close(gpointer dialog);

/** Add a check button to the dialog (e.g. "Don't show this message again")
 * 
 * @param dialog the dialog from simple_dialog()
 * @param text the text to display 
 */
extern void simple_dialog_check_set(gpointer dialog, gchar *text);

/** Get the check buttons state.
 * 
 * @param dialog the dialog from simple_dialog()
 * @return current button state (TRUE is checked)
 */
extern gboolean simple_dialog_check_get(gpointer dialog);

/** 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);
/** 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
 * up dialogs are displayed on top of those windows.
 */
extern void display_queued_messages(void);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __DIALOG_H__ */