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

.. module:: wx.lib.agw.balloontip

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

.. highlight:: python



.. _wx.lib.agw.balloontip:

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

:class:`~wx.lib.agw.balloontip.BalloonTip` is a class that allows you to display tooltips in a balloon style
window.


Description
===========

:class:`BalloonTip` is a class that allows you to display tooltips in a balloon style
window (actually a frame), similarly to the windows XP balloon help. There is
also an arrow that points to the center of the control designed as a "target"
for the :class:`BalloonTip`.

What it can do:

- Set the balloon shape as a rectangle or a rounded rectangle;
- Set an icon to the top-left of the :class:`BalloonTip` frame;
- Set a title at the top of the :class:`BalloonTip` frame;
- Automatic "best" placement of :class:`BalloonTip` frame depending on the target
  control/window position;
- Runtime customization of title/tip fonts and foreground colours;
- Runtime change of :class:`BalloonTip` frame shape;
- Set the balloon background colour;
- Possibility to set the delay after which the :class:`BalloonTip` is displayed;
- Possibility to set the delay after which the :class:`BalloonTip` is destroyed;
- Three different behaviors for the :class:`BalloonTip` window (regardless the delay
  destruction time set):

  a) Destroy by leave: the :class:`BalloonTip` is destroyed when the mouse leaves the
     target control/window;
  b) Destroy by click: the :class:`BalloonTip` is destroyed when you click on any area
     of the target control/window;
  c) Destroy by button: the :class:`BalloonTip` is destroyed when you click on the
     top-right close button;
- Possibility to enable/disable globally the :class:`BalloonTip` on you application;
- Set the :class:`BalloonTip` also for the taskbar icon.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.balloontip as BT

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init__(self, parent, -1, "BalloonTip Demo")

            panel = wx.Panel(self)

            # Let's suppose that in your application you have a wx.TextCtrl defined as:
            mytextctrl = wx.TextCtrl(panel, -1, "I am a textctrl", pos=(100, 100))

            # You can define your BalloonTip as follows:
            tipballoon = BT.BalloonTip(topicon=None, toptitle="textctrl",
                                       message="this is a textctrl",
                                       shape=BT.BT_ROUNDED,
                                       tipstyle=BT.BT_LEAVE)

            # Set the BalloonTip target
            tipballoon.SetTarget(mytextctrl)
            # Set the BalloonTip background colour
            tipballoon.SetBalloonColour(wx.WHITE)
            # Set the font for the balloon title
            tipballoon.SetTitleFont(wx.Font(9, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD, False))
            # Set the colour for the balloon title
            tipballoon.SetTitleColour(wx.BLACK)
            # Leave the message font as default
            tipballoon.SetMessageFont()
            # Set the message (tip) foreground colour
            tipballoon.SetMessageColour(wx.LIGHT_GREY)
            # Set the start delay for the BalloonTip
            tipballoon.SetStartDelay(1000)
            # Set the time after which the BalloonTip is destroyed
            tipballoon.SetEndDelay(3000)

    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()


Window Styles
=============

This class supports the following window styles:

================ =========== ==================================================
Window Styles    Hex Value   Description
================ =========== ==================================================
``BT_ROUNDED``           0x1 :class:`BalloonTip` will have a rounded rectangular shape.
``BT_RECTANGLE``         0x2 :class:`BalloonTip` will have a rectangular shape.
``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.
================ =========== ==================================================


Events Processing
=================

`No custom events are available for this class.`


License And Version
===================

BalloonTip is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 16 Jul 2012, 15.00 GMT

Version 0.3


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
`~wx.lib.agw.balloontip.BalloonFrame`                                            This class is called by the main :class:`BalloonTip` class, and it is
`~wx.lib.agw.balloontip.BalloonTip`                                              :class:`BalloonTip` is a class that allows you to display tooltips in a balloon style
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.balloontip.BalloonFrame
   wx.lib.agw.balloontip.BalloonTip