pidgin/minidialog.h

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