libpurple/request-datasheet.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_REQUEST_DATA_H_
  23 #define _PURPLE_REQUEST_DATA_H_
  24 /**
  25  * SECTION:request-datasheet
  26  * @section_id: libpurple-request-datasheet
  27  * @short_description: <filename>request-datasheet.h</filename>
  28  * @title: Request Datasheet API
  29  */
  30
  31 #include <glib.h>
  32
  33 typedef struct _PurpleRequestDatasheet PurpleRequestDatasheet;
  34 typedef struct _PurpleRequestDatasheetRecord PurpleRequestDatasheetRecord;
  35 typedef struct _PurpleRequestDatasheetAction PurpleRequestDatasheetAction;
  36
  37 typedef void (*PurpleRequestDatasheetActionCb)(
  38         PurpleRequestDatasheetRecord *rec, gpointer user_data);
  39 typedef gboolean (*PurpleRequestDatasheetActionCheckCb)(
  40         PurpleRequestDatasheetRecord *rec, gpointer user_data);
  41
  42 typedef enum
  43 {
  44         PURPLE_REQUEST_DATASHEET_COLUMN_STRING,
  45         PURPLE_REQUEST_DATASHEET_COLUMN_IMAGE
  46 } PurpleRequestDatasheetColumnType;
  47
  48 G_BEGIN_DECLS
  49
  50 /**************************************************************************/
  51 /* Datasheet API                                                          */
  52 /**************************************************************************/
  53
  54 /**
  55  * purple_request_datasheet_new:
  56  *
  57  * Creates new Datasheet.
  58  *
  59  * Returns: The new datasheet.
  60  */
  61 PurpleRequestDatasheet *
  62 purple_request_datasheet_new(void);
  63
  64 /**
  65  * purple_request_datasheet_free:
  66  * @sheet: The datasheet.
  67  *
  68  * Destroys datasheet with all its contents.
  69  */
  70 void
  71 purple_request_datasheet_free(PurpleRequestDatasheet *sheet);
  72
  73 /**
  74  * purple_request_datasheet_add_column:
  75  * @sheet: The datasheet.
  76  * @type:  The column type.
  77  * @title: The column title (may be %NULL).
  78  *
  79  * Adds a column to the datasheet.
  80  *
  81  * You cannot add a column if datasheet contains any data.
  82  */
  83 void
  84 purple_request_datasheet_add_column(PurpleRequestDatasheet *sheet,
  85         PurpleRequestDatasheetColumnType type, const gchar *title);
  86
  87 /**
  88  * purple_request_datasheet_get_column_count:
  89  * @sheet: The datasheet.
  90  *
  91  * Returns the column count of datasheet.
  92  *
  93  * Returns: The column count.
  94  */
  95 guint
  96 purple_request_datasheet_get_column_count(PurpleRequestDatasheet *sheet);
  97
  98 /**
  99  * purple_request_datasheet_get_column_type:
 100  * @sheet:  The datasheet.
 101  * @col_no: The column number (0 is the first one).
 102  *
 103  * Returns the column type for a datasheet.
 104  *
 105  * Returns: The column type.
 106  */
 107 PurpleRequestDatasheetColumnType
 108 purple_request_datasheet_get_column_type(PurpleRequestDatasheet *sheet,
 109         guint col_no);
 110
 111 /**
 112  * purple_request_datasheet_get_column_title:
 113  * @sheet:  The datasheet.
 114  * @col_no: The column number (0 is the first one).
 115  *
 116  * Returns the column title for a datasheet.
 117  *
 118  * Returns: The column title.
 119  */
 120 const gchar *
 121 purple_request_datasheet_get_column_title(PurpleRequestDatasheet *sheet,
 122         guint col_no);
 123
 124 /**
 125  * purple_request_datasheet_get_records:
 126  * @sheet: The datasheet.
 127  *
 128  * Returns the list of records in a datasheet.
 129  *
 130  * You shouldn't modify datasheet's data while iterating through it.
 131  *
 132  * Returns: (element-type PurpleRequestDatasheetRecord) (transfer none): The list of records.
 133  */
 134 const GList *
 135 purple_request_datasheet_get_records(PurpleRequestDatasheet *sheet);
 136
 137 /**
 138  * purple_request_datasheet_add_action:
 139  * @sheet:  The datasheet.
 140  * @action: The action.
 141  *
 142  * Adds an action to the datasheet.
 143  *
 144  * Action object is owned by the datasheet since this call.
 145  */
 146 void
 147 purple_request_datasheet_add_action(PurpleRequestDatasheet *sheet,
 148         PurpleRequestDatasheetAction *action);
 149
 150 /**
 151  * purple_request_datasheet_get_actions:
 152  * @sheet: The datasheet.
 153  *
 154  * Returns the list of actions in a datasheet.
 155  *
 156  * Returns: (element-type PurpleRequestDatasheetAction) (transfer none): The list of actions.
 157  */
 158 const GList *
 159 purple_request_datasheet_get_actions(PurpleRequestDatasheet *sheet);
 160
 161
 162 /**************************************************************************/
 163 /* Datasheet actions API                                                  */
 164 /**************************************************************************/
 165
 166 /**
 167  * purple_request_datasheet_action_new:
 168  *
 169  * Creates new datasheet action.
 170  *
 171  * Returns: The new action.
 172  */
 173 PurpleRequestDatasheetAction *
 174 purple_request_datasheet_action_new(void);
 175
 176 /**
 177  * purple_request_datasheet_action_free:
 178  * @act: The action.
 179  *
 180  * Destroys the datasheet action.
 181  */
 182 void
 183 purple_request_datasheet_action_free(PurpleRequestDatasheetAction *act);
 184
 185 /**
 186  * purple_request_datasheet_action_set_label:
 187  * @act:   The action.
 188  * @label: The label.
 189  *
 190  * Sets the localized label for the action.
 191  */
 192 void
 193 purple_request_datasheet_action_set_label(PurpleRequestDatasheetAction *act,
 194         const gchar *label);
 195
 196 /**
 197  * purple_request_datasheet_action_get_label:
 198  * @act: The action.
 199  *
 200  * Gets the label of action.
 201  *
 202  * Returns: The localized label text.
 203  */
 204 const gchar*
 205 purple_request_datasheet_action_get_label(PurpleRequestDatasheetAction *act);
 206
 207 /**
 208  * purple_request_datasheet_action_set_cb:
 209  * @act:       The action.
 210  * @cb:        The callback function.
 211  * @user_data: The data to be passed to the callback function.
 212  *
 213  * Sets the callback for the action.
 214  */
 215 void
 216 purple_request_datasheet_action_set_cb(PurpleRequestDatasheetAction *act,
 217         PurpleRequestDatasheetActionCb cb, gpointer user_data);
 218
 219 /**
 220  * purple_request_datasheet_action_call:
 221  * @act: The action.
 222  * @rec: The user selected record.
 223  *
 224  * Calls the callback of the action.
 225  */
 226 void
 227 purple_request_datasheet_action_call(PurpleRequestDatasheetAction *act,
 228         PurpleRequestDatasheetRecord *rec);
 229
 230 /**
 231  * purple_request_datasheet_action_set_sens_cb:
 232  * @act:       The action.
 233  * @cb:        The callback function, may be %NULL.
 234  * @user_data: The data to be passed to the callback function.
 235  *
 236  * Sets the sensitivity checker for the action.
 237  *
 238  * If there is no callback set, default is used: the action is enabled, if any
 239  * record is active.
 240  */
 241 void
 242 purple_request_datasheet_action_set_sens_cb(
 243         PurpleRequestDatasheetAction *act,
 244         PurpleRequestDatasheetActionCheckCb cb, gpointer user_data);
 245
 246 /**
 247  * purple_request_datasheet_action_is_sensitive:
 248  * @act: The action.
 249  * @rec: The record.
 250  *
 251  * Checks, if the action is enabled for the active record.
 252  *
 253  * Returns: %TRUE, if the action is enabled, %FALSE otherwise.
 254  */
 255 gboolean
 256 purple_request_datasheet_action_is_sensitive(PurpleRequestDatasheetAction *act,
 257         PurpleRequestDatasheetRecord *rec);
 258
 259
 260 /**************************************************************************/
 261 /* Datasheet record API                                                   */
 262 /**************************************************************************/
 263
 264 /**
 265  * purple_request_datasheet_record_get_key:
 266  * @rec: The record.
 267  *
 268  * Returns the key of a record.
 269  *
 270  * Returns: The key.
 271  */
 272 gpointer
 273 purple_request_datasheet_record_get_key(
 274         const PurpleRequestDatasheetRecord *rec);
 275
 276 /**
 277  * purple_request_datasheet_record_get_datasheet:
 278  * @rec: The record.
 279  *
 280  * Returns the datasheet of a record.
 281  *
 282  * Returns: The datasheet.
 283  */
 284 PurpleRequestDatasheet *
 285 purple_request_datasheet_record_get_datasheet(
 286         PurpleRequestDatasheetRecord *rec);
 287
 288 /**
 289  * purple_request_datasheet_record_find:
 290  * @sheet: The datasheet.
 291  * @key:   The key.
 292  *
 293  * Looks up for a record in datasheet.
 294  *
 295  * Returns: The record if found, %NULL otherwise.
 296  */
 297 PurpleRequestDatasheetRecord *
 298 purple_request_datasheet_record_find(PurpleRequestDatasheet *sheet,
 299         gpointer key);
 300
 301 /**
 302  * purple_request_datasheet_record_add:
 303  * @sheet: The datasheet.
 304  * @key:   The key.
 305  *
 306  * Adds a record to the datasheet.
 307  *
 308  * If the specified key already exists in datasheet, old record is returned.
 309  *
 310  * Returns: The record.
 311  */
 312 PurpleRequestDatasheetRecord *
 313 purple_request_datasheet_record_add(PurpleRequestDatasheet *sheet,
 314         gpointer key);
 315
 316 /**
 317  * purple_request_datasheet_record_remove:
 318  * @sheet: The datasheet.
 319  * @key:   The key.
 320  *
 321  * Removes a record from a datasheet.
 322  */
 323 void
 324 purple_request_datasheet_record_remove(PurpleRequestDatasheet *sheet,
 325         gpointer key);
 326
 327 /**
 328  * purple_request_datasheet_record_remove_all:
 329  * @sheet: The datasheet.
 330  *
 331  * Removes all records from a datasheet.
 332  */
 333 void
 334 purple_request_datasheet_record_remove_all(PurpleRequestDatasheet *sheet);
 335
 336 /**
 337  * purple_request_datasheet_record_mark_all_for_rem:
 338  * @sheet: The datasheet.
 339  *
 340  * Marks all records for removal. Record will be unmarked, when touched with
 341  * purple_request_datasheet_record_add.
 342  *
 343  * See purple_request_datasheet_record_add().
 344  */
 345 void
 346 purple_request_datasheet_record_mark_all_for_rem(PurpleRequestDatasheet *sheet);
 347
 348 /**
 349  * purple_request_datasheet_record_remove_marked:
 350  * @sheet: The datasheet.
 351  *
 352  * Removes all marked records.
 353  *
 354  * See purple_request_datasheet_record_mark_all_for_rem().
 355  */
 356 void
 357 purple_request_datasheet_record_remove_marked(PurpleRequestDatasheet *sheet);
 358
 359 /**
 360  * purple_request_datasheet_record_set_string_data:
 361  * @rec:    The record.
 362  * @col_no: The column.
 363  * @data:   The data.
 364  *
 365  * Sets data for a string column of specified record.
 366  */
 367 void
 368 purple_request_datasheet_record_set_string_data(
 369         PurpleRequestDatasheetRecord *rec, guint col_no, const gchar *data);
 370
 371 /**
 372  * purple_request_datasheet_record_set_image_data:
 373  * @rec:      The record.
 374  * @col_no:   The column.
 375  * @stock_id: The stock identifier of a image.
 376  *
 377  * Sets data for a image column of specified record.
 378  */
 379 void
 380 purple_request_datasheet_record_set_image_data(
 381         PurpleRequestDatasheetRecord *rec, guint col_no, const gchar *stock_id);
 382
 383 /**
 384  * purple_request_datasheet_record_get_string_data:
 385  * @rec:    The record.
 386  * @col_no: The column.
 387  *
 388  * Returns data for a string column of specified record.
 389  *
 390  * Returns: The data.
 391  */
 392 const gchar *
 393 purple_request_datasheet_record_get_string_data(
 394         const PurpleRequestDatasheetRecord *rec, guint col_no);
 395
 396 /**
 397  * purple_request_datasheet_record_get_image_data:
 398  * @rec:    The record.
 399  * @col_no: The column.
 400  *
 401  * Returns data for an image column of specified record.
 402  *
 403  * Returns: The stock id of an image.
 404  */
 405 const gchar *
 406 purple_request_datasheet_record_get_image_data(
 407         const PurpleRequestDatasheetRecord *rec, guint col_no);
 408
 409 G_END_DECLS
 410
 411 #endif /* _PURPLE_REQUEST_DATA_H_ */