:right-sidebar: True

Tooltip
===================================================================

.. currentmodule:: gi.repository.Gtk





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


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





``GtkTooltip`` is an object representing a widget tooltip.

Basic tooltips can be realized simply by using
:obj:`~gi.repository.Gtk.Widget.set_tooltip_text` or
:obj:`~gi.repository.Gtk.Widget.set_tooltip_markup` without
any explicit tooltip object.

When you need a tooltip with a little more fancy contents,
like adding an image, or you want the tooltip to have different
contents per ``GtkTreeView`` row or cell, you will have to do a
little more work:


- Set the :obj:`~gi.repository.Gtk.Widget.props.has_tooltip` property to :const:`True`.
  This will make GTK monitor the widget for motion and related events
  which are needed to determine when and where to show a tooltip.

- Connect to the :obj:`~gi.repository.Gtk.Widget.signals.query_tooltip` signal.
  This signal will be emitted when a tooltip is supposed to be shown.
  One of the arguments passed to the signal handler is a ``GtkTooltip``
  object. This is the object that we are about to display as a tooltip,
  and can be manipulated in your callback using functions like
  :obj:`~gi.repository.Gtk.Tooltip.set_icon`. There are functions for setting
  the tooltip’s markup, setting an image from a named icon, or even
  putting in a custom widget.

- Return :const:`True` from your ::query-tooltip handler. This causes the tooltip
  to be show. If you return :const:`False`, it will not be shown.





Methods
-------

.. rst-class:: interim-class

.. class:: Tooltip
   :no-index:


   .. method:: set_custom(custom_widget: ~gi.repository.Gtk.Widget | None = None) -> None

      Replaces the widget packed into the tooltip with
      ``custom_widget``. ``custom_widget`` does not get destroyed when the tooltip goes
      away.
      By default a box with a ``GtkImage`` and ``GtkLabel`` is embedded in
      the tooltip, which can be configured using :func:`~gi.repository.Gtk.Tooltip.set_markup`
      and :func:`~gi.repository.Gtk.Tooltip.set_icon`.







      :param custom_widget: a ``GtkWidget``, or :const:`None` to unset the old custom widget.





   .. method:: set_icon(paintable: ~gi.repository.Gdk.Paintable | None = None) -> None

      Sets the icon of the tooltip (which is in front of the text) to be
      ``paintable``.  If ``paintable`` is :const:`None`, the image will be hidden.







      :param paintable: a ``GdkPaintable``





   .. method:: set_icon_from_gicon(gicon: ~gi.repository.Gio.Icon | None = None) -> None

      Sets the icon of the tooltip (which is in front of the text)
      to be the icon indicated by ``gicon`` with the size indicated
      by ``size``. If ``gicon`` is :const:`None`, the image will be hidden.







      :param gicon: a ``GIcon`` representing the icon





   .. method:: set_icon_from_icon_name(icon_name: str | None = None) -> None

      Sets the icon of the tooltip (which is in front of the text) to be
      the icon indicated by ``icon_name`` with the size indicated
      by ``size``.  If ``icon_name`` is :const:`None`, the image will be hidden.







      :param icon_name: an icon name





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

      Sets the text of the tooltip to be ``markup``.

      The string must be marked up with Pango markup.
      If ``markup`` is :const:`None`, the label will be hidden.







      :param markup: a string with Pango markup or ``%NLL``





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

      Sets the text of the tooltip to be ``text``.

      If ``text`` is :const:`None`, the label will be hidden.
      See also :obj:`~gi.repository.Gtk.Tooltip.set_markup`.







      :param text: a text string





   .. method:: set_tip_area(rect: ~gi.repository.Gdk.Rectangle) -> None

      Sets the area of the widget, where the contents of this tooltip apply,
      to be ``rect`` (in widget coordinates).  This is especially useful for
      properly setting tooltips on ``GtkTreeView`` rows and cells, ``GtkIconViews``,
      etc.

      For setting tooltips on ``GtkTreeView``, please refer to the convenience
      functions for this: :func:`~gi.repository.Gtk.TreeView.set_tooltip_row` and
      :func:`~gi.repository.Gtk.TreeView.set_tooltip_cell`.







      :param rect: a ``GdkRectangle``