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