:right-sidebar: True

Inscription
===================================================================

.. currentmodule:: gi.repository.Gtk


.. versionadded:: 4.8




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


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.AccessibleText`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



``GtkInscription`` is a widget to show text in a predefined area.

You likely want to use ``GtkLabel`` instead as this widget is intended only
for a small subset of use cases. The main scenario envisaged is inside lists
such as ``GtkColumnView``.

While a ``GtkLabel`` sizes itself depending on the text that is displayed,
``GtkInscription`` is given a size and inscribes the given text into that
space as well as it can.

Users of this widget should take care to plan behaviour for the common case
where the text doesn't fit exactly in the allocated space.



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

.. rst-class:: interim-class

.. class:: Inscription
   :no-index:


   .. classmethod:: new(text: str | None = None) -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkInscription`` with the given text.



      .. versionadded:: 4.8





      :param text: The text to display.









Methods
-------

.. rst-class:: interim-class

.. class:: Inscription
   :no-index:


   .. method:: get_attributes() -> ~gi.repository.Pango.AttrList | None

      Gets the inscription's attribute list.



      .. versionadded:: 4.8








   .. method:: get_min_chars() -> int

      Gets the ``min-chars`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.min_chars` property.



      .. versionadded:: 4.8








   .. method:: get_min_lines() -> int

      Gets the ``min-lines`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.min_lines` property.



      .. versionadded:: 4.8








   .. method:: get_nat_chars() -> int

      Gets the ``nat-chars`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.nat_chars` property.



      .. versionadded:: 4.8








   .. method:: get_nat_lines() -> int

      Gets the ``nat-lines`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.nat_lines` property.



      .. versionadded:: 4.8








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

      Gets the text that is displayed.



      .. versionadded:: 4.8








   .. method:: get_text_overflow() -> ~gi.repository.Gtk.InscriptionOverflow

      Gets the inscription's overflow method.



      .. versionadded:: 4.8








   .. method:: get_wrap_mode() -> ~gi.repository.Pango.WrapMode

      Returns line wrap mode used by the inscription.

      See :obj:`~gi.repository.Gtk.Inscription.set_wrap_mode`.



      .. versionadded:: 4.8








   .. method:: get_xalign() -> float

      Gets the ``xalign`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.xalign` property.



      .. versionadded:: 4.8








   .. method:: get_yalign() -> float

      Gets the ``yalign`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.yalign` property.



      .. versionadded:: 4.8








   .. method:: set_attributes(attrs: ~gi.repository.Pango.AttrList | None = None) -> None

      Apply attributes to the inscription text.

      These attributes will not be evaluated for sizing the inscription.



      .. versionadded:: 4.8





      :param attrs: a :obj:`~gi.repository.Pango.AttrList`





   .. method:: set_markup(markup: str | None = None) -> None

      Utility function to set the text and attributes to be displayed.

      See the :obj:`~gi.repository.Gtk.Inscription.props.markup` property.



      .. versionadded:: 4.8





      :param markup: The markup to display





   .. method:: set_min_chars(min_chars: int) -> None

      Sets the ``min-chars`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.min_chars` property.



      .. versionadded:: 4.8





      :param min_chars: the minimum number of characters that should fit, approximately





   .. method:: set_min_lines(min_lines: int) -> None

      Sets the ``min-lines`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.min_lines` property.



      .. versionadded:: 4.8





      :param min_lines: the minimum number of lines that should fit, approximately





   .. method:: set_nat_chars(nat_chars: int) -> None

      Sets the ``nat-chars`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.nat_chars` property.



      .. versionadded:: 4.8





      :param nat_chars: the number of characters that should ideally fit, approximately





   .. method:: set_nat_lines(nat_lines: int) -> None

      Sets the ``nat-lines`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.nat_lines` property.



      .. versionadded:: 4.8





      :param nat_lines: the number of lines that should ideally fit





   .. method:: set_text(text: str | None = None) -> None

      Sets the text to be displayed.



      .. versionadded:: 4.8





      :param text: The text to display





   .. method:: set_text_overflow(overflow: ~gi.repository.Gtk.InscriptionOverflow) -> None

      Sets what to do when the text doesn't fit.



      .. versionadded:: 4.8





      :param overflow: the overflow method to use





   .. method:: set_wrap_mode(wrap_mode: ~gi.repository.Pango.WrapMode) -> None

      Controls how line wrapping is done.



      .. versionadded:: 4.8





      :param wrap_mode: the line wrapping mode





   .. method:: set_xalign(xalign: float) -> None

      Sets the ``xalign`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.xalign` property.



      .. versionadded:: 4.8





      :param xalign: the new xalign value, between 0 and 1





   .. method:: set_yalign(yalign: float) -> None

      Sets the ``yalign`` of the inscription.

      See the :obj:`~gi.repository.Gtk.Inscription.props.yalign` property.



      .. versionadded:: 4.8





      :param yalign: the new yalign value, between 0 and 1









Properties
----------

.. rst-class:: interim-class

.. class:: Inscription
   :no-index:
   

   .. attribute:: props.attributes
      :type: ~gi.repository.Pango.AttrList

      A list of style attributes to apply to the text of the inscription.



      .. versionadded:: 4.8





   .. attribute:: props.markup
      :type: str

      Utility property that sets both the :obj:`~gi.repository.Gtk.Inscription.props.text` and
      :obj:`~gi.repository.Gtk.Inscription.props.attributes` properties, mainly intended for use in
      GtkBuilder ui files to ease translation support and bindings.

      This function uses :obj:`~gi.repository.Pango.parse_markup` to parse the markup into text and
      attributes. The markup must be valid. If you cannot ensure that, consider using
      :obj:`~gi.repository.Pango.parse_markup` and setting the two properties yourself.



      .. versionadded:: 4.8





   .. attribute:: props.min_chars
      :type: int

      The number of characters that should fit into the inscription at minimum.

      This influences the requested width, not the width actually given to the widget,
      which might turn out to be larger.

      Note that this is an approximate character width, so some characters might be
      wider and some might be thinner, so do not expect the number of characters to
      exactly match.

      If you set this property to 0, the inscription will not request any width at all
      and its width will be determined entirely by its surroundings.



      .. versionadded:: 4.8





   .. attribute:: props.min_lines
      :type: int

      The number of lines that should fit into the inscription at minimum.

      This influences the requested height, not the height actually given to the widget,
      which might turn out to be larger.

      Note that this is an approximate line height, so if the text uses things like fancy
      Unicode or attribute that influence the height, the text might not fit.

      If you set this property to 0, the inscription will not request any height at all
      and its height will be determined entirely by its surroundings.



      .. versionadded:: 4.8





   .. attribute:: props.nat_chars
      :type: int

      The number of characters that should ideally fit into the inscription.

      This influences the requested width, not the width actually given to the widget.
      The widget might turn out larger as well as smaller.

      If this property is set to a value smaller than :obj:`~gi.repository.Gtk.Inscription.props.min_chars`,
      that value will be used. In particular, for the default value of 0, this will always
      be the case.



      .. versionadded:: 4.8





   .. attribute:: props.nat_lines
      :type: int

      The number of lines that should ideally fit into the inscription.

      This influences the requested height, not the height actually given to the widget.
      The widget might turn out larger as well as smaller.

      If this property is set to a value smaller than :obj:`~gi.repository.Gtk.Inscription.props.min_lines`,
      that value will be used. In particular, for the default value of 0, this will always
      be the case.



      .. versionadded:: 4.8





   .. attribute:: props.text
      :type: str

      The displayed text.



      .. versionadded:: 4.8





   .. attribute:: props.text_overflow
      :type: ~gi.repository.Gtk.InscriptionOverflow

      The overflow method to use for the text.



      .. versionadded:: 4.8





   .. attribute:: props.wrap_mode
      :type: ~gi.repository.Pango.WrapMode

      Controls how the line wrapping is done.

      Note that unlike ``GtkLabel``, the default here is ``%PANGO_WRAP_WORD_CHAR``.



      .. versionadded:: 4.8





   .. attribute:: props.xalign
      :type: float

      The horizontal alignment of the text inside the allocated size.

      Compare this to :obj:`~gi.repository.Gtk.Widget.props.halign`, which determines how the
      inscription's size allocation is positioned in the available space.



      .. versionadded:: 4.8





   .. attribute:: props.yalign
      :type: float

      The vertical alignment of the text inside the allocated size.

      Compare this to :obj:`~gi.repository.Gtk.Widget.props.valign`, which determines how the
      inscription's size allocation is positioned in the available space.



      .. versionadded:: 4.8