diff options
Diffstat (limited to 'libs/gtkmm2/gtk/gtkmm/textbuffer.h')
| -rw-r--r-- | libs/gtkmm2/gtk/gtkmm/textbuffer.h | 844 |
1 files changed, 844 insertions, 0 deletions
diff --git a/libs/gtkmm2/gtk/gtkmm/textbuffer.h b/libs/gtkmm2/gtk/gtkmm/textbuffer.h new file mode 100644 index 0000000000..7a40dd9526 --- /dev/null +++ b/libs/gtkmm2/gtk/gtkmm/textbuffer.h @@ -0,0 +1,844 @@ +// -*- c++ -*- +// Generated by gtkmmproc -- DO NOT MODIFY! +#ifndef _GTKMM_TEXTBUFFER_H +#define _GTKMM_TEXTBUFFER_H + +#include <glibmm.h> + +/* $Id$ */ + +/* Copyright(C) 1998-2002 The gtkmm Development Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or(at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public + * License along with this library; if not, write to the Free + * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + + +#include <gtkmm/object.h> +#include <gtkmm/texttagtable.h> +#include <gtkmm/textchildanchor.h> +#include <gtkmm/textmark.h> +#include <gtkmm/textiter.h> +#include <gtkmm/clipboard.h> +#include <gdkmm/pixbuf.h> +#include <gtkmmconfig.h> +#include <utility> + +GLIBMM_USING_STD(pair) + + +#ifndef DOXYGEN_SHOULD_SKIP_THIS +typedef struct _GtkTextBuffer GtkTextBuffer; +typedef struct _GtkTextBufferClass GtkTextBufferClass; +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ + + +namespace Gtk +{ class TextBuffer_Class; } // namespace Gtk +namespace Gtk +{ + +class TextMark; +class TextIter; + +/** Multi-line attributed text that can be displayed by one or more Gtk::TextView widgets. + * + * 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 + * might be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that; tags don't + * have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user + * can't edit it, or countless other things. A tag is represented by a @link Gtk::TextTag Gtk::TextBuffer::Tag@endlink object. + * 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. + * + * 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 + * table associated with it; only tags from that tag table can be used with the buffer. A single tag table can be shared between + * multiple buffers, however. + * + * Most text manipulation is accomplished with iterators, represented by an @link Gtk::TextIter iterator@endlink. The iterator can + * be used to navigate over characters, words, lines, and sentences. + * + * But iterators can't be used to preserve positions across buffer modifications. To preserve a position, the + * @link Gtk::TextMark Gtk::TextBuffer::Mark@endlink object is ideal. There are two marks built-in to GtkTextBuffer; these are + * named "insert" and "selection_bound" and refer to the insertion point and the boundary of the selection which is not the + * insertion point. If no text is selected, these two marks will be in the same position. You can manipulate what is selected and + * where the cursor appears by moving these marks around. + * + * Text buffers always contain at least one line, but may be empty (that is, buffers can contain zero characters). The last line + * in the text buffer never ends in a line separator (such as newline); the other lines in the buffer always end in a line + * separator. Line separators count as characters when computing character counts and character offsets. Note that some Unicode + * line separators are represented with multiple bytes in UTF-8, and the two-character sequence "\r\n" is also considered a line + * separator. + * + * @ingroup TextView + */ + +class TextBuffer : public Glib::Object +{ + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +public: + typedef TextBuffer CppObjectType; + typedef TextBuffer_Class CppClassType; + typedef GtkTextBuffer BaseObjectType; + typedef GtkTextBufferClass BaseClassType; + +private: friend class TextBuffer_Class; + static CppClassType textbuffer_class_; + +private: + // noncopyable + TextBuffer(const TextBuffer&); + TextBuffer& operator=(const TextBuffer&); + +protected: + explicit TextBuffer(const Glib::ConstructParams& construct_params); + explicit TextBuffer(GtkTextBuffer* castitem); + +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ + +public: + virtual ~TextBuffer(); + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + static GType get_type() G_GNUC_CONST; + static GType get_base_type() G_GNUC_CONST; +#endif + + ///Provides access to the underlying C GObject. + GtkTextBuffer* gobj() { return reinterpret_cast<GtkTextBuffer*>(gobject_); } + + ///Provides access to the underlying C GObject. + const GtkTextBuffer* gobj() const { return reinterpret_cast<GtkTextBuffer*>(gobject_); } + + ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. + GtkTextBuffer* gobj_copy(); + +private: + + +public: + typedef TextIter iterator; + typedef TextTag Tag; + typedef TextTagTable TagTable; + typedef TextMark Mark; + typedef TextChildAnchor ChildAnchor; + +protected: + TextBuffer(); + explicit TextBuffer(const Glib::RefPtr<TagTable>& tag_table); + +public: + + static Glib::RefPtr<TextBuffer> create(); + + + static Glib::RefPtr<TextBuffer> create(const Glib::RefPtr<TagTable>& tag_table); + + + /** Obtains the number of lines in the buffer. This value is cached, so + * the function is very fast. + * @return Number of lines in the buffer. + */ + int get_line_count() const; + + /** Gets the number of characters in the buffer; note that characters + * and bytes are not the same, you can't e.g.\ expect the contents of + * the buffer in string form to be this many bytes long. The character + * count is cached, so this function is very fast. + * @return Number of characters in the buffer. + */ + int get_char_count() const; + + /// See get_char_count(). + int size() const; + + + /** Get the Gtk::TextTagTable associated with this buffer. + * @return The buffer's tag table. + */ + Glib::RefPtr<TextBuffer::TagTable> get_tag_table(); + + /** Get the Gtk::TextTagTable associated with this buffer. + * @return The buffer's tag table. + */ + Glib::RefPtr<const TextBuffer::TagTable> get_tag_table() const; + + /** Removes the current contents of the buffer, and inserts @a text instead. + * @param text The text to put in the buffer. + */ + void set_text(const Glib::ustring& text); + + /** Removes the current contents of the buffer, and inserts @a text instead. + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + */ + void set_text(const char* text_begin, const char* text_end); + + + #ifndef GTKMM_DISABLE_DEPRECATED + /** @deprecated Use set_text() + */ + void assign(const Glib::ustring& text); + + /** @deprecated Use set_text() + */ + void assign(const char* text_begin, const char* text_end); + #endif //GTKMM_DISABLE_DEPRECATED + + //TODO: Make all insert() methods have the same return type: + + /** Inserts @a text at position @a pos. + * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal. + * The @a pos iterator is invalidated when insertion occurs (because the buffer contents change). + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text The text to be inserted in the buffer. + * @result An iterator that points to the end of the inserted text. + */ + iterator insert(const iterator& pos, const Glib::ustring& text); + + /** Inserts text at position @a pos. + * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal. + * The @a pos iterator is invalidated when insertion occurs (because the buffer contents change). + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @result An iterator that points to the end of the inserted text. + */ + iterator insert(const iterator& pos, const char* text_begin, const char* text_end); + + /** Inserts @a text, using the current cursor position as the insertion point. + * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal. + * + * @param text The text to be inserted in the buffer. + * @result An iterator that points to the end of the inserted text. + */ + void insert_at_cursor(const Glib::ustring& text); + + /** Inserts text, using the current cursor position as the insertion point. + * Emits the "insert_text" signal; insertion actually occurs in the default handler for the signal. + * + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @result An iterator that points to the end of the inserted text. + */ + void insert_at_cursor(const char* text_begin, const char* text_end); + + /** Like insert(), but the insertion will not occur if @a iter is at a non-editable location in the buffer. + * Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive). + * + * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text The text to be inserted in the buffer. + * @param default_editable Default editability of buffer + * @result Whether text was actually inserted + */ + std::pair<iterator,bool> insert_interactive( + const iterator& pos, const Glib::ustring& text, bool default_editable = true); + + /** Like insert(), but the insertion will not occur if @a pos is at a non-editable location in the buffer. + * Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive). + * + * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @param default_editable Default editability of buffer. + * @result Whether text was actually inserted + */ + std::pair<iterator,bool> insert_interactive( + const iterator& pos, const char* text_begin, const char* text_end, bool default_editable = true); + + /** Calls insert_interactive() at the cursor position. + * + * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param text The text to be inserted in the buffer. + * @param default_editable Default editability of buffer + * @result Whether text was actually inserted + */ + bool insert_interactive_at_cursor(const Glib::ustring& text, bool default_editable = true); + + /** Calls insert_interactive() at the cursor position. + * + * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @param default_editable Default editability of buffer + * @result Whether text was actually inserted + */ + bool insert_interactive_at_cursor(const char* text_begin, const char* text_end, + bool default_editable = true); + + /** Copies text, tags, and pixbufs between @a range_begin and @a range_end (the order of range_begin and range_begin doesn't + * matter) and inserts the copy at @a pos. Used instead of simply getting/inserting text because it preserves images and tags. + * If range_begin and range_end are in a different buffer, the two buffers must share the same tag table. + * + * Implemented via emissions of the insert_text and apply_tag signals, so expect those. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param range_begin A position in a buffer. + * @param range_end Another position in the same buffer as @a range_begin. + * @result Whether text was actually inserted + */ + iterator insert(const iterator& pos, const iterator& range_begin, const iterator& range_end); + + + /** Same as insert_range(), but does nothing if the insertion point isn't editable. + * + * The @a default_editable parameter indicates whether the text is editable at @a pos if no tags enclosing @a pos affect editability. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param range_begin A position in a buffer. + * @param range_end Another position in the same buffer as @a range_begin. + * @param default_editable Default editability of buffer. + * @result Whether text was actually inserted + */ + std::pair<iterator,bool> insert_interactive(const iterator& pos, const iterator& range_begin, const iterator& range_end, bool default_editable = true); + + + iterator insert_with_tag(const iterator& pos, const Glib::ustring& text, const Glib::RefPtr<Tag>& tag); + iterator insert_with_tag(const iterator& pos, const char* text_begin, const char* text_end, const Glib::RefPtr<Tag>& tag); + + iterator insert_with_tag(const iterator& pos, const Glib::ustring& text, const Glib::ustring& tag_name); + iterator insert_with_tag(const iterator& pos, const char* text_begin, const char* text_end, const Glib::ustring& tag_name); + + /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text. + * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text The text to be inserted in the buffer. + * @param tags A standard C++ container of @link Gtk::TextTag Gtk::TextBuffer::Tags@endlink. + * @result Whether text was actually inserted + */ + iterator insert_with_tags(const iterator& pos, const Glib::ustring& text, + const Glib::ArrayHandle< Glib::RefPtr<Tag> >& tags); + + /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text. + * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @param tags A standard C++ container of @link Gtk::TextTag Gtk::TextBuffer::Tags@endlink. + * @result Whether text was actually inserted + */ + iterator insert_with_tags(const iterator& pos, const char* text_begin, const char* text_end, + const Glib::ArrayHandle< Glib::RefPtr<Tag> >& tags); + + /** Inserts text into buffer at @a pos, applying the list of tags to the newly-inserted text. + * Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text The text to be inserted in the buffer. + * @param tag_names A standard C++ container of tag names. + * @result Whether text was actually inserted + */ + iterator insert_with_tags_by_name(const iterator& pos, const Glib::ustring& text, + const Glib::StringArrayHandle& tag_names); + + + /** Equivalent to calling insert(), then apply_tag() on the inserted text; This is just a convenience function. + * + * @param pos An iterator pointing to the position at which the text should be inserted. + * @param text_begin The start of a UTF8 character array. + * @param text_end The end of the UTF8 character array. + * @param tag_names A standard C++ container of tag names. + * @result Whether text was actually inserted + */ + iterator insert_with_tags_by_name(const iterator& pos, const char* text_begin, const char* text_end, + const Glib::StringArrayHandle& tag_names); + + /* Deletes all text between @a range_begin and @a range_end. The order of range_begin and range_end is not actually relevant. + * This function actually emits the "delete_range" signal, and the default handler of that signal deletes the text. + * Because the buffer is modified, all outstanding iterators become invalid after calling this function. + * @param range_begin + * @param range_end + * @result An iterator that points to the location where text was deleted. + */ + iterator erase(const iterator& range_begin, const iterator& range_end); + + + /* Deletes all editable text between @a range_begin and @a range_end. The order of range_begin and range_end is not actually relevant. + * This function actually emits the "delete_range" signal, and the default handler of that signal deletes the text. + * Because the buffer is modified, all outstanding iterators become invalid after calling this function. + * + * @a default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. + * Typically the result of Gtk::TextView::get_editable() is appropriate here. + * + * @param range_begin + * @param range_end + * @param default_editable Default editability of buffer + * @result An iterator that points to the location where text was deleted, or end() is no text was deleted. + */ + std::pair<iterator,bool> erase_interactive(const iterator& range_begin, const iterator& range_end, bool default_editable = true); + + + //TODO: Document this: + iterator backspace(const iterator& iter, bool interactive = true, bool default_editable = true); + + + /** Returns the text in the range [ @a start , @a end ). Excludes undisplayed + * text (text marked with tags that set the invisibility attribute) if + * @a include_hidden_chars is <tt>false</tt>. Does not include characters + * representing embedded images, so byte and character indexes into + * the returned string do <em>not</em> correspond to byte + * and character indexes into the buffer. Contrast with + * get_slice(). + * @param start Start of a range. + * @param end End of a range. + * @param include_hidden_chars Whether to include invisible text. + * @return An allocated UTF-8 string. + */ + Glib::ustring get_text(const iterator& start, const iterator& end, bool include_hidden_chars = true); + + /** Returns all the text in the buffer. Excludes undisplayed + * text (text marked with tags that set the invisibility attribute) if + * @a include_hidden_chars is <tt>false</tt>. Does not include characters + * representing embedded images, so byte and character indexes into + * the returned string do <em>not</em> correspond to byte + * and character indexes into the buffer. Contrast with + * get_slice(). + * + * @param include_hidden_chars Whether to include invisible text. + * @return An allocated UTF-8 string. + */ + Glib::ustring get_text(bool include_hidden_chars = true); + + + /** Returns the text in the range [ @a start , @a end ). Excludes undisplayed + * text (text marked with tags that set the invisibility attribute) if + * @a include_hidden_chars is <tt>false</tt>. The returned string includes a + * 0xFFFC character whenever the buffer contains + * embedded images, so byte and character indexes into + * the returned string <em>do</em> correspond to byte + * and character indexes into the buffer. Contrast with + * get_text(). Note that 0xFFFC can occur in normal + * text as well, so it is not a reliable indicator that a pixbuf or + * widget is in the buffer. + * @param start Start of a range. + * @param end End of a range. + * @param include_hidden_chars Whether to include invisible text. + * @return An allocated UTF-8 string. + */ + Glib::ustring get_slice(const iterator& start, const iterator& end, bool include_hidden_chars = true); + + iterator insert_pixbuf(const iterator& pos, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf); + + + iterator insert_child_anchor(const iterator& pos, const Glib::RefPtr<ChildAnchor>& anchor); + + + Glib::RefPtr<ChildAnchor> create_child_anchor(const iterator& pos); + + + /** Creates a mark at position @a where . The mark can be retrieved by name using + * get_mark(). If a mark has left gravity, and text is + * inserted at the mark's current location, the mark will be moved to + * the left of the newly-inserted text. If the mark has right gravity + * ( @a left_gravity = <tt>false</tt>), the mark will end up on the right of + * newly-inserted text. The standard left-to-right cursor is a mark + * with right gravity (when you type, the cursor stays on the right + * side of the text you're typing). + * + * Emits the "mark_set" signal as notification of the mark's initial + * placement. + * @param mark_name Name for mark, or <tt>0</tt>. + * @param where Location to place mark. + * @param left_gravity Whether the mark has left gravity. + * @return The new Gtk::TextMark object. + */ + Glib::RefPtr<TextBuffer::Mark> create_mark(const Glib::ustring& mark_name, const iterator& where, bool left_gravity = true); + + /** Create an anonymous mark. */ + /** Creates an anonymous mark at position @a where. + * + * If a mark has left gravity, and text is + * inserted at the mark's current location, the mark will be moved to + * the left of the newly-inserted text. If the mark has right gravity + * ( @a left_gravity = <tt>false</tt>), the mark will end up on the right of + * newly-inserted text. The standard left-to-right cursor is a mark + * with right gravity (when you type, the cursor stays on the right + * side of the text you're typing). + * + * Emits the "mark_set" signal as notification of the mark's initial + * placement. + * @param where Location to place mark. + * @param left_gravity Whether the mark has left gravity. + * @return The new Gtk::TextMark object. + */ + Glib::RefPtr<Mark> create_mark(const iterator& where, bool left_gravity = true); + + + /** Moves @a mark to the new location @a where . Emits the "mark_set" signal + * as notification of the move. + * @param mark A Gtk::TextMark. + * @param where New location for @a mark in @a buffer . + */ + void move_mark(const Glib::RefPtr<Mark>& mark, const iterator& where); + + /** Deletes @a mark , so that it's no longer located anywhere in the + * buffer. Removes the reference the buffer holds to the mark, so if + * you don't keep a Glib::RefPtr to the mark, it will be freed. Even + * if the mark isn't freed, most operations on @a mark become + * invalid. There is no way to undelete a + * mark. Gtk::TextMark::get_deleted() will return <tt>true</tt> after this + * function has been called on a mark; Gtk::TextMark::get_deleted() + * indicates that a mark no longer belongs to a buffer. The "mark_deleted" + * signal will be emitted as notification after the mark is deleted. + * @param mark A Gtk::TextMark in @a buffer . + */ + void delete_mark(const Glib::RefPtr<Mark>& mark); + + /** Returns the mark named @a name in buffer @a buffer , or <tt>0</tt> if no such + * mark exists in the buffer. + * @param name A mark name. + * @return A Gtk::TextMark, or <tt>0</tt>. + */ + Glib::RefPtr<TextBuffer::Mark> get_mark(const Glib::ustring& name); + + /** Returns the mark named @a name in buffer @a buffer , or <tt>0</tt> if no such + * mark exists in the buffer. + * @param name A mark name. + * @return A Gtk::TextMark, or <tt>0</tt>. + */ + Glib::RefPtr<const TextBuffer::Mark> get_mark(const Glib::ustring& name) const; + + + /** Moves the mark named @a name (which must exist) to location @a where . + * See move_mark() for details. + * @param name Name of a mark. + * @param where New location for mark. + */ + void move_mark_by_name(const Glib::ustring& name, const iterator& where); + + /** Deletes the mark named @a name ; the mark must exist. See + * delete_mark() for details. + * @param name Name of a mark in @a buffer . + */ + void delete_mark_by_name(const Glib::ustring& name); + + + /** Returns the mark that represents the cursor (insertion point). + * Equivalent to calling get_mark() to get the mark + * named "insert", but very slightly more efficient, and involves less + * typing. + * @return Insertion point mark. + */ + Glib::RefPtr<TextBuffer::Mark> get_insert(); + + /** Returns the mark that represents the selection bound. Equivalent + * to calling get_mark() to get the mark named + * "selection_bound", but very slightly more efficient, and involves + * less typing. + * + * The currently-selected text in @a buffer is the region between the + * "selection_bound" and "insert" marks. If "selection_bound" and + * "insert" are in the same place, then there is no current selection. + * get_selection_bounds() is another convenient function + * for handling the selection, if you just want to know whether there's a + * selection and what its bounds are. + * @return Selection bound mark. + */ + Glib::RefPtr<TextBuffer::Mark> get_selection_bound(); + + + /** This function moves the "insert" and "selection_bound" marks + * simultaneously. If you move them to the same place in two steps + * with move_mark(), you will temporarily select a + * region in between their old and new locations, which can be pretty + * inefficient since the temporarily-selected region will force stuff + * to be recalculated. This function moves them as a unit, which can + * be optimized. + * @param where Where to put the cursor. + */ + void place_cursor(const iterator& where); + + /** Emits the "apply_tag" signal on @a buffer . The default + * handler for the signal applies @a tag to the given range. + * @a start and @a end do not have to be in order. + * @param tag A Gtk::TextTag. + * @param start One bound of range to be tagged. + * @param end Other bound of range to be tagged. + */ + void apply_tag(const Glib::RefPtr<Tag>& tag, const iterator& start, const iterator& end); + + /** Emits the "remove_tag" signal. The default handler for the signal + * removes all occurrences of @a tag from the given range. @a start and + * @a end don't have to be in order. + * @param tag A Gtk::TextTag. + * @param start One bound of range to be untagged. + * @param end Other bound of range to be untagged. + */ + void remove_tag(const Glib::RefPtr<Tag>& tag, const iterator& start, const iterator& end); + + /** Calls Gtk::TextTagTable::lookup() on the buffer's tag table to + * get a Gtk::TextTag, then calls apply_tag(). + * @param name Name of a named Gtk::TextTag. + * @param start One bound of range to be tagged. + * @param end Other bound of range to be tagged. + */ + void apply_tag_by_name(const Glib::ustring& name, const iterator& start, const iterator& end); + + /** Calls Gtk::TextTagTable::lookup() on the buffer's tag table to + * get a Gtk::TextTag, then calls remove_tag(). + * @param name Name of a Gtk::TextTag. + * @param start One bound of range to be untagged. + * @param end Other bound of range to be untagged. + */ + void remove_tag_by_name(const Glib::ustring& name, const iterator& start, const iterator& end); + + /** Removes all tags in the range between @a start and @a end . Be careful + * with this function; it could remove tags added in code unrelated to + * the code you're currently writing. That is, using this function is + * probably a bad idea if you have two or more unrelated code sections + * that add tags. + * @param start One bound of range to be untagged. + * @param end Other bound of range to be untagged. + */ + void remove_all_tags(const iterator& start, const iterator& end); + + /** Creates a tag and adds it to the tag table for buffer. Equivalent to calling Gtk::TextBuffer::Tag::create() and then adding + * the tag to the buffer's tag table. + * A tag called @a tag_name must not already exist in the tag table for this buffer. + * + * @param tag_name The name for the new tag. + * @result The new tag. + */ + Glib::RefPtr<Tag> create_tag(const Glib::ustring& tag_name); + + + /** Creates an anoymous tag and adds it to the tag table for buffer. Equivalent to calling Gtk::TextBuffer::Tag::create() and then adding + * the tag to the buffer's tag table. + * + * @result The new tag. + */ + Glib::RefPtr<Tag> create_tag(); + + iterator get_iter_at_line_offset(int line_number, int char_offset); + iterator get_iter_at_line_index(int line_number, int byte_index); + iterator get_iter_at_offset(int char_offset); + iterator get_iter_at_line(int line_number); + iterator begin(); + iterator end(); + void get_bounds(iterator& range_begin, iterator& range_end); + + /** Get the current position of a mark. + * @param mark The @link Gtk::TextMark Gtk::TextBuffer::Mark@endlink + * @result An iterator that points to the position of the @a mark. + */ + iterator get_iter_at_mark(const Glib::RefPtr<Mark>& mark); + + /** Get the current position of an anchor. + * @param anchor A @link Gtk::TextChildAnchor Gtk::TextBuffer::Anchor@endlink that appears in the buffer. + * @result An iterator that points to the position of the @a anchor. + */ + iterator get_iter_at_child_anchor(const Glib::RefPtr<ChildAnchor>& anchor); + + + /** Indicates whether the buffer has been modified since the last call + * to set_modified() set the modification flag to + * <tt>false</tt>. Used for example to enable a "save" function in a text + * editor. + * @return <tt>true</tt> if the buffer has been modified. + */ + bool get_modified() const; + + /** Used to keep track of whether the buffer has been modified since the + * last time it was saved. Whenever the buffer is saved to disk, call + * gtk_text_buffer_set_modified ( @a buffer , <tt>false</tt>). When the buffer is modified, + * it will automatically toggled on the modified bit again. When the modified + * bit flips, the buffer emits a "modified_changed" signal. + * @param setting Modification flag setting. + */ + void set_modified(bool setting = true); + + + /** Adds @a clipboard to the list of clipboards in which the selection contents + * of @a buffer are available. In most cases, @a clipboard will be the Gtk::Clipboard + * of type Gdk::SELECTION_PRIMARY for a view of @a buffer . + * @param clipboard A Gtk::Clipboard. + */ + void add_selection_clipboard(const Glib::RefPtr<Clipboard>& clipboard); + + /** Removes a Gtk::Clipboard added with add_selection_clipboard() + * @param clipboard A Gtk::Clipboard added to @a buffer by add_selection_clipboard(). + */ + void remove_selection_clipboard(const Glib::RefPtr<Clipboard>& clipboard); + + /** Copies the currently-selected text to a clipboard, then deletes + * said text if it's editable. + * @param clipboard The Gtk::Clipboard object to cut to. + * @param default_editable Default editability of the buffer. + */ + void cut_clipboard(const Glib::RefPtr<Clipboard>& clipboard, bool default_editable = true); + + /** Copies the currently-selected text to a clipboard. + * @param clipboard The Gtk::Clipboard object to copy to. + */ + void copy_clipboard(const Glib::RefPtr<Clipboard>& clipboard); + void paste_clipboard(const Glib::RefPtr<Clipboard>& clipboard, const iterator& override_location, bool default_editable = true); + void paste_clipboard(const Glib::RefPtr<Clipboard>& clipboard, bool default_editable = true); + + + /** Returns <tt>true</tt> if some text is selected; places the bounds + * of the selection in @a start and @a end (if the selection has length 0, + * then @a start and @a end are filled in with the same value). + * @a start and @a end will be in ascending order. If @a start and @a end are + * <tt>0</tt>, then they are not filled in, but the return value still indicates + * whether text is selected. + * @param start Iterator to initialize with selection start. + * @param end Iterator to initialize with selection end. + * @return Whether the selection has nonzero length. + */ + bool get_selection_bounds(iterator& start, iterator& end) const; + + /** Deletes the range between the "insert" and "selection_bound" marks, + * that is, the currently-selected text. If @a interactive is <tt>true</tt>, + * the editability of the selection will be considered (users can't delete + * uneditable text). + * @param interactive Whether the deletion is caused by user interaction. + * @param default_editable Whether the buffer is editable by default. + * @return Whether there was a non-empty selection to delete. + */ + bool erase_selection(bool interactive = true, bool default_editable = true); + + + /** This function moves the "insert" and "selection_bound" marks + * simultaneously. If you move them in two steps + * with move_mark(), you will temporarily select a + * region in between their old and new locations, which can be pretty + * inefficient since the temporarily-selected region will force stuff + * to be recalculated. This function moves them as a unit, which can + * be optimized. + * + * Since: 2.4 + * @param ins Where to put the "insert" mark. + * @param bound Where to put the "selection_bound" mark. + */ + void select_range(const iterator& ins, const iterator& bound); + +/* Called to specify atomic user actions, used to implement undo */ + + /** Called to indicate that the buffer operations between here and a + * call to end_user_action() are part of a single + * user-visible operation. The operations between + * begin_user_action() and + * end_user_action() can then be grouped when creating + * an undo stack. Gtk::TextBuffer maintains a count of calls to + * begin_user_action() that have not been closed with + * a call to end_user_action(), and emits the "begin_user_action" + * and "end_user_action" signals only for the outermost pair of calls. + * This allows you to build user actions from other user actions. + * + * The "interactive" buffer mutation functions, such as + * insert_interactive(), automatically call begin/end + * user action around the buffer operations they perform, so there's + * no need to add extra calls if you user action consists solely of a + * single call to one of those functions. + */ + void begin_user_action(); + + /** Should be paired with a call to begin_user_action(). + * See that function for a full explanation. + */ + void end_user_action(); + + + Glib::SignalProxy3< void,const TextBuffer::iterator&,const Glib::ustring&,int > signal_insert(); + + + Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<Gdk::Pixbuf>& > signal_insert_pixbuf(); + + + Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<ChildAnchor>& > signal_insert_child_anchor(); + + + Glib::SignalProxy2< void,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_erase(); + + + Glib::SignalProxy0< void > signal_changed(); + + + Glib::SignalProxy0< void > signal_modified_changed(); + + + Glib::SignalProxy2< void,const TextBuffer::iterator&,const Glib::RefPtr<TextBuffer::Mark>& > signal_mark_set(); + + + Glib::SignalProxy1< void,const Glib::RefPtr<TextBuffer::Mark>& > signal_mark_deleted(); + + + Glib::SignalProxy3< void,const Glib::RefPtr<TextBuffer::Tag>&,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_apply_tag(); + + + Glib::SignalProxy3< void,const Glib::RefPtr<TextBuffer::Tag>&,const TextBuffer::iterator&,const TextBuffer::iterator& > signal_remove_tag(); + + + Glib::SignalProxy0< void > signal_begin_user_action(); + + + Glib::SignalProxy0< void > signal_end_user_action(); + + +public: + +public: + //C++ methods used to invoke GTK+ virtual functions: + +protected: + //GTK+ Virtual Functions (override these to change behaviour): + + //Default Signal Handlers:: + virtual void on_insert(const TextBuffer::iterator& pos, const Glib::ustring& text, int bytes); + virtual void on_insert_pixbuf(const TextBuffer::iterator& pos, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf); + virtual void on_insert_child_anchor(const TextBuffer::iterator& pos, const Glib::RefPtr<ChildAnchor>& anchor); + virtual void on_erase(const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end); + virtual void on_changed(); + virtual void on_modified_changed(); + virtual void on_mark_set(const TextBuffer::iterator& location, const Glib::RefPtr<TextBuffer::Mark>& mark); + virtual void on_mark_deleted(const Glib::RefPtr<TextBuffer::Mark>& mark); + virtual void on_apply_tag(const Glib::RefPtr<TextBuffer::Tag>& tag, const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end); + virtual void on_remove_tag(const Glib::RefPtr<TextBuffer::Tag>& tag, const TextBuffer::iterator& range_begin, const TextBuffer::iterator& range_end); + virtual void on_begin_user_action(); + virtual void on_end_user_action(); + + +}; + +} // namespace Gtk + + +namespace Glib +{ + /** @relates Gtk::TextBuffer + * @param object The C instance + * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. + * @result A C++ instance that wraps this C instance. + */ + Glib::RefPtr<Gtk::TextBuffer> wrap(GtkTextBuffer* object, bool take_copy = false); +} + + +#endif /* _GTKMM_TEXTBUFFER_H */ + |