pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
G_CONST_RETURN has been deprecated for awhile and honestly it's not necessary for us
release-2.x.y
2019-10-07, Gary Kramlich
e3c4fde8a94a
G_CONST_RETURN has been deprecated for awhile and honestly it's not necessary for us
/**
* @file minidialog.h API for the #PidginMiniDialog Gtk widget.
* @ingroup pidgin
*/
/* 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__
#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))
/**
* 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 <tt>GtkHBox</tt> 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:
* <dl>
* <dt><tt>"title"</tt> (<tt>char *</tt>)</dt>
* <dd>A string to be displayed as the dialog's title.</dd>
* <dt><tt>"description"</tt> (<tt>char *</tt>)</dt>
* <dd>A string to be displayed as the dialog's description. If this is @c
* NULL, the description widget will be hidden.
* </dd>
* <dt><tt>"icon-name"</tt> (<tt>char *</tt>)</dt>
* <dd>The Gtk stock id of an icon for the dialog, or @c NULL for no icon.
* @see pidginstock.h
* </dd>
* <dt><tt>"custom-icon"</tt> (<tt>GdkPixbuf *</tt>)</dt>
* <dd>The custom icon to use instead of a stock one (overrides the "icon-name" property).</dd>
* </dl>
*/
typedef
struct
{
GtkVBox
parent
;
/** A GtkVBox into which extra widgets for the dialog should be packed.
*/
GtkBox
*
contents
;
gpointer
priv
;
}
PidginMiniDialog
;
/** The class of #PidginMiniDialog objects. */
typedef
struct
{
GtkBoxClass
parent_class
;
void
(
*
_purple_reserved1
)
(
void
);
void
(
*
_purple_reserved2
)
(
void
);
void
(
*
_purple_reserved3
)
(
void
);
void
(
*
_purple_reserved4
)
(
void
);
}
PidginMiniDialogClass
;
/** The type of a callback triggered by a button in a mini-dialog being pressed.
* @param mini_dialog a dialog, one of whose buttons has been pressed.
* @param button the button which was pressed.
* @param user_data arbitrary data, supplied to
* pidgin_mini_dialog_add_button() when the button was
* created.
*/
typedef
void
(
*
PidginMiniDialogCallback
)(
PidginMiniDialog
*
mini_dialog
,
GtkButton
*
button
,
gpointer
user_data
);
/** Get the GType of #PidginMiniDialog. */
GType
pidgin_mini_dialog_get_type
(
void
);
/** Creates a new #PidginMiniDialog with a stock icon. This is a shortcut for creating the dialog
* with @c g_object_new() then setting each property yourself.
* @return a new #PidginMiniDialog.
*/
PidginMiniDialog
*
pidgin_mini_dialog_new
(
const
gchar
*
title
,
const
gchar
*
description
,
const
gchar
*
icon_name
);
/** Creates a new #PidginMiniDialog with a custom icon. This is a shortcut for creating the dialog
* with @c g_object_new() then setting each property yourself.
* @return a new #PidginMiniDialog.
*/
PidginMiniDialog
*
pidgin_mini_dialog_new_with_custom_icon
(
const
gchar
*
title
,
const
gchar
*
description
,
GdkPixbuf
*
custom_icon
);
/** Shortcut for setting a mini-dialog's title via GObject properties.
* @param mini_dialog a mini-dialog
* @param title the new title for @a mini_dialog
*/
void
pidgin_mini_dialog_set_title
(
PidginMiniDialog
*
mini_dialog
,
const
char
*
title
);
/** Shortcut for setting a mini-dialog's description via GObject properties.
* @param mini_dialog a mini-dialog
* @param description the new description for @a mini_dialog, or @c NULL to
* hide the description widget.
*/
void
pidgin_mini_dialog_set_description
(
PidginMiniDialog
*
mini_dialog
,
const
char
*
description
);
/** Enable GMarkup elements in the mini-dialog's description.
* @param mini_dialog a mini-dialog
*/
void
pidgin_mini_dialog_enable_description_markup
(
PidginMiniDialog
*
mini_dialog
);
/** Mini-dialogs support hyperlinks in their description
* (you should first call pidgin_mini_dialog_enable_description_markup() on a given
* dialog to enable them). */
gboolean
pidgin_mini_dialog_links_supported
(
void
);
/** Sets a callback which gets invoked when a hyperlink in the dialog's description is clicked on.
* @param mini_dialog a mini-dialog
* @param cb the callback to invoke
* @param user_data the user data to pass to the callback
*/
void
pidgin_mini_dialog_set_link_callback
(
PidginMiniDialog
*
mini_dialog
,
GCallback
cb
,
gpointer
user_data
);
/** Shortcut for setting a mini-dialog's icon via GObject properties.
* @param mini_dialog a mini-dialog
* @param icon_name the Gtk stock ID of an icon, or @c NULL for no icon.
*/
void
pidgin_mini_dialog_set_icon_name
(
PidginMiniDialog
*
mini_dialog
,
const
char
*
icon_name
);
/** Shortcut for setting a mini-dialog's custom icon via GObject properties.
* @param mini_dialog a mini-dialog
* @param custom_icon the pixbuf to use as a custom icon
*/
void
pidgin_mini_dialog_set_custom_icon
(
PidginMiniDialog
*
mini_dialog
,
GdkPixbuf
*
custom_icon
);
/** Adds a new button to a mini-dialog, and attaches the supplied callback to
* its <tt>clicked</tt> signal. After a button is clicked, the dialog is
* destroyed.
* @param mini_dialog a mini-dialog
* @param text the text to display on the new button
* @param clicked_cb the function to call when the button is clicked
* @param user_data arbitrary data to pass to @a clicked_cb when it is
* called.
*/
void
pidgin_mini_dialog_add_button
(
PidginMiniDialog
*
mini_dialog
,
const
char
*
text
,
PidginMiniDialogCallback
clicked_cb
,
gpointer
user_data
);
/** 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
);
/** Gets the number of widgets packed into PidginMiniDialog.contents.
* @param mini_dialog a mini-dialog
* @return the number of widgets in @a mini_dialog->contents.
*/
guint
pidgin_mini_dialog_get_num_children
(
PidginMiniDialog
*
mini_dialog
);
G_END_DECLS
#endif
/* __PIDGIN_MINI_DIALOG_H__ */