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)
def add_mark(mark, where)

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, ...)

"paste-done"

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.

gtk.TextBuffer.add_mark

    def add_mark(mark, where)

mark :

the gtk.TextMark to add

where :

the location to place mark.

Note

This method is available in PyGTK 2.12 and above.

Adds the mark at position where. The mark must not be added to another buffer, and if its name is not None then there must not be another mark in the buffer with the same name.

Emits the "mark_set" signal as notification of the mark's initial placement.

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, iter, textmark, 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 "paste-done" 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)

Note

This signal is available in GTK+ 2.16 and above.

The "paste-done" signal is emitted after paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text.

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.