GtkSourceRegion

GtkSourceRegion — Region utility

Functions

Properties

GtkTextBuffer * buffer Read / Write / Construct Only

Types and Values

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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

GtkSourceRegion

typedef struct _GtkSourceRegion GtkSourceRegion;

struct GtkSourceRegionIter

struct GtkSourceRegionIter {
};

GtkSourceRegionIter is an opaque datatype; ignore all its fields. Initialize the iter with gtk_source_region_get_start_region_iter().

Since: 3.22

Property Details

The “buffer” property

  “buffer”                   GtkTextBuffer *

The GtkTextBuffer. The GtkSourceRegion has a weak reference to the buffer.

Owner: GtkSourceRegion

Flags: Read / Write / Construct Only

Since: 3.22

See Also

GtkTextBuffer