libs/gtkmm2/gtk/gtkmm/textbuffer.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_TEXTBUFFER_H
   4 #define _GTKMM_TEXTBUFFER_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright(C) 1998-2002 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or(at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27
  28 #include <gtkmm/object.h>
  29 #include <gtkmm/texttagtable.h>
  30 #include <gtkmm/textchildanchor.h>
  31 #include <gtkmm/textmark.h>
  32 #include <gtkmm/textiter.h>
  33 #include <gtkmm/clipboard.h>
  34 #include <gdkmm/pixbuf.h>
  35 #include <gtkmmconfig.h>
  36 #include <utility>
  37
  38 GLIBMM_USING_STD(pair)
  39
  40
  41 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  42 typedef struct _GtkTextBuffer GtkTextBuffer;
  43 typedef struct _GtkTextBufferClass GtkTextBufferClass;
  44 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  45
  46
  47 namespace Gtk
  48 { class TextBuffer_Class; } // namespace Gtk
  49 namespace Gtk
  50 {
  51
  52 class TextMark;
  53 class TextIter;
  54
  55 /** Multi-line attributed text that can be displayed by one or more Gtk::TextView widgets.
  56  *
  57  * Text in a buffer can be marked with tags. A @link Gtk::TextTag Gtk::TextBuffer::Tag@endlink is an attribute that can be applied to some range of text. For example, a tag
  58  * might be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that; tags don't
  59  * have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user
  60  * can't edit it, or countless other things. A tag is represented by a @link Gtk::TextTag Gtk::TextBuffer::Tag@endlink object.
  61  * One @link Gtk::TextTag Gtk::TextBuffer::Tag@endlink can be applied to any number of text ranges in any number of @link Gtk::TextBuffer Gtk::TextBuffers@endlink.
  62  *
  63  * Each tag is stored in a @link Gtk::TextTagTable Gtk::TextBuffer::TagTable@endlink. A tag table defines a set of tags that can be used together. Each buffer has one tag
  64  * table associated with it; only tags from that tag table can be used with the buffer. A single tag table can be shared between
  65  * multiple buffers, however.
  66  *
  67  * Most text manipulation is accomplished with iterators, represented by an @link Gtk::TextIter iterator@endlink. The iterator can
  68  * be used to navigate over characters, words, lines, and sentences.
  69  *
  70  * But iterators can't be used to preserve positions across buffer modifications. To preserve a position, the
  71  * @link Gtk::TextMark Gtk::TextBuffer::Mark@endlink object is ideal. There are two marks built-in to GtkTextBuffer; these are
  72  * named "insert" and "selection_bound" and refer to the insertion point and the boundary of the selection which is not the
  73  * insertion point. If no text is selected, these two marks will be in the same position. You can manipulate what is selected and
  74  * where the cursor appears by moving these marks around.
  75  *
  76  * Text buffers always contain at least one line, but may be empty (that is, buffers can contain zero characters). The last line
  77  * in the text buffer never ends in a line separator (such as newline); the other lines in the buffer always end in a line
  78  * separator. Line separators count as characters when computing character counts and character offsets. Note that some Unicode
  79  * line separators are represented with multiple bytes in UTF-8, and the two-character sequence "\r\n" is also considered a line
  80  * separator.
  81  *
  82  * @ingroup TextView
  83  */
  84
  85 class TextBuffer : public Glib::Object
  86 {
  87
  88 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  89
  90 public:
  91   typedef TextBuffer CppObjectType;
  92   typedef TextBuffer_Class CppClassType;
  93   typedef GtkTextBuffer BaseObjectType;
  94   typedef GtkTextBufferClass BaseClassType;
  95
  96 private:  friend class TextBuffer_Class;
  97   static CppClassType textbuffer_class_;
  98
  99 private:
 100   // noncopyable
 101   TextBuffer(const TextBuffer&);
 102   TextBuffer& operator=(const TextBuffer&);
 103
 104 protected:
 105   explicit TextBuffer(const Glib::ConstructParams& construct_params);
 106   explicit TextBuffer(GtkTextBuffer* castitem);
 107
 108 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 109
 110 public:
 111   virtual ~TextBuffer();
 112
 113 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 114   static GType get_type()      G_GNUC_CONST;
 115   static GType get_base_type() G_GNUC_CONST;
 116 #endif
 117
 118   ///Provides access to the underlying C GObject.
 119   GtkTextBuffer*       gobj()       { return reinterpret_cast<GtkTextBuffer*>(gobject_); }
 120
 121   ///Provides access to the underlying C GObject.
 122   const GtkTextBuffer* gobj() const { return reinterpret_cast<GtkTextBuffer*>(gobject_); }
 123
 124   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 125   GtkTextBuffer* gobj_copy();
 126
 127 private:
 128
 129
 130 public:
 131   typedef TextIter iterator;
 132   typedef TextTag Tag;
 133   typedef TextTagTable TagTable;
 134   typedef TextMark Mark;
 135   typedef TextChildAnchor ChildAnchor;
 136
 137 protected:
 138   TextBuffer();
 139   explicit TextBuffer(const Glib::RefPtr<TagTable>& tag_table);
 140
 141 public:
 142
 143   static Glib::RefPtr<TextBuffer> create();
 144
 145
 146   static Glib::RefPtr<TextBuffer> create(const Glib::RefPtr<TagTable>& tag_table);
 147
 148
 149   /** Obtains the number of lines in the buffer. This value is cached, so
 150    * the function is very fast.
 151    * @return Number of lines in the buffer.
 152    */
 153   int get_line_count() const;
 154
 155   /** Gets the number of characters in the buffer; note that characters
 156    * and bytes are not the same, you can't e.g.\ expect the contents of
 157    * the buffer in string form to be this many bytes long. The character
 158    * count is cached, so this function is very fast.
 159    * @return Number of characters in the buffer.
 160    */
 161   int get_char_count() const;
 162
 163   /// See get_char_count().
 164   int size() const;
 165
 166
 167   /** Get the Gtk::TextTagTable associated with this buffer.
 168    * @return The buffer's tag table.
 169    */
 170   Glib::RefPtr<TextBuffer::TagTable> get_tag_table();
 171
 172   /** Get the Gtk::TextTagTable associated with this buffer.
 173    * @return The buffer's tag table.
 174    */
 175   Glib::RefPtr<const TextBuffer::TagTable> get_tag_table() const;
 176
 177   /** Removes the current contents of the buffer, and inserts @a text instead.
 178    * @param text The text to put in the buffer.
 179    */
 180   void set_text(const Glib::ustring& text);
 181
 182   /** Removes the current contents of the buffer, and inserts @a text instead.
 183    * @param text_begin The start of a UTF8 character array.
 184    * @param text_end The end of the UTF8 character array.
 185    */
 186   void set_text(const char* text_begin, const char* text_end);
 187
 188
 189   #ifndef GTKMM_DISABLE_DEPRECATED
 190   /** @deprecated Use set_text()
 191    */
 192   void assign(const Glib::ustring& text);
 193
 194   /** @deprecated Use set_text()
 195    */
 196   void assign(const char* text_begin, const char* text_end);
 197   #endif //GTKMM_DISABLE_DEPRECATED
 198
 199   //TODO: Make all insert() methods have the same return type:
 200
 201   /** Inserts @a text at position @a pos.
 202    * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal.
 203    * The @a pos iterator is invalidated when insertion occurs (because the buffer contents change).
 204    *
 205    * @param pos An iterator pointing to the position at which the text should be inserted.
 206    * @param text The text to be inserted in the buffer.
 207    * @result An iterator that points to the end of the inserted text.
 208    */
 209   iterator insert(const iterator& pos, const Glib::ustring& text);
 210
 211   /** Inserts text at position @a pos.
 212    * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal.
 213    * The @a pos iterator is invalidated when insertion occurs (because the buffer contents change).
 214    *
 215    * @param pos An iterator pointing to the position at which the text should be inserted.
 216    * @param text_begin The start of a UTF8 character array.
 217    * @param text_end The end of the UTF8 character array.
 218    * @result An iterator that points to the end of the inserted text.
 219    */
 220   iterator insert(const iterator& pos, const char* text_begin, const char* text_end);
 221
 222   /** Inserts @a text, using the current cursor position as the insertion point.
 223    * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal.
 224    *
 225    * @param text The text to be inserted in the buffer.
 226    * @result An iterator that points to the end of the inserted text.
 227    */
 228   void insert_at_cursor(const Glib::ustring& text);
 229
 230   /** Inserts text, using the current cursor position as the insertion point.
 231    * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal.
 232    *
 233    * @param text_begin The start of a UTF8 character array.
 234    * @param text_end The end of the UTF8 character array.
 235    * @result An iterator that points to the end of the inserted text.
 236    */
 237   void insert_at_cursor(const char* text_begin, const char* text_end);
 238
 239   /** Like insert(), but the insertion will not occur if @a iter is at a non-editable location in the buffer.
 240    * Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive).
 241    *
 242    * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it.
 243    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 244    *
 245    * @param pos An iterator pointing to the position at which the text should be inserted.
 246    * @param text The text to be inserted in the buffer.
 247    * @param default_editable Default editability of buffer
 248    * @result Whether text was actually inserted
 249    */
 250   std::pair<iterator,bool> insert_interactive(
 251       const iterator& pos, const Glib::ustring& text, bool default_editable = true);
 252
 253   /** Like insert(), but the insertion will not occur if @a pos is at a non-editable location in the buffer.
 254    * Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive).
 255    *
 256    * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it.
 257    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 258    *
 259    * @param pos An iterator pointing to the position at which the text should be inserted.
 260    * @param text_begin The start of a UTF8 character array.
 261    * @param text_end The end of the UTF8 character array.
 262    * @param default_editable Default editability of buffer.
 263    * @result Whether text was actually inserted
 264    */
 265   std::pair<iterator,bool> insert_interactive(
 266       const iterator& pos, const char* text_begin, const char* text_end, bool default_editable = true);
 267
 268   /** Calls insert_interactive() at the cursor position.
 269    *
 270    * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it.
 271    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 272    *
 273    * @param text The text to be inserted in the buffer.
 274    * @param default_editable Default editability of buffer
 275    * @result Whether text was actually inserted
 276    */
 277   bool insert_interactive_at_cursor(const Glib::ustring& text, bool default_editable = true);
 278
 279   /** Calls insert_interactive() at the cursor position.
 280    *
 281    * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it.
 282    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 283    *
 284    * @param text_begin The start of a UTF8 character array.
 285    * @param text_end The end of the UTF8 character array.
 286    * @param default_editable Default editability of buffer
 287    * @result Whether text was actually inserted
 288    */
 289   bool insert_interactive_at_cursor(const char* text_begin, const char* text_end,
 290                                     bool default_editable = true);
 291
 292   /** Copies text, tags, and pixbufs between @a range_begin and @a range_end (the order of range_begin and range_begin doesn't
 293    * matter) and inserts the copy at @a pos. Used instead of simply getting/inserting text because it preserves images and tags.
 294    * If range_begin and range_end are in a different buffer, the two buffers must share the same tag table.
 295    *
 296    * Implemented via emissions of the insert_text and apply_tag signals, so expect those.
 297    *
 298    * @param pos An iterator pointing to the position at which the text should be inserted.
 299    * @param range_begin A position in a buffer.
 300    * @param range_end Another position in the same buffer as @a range_begin.
 301    * @result Whether text was actually inserted
 302    */
 303   iterator insert(const iterator& pos, const iterator& range_begin, const iterator& range_end);
 304
 305
 306   /** Same as insert_range(), but does nothing if the insertion point isn't editable.
 307    *
 308    * The @a default_editable parameter indicates whether the text is editable at @a pos if no tags enclosing @a pos affect editability.
 309    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 310    *
 311    * @param pos An iterator pointing to the position at which the text should be inserted.
 312    * @param range_begin A position in a buffer.
 313    * @param range_end Another position in the same buffer as @a range_begin.
 314    * @param default_editable Default editability of buffer.
 315    * @result Whether text was actually inserted
 316    */
 317   std::pair<iterator,bool> insert_interactive(const iterator& pos, const iterator& range_begin, const iterator& range_end, bool default_editable = true);
 318
 319
 320   iterator insert_with_tag(const iterator& pos, const Glib::ustring& text, const Glib::RefPtr<Tag>& tag);
 321   iterator insert_with_tag(const iterator& pos, const char* text_begin, const char* text_end, const Glib::RefPtr<Tag>& tag);
 322
 323   iterator insert_with_tag(const iterator& pos, const Glib::ustring& text, const Glib::ustring& tag_name);
 324   iterator insert_with_tag(const iterator& pos, const char* text_begin, const char* text_end, const Glib::ustring& tag_name);
 325
 326   /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text.
 327    * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function.
 328    *
 329    * @param pos An iterator pointing to the position at which the text should be inserted.
 330    * @param text The text to be inserted in the buffer.
 331    * @param tags A standard C++ container of @link Gtk::TextTag Gtk::TextBuffer::Tags@endlink.
 332    * @result Whether text was actually inserted
 333    */
 334   iterator insert_with_tags(const iterator& pos, const Glib::ustring& text,
 335                             const Glib::ArrayHandle< Glib::RefPtr<Tag> >& tags);
 336
 337   /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text.
 338    * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function.
 339    *
 340    * @param pos An iterator pointing to the position at which the text should be inserted.
 341    * @param text_begin The start of a UTF8 character array.
 342    * @param text_end The end of the UTF8 character array.
 343    * @param tags A standard C++ container of @link Gtk::TextTag Gtk::TextBuffer::Tags@endlink.
 344    * @result Whether text was actually inserted
 345    */
 346   iterator insert_with_tags(const iterator& pos, const char* text_begin, const char* text_end,
 347                             const Glib::ArrayHandle< Glib::RefPtr<Tag> >& tags);
 348
 349   /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text.
 350    * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function.
 351    *
 352    * @param pos An iterator pointing to the position at which the text should be inserted.
 353    * @param text The text to be inserted in the buffer.
 354    * @param tag_names A standard C++ container of tag names.
 355    * @result Whether text was actually inserted
 356    */
 357   iterator insert_with_tags_by_name(const iterator& pos, const Glib::ustring& text,
 358                                     const Glib::StringArrayHandle& tag_names);
 359
 360
 361   /** Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function.
 362    *
 363    * @param pos An iterator pointing to the position at which the text should be inserted.
 364    * @param text_begin The start of a UTF8 character array.
 365    * @param text_end The end of the UTF8 character array.
 366    * @param tag_names A standard C++ container of tag names.
 367    * @result Whether text was actually inserted
 368    */
 369   iterator insert_with_tags_by_name(const iterator& pos, const char* text_begin, const char* text_end,
 370                                     const Glib::StringArrayHandle& tag_names);
 371
 372   /* Deletes all text between @a range_begin and @a range_end. The order of range_begin and range_end is not actually relevant.
 373    * This function actually emits the "delete_range" signal, and the default handler of that signal deletes the text.
 374    * Because the buffer is modified, all outstanding iterators become invalid after calling this function.
 375    * @param range_begin
 376    * @param range_end
 377    * @result An iterator that points to the location where text was deleted.
 378    */
 379   iterator erase(const iterator& range_begin, const iterator& range_end);
 380
 381
 382    /* Deletes all editable text between @a range_begin and @a range_end. The order of range_begin and range_end is not actually relevant.
 383    * This function actually emits the "delete_range" signal, and the default handler of that signal deletes the text.
 384    * Because the buffer is modified, all outstanding iterators become invalid after calling this function.
 385    *
 386    * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it.
 387    * Typically the result of Gtk::TextView::get_editable() is appropriate here.
 388    *
 389    * @param range_begin
 390    * @param range_end
 391    * @param default_editable Default editability of buffer
 392    * @result An iterator that points to the location where text was deleted, or end() is no text was deleted.
 393    */
 394   std::pair<iterator,bool> erase_interactive(const iterator& range_begin, const iterator& range_end, bool default_editable = true);
 395
 396
 397   //TODO: Document this:
 398   iterator backspace(const iterator& iter, bool interactive = true, bool default_editable = true);
 399
 400
 401   /** Returns the text in the range [ @a start , @a end ). Excludes undisplayed
 402    * text (text marked with tags that set the invisibility attribute) if
 403    *  @a include_hidden_chars  is <tt>false</tt>. Does not include characters
 404    * representing embedded images, so byte and character indexes into
 405    * the returned string do <em>not</em> correspond to byte
 406    * and character indexes into the buffer. Contrast with
 407    * get_slice().
 408    * @param start Start of a range.
 409    * @param end End of a range.
 410    * @param include_hidden_chars Whether to include invisible text.
 411    * @return An allocated UTF-8 string.
 412    */
 413   Glib::ustring get_text(const iterator& start, const iterator& end, bool include_hidden_chars = true);
 414
 415   /** Returns all the text in the buffer. Excludes undisplayed
 416    * text (text marked with tags that set the invisibility attribute) if
 417    *  @a include_hidden_chars  is <tt>false</tt>. Does not include characters
 418    * representing embedded images, so byte and character indexes into
 419    * the returned string do <em>not</em> correspond to byte
 420    * and character indexes into the buffer. Contrast with
 421    * get_slice().
 422    *
 423    * @param include_hidden_chars Whether to include invisible text.
 424    * @return An allocated UTF-8 string.
 425    */
 426   Glib::ustring get_text(bool include_hidden_chars = true);
 427
 428
 429   /** Returns the text in the range [ @a start , @a end ). Excludes undisplayed
 430    * text (text marked with tags that set the invisibility attribute) if
 431    *  @a include_hidden_chars  is <tt>false</tt>. The returned string includes a
 432    * 0xFFFC character whenever the buffer contains
 433    * embedded images, so byte and character indexes into
 434    * the returned string <em>do</em> correspond to byte
 435    * and character indexes into the buffer. Contrast with
 436    * get_text(). Note that 0xFFFC can occur in normal
 437    * text as well, so it is not a reliable indicator that a pixbuf or
 438    * widget is in the buffer.
 439    * @param start Start of a range.
 440    * @param end End of a range.
 441    * @param include_hidden_chars Whether to include invisible text.
 442    * @return An allocated UTF-8 string.
 443    */
 444   Glib::ustring get_slice(const iterator& start, const iterator& end, bool include_hidden_chars = true);
 445
 446   iterator insert_pixbuf(const iterator& pos, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
 447
 448
 449   iterator insert_child_anchor(const iterator& pos, const Glib::RefPtr<ChildAnchor>& anchor);
 450
 451
 452   Glib::RefPtr<ChildAnchor> create_child_anchor(const iterator& pos);
 453
 454
 455   /** Creates a mark at position @a where . The mark can be retrieved by name using
 456    * get_mark(). If a mark has left gravity, and text is
 457    * inserted at the mark's current location, the mark will be moved to
 458    * the left of the newly-inserted text. If the mark has right gravity
 459    * ( @a left_gravity  = <tt>false</tt>), the mark will end up on the right of
 460    * newly-inserted text. The standard left-to-right cursor is a mark
 461    * with right gravity (when you type, the cursor stays on the right
 462    * side of the text you're typing).
 463    *
 464    * Emits the "mark_set" signal as notification of the mark's initial
 465    * placement.
 466    * @param mark_name Name for mark, or <tt>0</tt>.
 467    * @param where Location to place mark.
 468    * @param left_gravity Whether the mark has left gravity.
 469    * @return The new Gtk::TextMark object.
 470    */
 471   Glib::RefPtr<TextBuffer::Mark> create_mark(const Glib::ustring& mark_name, const iterator& where, bool left_gravity = true);
 472
 473   /** Create an anonymous mark. */
 474   /** Creates an anonymous mark at position @a where.
 475    *
 476    * If a mark has left gravity, and text is
 477    * inserted at the mark's current location, the mark will be moved to
 478    * the left of the newly-inserted text. If the mark has right gravity
 479    * ( @a left_gravity  = <tt>false</tt>), the mark will end up on the right of
 480    * newly-inserted text. The standard left-to-right cursor is a mark
 481    * with right gravity (when you type, the cursor stays on the right
 482    * side of the text you're typing).
 483    *
 484    * Emits the "mark_set" signal as notification of the mark's initial
 485    * placement.
 486    * @param where Location to place mark.
 487    * @param left_gravity Whether the mark has left gravity.
 488    * @return The new Gtk::TextMark object.
 489    */
 490   Glib::RefPtr<Mark> create_mark(const iterator& where, bool left_gravity = true);
 491
 492
 493   /** Moves @a mark  to the new location @a where . Emits the "mark_set" signal
 494    * as notification of the move.
 495    * @param mark A Gtk::TextMark.
 496    * @param where New location for @a mark  in @a buffer .
 497    */
 498   void move_mark(const Glib::RefPtr<Mark>& mark, const iterator& where);
 499
 500   /** Deletes @a mark , so that it's no longer located anywhere in the
 501    * buffer. Removes the reference the buffer holds to the mark, so if
 502    * you don't keep a Glib::RefPtr to the mark, it will be freed. Even
 503    * if the mark isn't freed, most operations on @a mark  become
 504    * invalid. There is no way to undelete a
 505    * mark. Gtk::TextMark::get_deleted() will return <tt>true</tt> after this
 506    * function has been called on a mark; Gtk::TextMark::get_deleted()
 507    * indicates that a mark no longer belongs to a buffer. The "mark_deleted"
 508    * signal will be emitted as notification after the mark is deleted.
 509    * @param mark A Gtk::TextMark in @a buffer .
 510    */
 511   void delete_mark(const Glib::RefPtr<Mark>& mark);
 512
 513   /** Returns the mark named @a name  in buffer @a buffer , or <tt>0</tt> if no such
 514    * mark exists in the buffer.
 515    * @param name A mark name.
 516    * @return A Gtk::TextMark, or <tt>0</tt>.
 517    */
 518   Glib::RefPtr<TextBuffer::Mark> get_mark(const Glib::ustring& name);
 519
 520   /** Returns the mark named @a name  in buffer @a buffer , or <tt>0</tt> if no such
 521    * mark exists in the buffer.
 522    * @param name A mark name.
 523    * @return A Gtk::TextMark, or <tt>0</tt>.
 524    */
 525   Glib::RefPtr<const TextBuffer::Mark> get_mark(const Glib::ustring& name) const;
 526
 527
 528   /** Moves the mark named @a name  (which must exist) to location @a where .
 529    * See move_mark() for details.
 530    * @param name Name of a mark.
 531    * @param where New location for mark.
 532    */
 533   void move_mark_by_name(const Glib::ustring& name, const iterator& where);
 534
 535   /** Deletes the mark named @a name ; the mark must exist. See
 536    * delete_mark() for details.
 537    * @param name Name of a mark in @a buffer .
 538    */
 539   void delete_mark_by_name(const Glib::ustring& name);
 540
 541
 542   /** Returns the mark that represents the cursor (insertion point).
 543    * Equivalent to calling get_mark() to get the mark
 544    * named "insert", but very slightly more efficient, and involves less
 545    * typing.
 546    * @return Insertion point mark.
 547    */
 548   Glib::RefPtr<TextBuffer::Mark> get_insert();
 549
 550   /** Returns the mark that represents the selection bound.  Equivalent
 551    * to calling get_mark() to get the mark named
 552    * "selection_bound", but very slightly more efficient, and involves
 553    * less typing.
 554    *
 555    * The currently-selected text in @a buffer  is the region between the
 556    * "selection_bound" and "insert" marks. If "selection_bound" and
 557    * "insert" are in the same place, then there is no current selection.
 558    * get_selection_bounds() is another convenient function
 559    * for handling the selection, if you just want to know whether there's a
 560    * selection and what its bounds are.
 561    * @return Selection bound mark.
 562    */
 563   Glib::RefPtr<TextBuffer::Mark> get_selection_bound();
 564
 565
 566   /** This function moves the "insert" and "selection_bound" marks
 567    * simultaneously.  If you move them to the same place in two steps
 568    * with move_mark(), you will temporarily select a
 569    * region in between their old and new locations, which can be pretty
 570    * inefficient since the temporarily-selected region will force stuff
 571    * to be recalculated. This function moves them as a unit, which can
 572    * be optimized.
 573    * @param where Where to put the cursor.
 574    */
 575   void place_cursor(const iterator& where);
 576
 577   /** Emits the "apply_tag" signal on @a buffer . The default
 578    * handler for the signal applies @a tag  to the given range.
 579    *  @a start  and @a end  do not have to be in order.
 580    * @param tag A Gtk::TextTag.
 581    * @param start One bound of range to be tagged.
 582    * @param end Other bound of range to be tagged.
 583    */
 584   void apply_tag(const Glib::RefPtr<Tag>& tag, const iterator& start, const iterator& end);
 585
 586   /** Emits the "remove_tag" signal. The default handler for the signal
 587    * removes all occurrences of @a tag  from the given range. @a start  and
 588    *  @a end  don't have to be in order.
 589    * @param tag A Gtk::TextTag.
 590    * @param start One bound of range to be untagged.
 591    * @param end Other bound of range to be untagged.
 592    */
 593   void remove_tag(const Glib::RefPtr<Tag>& tag, const iterator& start, const iterator& end);
 594
 595   /** Calls Gtk::TextTagTable::lookup() on the buffer's tag table to
 596    * get a Gtk::TextTag, then calls apply_tag().
 597    * @param name Name of a named Gtk::TextTag.
 598    * @param start One bound of range to be tagged.
 599    * @param end Other bound of range to be tagged.
 600    */
 601   void apply_tag_by_name(const Glib::ustring& name, const iterator& start, const iterator& end);
 602
 603   /** Calls Gtk::TextTagTable::lookup() on the buffer's tag table to
 604    * get a Gtk::TextTag, then calls remove_tag().
 605    * @param name Name of a Gtk::TextTag.
 606    * @param start One bound of range to be untagged.
 607    * @param end Other bound of range to be untagged.
 608    */
 609   void remove_tag_by_name(const Glib::ustring& name, const iterator& start, const iterator& end);
 610
 611   /** Removes all tags in the range between @a start  and @a end .  Be careful
 612    * with this function; it could remove tags added in code unrelated to
 613    * the code you're currently writing. That is, using this function is
 614    * probably a bad idea if you have two or more unrelated code sections
 615    * that add tags.
 616    * @param start One bound of range to be untagged.
 617    * @param end Other bound of range to be untagged.
 618    */
 619   void remove_all_tags(const iterator& start, const iterator& end);
 620
 621   /** Creates a tag and adds it to the tag table for buffer. Equivalent to calling Gtk::TextBuffer::Tag::create() and then adding
 622    * the tag to the buffer's tag table.
 623    * A tag called @a tag_name must not already exist in the tag table for this buffer.
 624    *
 625    * @param tag_name The name for the new tag.
 626    * @result The new tag.
 627    */
 628   Glib::RefPtr<Tag> create_tag(const Glib::ustring& tag_name);
 629
 630
 631   /** Creates an anoymous tag and adds it to the tag table for buffer. Equivalent to calling Gtk::TextBuffer::Tag::create() and then adding
 632    * the tag to the buffer's tag table.
 633    *
 634    * @result The new tag.
 635    */
 636   Glib::RefPtr<Tag> create_tag();
 637
 638   iterator get_iter_at_line_offset(int line_number, int char_offset);
 639   iterator get_iter_at_line_index(int line_number, int byte_index);
 640   iterator get_iter_at_offset(int char_offset);
 641   iterator get_iter_at_line(int line_number);
 642   iterator begin();
 643   iterator end();
 644   void get_bounds(iterator& range_begin, iterator& range_end);
 645
 646   /** Get the current position of a mark.
 647    * @param mark The @link Gtk::TextMark Gtk::TextBuffer::Mark@endlink
 648    * @result An iterator that points to the position of the @a mark.
 649    */
 650   iterator get_iter_at_mark(const Glib::RefPtr<Mark>& mark);
 651
 652   /** Get the current position of an anchor.
 653    * @param anchor A @link Gtk::TextChildAnchor Gtk::TextBuffer::Anchor@endlink that appears in the buffer.
 654    * @result An iterator that points to the position of the @a anchor.
 655    */
 656   iterator get_iter_at_child_anchor(const Glib::RefPtr<ChildAnchor>& anchor);
 657
 658
 659   /** Indicates whether the buffer has been modified since the last call
 660    * to set_modified() set the modification flag to
 661    * <tt>false</tt>. Used for example to enable a "save" function in a text
 662    * editor.
 663    * @return <tt>true</tt> if the buffer has been modified.
 664    */
 665   bool get_modified() const;
 666
 667   /** Used to keep track of whether the buffer has been modified since the
 668    * last time it was saved. Whenever the buffer is saved to disk, call
 669    * gtk_text_buffer_set_modified ( @a buffer , <tt>false</tt>). When the buffer is modified,
 670    * it will automatically toggled on the modified bit again. When the modified
 671    * bit flips, the buffer emits a "modified_changed" signal.
 672    * @param setting Modification flag setting.
 673    */
 674   void set_modified(bool setting = true);
 675
 676
 677   /** Adds @a clipboard  to the list of clipboards in which the selection contents
 678    * of @a buffer  are available. In most cases, @a clipboard  will be the Gtk::Clipboard
 679    * of type Gdk::SELECTION_PRIMARY for a view of @a buffer .
 680    * @param clipboard A Gtk::Clipboard.
 681    */
 682   void add_selection_clipboard(const Glib::RefPtr<Clipboard>& clipboard);
 683
 684   /** Removes a Gtk::Clipboard added with add_selection_clipboard()
 685    * @param clipboard A Gtk::Clipboard added to @a buffer  by add_selection_clipboard().
 686    */
 687   void remove_selection_clipboard(const Glib::RefPtr<Clipboard>& clipboard);
 688
 689   /** Copies the currently-selected text to a clipboard, then deletes
 690    * said text if it's editable.
 691    * @param clipboard The Gtk::Clipboard object to cut to.
 692    * @param default_editable Default editability of the buffer.
 693    */
 694   void cut_clipboard(const Glib::RefPtr<Clipboard>& clipboard, bool default_editable = true);
 695
 696   /** Copies the currently-selected text to a clipboard.
 697    * @param clipboard The Gtk::Clipboard object to copy to.
 698    */
 699   void copy_clipboard(const Glib::RefPtr<Clipboard>& clipboard);
 700   void paste_clipboard(const Glib::RefPtr<Clipboard>& clipboard, const iterator& override_location, bool default_editable = true);
 701   void paste_clipboard(const Glib::RefPtr<Clipboard>& clipboard, bool default_editable = true);
 702
 703
 704   /** Returns <tt>true</tt> if some text is selected; places the bounds
 705    * of the selection in @a start  and @a end  (if the selection has length 0,
 706    * then @a start  and @a end  are filled in with the same value).
 707    *  @a start  and @a end  will be in ascending order. If @a start  and @a end  are
 708    * <tt>0</tt>, then they are not filled in, but the return value still indicates
 709    * whether text is selected.
 710    * @param start Iterator to initialize with selection start.
 711    * @param end Iterator to initialize with selection end.
 712    * @return Whether the selection has nonzero length.
 713    */
 714   bool get_selection_bounds(iterator& start, iterator& end) const;
 715
 716   /** Deletes the range between the "insert" and "selection_bound" marks,
 717    * that is, the currently-selected text. If @a interactive  is <tt>true</tt>,
 718    * the editability of the selection will be considered (users can't delete
 719    * uneditable text).
 720    * @param interactive Whether the deletion is caused by user interaction.
 721    * @param default_editable Whether the buffer is editable by default.
 722    * @return Whether there was a non-empty selection to delete.
 723    */
 724   bool erase_selection(bool interactive = true, bool default_editable = true);
 725
 726
 727   /** This function moves the "insert" and "selection_bound" marks
 728    * simultaneously.  If you move them in two steps
 729    * with move_mark(), you will temporarily select a
 730    * region in between their old and new locations, which can be pretty
 731    * inefficient since the temporarily-selected region will force stuff
 732    * to be recalculated. This function moves them as a unit, which can
 733    * be optimized.
 734    *
 735    * Since: 2.4
 736    * @param ins Where to put the "insert" mark.
 737    * @param bound Where to put the "selection_bound" mark.
 738    */
 739   void select_range(const iterator& ins, const iterator& bound);
 740
 741 /* Called to specify atomic user actions, used to implement undo */
 742
 743   /** Called to indicate that the buffer operations between here and a
 744    * call to end_user_action() are part of a single
 745    * user-visible operation. The operations between
 746    * begin_user_action() and
 747    * end_user_action() can then be grouped when creating
 748    * an undo stack. Gtk::TextBuffer maintains a count of calls to
 749    * begin_user_action() that have not been closed with
 750    * a call to end_user_action(), and emits the "begin_user_action"
 751    * and "end_user_action" signals only for the outermost pair of calls.
 752    * This allows you to build user actions from other user actions.
 753    *
 754    * The "interactive" buffer mutation functions, such as
 755    * insert_interactive(), automatically call begin/end
 756    * user action around the buffer operations they perform, so there's
 757    * no need to add extra calls if you user action consists solely of a
 758    * single call to one of those functions.
 759    */
 760   void begin_user_action();
 761
 762   /** Should be paired with a call to begin_user_action().
 763    * See that function for a full explanation.
 764    */
 765   void end_user_action();
 766
 767
 768   Glib::SignalProxy3< void,const TextBuffer::iterator&,const Glib::ustring&,int > signal_insert();
 769
 770
 771   Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<Gdk::Pixbuf>& > signal_insert_pixbuf();
 772
 773
 774   Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<ChildAnchor>& > signal_insert_child_anchor();
 775
 776
 777   Glib::SignalProxy2< void,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_erase();
 778
 779
 780   Glib::SignalProxy0< void > signal_changed();
 781
 782
 783   Glib::SignalProxy0< void > signal_modified_changed();
 784
 785
 786   Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<TextBuffer::Mark>& > signal_mark_set();
 787
 788
 789   Glib::SignalProxy1< void,const Glib::RefPtr<TextBuffer::Mark>& > signal_mark_deleted();
 790
 791
 792   Glib::SignalProxy3< void,const Glib::RefPtr<TextBuffer::Tag>&,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_apply_tag();
 793
 794
 795   Glib::SignalProxy3< void,const Glib::RefPtr<TextBuffer::Tag>&,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_remove_tag();
 796
 797
 798   Glib::SignalProxy0< void > signal_begin_user_action();
 799
 800
 801   Glib::SignalProxy0< void > signal_end_user_action();
 802
 803
 804 public:
 805
 806 public:
 807   //C++ methods used to invoke GTK+ virtual functions:
 808
 809 protected:
 810   //GTK+ Virtual Functions (override these to change behaviour):
 811
 812   //Default Signal Handlers::
 813   virtual void on_insert(const TextBuffer::iterator& pos, const Glib::ustring& text, int bytes);
 814   virtual void on_insert_pixbuf(const TextBuffer::iterator& pos, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
 815   virtual void on_insert_child_anchor(const TextBuffer::iterator& pos, const Glib::RefPtr<ChildAnchor>& anchor);
 816   virtual void on_erase(const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end);
 817   virtual void on_changed();
 818   virtual void on_modified_changed();
 819   virtual void on_mark_set(const TextBuffer::iterator& location, const Glib::RefPtr<TextBuffer::Mark>& mark);
 820   virtual void on_mark_deleted(const Glib::RefPtr<TextBuffer::Mark>& mark);
 821   virtual void on_apply_tag(const Glib::RefPtr<TextBuffer::Tag>& tag, const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end);
 822   virtual void on_remove_tag(const Glib::RefPtr<TextBuffer::Tag>& tag, const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end);
 823   virtual void on_begin_user_action();
 824   virtual void on_end_user_action();
 825
 826
 827 };
 828
 829 } // namespace Gtk
 830
 831
 832 namespace Glib
 833 {
 834   /** @relates Gtk::TextBuffer
 835    * @param object The C instance
 836    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 837    * @result A C++ instance that wraps this C instance.
 838    */
 839   Glib::RefPtr<Gtk::TextBuffer> wrap(GtkTextBuffer* object, bool take_copy = false);
 840 }
 841
 842
 843 #endif /* _GTKMM_TEXTBUFFER_H */
 844