gtkmm  4.8.0
Public Member Functions | Related Functions | List of all members
Gtk::TextIter Class Reference

Typedefed as Gtk::TextBuffer::iterator. More...

#include <gtkmm/textiter.h>

Inheritance diagram for Gtk::TextIter:
Inheritance graph
[legend]

Public Member Functions

TextIteroperator++ ()
 Alias for forward_char(). More...
 
TextIter operator++ (int)
 
TextIteroperator-- ()
 Alias for backward_char(). More...
 
TextIter operator-- (int)
 
Glib::RefPtr< TextBufferget_buffer () const
 Returns the Gtk::TextBuffer this iterator is associated with. More...
 
Glib::RefPtr< Gdk::Paintableget_paintable () const
 If the element at iter is a paintable, the paintable is returned. More...
 
std::vector< Glib::RefPtr< TextMark > > get_marks () const
 Returns a list of all Gtk::TextMark at this location. More...
 
Glib::RefPtr< TextChildAnchorget_child_anchor () const
 If the location at iter contains a child anchor, the anchor is returned. More...
 
std::vector< Glib::RefPtr< TextTag > > get_toggled_tags (bool toggled_on=true) const
 Returns a list of Gtk::TextTag that are toggled on or off at this point. More...
 
std::vector< Glib::RefPtr< TextTag > > get_tags () const
 Returns a list of tags that apply to iter, in ascending order of priority (highest-priority tags are last). More...
 
bool forward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end, const TextIterBase & limit) const
 Searches forward for str. More...
 
bool forward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end) const
 A forward_search() convenience overload. More...
 
bool backward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end, const TextIterBase & limit) const
 Same as forward_search(), but moves backward. More...
 
bool backward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end) const
 A backward_search() convenience overload. More...
 
void order (TextIter & second)
 Swaps the value of first and second if second comes before first in the buffer. More...
 
- Public Member Functions inherited from Gtk::TextIterBase
 TextIterBase (const TextIterBase & other) noexcept
 
TextIterBaseoperator= (const TextIterBase & other) noexcept
 
 TextIterBase (TextIterBase && other) noexcept
 
TextIterBaseoperator= (TextIterBase && other) noexcept
 
 TextIterBase ()
 
 TextIterBase (const GtkTextIter * gobject)
 
GtkTextIter * gobj ()
 Provides access to the underlying C instance. More...
 
const GtkTextIter * gobj () const
 Provides access to the underlying C instance. More...
 
value_type operator* () const
 Alias for get_char(). More...
 
 operator bool () const
 Alias for !is_end(). More...
 
int get_offset () const
 Returns the character offset of an iterator. More...
 
int get_line () const
 Returns the line number containing the iterator. More...
 
int get_line_offset () const
 Returns the character offset of the iterator, counting from the start of a newline-terminated line. More...
 
int get_line_index () const
 Returns the byte index of the iterator, counting from the start of a newline-terminated line. More...
 
int get_visible_line_offset () const
 Returns the offset in characters from the start of the line to the given iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. More...
 
int get_visible_line_index () const
 Returns the number of bytes from the start of the line to the given iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. More...
 
gunichar get_char () const
 The Unicode character at this iterator is returned. More...
 
Glib::ustring get_slice (const TextIterBase &end) const
 Returns the text in the given range. More...
 
Glib::ustring get_text (const TextIterBase &end) const
 Returns text in the given range. More...
 
Glib::ustring get_visible_slice (const TextIterBase &end) const
 Returns visible text in the given range. More...
 
Glib::ustring get_visible_text (const TextIterBase &end) const
 Returns visible text in the given range. More...
 
bool starts_tag (const Glib::RefPtr< const TextTag > & tag={}) const
 Returns true if tag is toggled on at exactly this point. More...
 
bool ends_tag (const Glib::RefPtr< const TextTag > & tag={}) const
 Returns true if tag is toggled off at exactly this point. More...
 
bool toggles_tag (const Glib::RefPtr< const TextTag > & tag={}) const
 Gets whether a range with tag applied to it begins or ends at iter. More...
 
bool has_tag (const Glib::RefPtr< const TextTag > & tag) const
 Returns true if iter points to a character that is part of a range tagged with tag. More...
 
bool editable (bool default_setting=true) const
 Returns whether the character at iter is within an editable region of text. More...
 
bool can_insert (bool default_editability=true) const
 Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at iter would be editable. More...
 
bool starts_word () const
 Determines whether iter begins a natural-language word. More...
 
bool ends_word () const
 Determines whether iter ends a natural-language word. More...
 
bool inside_word () const
 Determines whether the character pointed by iter is part of a natural-language word (as opposed to say inside some whitespace). More...
 
bool starts_sentence () const
 Determines whether iter begins a sentence. More...
 
bool ends_sentence () const
 Determines whether iter ends a sentence. More...
 
bool inside_sentence () const
 Determines whether iter is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). More...
 
bool starts_line () const
 Returns true if iter begins a paragraph. More...
 
bool ends_line () const
 Returns true if iter points to the start of the paragraph delimiter characters for a line. More...
 
bool is_cursor_position () const
 Determine if iter is at a cursor position. More...
 
int get_chars_in_line () const
 Returns the number of characters in the line containing iter, including the paragraph delimiters. More...
 
int get_bytes_in_line () const
 Returns the number of bytes in the line containing iter, including the paragraph delimiters. More...
 
Pango::Language get_language () const
 Returns the language in effect at iter. More...
 
bool is_end () const
 Returns true if iter is the end iterator. More...
 
bool is_start () const
 Returns true if iter is the first iterator in the buffer. More...
 
bool forward_char ()
 Moves iter forward by one character offset. More...
 
bool backward_char ()
 Moves backward by one character offset. More...
 
bool forward_chars (int count)
 Moves count characters if possible. More...
 
bool backward_chars (int count)
 Moves count characters backward, if possible. More...
 
bool forward_line ()
 Moves iter to the start of the next line. More...
 
bool backward_line ()
 Moves iter to the start of the previous line. More...
 
bool forward_lines (int count)
 Moves count lines forward, if possible. More...
 
bool backward_lines (int count)
 Moves count lines backward, if possible. More...
 
bool forward_word_end ()
 Moves forward to the next word end. More...
 
bool backward_word_start ()
 Moves backward to the previous word start. More...
 
bool forward_word_ends (int count)
 Calls forward_word_end() up to count times. More...
 
bool backward_word_starts (int count)
 Calls backward_word_start() up to count times. More...
 
bool forward_visible_line ()
 Moves iter to the start of the next visible line. More...
 
bool backward_visible_line ()
 Moves iter to the start of the previous visible line. More...
 
bool forward_visible_lines (int count)
 Moves count visible lines forward, if possible. More...
 
bool backward_visible_lines (int count)
 Moves count visible lines backward, if possible. More...
 
bool forward_visible_word_end ()
 Moves forward to the next visible word end. More...
 
bool backward_visible_word_start ()
 Moves backward to the previous visible word start. More...
 
bool forward_visible_word_ends (int count)
 Calls forward_visible_word_end() up to count times. More...
 
bool backward_visible_word_starts (int count)
 Calls backward_visible_word_start() up to count times. More...
 
bool forward_sentence_end ()
 Moves forward to the next sentence end. More...
 
bool backward_sentence_start ()
 Moves backward to the previous sentence start. More...
 
bool forward_sentence_ends (int count)
 Calls forward_sentence_end() count times. More...
 
bool backward_sentence_starts (int count)
 Calls backward_sentence_start() up to count times. More...
 
bool forward_cursor_position ()
 Moves iter forward by a single cursor position. More...
 
bool backward_cursor_position ()
 Like forward_cursor_position(), but moves backward. More...
 
bool forward_cursor_positions (int count)
 Moves up to count cursor positions. More...
 
bool backward_cursor_positions (int count)
 Moves up to count cursor positions. More...
 
bool forward_visible_cursor_position ()
 Moves iter forward to the next visible cursor position. More...
 
bool backward_visible_cursor_position ()
 Moves iter forward to the previous visible cursor position. More...
 
bool forward_visible_cursor_positions (int count)
 Moves up to count visible cursor positions. More...
 
bool backward_visible_cursor_positions (int count)
 Moves up to count visible cursor positions. More...
 
void set_offset (int char_offset)
 Sets iter to point to char_offset. More...
 
void set_line (int line_number)
 Moves iterator iter to the start of the line line_number. More...
 
void set_line_offset (int char_on_line)
 Moves iter within a line, to a new character (not byte) offset. More...
 
void set_line_index (int byte_on_line)
 Same as set_line_offset(), but works with a byte index. More...
 
void forward_to_end ()
 Moves iter forward to the “end iterator”, which points one past the last valid character in the buffer. More...
 
bool forward_to_line_end ()
 Moves the iterator to point to the paragraph delimiter characters. More...
 
void set_visible_line_offset (int char_on_line)
 Like set_line_offset(), but the offset is in visible characters, i.e. text with a tag making it invisible is not counted in the offset. More...
 
void set_visible_line_index (int byte_on_line)
 Like set_line_index(), but the index is in visible bytes, i.e. text with a tag making it invisible is not counted in the index. More...
 
bool forward_to_tag_toggle (const Glib::RefPtr< const TextTag > & tag={})
 Moves forward to the next toggle (on or off) of the tag, or to the next toggle of any tag if tag is nullptr. More...
 
bool backward_to_tag_toggle (const Glib::RefPtr< const TextTag > & tag={})
 Moves backward to the next toggle (on or off) of the tag, or to the next toggle of any tag if tag is nullptr. More...
 
bool forward_find_char (const SlotFindChar & slot, const TextIterBase & limit)
 Advances this iterator, calling slot on each character. More...
 
bool forward_find_char (const SlotFindChar & slot)
 Advances this iterator, calling slot on each character. More...
 
bool backward_find_char (const SlotFindChar & slot, const TextIterBase & limit)
 Same as forward_find_char(const SlotFindChar& slot, const TextIterBase& limit), but goes backward. More...
 
bool backward_find_char (const SlotFindChar & slot)
 Same as forward_find_char(const SlotFindChar& slot), but goes backward. More...
 
int compare (const TextIterBase & rhs) const
 A qsort()-style function that returns negative if lhs is less than rhs, positive if lhs is greater than rhs, and 0 if they’re equal. More...
 
bool in_range (const TextIterBase &start, const TextIterBase &end) const
 Checks whether iter falls in the range [ start, end). More...
 

Related Functions

(Note that these are not member functions.)

Gtk::TextIterwrap_iter (GtkTextIter * object)
 
const Gtk::TextIterwrap_iter (const GtkTextIter * object)
 

Additional Inherited Members

- Public Types inherited from Gtk::TextIterBase
using iterator_category = std::bidirectional_iterator_tag
 
using value_type = gunichar
 
using difference_type = int
 
using reference = value_type
 
using pointer = void
 
using SlotFindChar = sigc::slot< bool(gunichar)>
 A slot that will be called on each consecutive character. More...
 
- Static Public Member Functions inherited from Gtk::TextIterBase
static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 
- Protected Attributes inherited from Gtk::TextIterBase
GtkTextIter gobject_
 

Detailed Description

Typedefed as Gtk::TextBuffer::iterator.

An iterator represents a position between two characters in the text buffer. Iterators are not valid indefinitely; whenever the buffer is modified in a way that affects the number of characters in the buffer, all outstanding iterators become invalid. (Note that deleting 5 characters and then reinserting 5 still invalidates iterators, though you end up with the same number of characters you pass through a state with a different number).

Because of this, iterators can't be used to preserve positions across buffer modifications. To preserve a position, the Gtk::TextBuffer::Mark object is ideal.

You can iterate over characters, words, lines, and sentences, but operator*() and operator++() deal only in characters.

Member Function Documentation

◆ backward_search() [1/2]

bool Gtk::TextIter::backward_search ( const Glib::ustring &  str,
TextSearchFlags  flags,
TextIter match_start,
TextIter match_end 
) const

A backward_search() convenience overload.

◆ backward_search() [2/2]

bool Gtk::TextIter::backward_search ( const Glib::ustring &  str,
TextSearchFlags  flags,
TextIter match_start,
TextIter match_end,
const TextIterBase limit 
) const

Same as forward_search(), but moves backward.

Parameters
strSearch string.
flagsBitmask of flags affecting the search.
match_startReturn location for start of match.
match_endReturn location for end of match.
limitLocation of last possible match_start.
Returns
Whether a match was found.

◆ forward_search() [1/2]

bool Gtk::TextIter::forward_search ( const Glib::ustring &  str,
TextSearchFlags  flags,
TextIter match_start,
TextIter match_end 
) const

A forward_search() convenience overload.

◆ forward_search() [2/2]

bool Gtk::TextIter::forward_search ( const Glib::ustring &  str,
TextSearchFlags  flags,
TextIter match_start,
TextIter match_end,
const TextIterBase limit 
) const

Searches forward for str.

Any match is returned by setting match_start to the first character of the match and match_end to the first character after the match. The search will not continue past limit. Note that a search is a linear or O(n) operation, so you may wish to use limit to avoid locking up your UI on large buffers.

If the Gtk::TextSearchFlags::VISIBLE_ONLY flag is present, the match may have invisible text interspersed in str. i.e. str will be a possibly-noncontiguous subsequence of the matched range. similarly, if you specify Gtk::TextSearchFlags::TEXT_ONLY, the match may have pixbufs or child widgets mixed inside the matched range. If these flags are not given, the match must be exact; the special 0xFFFC character in str will match embedded pixbufs or child widgets.

Parameters
strA search string.
flagsFlags affecting how the search is done.
match_startReturn location for start of match.
match_endReturn location for end of match.
limitBound for the search.
Returns
Whether a match was found.

◆ get_buffer()

Glib::RefPtr<TextBuffer> Gtk::TextIter::get_buffer ( ) const

Returns the Gtk::TextBuffer this iterator is associated with.

Returns
The buffer.

◆ get_child_anchor()

Glib::RefPtr<TextChildAnchor> Gtk::TextIter::get_child_anchor ( ) const

If the location at iter contains a child anchor, the anchor is returned.

Otherwise, nullptr is returned.

Returns
The anchor at iter.

◆ get_marks()

std::vector<Glib::RefPtr<TextMark> > Gtk::TextIter::get_marks ( ) const

Returns a list of all Gtk::TextMark at this location.

Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between iterable locations), multiple marks can exist in the same place.

The returned list is not in any meaningful order.

Returns
List of Gtk::TextMark.

◆ get_paintable()

Glib::RefPtr<Gdk::Paintable> Gtk::TextIter::get_paintable ( ) const

If the element at iter is a paintable, the paintable is returned.

Otherwise, nullptr is returned.

Returns
The paintable at iter.

◆ get_tags()

std::vector<Glib::RefPtr<TextTag> > Gtk::TextIter::get_tags ( ) const

Returns a list of tags that apply to iter, in ascending order of priority (highest-priority tags are last).

Returns
List of Gtk::TextTag.

◆ get_toggled_tags()

std::vector<Glib::RefPtr<TextTag> > Gtk::TextIter::get_toggled_tags ( bool  toggled_on = true) const

Returns a list of Gtk::TextTag that are toggled on or off at this point.

If toggled_on is true, the list contains tags that are toggled on. If a tag is toggled on at iter, then some non-empty range of characters following iter has that tag applied to it. If a tag is toggled off, then some non-empty range following iter does not have the tag applied to it.

Parameters
toggled_ontrue to get toggled-on tags.
Returns
Tags toggled at this point.

◆ operator++() [1/2]

TextIter& Gtk::TextIter::operator++ ( )
inline

Alias for forward_char().

◆ operator++() [2/2]

TextIter Gtk::TextIter::operator++ ( int  )
inline

◆ operator--() [1/2]

TextIter& Gtk::TextIter::operator-- ( )
inline

Alias for backward_char().

◆ operator--() [2/2]

TextIter Gtk::TextIter::operator-- ( int  )
inline

◆ order()

void Gtk::TextIter::order ( TextIter second)

Swaps the value of first and second if second comes before first in the buffer.

That is, ensures that first and second are in sequence. Most text buffer functions that take a range call this automatically on your behalf, so there’s no real reason to call it yourself in those cases. There are some exceptions, such as in_range(), that expect a pre-sorted range.

Parameters
secondAnother Gtk::TextIter.

Friends And Related Function Documentation

◆ wrap_iter() [1/2]

const Gtk::TextIter & wrap_iter ( const GtkTextIter *  object)
related
Parameters
objectThe C instance
Returns
A C++ instance that wraps this C instance.

◆ wrap_iter() [2/2]

Gtk::TextIter & wrap_iter ( GtkTextIter *  object)
related
Parameters
objectThe C instance
Returns
A C++ instance that wraps this C instance.