GtkSourceRegion: GtkSourceView 3 Reference Manual

## GtkSourceRegion GtkSourceRegion — Region utility |

## Functions

GtkSourceRegion * | gtk_source_region_new ()
GtkTextBuffer * | gtk_source_region_get_buffer ()
void | gtk_source_region_add_subregion ()
void | gtk_source_region_add_region ()
void | gtk_source_region_subtract_subregion ()
void | gtk_source_region_subtract_region ()
GtkSourceRegion * | gtk_source_region_intersect_subregion ()
GtkSourceRegion * | gtk_source_region_intersect_region ()
gboolean | gtk_source_region_is_empty ()
gboolean | gtk_source_region_get_bounds ()
void | gtk_source_region_get_start_region_iter ()
gboolean | gtk_source_region_iter_is_end ()
gboolean | gtk_source_region_iter_next ()
gboolean | gtk_source_region_iter_get_subregion ()
gchar * | gtk_source_region_to_string ()

## Properties

GtkTextBuffer * | buffer | 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:

    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.

Flags: Read / Write / Construct Only

Since: 3.22

## See Also

GtkTextBuffer