gtksourceview.SourceBuffer

Text buffer object for gtksourceview.SourceView

## Synopsis

        gtksourceview.SourceBuffer
        gtk.TextBuffer

    	gtksourceview.SourceBuffer
    	bufferNone

    	set_check_brackets
    	check_brackets

    	get_check_brackets

    	set_bracket_match_style
    	style

    	set_highlight
    	highlight

        get_highlight

        set_max_undo_levels
    	max_undo_levels

    	get_max_undo_levels

    	set_language
    	language

    	get_language

    	set_escape_char
    	escape_char

    	get_escape_char

    	can_undo

    	can_redo

    	undo

    	redo

    	begin_not_undoable_action

    	end_not_undoable_action

    	create_marker
    	name
        type
        where

        move_marker
    	marker
        where

        delete_marker
    	marker

        get_marker
        name

        get_marker_in_region
        start
        end

        get_first_marker

        get_last_marker

        get_iter_at_marker

        get_next_marker

        get_prev_marker

    Functions

    gtksourceview.gtk_source_buffer_new_with_language
    gtksourceview.SourceLanguage

## Ancestry

    +-- gobject.GObject
      +-- gtk.TextBuffer
        +-- gtksourceview.SourceBuffer

## Properties

> "check-brackets" | Read-Write | If `TRUE` bracket match highlighting is activated.
> "escape-char" | Read-Write | Escaping character for syntax patterns.
> "highlight" | Read-Write | If `TRUE` the syntax highlighting is activated.
> "language" | Read-Write | Language object to get highlighting patterns from.
> "max-undo-levels" | Read-Write | Number of undo levels for the buffer.

## Signal Prototypes

""can-redo""

- `callback` `sourceview` `arg1` `user_param1` `...`

""can-undo""

- `callback` `sourceview` `arg1` `user_param1` `...`

""highlight-updated""

- `callback` `sourceview` `start` `end` `user_param1` `...`

""marker-updated""

- `callback` `sourceview` `iter` `user_param1` `...`

## Description

The `gtksourceview.SourceBuffer` is the model for `gtksourceview.SourceView` widgets. It extends the `gtk.TextBuffer` object by adding features necessary to display and edit source code: syntax highlighting, bracket matching and markers. It also implements support for undo/redo operations.

To create a `gtksourceview.SourceBuffer` use `gtksourceview.gtk_source_buffer_new`() or `gtksourceview.gtk_source_buffer_new_with_language`. The second form is just a convenience function which allows you to initially set a `gtksourceview.SourceLanguage`.

By default highlighting is enabled, but you can disable it with `set_highlight`(). This can be useful if you're not using `gtksourceview.SourceLanguage` objects to set the highlighting patterns, and instead you're manually adding `gtksourceview.SourceTag` objects to the buffer's tag table.

## Constructor

    	  gtksourceview.SourceBuffer
    	  tableNone

`table` :

- a `gtksourceview.SourceTagTable` or `None`

Returns :

- a new `gtksourceview.SourceBuffer`.

Creates a new `gtksourceview.SourceBuffer` object.

## Methods

### gtksourceview.SourceBuffer.set_check_brackets

    	  set_check_brackets
    	  check_brackets

`check_brackets` :

- if `TRUE` turns on the matching brackets highlight.

The `set_check_brackets`() method controls the bracket match highlighting function in the buffer. If activated, when you position your cursor over a bracket character (a parenthesis, a square bracket, etc.) the matching opening or closing bracket character will be highlighted. You can specify the style with the `set_bracket_match_style` function.

### gtksourceview.SourceBuffer.get_check_brackets

    	  get_check_brackets

Returns :

- `TRUE` if the matching brackets highlight is active, `FALSE` otherwise.

The `get_check_brackets`() method returns the value of the "check-brackets" property which determines if the matching brackets highlight is active.

### gtksourceview.SourceBuffer.set_bracket_match_style

    	  set_bracket_match_style
    	  style

`style` :

- the `gtksourceview.SourceTagStyle` specifying colors and text attributes.

The `set_bracket_match_style`() method sets the style used for highlighting matching brackets.

### gtksourceview.SourceBuffer.set_highlight

    	    set_highlight
    	    highlight

`highlight` :

- if `TRUE` turns on the source highlighting.

The `set_highlight`() method controls whether text is highlighted in the buffer. If `highlight` is `TRUE` , the text will be highlighted according to the patterns installed in the buffer (either set with `set_language` or by adding individual `gtksourceview.SourceTag` tags to the buffer's tag table). Otherwise, any current highlighted text will be restored to the default buffer style.

Tags not of `gtksourceview.SourceTag` type will not be removed by this option, and normal GtkTextTag priority settings apply when highlighting is enabled.

If not using a `gtksourceview.SourceLanguage` for setting the highlighting patterns in the buffer, it is recommended for performance reasons that you add all the `gtksourceview.SourceTag` tags with highlighting disabled and enable it when finished.

### gtksourceview.SourceBuffer.get_highlight

    	  get_highlight

Returns :

- `TRUE` if the source highlighting is active, `FALSE` otherwise.

The `get_highlight`() method returns the value of the "highlight" property which determines if the text highlighting is active.

### gtksourceview.SourceBuffer.set_max_undo_levels

    	    set_max_undo_levels
    	    max_undo_levels

`max_undo_levels` :

- the desired maximum number of undo levels.

The `set_max_undo_levels`() method Sets the number of undo levels for user actions the buffer will track. If the number of user actions exceeds the limit set by this function, older actions will be discarded.

A new action is started whenever the function `begin_user_action` is called. In general, this happens whenever the user presses any key which modifies the buffer, but the undo manager will try to merge similar consecutive actions, such as multiple character insertions into one action. But, inserting a newline does start a new action.

### gtksourceview.SourceBuffer.get_max_undo_levels

    	  get_max_undo_levels

Returns :

- the maximum number of possible undo levels.

The `get_max_undo_levels`() method returns the value of the "max-undo-levels" property which determines the number of undo levels the buffer will track for buffer edits.

### gtksourceview.SourceBuffer.set_language

    	  set_language
    	  language

`language` :

- A `gtksourceview.SourceLanguage` or `None`.

The `set_check_brackets`() method Sets the `gtksourceview.SourceLanguage` the source buffer will use, adding `gtksourceview.SourceTag` tags with the language's patterns and setting the escape character with `set_escape_char`. Note that this will remove any `gtksourceview.SourceTag` tags currently in the buffer's tag table. The buffer holds a reference to the `language` set.

### gtksourceview.SourceBuffer.get_language

    	  get_language

Returns :

- the `gtksourceview.SourceLanguage` set by `set_language`.

The `get_check_brackets`() method determines the `gtksourceview.SourceLanguage` used by the buffer. The returned object should not be unreferenced by the user.

### gtksourceview.SourceBuffer.set_escape_char

    	  set_escape_char
    	  escape_char

`escape_char` :

- the escape character the buffer should use.

The `set_check_brackets`() method sets the escape character to be used by the highlighting engine.

When performing the initial analysis, the engine will discard a matching syntax pattern if it's prefixed with an odd number of escape characters. This allows for example to correctly highlight strings with escaped quotes embedded.

This setting affects only syntax patterns (i.e. those defined in `gtksourceview.SourceTag` tags).

### gtksourceview.SourceBuffer.get_escape_char

    	  get_escape_char

Returns :

- the UTF-8 character for the escape character the buffer is using.

The `get_escape_char`() method determines the escaping character used by the source buffer highlighting engine.

### gtksourceview.SourceBuffer.can_undo

    	  can_undo

Returns :

- `TRUE` if it's possible to undo the last action.

The `can_undo`() method determines whether a source buffer can undo the last action.

### gtksourceview.SourceBuffer.can_redo

    	  can_redo

Returns :

- `TRUE` if a redo is possible.

The `can_redo`() method Determines whether a source buffer can redo the last action (i.e. if the last operation was an undo).

### gtksourceview.SourceBuffer.undo

    	  undo

The `undo`() Undoes the last user action which modified the buffer. Use `can_undo` to check whether a call to this function will have any effect.

Actions are defined as groups of operations between a call to `begin_user_action`() and `end_user_action`(), or sequences of similar edits (inserts or deletes) on the same line.

### gtksourceview.SourceBuffer.redo

    	  redo

The `redo`() method redoes the last undo operation. Use `can_redo` to check whether a call to this function will have any effect.

### gtksourceview.SourceBuffer.begin_not_undoable_action

    	  begin_not_undoable_action

The `begin_not_undoable_action`() marks the beginning of a not undoable action on the buffer, disabling the undo manager. Typically you would call this function before initially setting the contents of the buffer (e.g. when loading a file in a text editor).

You may nest `begin_not_undoable_action`() / `end_not_undoable_action`() blocks.

### gtksourceview.SourceBuffer.end_not_undoable_action

    	  end_not_undoable_action

The `end_not_undoable_action`() method marks the end of a not undoable action on the buffer. When the last not undoable block is closed through the call to this function, the list of undo actions is cleared and the undo manager is re-enabled.

### gtksourceview.SourceBuffer.create_marker

    	  create_marker
    	  name
    	  type
        where

`name` :

- the name of the marker, or `None`.

`type` :

- a string defining the marker type, or `None`.

`where` :

- location to place the marker.

Returns :

- a new `gtksourceview.SourceMarker`

The `set_marker_pixbuf`() method creates a marker in the `gtksourceview.SourceBuffer` of type `type`. A marker is semantically very similar to a `gtk.TextMark`, except it has a type which is used by the `gtksourceview.SourceView` displaying the buffer to show a pixmap on the left margin, at the line the marker is in. Because of this, a marker is generally associated to a line and not a character position. Markers are also accessible through a position or range in the buffer.

Markers are implemented using `gtk.TextMark`, so all characteristics and restrictions to marks apply to markers too. These includes life cycle issues and "mark-set" and "mark-deleted" signal emissions.

Like a `gtk.TextMark`, a `gtksourceview.SourceMarker` can be anonymous if the passed `name` is `None`. Also, the buffer owns the markers so you shouldn't unreference it.

Markers always have left gravity and are moved to the beginning of the line when the user deletes the line they were in. Also, if the user deletes a region of text which contained lines with markers, those are deleted.

Typical uses for a marker are bookmarks, breakpoints, current executing instruction indication in a source file, etc..

### gtksourceview.SourceBuffer.move_marker

    	  move_marker
    	  marker
        where

`marker` :

- a `gtksourceview.SourceMarker`.

`where` :

- the new location for the marker.

Moves `marker` to the new location `where`.

### gtksourceview.SourceBuffer.delete_marker

    	  delete_marker
    	  marker

`marker` :

- a `gtksourceview.SourceMarker`.

`where` :

- the new location for the marker.

Deletes `marker` from the source buffer. The same conditions as for `gtk.TextMark` apply here. The marker is no longer accessible from the buffer, but if you held a reference to it, it will not be destroyed.

### gtksourceview.SourceBuffer.get_marker

    	  get_marker
    	  name

`name` :

- name of the `gtksourceview.SourceMarker` to retreive.

Looks up the `gtksourceview.SourceMarker` named `name` in `buffer`, returning `None` if it doesn't exists.

### gtksourceview.SourceBuffer.get_markers_in_region

    	  get_markers_in_region
    	  begin
        end

`begin` :

- beginning of the range.

`end` :

- end of the range.

Returns :

- a list of the `gtksourceview.SourceMarker` in the range.

Returns an ordered (by position) list of `gtksourceview.SourceMarker` objects inside the region delimited by the `gtk.TextIter` `begin` and `end`. The iters may be in any order.

### gtksourceview.SourceBuffer.get_first_marker

    	  get_first_marker

Returns :

- a reference to the first `gtksourceview.SourceMarker`, or `None` if there are no markers in the buffer.

Returns the first (nearest to the top of the buffer) marker in buffer.

### gtksourceview.SourceBuffer.get_last_marker

    	  get_last_marker

Returns :

- a reference to the last `gtksourceview.SourceMarker`, or `None` if there are no markers in the buffer.

Returns the last (nearest to the bottom of the buffer) marker in buffer.

### gtksourceview.SourceBuffer.get_iter_at_marker

    	  get_iter_at_marker
    	  iter
        marker

`iter` :

- a `gtk.TextIter` to initialize.

`marker` :

- a `gtksourceview.SourceMarker` of buffer.

Initializes `iter` at the location of `marker`.

### gtksourceview.SourceBuffer.get_next_marker

    	  get_next_marker
    	  iter

`iter` :

- the location to start searching from.

Returns :

- the `gtksourceview.SourceMarker` nearest to the right of `iter`, or `None` if there are no more markers after `iter`.

Returns the nearest marker to the right of `iter`. If there are multiple markers at the same position, this function will always return the first one (from the internal linked list), even if starting the search exactly at its location. You can get the others using `next`().

### gtksourceview.SourceBuffer.get_prev_marker

    	  get_prev_marker
    	  iter

`iter` :

- the location to start searching from.

Returns :

- the `gtksourceview.SourceMarker` nearest to the left of `iter`, or `None` if there are no more markers before `iter`.

Returns the nearest marker to the left of `iter`. If there are multiple markers at the same position, this function will always return the first one (from the internal linked list), even if starting the search exactly at its location. You can get the others using `prev`().

## Functions

### gtksourceview.SourceBuffer.gtk_source_buffer_new_with_language

      	  gtksourceview.SourceBuffer.gtk_source_buffer_new_with_language
          language

`language` :

- a `gtksourceview.SourceLanguage`.

Returns :

- a new source buffer which will highlight text according to `language`.

Creates a new source buffer using the highlighting patterns in `language`. This is equivalent to creating a new source buffer with the default tag table and then calling `set_language`

## Signals

### The "can-redo" gtksourceview.SourceBuffer Signal

    	  callback
    	  sourcebuffer
        arg1
    	  user_param1
    	  ...

`sourcebuffer` :

- the sourcebuffer that received the signal

`arg1` :

- TRUE if the buffer can now perform a redo.

`user_param1` :

- the first user parameter (if any) specified with the `connect`() method

`...` :

- additional user parameters (if any)

The "can-redo" signal is emitted when there is a change in the buffer's ability to redo an operation.

### The "can-undo" gtksourceview.SourceBuffer Signal

    	  callback
    	  sourcebuffer
    	  arg1
        user_param1
    	  ...

`sourcebuffer` :

- the sourcebuffer that received the signal

`arg1` :

- TRUE if the buffer can now perform an undo.

`user_param1` :

- the first user parameter (if any) specified with the `connect`() method

`...` :

- additional user parameters (if any)

The "can-undo" signal is emitted when there is a change in the buffer's ability to undo an operation.

### The "highlight-updated" gtksourceview.SourceBuffer Signal

    	  callback
    	  sourcebuffer
    	  start
        end
        user_param1
    	  ...

`sourcebuffer` :

- the sourcebuffer that received the signal

`start` :

- the `gtk.TextIter` at the start of the updated region.

`end` :

- the `gtk.TextIter` at the end of the updated region.

`user_param1` :

- the first user parameter (if any) specified with the `connect`() method

`...` :

- additional user parameters (if any)

The "highlight-updated" signal is emitted whenever the syntax highlighting information has been updated, so that views can request a redraw if the region changed is visible. Usually only view widgets displaying this buffer will be interested in this signal.

### The "marker-updated" gtksourceview.SourceBuffer Signal

    	  callback
    	  sourcebuffer
    	  arg1
        user_param1
    	  ...

`sourcebuffer` :

- the sourcebuffer that received the signal

`end` :

- the `gtk.TextIter` at the location where the change occurred.

`user_param1` :

- the first user parameter (if any) specified with the `connect`() method

`...` :

- additional user parameters (if any)

The "can-undo" signal is emitted whenever a marker of `sourcebuffer` has changed and needs to be redisplayed by the view. A change in a marker's type or location can trigger this signal.