pidgin/gtkimhtml.h

   1 /**
   2  * @file gtkimhtml.h GTK+ IM/HTML rendering component
   3  * @ingroup pidgin
   4  * @see @ref gtkimhtml-signals
   5  */
   6
   7 /* Pidgin 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  * 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 #ifndef _PIDGINIMHTML_H_
  26 #define _PIDGINIMHTML_H_
  27
  28 #include <gdk/gdk.h>
  29 #include <gtk/gtk.h>
  30 #include "gtksourceundomanager.h"
  31
  32 #include "connection.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**************************************************************************
  39  * @name Structures
  40  **************************************************************************/
  41 /*@{*/
  42
  43 #define GTK_TYPE_IMHTML            (gtk_imhtml_get_type())
  44 #define GTK_IMHTML(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), GTK_TYPE_IMHTML, GtkIMHtml))
  45 #define GTK_IMHTML_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), GTK_TYPE_IMHTML, GtkIMHtmlClass))
  46 #define GTK_IS_IMHTML(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), GTK_TYPE_IMHTML))
  47 #define GTK_IS_IMHTML_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GTK_TYPE_IMHTML))
  48 #define GTK_IMHTML_SCALABLE(obj)   ((GtkIMHtmlScalable *)obj)
  49 #define GTK_IMHTML_ANIMATION(obj)  ((GtkIMHtmlAnimation *)obj)
  50
  51 typedef struct _GtkIMHtml                       GtkIMHtml;
  52 typedef struct _GtkIMHtmlClass          GtkIMHtmlClass;
  53 #if !(defined PIDGIN_DISABLE_DEPRECATED) && !(defined _PIDGIN_GTKIMHTML_C_)
  54 typedef struct _GtkIMHtmlFontDetail     GtkIMHtmlFontDetail;    /* The five elements contained in a FONT tag */
  55 #endif
  56 typedef struct _GtkSmileyTree           GtkSmileyTree;
  57 typedef struct _GtkIMHtmlSmiley         GtkIMHtmlSmiley;
  58 typedef struct _GtkIMHtmlScalable       GtkIMHtmlScalable;
  59 typedef struct _GtkIMHtmlImage          GtkIMHtmlImage;
  60 typedef struct _GtkIMHtmlAnimation      GtkIMHtmlAnimation;
  61 typedef struct _GtkIMHtmlHr                     GtkIMHtmlHr;
  62 typedef struct _GtkIMHtmlFuncs          GtkIMHtmlFuncs;
  63
  64 /**
  65  * @since 2.6.0
  66  */
  67 typedef struct _GtkIMHtmlLink       GtkIMHtmlLink;
  68
  69 typedef enum {
  70         GTK_IMHTML_BOLD =       1 << 0,
  71         GTK_IMHTML_ITALIC =     1 << 1,
  72         GTK_IMHTML_UNDERLINE =  1 << 2,
  73         GTK_IMHTML_GROW =       1 << 3,
  74         GTK_IMHTML_SHRINK =     1 << 4,
  75         GTK_IMHTML_FACE =       1 << 5,
  76         GTK_IMHTML_FORECOLOR =  1 << 6,
  77         GTK_IMHTML_BACKCOLOR =  1 << 7,
  78         GTK_IMHTML_BACKGROUND = 1 << 8,
  79         GTK_IMHTML_LINK =       1 << 9,
  80         GTK_IMHTML_IMAGE =      1 << 10,
  81         GTK_IMHTML_SMILEY =     1 << 11,
  82         GTK_IMHTML_LINKDESC =   1 << 12,
  83         GTK_IMHTML_STRIKE =     1 << 13,
  84         /** Show custom smileys when appropriate. @since 2.5.0 */
  85         GTK_IMHTML_CUSTOM_SMILEY = 1 << 14,
  86         GTK_IMHTML_ALL =       -1
  87 } GtkIMHtmlButtons;
  88
  89 typedef enum {
  90         GTK_IMHTML_SMILEY_CUSTOM =      1 << 0
  91 } GtkIMHtmlSmileyFlags;
  92
  93 struct _GtkIMHtml {
  94         GtkTextView text_view;
  95         GtkTextBuffer *text_buffer;
  96         GdkCursor *hand_cursor;
  97         GdkCursor *arrow_cursor;
  98         GdkCursor *text_cursor;
  99         GHashTable *smiley_data;
 100         GtkSmileyTree *default_smilies;
 101         char *protocol_name;
 102         guint scroll_src;
 103         GTimer *scroll_time;
 104         GQueue *animations;
 105         int num_animations;
 106
 107         gboolean show_comments;
 108
 109         GtkWidget *tip_window;
 110         char *tip;
 111         guint tip_timer;
 112         GtkTextTag *prelit_tag;
 113
 114         GList *scalables;
 115         GdkRectangle old_rect;
 116
 117         gchar *search_string;
 118
 119         gboolean editable;
 120         GtkIMHtmlButtons format_functions;
 121         gboolean wbfo;  /* Whole buffer formatting only. */
 122
 123         gint insert_offset;
 124
 125         struct {
 126                 gboolean bold:1;
 127                 gboolean italic:1;
 128                 gboolean underline:1;
 129                 gboolean strike:1;
 130                 gchar *forecolor;
 131                 gchar *backcolor;
 132                 gchar *background;
 133                 gchar *fontface;
 134                 int fontsize;
 135                 GtkTextTag *link;
 136         } edit;
 137
 138 #if !(defined PIDGIN_DISABLE_DEPRECATED) || (defined _PIDGIN_GTKIMHTML_C_)
 139         /** @deprecated */
 140         char *clipboard_text_string;
 141         /** @deprecated */
 142         char *clipboard_html_string;
 143 #else
 144         char *depr1;
 145         char *depr2;
 146 #endif
 147
 148         GSList *im_images;
 149         GtkIMHtmlFuncs *funcs;
 150         GtkSourceUndoManager *undo_manager;
 151 };
 152
 153 struct _GtkIMHtmlClass {
 154         GtkTextViewClass parent_class;
 155
 156         void (*url_clicked)(GtkIMHtml *, const gchar *);
 157         void (*buttons_update)(GtkIMHtml *, GtkIMHtmlButtons);
 158         void (*toggle_format)(GtkIMHtml *, GtkIMHtmlButtons);
 159         void (*clear_format)(GtkIMHtml *);
 160         void (*update_format)(GtkIMHtml *);
 161         gboolean (*message_send)(GtkIMHtml *);
 162         void (*undo)(GtkIMHtml *);
 163         void (*redo)(GtkIMHtml *);
 164         GList *protocols; /* List of GtkIMHtmlProtocol's */
 165 };
 166
 167 #if !(defined PIDGIN_DISABLE_DEPRECATED) && !(defined _PIDGIN_GTKIMHTML_C_)
 168 /** @deprecated as of 2.7.10 */
 169 struct _GtkIMHtmlFontDetail {
 170         gushort size;
 171         gchar *face;
 172         gchar *fore;
 173         gchar *back;
 174         gchar *bg;
 175         gchar *sml;
 176         gboolean underline;
 177         gshort bold;
 178 };
 179 #endif
 180
 181 struct _GtkSmileyTree {
 182         GString *values;
 183         GtkSmileyTree **children;
 184         GtkIMHtmlSmiley *image;
 185 };
 186
 187 struct _GtkIMHtmlSmiley {
 188         gchar *smile;
 189         gchar *file;
 190         GdkPixbufAnimation *icon;
 191         gboolean hidden;
 192         GdkPixbufLoader *loader;
 193         GSList *anchors;
 194         GtkIMHtmlSmileyFlags flags;
 195         GtkIMHtml *imhtml;
 196         gpointer data;       /** @since 2.6.0 */
 197         gsize datasize;      /** @since 2.6.0 */
 198 };
 199
 200 struct _GtkIMHtmlScalable {
 201         void (*scale)(struct _GtkIMHtmlScalable *, int, int);
 202         void (*add_to)(struct _GtkIMHtmlScalable *, GtkIMHtml *, GtkTextIter *);
 203         void (*free)(struct _GtkIMHtmlScalable *);
 204 };
 205
 206 struct _GtkIMHtmlImage {
 207         GtkIMHtmlScalable scalable;
 208         GtkImage *image; /**< Contains the scaled version of this pixbuf. */
 209         GdkPixbuf *pixbuf; /**< The original pixbuf, before any scaling. */
 210         GtkTextMark *mark;
 211         gchar *filename;
 212         int width;
 213         int height;
 214         int id;
 215         GtkWidget *filesel;
 216 };
 217
 218 struct _GtkIMHtmlAnimation {
 219         GtkIMHtmlImage imhtmlimage;
 220         GdkPixbufAnimation *anim; /**< The original animation, before any scaling. */
 221         GdkPixbufAnimationIter *iter;
 222         guint timer;
 223 };
 224
 225 struct _GtkIMHtmlHr {
 226         GtkIMHtmlScalable scalable;
 227         GtkWidget *sep;
 228 };
 229
 230 typedef enum {
 231         GTK_IMHTML_NO_COLOURS          = 1 << 0,
 232         GTK_IMHTML_NO_FONTS            = 1 << 1,
 233         GTK_IMHTML_NO_COMMENTS         = 1 << 2, /* Remove */
 234         GTK_IMHTML_NO_TITLE            = 1 << 3,
 235         GTK_IMHTML_NO_NEWLINE          = 1 << 4,
 236         GTK_IMHTML_NO_SIZES            = 1 << 5,
 237         GTK_IMHTML_NO_SCROLL           = 1 << 6,
 238         GTK_IMHTML_RETURN_LOG          = 1 << 7,
 239         GTK_IMHTML_USE_POINTSIZE       = 1 << 8,
 240         GTK_IMHTML_NO_FORMATTING       = 1 << 9,
 241         GTK_IMHTML_USE_SMOOTHSCROLLING = 1 << 10,
 242         GTK_IMHTML_NO_SMILEY           = 1 << 11
 243 } GtkIMHtmlOptions;
 244
 245 enum {
 246         GTK_IMHTML_DRAG_URL = 0,
 247         GTK_IMHTML_DRAG_HTML,
 248         GTK_IMHTML_DRAG_UTF8_STRING,
 249         GTK_IMHTML_DRAG_COMPOUND_TEXT,
 250         GTK_IMHTML_DRAG_STRING,
 251         GTK_IMHTML_DRAG_TEXT,
 252         GTK_IMHTML_DRAG_NUM
 253 };
 254
 255 #define GTK_IMHTML_DND_TARGETS  \
 256         { "text/uri-list", 0, GTK_IMHTML_DRAG_URL }, \
 257         { "_NETSCAPE_URL", 0, GTK_IMHTML_DRAG_URL }, \
 258         { "text/html", 0, GTK_IMHTML_DRAG_HTML }, \
 259         { "x-url/ftp", 0, GTK_IMHTML_DRAG_URL }, \
 260         { "x-url/http", 0, GTK_IMHTML_DRAG_URL }, \
 261         { "UTF8_STRING", 0, GTK_IMHTML_DRAG_UTF8_STRING }, \
 262         { "COMPOUND_TEXT", 0, GTK_IMHTML_DRAG_COMPOUND_TEXT }, \
 263         { "STRING", 0, GTK_IMHTML_DRAG_STRING }, \
 264         { "text/plain", 0, GTK_IMHTML_DRAG_TEXT }, \
 265         { "TEXT", 0, GTK_IMHTML_DRAG_TEXT }
 266
 267 typedef gpointer    (*GtkIMHtmlGetImageFunc)        (int id);
 268 typedef gpointer    (*GtkIMHtmlGetImageDataFunc)    (gpointer i);
 269 typedef size_t      (*GtkIMHtmlGetImageSizeFunc)    (gpointer i);
 270 typedef const char *(*GtkIMHtmlGetImageFilenameFunc)(gpointer i);
 271 typedef void        (*GtkIMHtmlImageRefFunc)        (int id);
 272 typedef void        (*GtkIMHtmlImageUnrefFunc)      (int id);
 273
 274 struct _GtkIMHtmlFuncs {
 275         GtkIMHtmlGetImageFunc image_get;
 276         GtkIMHtmlGetImageDataFunc image_get_data;
 277         GtkIMHtmlGetImageSizeFunc image_get_size;
 278         GtkIMHtmlGetImageFilenameFunc image_get_filename;
 279         GtkIMHtmlImageRefFunc image_ref;
 280         GtkIMHtmlImageUnrefFunc image_unref;
 281 };
 282
 283 /*@}*/
 284
 285 /**************************************************************************
 286  * @name GTK+ IM/HTML rendering component API
 287  **************************************************************************/
 288 /*@{*/
 289
 290 /**
 291  * Returns the GType object for an IM/HTML widget.
 292  *
 293  * @return The GType for an IM/HTML widget.
 294  */
 295 GType gtk_imhtml_get_type(void);
 296
 297 /**
 298  * Creates and returns a new GTK+ IM/HTML widget.
 299  *
 300  * @return The GTK+ IM/HTML widget created.
 301  */
 302 GtkWidget *gtk_imhtml_new(void *, void *);
 303
 304 /**
 305  * Returns the smiley object associated with the text.
 306  *
 307  * @param imhtml The GTK+ IM/HTML.
 308  * @param sml    The name of the smiley category.
 309  * @param text   The text associated with the smiley.
 310  */
 311
 312 GtkIMHtmlSmiley *gtk_imhtml_smiley_get(GtkIMHtml * imhtml,
 313                                         const gchar * sml, const gchar * text);
 314
 315
 316 /**
 317  * Associates a smiley with a GTK+ IM/HTML.
 318  *
 319  * @param imhtml The GTK+ IM/HTML.
 320  * @param sml    The name of the smiley category.
 321  * @param smiley The GtkIMSmiley to associate.
 322  */
 323 void gtk_imhtml_associate_smiley(GtkIMHtml *imhtml, const gchar *sml, GtkIMHtmlSmiley *smiley);
 324
 325 /**
 326  * Removes all smileys associated with a GTK+ IM/HTML.
 327  *
 328  * @param imhtml The GTK+ IM/HTML.
 329  */
 330 void gtk_imhtml_remove_smileys(GtkIMHtml *imhtml);
 331
 332 /**
 333  * Sets the function callbacks to use with a GTK+ IM/HTML instance.
 334  *
 335  * @param imhtml The GTK+ IM/HTML.
 336  * @param f      The GtkIMHTMLFuncs struct containing the functions to use.
 337  */
 338 void gtk_imhtml_set_funcs(GtkIMHtml *imhtml, GtkIMHtmlFuncs *f);
 339
 340 /**
 341  * Enables or disables showing the contents of HTML comments in a GTK+ IM/HTML.
 342  *
 343  * @param imhtml The GTK+ IM/HTML.
 344  * @param show   @c TRUE if comments should be shown, or @c FALSE otherwise.
 345  */
 346 void gtk_imhtml_show_comments(GtkIMHtml *imhtml, gboolean show);
 347
 348 /**
 349  * Gets the protocol name associated with this GTK+ IM/HTML.
 350  *
 351  * @param imhtml The GTK+ IM/HTML
 352  */
 353 const char *gtk_imhtml_get_protocol_name(GtkIMHtml *imhtml);
 354
 355 /**
 356  * Associates a protocol name with a GTK+ IM/HTML.
 357  *
 358  * @param imhtml        The GTK+ IM/HTML.
 359  * @param protocol_name The protocol name to associate with the IM/HTML.
 360  */
 361 void gtk_imhtml_set_protocol_name(GtkIMHtml *imhtml, const gchar *protocol_name);
 362
 363 /**
 364  * Appends HTML formatted text to a GTK+ IM/HTML.
 365  *
 366  * @param imhtml  The GTK+ IM/HTML.
 367  * @param text    The formatted text to append.
 368  * @param options A GtkIMHtmlOptions object indicating insert behavior.
 369  */
 370 #define gtk_imhtml_append_text(imhtml, text, options) \
 371  gtk_imhtml_append_text_with_images(imhtml, text, options, NULL)
 372
 373 /**
 374  * Appends HTML formatted text to a GTK+ IM/HTML.
 375  *
 376  * @param imhtml  The GTK+ IM/HTML.
 377  * @param text    The formatted text to append.
 378  * @param options A GtkIMHtmlOptions object indicating insert behavior.
 379  * @param unused  Use @c NULL value.
 380  */
 381 void gtk_imhtml_append_text_with_images(GtkIMHtml *imhtml,
 382                                          const gchar *text,
 383                                          GtkIMHtmlOptions options,
 384                                          GSList *unused);
 385
 386 /**
 387  * Inserts HTML formatted text to a GTK+ IM/HTML at a given iter.
 388  *
 389  * @param imhtml  The GTK+ IM/HTML.
 390  * @param text    The formatted text to append.
 391  * @param options A GtkIMHtmlOptions object indicating insert behavior.
 392  * @param iter    A GtkTextIter in the GTK+ IM/HTML at which to insert text.
 393  */
 394 void gtk_imhtml_insert_html_at_iter(GtkIMHtml        *imhtml,
 395                                     const gchar      *text,
 396                                     GtkIMHtmlOptions  options,
 397                                     GtkTextIter      *iter);
 398
 399 /**
 400  * Scrolls a GTK+ IM/HTML to the end of its contents.
 401  *
 402  * @param imhtml  The GTK+ IM/HTML.
 403  * @param smooth  A boolean indicating if smooth scrolling should be used.
 404  */
 405 void gtk_imhtml_scroll_to_end(GtkIMHtml *imhtml, gboolean smooth);
 406
 407 /**
 408  * Delete the contents of a GTK+ IM/HTML between start and end.
 409  *
 410  * @param imhtml  The GTK+ IM/HTML.
 411  * @param start   a postition in the imhtml's buffer
 412  * @param end     another postition in the imhtml's buffer
 413  */
 414 void gtk_imhtml_delete(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *end);
 415
 416 /**
 417  * Purges the contents from a GTK+ IM/HTML and resets formatting.
 418  *
 419  * @param imhtml  The GTK+ IM/HTML.
 420  */
 421 #define gtk_imhtml_clear(imhtml) \
 422  gtk_imhtml_delete(imhtml, NULL, NULL)
 423
 424 /**
 425  * Scrolls a GTK+ IM/HTML up by one page.
 426  *
 427  * @param imhtml  The GTK+ IM/HTML.
 428  */
 429 void gtk_imhtml_page_up(GtkIMHtml *imhtml);
 430
 431 /**
 432  * Scrolls a GTK+ IM/HTML down by one page.
 433  *
 434  * @param imhtml  The GTK+ IM/HTML.
 435  */
 436 void gtk_imhtml_page_down(GtkIMHtml *imhtml);
 437
 438 /**
 439  * Creates and returns an new GTK+ IM/HTML scalable object.
 440  *
 441  * @return A new IM/HTML Scalable object.
 442  */
 443 GtkIMHtmlScalable *gtk_imhtml_scalable_new(void);
 444
 445 /**
 446  * Creates and returns a new GTK+ IM/HTML scalable object with an image.
 447  *
 448  * @param img      A GdkPixbuf of the image to add.
 449  * @param filename The filename to associate with the image.
 450  * @param id       The id to associate with the image.
 451  *
 452  * @return A new IM/HTML Scalable object with an image.
 453  */
 454 GtkIMHtmlScalable *gtk_imhtml_image_new(GdkPixbuf *img, const gchar *filename, int id);
 455
 456 /**
 457  * Creates and returns a new GTK+ IM/HTML scalable object with an
 458  * animated image.
 459  *
 460  * @param img      A GdkPixbufAnimation of the image to add.
 461  * @param filename The filename to associate with the image.
 462  * @param id       The id to associate with the image.
 463  *
 464  * @return A new IM/HTML Scalable object with an image.
 465  *
 466  * @since 2.1.0
 467  */
 468 /*
 469  * TODO: All this animation code could be combined much better with
 470  *       the image code.  It couldn't be done when it was written
 471  *       because it requires breaking backward compatibility.  It
 472  *       would be good to do it for 3.0.0.
 473  */
 474 GtkIMHtmlScalable *gtk_imhtml_animation_new(GdkPixbufAnimation *img, const gchar *filename, int id);
 475
 476 /**
 477  * Destroys and frees a GTK+ IM/HTML scalable image.
 478  *
 479  * @param scale The GTK+ IM/HTML scalable.
 480  */
 481 /* TODO: Is there any reason this isn't private? */
 482 void gtk_imhtml_image_free(GtkIMHtmlScalable *scale);
 483
 484 /**
 485  * Destroys and frees a GTK+ IM/HTML scalable animation.
 486  *
 487  * @param scale The GTK+ IM/HTML scalable.
 488  */
 489 /* TODO: Is there any reason this isn't private? */
 490 void gtk_imhtml_animation_free(GtkIMHtmlScalable *scale);
 491
 492 /**
 493  * Rescales a GTK+ IM/HTML scalable image to a given size.
 494  *
 495  * @param scale  The GTK+ IM/HTML scalable.
 496  * @param width  The new width.
 497  * @param height The new height.
 498  */
 499 /* TODO: Is there any reason this isn't private? */
 500 void gtk_imhtml_image_scale(GtkIMHtmlScalable *scale, int width, int height);
 501
 502 /**
 503  * Adds a GTK+ IM/HTML scalable image to a given GTK+ IM/HTML at a given iter.
 504  *
 505  * @param scale  The GTK+ IM/HTML scalable.
 506  * @param imhtml The GTK+ IM/HTML.
 507  * @param iter   The GtkTextIter at which to add the scalable.
 508  */
 509 /* TODO: Is there any reason this isn't private? */
 510 void gtk_imhtml_image_add_to(GtkIMHtmlScalable *scale, GtkIMHtml *imhtml, GtkTextIter *iter);
 511
 512 /**
 513  * Creates and returns an new GTK+ IM/HTML scalable with a horizontal rule.
 514  *
 515  * @return A new IM/HTML Scalable object with an image.
 516  */
 517 GtkIMHtmlScalable *gtk_imhtml_hr_new(void);
 518
 519 /**
 520  * Destroys and frees a GTK+ IM/HTML scalable horizontal rule.
 521  *
 522  * @param scale The GTK+ IM/HTML scalable.
 523  */
 524 void gtk_imhtml_hr_free(GtkIMHtmlScalable *scale);
 525
 526 /**
 527  * Rescales a GTK+ IM/HTML scalable horizontal rule to a given size.
 528  *
 529  * @param scale  The GTK+ IM/HTML scalable.
 530  * @param width  The new width.
 531  * @param height The new height.
 532  */
 533 void gtk_imhtml_hr_scale(GtkIMHtmlScalable *scale, int width, int height);
 534
 535 /**
 536  * Adds a GTK+ IM/HTML scalable horizontal rule to a given GTK+ IM/HTML at
 537  * a given iter.
 538  *
 539  * @param scale  The GTK+ IM/HTML scalable.
 540  * @param imhtml The GTK+ IM/HTML.
 541  * @param iter   The GtkTextIter at which to add the scalable.
 542  */
 543 void gtk_imhtml_hr_add_to(GtkIMHtmlScalable *scale, GtkIMHtml *imhtml, GtkTextIter *iter);
 544
 545 /**
 546  * Finds and highlights a given string in a GTK+ IM/HTML.
 547  *
 548  * @param imhtml The GTK+ IM/HTML.
 549  * @param text   The string to search for.
 550  *
 551  * @return @c TRUE if a search was performed, or @c FALSE if not.
 552  */
 553 gboolean gtk_imhtml_search_find(GtkIMHtml *imhtml, const gchar *text);
 554
 555 /**
 556  * Clears the highlighting from a prior search in a GTK+ IM/HTML.
 557  *
 558  * @param imhtml The GTK+ IM/HTML.
 559  */
 560 void gtk_imhtml_search_clear(GtkIMHtml *imhtml);
 561
 562 /**
 563  * Enables or disables editing in a GTK+ IM/HTML.
 564  *
 565  * @param imhtml   The GTK+ IM/HTML.
 566  * @param editable @c TRUE to make the widget editable, or @c FALSE otherwise.
 567  */
 568 void gtk_imhtml_set_editable(GtkIMHtml *imhtml, gboolean editable);
 569
 570 /**
 571  * Enables or disables whole buffer formatting only (wbfo) in a GTK+ IM/HTML.
 572  * In this mode formatting options to the buffer take effect for the entire
 573  * buffer instead of specific text.
 574  *
 575  * @param imhtml The GTK+ IM/HTML.
 576  * @param wbfo   @c TRUE to enable the mode, or @c FALSE otherwise.
 577  */
 578 void gtk_imhtml_set_whole_buffer_formatting_only(GtkIMHtml *imhtml, gboolean wbfo);
 579
 580 /**
 581  * Indicates which formatting functions to enable and disable in a GTK+ IM/HTML.
 582  *
 583  * @param imhtml  The GTK+ IM/HTML.
 584  * @param buttons A GtkIMHtmlButtons bitmask indicating which functions to use.
 585  */
 586 void gtk_imhtml_set_format_functions(GtkIMHtml *imhtml, GtkIMHtmlButtons buttons);
 587
 588 /**
 589  * Returns which formatting functions are enabled in a GTK+ IM/HTML.
 590  *
 591  * @param imhtml The GTK+ IM/HTML.
 592  *
 593  * @return A GtkIMHtmlButtons bitmask indicating which functions to are enabled.
 594  */
 595 GtkIMHtmlButtons gtk_imhtml_get_format_functions(GtkIMHtml *imhtml);
 596
 597 /**
 598  * Sets each boolean to @c TRUE or @c FALSE to indicate if that formatting option
 599  * is enabled at the current position in a GTK+ IM/HTML.
 600  *
 601  * @param imhtml    The GTK+ IM/HTML.
 602  * @param bold      The boolean to set for bold or @c NULL.
 603  * @param italic    The boolean to set for italic or @c NULL.
 604  * @param underline The boolean to set for underline or @c NULL.
 605  */
 606 void gtk_imhtml_get_current_format(GtkIMHtml *imhtml, gboolean *bold, gboolean *italic, gboolean *underline);
 607
 608 /**
 609  * Returns a string containing the selected font face at the current position
 610  * in a GTK+ IM/HTML.
 611  *
 612  * @param imhtml The GTK+ IM/HTML.
 613  *
 614  * @return A string containg the font face or @c NULL if none is set.
 615  */
 616 char *gtk_imhtml_get_current_fontface(GtkIMHtml *imhtml);
 617
 618 /**
 619  * Returns a string containing the selected foreground color at the current
 620  * position in a GTK+ IM/HTML.
 621  *
 622  * @param imhtml The GTK+ IM/HTML.
 623  *
 624  * @return A string containg the foreground color or @c NULL if none is set.
 625  */
 626 char *gtk_imhtml_get_current_forecolor(GtkIMHtml *imhtml);
 627
 628 /**
 629  * Returns a string containing the selected font background color at the current
 630  * position in a GTK+ IM/HTML.
 631  *
 632  * @param imhtml The GTK+ IM/HTML.
 633  *
 634  * @return A string containg the font background color or @c NULL if none is set.
 635  */
 636 char *gtk_imhtml_get_current_backcolor(GtkIMHtml *imhtml);
 637
 638 /**
 639  * Returns a string containing the selected background color at the current
 640  * position in a GTK+ IM/HTML.
 641  *
 642  * @param imhtml The GTK+ IM/HTML.
 643  *
 644  * @return A string containg the background color or @c NULL if none is set.
 645  */
 646 char *gtk_imhtml_get_current_background(GtkIMHtml *imhtml);
 647
 648 /**
 649  * Returns a integer containing the selected HTML font size at the current
 650  * position in a GTK+ IM/HTML.
 651  *
 652  * @param imhtml The GTK+ IM/HTML.
 653  *
 654  * @return The HTML font size.
 655  */
 656 gint gtk_imhtml_get_current_fontsize(GtkIMHtml *imhtml);
 657
 658 /**
 659  * Checks whether a GTK+ IM/HTML is marked as editable.
 660  *
 661  * @param imhtml The GTK+ IM/HTML.
 662  *
 663  * @return @c TRUE if the IM/HTML is editable, or @c FALSE otherwise.
 664  */
 665 gboolean gtk_imhtml_get_editable(GtkIMHtml *imhtml);
 666
 667 /**
 668  * Clear all the formatting on a GTK+ IM/HTML.
 669  *
 670  * @param imhtml The GTK+ IM/HTML.
 671  */
 672 void gtk_imhtml_clear_formatting(GtkIMHtml *imhtml);
 673
 674 /**
 675  * Toggles bold at the cursor location or selection in a GTK+ IM/HTML.
 676  *
 677  * @param imhtml The GTK+ IM/HTML.
 678  */
 679 void gtk_imhtml_toggle_bold(GtkIMHtml *imhtml);
 680
 681 /**
 682  * Toggles italic at the cursor location or selection in a GTK+ IM/HTML.
 683  *
 684  * @param imhtml The GTK+ IM/HTML.
 685  */
 686 void gtk_imhtml_toggle_italic(GtkIMHtml *imhtml);
 687
 688 /**
 689  * Toggles underline at the cursor location or selection in a GTK+ IM/HTML.
 690  *
 691  * @param imhtml The GTK+ IM/HTML.
 692  */
 693 void gtk_imhtml_toggle_underline(GtkIMHtml *imhtml);
 694
 695 /**
 696  * Toggles strikethrough at the cursor location or selection in a GTK+ IM/HTML.
 697  *
 698  * @param imhtml The GTK+ IM/HTML.
 699  */
 700 void gtk_imhtml_toggle_strike(GtkIMHtml *imhtml);
 701
 702 /**
 703  * Toggles a foreground color at the current location or selection in a GTK
 704  * IM/HTML.
 705  *
 706  * @param imhtml The GTK+ IM/HTML.
 707  * @param color  The HTML-style color, or @c NULL or "" to clear the color.
 708  *
 709  * @return @c TRUE if a color was set, or @c FALSE if it was cleared.
 710  */
 711 gboolean gtk_imhtml_toggle_forecolor(GtkIMHtml *imhtml, const char *color);
 712
 713 /**
 714  * Toggles a background color at the current location or selection in a GTK
 715  * IM/HTML.
 716  *
 717  * @param imhtml The GTK+ IM/HTML.
 718  * @param color  The HTML-style color, or @c NULL or "" to clear the color.
 719  *
 720  * @return @c TRUE if a color was set, or @c FALSE if it was cleared.
 721  */
 722 gboolean gtk_imhtml_toggle_backcolor(GtkIMHtml *imhtml, const char *color);
 723
 724 /**
 725  * Toggles a background color at the current location or selection in a GTK
 726  * IM/HTML.
 727  *
 728  * @param imhtml The GTK+ IM/HTML.
 729  * @param color  The HTML-style color, or @c NULL or "" to clear the color.
 730  *
 731  * @return @c TRUE if a color was set, or @c FALSE if it was cleared.
 732  */
 733 gboolean gtk_imhtml_toggle_background(GtkIMHtml *imhtml, const char *color);
 734
 735 /**
 736  * Toggles a font face at the current location or selection in a GTK+ IM/HTML.
 737  *
 738  * @param imhtml The GTK+ IM/HTML.
 739  * @param face   The font face name, or @c NULL or "" to clear the font.
 740  *
 741  * @return @c TRUE if a font name was set, or @c FALSE if it was cleared.
 742  */
 743 gboolean gtk_imhtml_toggle_fontface(GtkIMHtml *imhtml, const char *face);
 744
 745 /**
 746  * Toggles a link tag with the given URL at the current location or selection
 747  * in a GTK+ IM/HTML.
 748  *
 749  * @param imhtml The GTK+ IM/HTML.
 750  * @param url    The URL for the link or @c NULL to terminate the link.
 751  */
 752 void gtk_imhtml_toggle_link(GtkIMHtml *imhtml, const char *url);
 753
 754 /**
 755  * Inserts a link to the given url at the given GtkTextMark in a GTK+ IM/HTML.
 756  *
 757  * @param imhtml The GTK+ IM/HTML.
 758  * @param mark   The GtkTextMark to insert the link at.
 759  * @param url    The URL for the link.
 760  * @param text   The string to use for the link description.
 761  */
 762 void gtk_imhtml_insert_link(GtkIMHtml *imhtml, GtkTextMark *mark, const char *url, const char *text);
 763
 764 /**
 765  * Inserts a smiley at the current location or selection in a GTK+ IM/HTML.
 766  *
 767  * @param imhtml The GTK+ IM/HTML.
 768  * @param sml    The category of the smiley.
 769  * @param smiley The text of the smiley to insert.
 770  */
 771 void gtk_imhtml_insert_smiley(GtkIMHtml *imhtml, const char *sml, char *smiley);
 772 /**
 773  * Inserts a smiley at the given iter in a GTK+ IM/HTML.
 774  *
 775  * @param imhtml The GTK+ IM/HTML.
 776  * @param sml    The category of the smiley.
 777  * @param smiley The text of the smiley to insert.
 778  * @param iter   The GtkTextIter in the IM/HTML to insert the smiley at.
 779  */
 780 void gtk_imhtml_insert_smiley_at_iter(GtkIMHtml *imhtml, const char *sml, char *smiley, GtkTextIter *iter);
 781
 782 /**
 783  * Inserts the IM/HTML scalable image with the given id at the given iter in a
 784  * GTK+ IM/HTML.
 785  *
 786  * @param imhtml The GTK+ IM/HTML.
 787  * @param id     The id of the IM/HTML scalable.
 788  * @param iter   The GtkTextIter in the IM/HTML to insert the image at.
 789  */
 790 void gtk_imhtml_insert_image_at_iter(GtkIMHtml *imhtml, int id, GtkTextIter *iter);
 791
 792 /**
 793  * Sets the font size at the current location or selection in a GTK+ IM/HTML.
 794  *
 795  * @param imhtml The GTK+ IM/HTML.
 796  * @param size   The HTML font size to use.
 797  */
 798 void gtk_imhtml_font_set_size(GtkIMHtml *imhtml, gint size);
 799
 800 /**
 801  * Decreases the font size by 1 at the current location or selection in a GTK
 802  * IM/HTML.
 803  *
 804  * @param imhtml The GTK+ IM/HTML.
 805  */
 806 void gtk_imhtml_font_shrink(GtkIMHtml *imhtml);
 807
 808 /**
 809  * Increases the font size by 1 at the current location or selection in a GTK
 810  * IM/HTML.
 811  *
 812  * @param imhtml The GTK+ IM/HTML.
 813  */
 814 void gtk_imhtml_font_grow(GtkIMHtml *imhtml);
 815
 816 /**
 817  * Returns the HTML formatted contents between two iters in a GTK+ IM/HTML.
 818  *
 819  * @param imhtml The GTK+ IM/HTML.
 820  * @param start  The GtkTextIter indicating the start point in the IM/HTML.
 821  * @param end    The GtkTextIter indicating the end point in the IM/HTML.
 822  *
 823  * @return A string containing the HTML formatted text.
 824  */
 825 char *gtk_imhtml_get_markup_range(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *end);
 826
 827 /**
 828  * Returns the entire HTML formatted contents of a GTK+ IM/HTML.
 829  *
 830  * @param imhtml The GTK+ IM/HTML.
 831  *
 832  * @return A string containing the HTML formatted text.
 833  */
 834 char *gtk_imhtml_get_markup(GtkIMHtml *imhtml);
 835
 836 /**
 837  * Returns a null terminated array of pointers to null terminated strings, each
 838  * string for each line.  g_strfreev() should be called to free it when done.
 839  *
 840  * @param imhtml The GTK+ IM/HTML.
 841  *
 842  * @return A null terminated array of null terminated HTML formatted strings.
 843  */
 844 char **gtk_imhtml_get_markup_lines(GtkIMHtml *imhtml);
 845
 846 /**
 847  * Returns the entire unformatted (plain text) contents of a GTK+ IM/HTML
 848  * between two iters in a GTK+ IM/HTML.
 849  *
 850  * @param imhtml The GTK+ IM/HTML.
 851  * @param start  The GtkTextIter indicating the start point in the IM/HTML.
 852  * @param stop   The GtkTextIter indicating the end point in the IM/HTML.
 853  *
 854  * @return A string containing the unformatted text.
 855  */
 856 char *gtk_imhtml_get_text(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *stop);
 857
 858 /**
 859  * Setup formatting for an imhtml depending on the flags specified.
 860  *
 861  * @param imhtml  The GTK+ IM/HTML.
 862  * @param flags   The connection flag which describes the allowed types of formatting.
 863  *
 864  * @since 2.1.0
 865  */
 866 void gtk_imhtml_setup_entry(GtkIMHtml *imhtml, PurpleConnectionFlags flags);
 867
 868 /**
 869  * Create a new GtkIMHtmlSmiley.
 870  *
 871  * @param file       The image file for the smiley
 872  * @param shortcut   The key shortcut for the smiley
 873  * @param hide       @c TRUE if the smiley should be hidden in the smiley dialog, @c FALSE otherwise
 874  * @param flags      The smiley flags
 875  *
 876  * @return The newly created smiley
 877  * @since 2.5.0
 878  */
 879 GtkIMHtmlSmiley *gtk_imhtml_smiley_create(const char *file, const char *shortcut, gboolean hide,
 880                 GtkIMHtmlSmileyFlags flags);
 881
 882 /**
 883  * Reload the image data for the smiley.
 884  *
 885  * @param smiley   The smiley to reload
 886  *
 887  * @since 2.5.0
 888  */
 889 void gtk_imhtml_smiley_reload(GtkIMHtmlSmiley *smiley);
 890
 891 /**
 892  * Destroy a GtkIMHtmlSmiley.
 893  *
 894  * @param smiley   The smiley to destroy
 895  *
 896  * @since 2.5.0
 897  */
 898 void gtk_imhtml_smiley_destroy(GtkIMHtmlSmiley *smiley);
 899
 900 /**
 901  * Register a protocol with the GtkIMHtml widget. Registering a protocol would
 902  * allow certain text to be clickable.
 903  *
 904  * @param name      The name of the protocol (e.g. http://)
 905  * @param activate  The callback to trigger when the protocol text is clicked.
 906  *                  Removes any current protocol definition if @c NULL. The
 907  *                  callback should return @c TRUE if the link was activated
 908  *                  properly, @c FALSE otherwise.
 909  * @param context_menu  The callback to trigger when the context menu is popped
 910  *                      up on the protocol text. The callback should return
 911  *                      @c TRUE if the request for context menu was processed
 912  *                      successfully, @c FALSE otherwise.
 913  *
 914  * @return  @c TRUE if the protocol was successfully registered (or unregistered, when \a activate is @c NULL)
 915  *
 916  * @since 2.6.0
 917  */
 918 gboolean gtk_imhtml_class_register_protocol(const char *name,
 919                 gboolean (*activate)(GtkIMHtml *imhtml, GtkIMHtmlLink *link),
 920                 gboolean (*context_menu)(GtkIMHtml *imhtml, GtkIMHtmlLink *link, GtkWidget *menu));
 921
 922 /**
 923  * Get the URL associated with a link. This should be used by the IMHtml protocol-callbacks.
 924  *
 925  * @param link   The GtkIMHtmlLink object sent to the callback functions
 926  *
 927  * @return  The URL
 928  *
 929  * @since 2.6.0
 930  */
 931 const char *gtk_imhtml_link_get_url(GtkIMHtmlLink *link);
 932
 933 /**
 934  * Get the GtkTextTag object (if any) associated with a particular link.
 935  *
 936  * @param link   The GtkIMHtmlLink object sent to the callback functions
 937  *
 938  * @return  The GtkTextTag object, or @c NULL
 939  *
 940  * @since 2.6.0
 941  */
 942 const GtkTextTag *gtk_imhtml_link_get_text_tag(GtkIMHtmlLink *link);
 943
 944 /**
 945  * Activates a GtkIMHtmlLink object. This triggers the 'url-clicked' signal, marks the
 946  * link as visited (when possible).
 947  *
 948  * @param link   The GtkIMHtmlLink object sent to the callback functions
 949  *
 950  * @return  @c TRUE if 'url-clicked' signal was emitted, @c FALSE otherwise.
 951  *
 952  * @since 2.6.0
 953  */
 954 gboolean gtk_imhtml_link_activate(GtkIMHtmlLink *link);
 955
 956 /**
 957  * By default this widget intercepts presses of the "return" key and
 958  * emits the "message_send" signal instead.  If you don't want this
 959  * behavior, and you want the standard GtkTextView behavior of
 960  * inserting a newline into the buffer, then call this function.
 961  *
 962  * @param imhtml The GtkIMHtml where you want the "return" key to add
 963  *        newline and not emit the "message_send" signal.
 964  */
 965 void gtk_imhtml_set_return_inserts_newline(GtkIMHtml *imhtml);
 966
 967 /**
 968  * By default this widget populates the PRIMARY clipboard with any selected
 969  * text (as you would expect).  For scenarios (e.g. select-on-focus) where this
 970  * would be problematic, this function can disable the PRIMARY population.
 971  *
 972  * @param imhtml The GtkIMHtml to enable/disable populating PRIMARY
 973  * @param populate enable/disable PRIMARY population
 974  */
 975 void gtk_imhtml_set_populate_primary_clipboard(GtkIMHtml *imhtml, gboolean populate);
 976
 977 /*@}*/
 978
 979 #ifdef __cplusplus
 980 }
 981 #endif
 982
 983 #endif /* _PIDGINIMHTML_H_ */