pidgin/pidgin

closing merged branch
port-changes-from-branch-2.x.y-to-default
13 months ago, Gary Kramlich
2f836435c33c
closing merged branch
/* pidgin
*
* Pidgin is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* 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., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef __PIDGIN_MINI_DIALOG_H__
#define __PIDGIN_MINI_DIALOG_H__
/**
* SECTION:minidialog
* @section_id: pidgin-minidialog
* @short_description: <filename>minidialog.h</filename>
* @title: Mini Dialog Widget
*/
#include <glib-object.h>
#include <gtk/gtk.h>
G_BEGIN_DECLS
#define PIDGIN_TYPE_MINI_DIALOG pidgin_mini_dialog_get_type()
#define PIDGIN_MINI_DIALOG(obj) \
(G_TYPE_CHECK_INSTANCE_CAST ((obj), \
PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialog))
#define PIDGIN_MINI_DIALOG_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST ((klass), \
PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialogClass))
#define PIDGIN_IS_MINI_DIALOG(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
PIDGIN_TYPE_MINI_DIALOG))
#define PIDGIN_IS_MINI_DIALOG_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE ((klass), \
PIDGIN_TYPE_MINI_DIALOG))
#define PIDGIN_MINI_DIALOG_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), \
PIDGIN_TYPE_MINI_DIALOG, PidginMiniDialogClass))
/**
* PidginMiniDialog:
* @contents: A GtkBox into which extra widgets for the dialog should be packed.
*
* A widget resembling a diminutive dialog box, designed to be embedded in the
* #PidginBuddyList. Mini-dialogs have titles, optional descriptions, and a row
* of buttons at the bottom; above the buttons is a #GtkBox into which
* you can pack any random widgets you want to add to the dialog. When any of
* the dialog's buttons is clicked, the dialog will be destroyed.
*
* Dialogs have the following GObject properties:
* <informaltable frame='none'>
* <tgroup cols='2'><tbody>
* <row><entry><literal>"title"</literal></entry>
* <entry>(<type>char *</type>) A string to be displayed as the dialog's
* title.</entry>
* </row>
* <row><entry><literal>"description"</literal></entry>
* <entry>(<type>char *</type>) A string to be displayed as the dialog's
* description. If this is %NULL, the description widget will be
* hidden.</entry>
* </row>
* <row><entry><literal>"icon-name"</literal></entry>
* <entry>(<type>char *</type>)The #GtkIconTheme name of an icon for the
* dialog, or %NULL for no icon.</entry>
* </row>
* <row><entry><literal>"custom-icon"</literal></entry>
* <entry>(<type>GdkPixbuf *</type>) The custom icon to use instead of a
* #GtkIconTheme one (overrides the <literal>"icon-name"</literal>
* property).</entry>
* </row>
* </tbody></tgroup>
* </informaltable>
*/
typedef struct {
GtkBox parent;
gpointer priv;
/*< public >*/
GtkBox *contents;
} PidginMiniDialog;
/**
* PidginMiniDialogClass:
*
* The class of #PidginMiniDialog objects.
*/
typedef struct {
GtkBoxClass parent_class;
/*< private >*/
void (*_purple_reserved1) (void);
void (*_purple_reserved2) (void);
void (*_purple_reserved3) (void);
void (*_purple_reserved4) (void);
} PidginMiniDialogClass;
/**
* PidginMiniDialogCallback:
* @mini_dialog: a dialog, one of whose buttons has been pressed.
* @button: the button which was pressed.
* @user_data: arbitrary data, supplied to
* pidgin_mini_dialog_add_button() when the button was
* created.
*
* The type of a callback triggered by a button in a mini-dialog being pressed.
*/
typedef void (*PidginMiniDialogCallback)(PidginMiniDialog *mini_dialog,
GtkButton *button, gpointer user_data);
/**
* pidgin_mini_dialog_get_type:
*
* Get the GType of #PidginMiniDialog.
*/
GType pidgin_mini_dialog_get_type (void);
/**
* pidgin_mini_dialog_new:
*
* Creates a new #PidginMiniDialog with a #GtkIconTheme icon. This is a
* shortcut for creating the dialog with g_object_new() then setting each
* property yourself.
*
* Returns: a new #PidginMiniDialog.
*/
PidginMiniDialog *pidgin_mini_dialog_new(const gchar *title,
const gchar *description, const gchar *icon_name);
/**
* pidgin_mini_dialog_new_with_custom_icon:
*
* Creates a new #PidginMiniDialog with a custom icon. This is a shortcut for creating the dialog
* with g_object_new() then setting each property yourself.
*
* Returns: a new #PidginMiniDialog.
*/
PidginMiniDialog *pidgin_mini_dialog_new_with_custom_icon(const gchar *title,
const gchar *description, GdkPixbuf *custom_icon);
/**
* pidgin_mini_dialog_set_title:
* @mini_dialog: a mini-dialog
* @title: the new title for @mini_dialog
*
* Shortcut for setting a mini-dialog's title via GObject properties.
*/
void pidgin_mini_dialog_set_title(PidginMiniDialog *mini_dialog,
const char *title);
/**
* pidgin_mini_dialog_set_description:
* @mini_dialog: a mini-dialog
* @description: the new description for @mini_dialog, or %NULL to
* hide the description widget.
*
* Shortcut for setting a mini-dialog's description via GObject properties.
*/
void pidgin_mini_dialog_set_description(PidginMiniDialog *mini_dialog,
const char *description);
/**
* pidgin_mini_dialog_enable_description_markup:
* @mini_dialog: a mini-dialog
*
* Enable GMarkup elements in the mini-dialog's description.
*/
void pidgin_mini_dialog_enable_description_markup(PidginMiniDialog *mini_dialog);
/**
* pidgin_mini_dialog_set_link_callback:
* @mini_dialog: a mini-dialog
* @cb: (scope call): the callback to invoke
* @user_data: the user data to pass to the callback
*
* Sets a callback which gets invoked when a hyperlink in the dialog's description is clicked on.
*/
void pidgin_mini_dialog_set_link_callback(PidginMiniDialog *mini_dialog, GCallback cb, gpointer user_data);
/**
* pidgin_mini_dialog_set_icon_name:
* @mini_dialog: a mini-dialog
* @icon_name: the #GtkIconTheme name of an icon, or %NULL for no icon.
*
* Shortcut for setting a mini-dialog's icon via GObject properties.
*/
void pidgin_mini_dialog_set_icon_name(PidginMiniDialog *mini_dialog,
const char *icon_name);
/**
* pidgin_mini_dialog_set_custom_icon:
* @mini_dialog: a mini-dialog
* @custom_icon: the pixbuf to use as a custom icon
*
* Shortcut for setting a mini-dialog's custom icon via GObject properties.
*/
void pidgin_mini_dialog_set_custom_icon(PidginMiniDialog *mini_dialog,
GdkPixbuf *custom_icon);
/**
* pidgin_mini_dialog_add_button:
* @mini_dialog: a mini-dialog
* @text: the text to display on the new button
* @clicked_cb: (scope call): the function to call when the button is clicked
* @user_data: arbitrary data to pass to @clicked_cb when it is
* called.
*
* Adds a new button to a mini-dialog, and attaches the supplied callback to
* its <literal>clicked</literal> signal. After a button is clicked, the dialog
* is destroyed.
*/
void pidgin_mini_dialog_add_button(PidginMiniDialog *mini_dialog,
const char *text, PidginMiniDialogCallback clicked_cb,
gpointer user_data);
/**
* pidgin_mini_dialog_add_non_closing_button:
* @mini_dialog: a mini-dialog
* @text: the text to display on the new button
* @clicked_cb: (scope call): the function to call when the button is clicked
* @user_data: arbitrary data to pass to @clicked_cb when it is
* called.
*
* Equivalent to pidgin_mini_dialog_add_button(), the only difference
* is that the mini-dialog won't be closed after the button is clicked.
*/
void pidgin_mini_dialog_add_non_closing_button(PidginMiniDialog *mini_dialog,
const char *text, PidginMiniDialogCallback clicked_cb,
gpointer user_data);
/**
* pidgin_mini_dialog_get_num_children:
* @mini_dialog: a mini-dialog
*
* Gets the number of widgets packed into PidginMiniDialog.contents.
*
* Returns: the number of widgets in @mini_dialog->contents.
*/
guint pidgin_mini_dialog_get_num_children(PidginMiniDialog *mini_dialog);
G_END_DECLS
#endif /* __PIDGIN_MINI_DIALOG_H__ */