GtkSourceBuffer

## GtkSourceBuffer GtkSourceBuffer — Buffer object for GtkSourceView |

## Synopsis

    #include <gtksourceview/gtksourcebuffer.h>

    struct              GtkSourceBuffer;
    GtkSourceBuffer *   gtk_source_buffer_new               (GtkTextTagTable *table);
    GtkSourceBuffer *   gtk_source_buffer_new_with_language (GtkSourceLanguage *language);
    void                gtk_source_buffer_set_highlight_syntax
                                                            (GtkSourceBuffer *buffer,
                                                             gboolean highlight);
    gboolean            gtk_source_buffer_get_highlight_syntax
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_set_language      (GtkSourceBuffer *buffer,
                                                             GtkSourceLanguage *language);
    GtkSourceLanguage * gtk_source_buffer_get_language      (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_set_highlight_matching_brackets
                                                            (GtkSourceBuffer *buffer,
                                                             gboolean highlight);
    gboolean            gtk_source_buffer_get_highlight_matching_brackets
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_set_style_scheme  (GtkSourceBuffer *buffer,
                                                             GtkSourceStyleScheme *scheme);
    GtkSourceStyleScheme * gtk_source_buffer_get_style_scheme
                                                            (GtkSourceBuffer *buffer);
    gint                gtk_source_buffer_get_max_undo_levels
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_set_max_undo_levels
                                                            (GtkSourceBuffer *buffer,
                                                             gint max_undo_levels);
    void                gtk_source_buffer_redo              (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_undo              (GtkSourceBuffer *buffer);
    gboolean            gtk_source_buffer_can_redo          (GtkSourceBuffer *buffer);
    gboolean            gtk_source_buffer_can_undo          (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_begin_not_undoable_action
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_end_not_undoable_action
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_ensure_highlight  (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *start,
                                                             const GtkTextIter *end);
    GtkSourceMark *     gtk_source_buffer_create_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             const gchar *name,
                                                             const gchar *category,
                                                             const GtkTextIter *where);
    gboolean            gtk_source_buffer_forward_iter_to_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);
    gboolean            gtk_source_buffer_backward_iter_to_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);
    GSList *            gtk_source_buffer_get_source_marks_at_line
                                                            (GtkSourceBuffer *buffer,
                                                             gint line,
                                                             const gchar *category);
    GSList *            gtk_source_buffer_get_source_marks_at_iter
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);
    void                gtk_source_buffer_remove_source_marks
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *start,
                                                             const GtkTextIter *end,
                                                             const gchar *category);
    gboolean            gtk_source_buffer_iter_has_context_class
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *iter,
                                                             const gchar *context_class);
    gchar **            gtk_source_buffer_get_context_classes_at_iter
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *iter);
    gboolean            gtk_source_buffer_iter_forward_to_context_class_toggle
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *context_class);
    gboolean            gtk_source_buffer_iter_backward_to_context_class_toggle
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *context_class);
    GtkSourceUndoManager * gtk_source_buffer_get_undo_manager
                                                            (GtkSourceBuffer *buffer);
    void                gtk_source_buffer_set_undo_manager  (GtkSourceBuffer *buffer,
                                                             GtkSourceUndoManager *manager);

## Object Hierarchy

      GObject
       +----GtkTextBuffer
             +----GtkSourceBuffer

## Properties

      "can-redo"                 gboolean              : Read
      "can-undo"                 gboolean              : Read
      "highlight-matching-brackets" gboolean              : Read / Write
      "highlight-syntax"         gboolean              : Read / Write
      "language"                 GtkSourceLanguage*    : Read / Write
      "max-undo-levels"          gint                  : Read / Write
      "style-scheme"             GtkSourceStyleScheme*  : Read / Write
      "undo-manager"             GtkSourceUndoManager*  : Read / Write / Construct

## Signals

      "bracket-matched"                                : Run Last
      "highlight-updated"                              : Run Last
      "redo"                                           : Run Last
      "source-mark-updated"                            : Run Last
      "undo"                                           : Run Last

## Description

The GtkSourceBuffer object is the model for GtkSourceView widgets. It extends the GtkTextBuffer object by adding features useful to display and edit source code as syntax highlighting and bracket matching. It also implements support for undo/redo operations.

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

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

## Details

### struct GtkSourceBuffer

    struct GtkSourceBuffer;

### gtk_source_buffer_new ()

    GtkSourceBuffer *   gtk_source_buffer_new               (GtkTextTagTable *table);

Creates a new source buffer.

`table` : | a GtkTextTagTable, or `NULL` to create a new one. [allow-none]
Returns : | a new source buffer.

### gtk_source_buffer_new_with_language ()

    GtkSourceBuffer *   gtk_source_buffer_new_with_language (GtkSourceLanguage *language);

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

`language` : | a GtkSourceLanguage.
Returns : | a new source buffer which will highlight text according to the highlighting patterns in `language`.

### gtk_source_buffer_set_highlight_syntax ()

    void                gtk_source_buffer_set_highlight_syntax
                                                            (GtkSourceBuffer *buffer,
                                                             gboolean highlight);

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 `gtk_source_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.

`buffer` : | a GtkSourceBuffer.
`highlight` : | `TRUE` to enable syntax highlighting, `FALSE` to disable it.

### gtk_source_buffer_get_highlight_syntax ()

    gboolean            gtk_source_buffer_get_highlight_syntax
                                                            (GtkSourceBuffer *buffer);

Determines whether syntax highlighting is activated in the source buffer.

`buffer` : | a GtkSourceBuffer.
Returns : | `TRUE` if syntax highlighting is enabled, `FALSE` otherwise.

### gtk_source_buffer_set_language ()

    void                gtk_source_buffer_set_language      (GtkSourceBuffer *buffer,
                                                             GtkSourceLanguage *language);

Associate a GtkSourceLanguage with the buffer. If `language` is not-`NULL` and syntax highlighting is enabled (see `gtk_source_buffer_set_highlight_syntax()`), the syntax patterns defined in `language` will be used to highlight the text contained in the buffer. If `language` is `NULL`, the text contained in the buffer is not highlighted.

The buffer holds a reference to `language`.

`buffer` : | a GtkSourceBuffer.
`language` : | a GtkSourceLanguage to set, or `NULL`. [allow-none]

### gtk_source_buffer_get_language ()

    GtkSourceLanguage * gtk_source_buffer_get_language      (GtkSourceBuffer *buffer);

Returns the GtkSourceLanguage associated with the buffer, see `gtk_source_buffer_set_language()`. The returned object should not be unreferenced by the user.

`buffer` : | a GtkSourceBuffer.
Returns : | the GtkSourceLanguage associated with the buffer, or `NULL`. [transfer none]

### gtk_source_buffer_set_highlight_matching_brackets ()

    void                gtk_source_buffer_set_highlight_matching_brackets
                                                            (GtkSourceBuffer *buffer,
                                                             gboolean highlight);

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 `gtk_source_buffer_set_bracket_match_style()` function.

`buffer` : | a GtkSourceBuffer.
`highlight` : | `TRUE` if you want matching brackets highlighted.

### gtk_source_buffer_get_highlight_matching_brackets ()

    gboolean            gtk_source_buffer_get_highlight_matching_brackets
                                                            (GtkSourceBuffer *buffer);

Determines whether bracket match highlighting is activated for the source buffer.

`buffer` : | a GtkSourceBuffer.
Returns : | `TRUE` if the source buffer will highlight matching brackets.

### gtk_source_buffer_set_style_scheme ()

    void                gtk_source_buffer_set_style_scheme  (GtkSourceBuffer *buffer,
                                                             GtkSourceStyleScheme *scheme);

Sets style scheme used by the buffer. If `scheme` is `NULL` no style scheme is used.

`buffer` : | a GtkSourceBuffer.
`scheme` : | a GtkSourceStyleScheme or `NULL`. [allow-none]

### gtk_source_buffer_get_style_scheme ()

    GtkSourceStyleScheme * gtk_source_buffer_get_style_scheme
                                                            (GtkSourceBuffer *buffer);

Returns the GtkSourceStyleScheme associated with the buffer, see `gtk_source_buffer_set_style_scheme()`. The returned object should not be unreferenced by the user.

`buffer` : | a GtkSourceBuffer.
Returns : | the GtkSourceStyleScheme associated with the buffer, or `NULL`. [transfer none]

### gtk_source_buffer_get_max_undo_levels ()

    gint                gtk_source_buffer_get_max_undo_levels
                                                            (GtkSourceBuffer *buffer);

Determines the number of undo levels the buffer will track for buffer edits.

`buffer` : | a GtkSourceBuffer.
Returns : | the maximum number of possible undo levels or -1 if no limit is set.

### gtk_source_buffer_set_max_undo_levels ()

    void                gtk_source_buffer_set_max_undo_levels
                                                            (GtkSourceBuffer *buffer,
                                                             gint max_undo_levels);

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_text_buffer_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.

`buffer` : | a GtkSourceBuffer.
`max_undo_levels` : | the desired maximum number of undo levels.

### gtk_source_buffer_redo ()

    void                gtk_source_buffer_redo              (GtkSourceBuffer *buffer);

Redoes the last undo operation. Use `gtk_source_buffer_can_redo()` to check whether a call to this function will have any effect.

`buffer` : | a GtkSourceBuffer.

### gtk_source_buffer_undo ()

    void                gtk_source_buffer_undo              (GtkSourceBuffer *buffer);

Undoes the last user action which modified the buffer. Use `gtk_source_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_text_buffer_begin_user_action()` and `gtk_text_buffer_end_user_action()`, or sequences of similar edits (inserts or deletes) on the same line.

`buffer` : | a GtkSourceBuffer.

### gtk_source_buffer_can_redo ()

    gboolean            gtk_source_buffer_can_redo          (GtkSourceBuffer *buffer);

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

`buffer` : | a GtkSourceBuffer.
Returns : | `TRUE` if a redo is possible.

### gtk_source_buffer_can_undo ()

    gboolean            gtk_source_buffer_can_undo          (GtkSourceBuffer *buffer);

Determines whether a source buffer can undo the last action.

`buffer` : | a GtkSourceBuffer.
Returns : | `TRUE` if it's possible to undo the last action.

### gtk_source_buffer_begin_not_undoable_action ()

    void                gtk_source_buffer_begin_not_undoable_action
                                                            (GtkSourceBuffer *buffer);

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 `gtk_source_buffer_begin_not_undoable_action()` / `gtk_source_buffer_end_not_undoable_action()` blocks.

`buffer` : | a GtkSourceBuffer.

### gtk_source_buffer_end_not_undoable_action ()

    void                gtk_source_buffer_end_not_undoable_action
                                                            (GtkSourceBuffer *buffer);

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.

`buffer` : | a GtkSourceBuffer.

### gtk_source_buffer_ensure_highlight ()

    void                gtk_source_buffer_ensure_highlight  (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *start,
                                                             const GtkTextIter *end);

Forces buffer to analyze and highlight the given area synchronously.

### Note

This is a potentially slow operation and should be used only when you need to make sure that some text not currently visible is highlighted, for instance before printing.

`buffer` : | a GtkSourceBuffer.
`start` : | start of the area to highlight.
`end` : | end of the area to highlight.

### gtk_source_buffer_create_source_mark ()

    GtkSourceMark *     gtk_source_buffer_create_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             const gchar *name,
                                                             const gchar *category,
                                                             const GtkTextIter *where);

Creates a source mark in the `buffer` of category `category`. A source mark is a GtkTextMark but organised into categories. Depending on the category a pixbuf can be specified that will be displayed along the line of the mark.

Like a GtkTextMark, a GtkSourceMark can be anonymous if the passed `name` is `NULL`. Also, the buffer owns the marks 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.

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

`buffer` : | a GtkSourceBuffer.
`name` : | the name of the mark, or `NULL`. [allow-none]
`category` : | a string defining the mark category.
`where` : | location to place the mark.
Returns : | a new GtkSourceMark, owned by the buffer. [transfer none]

Since 2.2

### gtk_source_buffer_forward_iter_to_source_mark ()

    gboolean            gtk_source_buffer_forward_iter_to_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);

Moves `iter` to the position of the next GtkSourceMark of the given `category`. Returns `TRUE` if `iter` was moved. If `category` is NULL, the next source mark can be of any category.

`buffer` : | a GtkSourceBuffer.
`iter` : | an iterator.
`category` : | category to search for, or `NULL`. [allow-none]
Returns : | whether `iter` was moved.

Since 2.2

### gtk_source_buffer_backward_iter_to_source_mark ()

    gboolean            gtk_source_buffer_backward_iter_to_source_mark
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);

Moves `iter` to the position of the previous GtkSourceMark of the given category. Returns `TRUE` if `iter` was moved. If `category` is NULL, the previous source mark can be of any category.

`buffer` : | a GtkSourceBuffer.
`iter` : | an iterator.
`category` : | category to search for, or `NULL`. [allow-none]
Returns : | whether `iter` was moved.

Since 2.2

### gtk_source_buffer_get_source_marks_at_line ()

    GSList *            gtk_source_buffer_get_source_marks_at_line
                                                            (GtkSourceBuffer *buffer,
                                                             gint line,
                                                             const gchar *category);

Returns the list of marks of the given category at `line`. If `category` is NULL, all marks at `line` are returned.

`buffer` : | a GtkSourceBuffer.
`line` : | a line number.
`category` : | category to search for, or `NULL`. [allow-none]
Returns : | a newly allocated GSList. [element-type GtkSource.Mark][transfer container]

Since 2.2

### gtk_source_buffer_get_source_marks_at_iter ()

    GSList *            gtk_source_buffer_get_source_marks_at_iter
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *category);

Returns the list of marks of the given category at `iter`. If `category` is `NULL` it returns all marks at `iter`.

`buffer` : | a GtkSourceBuffer.
`iter` : | an iterator.
`category` : | category to search for, or `NULL`. [allow-none]
Returns : | a newly allocated GSList. [element-type GtkSource.Mark][transfer container]

Since 2.2

### gtk_source_buffer_remove_source_marks ()

    void                gtk_source_buffer_remove_source_marks
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *start,
                                                             const GtkTextIter *end,
                                                             const gchar *category);

Remove all marks of `category` between `start` and `end` from the buffer. If `category` is NULL, all marks in the range will be removed.

`buffer` : | a GtkSourceBuffer.
`start` : | a GtkTextIter.
`end` : | a GtkTextIter.
`category` : | category to search for, or `NULL`. [allow-none]

Since 2.2

### gtk_source_buffer_iter_has_context_class ()

    gboolean            gtk_source_buffer_iter_has_context_class
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *iter,
                                                             const gchar *context_class);

Check if the class `context_klass` is set on `iter`.

`buffer` : | a GtkSourceBuffer.
`iter` : | a GtkTextIter.
`context_class` : | class to search for.

Since 2.10

### gtk_source_buffer_get_context_classes_at_iter ()

    gchar **            gtk_source_buffer_get_context_classes_at_iter
                                                            (GtkSourceBuffer *buffer,
                                                             const GtkTextIter *iter);

Get all defined context classes at `iter`.

`buffer` : | a GtkSourceBuffer.
`iter` : | a GtkTextIter.
Returns : | a new `NULL` terminated array of context class names. Use `g_strfreev()` to free the array if it is no longer needed. [array zero-terminated=1][transfer full]

Since 2.10

### gtk_source_buffer_iter_forward_to_context_class_toggle ()

    gboolean            gtk_source_buffer_iter_forward_to_context_class_toggle
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *context_class);

Moves forward to the next toggle (on or off) of the context class. If no matching context class toggles are found, returns `FALSE`, otherwise `TRUE`. Does not return toggles located at `iter`, only toggles after `iter`. Sets `iter` to the location of the toggle, or to the end of the buffer if no toggle is found.

`buffer` : | a GtkSourceBuffer.
`iter` : | a GtkTextIter.
`context_class` : | the context class.
Returns : | whether we found a context class toggle after `iter`

Since 2.10

### gtk_source_buffer_iter_backward_to_context_class_toggle ()

    gboolean            gtk_source_buffer_iter_backward_to_context_class_toggle
                                                            (GtkSourceBuffer *buffer,
                                                             GtkTextIter *iter,
                                                             const gchar *context_class);

Moves backward to the next toggle (on or off) of the context class. If no matching context class toggles are found, returns `FALSE`, otherwise `TRUE`. Does not return toggles located at `iter`, only toggles after `iter`. Sets `iter` to the location of the toggle, or to the end of the buffer if no toggle is found.

`buffer` : | a GtkSourceBuffer.
`iter` : | a GtkTextIter.
`context_class` : | the context class.
Returns : | whether we found a context class toggle before `iter`

Since 2.10

### gtk_source_buffer_get_undo_manager ()

    GtkSourceUndoManager * gtk_source_buffer_get_undo_manager
                                                            (GtkSourceBuffer *buffer);

Returns the GtkSourceUndoManager associated with the buffer, see `gtk_source_buffer_set_undo_manager()`. The returned object should not be unreferenced by the user.

`buffer` : | a GtkSourceBuffer.
Returns : | the GtkSourceUndoManager associated with the buffer, or `NULL`. [transfer none]

### gtk_source_buffer_set_undo_manager ()

    void                gtk_source_buffer_set_undo_manager  (GtkSourceBuffer *buffer,
                                                             GtkSourceUndoManager *manager);

Set the buffer undo manager. If `manager` is `NULL` the default undo manager will be set.

`buffer` : | a GtkSourceBuffer.
`manager` : | A GtkSourceUndoManager or `NULL`. [allow-none]

## Property Details

### The `"can-redo"` property

      "can-redo"                 gboolean              : Read

Whether Redo operation is possible.

Default value: FALSE

### The `"can-undo"` property

      "can-undo"                 gboolean              : Read

Whether Undo operation is possible.

Default value: FALSE

### The `"highlight-matching-brackets"` property

      "highlight-matching-brackets" gboolean              : Read / Write

Whether to highlight matching brackets in the buffer.

Default value: TRUE

### The `"highlight-syntax"` property

      "highlight-syntax"         gboolean              : Read / Write

Whether to highlight syntax in the buffer.

Default value: TRUE

### The `"language"` property

      "language"                 GtkSourceLanguage*    : Read / Write

Language object to get highlighting patterns from.

### The `"max-undo-levels"` property

      "max-undo-levels"          gint                  : Read / Write

Number of undo levels for the buffer. -1 means no limit. This property will only affect the default undo manager.

Allowed values: >= G_MAXULONG

Default value: 1000

### The `"style-scheme"` property

      "style-scheme"             GtkSourceStyleScheme*  : Read / Write

Style scheme. It contains styles for syntax highlighting, optionally foreground, background, cursor color, current line color, and matching brackets style.

### The `"undo-manager"` property

      "undo-manager"             GtkSourceUndoManager*  : Read / Write / Construct

The buffer undo manager.

## Signal Details

### The `"bracket-matched"` signal

    void                user_function                      (GtkSourceBuffer          *buffer,
                                                            GtkTextIter              *iter,
                                                            GtkSourceBracketMatchType state,
                                                            gpointer                  user_data)      : Run Last

Sets `iter` to a valid iterator pointing to the matching bracket if `state` is GTK_SOURCE_BRACKET_MATCH_FOUND. Otherwise `iter` is meaningless.

`buffer` : | a GtkSourceBuffer.
`iter` : | iterator to initialize.
`state` : | state of bracket matching
`user_data` : | user data set when the signal handler was connected.

Since 2.12

### The `"highlight-updated"` signal

    void                user_function                      (GtkSourceBuffer *sourcebuffer,
                                                            GtkTextIter     *arg1,
                                                            GtkTextIter     *arg2,
                                                            gpointer         user_data)         : Run Last

### The `"redo"` signal

    void                user_function                      (GtkSourceBuffer *sourcebuffer,
                                                            gpointer         user_data)         : Run Last

### The `"source-mark-updated"` signal

    void                user_function                      (GtkSourceBuffer *buffer,
                                                            GtkTextMark     *arg1,
                                                            gpointer         user_data)      : Run Last

The ::source_mark_updated signal is emitted each time a mark is added to, moved or removed from the `buffer`.

`buffer` : | the buffer that received the signal
`user_data` : | user data set when the signal handler was connected.

### The `"undo"` signal

    void                user_function                      (GtkSourceBuffer *sourcebuffer,
                                                            gpointer         user_data)         : Run Last

## See Also

GtkTextBuffer,GtkSourceView