libpurple/whiteboard.h

   1 /**
   2  * @file whiteboard.h The PurpleWhiteboard core object
   3  */
   4
   5 /* purple
   6  *
   7  * Purple is the legal property of its developers, whose names are too numerous
   8  * to list here.  Please refer to the COPYRIGHT file distributed with this
   9  * source distribution.
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  24  */
  25
  26 #ifndef _PURPLE_WHITEBOARD_H_
  27 #define _PURPLE_WHITEBOARD_H_
  28
  29 /**
  30  * Whiteboard PRPL Operations
  31  */
  32 typedef struct _PurpleWhiteboardPrplOps PurpleWhiteboardPrplOps;
  33
  34 #include "account.h"
  35
  36 /**
  37  * A PurpleWhiteboard
  38  */
  39 typedef struct _PurpleWhiteboard
  40 {
  41         int state;                       /**< State of whiteboard session */
  42
  43         PurpleAccount *account;            /**< Account associated with this session */
  44         char *who;                       /**< Name of the remote user */
  45
  46         void *ui_data;                   /**< Graphical user-interface data */
  47         void *proto_data;                /**< Protocol specific data */
  48         PurpleWhiteboardPrplOps *prpl_ops; /**< Protocol-plugin operations */
  49
  50         GList *draw_list;                /**< List of drawing elements/deltas to send */
  51 } PurpleWhiteboard;
  52
  53 /**
  54  * The PurpleWhiteboard UI Operations
  55  */
  56 typedef struct _PurpleWhiteboardUiOps
  57 {
  58         void (*create)(PurpleWhiteboard *wb);                                 /**< create function */
  59         void (*destroy)(PurpleWhiteboard *wb);                               /**< destory function */
  60         void (*set_dimensions)(PurpleWhiteboard *wb, int width, int height); /**< set_dimensions function */
  61         void (*set_brush) (PurpleWhiteboard *wb, int size, int color);          /**< set the size and color of the brush */
  62         void (*draw_point)(PurpleWhiteboard *wb, int x, int y,
  63                                            int color, int size);                           /**< draw_point function */
  64         void (*draw_line)(PurpleWhiteboard *wb, int x1, int y1,
  65                                           int x2, int y2,
  66                                           int color, int size);                            /**< draw_line function */
  67         void (*clear)(PurpleWhiteboard *wb);                                 /**< clear function */
  68
  69         void (*_purple_reserved1)(void);
  70         void (*_purple_reserved2)(void);
  71         void (*_purple_reserved3)(void);
  72         void (*_purple_reserved4)(void);
  73 } PurpleWhiteboardUiOps;
  74
  75 /**
  76  * PurpleWhiteboard PRPL Operations
  77  */
  78 struct _PurpleWhiteboardPrplOps
  79 {
  80         void (*start)(PurpleWhiteboard *wb);                                   /**< start function */
  81         void (*end)(PurpleWhiteboard *wb);                                     /**< end function */
  82         void (*get_dimensions)(const PurpleWhiteboard *wb, int *width, int *height); /**< get_dimensions function */
  83         void (*set_dimensions)(PurpleWhiteboard *wb, int width, int height);   /**< set_dimensions function */
  84         void (*get_brush) (const PurpleWhiteboard *wb, int *size, int *color); /**< get the brush size and color */
  85         void (*set_brush) (PurpleWhiteboard *wb, int size, int color);         /**< set the brush size and color */
  86         void (*send_draw_list)(PurpleWhiteboard *wb, GList *draw_list);        /**< send_draw_list function */
  87         void (*clear)(PurpleWhiteboard *wb);                                   /**< clear function */
  88
  89         void (*_purple_reserved1)(void);
  90         void (*_purple_reserved2)(void);
  91         void (*_purple_reserved3)(void);
  92         void (*_purple_reserved4)(void);
  93 };
  94
  95 #ifdef __cplusplus
  96 extern "C" {
  97 #endif /* __cplusplus */
  98
  99 /******************************************************************************/
 100 /** @name PurpleWhiteboard API                                                  */
 101 /******************************************************************************/
 102 /*@{*/
 103
 104 /**
 105  * Sets the UI operations
 106  *
 107  * @param ops The UI operations to set
 108  */
 109 void purple_whiteboard_set_ui_ops(PurpleWhiteboardUiOps *ops);
 110
 111 /**
 112  * Sets the prpl operations for a whiteboard
 113  *
 114  * @param wb  The whiteboard for which to set the prpl operations
 115  * @param ops The prpl operations to set
 116  */
 117 void purple_whiteboard_set_prpl_ops(PurpleWhiteboard *wb, PurpleWhiteboardPrplOps *ops);
 118
 119 /**
 120  * Creates a whiteboard
 121  *
 122  * @param account The account.
 123  * @param who     Who you're drawing with.
 124  * @param state   The state.
 125  *
 126  * @return The new whiteboard
 127  */
 128 PurpleWhiteboard *purple_whiteboard_create(PurpleAccount *account, const char *who, int state);
 129
 130 /**
 131  * Destroys a whiteboard
 132  *
 133  * @param wb The whiteboard.
 134  */
 135 void purple_whiteboard_destroy(PurpleWhiteboard *wb);
 136
 137 /**
 138  * Starts a whiteboard
 139  *
 140  * @param wb The whiteboard.
 141  */
 142 void purple_whiteboard_start(PurpleWhiteboard *wb);
 143
 144 /**
 145  * Finds a whiteboard from an account and user.
 146  *
 147  * @param account The account.
 148  * @param who     The user.
 149  *
 150  * @return The whiteboard if found, otherwise @c NULL.
 151  */
 152 PurpleWhiteboard *purple_whiteboard_get_session(const PurpleAccount *account, const char *who);
 153
 154 /**
 155  * Destorys a drawing list for a whiteboard
 156  *
 157  * @param draw_list The drawing list.
 158  */
 159 void purple_whiteboard_draw_list_destroy(GList *draw_list);
 160
 161 /**
 162  * Gets the dimension of a whiteboard.
 163  *
 164  * @param wb            The whiteboard.
 165  * @param width         The width to be set.
 166  * @param height        The height to be set.
 167  *
 168  * @return TRUE if the values of width and height were set.
 169  */
 170 gboolean purple_whiteboard_get_dimensions(const PurpleWhiteboard *wb, int *width, int *height);
 171
 172 /**
 173  * Sets the dimensions for a whiteboard.
 174  *
 175  * @param wb     The whiteboard.
 176  * @param width  The width.
 177  * @param height The height.
 178  */
 179 void purple_whiteboard_set_dimensions(PurpleWhiteboard *wb, int width, int height);
 180
 181 /**
 182  * Draws a point on a whiteboard.
 183  *
 184  * @param wb    The whiteboard.
 185  * @param x     The x coordinate.
 186  * @param y     The y coordinate.
 187  * @param color The color to use.
 188  * @param size  The brush size.
 189  */
 190 void purple_whiteboard_draw_point(PurpleWhiteboard *wb, int x, int y, int color, int size);
 191
 192 /**
 193  * Send a list of points to draw to the buddy.
 194  *
 195  * @param wb    The whiteboard
 196  * @param list  A GList of points
 197  */
 198 void purple_whiteboard_send_draw_list(PurpleWhiteboard *wb, GList *list);
 199
 200 /**
 201  * Draws a line on a whiteboard
 202  *
 203  * @param wb    The whiteboard.
 204  * @param x1    The top-left x coordinate.
 205  * @param y1    The top-left y coordinate.
 206  * @param x2    The bottom-right x coordinate.
 207  * @param y2    The bottom-right y coordinate.
 208  * @param color The color to use.
 209  * @param size  The brush size.
 210  */
 211 void purple_whiteboard_draw_line(PurpleWhiteboard *wb, int x1, int y1, int x2, int y2, int color, int size);
 212
 213 /**
 214  * Clears a whiteboard
 215  *
 216  * @param wb The whiteboard.
 217  */
 218 void purple_whiteboard_clear(PurpleWhiteboard *wb);
 219
 220 /**
 221  * Sends a request to the buddy to clear the whiteboard.
 222  *
 223  * @param wb The whiteboard
 224  */
 225 void purple_whiteboard_send_clear(PurpleWhiteboard *wb);
 226
 227 /**
 228  * Sends a request to change the size and color of the brush.
 229  *
 230  * @param wb    The whiteboard
 231  * @param size  The size of the brush
 232  * @param color The color of the brush
 233  */
 234 void purple_whiteboard_send_brush(PurpleWhiteboard *wb, int size, int color);
 235
 236 /**
 237  * Gets the size and color of the brush.
 238  *
 239  * @param wb    The whiteboard
 240  * @param size  The size of the brush
 241  * @param color The color of the brush
 242  *
 243  * @return      TRUE if the size and color were set.
 244  */
 245 gboolean purple_whiteboard_get_brush(const PurpleWhiteboard *wb, int *size, int *color);
 246
 247 /**
 248  * Sets the size and color of the brush.
 249  *
 250  * @param wb    The whiteboard
 251  * @param size  The size of the brush
 252  * @param color The color of the brush
 253  */
 254 void purple_whiteboard_set_brush(PurpleWhiteboard *wb, int size, int color);
 255
 256 /*@}*/
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif /* __cplusplus */
 261
 262 #endif /* _PURPLE_WHITEBOARD_H_ */