.. 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

Inheritance diagram for class
BalloonTip:
|
|appearance| Control Appearance
===============================
|
.. container:: control-appearance-figures
.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.balloontip.balloontip.png
:alt: wxMSW
:figclass: appearance-figure
**wxMSW**
.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
:alt: wxMAC
:figclass: appearance-figure
**wxMAC**
.. figure:: _static/images/widgets/fullsize/wxgtk/../no_appearance.png
:alt: wxGTK
:figclass: appearance-figure
**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.
.. seealso:: :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.