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