src/ml_dialog.h

   1 /* Monolith dialog class.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: ml_dialog.h,v 1.3 2002/11/13 21:41:01 rich Exp $
  19  */
  20
  21 #ifndef ML_DIALOG_H
  22 #define ML_DIALOG_H
  23
  24 #include "monolith.h"
  25 #include "ml_window.h"
  26
  27 struct ml_dialog;
  28 typedef struct ml_dialog *ml_dialog;
  29
  30 /* Function: new_ml_dialog - monolith dialog widget
  31  * Function: ml_dialog_set_text
  32  * Function: ml_dialog_get_text
  33  * Function: ml_dialog_set_title
  34  * Function: ml_dialog_get_title
  35  * Function: ml_dialog_set_icon
  36  * Function: ml_dialog_get_icon
  37  * Function: ml_dialog_clear_buttons
  38  * Function: ml_dialog_add_button
  39  * Function: ml_dialog_add_close_button
  40  *
  41  * A dialog is a widget for asking a user a question, and getting an
  42  * answer. It can also be used for presenting the user with
  43  * confirmation that some operation has been carried out, or for
  44  * presenting the user with an error message.
  45  *
  46  * Fundamentally, a dialog consists of some text, and a series of
  47  * zero or more buttons along the bottom of the widget. A dialog
  48  * can also have an optional title which appears along the top
  49  * and an optional icon which appears on the left of the window.
  50  *
  51  * Dialogs are almost always used packed directly into a window.
  52  *
  53  * Dialogs are actually "super-widgets", built up from fundamental
  54  * widgets like labels, buttons, and table layouts. However currently
  55  * none of the fundamental widgets are actually exposed through the
  56  * @code{ml_dialog_*} interface.
  57  *
  58  * @code{new_ml_dialog} creates a new dialog widget with no text, no
  59  * title, no icon and no buttons (ie. not very useful! - after calling
  60  * this you should immediately call @code{ml_dialog_set_text} and
  61  * probably @code{ml_dialog_add_button} too).
  62  *
  63  * @code{ml_dialog_(set|get)_text} updates the text in a dialog
  64  * widget. Although having text is not strictly mandatory, it is
  65  * highly advisable.
  66  *
  67  * @code{ml_dialog_(set|get)_title} changes the title. To have no
  68  * title, set the title to @code{NULL}.
  69  *
  70  * @code{ml_dialog_(set|get)_icon} changes the icon. To have no
  71  * icon, set the icon to @code{NULL}.
  72  *
  73  * @code{ml_dialog_clear_buttons} removes all the buttons from the
  74  * dialog.
  75  *
  76  * @code{ml_dialog_add_button} adds a single button to the dialog. If
  77  * there are already buttons attached to the dialog, then this adds
  78  * the new button on the right. The @code{text} which appears on
  79  * the button must be specified. When the button is pressed,
  80  * @code{callback_fn} will be called.
  81  *
  82  * @code{ml_dialog_add_close_button} adds a single close button to the
  83  * dialog. The @code{text} which appears on the button must be specified.
  84  * If @code{close_flags} contains @code{ML_DIALOG_CLOSE_RELOAD_OPENER}
  85  * then the close button will cause the opener window to reload (see
  86  * @ref{new_ml_close_button(3)}).
  87  *
  88  * See also: @ref{ml_ok_window(3)}, @ref{ml_error_window(3)}.
  89  */
  90 extern ml_dialog new_ml_dialog (pool pool);
  91 extern void ml_dialog_set_text (ml_dialog, const char *text);
  92 extern const char *ml_dialog_get_text (ml_dialog);
  93 extern void ml_dialog_set_title (ml_dialog, const char *title);
  94 extern const char *ml_dialog_get_title (ml_dialog);
  95 extern void ml_dialog_set_icon (ml_dialog, const char *icon);
  96 extern const char *ml_dialog_get_icon (ml_dialog);
  97 extern void ml_dialog_clear_buttons (ml_dialog);
  98 extern void ml_dialog_add_button (ml_dialog, const char *text, void (*callback_fn) (ml_session, void *), ml_session session, void *data);
  99 extern void ml_dialog_add_close_button (ml_dialog w, const char *text, int close_flags);
 100
 101 /* Function: ml_ok_window - confirmation and error windows
 102  * Function: ml_error_window
 103  *
 104  * @code{ml_ok_window} and @code{ml_error_window} are handy helper
 105  * functions which display either a confirmation of success, or error
 106  * window. They are just convenient wrappers around @code{new_ml_window}
 107  * and @code{new_ml_dialog}.
 108  *
 109  * @code{ml_ok_window} is a window which displays a confirmation of
 110  * success. The @code{session} argument is the current session. The
 111  * @code{text} is the text to display. @code{flags} is explained below.
 112  *
 113  * @code{ml_error_window} is a window which displays an error
 114  * message. The @code{session} argument is the current session. The
 115  * @code{text} is the text to display. @code{flags} is explained below.
 116  *
 117  * The @code{flags} argument is a list of the following flags:
 118  *
 119  * @code{ML_DIALOG_CLOSE_BUTTON}: If set, display a close window button.
 120  *
 121  * @code{ML_DIALOG_CLOSE_RELOAD_OPENER}: If set, refresh the opener
 122  * window on close (see @ref{new_ml_close_button(3)}).
 123  *
 124  * Both functions return the new window.
 125  *
 126  * See also: @ref{new_ml_window(3)}, @ref{new_ml_dialog(3)}.
 127  */
 128 extern ml_window ml_ok_window (pool, ml_session, const char *text, int flags);
 129 extern ml_window ml_error_window (pool, ml_session, const char *text, int flags);
 130
 131 #define ML_DIALOG_CLOSE_BUTTON        0x0001
 132 #define ML_DIALOG_CLOSE_RELOAD_OPENER 0x0002
 133
 134 #endif /* ML_DIALOG_H */