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_ */ 984