gtkmm: Gtk::TextIter Class Reference

gtkmm 4.12.0

Public Member Functions | Related Symbols | List of all members
Gtk::TextIter Class Reference
TextView Classes

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

`#include <gtkmm/textiter.h>`

Inheritance diagram for Gtk::TextIter:
[legend]

## Public Member Functions
TextIter & | operator++ ()
| Alias for forward_char().
TextIter | operator++ (int)
TextIter & | operator-- ()
| Alias for backward_char().
TextIter | operator-- (int)
Glib::RefPtr< TextBuffer > | get_buffer () const
| Returns the `Gtk::TextBuffer` this iterator is associated with.
Glib::RefPtr< Gdk::Paintable > | get_paintable () const
| If the element at iter is a paintable, the paintable is returned.
std::vector< Glib::RefPtr< TextMark > > | get_marks () const
| Returns a list of all `Gtk::TextMark` at this location.
Glib::RefPtr< TextChildAnchor > | get_child_anchor () const
| If the location at iter contains a child anchor, the anchor is returned.
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.
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).
bool | forward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end, const TextIterBase & limit) const
| Searches forward for str.
bool | forward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end) const
| A forward_search() convenience overload.
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.
bool | backward_search (const Glib::ustring & str, TextSearchFlags flags, TextIter & match_start, TextIter & match_end) const
| A backward_search() convenience overload.
void | order (TextIter & second)
| Swaps the value of first and second if second comes before first in the buffer.
Public Member Functions inherited from Gtk::TextIterBase
| TextIterBase (const TextIterBase & other) noexcept
TextIterBase & | operator= (const TextIterBase & other) noexcept
| TextIterBase (TextIterBase && other) noexcept
TextIterBase & | operator= (TextIterBase && other) noexcept
| TextIterBase ()
| TextIterBase (const GtkTextIter * gobject)
GtkTextIter * | gobj ()
| Provides access to the underlying C instance.
const GtkTextIter * | gobj () const
| Provides access to the underlying C instance.
value_type | operator* () const
| Alias for get_char().
| operator bool () const
| Alias for !is_end().
int | get_offset () const
| Returns the character offset of an iterator.
int | get_line () const
| Returns the line number containing the iterator.
int | get_line_offset () const
| Returns the character offset of the iterator, counting from the start of a newline-terminated line.
int | get_line_index () const
| Returns the byte index of the iterator, counting from the start of a newline-terminated line.
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.
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.
gunichar | get_char () const
| The Unicode character at this iterator is returned.
Glib::ustring | get_slice (const TextIterBase &end) const
| Returns the text in the given range.
Glib::ustring | get_text (const TextIterBase &end) const
| Returns text in the given range.
Glib::ustring | get_visible_slice (const TextIterBase &end) const
| Returns visible text in the given range.
Glib::ustring | get_visible_text (const TextIterBase &end) const
| Returns visible text in the given range.
bool | starts_tag (const Glib::RefPtr< const TextTag > & tag={}) const
| Returns `true` if tag is toggled on at exactly this point.
bool | ends_tag (const Glib::RefPtr< const TextTag > & tag={}) const
| Returns `true` if tag is toggled off at exactly this point.
bool | toggles_tag (const Glib::RefPtr< const TextTag > & tag={}) const
| Gets whether a range with tag applied to it begins or ends at iter.
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.
bool | editable (bool default_setting=true) const
| Returns whether the character at iter is within an editable region of text.
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.
bool | starts_word () const
| Determines whether iter begins a natural-language word.
bool | ends_word () const
| Determines whether iter ends a natural-language word.
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).
bool | starts_sentence () const
| Determines whether iter begins a sentence.
bool | ends_sentence () const
| Determines whether iter ends a sentence.
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).
bool | starts_line () const
| Returns `true` if iter begins a paragraph.
bool | ends_line () const
| Returns `true` if iter points to the start of the paragraph delimiter characters for a line.
bool | is_cursor_position () const
| Determine if iter is at a cursor position.
int | get_chars_in_line () const
| Returns the number of characters in the line containing iter, including the paragraph delimiters.
int | get_bytes_in_line () const
| Returns the number of bytes in the line containing iter, including the paragraph delimiters.
Pango::Language | get_language () const
| Returns the language in effect at iter.
bool | is_end () const
| Returns `true` if iter is the end iterator.
bool | is_start () const
| Returns `true` if iter is the first iterator in the buffer.
bool | forward_char ()
| Moves iter forward by one character offset.
bool | backward_char ()
| Moves backward by one character offset.
bool | forward_chars (int count)
| Moves count characters if possible.
bool | backward_chars (int count)
| Moves count characters backward, if possible.
bool | forward_line ()
| Moves iter to the start of the next line.
bool | backward_line ()
| Moves iter to the start of the previous line.
bool | forward_lines (int count)
| Moves count lines forward, if possible.
bool | backward_lines (int count)
| Moves count lines backward, if possible.
bool | forward_word_end ()
| Moves forward to the next word end.
bool | backward_word_start ()
| Moves backward to the previous word start.
bool | forward_word_ends (int count)
| Calls forward_word_end() up to count times.
bool | backward_word_starts (int count)
| Calls backward_word_start() up to count times.
bool | forward_visible_line ()
| Moves iter to the start of the next visible line.
bool | backward_visible_line ()
| Moves iter to the start of the previous visible line.
bool | forward_visible_lines (int count)
| Moves count visible lines forward, if possible.
bool | backward_visible_lines (int count)
| Moves count visible lines backward, if possible.
bool | forward_visible_word_end ()
| Moves forward to the next visible word end.
bool | backward_visible_word_start ()
| Moves backward to the previous visible word start.
bool | forward_visible_word_ends (int count)
| Calls forward_visible_word_end() up to count times.
bool | backward_visible_word_starts (int count)
| Calls backward_visible_word_start() up to count times.
bool | forward_sentence_end ()
| Moves forward to the next sentence end.
bool | backward_sentence_start ()
| Moves backward to the previous sentence start.
bool | forward_sentence_ends (int count)
| Calls forward_sentence_end() count times.
bool | backward_sentence_starts (int count)
| Calls backward_sentence_start() up to count times.
bool | forward_cursor_position ()
| Moves iter forward by a single cursor position.
bool | backward_cursor_position ()
| Like forward_cursor_position(), but moves backward.
bool | forward_cursor_positions (int count)
| Moves up to count cursor positions.
bool | backward_cursor_positions (int count)
| Moves up to count cursor positions.
bool | forward_visible_cursor_position ()
| Moves iter forward to the next visible cursor position.
bool | backward_visible_cursor_position ()
| Moves iter backward to the previous visible cursor position.
bool | forward_visible_cursor_positions (int count)
| Moves up to count visible cursor positions.
bool | backward_visible_cursor_positions (int count)
| Moves up to count visible cursor positions.
void | set_offset (int char_offset)
| Sets iter to point to char_offset.
void | set_line (int line_number)
| Moves iterator iter to the start of the line line_number.
void | set_line_offset (int char_on_line)
| Moves iter within a line, to a new character (not byte) offset.
void | set_line_index (int byte_on_line)
| Same as set_line_offset(), but works with a byte index.
void | forward_to_end ()
| Moves iter forward to the “end iterator”, which points one past the last valid character in the buffer.
bool | forward_to_line_end ()
| Moves the iterator to point to the paragraph delimiter characters.
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.
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.
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`.
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`.
bool | forward_find_char (const SlotFindChar & slot, const TextIterBase & limit)
| Advances this iterator, calling slot on each character.
bool | forward_find_char (const SlotFindChar & slot)
| Advances this iterator, calling slot on each character.
bool | backward_find_char (const SlotFindChar & slot, const TextIterBase & limit)
| Same as forward_find_char(const SlotFindChar& slot, const TextIterBase& limit), but goes backward.
bool | backward_find_char (const SlotFindChar & slot)
| Same as forward_find_char(const SlotFindChar& slot), but goes backward.
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.
bool | in_range (const TextIterBase &start, const TextIterBase &end) const
| Checks whether iter falls in the range [ start, end).

## Related Symbols
(Note that these are not member symbols.)
Gtk::TextIter & | wrap_iter (GtkTextIter * object)
const Gtk::TextIter & | wrap_iter (const GtkTextIter * object)
Related Symbols inherited from Gtk::TextIterBase
bool | operator== (const TextIterBase & lhs, const TextIterBase & rhs)
bool | operator!= (const TextIterBase & lhs, const TextIterBase & rhs)
bool | operator< (const TextIterBase & lhs, const TextIterBase & rhs)
bool | operator> (const TextIterBase & lhs, const TextIterBase & rhs)
bool | operator<= (const TextIterBase & lhs, const TextIterBase & rhs)
bool | operator>= (const TextIterBase & lhs, const TextIterBase & rhs)
Gtk::TextIterBase & | wrap (GtkTextIter * object)
const Gtk::TextIterBase & | wrap (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.
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.
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

  str | Search string.
  flags | Bitmask of flags affecting the search.
  match_start | Return location for start of match.
  match_end | Return location for end of match.
  limit | Location 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

  str | A search string.
  flags | Flags affecting how the search is done.
  match_start | Return location for start of match.
  match_end | Return location for end of match.
  limit | Bound 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_on | `true` 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

  second | Another `Gtk::TextIter`.

## Friends And Related Symbol Documentation

## ◆ wrap_iter() [1/2]

const Gtk::TextIter & wrap_iter | ( | const GtkTextIter * | object | ) |
| related

Parameters

  object | The C instance

Returns
  A C++ instance that wraps this C instance.

## ◆ wrap_iter() [2/2]

Gtk::TextIter & wrap_iter | ( | GtkTextIter * | object | ) |
| related

Parameters

  object | The C instance

Returns
  A C++ instance that wraps this C instance.