.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.balloontip

.. highlight:: python



.. _wx.lib.agw.balloontip.BalloonTip:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.balloontip.BalloonTip**
==========================================================================================================================================

:class:`BalloonTip` is a class that allows you to display tooltips in a balloon style
window.

This is the main class implementation.



|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>BalloonTip</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.lib.agw.balloontip.BalloonTip_inheritance.png" alt="Inheritance diagram of BalloonTip" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.balloontip.BalloonTip.html" title="wx.lib.agw.balloontip.BalloonTip" alt="" coords="5,5,239,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.balloontip.balloontip.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/../no_appearance.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|




|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.lib.agw.balloontip.BalloonTip.__init__`                               Default class constructor.
:meth:`~wx.lib.agw.balloontip.BalloonTip.DestroyTimer`                           The destruction timer has expired. Destroys the :class:`BalloonTip` frame.
:meth:`~wx.lib.agw.balloontip.BalloonTip.EnableTip`                              Enable/disable globally the :class:`BalloonTip`.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonColour`                       Returns the :class:`BalloonTip` background colour.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonIcon`                         Returns the :class:`BalloonTip` top-left icon.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonMessage`                      Returns the :class:`BalloonTip` tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonShape`                        Returns the :class:`BalloonTip` frame shape.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonTipStyle`                     Returns the :class:`BalloonTip` `tipstyle` parameter.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetBalloonTitle`                        Returns the :class:`BalloonTip` top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetEndDelay`                            Returns the delay time after which the :class:`BalloonTip` is destroyed.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetMessageColour`                       Returns the colour for the tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetMessageFont`                         Returns the font for the tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetStartDelay`                          Returns the delay time after which the :class:`BalloonTip` is created.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetTarget`                              Returns the target window for the :class:`BalloonTip`.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetTitleColour`                         Returns the colour for the top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.GetTitleFont`                           Returns the font for the top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.NotifyTimer`                            The creation timer has expired. Creates the :class:`BalloonTip` frame.
:meth:`~wx.lib.agw.balloontip.BalloonTip.OnDestroy`                              Handles the target destruction, specifically handling the ``wx.EVT_WINDOW_DESTROY``
:meth:`~wx.lib.agw.balloontip.BalloonTip.OnTaskBarMove`                          Handles the mouse motion inside the taskbar icon area.
:meth:`~wx.lib.agw.balloontip.BalloonTip.OnWidgetEnter`                          Handles the ``wx.EVT_ENTER_WINDOW`` for the target control/window and
:meth:`~wx.lib.agw.balloontip.BalloonTip.OnWidgetLeave`                          Handles the ``wx.EVT_LEAVE_WINDOW`` for the target control/window.
:meth:`~wx.lib.agw.balloontip.BalloonTip.OnWidgetMotion`                         Handle the mouse motion inside the target.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonColour`                       Sets the :class:`BalloonTip` background colour.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonIcon`                         Sets the :class:`BalloonTip` top-left icon.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonMessage`                      Sets the :class:`BalloonTip` tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonShape`                        Sets the :class:`BalloonTip` frame shape.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonTipStyle`                     Sets the :class:`BalloonTip` `tipstyle` parameter.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetBalloonTitle`                        Sets the :class:`BalloonTip` top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetEndDelay`                            Sets the delay time after which the BalloonTip is destroyed.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetMessageColour`                       Sets the colour for the tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetMessageFont`                         Sets the font for the tip message.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetStartDelay`                          Sets the delay time after which the :class:`BalloonTip` is created.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetTarget`                              Sets the target control/window for the :class:`BalloonTip`.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetTitleColour`                         Sets the colour for the top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.SetTitleFont`                           Sets the font for the top title.
:meth:`~wx.lib.agw.balloontip.BalloonTip.TaskBarTimer`                           This timer check periodically the mouse position.
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: BalloonTip(object)

   :class:`BalloonTip` is a class that allows you to display tooltips in a balloon style
   window.
   
   This is the main class implementation.

   .. method:: __init__(self, topicon=None, toptitle="", message="", shape=BT_ROUNDED, tipstyle=BT_LEAVE)

      Default class constructor.
      
      :param `topicon`: an icon that will be displayed on the top-left part of the
       :class:`BalloonTip` frame. If set to ``None``, no icon will be displayed;
      :type `topicon`: :class:`wx.Bitmap` or ``None``
      :param string `toptitle`: a title that will be displayed on the top part of the
       :class:`BalloonTip` frame. If set to an empty string, no title will be displayed;
      :param string `message`: the tip message that will be displayed. It can not be set to
       an empty string;
      :param integer `shape`: the :class:`BalloonTip` shape. It can be one of the following:
      
       ======================= ========= ====================================
       Shape Flag              Hex Value  Description
       ======================= ========= ====================================
       ``BT_ROUNDED``           0x1      :class:`BalloonTip` will have a rounded rectangular shape.
       ``BT_RECTANGLE``         0x2      :class:`BalloonTip` will have a rectangular shape.
       ======================= ========= ====================================
      
      :param integer `tipstyle`: the :class:`BalloonTip` destruction behavior. It can be one of:
      
       ======================= ========= ====================================
       Tip Flag                Hex Value  Description
       ======================= ========= ====================================
       ``BT_LEAVE``                  0x3 :class:`BalloonTip` will be destroyed when the user moves the mouse outside the target window.
       ``BT_CLICK``                  0x4 :class:`BalloonTip` will be destroyed when the user click on :class:`BalloonTip`.
       ``BT_BUTTON``                 0x5 :class:`BalloonTip` will be destroyed when the user click on the close button.
       ======================= ========= ====================================
      
      :raise: `Exception` in the following cases:
      
       - The `message` parameter is an empty string;
       - The `shape` parameter has an invalid value (i.e., it's not one of ``BT_ROUNDED``, ``BT_RECTANGLE``);
       - The `tipstyle` parameter has an invalid value (i.e., it's not one of ``BT_LEAVE``, ``BT_CLICK``, ``BT_BUTTON``).


   .. method:: DestroyTimer(self, event)

      The destruction timer has expired. Destroys the :class:`BalloonTip` frame.
      
      :param `event`: a :class:`wx.TimerEvent` to be processed.


   .. method:: EnableTip(self, enable=True)

      Enable/disable globally the :class:`BalloonTip`.
      
      :param bool `enable`: ``True`` to enable :class:`BalloonTip`, ``False`` otherwise.


   .. method:: GetBalloonColour(self)

      Returns the :class:`BalloonTip` background colour.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetBalloonIcon(self)

      Returns the :class:`BalloonTip` top-left icon.
      
      :return: An instance of :class:`wx.Bitmap`.


   .. method:: GetBalloonMessage(self)

      Returns the :class:`BalloonTip` tip message.
      
      :return: A string containing the main message.


   .. method:: GetBalloonShape(self)

      Returns the :class:`BalloonTip` frame shape.
      
      :return: An integer, one of ``BT_ROUNDED``, ``BT_RECTANGLE``.


   .. method:: GetBalloonTipStyle(self)

      Returns the :class:`BalloonTip` `tipstyle` parameter.
      
      :return: An integer representing the style.
      
      :see: :meth:`~BalloonTip.SetBalloonTipStyle`


   .. method:: GetBalloonTitle(self)

      Returns the :class:`BalloonTip` top title.
      
      :return: A string containing the top title.


   .. method:: GetEndDelay(self)

      Returns the delay time after which the :class:`BalloonTip` is destroyed.
      
      :return: the delay time, in milliseconds.


   .. method:: GetMessageColour(self)

      Returns the colour for the tip message.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetMessageFont(self)

      Returns the font for the tip message.
      
      :return: An instance of :class:`wx.Font`.


   .. method:: GetStartDelay(self)

      Returns the delay time after which the :class:`BalloonTip` is created.
      
      :return: the delay time, in milliseconds.


   .. method:: GetTarget(self)

      Returns the target window for the :class:`BalloonTip`.
      
      :return: An instance of :class:`wx.Window`.
      
      :raise: `Exception` if the :meth:`~BalloonTip.SetTarget` method has not previously called.


   .. method:: GetTitleColour(self)

      Returns the colour for the top title.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetTitleFont(self)

      Returns the font for the top title.
      
      :return: An instance of :class:`wx.Font`.


   .. method:: NotifyTimer(self, event)

      The creation timer has expired. Creates the :class:`BalloonTip` frame.
      
      :param `event`: a :class:`wx.TimerEvent` to be processed.


   .. method:: OnDestroy(self, event)

      Handles the target destruction, specifically handling the ``wx.EVT_WINDOW_DESTROY``
      event.
      
      :param `event`: a :class:`wx.WindowDestroyEvent` event to be processed.


   .. method:: OnTaskBarMove(self, event)

      Handles the mouse motion inside the taskbar icon area.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnWidgetEnter(self, event)

      Handles the ``wx.EVT_ENTER_WINDOW`` for the target control/window and
      starts the :class:`BalloonTip` timer for creation.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnWidgetLeave(self, event)

      Handles the ``wx.EVT_LEAVE_WINDOW`` for the target control/window.
      
      :param `event`: a :class:`MouseEvent` event to be processed.
      
      :note: If the BalloonTip `tipstyle` is set to ``BT_LEAVE``, the :class:`BalloonTip` is destroyed.


   .. method:: OnWidgetMotion(self, event)

      Handle the mouse motion inside the target.
      
      This prevents the annoying behavior of :class:`BalloonTip` to display when the
      user does something else inside the window. The :class:`BalloonTip` window is
      displayed only when the mouse does *not* move for the start delay time.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: SetBalloonColour(self, colour=None)

      Sets the :class:`BalloonTip` background colour.
      
      :param `colour`: a valid :class:`wx.Colour` instance.


   .. method:: SetBalloonIcon(self, icon)

      Sets the :class:`BalloonTip` top-left icon.
      
      :param `icon`: an instance of :class:`wx.Bitmap`.
      
      :raise: `Exception` if the `icon` bitmap is not a valid :class:`wx.Bitmap`.


   .. method:: SetBalloonMessage(self, message)

      Sets the :class:`BalloonTip` tip message.
      
      :param string `message`: a string identifying the main message body of :class:`BalloonTip`.
      
      :raise: `Exception` if the message is an empty string.
      
      :note: The :class:`BalloonTip` message should never be empty.


   .. method:: SetBalloonShape(self, shape=BT_ROUNDED)

      Sets the :class:`BalloonTip` frame shape.
      
      :param integer `shape`: should be one of ``BT_ROUNDED`` or ``BT_RECTANGLE``.
      
      :raise: `Exception` if the `shape` parameter is not a valid value
       (i.e., it's not one of ``BT_ROUNDED``, ``BT_RECTANGLE``);


   .. method:: SetBalloonTipStyle(self, tipstyle=BT_LEAVE)

      Sets the :class:`BalloonTip` `tipstyle` parameter.
      
      :param integer `tipstyle`: one of the following bit set:
      
       ============== ========== =====================================
       Tip Style      Hex Value  Description
       ============== ========== =====================================
       ``BT_LEAVE``          0x3 :class:`BalloonTip` will be destroyed when the user moves the mouse outside the target window.
       ``BT_CLICK``          0x4 :class:`BalloonTip` will be destroyed when the user click on :class:`BalloonTip`.
       ``BT_BUTTON``         0x5 :class:`BalloonTip` will be destroyed when the user click on the close button.
       ============== ========== =====================================
      
      :raise: `Exception` if the `tipstyle` parameter has an invalid value
       (i.e., it's not one of ``BT_LEAVE``, ``BT_CLICK``, ``BT_BUTTON``).


   .. method:: SetBalloonTitle(self, title="")

      Sets the :class:`BalloonTip` top title.
      
      :param string `title`: a string to use as a :class:`BalloonTip` title.


   .. method:: SetEndDelay(self, delay=1e6)

      Sets the delay time after which the BalloonTip is destroyed.
      
      :param integer `delay`: the number of milliseconds after which :class:`BalloonTip` is destroyed.
      
      :raise: `Exception` if `delay` is less than ``1`` milliseconds.


   .. method:: SetMessageColour(self, colour=None)

      Sets the colour for the tip message.
      
      :param `colour`: a valid :class:`wx.Colour` instance.


   .. method:: SetMessageFont(self, font=None)

      Sets the font for the tip message.
      
      :param `font`: a valid :class:`wx.Font` instance.


   .. method:: SetStartDelay(self, delay=1)

      Sets the delay time after which the :class:`BalloonTip` is created.
      
      :param integer `delay`: the number of milliseconds after which :class:`BalloonTip` is created.
      
      :raise: `Exception` if `delay` is less than ``1`` milliseconds.


   .. method:: SetTarget(self, widget)

      Sets the target control/window for the :class:`BalloonTip`.
      
      :param `widget`: any subclass of :class:`wx.Window`.


   .. method:: SetTitleColour(self, colour=None)

      Sets the colour for the top title.
      
      :param `colour`: a valid :class:`wx.Colour` instance.


   .. method:: SetTitleFont(self, font=None)

      Sets the font for the top title.
      
      :param `font`: a valid :class:`wx.Font` instance.


   .. method:: TaskBarTimer(self, event)

      This timer check periodically the mouse position.
      
      If the current mouse position is sufficiently far from the coordinates
      it had when entered the taskbar icon and the :class:`BalloonTip` style is
      ``BT_LEAVE``, the :class:`BalloonTip` frame is destroyed.
      
      :param `event`: a :class:`wx.TimerEvent` to be processed.


