libpurple/action.h

   1 /* purple
   2  *
   3  * Purple 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 PURPLE_ACTION
  23 #define PURPLE_ACTION
  24
  25 #include <glib.h>
  26 #include <glib-object.h>
  27
  28 #define PURPLE_TYPE_PROTOCOL_ACTION (purple_protocol_action_get_type())
  29 typedef struct _PurpleProtocolAction PurpleProtocolAction;
  30
  31 typedef void (*PurpleProtocolActionCallback)(PurpleProtocolAction *action);
  32
  33 /**
  34  * PurpleActionMenu:
  35  *
  36  * A generic structure that contains information about an "action".  One
  37  * place this is used is by protocols to tell the core the list of available
  38  * right-click actions for a buddy list row.
  39  */
  40 typedef struct _PurpleActionMenu PurpleActionMenu;
  41
  42 #include "connection.h"
  43
  44 /**
  45  * PurpleProtocolAction:
  46  * @label: A translated string to be shown in a user interface.
  47  * @callback: The function to call when the user wants to perform this action.
  48  * @connection: The connection that this action should be performed against.
  49  * @user_data: User data to pass to @callback.
  50  *
  51  * Represents an action that the protocol can perform. This shows up in the
  52  * Accounts menu, under a submenu with the name of the account.
  53  */
  54 struct _PurpleProtocolAction {
  55         gchar *label;
  56         PurpleProtocolActionCallback callback;
  57         PurpleConnection *connection;
  58         gpointer user_data;
  59 };
  60
  61 G_BEGIN_DECLS
  62
  63 /******************************************************************************
  64  * Menu Action API
  65  *****************************************************************************/
  66
  67 /**
  68  * purple_action_menu_new:
  69  * @label:    The text label to display for this action.
  70  * @callback: The function to be called when the action is used on
  71  *                 the selected item.
  72  * @data:     Additional data to be passed to the callback.
  73  * @children: (element-type PurpleActionMenu) (transfer full): Menu actions to
  74  *            be added as a submenu of this action.
  75  *
  76  * Creates a new PurpleActionMenu.
  77  *
  78  * Returns: The PurpleActionMenu.
  79  */
  80 PurpleActionMenu *purple_action_menu_new(const gchar *label, GCallback callback, gpointer data, GList *children);
  81
  82 /**
  83  * purple_action_menu_free:
  84  * @act: The PurpleActionMenu to free.
  85  *
  86  * Frees a PurpleActionMenu
  87  */
  88 void purple_action_menu_free(PurpleActionMenu *act);
  89
  90 /**
  91  * purple_action_menu_get_label:
  92  * @act:        The PurpleActionMenu.
  93  *
  94  * Returns the label of the PurpleActionMenu.
  95  *
  96  * Returns: The label string.
  97  */
  98 const gchar *purple_action_menu_get_label(const PurpleActionMenu *act);
  99
 100 /**
 101  * purple_action_menu_get_callback:
 102  * @act:        The PurpleActionMenu.
 103  *
 104  * Returns the callback of the PurpleActionMenu.
 105  *
 106  * Returns: The callback function.
 107  */
 108 GCallback purple_action_menu_get_callback(const PurpleActionMenu *act);
 109
 110 /**
 111  * purple_action_menu_get_data:
 112  * @act:        The PurpleActionMenu.
 113  *
 114  * Returns the data stored in the PurpleActionMenu.
 115  *
 116  * Returns: The data.
 117  */
 118 gpointer purple_action_menu_get_data(const PurpleActionMenu *act);
 119
 120 /**
 121  * purple_action_menu_get_children:
 122  * @act:        The PurpleActionMenu.
 123  *
 124  * Returns the children of the PurpleActionMenu.
 125  *
 126  * Returns: (element-type PurpleActionMenu) (transfer none): The menu children.
 127  */
 128 GList* purple_action_menu_get_children(const PurpleActionMenu *act);
 129
 130 /**
 131  * purple_action_menu_set_label:
 132  * @act:   The menu action.
 133  * @label: The label for the menu action.
 134  *
 135  * Set the label to the PurpleActionMenu.
 136  */
 137 void purple_action_menu_set_label(PurpleActionMenu *act, const gchar *label);
 138
 139 /**
 140  * purple_action_menu_set_callback:
 141  * @act:        The menu action.
 142  * @callback:   The callback.
 143  *
 144  * Set the callback that will be used by the PurpleActionMenu.
 145  */
 146 void purple_action_menu_set_callback(PurpleActionMenu *act, GCallback callback);
 147
 148 /**
 149  * purple_action_menu_set_data:
 150  * @act:   The menu action.
 151  * @data:  The data used by this PurpleActionMenu
 152  *
 153  * Set the label to the PurpleActionMenu.
 154  */
 155 void purple_action_menu_set_data(PurpleActionMenu *act, gpointer data);
 156
 157 /**
 158  * purple_action_menu_set_children:
 159  * @act:       The menu action.
 160  * @children: (element-type PurpleActionMenu) (transfer full): The menu children
 161  *
 162  * Set the children of the PurpleActionMenu.
 163  */
 164 void purple_action_menu_set_children(PurpleActionMenu *act, GList *children);
 165
 166 /******************************************************************************
 167  * Protocol Action API
 168  *****************************************************************************/
 169
 170 /**
 171  * purple_protocol_action_get_type:
 172  *
 173  * Returns: The #GType for the #PurpleProtocolAction boxed structure.
 174  */
 175 GType purple_protocol_action_get_type(void);
 176
 177 /**
 178  * purple_protocol_action_new:
 179  * @label:    The description of the action to show to the user.
 180  * @callback: (scope call): The callback to call when the user selects this
 181  *            action.
 182  *
 183  * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
 184  * a list in the get_actions function of the protocol.
 185  *
 186  * Returns: (transfer full): The new #PurpleProtocolAction.
 187  */
 188 PurpleProtocolAction *purple_protocol_action_new(const gchar *label, PurpleProtocolActionCallback callback);
 189
 190 /**
 191  * purple_protocol_action_copy:
 192  * @action: The #PurpleProtocolAction to copy.
 193  *
 194  * Creates a newly allocated copy of @action.
 195  *
 196  * Returns: (transfer full): A copy of @action.
 197  */
 198 PurpleProtocolAction *purple_protocol_action_copy(PurpleProtocolAction *action);
 199
 200 /**
 201  * purple_protocol_action_free:
 202  * @action: The PurpleProtocolAction to free.
 203  *
 204  * Frees a PurpleProtocolAction
 205  */
 206 void purple_protocol_action_free(PurpleProtocolAction *action);
 207
 208
 209 G_END_DECLS
 210
 211 #endif /* PURPLE_ACTION */