GtkSourceRegion: libgedit-gtksourceview 300 Reference Manual

GtkSourceRegion

GtkSourceRegion — Region utility

Properties

Read / Write / Construct Only

Types and Values

	GtkSourceRegion
struct	GtkSourceRegionIter

Object Hierarchy

    GObject
    ╰── GtkSourceRegion

Includes

#include <gtksourceview/gtksource.h>

Description

A GtkSourceRegion permits to store a group of subregions of a GtkTextBuffer. GtkSourceRegion stores the subregions with pairs of GtkTextMark's, so the region is still valid after insertions and deletions in the GtkTextBuffer.

The GtkTextMark for the start of a subregion has a left gravity, while the GtkTextMark for the end of a subregion has a right gravity.

The typical use-case of GtkSourceRegion is to scan a GtkTextBuffer chunk by chunk, not the whole buffer at once to not block the user interface. The GtkSourceRegion represents in that case the remaining region to scan. You can listen to the “insert-text” and “delete-range” signals to update the GtkSourceRegion accordingly.

To iterate through the subregions, you need to use a GtkSourceRegionIter, for example:

GtkSourceRegion *region;
GtkSourceRegionIter region_iter;

gtk_source_region_get_start_region_iter (region, &region_iter);

while (!gtk_source_region_iter_is_end (&region_iter))
{
        GtkTextIter subregion_start;
        GtkTextIter subregion_end;

        if (!gtk_source_region_iter_get_subregion (&region_iter,
                                                   &subregion_start,
                                                   &subregion_end))
        {
                break;
        }

        // Do something useful with the subregion.

        gtk_source_region_iter_next (&region_iter);
}

Functions

gtk_source_region_new ()

GtkSourceRegion *
gtk_source_region_new (GtkTextBuffer *buffer);

Parameters

buffer

a GtkTextBuffer.

Returns

a new GtkSourceRegion object for buffer .

Since: 3.22

gtk_source_region_get_buffer ()

GtkTextBuffer *
gtk_source_region_get_buffer (GtkSourceRegion *region);

Parameters

region

a GtkSourceRegion.

Returns

the GtkTextBuffer.

[transfer none][nullable]

Since: 3.22

gtk_source_region_add_subregion ()

void
gtk_source_region_add_subregion (GtkSourceRegion *region,
                                 const GtkTextIter *_start,
                                 const GtkTextIter *_end);

Adds the subregion delimited by _start and _end to region .

Parameters

region	a GtkSourceRegion.
_start	the start of the subregion.
_end	the end of the subregion.

Since: 3.22

gtk_source_region_add_region ()

void
gtk_source_region_add_region (GtkSourceRegion *region,
                              GtkSourceRegion *region_to_add);

Adds region_to_add to region . region_to_add is not modified.

Parameters

region	a GtkSourceRegion.
region_to_add	the GtkSourceRegion to add to `region` , or `NULL`.	[nullable]

Since: 3.22

gtk_source_region_subtract_subregion ()

void
gtk_source_region_subtract_subregion (GtkSourceRegion *region,
                                      const GtkTextIter *_start,
                                      const GtkTextIter *_end);

Subtracts the subregion delimited by _start and _end from region .

Parameters

region	a GtkSourceRegion.
_start	the start of the subregion.
_end	the end of the subregion.

Since: 3.22

gtk_source_region_subtract_region ()

void
gtk_source_region_subtract_region (GtkSourceRegion *region,
                                   GtkSourceRegion *region_to_subtract);

Subtracts region_to_subtract from region . region_to_subtract is not modified.

Parameters

region	a GtkSourceRegion.
region_to_subtract	the GtkSourceRegion to subtract from `region` , or `NULL`.	[nullable]

Since: 3.22

gtk_source_region_intersect_subregion ()

GtkSourceRegion *
gtk_source_region_intersect_subregion (GtkSourceRegion *region,
                                       const GtkTextIter *_start,
                                       const GtkTextIter *_end);

Returns the intersection between region and the subregion delimited by _start and _end . region is not modified.

Parameters

region	a GtkSourceRegion.
_start	the start of the subregion.
_end	the end of the subregion.

Returns

the intersection as a new GtkSourceRegion.

[transfer full][nullable]

Since: 3.22

gtk_source_region_intersect_region ()

GtkSourceRegion *
gtk_source_region_intersect_region (GtkSourceRegion *region1,
                                    GtkSourceRegion *region2);

Returns the intersection between region1 and region2 . region1 and region2 are not modified.

Parameters

region1	a GtkSourceRegion, or `NULL`.	[nullable]
region2	a GtkSourceRegion, or `NULL`.	[nullable]

Returns

the intersection as a GtkSourceRegion object.

[transfer full][nullable]

Since: 3.22

gtk_source_region_is_empty ()

gboolean
gtk_source_region_is_empty (GtkSourceRegion *region);

Returns whether the region is empty. A NULL region is considered empty.

Parameters

region

a GtkSourceRegion, or NULL.

[nullable]

Returns

whether the region is empty.

Since: 3.22

gtk_source_region_get_bounds ()

gboolean
gtk_source_region_get_bounds (GtkSourceRegion *region,
                              GtkTextIter *start,
                              GtkTextIter *end);

Gets the start and end bounds of the region .

Parameters

region	a GtkSourceRegion.
start	iterator to initialize with the start of `region` , or `NULL`.	[out][optional]
end	iterator to initialize with the end of `region` , or `NULL`.	[out][optional]

Returns

TRUE if start and end have been set successfully (if non-NULL), or FALSE if the region is empty.

Since: 3.22

gtk_source_region_get_start_region_iter ()

void
gtk_source_region_get_start_region_iter
                               (GtkSourceRegion *region,
                                GtkSourceRegionIter *iter);

Initializes a GtkSourceRegionIter to the first subregion of region . If region is empty, iter will be initialized to the end iterator.

Parameters

region	a GtkSourceRegion.
iter	iterator to initialize to the first subregion.	[out]

Since: 3.22

gtk_source_region_iter_is_end ()

gboolean
gtk_source_region_iter_is_end (GtkSourceRegionIter *iter);

Parameters

iter

a GtkSourceRegionIter.

Returns

whether iter is the end iterator.

Since: 3.22

gtk_source_region_iter_next ()

gboolean
gtk_source_region_iter_next (GtkSourceRegionIter *iter);

Moves iter to the next subregion.

Parameters

iter

a GtkSourceRegionIter.

Returns

TRUE if iter moved and is dereferenceable, or FALSE if iter has been set to the end iterator.

Since: 3.22

gtk_source_region_iter_get_subregion ()

gboolean
gtk_source_region_iter_get_subregion (GtkSourceRegionIter *iter,
                                      GtkTextIter *start,
                                      GtkTextIter *end);

Gets the subregion at this iterator.

Parameters

iter	a GtkSourceRegionIter.
start	iterator to initialize with the subregion start, or `NULL`.	[out][optional]
end	iterator to initialize with the subregion end, or `NULL`.	[out][optional]

Returns

TRUE if start and end have been set successfully (if non-NULL), or FALSE if iter is the end iterator or if the region is empty.

Since: 3.22

gtk_source_region_to_string ()

gchar *
gtk_source_region_to_string (GtkSourceRegion *region);

Gets a string represention of region , for debugging purposes.

The returned string contains the character offsets of the subregions. It doesn't include a newline character at the end of the string.

Parameters

region

a GtkSourceRegion.

Returns

a string represention of region . Free with g_free() when no longer needed.

[transfer full][nullable]

Since: 3.22

Types and Values