gtk.TextBuffer
Prev | The gtk Class Reference | Next

## gtk.TextBuffer

gtk.TextBuffer — stores attributed text for display in a `gtk.TextView`

## Synopsis

    class gtk.TextBuffer(gobject.GObject):
        gtk.TextBuffer(table=None)
        def get_line_count()
        def get_char_count()
        def get_tag_table()
        def set_text(text)
        def insert(iter, text)
        def insert_at_cursor(text)
        def insert_interactive(iter, text, default_editable)
        def insert_interactive_at_cursor(text, default_editable)
        def insert_range(iter, start, end)
        def insert_range_interactive(iter, start, end, default_editable)
        def insert_with_tags(iter, text, ...)
        def insert_with_tags_by_name(iter, text, ...)
        def delete(start, end)
        def delete_interactive(start_iter, end_iter, default_editable)
        def get_text(start, end, include_hidden_chars=True)
        def get_slice(start, end, include_hidden_chars=True)
        def insert_pixbuf(iter, pixbuf)
        def insert_child_anchor(iter, anchor)
        def create_child_anchor(iter)
        def create_mark(mark_name, where, left_gravity=False)
        def move_mark(mark, where)
        def delete_mark(mark)
        def get_mark(name)
        def move_mark_by_name(name, where)
        def delete_mark_by_name(name)
        def get_insert()
        def get_selection_bound()
        def place_cursor(where)
        def select_range(ins, bound)
        def apply_tag(tag, start, end)
        def remove_tag(tag, start, end)
        def apply_tag_by_name(name, start, end)
        def remove_tag_by_name(name, start, end)
        def remove_all_tags(start, end)
        def create_tag(tag_name=None, ...)
        def get_iter_at_line_offset(line_number, char_offset)
        def get_iter_at_line_index(line_number, byte_index)
        def get_iter_at_offset(char_offset)
        def get_iter_at_line(line_number)
        def get_start_iter()
        def get_end_iter()
        def get_bounds()
        def get_iter_at_mark(mark)
        def get_iter_at_child_anchor(anchor)
        def get_modified()
        def set_modified(setting)
        def add_selection_clipboard(clipboard)
        def remove_selection_clipboard(clipboard)
        def cut_clipboard(clipboard, default_editable)
        def copy_clipboard(clipboard)
        def paste_clipboard(clipboard, override_location, default_editable)
        def get_selection_bounds()
        def delete_selection(interactive, default_editable)
        def begin_user_action()
        def end_user_action()
        def backspace(iter, interactive, default_editable)
        def get_has_selection()
        def get_copy_target_list()
        def get_paste_target_list()
        def register_serialize_format(mime_type, function, user_data)
        def register_serialize_tagset(tagset_name=NULL)
        def register_deserialize_format(mime_type, function, user_data)
        def register_deserialize_tagset(tagset_name=NULL)
        def unregister_serialize_format(format)
        def unregister_deserialize_format(format)
        def deserialize_set_can_create_tags(format, can_create_tags)
        def deserialize_get_can_create_tags(format)
        def get_serialize_formats()
        def get_deserialize_formats()
        def serialize(content_buffer, format, start, end)
        def deserialize(content_buffer, format, iter, data)

## Ancestry

    +-- gobject.GObject
      +-- gtk.TextBuffer

## gtk.TextBuffer Properties

"copy-target-list" | Read | The list of targets this buffer supports for clipboard copying and as DND source. This property is available in GTK+ 2.10 and above.
"cursor-position" | Read | The position of the insert mark (as offset from the beginning of the buffer). It is useful for getting notified when the cursor moves. Allowed values: >= 0. Default value: 0. This property is available in GTK+ 2.10 and above.
"has-selection" | Read | If `True` the buffer has some text currently selected. Default value: `False`. This property is available in GTK+ 2.10 and above.
"paste-target-list" | Read | The list of targets this buffer supports for clipboard pasting and as DND destination. This property is available in GTK+ 2.10 and above.
"tag-table" | Read-Write-Construct Only | The `gtk.TextTagTable` associated with the textbuffer. Available in GTK+ 2.2 and above.
"text" | Read-Write | The text content of the buffer. Without child widgets and images, see the `gtk.TextBuffer.get_text()` method for more information. Default value: "". This property is available in GTK+ 2.8 and above.

## Attributes

"tag_table" | Read | The `gtk.TextTagTable` associated with the textbuffer.

## gtk.TextBuffer Signal Prototypes

gobject.GObject Signal Prototypes

"apply-tag" | `def callback(`textbuffer`, `texttag`, `start`, `end`, `user_param1`, `...`)`
"begin-user-action" | `def callback(`textbuffer`, `user_param1`, `...`)`
"changed" | `def callback(`textbuffer`, `user_param1`, `...`)`
"delete-range" | `def callback(`textbuffer`, `start`, `end`, `user_param1`, `...`)`
"end-user-action" | `def callback(`textbuffer`, `user_param1`, `...`)`
"insert-child-anchor" | `def callback(`textbuffer`, `iter`, `anchor`, `user_param1`, `...`)`
"insert-pixbuf" | `def callback(`textbuffer`, `iter`, `pixbuf`, `user_param1`, `...`)`
"insert-text" | `def callback(`textbuffer`, `iter`, `text`, `length`, `user_param1`, `...`)`
"mark-deleted" | `def callback(`textbuffer`, `textmark`, `user_param1`, `...`)`
"mark-set" | `def callback(`textbuffer`, `iter`, `textmark`, `user_param1`, `...`)`
"modified-changed" | `def callback(`textbuffer`, `user_param1`, `...`)`
"remove-tag" | `def callback(`textbuffer`, `texttag`, `start`, `end`, `user_param1`, `...`)`

## Description

A `gtk.TextBuffer` is the core component of the PyGTK text editing system. A `gtk.TextBuffer` contains the text, pixbufs and child widget anchors that are displayed in one or more `gtk.TextView` widgets. A `gtk.TextBuffer` has an associated `gtk.TextTagTable` that contains the `gtk.TextTag` objects that can be used to set attributes on the text in the textbuffer.

A `gtk.TextBuffer` can be automatically created when creating a `gtk.TextView` or it can be created with the gtk.TextBuffer() constructor and associated with a `gtk.TextView` using the `set_buffer`() method or the gtk.TextView() constructor.

## Constructor

        gtk.TextBuffer(table=None)

`table` : | a tag table, or None to create a new one
Returns : | a new text buffer object

Creates a new `gtk.TextBuffer` object.

## Methods

### gtk.TextBuffer.get_line_count

        def get_line_count()

Returns : | the number of lines in the buffer

The `get_line_count`() method returns the number of lines in the buffer. This value is cached, so the function is very fast.

### gtk.TextBuffer.get_char_count

        def get_char_count()

Returns : | the number of characters in the buffer

The `get_char_count`() method returns 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.

### gtk.TextBuffer.get_tag_table

        def get_tag_table()

Returns : | the buffer's tag table

The `get_tag_table`() method returns the `gtk.TextTagTable` object associated with the textbuffer.

### gtk.TextBuffer.set_text

        def set_text(text)

`text` : | UTF-8 text to insert

The `set_text`() method replaces the current contents of the textbuffer with the contents of `text`. `text` must be valid UTF-8.

### gtk.TextBuffer.insert

        def insert(iter, text)

`iter` : | a `gtk.TextIter` specifying a position in the buffer
`text` : | UTF-8 format text to insert

The `insert`() method inserts the contents of `text` into the textbuffer at the position specified by `iter`. The "insert_text" signal is emitted and the text insertion actually occurs in the default handler for the signal. `iter` is invalidated when insertion occurs (because the buffer contents change), but the default signal handler revalidates it to point to the end of the inserted text.

### gtk.TextBuffer.insert_at_cursor

        def insert_at_cursor(text)

`text` : | some text in UTF-8 format

The `insert_at_cursor`() method is a convenience method that calls the `insert`() method, using the current cursor position as the insertion point.

### gtk.TextBuffer.insert_interactive

        def insert_interactive(iter, text, default_editable)

`iter` : | a `gtk.TextIter` specifying a position in `buffer`
`text` : | some UTF-8 text
`default_editable` : | default editability of buffer
Returns : | `True` if the text was actually inserted

The `insert_interactive`() method is similar to the `insert`() method, except the insertion of `text` at `iter` will not occur if `iter` is at a non-editable location in the buffer. A location is non-editable if a `gtk.TextTag` applied at that location has its "editable" attribute set to `False` or the `gtk.TextView` used by the user is set non-editable. Usually you want to prevent insertions at locations if the insertion results from a user action (is interactive).

`default_editable` indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of the `gtk.TextView.get_editable`() method is appropriate here.

### gtk.TextBuffer.insert_interactive_at_cursor

        def insert_interactive_at_cursor(text, default_editable)

`text` : | text in UTF-8 format
`default_editable` : | default editability of buffer
Returns : | `True` if the text was actually inserted

The `insert_interactive_at_cursor`() method calls the `insert_interactive`() method to insert `text` at the cursor (insert) position. `default_editable` indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of the `gtk.TextView.get_editable`() method is appropriate here.

### gtk.TextBuffer.insert_range

        def insert_range(iter, start, end)

`iter` : | a `gtk.TextIter` specifying a position in the textbuffer
`start` : | a `gtk.TextIter` specifying a position in a (possibly different) `gtk.TextBuffer`
`end` : | a `gtk.TextIter` specifying another position in the same buffer as `start`

The `insert_range`() method copies text, tags, and pixbufs (but not child anchors) between `start` and `end` (the order of `start` and `end` doesn't matter) form a `gtk.TextBuffer` and inserts the copy at `iter`. Used instead of simply getting/inserting text because it preserves images and tags. If `start` and `end` are in a different buffer from `buffer`, the two buffers must share the same tag table. This method is implemented via emissions of the "insert_text" and "apply_tag" signals.

### gtk.TextBuffer.insert_range_interactive

        def insert_range_interactive(iter, start, end, default_editable)

`iter` : | a `gtk.TextIter` specifying a position in the textbuffer
`start` : | a `gtk.TextIter` specifying a position in a (possibly different) `gtk.TextBuffer`
`end` : | a `gtk.TextIter` specifying another position in the same buffer as `start`
`default_editable` : | default editability of the buffer
Returns : | `True` if an insertion was possible at `iter`

The `insert_range_interactive`() method is similar to the `insert_range`() method, except the insertion of `text` at `iter` will not occur if the insertion position is non-editable. A location is non-editable if a `gtk.TextTag` applied at that location has its "editable" attribute set to `False` or the `gtk.TextView` used by the user is set non-editable. The `default_editable` parameter indicates whether the text is editable at `iter` if no tags enclosing `iter` affect editability. Typically the result of the `gtk.TextView.get_editable`() method is appropriate here.

### gtk.TextBuffer.insert_with_tags

        def insert_with_tags(iter, text, ...)

`iter` : | a `gtk.TextIter` specifying a position in `buffer`
`text` : | UTF-8 text
`...` : | one or more optional `gtk.TextTag` objects to apply to `text`

The `insert_with_tags`() method inserts the specified `text` into the textbuffer at the location specified by `iter`, applying any optional tags following the first two parameters to the newly-inserted text. This method is a convenience method that is equivalent to calling the `insert`() method, then the `apply_tag`() method on the inserted text.

### gtk.TextBuffer.insert_with_tags_by_name

        def insert_with_tags_by_name(iter, text, ...)

`iter` : | a `gtk.TextIter` specifying a position in `buffer`
`text` : | UTF-8 text
`...` : | one or more optional `gtk.TextTag` names to apply to `text`

The `insert_with_tags_by_name`() method is similar to the `insert_with_tags`() method, but uses tag names instead of tag objects.

### gtk.TextBuffer.delete

        def delete(start, end)

`start` : | a `gtk.TextIter` specifying a position in the textbuffer
`end` : | a `gtk.TextIter` specifying another position in the textbuffer

The `delete`() method deletes the text between `start` and `end`. The order of `start` and `end` is not actually relevant as the `delete`() method will reorder them. This method emits the "delete_range" signal, and the default handler of that signal deletes the text. Because the textbuffer is modified, all outstanding iterators become invalid after calling this function; however, `start` and `end` will be re-initialized to point to the location where text was deleted.

### gtk.TextBuffer.delete_interactive

        def delete_interactive(start_iter, end_iter, default_editable)

`start_iter` : | a `gtk.TextIter` specifying the start of the text to delete
`end_iter` : | a `gtk.TextIter` specifying the end of the text to delete
`default_editable` : | whether the buffer is editable by default
Returns : | `True` if some text was actually deleted

The `delete_interactive`() method deletes all editable text in the given range. This method calls the `delete`() method for each editable sub-range of [`start`,`end`). `start` and `end` are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. A range of `text` is non-editable if a `gtk.TextTag` applied to that range has its "editable" attribute set to `False` or the `gtk.TextView` used by the user is set non-editable. The `default_editable` parameter indicates whether `text` is editable if no tags enclosing any part of `text` affect editability. Typically the result of the `gtk.TextView.get_editable`() method is appropriate here.

### gtk.TextBuffer.get_text

        def get_text(start, end, include_hidden_chars=True)

`start` : | a `gtk.TextIter` specifying the start of a range
`end` : | a `gtk.TextIter` specifying the end of a range
`include_hidden_chars` : | if `True` include invisible text
Returns : | the text in the range

The `get_text`() method returns the text in the specified range [`start`,`end`). Undisplayed text (text marked with tags that set the invisibility attribute) are excluded if `include_hidden_chars` is `False`. `get_text`() does not return characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the buffer. Contrast this behavior with the `get_slice`() method.

### gtk.TextBuffer.get_slice

        def get_slice(start, end, include_hidden_chars)

`start` : | a `gtk.TextIter` specifying the start of a range
`end` : | a `gtk.TextIter` specifying the end of a range
`include_hidden_chars` : | if `True` include invisible text
Returns : | the contents of the range including text and indicators for pixbufs and child anchors

The `get_slice`() method returns the text in the range [`start`,`end`). Undisplayed text (text marked with tags that set the invisibility attribute) is excluded if `include_hidden_chars` is `False`. The returned string includes a 0xFFFC character whenever the textbuffer contains embedded images or child anchors, so byte and character indexes into the returned string do correspond to byte and character indexes into the buffer. Contrast this behavior with the `get_text`() method. 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.

### gtk.TextBuffer.insert_pixbuf

        def insert_pixbuf(iter, pixbuf)

`iter` : | a `gtk.TextIter` specifying the location to insert the pixbuf
`pixbuf` : | a `gtk.gdk.Pixbuf`

The `insert_pixbuf`() method inserts an image specified by `pixbuf` into the text buffer at the location specified by `iter`. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode "object replacement character" 0xFFFC. Note that the "slice" variants for obtaining portions of the buffer as a string include this character for pixbufs, but the "text" variants do not. e.g. see the `get_slice`() and `get_text`() methods.

### gtk.TextBuffer.insert_child_anchor

        def insert_child_anchor(iter, anchor)

`iter` : | a `gtk.TextIter` specifying the location to insert the anchor
`anchor` : | a `gtk.TextChildAnchor`

The `insert_child_anchor`() method inserts a child widget anchor specified by `anchor` into the textbuffer at the location specified by `iter`. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode "object replacement character" 0xFFFC. Note that the "slice" variants for obtaining portions of the buffer as a string include this character for child anchors, but the "text" variants do not. e.g. see the `get_slice`() and `get_text`() methods. The `create_child_anchor`() is a more convenient alternative to this function.

### gtk.TextBuffer.create_child_anchor

        def create_child_anchor(iter)

`iter` : | a `gtk.TextIter` specifying a location in the buffer
Returns : | the new child anchor

The `create_child_anchor`() method is a convenience function that creates a child anchor with the gtk.TextChildAnchor() constructor and inserts it into the textbuffer at the location specified by `iter` with the `insert_child_anchor`() method.

### gtk.TextBuffer.create_mark

        def create_mark(mark_name, where, left_gravity)

`mark_name` : | the name for the new mark, or `None`
`where` : | a `gtk.TextIter` specifying the location to place the mark
`left_gravity` : | if `True` the mark has left gravity
Returns : | the new `gtk.TextMark` object

The `create_mark`() method creates a mark with the name specified by `mark_name` at the position specified by `where` and left gravity specified by `left_gravity`. If `mark_name` is `None`, the mark is anonymous; otherwise, the mark can be retrieved by name using the `get_mark`() method. 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 (`left_gravity` = `False`), 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). Marks are owned by the buffer and go away when the buffer does. This method emits the "mark_set" signal as notification of the mark's initial placement.

### gtk.TextBuffer.move_mark

        def move_mark(mark, where)

`mark` : | a `gtk.TextMark`
`where` : | a `gtk.TextIter` specifying a new location for `mark`

The `move_mark`() method moves the `gtk.TextMark` specified by `mark` to the new location specified by `where`.This method emits the "mark_set" signal as notification of the move.

### gtk.TextBuffer.delete_mark

        def delete_mark(mark)

`mark` : | a `gtk.TextMark` in the textbuffer

The `delete_mark`() method deletes the `gtk.TextMark` specified by `mark`, so that it's no longer located anywhere in the textbuffer. Most operations on `mark` become invalid and there is no way to undelete a mark. The `get_deleted`() method will return `True` after this method has been called on a mark to indicate that a mark no longer belongs to a textbuffer. The "mark_deleted" signal will be emitted as notification after the mark is deleted.

### gtk.TextBuffer.get_mark

        def get_mark(name)

`name` : | a mark name
Returns : | a `gtk.TextMark`, or None

The get_mark() method returns the mark named `name` in the textbuffer, or `None` if no such mark exists in the buffer.

### gtk.TextBuffer.move_mark_by_name

        def move_mark_by_name(name, where)

`name` : | the name of a mark
`where` : | a `gtk.TextIter` specifying the new location for mark

The `move_mark_by_name`() method moves the mark named `name` (which must exist) to the textbuffer location specified by `where`. See the `move_mark`() method for details.

### gtk.TextBuffer.delete_mark_by_name

        def delete_mark_by_name(name)

`name` : | the name of a mark in `buffer`

The `delete_mark_by_name`() method deletes the mark (which must exist) named `name`. See the `delete_mark`() for details.

### gtk.TextBuffer.get_insert

        def get_insert()

Returns : | the insertion point mark

The `get_insert`() method returns the mark that represents the cursor (insertion point). Equivalent to calling the `get_mark`() method to get the mark named "insert", but very slightly more efficient, and involving less typing.

### gtk.TextBuffer.get_selection_bound

        def get_selection_bound()

Returns : | the selection bound mark

The `get_selection_bound`() method returns the mark that represents the selection bound. Equivalent to calling the `get_mark`() method to get the mark named "selection_bound", but very slightly more efficient, and involving less typing. The currently-selected text in a textbuffer 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. The `get_selection_bounds`() method is a convenience method for handling the selection, if you just want to know whether there's a selection and what its bounds are.

### gtk.TextBuffer.place_cursor

        def place_cursor(where)

`where` : | a `gtk.TextIter` specifying where to put the cursor

The `place_cursor`() method moves the "insert" and "selection_bound" marks simultaneously to the location specified by `where`. If you move them to the same place in two steps with the `move_mark`() method, you will temporarily select a region in between their old and new locations, which is inefficient. This method moves them as a unit, which can be optimized.

### gtk.TextBuffer.select_range

        def select_range(ins, bound)

`ins` : | a `gtk.TextIter` specifying where to put the "insert" mark
`bound` : | a `gtk.TextIter` specifying where to put the "selection_bound" mark

### Note

This method is available in PyGTK 2.4 and above.

The `select_range`() method moves the "insert" and "selection_bound" marks simultaneously to the locations specified by `ins` and `bound` respectively. If you move them to the same place in two steps with the `move_mark`() method, you will temporarily select a region in between their old and new locations, which is inefficient. This method moves them as a unit, which can be optimized.

### gtk.TextBuffer.apply_tag

        def apply_tag(tag, start, end)

`tag` : | a `gtk.TextTag`
`start` : | a `gtk.TextIter` specifying the start of the range
`end` : | a `gtk.TextIter` specifying the end of the range

The `apply_tag`() method emits the "apply-tag" signal that causes the `gtk.TextTag` specified by `tag` to be applied to the range of text between `start` and `end` by the default signal handler. `start` and `end` do not have to be in order.

### gtk.TextBuffer.remove_tag

        def remove_tag(tag, start, end)

`tag` : | a `gtk.TextTag`
`start` : | a `gtk.TextIter` specifying the start of the range
`end` : | a `gtk.TextIter` specifying the end of the range

The `delete_tag`() method emits the "remove_tag" signal that causes the default handler for the signal to remove all occurrences of the `gtk.TextTag` specified by `tag` from the text in the range between `start` and `end`. `start` and `end` don't have to be in order.

### gtk.TextBuffer.apply_tag_by_name

        def apply_tag_by_name(name, start, end)

`name` : | the name of a `gtk.TextTag`
`start` : | a `gtk.TextIter` specifying the start of the range
`end` : | a `gtk.TextIter` specifying the end of the range

The `apply_tag_by_name`() method calls the `gtk.TextTagTable.lookup`() method on the textbuffer's tag table to find the `gtk.TextTag` with the specified `name`, then calls the `apply_tag`() method to apply that tag to the text in the range between `start` and `end`. `start` and `end` don't have to be in order.

### gtk.TextBuffer.remove_tag_by_name

        def remove_tag_by_name(name, start, end)

`name` : | the name of a `gtk.TextTag`
`start` : | a `gtk.TextIter` specifying the start of the range
`end` : | a `gtk.TextIter` specifying the end of the range

The `delete_tag_by_name`() method calls the `gtk.TextTagTable.lookup`() method on the textbuffer's tag table to find the `gtk.TextTag`, then calls the `remove_tag`() method to remove that that tag from the text in the range between `start` and `end`. `start` and `end` don't have to be in order.

### gtk.TextBuffer.remove_all_tags

        def remove_all_tags(start, end)

`start` : | a `gtk.TextIter` specifying the start of the range
`end` : | a `gtk.TextIter` specifying the end of the range

The `remove_all_tags`() method removes all tags in the text in the range between `start` and `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. `start` and `end` don't have to be in order.

### gtk.TextBuffer.create_tag

        def create_tag(tag_name=None, ...)

`tag_name` : | the name of the new tag, or `None` if the tag is anonymous
`...` : | one or more property_name= value pairs
Returns : | a new tag

The `create_tag`() method creates a tag with the name specified by `tag_name` and adds it to the tag table for the textbuffer. If one or more `property_name=value` pairs are available they are used to set the properties of the tag. Note the `property_name` must be specified using underscores instead of dashes e.g. use pixels_above_lines=10 instead of pixels-above-lines=10. This method is equivalent to calling the gtk.TextTag() constructor and then adding the tag to the buffer's tag table with the `gtk.TextTagTable.add`() method. If `tag_name` is `None`, the tag is anonymous. If `tag_name` is non-`None`, a tag called `tag_name` must not already exist in the tag table for this buffer.

### gtk.TextBuffer.get_iter_at_line_offset

        def get_iter_at_line_offset(line_number, char_offset)

`line_number` : | the line number counting from 0
`char_offset` : | the char offset from start of line
Returns : | a `gtk.TextIter`

The`get_iter_at_line_offset`() returns an iterator pointing to the position specified by `char_offset` within the line specified by `line_number`. The `char_offset` must exist, offsets off the end of the line are not allowed. Note specify characters, not bytes; UTF-8 may encode one character as multiple bytes.

### gtk.TextBuffer.get_iter_at_line_index

        def get_iter_at_line_index(line_number, byte_index)

`line_number` : | the line number counting from 0
`byte_index` : | the byte index from start of line
Returns : | a `gtk.TextIter`

The `get_iter_at_line_index`() method returns an iterator pointing to the position specified by `byte_index` within the line specified by `line_number`. `byte_index` must be the start of a UTF-8 character, and must not be beyond the end of the line. Note specify bytes, not characters; UTF-8 may encode one character as multiple bytes.

### gtk.TextBuffer.get_iter_at_offset

        def get_iter_at_offset(char_offset)

`char_offset` : | the char offset from start of buffer, counting from 0
Returns : | a `gtk.TextIter`

The `get_iter_at_offset`() method returns an iterator pointing to the location specified by `char_offset` characters from the start of the entire buffer.

### gtk.TextBuffer.get_iter_at_line

        def get_iter_at_line(line_number)

`line_number` : | line number counting from 0
Returns : | a `gtk.TextIter`

The `get_iter_at_line`() method returns an iterator pointing to the start of the line specified by `line_number`.

### gtk.TextBuffer.get_start_iter

        def get_start_iter()

Returns : | a `gtk.TextIter`

The `get_start_iter`() method returns an iterator pointing at the location of the first position in the text buffer. This is the same as using the `get_iter_at_offset`() with an argument of 0.

### gtk.TextBuffer.get_end_iter

        def get_end_iter()

Returns : | a `gtk.TextIter`

The `get_end_iter`() method returns an iterator pointing at the "end iterator," one past the last valid character in the text buffer. If passed to the `gtk.TextIter.get_char`() method, the end iterator has a character value of 0. The entire buffer lies in the range from the first position in the buffer (call the `get_start_iter`() method to get character position 0) to the end iterator.

### gtk.TextBuffer.get_bounds

        def get_bounds()

Returns : | a tuple containing `gtk.TextIter` objects that point at the first and last positions in the buffer

The `get_bounds`() method returns a tuple containing the first and last iterators in the buffer, i.e. the entire buffer lies within the range.

### gtk.TextBuffer.get_iter_at_mark

        def get_iter_at_mark(mark)

`mark` : | a `gtk.TextMark` in the textbuffer
Returns : | a `gtk.TextIter`

The `get_iter_at_mark`() method returns an iterator that points at the current position of `mark`.

### gtk.TextBuffer.get_iter_at_child_anchor

        def get_iter_at_child_anchor(iter, anchor)

`anchor` : | a child anchor that appears in the textbuffer
Returns : | a `gtk.TextIter`

The `get_iter_at_child_anchor`() method returns an iterator that points at the location of `anchor` within the textbuffer.

### gtk.TextBuffer.get_modified

        def get_modified()

Returns : | `True` if the buffer has been modified

The `get_modified`() method returns `True` if the buffer has been modified since the last call to the `set_modified`() method set the modification flag to `False`. Used for example to enable a "save" function in a text editor.

### gtk.TextBuffer.set_modified

        def set_modified(setting)

`setting` : | the modification flag setting

The `set_modified`() method sets the modification flag of the textbuffer to the value specified by `setting`. The modification flag is 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 this method with a `setting` of `False`. When the buffer is modified, it will automatically set the modification flag to `True` and emit a "modified_changed" signal.

### gtk.TextBuffer.add_selection_clipboard

        def add_selection_clipboard(clipboard)

`clipboard` : | a `gtk.Clipboard`

### Note

This method is available in PyGTK 2.2 and above.

The `add_selection_clipboard`() method adds the `gtk.Clipboard` specified by `clipboard` to the list of clipboards in which the selection contents of the buffer are available. In most cases, `clipboard` will be the `gtk.gdk.SELECTION_PRIMARY` clipboard

### gtk.TextBuffer.remove_selection_clipboard

        def remove_selection_clipboard(clipboard)

`clipboard` : | a `gtk.Clipboard` added to the buffer by the `add_selection_clipboard()` method.

### Note

This method is available in PyGTK 2.2 and above.

The `remove_selection_clipboard`() method removes the `gtk.Clipboard` added with the `add_selection_clipboard`() method.

### gtk.TextBuffer.cut_clipboard

        def cut_clipboard(clipboard, default_editable)

`clipboard` : | the `gtk.Clipboard` object to cut to.
`default_editable` : | the default editability of the buffer

### Note

This method is available in PyGTK 2.2 and above.

The `cut_clipboard`() method copies the currently-selected text to the `gtk.Clipboard` specified by `clipboard`, then deletes said text if it's editable as specified by `default_editable`. Typically the result of the `gtk.TextView.get_editable`() method is appropriate here.

### gtk.TextBuffer.copy_clipboard

        def copy_clipboard(clipboard)

`clipboard` : | the `gtk.Clipboard` object to copy to.

### Note

This method is available in PyGTK 2.2 and above.

The `copy_clipboard`() method copies the currently-selected text to the `gtk.ClipBoard` specified by `clipboard`.

### gtk.TextBuffer.paste_clipboard

        def paste_clipboard(clipboard, override_location, default_editable)

`clipboard` : | the `gtk.Clipboard` to paste from
`override_location` : | the `gtk.TextIter` specifying the location to insert pasted text, or `None` for at the cursor
`default_editable` : | the default editability of the buffer

### Note

This method is available in PyGTK 2.2 and above.

The `paste_clipboard`() method pastes the contents of the `gtk.ClipBoard` specified by `clipboard` at the insertion point, or at the location specified by `override_location` (if not `None`). (Note: pasting is asynchronous, that is, we'll ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted.)

### gtk.TextBuffer.get_selection_bounds

        def get_selection_bounds()

Returns : | a tuple containing `gtk.TextIter` objects pointing to the selection start and end or an empty tuple if there is no selection

The `get_selection_bounds`() method returns a tuple containing iterators that point at the start and end of the selection, if any. If there is no selection an empty tuple is returned.

### gtk.TextBuffer.delete_selection

        def delete_selection(interactive, default_editable)

`interactive` : | if `True` the deletion is caused by user interaction
`default_editable` : | if `True` the buffer is editable by default
Returns : | `True` if there was a non-empty selection to delete

The `delete_selection`() method deletes the text in the range between the "insert" and "selection_bound" marks, i.e. the currently-selected text. If `interactive` is `True`, the editability of the selection will be considered (users can't delete uneditable text) and default_editable is used to determine the default editability of the textbuffer usually as a result of a call to the `gtk.TextView.get_editable`() method.

### gtk.TextBuffer.begin_user_action

        def begin_user_action()

The `begin_user_action`() method is called to indicate that the textbuffer operations until a call to the `end_user_action`() method are part of a single user-visible operation. The operations between the `begin_user_action`() and `end_user_action`() methods can then be grouped when creating an undo stack. `gtk.TextBuffer` maintains a count of calls to the `begin_user_action`() method that have not been closed with a call to the `end_user_action`() method, and emits the "begin_user_action" and "end_user_action" signals only for the outermost pair of calls. This allows you to chain user actions.

The "interactive" textbuffer mutation methods, such as the `insert_interactive`() method, automatically call the begin and end user action methods around the textbuffer 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 methods.

### gtk.TextBuffer.end_user_action

        def end_user_action()

The `end_user_action`() method should be paired with a call to the `begin_user_action`() method.

### gtk.TextBuffer.backspace

        def backspace(iter, interactive, default_editable)

`iter` : | a `gtk.TextIter`
`interactive` : | if `True` the deletion is caused by user interaction
`default_editable` : | if `True` the buffer is editable by default
Returns : | `True` if the buffer was modified

### Note

This method is available in PyGTK 2.6 and above.

The `backspace`() method performs the appropriate action as if the user hit the delete key with the cursor at the position specified by `iter`. In the normal case a single character will be deleted, but when combining accents are involved, more than one character can be deleted, and when precomposed character and accent combinations are involved, less than one character will be deleted.

Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, `iter` will be re-initialized to point to the location where text was deleted.

### gtk.TextBuffer.get_has_selection

        def get_has_selection()

Returns : | `True` if there is text selected

### Note

This method is available in PyGTK 2.10 and above.

Indicates whether the buffer has some text currently selected.

### gtk.TextBuffer.get_copy_target_list

        def get_copy_target_list()

Returns : | a list of the targets each represented as a 3-tuple containing the target name, a combination of the GTK Target Flags Constants and an application assigned integer

### Note

This method is available in PyGTK 2.10 and above.

This method returns the list of targets this text buffer can provide for copying and as DND source. The targets in the list are added with `info` values from the GTK TextBuffer Target Info Constants, using the `gtk.target_list_add_rich_text_targets`() and `gtk.target_list_add_text_targets`() functions.

### gtk.TextBuffer.get_paste_target_list

        def get_paste_target_list()

Returns : | a list of the targets each represented as a 3-tuple containing the target name, a combination of the GTK Target Flags Constants and an application assigned integer

### Note

This method is available in PyGTK 2.10 and above.

This method returns the list of targets this text buffer supports for pasting and as DND destination. The targets in the list are added with `info` values from the GTK TextBuffer Target Info Constants, using the `gtk.target_list_add_rich_text_targets`() and `gtk.target_list_add_text_targets`() functions.

### gtk.TextBuffer.register_serialize_format

        def register_serialize_format(mime_type, function, user_data)

`mime_type` : | the format's mime-type
`function` : | the serialize function to register
`user_data` : | `function`'s user_data
Returns : | the newly registered format's mime-type.

### Note

This method is available in PyGTK 2.10 and above.

This method registers a rich text serialization `function` along with its `mime_type` with the passed `buffer`.

The signature of function is:

      def function(register_buf, content_buf, start, end, data):

where `register_buf` is the textbuffer that the format is registered with, `content_buf` is the textbuffer containing the text to be serialized, `start` and `end` are textiters bounding the text to be serialized and `data` is `user_data`. `function` should return the serialized data.

### gtk.TextBuffer.register_serialize_tagset

        def register_serialize_tagset(tagset_name=NULL)

`tagset_name` : | an optional tagset name, or `None`
Returns : | the newly registered format's mime-type.

### Note

This method is available in PyGTK 2.10 and above.

This method registers GTK+'s internal rich text serialization format with this textbuffer. The internal format does not comply to any standard rich text format and only works between `gtk.TextBuffer` instances. It is capable of serializing all of a text buffer's tags and embedded pixbufs.

This method is just a wrapper around `gtk.TextBuffer.register_serialize_format()`. The `mime_type` used for registering is "application/x-gtk-text-buffer-rich-text", or "application/x-gtk-text-buffer-rich-text;format=`tagset_name`" if a `tagset_name` was passed.

The `tagset_name` can be used to restrict the transfer of rich text to buffers with compatible sets of tags, in order to avoid unknown tags from being pasted. It is probably the common case to pass a non-`None` tagset here, since the `None` tagset requires the receiving buffer to deal with with pasting of arbitrary tags.

### gtk.TextBuffer.register_deserialize_format

        def register_deserialize_format(mime_type, function, user_data)

`mime_type` : | the format's mime-type
`function` : | the deserialize function to register
`user_data` : | `function`'s user_data
Returns : | the newly registered format's mime-type.

### Note

This method is available in PyGTK 2.10 and above.

This method registers a rich text deserialization `function` along with its `mime_type` with the passed `buffer`.

The signature of function is:

      def function(register_buf, content_buf, iter, data, create_tags, udata):

where `register_buf` is the textbuffer that the format is registered with, `content_buf` is the textbuffer that data will be deserialized into, `iter` is a textiter indicating the start of the deserialized data in `content_buf`, create_tags is a boolean indicating if tags should be created during deserializtion and `udata` is `user_data`. `function` should return `True` if the data was successfully deserialized.

### gtk.TextBuffer.register_deserialize_tagset

        def register_deserialize_tagset(tagset_name=NULL)

`tagset_name` : | an optional tagset name, or `None`
Returns : | the newly registered format's mime-type.

### Note

This method is available in PyGTK 2.10 and above.

This method registers GTK+'s internal rich text serialization format with this buffer. See the `gtk.TextBuffer.register_serialize_tagset()` method for details.

### gtk.TextBuffer.unregister_serialize_format

        def unregister_serialize_format(format)

`format` : | a target string representing a registered rich text format.

### Note

This method is available in PyGTK 2.10 and above.

This method unregisters a rich text format that was previously registered using the `gtk.TextBuffer.register_serialize_format()` or `gtk.TextBuffer.register_serialize_tagset()` methods.

### gtk.TextBuffer.unregister_deserialize_format

        def unregister_deserialize_format(format)

`format` : | a target string representing a registered rich text format.

### Note

This method is available in PyGTK 2.10 and above.

This method unregisters a rich text format that was previously registered using the `gtk.TextBuffer.register_deserialize_format()` or `gtk.TextBuffer.register_deserialize_tagset()` methods.

### gtk.TextBuffer.deserialize_set_can_create_tags

        def deserialize_set_can_create_tags(format, can_create_tags)

`format` : | a target string representing a registered rich text format
`can_create_tags` : | if `True` deserializing `format` may create tags

### Note

This method is available in PyGTK 2.10 and above.

Use this method to allow a rich text deserialization function to create new tags in the receiving buffer. Note that using this method is almost always a bad idea, because the rich text functions you register should know how to map the rich text format they handle to your text buffers set of tags.

The ability of creating new (arbitrary!) tags in the receiving buffer is meant for special rich text formats like the internal one that is registered using `gtk.TextBuffer.register_deserialize_tagset()`, because that format is essentially a dump of the internal structure of the source buffer, including its tag names.

You should allow creation of tags only if you know what you are doing, e.g. if you defined a tagset name for your application suite's text buffers and you know that it's fine to receive new tags from these buffers, because you know that your application can handle the newly created tags.

### gtk.TextBuffer.deserialize_get_can_create_tags

        def deserialize_get_can_create_tags(format)

`format` : | a target string representing a registered rich text format
Returns : | `True` if deserializing `format` may create tags

### Note

This method is available in PyGTK 2.10 and above.

This method returns the value set with the `gtk.TextBuffer.deserialize_set_can_create_tags()` method.

### gtk.TextBuffer.get_serialize_formats

        def get_serialize_formats()

Returns : | a list of target strings representing the registered formats.

### Note

This method is available in PyGTK 2.10 and above.

This method returns a list of the rich text serialize formats registered using the `gtk.TextBuffer.register_serialize_format()` or `gtk.TextBuffer.register_serialize_tagset()` methods.

### gtk.TextBuffer.get_deserialize_formats

        def get_deserialize_formats()

Returns : | a list of target strings representing the registered formats.

### Note

This method is available in PyGTK 2.10 and above.

This method returns the rich text deserialize formats registered using the `gtk.TextBuffer.register_deserialize_format()` or `gtk.TextBuffer.register_deserialize_tagset()` methods.

### gtk.TextBuffer.serialize

        def serialize(content_buffer, format, start, end)

`content_buffer` : | the `gtk.TextBuffer` to serialize
`format` : | the rich text format to use for serializing
`start` : | start of block of text to serialize
`end` : | end of block of test to serialize
Returns : | the serialized data, encoded as `format`

### Note

This method is available in PyGTK 2.10 and above.

This method serializes the portion of text between `start` and `end` in the rich text format represented by `format`.

The formats to be used must be registered using the `gtk.TextBuffer.register_serialize_format()` or `gtk.TextBuffer.register_serialize_tagset()` methods beforehand.

### gtk.TextBuffer.deserialize

        def deserialize(content_buffer, format, iter, data)

`content_buffer` : | the `gtk.TextBuffer` to deserialize into
`format` : | the rich text format to use for deserializing
`iter` : | insertion point for the deserialized text
`data` : | data to deserialize
Returns : | `True` on success, `False` otherwise.

### Note

This method is available in PyGTK 2.10 and above.

This method deserializes rich text in format `format` and inserts it at `iter` in `content_buffer`.

The formats to be used must be registered using the `gtk.TextBuffer.register_deserialize_format()` or `gtk.TextBuffer.register_deserialize_tagset()` methods beforehand.

## Signals

### The "apply-tag" gtk.TextBuffer Signal

        def callback(textbuffer, texttag, start, end, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`texttag` : | the `gtk.TextTag` being applied
`start` : | a `gtk.TextIter` pointing to the start of the range of text
`end` : | a `gtk.TextIter` pointing to the end of the range of text
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "apply-tag" signal is emitted when `texttag` is applied to the text in `textbuffer` in the range specified by `start` and `end`.

### The "begin-user-action" gtk.TextBuffer Signal

        def callback(textbuffer, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "begin-user-action" signal is emitted on the first call to the `begin_user_action`() method.

### The "changed" gtk.TextBuffer Signal

        def callback(textbuffer, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "changed" signal is emitted when text is inserted in `textbuffer`.

### The "delete-range" gtk.TextBuffer Signal

        def callback(textbuffer, start, end, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`start` : | a `gtk.TextIter` pointing to the start of the range of text
`end` : | a `gtk.TextIter` pointing to the end of the range of text
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "delete-range" signal is emitted when the text in the range specified by `start` and `end` is to be deleted.

### The "end-user-action" gtk.TextBuffer Signal

        def callback(textbuffer, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "end-user-action" signal is emitted when the call to the `end_user_action`() method reduces the user action count to zero i.e. undoes the first call to the `begin_user_action`() method.

### The "insert-child-anchor" gtk.TextBuffer Signal

        def callback(textbuffer, iter, anchor, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`iter` : | a `gtk.TextIter`
`anchor` : | a `gtk.TextChildAnchor`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "insert-child-anchor" signal is emitted when `anchor` is inserted into `textbuffer` at the location specified by `iter`.

### The "insert-pixbuf" gtk.TextBuffer Signal

        def callback(textbuffer, iter, pixbuf, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`iter` : | a `gtk.TextIter`
`pixbuf` : | a `gtk.gdk.Pixbuf`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "insert-pixbuf" signal is emitted when `pixbuf` is inserted into `textbuffer` at the location specified by `iter`.

### The "insert-text" gtk.TextBuffer Signal

        def callback(textbuffer, iter, text, length, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`iter` : | a `gtk.TextIter`
`text` : | the text inserted in `textbuffer`
`length` : | the length of the text inserted in `textbuffer`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "insert-text" signal is emitted when `text` of the size specified by `length` is inserted into `textbuffer` at the location specified by `iter`.

### The "mark-deleted" gtk.TextBuffer Signal

        def callback(textbuffer, textmark, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`textmark` : | the `gtk.TextMark` that is being deleted
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "mark-deleted" signal is emitted when `textmark` is being deleted from `textbuffer`.

### The "mark-set" gtk.TextBuffer Signal

        def callback(textbuffer, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`iter` : | a `gtk.TextIter` pointing at the location where `textmark` will be set.
`textmark` : | the `gtk.TextMark` that is being set
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "mark-set" signal is emitted when `textmark` is being set at the location specified by `iter` in `textbuffer`.

### The "modified-changed" gtk.TextBuffer Signal

        def callback(textbuffer, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "modified-changed" signal is emitted when the modification flag is changed.

### The "remove-tag" gtk.TextBuffer Signal

        def callback(textbuffer, texttag, start, end, user_param1, ...)

`textbuffer` : | the textbuffer that received the signal
`texttag` : | the `gtk.TextTag` being removed
`start` : | a `gtk.TextIter` pointing to the start of the range of text
`end` : | a `gtk.TextIter` pointing to the end of the range of text
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "remove-tag" signal is emitted when `texttag` is being removed from the `textbuffer` text in the range specified by `start` and `end`.

Prev | Up | Next
gtk.TextAttributes | Home | gtk.TextChildAnchor