gtksourceview2.Buffer

Text buffer object for gtksourceview2.View

## Synopsis

        gtksourceview2.Buffer
        gtk.TextBuffer

          gtksourceview2.Buffer
          bufferNone

            backward_iter_to_source_mark
            iter
            categoryNone

          begin_not_undoable_action

          can_redo

          can_undo

          create_source_mark
          name
          category
          where

          end_not_undoable_action

          ensure_highlight
          start
          end

            forward_iter_to_source_mark
            iter
            categoryNone

          get_highlight_matching_brackets

          get_highlight_syntax

          get_language

            get_source_marks_at_iter
            iter
            categoryNone

            get_source_marks_at_line
            line
            categoryNone

          get_max_undo_levels

          get_style_scheme

          redo

          remove_source_marks
          start
          end
          categoryNone

          set_highlight_matching_brackets
          highlight

          set_highlight_syntax
          highlight

          set_language
          language

          set_max_undo_levels
          max_undo_levels

          set_style_scheme
          scheme

          undo

    Functions

    gtksourceview2.iter_backward_search
    iter
    str
    flags
    limit

    gtksourceview2.iter_forward_search
    iter
    str
    flags
    limit

## Ancestry

    +-- gobject.GObject
        +-- gtk.TextBuffer
            +-- gtksourceview2.Buffer

## Properties

> "can-redo" | Read | Whether Redo operation is possible. Default value: False.
> "can-undo" | Read | Whether Undo operation is possible. Default value: False.
> "highlight-matching-brackets" | Read-Write | Whether to highlight matching brackets in the buffer. Default value: True.
> "highlight-syntax" | Read-Write | Whether to highlight syntax in the buffer. Default value: True.
> "language" | Read-Write | Language object to get highlighting patterns from.
> "max-undo-levels" | Read-Write | Number of undo levels for the buffer. -1 means no limit. Allowed values: >= -1 Default value: 1000.

## Signal Prototypes

"highlight-updated"

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

"source-mark-updated"

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

## Description

The `gtksourceview2.Buffer` is the model for `gtksourceview.View` 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 `gtksourceview2.Buffer` use the constructor.

By default highlighting is enabled, but you can disable it with `set_highlight_syntax`().

## Constructor

    	  gtksourceview2.Buffer
    	  tableNone
        languageNone

`table` :

- a `gtk.TextTagTable` or `None`

`language` :

- a `gtksourceview2.Language` or `None`

Returns :

- a new `gtksourceview2.Buffer`.

Creates a new `gtksourceview2.Buffer` object.

## Methods

### gtksourceview2.Buffer.backward_iter_to_source_mark

    	  backward_iter_to_source_mark
          iter
          categoryNone

`iter` :

- a `gtk.TextIter`

`category` :

- category to search for or `None`.

Returns :

- whether iter moved.

The `backward_iter_to_source_mark`() method moves iter to the position of the previous `gtksourceview2.Mark` of the given category. Returns `True` if iter was moved. If category is `None`, the previous source mark can be of any category.

### gtksourceview2.Buffer.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.

### gtksourceview2.Buffer.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).

### gtksourceview2.Buffer.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.

### gtksourceview2.Buffer.create_source_mark

    	  create_source_mark
          name
          category
          where

`name` :

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

`category` :

- a string defining the mark category.

`where` :

- location to place the mark.

Returns :

- a new `gtksourceview2.Mark`

The `create_source_mark`() method creates a mark in the `gtksourceview2.Buffer` of category `category`. A mark is semantically very similar to a `gtk.TextMark`, but organised into categories.

Like a `gtk.TextMark`, a `gtksourceview2.Mark` can be anonymous if the passed name is `None`.

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

Marks 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 marks are bookmarks, breakpoints, current executing instruction indication in a source file, etc..

### gtksourceview2.Buffer.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.

### gtksourceview2.Buffer.ensure_highlight

          ensure_highlight
            start
            end

`start` :

- start of the area to highlight.

`end` :

- end of the area to highlight.

The `ensure_highlight`() method forces buffer to analyze and highlight the given area synchronously.

### gtksourceview2.Buffer.forward_iter_to_source_mark

    	  forward_iter_to_source_mark
          iter
          categoryNone

`iter` :

- a `gtk.TextIter`

`category` :

- category to search for or `None`.

Returns :

- whether iter moved.

The `forward_iter_to_source_mark`() method moves iter to the position of the next `gtksourceview2.Mark` of the given category. Returns `True` if iter was moved. If category is `None`, the previous source mark can be of any category.

### gtksourceview2.Buffer.get_highlight_matching_brackets

    	  get_highlight_matching_brackets

Returns :

- `True` if the matching brackets highlight is active, `False` otherwise.

The `get_highlight_matching_brackets`() method determines whether bracket match highlighting is activated for the source buffer.

### gtksourceview2.Buffer.get_highlight_syntax

    	  get_highlight_syntax

Returns :

- `True` if the source highlighting is activated in the buffer, `False` otherwise.

The `get_highlight_syntax`() method determines whether syntax highlighting is activated in the source buffer.

### gtksourceview2.Buffer.get_language

    	  get_language

Returns :

- the `gtksourceview2.Language` set by `set_language`.

The `get_language`() method returns the `gtksourceview2.Language` associated with the buffer, see `gtksourceview2.Buffer.set_language`().

### gtksourceview2.Buffer.get_source_marks_at_iter

    	  get_source_marks_at_iter
          iter
          categoryNone

`iter` :

- a `gtk.TextIter`.

`category` :

- category to search for or `None`

Returns :

- a list of `gtksourceview2.Mark`.

The `get_source_marks_at_iter`() method returns the list of marks of the given category at iter. If category is `None` it returns all marks at iter.

### gtksourceview2.Buffer.get_source_marks_at_line

    	  get_source_marks_at_line
          iter
          categoryNone

`iter` :

- a `gtk.TextIter`.

`category` :

- category to search for or `None`

Returns :

- a list of `gtksourceview2.Mark`.

The `get_source_marks_at_line`() method returns the list of marks of the given category at line. If category is `None` it returns all marks at line.

### gtksourceview2.Buffer.get_max_undo_levels

    	  get_max_undo_levels

Returns :

- the maximum number of possible undo levels or -1 if no limit is set.

The `get_max_undo_levels`() method determines the number of undo levels the buffer will track for buffer edits.

### gtksourceview2.Buffer.get_style_scheme

          get_style_scheme

Returns :

- the `gtksourceview2.StyleScheme` set by `gtksourceview2.Buffer.set_style_scheme`(), or `None`.

The `get_style_scheme`() method 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 `gtksourceview2.Marker.next`().

### gtksourceview2.Buffer.redo

    	  redo

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

### gtksourceview2.Buffer.remove_source_marks

    	  remove_source_marks
          start
          end
          categoryNone

`start` :

- a `gtk.TextIter`

`end` :

- a `gtk.TextIter`

`category` :

- category to search for or `None`.

The `remove_source_marks`() method remove all marks of category between start and end from the buffer. If category is `None`, all marks in the range will be removed.

### gtksourceview2.Buffer.set_highlight_matching_brackets

    	  set_highlight_matching_brackets
    	  highlight

`highlight` :

- `True` if you want matching brackets highlighted.

The `set_highlight_matching_brackets`() method Controls the bracket match highlighting function in the buffer. If activated, when you position your ursor over a bracket character (a parenthesis, a square bracket, etc.) the matching opening or closing bracket character will be highlighted.

### gtksourceview2.Buffer.set_highlight_syntax

    	    set_highlight_syntax
    	    highlight

`highlight` :

- `True` to enable syntax highlighting, `False` to disable it.

The `set_highlight_syntax`() method controls whether syntax is highlighted in the buffer. If highlight is `True`, the text will be highlighted according to the syntax patterns specified in the language set with `gtksourceview2.Buffer.set_language`(). If highlight is `False`, syntax highlighting is disabled and all the GtkTextTag objects that have been added by the syntax highlighting engine are removed from the buffer.

### gtksourceview2.Buffer.set_language

    	  set_language
    	  language

`language` :

- A `gtksourceview2.Language` or `None`.

The `set_language`() method associate a `gtksourceview2.Language` with the source buffer. If language is not-`None` and syntax highlighting is enabled (see `gtksourceview2.Buffer.set_highlight_syntax`()), the syntax patterns defined in language will be used to highlight the text contained in the buffer. If language is `None`, the text contained in the buffer is not highlighted.

### gtksourceview2.Buffer.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.

If max_undo_levels is -1, no limit is set.

A new action is started whenever the function `gtk.TextBuffer.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.

### gtksourceview2.Buffer.set_style_scheme

    	    set_style_scheme
    	    scheme

`scheme` :

- a style scheme.

The `set_style_scheme`() method sets the style scheme used by the buffer.

### gtksourceview2.Buffer.undo

    	  undo

The `undo`() Undoes the last user action which modified the buffer. Use `gtksourceview2.Buffer.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 `gtk.TextBuffer.begin_user_action`() and `gtk.TextBuffer.end_user_action`(), or sequences of similar edits (inserts or deletes) on the same line.

## Signals

### The "highlight-updated" gtksourceview2.Buffer 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" gtksourceview2.Buffer Signal

    	  callback
    	  sourcebuffer
    	  arg1
        user_param1
    	  ...

`sourcebuffer` :

- the sourcebuffer that received the signal

`arg1` :

- the `gtk.TextMark` 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 "source-mark-updated" signal is emitted whenever a mark is added to, moved or removed from the buffer.

## Functions

### gtksourceview2.iter_backward_search

      	  gtksourceview2.iter_backward_search
          iter
    	  str
    	  flags
    	  limit

iter :

- a `gtk.TextIter` where the search begins.

str :

- search string.

flags :

- bitmask of flags affecting the search.

limit :

- location of last possible match_start, or `None` for start of buffer.

Returns :

- start of match and end of match

The `iter_backward_search`() function is the same as the `gtksourceview2.iter_forward_search`() function, except searches backward.

### gtksourceview2.iter_forward_search

      	  gtksourceview2.iter_forward_search
          iter
    	  str
    	  flags
    	  limit

iter :

- a `gtk.TextIter` where the search begins.

str :

- search string.

flags :

- bitmask of flags affecting the search.

limit :

- bound for the search, or `None` for the end of the buffer.

Returns :

- start of match and end of match

The `iter_forward_search`() function searches forward for `str` and returns a tuple containing `gtk.TextIter` objects that point at the start and end locations of the match. The search will not continue past limit. Note that a search is a linear or O(n) operation, so you may wish to use limit to avoid locking up your UI on large buffers.

If the gtksourceview2.SOURCE_SEARCH_VISIBLE_ONLY flag is present, the match may have invisible text interspersed in str. i.e. str will be a possibly-noncontiguous subsequence of the matched range. similarly, if you specify gtksourceview2.SOURCE_SEARCH_TEXT_ONLY, the match may have pixbufs or child widgets mixed inside the matched range. If these flags are not given, the match must be exact; the special 0xFFFC character in str will match embedded pixbufs or child widgets. If you specify the gtksourceview2.SOURCE_SEARCH_CASE_INSENSITIVE flag, the text will be matched regardless of what case it is in.

Same as `gtk.TextIter.forward_search`(), but supports case insensitive searching.