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"ReadThe 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"ReadThe 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"ReadIf TRUE the buffer has some text currently selected. Default value: FALSE. This property is available in GTK+ 2.10 and above.
"paste-target-list"ReadThe 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 OnlyThe gtk.TextTagTable associated with the textbuffer. Available in GTK+ 2.2 and above.
"text"Read-WriteThe 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"ReadThe 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.