GtkSourceBuffer

## GtkSourceBuffer GtkSourceBuffer — Text buffer object for GtkSourceView |

## Synopsis

    #include <gtksourceview/gtksourcebuffer.h>

                GtkSourceBuffer;
    GtkSourceBuffer* gtk_source_buffer_new      (GtkSourceTagTable *table);
    GtkSourceBuffer* gtk_source_buffer_new_with_language
                                                (GtkSourceLanguage *language);
    gboolean    gtk_source_buffer_get_check_brackets
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_set_check_brackets
                                                (GtkSourceBuffer *buffer,
                                                 gboolean check_brackets);
    void        gtk_source_buffer_set_bracket_match_style
                                                (GtkSourceBuffer *source_buffer,
                                                 const GtkSourceTagStyle *style);
    gboolean    gtk_source_buffer_get_highlight (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_set_highlight (GtkSourceBuffer *buffer,
                                                 gboolean highlight);
    gint        gtk_source_buffer_get_max_undo_levels
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_set_max_undo_levels
                                                (GtkSourceBuffer *buffer,
                                                 gint max_undo_levels);
    GtkSourceLanguage* gtk_source_buffer_get_language
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_set_language  (GtkSourceBuffer *buffer,
                                                 GtkSourceLanguage *language);
    gunichar    gtk_source_buffer_get_escape_char
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_set_escape_char
                                                (GtkSourceBuffer *buffer,
                                                 gunichar escape_char);
    gboolean    gtk_source_buffer_can_undo      (GtkSourceBuffer *buffer);
    gboolean    gtk_source_buffer_can_redo      (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_undo          (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_redo          (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_begin_not_undoable_action
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_end_not_undoable_action
                                                (GtkSourceBuffer *buffer);
    GtkSourceMarker* gtk_source_buffer_create_marker
                                                (GtkSourceBuffer *buffer,
                                                 const gchar *name,
                                                 const gchar *type,
                                                 const GtkTextIter *where);
    void        gtk_source_buffer_move_marker   (GtkSourceBuffer *buffer,
                                                 GtkSourceMarker *marker,
                                                 const GtkTextIter *where);
    void        gtk_source_buffer_delete_marker (GtkSourceBuffer *buffer,
                                                 GtkSourceMarker *marker);
    GtkSourceMarker* gtk_source_buffer_get_marker
                                                (GtkSourceBuffer *buffer,
                                                 const gchar *name);
    GSList*     gtk_source_buffer_get_markers_in_region
                                                (GtkSourceBuffer *buffer,
                                                 const GtkTextIter *begin,
                                                 const GtkTextIter *end);
    GtkSourceMarker* gtk_source_buffer_get_first_marker
                                                (GtkSourceBuffer *buffer);
    GtkSourceMarker* gtk_source_buffer_get_last_marker
                                                (GtkSourceBuffer *buffer);
    void        gtk_source_buffer_get_iter_at_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *iter,
                                                 GtkSourceMarker *marker);
    GtkSourceMarker* gtk_source_buffer_get_next_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *iter);
    GtkSourceMarker* gtk_source_buffer_get_prev_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *iter);

## Object Hierarchy

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

## Properties

      "check-brackets"       gboolean              : Read / Write
      "escape-char"          guint                 : Read / Write
      "highlight"            gboolean              : Read / Write
      "language"             GtkSourceLanguage     : Read / Write
      "max-undo-levels"      gint                  : Read / Write

## Signal Prototypes

    "can-redo"  void        user_function      (GtkSourceBuffer *sourcebuffer,
                                                gboolean arg1,
                                                gpointer user_data);
    "can-undo"  void        user_function      (GtkSourceBuffer *sourcebuffer,
                                                gboolean arg1,
                                                gpointer user_data);
    "highlight-updated"
                void        user_function      (GtkSourceBuffer *sourcebuffer,
                                                GtkTextIter *arg1,
                                                GtkTextIter *arg2,
                                                gpointer user_data);
    "marker-updated"
                void        user_function      (GtkSourceBuffer *sourcebuffer,
                                                GtkTextIter *arg1,
                                                gpointer user_data);

## Description

The GtkSourceBuffer object is the model for GtkSourceView widgets. It extends the GtkTextBuffer 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 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()`. This can be useful if you're not using GtkSourceLanguage objects to set the highlighting patterns, and instead you're manually adding GtkSourceTag objects to the buffer's tag table.

## Details

### GtkSourceBuffer

    typedef struct _GtkSourceBuffer GtkSourceBuffer;

### gtk_source_buffer_new ()

    GtkSourceBuffer* gtk_source_buffer_new      (GtkSourceTagTable *table);

Creates a new source buffer.

`table` : | a GtkSourceTagTable, or `NULL` to create a new one.
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 the default tag table and then calling `gtk_source_buffer_set_language()`.

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

### gtk_source_buffer_get_check_brackets ()

    gboolean    gtk_source_buffer_get_check_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_check_brackets ()

    void        gtk_source_buffer_set_check_brackets
                                                (GtkSourceBuffer *buffer,
                                                 gboolean check_brackets);

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.
`check_brackets` : | `TRUE` if you want matching brackets highlighted.

### gtk_source_buffer_set_bracket_match_style ()

    void        gtk_source_buffer_set_bracket_match_style
                                                (GtkSourceBuffer *source_buffer,
                                                 const GtkSourceTagStyle *style);

Sets the style used for highlighting matching brackets.

`source_buffer` : | a GtkSourceBuffer.
`style` : | the GtkSourceTagStyle specifying colors and text attributes.

### gtk_source_buffer_get_highlight ()

    gboolean    gtk_source_buffer_get_highlight (GtkSourceBuffer *buffer);

Determines whether text highlighting is activated in the source buffer.

`buffer` : | a GtkSourceBuffer.
Returns : | `TRUE` if highlighting is enabled.

### gtk_source_buffer_set_highlight ()

    void        gtk_source_buffer_set_highlight (GtkSourceBuffer *buffer,
                                                 gboolean highlight);

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 `gtk_source_buffer_set_language()` or by adding individual GtkSourceTag tags to the buffer's tag table). Otherwise, any current highlighted text will be restored to the default buffer style.

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

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

`buffer` : | a GtkSourceBuffer.
`highlight` : | `TRUE` if you want to activate highlighting.

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

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

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_get_language ()

    GtkSourceLanguage* gtk_source_buffer_get_language
                                                (GtkSourceBuffer *buffer);

Determines the GtkSourceLanguage used by the buffer. The returned object should not be unreferenced by the user.

`buffer` : | a GtkSourceBuffer.
Returns : | the GtkSourceLanguage set by `gtk_source_buffer_set_language()`, or `NULL`.

### gtk_source_buffer_set_language ()

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

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

`buffer` : | a GtkSourceBuffer.
`language` : | a GtkSourceLanguage to set, or `NULL`.

### gtk_source_buffer_get_escape_char ()

    gunichar    gtk_source_buffer_get_escape_char
                                                (GtkSourceBuffer *buffer);

Determines the escaping character used by the source buffer highlighting engine.

`buffer` : | a GtkSourceBuffer.
Returns : | the UTF-8 character for the escape character the buffer is using.

### gtk_source_buffer_set_escape_char ()

    void        gtk_source_buffer_set_escape_char
                                                (GtkSourceBuffer *buffer,
                                                 gunichar escape_char);

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 GtkSyntaxTag tags).

`buffer` : | a GtkSourceBuffer.
`escape_char` : | the escape character the buffer should use.

### 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_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_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_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_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_create_marker ()

    GtkSourceMarker* gtk_source_buffer_create_marker
                                                (GtkSourceBuffer *buffer,
                                                 const gchar *name,
                                                 const gchar *type,
                                                 const GtkTextIter *where);

Creates a marker in the `buffer` of type `type`. A marker is semantically very similar to a GtkTextMark, except it has a type which is used by the GtkSourceView 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 GtkTextMark, 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 GtkTextMark, a GtkSourceMarker can be anonymous if the passed `name` is `NULL`. 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..

`buffer` : | a GtkSourceBuffer.
`name` : | the name of the marker, or `NULL`.
`type` : | a string defining the marker type, or `NULL`.
`where` : | location to place the marker.
Returns : | a new GtkSourceMarker, owned by the buffer.

### gtk_source_buffer_move_marker ()

    void        gtk_source_buffer_move_marker   (GtkSourceBuffer *buffer,
                                                 GtkSourceMarker *marker,
                                                 const GtkTextIter *where);

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

`buffer` : | a GtkSourceBuffer.
`marker` : | a GtkSourceMarker in `buffer`.
`where` : | the new location for the marker.

### gtk_source_buffer_delete_marker ()

    void        gtk_source_buffer_delete_marker (GtkSourceBuffer *buffer,
                                                 GtkSourceMarker *marker);

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

`buffer` : | a GtkSourceBuffer.
`marker` : | a GtkSourceMarker in the `buffer`.

### gtk_source_buffer_get_marker ()

    GtkSourceMarker* gtk_source_buffer_get_marker
                                                (GtkSourceBuffer *buffer,
                                                 const gchar *name);

Looks up the GtkSourceMarker named `name` in `buffer`, returning `NULL` if it doesn't exists.

`buffer` : | a GtkSourceBuffer.
`name` : | name of the marker to retrieve.
Returns : | the GtkSourceMarker whose name is `name`, or `NULL`.

### gtk_source_buffer_get_markers_in_region ()

    GSList*     gtk_source_buffer_get_markers_in_region
                                                (GtkSourceBuffer *buffer,
                                                 const GtkTextIter *begin,
                                                 const GtkTextIter *end);

Returns an ordered (by position) GSList of GtkSourceMarker objects inside the region delimited by the GtkTextIter `begin` and `end`. The iters may be in any order.

`buffer` : | a GtkSourceBuffer.
`begin` : | beginning of the range.
`end` : | end of the range.
Returns : | a GSList of the GtkSourceMarker inside the range.

### gtk_source_buffer_get_first_marker ()

    GtkSourceMarker* gtk_source_buffer_get_first_marker
                                                (GtkSourceBuffer *buffer);

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

`buffer` : | a GtkSourceBuffer.
Returns : | a reference to the first GtkSourceMarker, or `NULL` if there are no markers in the buffer.

### gtk_source_buffer_get_last_marker ()

    GtkSourceMarker* gtk_source_buffer_get_last_marker
                                                (GtkSourceBuffer *buffer);

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

`buffer` : | a GtkSourceBuffer.
Returns : | a reference to the last GtkSourceMarker, or `NULL` if there are no markers in the buffer.

### gtk_source_buffer_get_iter_at_marker ()

    void        gtk_source_buffer_get_iter_at_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *iter,
                                                 GtkSourceMarker *marker);

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

`buffer` : | a GtkSourceBuffer.
`iter` : | a GtkTextIter to initialize.
`marker` : | a GtkSourceMarker of `buffer`.

### gtk_source_buffer_get_next_marker ()

    GtkSourceMarker* gtk_source_buffer_get_next_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *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 `gtk_source_marker_next()`.

`buffer` : | a GtkSourceBuffer.
`iter` : | the location to start searching from.
Returns : | the GtkSourceMarker nearest to the right of `iter`, or `NULL` if there are no more markers after `iter`.

### gtk_source_buffer_get_prev_marker ()

    GtkSourceMarker* gtk_source_buffer_get_prev_marker
                                                (GtkSourceBuffer *buffer,
                                                 GtkTextIter *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 last one (from the internal linked list), even if starting the search exactly at its location. You can get the others using `gtk_source_marker_prev()`.

`buffer` : | a GtkSourceBuffer.
`iter` : | the location to start searching from.
Returns : | the GtkSourceMarker nearest to the left of `iter`, or `NULL` if there are no more markers before `iter`.

## Properties

### The "`check-brackets`" property

      "check-brackets"       gboolean              : Read / Write

Whether to check and highlight matching brackets.

Default value: TRUE

### The "`escape-char`" property

      "escape-char"          guint                 : Read / Write

Escaping character for syntax patterns.

Default value: 0

### The "`highlight`" property

      "highlight"            gboolean              : Read / Write

Whether to highlight syntax in the buffer.

Default value: FALSE

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

Allowed values: [0,200]

Default value: 25

## Signals

### The "can-redo" signal

    void        user_function                  (GtkSourceBuffer *sourcebuffer,
                                                gboolean arg1,
                                                gpointer user_data);

Emitted whenever there is a change in the buffer's ability to redo an operation.

`sourcebuffer` : | the object which received the signal.
`arg1` : | TRUE if the buffer can now perform an redo.
`user_data` : | user data set when the signal handler was connected.

### The "can-undo" signal

    void        user_function                  (GtkSourceBuffer *sourcebuffer,
                                                gboolean arg1,
                                                gpointer user_data);

Emitted whenever there is a change in the buffer's ability to undo an operation.

`sourcebuffer` : | the object which received the signal.
`arg1` : | TRUE if the buffer can now perform an undo.
`user_data` : | user data set when the signal handler was connected.

### The "highlight-updated" signal

    void        user_function                  (GtkSourceBuffer *sourcebuffer,
                                                GtkTextIter *arg1,
                                                GtkTextIter *arg2,
                                                gpointer user_data);

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.

`sourcebuffer` : | the object which received the signal.
`arg1` : | GtkTextIter at the start of the updated region.
`arg2` : | GtkTextIter at the end of the updated region.
`user_data` : | user data set when the signal handler was connected.

### The "marker-updated" signal

    void        user_function                  (GtkSourceBuffer *sourcebuffer,
                                                GtkTextIter *arg1,
                                                gpointer user_data);

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.

Note that moving a marker causes the emission of this signal twice: one for the old location and one for the new.

`sourcebuffer` : | the object which received the signal.
`arg1` : | GtkTextIter at the location where the change occurred.
`user_data` : | user data set when the signal handler was connected.

## See Also

There is an introduction document describing the basic concepts of the buffer/view interactions.

Check GtkTextBuffer for information about the base buffer; and GtkSourceView for examples on setting up the buffer to be displayed in a view widget.