pidgin/minidialog.h

   1 /* pidgin
   2  *
   3  * Pidgin is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef __PIDGIN_MINI_DIALOG_H__
  23 #define __PIDGIN_MINI_DIALOG_H__
  24 /**
  25  * SECTION:minidialog
  26  * @section_id: pidgin-minidialog
  27  * @short_description: <filename>minidialog.h</filename>
  28  * @title: Mini Dialog Widget
  29  */
  30
  31 #include <glib-object.h>
  32 #include <gtk/gtk.h>
  33
  34 G_BEGIN_DECLS
  35
  36 #define PIDGIN_TYPE_MINI_DIALOG pidgin_mini_dialog_get_type()
  37
  38 #define PIDGIN_MINI_DIALOG(obj) \
  39   (G_TYPE_CHECK_INSTANCE_CAST ((obj), \
  40   PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialog))
  41
  42 #define PIDGIN_MINI_DIALOG_CLASS(klass) \
  43   (G_TYPE_CHECK_CLASS_CAST ((klass), \
  44   PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialogClass))
  45
  46 #define PIDGIN_IS_MINI_DIALOG(obj) \
  47   (G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
  48   PIDGIN_TYPE_MINI_DIALOG))
  49
  50 #define PIDGIN_IS_MINI_DIALOG_CLASS(klass) \
  51   (G_TYPE_CHECK_CLASS_TYPE ((klass), \
  52   PIDGIN_TYPE_MINI_DIALOG))
  53
  54 #define PIDGIN_MINI_DIALOG_GET_CLASS(obj) \
  55   (G_TYPE_INSTANCE_GET_CLASS ((obj), \
  56   PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialogClass))
  57
  58 /**
  59  * PidginMiniDialog:
  60  * @contents: A GtkBox into which extra widgets for the dialog should be packed.
  61  *
  62  * A widget resembling a diminutive dialog box, designed to be embedded in the
  63  * #PidginBuddyList.  Mini-dialogs have titles, optional descriptions, and a row
  64  * of buttons at the bottom; above the buttons is a #GtkBox into which
  65  * you can pack any random widgets you want to add to the dialog.  When any of
  66  * the dialog's buttons is clicked, the dialog will be destroyed.
  67  *
  68  * Dialogs have the following GObject properties:
  69  * <informaltable frame='none'>
  70  *   <tgroup cols='2'><tbody>
  71  *   <row><entry><literal>"title"</literal></entry>
  72  *     <entry>(<type>char *</type>) A string to be displayed as the dialog's
  73  *       title.</entry>
  74  *   </row>
  75  *   <row><entry><literal>"description"</literal></entry>
  76  *     <entry>(<type>char *</type>) A string to be displayed as the dialog's
  77  *       description.  If this is %NULL, the description widget will be
  78  *       hidden.</entry>
  79  *   </row>
  80  *   <row><entry><literal>"icon-name"</literal></entry>
  81  *     <entry>(<type>char *</type>)The #GtkIconTheme name of an icon for the
  82  *       dialog, or %NULL for no icon.</entry>
  83  *   </row>
  84  *   <row><entry><literal>"custom-icon"</literal></entry>
  85  *     <entry>(<type>GdkPixbuf *</type>) The custom icon to use instead of a
  86  *       #GtkIconTheme one (overrides the <literal>"icon-name"</literal>
  87  *       property).</entry>
  88  *   </row>
  89  *   </tbody></tgroup>
  90  * </informaltable>
  91  */
  92 typedef struct {
  93         GtkBox parent;
  94         gpointer priv;
  95
  96         /*< public >*/
  97         GtkBox *contents;
  98 } PidginMiniDialog;
  99
 100 /**
 101  * PidginMiniDialogClass:
 102  *
 103  * The class of #PidginMiniDialog objects.
 104  */
 105 typedef struct {
 106         GtkBoxClass parent_class;
 107
 108         /*< private >*/
 109         void (*_purple_reserved1) (void);
 110         void (*_purple_reserved2) (void);
 111         void (*_purple_reserved3) (void);
 112         void (*_purple_reserved4) (void);
 113 } PidginMiniDialogClass;
 114
 115 /**
 116  * PidginMiniDialogCallback:
 117  * @mini_dialog: a dialog, one of whose buttons has been pressed.
 118  * @button:      the button which was pressed.
 119  * @user_data:   arbitrary data, supplied to
 120  *                    pidgin_mini_dialog_add_button() when the button was
 121  *                    created.
 122  *
 123  * The type of a callback triggered by a button in a mini-dialog being pressed.
 124  */
 125 typedef void (*PidginMiniDialogCallback)(PidginMiniDialog *mini_dialog,
 126         GtkButton *button, gpointer user_data);
 127
 128 /**
 129  * pidgin_mini_dialog_get_type:
 130  *
 131  * Get the GType of #PidginMiniDialog.
 132  */
 133 GType pidgin_mini_dialog_get_type (void);
 134
 135 /**
 136  * pidgin_mini_dialog_new:
 137  *
 138  * Creates a new #PidginMiniDialog with a #GtkIconTheme icon. This is a
 139  * shortcut for creating the dialog with g_object_new() then setting each
 140  * property yourself.
 141  *
 142  * Returns: a new #PidginMiniDialog.
 143  */
 144 PidginMiniDialog *pidgin_mini_dialog_new(const gchar *title,
 145         const gchar *description, const gchar *icon_name);
 146
 147 /**
 148  * pidgin_mini_dialog_new_with_custom_icon:
 149  *
 150  * Creates a new #PidginMiniDialog with a custom icon. This is a shortcut for creating the dialog
 151  * with g_object_new() then setting each property yourself.
 152  *
 153  * Returns: a new #PidginMiniDialog.
 154  */
 155 PidginMiniDialog *pidgin_mini_dialog_new_with_custom_icon(const gchar *title,
 156         const gchar *description, GdkPixbuf *custom_icon);
 157
 158 /**
 159  * pidgin_mini_dialog_set_title:
 160  * @mini_dialog: a mini-dialog
 161  * @title:       the new title for @mini_dialog
 162  *
 163  * Shortcut for setting a mini-dialog's title via GObject properties.
 164  */
 165 void pidgin_mini_dialog_set_title(PidginMiniDialog *mini_dialog,
 166         const char *title);
 167
 168 /**
 169  * pidgin_mini_dialog_set_description:
 170  * @mini_dialog: a mini-dialog
 171  * @description: the new description for @mini_dialog, or %NULL to
 172  *                    hide the description widget.
 173  *
 174  * Shortcut for setting a mini-dialog's description via GObject properties.
 175  */
 176 void pidgin_mini_dialog_set_description(PidginMiniDialog *mini_dialog,
 177         const char *description);
 178
 179 /**
 180  * pidgin_mini_dialog_enable_description_markup:
 181  * @mini_dialog: a mini-dialog
 182  *
 183  * Enable GMarkup elements in the mini-dialog's description.
 184  */
 185 void pidgin_mini_dialog_enable_description_markup(PidginMiniDialog *mini_dialog);
 186
 187 /**
 188  * pidgin_mini_dialog_set_link_callback:
 189  * @mini_dialog: a mini-dialog
 190  * @cb: (scope call): the callback to invoke
 191  * @user_data: the user data to pass to the callback
 192  *
 193  * Sets a callback which gets invoked when a hyperlink in the dialog's description is clicked on.
 194  */
 195 void pidgin_mini_dialog_set_link_callback(PidginMiniDialog *mini_dialog, GCallback cb, gpointer user_data);
 196
 197 /**
 198  * pidgin_mini_dialog_set_icon_name:
 199  * @mini_dialog: a mini-dialog
 200  * @icon_name:   the #GtkIconTheme name of an icon, or %NULL for no icon.
 201  *
 202  * Shortcut for setting a mini-dialog's icon via GObject properties.
 203  */
 204 void pidgin_mini_dialog_set_icon_name(PidginMiniDialog *mini_dialog,
 205         const char *icon_name);
 206
 207 /**
 208  * pidgin_mini_dialog_set_custom_icon:
 209  * @mini_dialog: a mini-dialog
 210  * @custom_icon: the pixbuf to use as a custom icon
 211  *
 212  * Shortcut for setting a mini-dialog's custom icon via GObject properties.
 213  */
 214 void pidgin_mini_dialog_set_custom_icon(PidginMiniDialog *mini_dialog,
 215         GdkPixbuf *custom_icon);
 216
 217 /**
 218  * pidgin_mini_dialog_add_button:
 219  * @mini_dialog: a mini-dialog
 220  * @text:        the text to display on the new button
 221  * @clicked_cb: (scope call): the function to call when the button is clicked
 222  * @user_data:   arbitrary data to pass to @clicked_cb when it is
 223  *                    called.
 224  *
 225  * Adds a new button to a mini-dialog, and attaches the supplied callback to
 226  * its <literal>clicked</literal> signal.  After a button is clicked, the dialog
 227  * is destroyed.
 228  */
 229 void pidgin_mini_dialog_add_button(PidginMiniDialog *mini_dialog,
 230         const char *text, PidginMiniDialogCallback clicked_cb,
 231         gpointer user_data);
 232
 233 /**
 234  * pidgin_mini_dialog_add_non_closing_button:
 235  * @mini_dialog: a mini-dialog
 236  * @text:        the text to display on the new button
 237  * @clicked_cb: (scope call): the function to call when the button is clicked
 238  * @user_data:   arbitrary data to pass to @clicked_cb when it is
 239  *                    called.
 240  *
 241  * Equivalent to pidgin_mini_dialog_add_button(), the only difference
 242  * is that the mini-dialog won't be closed after the button is clicked.
 243  */
 244 void pidgin_mini_dialog_add_non_closing_button(PidginMiniDialog *mini_dialog,
 245         const char *text, PidginMiniDialogCallback clicked_cb,
 246         gpointer user_data);
 247
 248 /**
 249  * pidgin_mini_dialog_get_num_children:
 250  * @mini_dialog: a mini-dialog
 251  *
 252  * Gets the number of widgets packed into PidginMiniDialog.contents.
 253  *
 254  * Returns: the number of widgets in @mini_dialog->contents.
 255  */
 256 guint pidgin_mini_dialog_get_num_children(PidginMiniDialog *mini_dialog);
 257
 258 G_END_DECLS
 259
 260 #endif /* __PIDGIN_MINI_DIALOG_H__ */