pidgin/pidgininvitedialog.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_INVITE_DIALOG_H
  23 #define PIDGIN_INVITE_DIALOG_H
  24
  25 /**
  26  * SECTION:pidgininvitedialog
  27  * @section_id: pidgin-invite-dialog
  28  * @short_description: A dialog widget to invite others to chat
  29  * @title: Invite Dialog
  30  *
  31  * #PidginInviteDialog is a simple #GtkDialog that presents the user with an
  32  * interface to invite another user to a conversation.  Name completion is
  33  * automatically setup as well.
  34  *
  35  * |[<!-- language="C" -->
  36  * static void
  37  * invite_response(GtkWidget *widget, int resp, gpointer data) {
  38  *     PidginInviteDialog *dialog = PIDGIN_INVITE_DIALOG(widget);
  39  *
  40  *     if(resp == GTK_RESPONSE_ACCEPT) {
  41  *         g_message(
  42  *             "user wants to invite %s with message %s",
  43  *             pidgin_invite_dialog_get_contact(dialog),
  44  *             pidgin_invite_dialog_get_message(dialog)
  45  *         );
  46  *     }
  47  * }
  48  *
  49  * static void
  50  * invite_prompt(PurpleChatConversation *conv) {
  51  *     GtkWidget *dialog = pidgin_invite_dialog_new(conv);
  52  *     g_signal_connect(G_OBJECT(dialog), "response",
  53  *                      G_CALLBACK(invite_response), NULL);
  54  *
  55  * }
  56  * ]|
  57  */
  58
  59 #include <gtk/gtk.h>
  60
  61 #include <purple.h>
  62
  63 G_BEGIN_DECLS
  64
  65 #define PIDGIN_TYPE_INVITE_DIALOG  pidgin_invite_dialog_get_type()
  66
  67 G_DECLARE_FINAL_TYPE(PidginInviteDialog, pidgin_invite_dialog, PIDGIN,
  68                 INVITE_DIALOG, GtkDialog)
  69
  70 /**
  71  * pidgin_invite_dialog_new:
  72  * @conversation: The #PurpleChatConversation instance.
  73  *
  74  * Creates a new #PidginInviteDialog to invite someone to @conversation.
  75  *
  76  * Returns: (transfer full): The new #PidginInviteDialog instance.
  77  *
  78  * Since: 3.0.0
  79  */
  80 GtkWidget *pidgin_invite_dialog_new(PurpleChatConversation *conversation);
  81
  82 /**
  83  * pidgin_invite_dialog_set_contact:
  84  * @dialog: The #PidginInviteDialog instance.
  85  * @contact: The contact to invite.
  86  *
  87  * Sets the contact that should be invited.  This function is intended to be
  88  * used to prepopulate the dialog in cases where you just need to prompt the
  89  * user for an invite message.
  90  *
  91  * Since: 3.0.0
  92  */
  93 void pidgin_invite_dialog_set_contact(PidginInviteDialog *dialog, const gchar *contact);
  94
  95 /**
  96  * pidgin_invite_dialog_get_contact:
  97  * @dialog: #PidginInviteDialog instance.
  98  *
  99  * Gets the contact that was entered in @dialog.  This string is only valid as
 100  * long as @dialog exists.
 101  *
 102  * Returns: (transfer none): The contact that was entered.
 103  *
 104  * Since: 3.0.0
 105  */
 106 const gchar *pidgin_invite_dialog_get_contact(PidginInviteDialog *dialog);
 107
 108 /**
 109  * pidgin_invite_dialog_set_message:
 110  * @dialog: The #PidginInviteDialog instance.
 111  * @message: The message that should be displayed.
 112  *
 113  * Sets the message to be displayed in @dialog.  The main use case is to
 114  * prepopulate the message.
 115  *
 116  * Since: 3.0.0
 117  */
 118 void pidgin_invite_dialog_set_message(PidginInviteDialog *dialog, const gchar *message);
 119
 120 /**
 121  * pidgin_invite_dialog_get_message:
 122  * @dialog: The #PidginInviteDialog instance.
 123  *
 124  * Gets the message that was entered in @dialog.  The returned value is only
 125  * valid as long as @dialog exists.
 126  *
 127  * Returns: (transfer none): The message that was entered in @dialog.
 128  *
 129  * Since: 3.0.0
 130  */
 131 const gchar *pidgin_invite_dialog_get_message(PidginInviteDialog *dialog);
 132
 133 /**
 134  * pidgin_invite_dialog_get_conversation:
 135  * @dialog: The #PidginInviteDialog instance.
 136  *
 137  * Gets the #PurpleChatConversation that @dialog was created for.
 138  *
 139  * Returns: (transfer none): The #PurpleChatConversation that @dialog was
 140  *          created with.
 141  *
 142  * Since: 3.0.0
 143  */
 144 PurpleChatConversation *pidgin_invite_dialog_get_conversation(PidginInviteDialog *dialog);
 145
 146 G_END_DECLS
 147
 148 #endif /* PIDGIN_INVITE_DIALOG_H */