12.3. Gtk2::TextBuffers

textbuffer = Gtk2::TextBuffer->new ($tagtable=undef) 
	* $tagtable (Gtk2::TextTagTable or undef)

12.3.1. Gtk2::TextBuffer Status Information

You can retrieve the number of lines in a Gtk2::TextBuffer by using the method:

integer = $buffer->get_line_count 

Likewise you can get the number of characters in the Gtk2::TextBuffer using:

integer = $buffer->get_char_count 

When the textbuffer contents are changed the modified flag in the textbuffer is set. The status of the modified flag can be retrieved using the method:

boolean = $buffer->get_modified 

If the program saves the contents of the textbuffer the following method can be used to reset the modified flag:

$buffer->set_modified ($setting) 
	* $setting (boolean)

12.3.2. Creating Gtk2::TextIters

A Gtk2::TextIter is used to specify a location within a Gtk2::TextBuffer between two characters. Gtk2::TextBuffer methods that manipulate text use Gtk2::TextIters to specify where the method is to be applied. Gtk2::TextIters have a large number of methods that will be described in the Section 12.4 section.

The basic TextBuffer methods used to create TextIters are:

textiter = $buffer->get_iter_at_offset ($char_offset) 
	* $char_offset (integer)

textiter = $buffer->get_iter_at_line ($line_number) 
	* $line_number (integer)
	
textiter = $buffer->get_iter_at_line_offset ($line_number, $char_offset) 
	* $line_number (integer)
	* $char_offset (integer)
textiter = $buffer->get_iter_at_mark ($mark) 
	* $mark (Gtk2::TextMark)

get_iter_at_offset creates an Gtk2::TextIter that is just after $char_offset chars from the start of the Gtk2::TextBuffer.

get_iter_at_line creates an Gtk2::TextIter that is just before the first character in $line_number.

get_iter_at_line_offset creates an Gtk2::TextIter that is just after the $line_offset character in $line_number.

get_iter_at_mark() creates an Gtk2::TextIter that is at the same position as the given $mark.

The following methods create one or more Gtk2::TextIters at specific buffer locations:

textiter = $buffer->get_start_iter
 
textiter = $buffer->get_end_iter

(start, end) = $buffer->get_bounds 
	
(start, end) = $buffer->get_selection_bounds

get_start_iter creates an Gtk2::TextIter that is just before the first character in the Gtk2::TextBuffer.

get_end_iter creates an Gtk2::TextIter that is just after the last character in the Gtk2::TextBuffer.

get_bounds creates a tuple of two Gtk2::TextIters that are just before the first character and just after the last character in the Gtk2::TextBuffer respectively.

get_selection_bounds creates a tuple of two Gtk2::TextIters that have the same location as the insert and selection_bound marks in the Gtk2::TextBuffer.

12.3.3. Text Insertion, Retrieval and Deletion

The text in a Gtk2::TextBuffer can be set using the method:

$buffer->set_text ($text) 
	* $text (string)

This method replaces the current contents of Gtk2::TextBuffer with $text.

The most general method to insert characters in a Gtk2::TextBuffer is:

$buffer->insert ($iter, $text) 
	* $iter (Gtk2::TextIter)
 	* $text (string)

which inserts $text at the Gtk2::TextBuffer location specified by $iter.

If you want to simulate the insertion of text by an interactive user use the method:

boolean = $buffer->insert_interactive ($iter, $text, $default_editable) 
	* $iter (Gtk2::TextIter)
	* $text (string)
	* $default_editable (boolean)

which inserts $text in the Gtk2::TextBuffer at the location specified by $iter but only if the location is editable (i.e. does not have a tag that specifies the text is non-editable) and the $default_editable value is TRUE. The result indicates whether the text was inserted.

$default_editable indicates the editability of text that doesn't have a tag affecting editability; $default_editable is usually determined by a call to the Gtk2::TextBuffer get_editable method.

Other methods that insert text are:

$buffer->insert_at_cursor ($text) 
	* $text (string)

boolean = $buffer->insert_interactive_at_cursor ($text, $default_editable) 
	* $text (string)
	* $default_editable (boolean)

$buffer->insert_range ($iter, $start, $end) 
	* $iter (Gtk2::TextIter)
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)

boolean = $buffer->insert_range_interactive ($iter, $start, $end, $default_editable) 
	* $iter (Gtk2::TextIter)
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)
	* $default_editable (boolean)

insert_at_cursor is a convenience method that inserts $text at the current cursor (insert) location.

insert_range copies text, pixbufs and tags between start and end from a Gtk2::TextBuffer (if different from Gtk2::TextBuffer, the tag table must be the same) and inserts the copy into Gtk2::TextBuffer at iter's location.

The interactive versions of these methods operate the same way except they will only insert if the location is editable.

Finally, text can be inserted and have tags applied at the same time using the methods:

$buffer->insert_with_tags ($iter, $text, ...) 
	* $iter (Gtk2::TextIter)
	* $text (string)
 	* ... (list) of Gtk2::TextTag's
	
$buffer->insert_with_tags_by_name ($iter, $text, ...) 
	* $iter (Gtk2::TextIter)
	* $text (string)
 	* ... (list) of strings, tag names

insert_with_tags inserts $text in the Gtk2::TextBuffer at the location specified by $iter and applies the given tags.

insert_with_tags_by_name does that same thing but allows you to specify the tags using the tag name.

The text in a textbuffer can be deleted by using the methods:

$buffer->delete ($start, $end) 
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)

boolean = $buffer->delete_interactive ($start_iter, $end_iter, $default_editable) 
	* $start_iter (Gtk2::TextIter)
	* $end_iter (Gtk2::TextIter)
	* $default_editable (boolean)

delete removes the text between $start and $end Gtk2::TextIter locations in Gtk2::TextBuffer.

delete_interactive removes all the editable (as determined by the applicable text tags and the default_editable argument) text between $start_iter and $end_iter.

You can retrieve a copy of the text from a Gtk2::TextBuffer by using the methods:

string = $buffer->get_text ($start, $end, $include_hidden_chars) 
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)
	* $include_hidden_chars (boolean)
string = $buffer->get_slice ($start, $end, $include_hidden_chars) 
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)
	* $include_hidden_chars (boolean)

get_text returns a copy of the text in Gtk2::TextBuffer between $start and $end. Undisplayed text is excluded if $include_hidden_chars is FALSE. Characters which represent embedded images or widgets are excluded.

get_slice is the same as get_text, except that the returned text includes a 0xFFFC character for each embedded image or widget.

12.3.4. Gtk2::TextMarks

Gtk2::TextMarks are similar to Gtk2::TextIters in that they specify a location in a Gtk2::TextBuffer between two characters. However, Gtk2::TextMarks maintain their location information across buffer modifications. The Gtk2::TextMark methods will be described in the Gtk2::TextMarks section.

A Gtk2::TextBuffer contains two built-in marks: the insert (cursor) mark and the selection_bound mark. The insert mark is the default location for the insertion of text and the selection_bound mark combines with the insert mark to define a selection range.

The built-in Gtk2::TextMarks can be retrieved by using the methods:

textmark = $buffer->get_insert 
 textmark = $buffer->get_selection_bound 

The insert and selection_bound marks can be placed simultaneously at a location by using the method:

$buffer->place_cursor ($where) 
	* $where (Gtk2::TextIter)

$where is a Gtk2::TextIter specifying the location. The place_cursor() method is needed to avoid temporarily creating a selection if the marks were moved individually.

Gtk2::TextMarks are created by using the method:

textmark = $buffer->create_mark ($mark_name, $where, $left_gravity) 
	* $mark_name (string or undef)
	* $where (Gtk2::TextIter)
	* $left_gravity (boolean)

where $mark_name is the name assigned to the created Gtk2::TextMark (can be undef to create an anonymous mark), $where is the Gtk2::TextIter specifying the location of the Gtk2::TextMark in Gtk2::TextBuffer and $left_gravity indicates where the Gtk2::TextMark will be located after text is inserted at the Gtk2::TextMark (left if TRUE or right if FALSE).

A Gtk2::TextMark can be moved in the Gtk2::TextBuffer by using the methods:

 $buffer->move_mark ($mark, $where) 
	* $mark (Gtk2::TextMark)
 	* $where (Gtk2::TextIter)
	
$buffer->move_mark_by_name ($name, $where) 
	* $name (string)
	* $where (Gtk2::TextIter)

$mark specifies the Gtk2::TextMark to be moved. $name specifies the name of the Gtk2::TextMark to be moved. $where is a Gtk2::TextIter specifying the new location.

A Gtk2::TextMark can be deleted from a Gtk2::TextBuffer by using the methods:

$buffer->delete_mark ($mark) 
	* $mark (Gtk2::TextMark)
 
$buffer->delete_mark_by_name ($name) 
	* $name (string)

A Gtk2::TextMark can be retrieved by name using the method:

textmark or undef = $buffer->get_mark ($name) 
	* $name (string)

12.3.5. Creating and Applying Gtk2::TextTags

Gtk2::TextTags contain one or more attributes (e.g. foreground and background colors, font, editability) that can be applied to one or more ranges of text in a Gtk2::TextBuffer. The attributes that can be specified by Gtk2::TextTag properties will be described in Section 12.6.

A Gtk2::TextTag can be created with attributes and installed in the Gtk2::TextTagTable of a Gtk2::TextBuffer by using the convenience method:

	
texttag = $buffer->create_tag ($tag_name, $property_name1, $property_value1, ...) 
	* $tag_name (string or undef)
	* $property_name1 (string) the first property name
	* $property_value1 (string) the first property value
	* ... (list) pairs of names and values

where $tag_name is a string specifying the name of the Gtk2::TextTag or undef, if the tag is an anonymous tag and the name-value pairs specify the attributes that the Gtk2::TextTag will have. See the Section 12.6 section for information on what attributes can be set by the Gtk2::TextTag properties.

A tag can be applied to a range of text in a textbuffer by using the methods:

$buffer->apply_tag ($tag, $start, $end) 
	* $tag (Gtk2::TextTag)
	* $start (Gtk2::TextIter)
 	* $end (Gtk2::TextIter)
	
 $buffer->apply_tag_by_name ($name, $start, $end) 
	* $name (string)
 	* $start (Gtk2::TextIter)
 	* $end (Gtk2::TextIter)

$tag is the Gtk2::TextTag to be applied to the text. $name is the name of the Gtk2::TextTag to be applied. $start and $end are Gtk2::TextIters that specify the range of text that the Gtk2::TextTag is to be applied to.

A Gtk2::TextTag can be removed from a range of text by using the methods:

$buffer->remove_tag ($tag, $start, $end) 
	* $tag (Gtk2::TextTag)
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)
	
 $buffer->remove_tag_by_name ($name, $start, $end) 
	* $name (string)
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)

All Gtk2::TextTags for a range of text can be removed by using the method:

$buffer->remove_all_tags ($start, $end) 
	* $start (Gtk2::TextIter)
	* $end (Gtk2::TextIter)	

A tag can be removed from a range of text by using the methods:

A tag can be removed from a range of text by using the methods:

12.3.6. Inserting Images and Widgets

In addition to text a Gtk2::TextBuffer can contain pixbuf images and an anchor location for widgets. A widget can be added to a Gtk2::TextView at an anchor location. A different widget can be added in each Gtk2::TextView which displays a Gtk2::TextBuffer with an anchor.

A pixbuf can be inserted by using the method:

$buffer->insert_pixbuf ($iter, $pixbuf) 
	* $iter (Gtk2::TextIter)
	* $pixbuf (Gtk2::Gdk::Pixbuf)

where $iter specifies the location in the Gtk2::TextBuffer to insert the Gtk2::Gdk::Pixbuf. The image will be counted as one character and will be represented in a get_slice return (but left out of a get_text return) as the Unicode character "0xFFFC".

A Gtk+ widget can be inserted in a Gtk2::TextView at a buffer location specified with a TextChildAnchor. The TextChildAnchor will be counted as one character and represented as "0xFFFC" similar to a pixbuf.

The TextChildAnchor can be created and inserted in the Gtk2::TextBuffer by using the convenience method:

textchildanchor = $buffer->create_child_anchor ($iter) 
	* $iter (Gtk2::TextIter)

where $iter is the location for the textchildanchor.

A TextChildAnchor can also be created and inserted in two operations as:

textchildanchor = Gtk2::TextChildAnchor->new

$buffer->insert_child_anchor ($iter, $anchor) 
	* $iter (Gtk2::TextIter)
	* $anchor (Gtk2::TextChildAnchor)

Then the widget can be added to the Gtk2::TextView at an anchor location using the Gtk2::TextView's method:

$text_view->add_child_at_anchor ($child, $anchor) 
	* $child (Gtk2::Widget)
 	* $anchor (Gtk2::TextChildAnchor)

The list of widgets at a particular buffer anchor can be retrieved using the method:

list = $anchor->get_widgets 

A widget can also be added to a Gtk2::TextView using the method:

$text_view->add_child_in_window ($child, $which_window, $xpos, $ypos) 
	* $child (Gtk2::Widget)
 	* $which_window (Gtk2::TextWindowType)
 	* $xpos (integer)
	* $ypos (integer)

where the $child widget is placed in $which_window at the location specified by $xpos and $ypos. $which_window indicates in which of the windows that make up the Gtk2::TextView the widget is to be placed:

    * 'private' / 'GTK_TEXT_WINDOW_PRIVATE'
    * 'widget' / 'GTK_TEXT_WINDOW_WIDGET'
    * 'text' / 'GTK_TEXT_WINDOW_TEXT'
    * 'left' / 'GTK_TEXT_WINDOW_LEFT'
    * 'right' / 'GTK_TEXT_WINDOW_RIGHT'
    * 'top' / 'GTK_TEXT_WINDOW_TOP'
    * 'bottom' / 'GTK_TEXT_WINDOW_BOTTOM'