Context Classes

It is possible to retrieve some information from the syntax highlighting engine. The default context classes that are applied to regions of a GtkSourceBuffer:

Custom language definition files can create their own context classes, since the functions like gtk_source_buffer_iter_has_context_class() take a string parameter as the context class.

GtkSourceBuffer provides an API to access the context classes: gtk_source_buffer_iter_has_context_class(), gtk_source_buffer_get_context_classes_at_iter(), gtk_source_buffer_iter_forward_to_context_class_toggle() and gtk_source_buffer_iter_backward_to_context_class_toggle().

And the “highlight-updated” signal permits to be notified when a context class region changes.

Each context class has also an associated GtkTextTag with the name gtksourceview:context-classes:<name>. For example to retrieve the GtkTextTag for the string context class, one can write:

1
2
3
4
5

GtkTextTagTable *tag_table;
GtkTextTag *tag;

tag_table = gtk_text_buffer_get_tag_table (buffer);
tag = gtk_text_tag_table_lookup (tag_table, "gtksourceview:context-classes:string");

The tag must be used for read-only purposes.

Accessing a context class via the associated GtkTextTag is less convenient than the GtkSourceBuffer API, because:

A possible use-case for accessing a context class via the associated GtkTextTag is to read the region but without adding a hard dependency on the GtkSourceView library (for example for a spell-checking library that wants to read the no-spell-check region).

gtk_source_buffer_new ()

GtkSourceBuffer *
gtk_source_buffer_new (GtkTextTagTable *table);

Creates 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().

gtk_source_buffer_create_source_tag ()

GtkTextTag *
gtk_source_buffer_create_source_tag (GtkSourceBuffer *buffer,
                                     const gchar *tag_name,
                                     const gchar *first_property_name,
                                     ...);

In short, this is the same function as gtk_text_buffer_create_tag(), but instead of creating a GtkTextTag, this function creates a GtkSourceTag.

This function creates a GtkSourceTag and adds it to the tag table for buffer . Equivalent to calling gtk_text_tag_new() and then adding the tag to the buffer’s tag table. The returned tag is owned by the buffer’s tag table, so the ref count will be equal to one.

If tag_name is NULL, the tag is anonymous.

If tag_name is non-NULL, a tag called tag_name must not already exist in the tag table for this buffer.

The first_property_name argument and subsequent arguments are a list of properties to set on the tag, as with g_object_set().

Since: 3.20

gtk_source_buffer_set_language ()

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

Associates a GtkSourceLanguage with the buffer.

Note that a GtkSourceLanguage affects not only the syntax highlighting, but also the context classes. If you want to disable just the syntax highlighting, see gtk_source_buffer_set_highlight_syntax().

The buffer holds a reference to language .

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.

gtk_source_buffer_set_style_scheme ()

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

Sets a GtkSourceStyleScheme to be used by the buffer and the view.

Note that a GtkSourceStyleScheme affects not only the syntax highlighting, but also other GtkSourceView features such as highlighting the current line, matching brackets, the line numbers, etc.

Instead of setting a NULL scheme , it is better to disable syntax highlighting with gtk_source_buffer_set_highlight_syntax(), and setting the GtkSourceStyleScheme with the "classic" or "tango" ID, because those two style schemes follow more closely the GTK+ theme (for example for the background color).

The buffer holds a reference to scheme .

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.

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

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.

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.

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.

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.

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_class is set on iter .

See the GtkSourceBuffer description for the list of default context classes.

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 .

See the GtkSourceBuffer description for the list of default context classes.

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.

See the GtkSourceBuffer description for the list of default context classes.

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.

See the GtkSourceBuffer description for the list of default context classes.

Since: 2.10

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

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.

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.

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.

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 .

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.

Since: 2.2

gtk_source_buffer_change_case ()

void
gtk_source_buffer_change_case (GtkSourceBuffer *buffer,
                               GtkSourceChangeCaseType case_type,
                               GtkTextIter *start,
                               GtkTextIter *end);

Changes the case of the text between the specified iterators.

Since: 3.12

gtk_source_buffer_join_lines ()

void
gtk_source_buffer_join_lines (GtkSourceBuffer *buffer,
                              GtkTextIter *start,
                              GtkTextIter *end);

Joins the lines of text between the specified iterators.

Since: 3.16

gtk_source_buffer_sort_lines ()

void
gtk_source_buffer_sort_lines (GtkSourceBuffer *buffer,
                              GtkTextIter *start,
                              GtkTextIter *end,
                              GtkSourceSortFlags flags,
                              gint column);

Sort the lines of text between the specified iterators.

Since: 3.18

gtk_source_buffer_set_implicit_trailing_newline ()

void
gtk_source_buffer_set_implicit_trailing_newline
                               (GtkSourceBuffer *buffer,
                                gboolean implicit_trailing_newline);

Sets whether the buffer has an implicit trailing newline.

If an explicit trailing newline is present in a GtkTextBuffer, GtkTextView shows it as an empty line. This is generally not what the user expects.

If implicit_trailing_newline is TRUE (the default value):

On the other hand, if implicit_trailing_newline is FALSE, the file's content is not modified when loaded into the buffer , and the buffer 's content is not modified when saved into a file.

Since: 3.14

gtk_source_buffer_get_implicit_trailing_newline ()

gboolean
gtk_source_buffer_get_implicit_trailing_newline
                               (GtkSourceBuffer *buffer);

Since: 3.14

GtkSourceBuffer

typedef struct _GtkSourceBuffer GtkSourceBuffer;

enum GtkSourceBracketMatchType

enum GtkSourceChangeCaseType

Since: 3.12

enum GtkSourceSortFlags

Since: 3.18

The “highlight-matching-brackets” property

  “highlight-matching-brackets” gboolean

Whether to highlight matching brackets in the buffer.

Owner: GtkSourceBuffer

Flags: Read / Write

Default value: TRUE

The “highlight-syntax” property

  “highlight-syntax”         gboolean

Whether to highlight syntax in the buffer.

Owner: GtkSourceBuffer

Flags: Read / Write

Default value: TRUE

The “implicit-trailing-newline” property

  “implicit-trailing-newline” gboolean

Whether the buffer has an implicit trailing newline. See gtk_source_buffer_set_implicit_trailing_newline().

Owner: GtkSourceBuffer

Flags: Read / Write / Construct

Default value: TRUE

Since: 3.14

The “language” property

  “language”                 GtkSourceLanguage *

Language object to get highlighting patterns from.

Owner: GtkSourceBuffer

Flags: Read / Write

The “style-scheme” property

  “style-scheme”             GtkSourceStyleScheme *

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

Owner: GtkSourceBuffer

Flags: Read / Write

The “bracket-matched” signal

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

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

The signal is emitted only when the state changes, typically when the cursor moves.

A use-case for this signal is to show messages in a GtkStatusbar.

Flags: Run Last

Since: 2.12

The “cursor-moved” signal

void
user_function (GtkSourceBuffer *buffer,
               gpointer         user_data)

The "cursor-moved" signal is emitted when then insertion mark has moved.

Flags: Run Last

Since: 5.0

The “highlight-updated” signal

void
user_function (GtkSourceBuffer *buffer,
               GtkTextIter     *start,
               GtkTextIter     *end,
               gpointer         user_data)

The ::highlight-updated signal is emitted when the syntax highlighting and context classes are updated in a certain region of the buffer .

Flags: Run Last

The “source-mark-updated” signal

void
user_function (GtkSourceBuffer *buffer,
               GtkTextMark     *mark,
               gpointer         user_data)

The ::source-mark-updated signal is emitted each time a mark is added to, moved or removed from the buffer .

Flags: Run Last