:right-sidebar: True

Region
===================================================================

.. currentmodule:: gi.repository.GtkSource





.. class:: Region(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`





Region utility.

A ``GtkSourceRegion`` permits to store a group of subregions of a
:obj:`~gi.repository.Gtk.TextBuffer`\. ``GtkSourceRegion`` stores the subregions with pairs of
:obj:`~gi.repository.Gtk.TextMark`\'s, so the region is still valid after insertions and deletions
in the :obj:`~gi.repository.Gtk.TextBuffer`\.

The :obj:`~gi.repository.Gtk.TextMark` for the start of a subregion has a left gravity, while the
:obj:`~gi.repository.Gtk.TextMark` for the end of a subregion has a right gravity.

The typical use-case of ``GtkSourceRegion`` is to scan a :obj:`~gi.repository.Gtk.TextBuffer` 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 :obj:`~gi.repository.Gtk.TextBuffer.signals.insert_text` and
:obj:`~gi.repository.Gtk.TextBuffer.signals.delete_range` signals to update the ``GtkSourceRegion``
accordingly.

To iterate through the subregions, you need to use a :obj:`~gi.repository.GtkSource.RegionIter`\,
for example:


.. code-block:: c
    :dedent:

    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);
    }


Constructors
------------

.. rst-class:: interim-class

.. class:: Region
   :no-index:


   .. classmethod:: new(buffer: ~gi.repository.Gtk.TextBuffer) -> ~gi.repository.GtkSource.Region

      






      :param buffer: a :obj:`~gi.repository.Gtk.TextBuffer`\.








Methods
-------

.. rst-class:: interim-class

.. class:: Region
   :no-index:


   .. method:: add_region(region_to_add: ~gi.repository.GtkSource.Region | None = None) -> None

      Adds ``region_to_add`` to ``region``\.

      ``region_to_add`` is not modified.






      :param region_to_add: the :obj:`~gi.repository.GtkSource.Region` to add to ``region``\, or :const:`None`.




   .. method:: add_subregion(_start: ~gi.repository.Gtk.TextIter, _end: ~gi.repository.Gtk.TextIter) -> None

      Adds the subregion delimited by ``_start`` and ``_end`` to ``region``\.






      :param _start: the start of the subregion.

      :param _end: the end of the subregion.




   .. method:: get_bounds() -> ~typing.Tuple[bool, ~gi.repository.Gtk.TextIter, ~gi.repository.Gtk.TextIter]

      Gets the ``start`` and ``end`` bounds of the ``region``\.









   .. method:: get_buffer() -> ~gi.repository.Gtk.TextBuffer | None

      









   .. method:: get_start_region_iter() -> ~gi.repository.GtkSource.RegionIter

      Initializes a :obj:`~gi.repository.GtkSource.RegionIter` to the first subregion of ``region``\.

      If ``region`` is empty, ``iter`` will be initialized to the end iterator.









   .. method:: intersect_region(region2: ~gi.repository.GtkSource.Region | None = None) -> ~gi.repository.GtkSource.Region | None

      Returns the intersection between ``region1`` and ``region2``\.

      ``region1`` and ``region2`` are not modified.






      :param region2: a :obj:`~gi.repository.GtkSource.Region`\, or :const:`None`.




   .. method:: intersect_subregion(_start: ~gi.repository.Gtk.TextIter, _end: ~gi.repository.Gtk.TextIter) -> ~gi.repository.GtkSource.Region | None

      Returns the intersection between ``region`` and the subregion delimited by
      ``_start`` and ``_end``\.

      ``region`` is not modified.






      :param _start: the start of the subregion.

      :param _end: the end of the subregion.




   .. method:: is_empty() -> bool

      Returns whether the ``region`` is empty.

      A :const:`None` ``region`` is considered empty.









   .. method:: subtract_region(region_to_subtract: ~gi.repository.GtkSource.Region | None = None) -> None

      Subtracts ``region_to_subtract`` from ``region``\.

      ``region_to_subtract`` is not modified.






      :param region_to_subtract: the :obj:`~gi.repository.GtkSource.Region` to subtract from
           ``region``\, or :const:`None`.




   .. method:: subtract_subregion(_start: ~gi.repository.Gtk.TextIter, _end: ~gi.repository.Gtk.TextIter) -> None

      Subtracts the subregion delimited by ``_start`` and ``_end`` from ``region``\.






      :param _start: the start of the subregion.

      :param _end: the end of the subregion.




   .. method:: to_string() -> str | None

      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.













Properties
----------

.. rst-class:: interim-class

.. class:: Region
   :no-index:
   

   .. attribute:: props.buffer
      :type: ~gi.repository.Gtk.TextBuffer

      The type of the None singleton.















Fields
------

.. rst-class:: interim-class

.. class:: Region
   :no-index:
   

   .. attribute:: parent_instance