manpagez: man pages & more
html files: gtksourceview
Home | html | info | man

GtkSourceBuffer

GtkSourceBuffer — Buffer object for GtkSourceView

Functions

GtkSourceBuffer * gtk_source_buffer_new ()
GtkSourceBuffer * gtk_source_buffer_new_with_language ()
void gtk_source_buffer_set_highlight_syntax ()
gboolean gtk_source_buffer_get_highlight_syntax ()
void gtk_source_buffer_set_language ()
GtkSourceLanguage * gtk_source_buffer_get_language ()
void gtk_source_buffer_set_highlight_matching_brackets ()
gboolean gtk_source_buffer_get_highlight_matching_brackets ()
void gtk_source_buffer_set_style_scheme ()
GtkSourceStyleScheme * gtk_source_buffer_get_style_scheme ()
void gtk_source_buffer_ensure_highlight ()
GtkSourceMark * gtk_source_buffer_create_source_mark ()
gboolean gtk_source_buffer_forward_iter_to_source_mark ()
gboolean gtk_source_buffer_backward_iter_to_source_mark ()
GSList * gtk_source_buffer_get_source_marks_at_line ()
GSList * gtk_source_buffer_get_source_marks_at_iter ()
void gtk_source_buffer_remove_source_marks ()
gboolean gtk_source_buffer_iter_has_context_class ()
gchar ** gtk_source_buffer_get_context_classes_at_iter ()
gboolean gtk_source_buffer_iter_forward_to_context_class_toggle ()
gboolean gtk_source_buffer_iter_backward_to_context_class_toggle ()
void gtk_source_buffer_change_case ()
gint gtk_source_buffer_get_max_undo_levels ()
void gtk_source_buffer_set_max_undo_levels ()
void gtk_source_buffer_redo ()
void gtk_source_buffer_undo ()
gboolean gtk_source_buffer_can_redo ()
gboolean gtk_source_buffer_can_undo ()
void gtk_source_buffer_begin_not_undoable_action ()
void gtk_source_buffer_end_not_undoable_action ()
GtkSourceUndoManager * gtk_source_buffer_get_undo_manager ()
void gtk_source_buffer_set_undo_manager ()

Properties

Signals

void bracket-matched Run Last
void highlight-updated Run Last
void redo Run Last
void source-mark-updated Run Last
void undo Run Last

Object Hierarchy

    GObject
    ╰── GtkTextBuffer
        ╰── GtkSourceBuffer

Includes

#include <gtksourceview/gtksource.h>

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 such as syntax highlighting and bracket matching. It also implements support for undo/redo operations, and for the search and replace.

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

Undo and Redo

A custom GtkSourceUndoManager can be implemented and set with gtk_source_buffer_set_undo_manager(). However the default implementation should be suitable for most uses. By default, actions that can be undone or redone are defined as groups of operations between a call to gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action(). In general, this happens whenever the user presses any key which modifies the buffer. But the default undo manager will try to merge similar consecutive actions, such as multiple character insertions on the same line, into one action. But, inserting a newline starts a new action.

The default undo manager remembers the "modified" state of the buffer, and restore it when an action is undone or redone. It can be useful in a text editor to know whether the file is saved. See gtk_text_buffer_get_modified() and gtk_text_buffer_set_modified().


Context Classes

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

  • comment: the region delimits a comment;

  • string: the region delimits a string;

  • no-spell-check: the region should not be spell checked.

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.

Functions

gtk_source_buffer_new ()

GtkSourceBuffer *
gtk_source_buffer_new (GtkTextTagTable *table);

Creates a new source buffer.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

buffer

a GtkSourceBuffer.

 

Returns

the GtkSourceStyleScheme associated with the buffer, or NULL.

[transfer none]


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.

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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

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

Parameters

buffer

a GtkSourceBuffer.

 

iter

a GtkTextIter.

 

context_class

class to search for.

 

Returns

whether iter has the context class.

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.

Parameters

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.

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

Parameters

buffer

a GtkSourceBuffer.

 

iter

a GtkTextIter.

[inout]

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.

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

Parameters

buffer

a GtkSourceBuffer.

 

iter

a GtkTextIter.

[inout]

context_class

the context class.

 

Returns

whether we found a context class toggle before iter

Since 2.10


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.

Parameters

buffer

a GtkSourceBuffer.

 

case_type

how to change the case.

 

start

a GtkTextIter.

 

end

a GtkTextIter.

 

Since 3.12


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.

Parameters

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.

Parameters

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.

This function emits the “redo” signal.

Parameters

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.

This function emits the “undo” signal.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

buffer

a GtkSourceBuffer.

 

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.

Parameters

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.

Parameters

buffer

a GtkSourceBuffer.

 

manager

A GtkSourceUndoManager or NULL.

[allow-none]

Types and Values

GtkSourceBuffer

typedef struct _GtkSourceBuffer GtkSourceBuffer;

enum GtkSourceBracketMatchType

Members

GTK_SOURCE_BRACKET_MATCH_NONE

there is no bracket to match.

 

GTK_SOURCE_BRACKET_MATCH_OUT_OF_RANGE

matching a bracket failed because the maximum range was reached.

 

GTK_SOURCE_BRACKET_MATCH_NOT_FOUND

a matching bracket was not found.

 

GTK_SOURCE_BRACKET_MATCH_FOUND

a matching bracket was found.

 

enum GtkSourceChangeCaseType

Members

GTK_SOURCE_CHANGE_CASE_LOWER

change case to lowercase.

 

GTK_SOURCE_CHANGE_CASE_UPPER

change case to uppercase.

 

GTK_SOURCE_CHANGE_CASE_TOGGLE

toggle case of each character.

 

GTK_SOURCE_CHANGE_CASE_TITLE

capitalize each word.

 

Since 3.12

Property Details

The “can-redo” property

  “can-redo”                 gboolean

Whether Redo operation is possible.

Flags: Read

Default value: FALSE


The “can-undo” property

  “can-undo”                 gboolean

Whether Undo operation is possible.

Flags: Read

Default value: FALSE


The “highlight-matching-brackets” property

  “highlight-matching-brackets” gboolean

Whether to highlight matching brackets in the buffer.

Flags: Read / Write

Default value: TRUE


The “highlight-syntax” property

  “highlight-syntax”         gboolean

Whether to highlight syntax in the buffer.

Flags: Read / Write

Default value: TRUE


The “language” property

  “language”                 GtkSourceLanguage *

Language object to get highlighting patterns from.

Flags: Read / Write


The “max-undo-levels” property

  “max-undo-levels”          gint

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

Flags: Read / Write

Allowed values: >= -1

Default value: 1000


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.

Flags: Read / Write


The “undo-manager” property

  “undo-manager”             GtkSourceUndoManager *

The buffer undo manager.

Flags: Read / Write / Construct

Signal Details

The “bracket-matched” signal

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

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

Parameters

buffer

a GtkSourceBuffer.

 

iter

iterator to initialize.

 

state

state of bracket matching

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 2.12


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 is updated in a certain region of the buffer . This signal is useful to be notified when a context class region is updated (e.g. the no-spell-check context class).

Parameters

buffer

the buffer that received the signal

 

start

the start of the updated region

 

end

the end of the updated region

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “redo” signal

void
user_function (GtkSourceBuffer *buffer,
               gpointer         user_data)

The ::redo signal is emitted to redo the last undo operation.

Parameters

buffer

the buffer that received the signal

 

user_data

user data set when the signal handler was connected.

 

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 .

Parameters

buffer

the buffer that received the signal

 

mark

the GtkSourceMark

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “undo” signal

void
user_function (GtkSourceBuffer *buffer,
               gpointer         user_data)

The ::undo signal is emitted to undo the last user action which modified the buffer.

Parameters

buffer

the buffer that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.