:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/tooltip/tooltip.py Tooltip ======= .. py:module:: kivymd.uix.tooltip.tooltip .. autoapi-nested-parse:: Components/Tooltip ================== .. seealso:: `Material Design spec, Tooltips `_ .. rubric:: Tooltips display brief labels or messages. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-preview.png :align: center - Use tooltips to add additional context to a button or other UI element - Two types: plain and rich - Use plain tooltips to describe elements or actions of icon buttons - Use rich tooltips to provide more details, like describing the value of a feature - Rich tooltips can include an optional title, link, and buttons **KivyMD provides two types of tooltip:** 1. Plain tooltip 2. Rich tooltip .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-type.png :align: center Usage of tooltip plain ---------------------- .. tabs:: .. tab:: Declarative KV style .. code-block:: python from kivy.lang import Builder from kivy.properties import StringProperty from kivymd.uix.button import MDButton from kivymd.uix.tooltip import MDTooltip from kivymd.app import MDApp KV = ''' MDTooltipPlain: text: "Grant value is calculated using the closing stock price \\n" \ "from the day before the grant date. Amounts do not \\n" \ "reflect tax witholdings." MDButtonText: text: root.text MDScreen: md_bg_color: self.theme_cls.backgroundColor TooltipMDIconButton: text: "Tooltip button" pos_hint: {"center_x": .5, "center_y": .5} ''' class YourTooltipClass(MDTooltip): '''Implements your tooltip base class.''' class TooltipMDIconButton(YourTooltipClass, MDButton): '''Implements a button with tooltip behavior.''' text = StringProperty() class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return Builder.load_string(KV) Example().run() .. tab:: Declarative Python style .. code-block:: python from kivy.properties import StringProperty from kivy.clock import Clock from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.screen import MDScreen from kivymd.uix.tooltip import MDTooltip, MDTooltipPlain from kivymd.app import MDApp class YourTooltipClass(MDTooltip): '''Implements your tooltip base class.''' def __init__(self, **kwargs): super().__init__(**kwargs) self.widgets = [ MDTooltipPlain( text="Grant value is calculated using the closing stock price " "from the day before the grant date. Amounts do not " "reflect tax witholdings.", ) ] class TooltipMDIconButton(YourTooltipClass, MDButton): '''Implements a button with tooltip behavior.''' text = StringProperty() def __init__(self, **kwargs): super().__init__(**kwargs) Clock.schedule_once(self.set_widgets) def set_widgets(self, *args): self.widgets = [ MDButtonText( text=self.text, pos_hint={"center_x": .5, "center_y": .5} ) ] class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return ( MDScreen( TooltipMDIconButton( text="Tooltip button", pos_hint={"center_x": .5, "center_y": .5}, ), md_bg_color=self.theme_cls.backgroundColor, ) ) Example().run() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-plain-usage.gif :align: center The anatomy of a plain tooltip ------------------------------ .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-plain-anatomy.png :align: center Usage of tooltip rich --------------------- .. tabs:: .. tab:: Declarative KV style .. code-block:: python from kivy.lang import Builder from kivy.properties import StringProperty from kivymd.uix.button import MDButton from kivymd.uix.tooltip import MDTooltip from kivymd.app import MDApp KV = ''' MDTooltipRich: id: tooltip auto_dismiss: False MDTooltipRichSubhead: text: "Add others" MDTooltipRichSupportingText: text: "Grant value is calculated using the closing stock price \\n" \ "from the day before the grant date. Amounts do not \\n" \ "reflect tax witholdings." MDTooltipRichActionButton: on_press: tooltip.dismiss() MDButtonText: text: "Learn more" MDButtonText: text: root.text MDScreen: md_bg_color: self.theme_cls.backgroundColor TooltipMDIconButton: text: "Tooltip button" pos_hint: {"center_x": .5, "center_y": .5} ''' class YourTooltipClass(MDTooltip): '''Implements your tooltip base class.''' class TooltipMDIconButton(YourTooltipClass, MDButton): '''Implements a button with tooltip behavior.''' text = StringProperty() class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return Builder.load_string(KV) Example().run() .. tab:: Declarative Python style .. code-block:: python from kivy.properties import StringProperty from kivy.clock import Clock from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.screen import MDScreen from kivymd.uix.tooltip import ( MDTooltip, MDTooltipRich, MDTooltipRichSubhead, MDTooltipRichSupportingText, MDTooltipRichActionButton, ) from kivymd.app import MDApp class YourTooltipClass(MDTooltip): '''Implements your tooltip base class.''' def __init__(self, **kwargs): super().__init__(**kwargs) self.widgets = [ MDTooltipRich( MDTooltipRichSubhead( text="Add others", ), MDTooltipRichSupportingText( text="Grant value is calculated using the closing stock price " "from the day before the grant date. Amounts do not " "reflect tax witholdings." ), MDTooltipRichActionButton( MDButtonText( text="Learn more", ), on_press=self.tooltip_dismiss, ), id="tooltip", auto_dismiss=False, ), ] def tooltip_dismiss(self, *args): MDApp.get_running_app().root.get_ids().tooltip.dismiss() class TooltipMDIconButton(YourTooltipClass, MDButton): '''Implements a button with tooltip behavior.''' text = StringProperty() def __init__(self, **kwargs): super().__init__(**kwargs) Clock.schedule_once(self.set_widgets) def set_widgets(self, *args): self.widgets = [ MDButtonText( text=self.text, pos_hint={"center_x": .5, "center_y": .5} ) ] class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return ( MDScreen( TooltipMDIconButton( text="Tooltip button", pos_hint={"center_x": .5, "center_y": .5}, ), md_bg_color=self.theme_cls.backgroundColor, ) ) Example().run() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-rich-usage.gif :align: center The anatomy of a plain tooltip ------------------------------ .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-rich-anatomy.png :align: center API - :mod:`kivymd.uix.tooltip.tooltip` --------------------------------------- .. py:class:: MDTooltip(**kwargs) Tooltip class. For more information, see in the :class:`~kivymd.uix.behaviors.touch_behavior.TouchBehavior` class documentation. :Events: `on_open`: Fired when the tooltip opens. `on_dismiss`: Fired when the tooltip is closed. .. py:attribute:: tooltip_display_delay Tooltip display delay. .. note:: This property only works on desktop. :attr:`tooltip_display_delay` is an :class:`~kivy.properties.BoundedNumericProperty` and defaults to `0`, min of `0` & max of `4`. .. py:attribute:: shift_y Y-offset of tooltip to the top. :attr:`shift_y` is an :class:`~kivy.properties.NumericProperty` and defaults to `0`. .. py:attribute:: shift_right Shifting the tooltip to the right. .. versionadded:: 1.0.0 :attr:`shift_right` is an :class:`~kivy.properties.NumericProperty` and defaults to `0`. .. py:attribute:: shift_left Shifting the tooltip to the left. .. versionadded:: 1.0.0 :attr:`shift_left` is an :class:`~kivy.properties.NumericProperty` and defaults to `0`. .. py:method:: delete_clock(widget, touch, *args) Removes a key event from `touch.ud`. .. py:method:: adjust_tooltip_position() -> tuple Returns the coordinates of the tooltip that fit into the borders of the screen. .. py:method:: display_tooltip(*args) -> None Adds a tooltip widget to the screen and animates its display. .. py:method:: animation_tooltip_show(*args) -> None Animation of opening tooltip on the screen. .. py:method:: animation_tooltip_dismiss(*args) -> None Animation of closing tooltip on the screen. .. versionadded:: 1.0.0 .. py:method:: remove_tooltip(*args) -> None Removes the tooltip widget from the screen. .. py:method:: add_widget(widget, *args, **kwargs) Add a new widget as a child of this widget. .. py:method:: on_long_touch(touch, *args) -> None Fired when the widget is pressed for a long time. .. py:method:: on_enter(*args) -> None Fired when mouse enter the bbox of the widget. .. py:method:: on_leave(*args) -> None Fired when the mouse goes outside the widget border. .. py:method:: on_open() -> None Default display event handler. .. versionchanged:: 2.0.0 Rename from `on_show` to `on_open`. .. py:method:: on_dismiss() -> None Default dismiss event handler. .. versionadded:: 1.0.0 .. py:class:: MDTooltipPlain(*args, **kwargs) Tooltip plain class. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.label.label.MDLabel` and :class:`~kivymd.uix.behaviors.scale_behavior.ScaleBehavior` classes documentation. .. py:class:: MDTooltipRichSupportingText(*args, **kwargs) Implements supporting text for the :class:`~MDTooltipRich` class. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.label.label.MDLabel` class documentation. .. py:class:: MDTooltipRichSubhead(*args, **kwargs) Implements subhead text for the :class:`~MDTooltipRich` class. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.label.label.MDLabel` class documentation. .. py:class:: MDTooltipRichActionButton(*args, **kwargs) Implements action button for the :class:`~MDTooltipRich` class. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.button.button.MDButton` class documentation. .. py:method:: on_enter() -> None Fired when mouse enter the bbox of the widget. .. py:method:: on_leave() -> None Fired when the mouse goes outside the widget border. .. py:class:: MDTooltipRich(*args, **kwargs) Tooltip rich class. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.behaviors.declarative_behavior.DeclarativeBehavior` and :class:`~kivymd.theming.ThemableBehavior` and :class:`~kivymd.uix.behaviors.backgroundcolor_behavior.BackgroundColorBehavior` and :class:`~kivymd.uix.behaviors.elevation.CommonElevationBehavior` and :class:`~kivymd.uix.behaviors.scale_behavior.ScaleBehavior` and :class:`~kivymd.uix.behaviors.state_layer_behavior.StateLayerBehavior` and :class:`~kivy.uix.boxlayout.BoxLayout` and classes documentation. .. py:attribute:: auto_dismiss This property determines if the view is automatically dismissed when the cursor goes outside of the tooltip body. :attr:`auto_dismiss` is a :class:`~kivy.properties.BooleanProperty` and defaults to True. .. py:method:: on_leave() -> None Fired when the mouse goes outside the widget border. .. py:method:: dismiss() -> None Hides the tooltip.