This is the Advanced Generic Widgets package (AGW). It provides many
custom-drawn wxPython controls: some of them can be used as a replacement
of the platform native controls, others are simply an addition to the
already rich wxPython widgets set.

Description:

AGW contains many different modules, listed below. Items labelled with
an asterisk were already present in :mod:`lib` before:

- AdvancedSplash: reproduces the behaviour of :class:`~adv.SplashScreen`, with more
  advanced features like custom shapes and text animations;
- AquaButton: this is another custom-drawn button class which
  *approximately* mimics the behaviour of Aqua buttons on the Mac;
- AUI: a pure-Python implementation of :mod:`~wx.lib.agw.aui`, with many bug fixes and
  new features like HUD docking and :class:`~wx.lib.agw.aui.auibook.AuiNotebook` tab arts;
- BalloonTip: allows you to display tooltips in a balloon style window
  (actually a frame), similarly to the Windows XP balloon help;
- ButtonPanel (*): a panel with gradient background shading with the
  possibility to add buttons and controls still respecting the gradient
  background;
- CubeColourDialog: an alternative implementation of :class:`wx.ColourDialog`, it
  offers different functionalities like colour wheel and RGB cube;
- CustomTreeCtrl (*): mimics the behaviour of :class:`TreeCtrl`, with almost the
  same base functionalities plus a bunch of enhancements and goodies;
- FlatMenu: as the name implies, it is a generic menu implementation,
  offering the same :class:`wx.MenuBar` / :class:`wx.Menu` / :class:`ToolBar` capabilities and much more;
- FlatNotebook (*): a full implementation of the :class:`Notebook`, and designed
  to be a drop-in replacement for :class:`Notebook` with enhanced capabilities;
- FloatSpin: this class implements a floating point spinctrl, cabable (in
  theory) of handling infinite-precision floating point numbers;
- FoldPanelBar (*): a control that contains multiple panels that can be
  expanded or collapsed a la Windows Explorer/Outlook command bars;
- FourWaySplitter: this is a layout manager which manages four children like
  four panes in a window, similar to many CAD software interfaces;
- GenericMessageDialog: it is a possible replacement for the standard
  :class:`MessageDialog`, with a fancier look and extended functionalities;
- GradientButton: another custom-drawn button class which mimics Windows CE
  mobile gradient buttons, using a tri-vertex blended gradient background;
- HyperLinkCtrl (*): this widget acts line an hyper link in a typical browser;
- HyperTreeList: a class that mimics the behaviour of :class:`wx.adv.TreeListCtrl`,
  with almost the same base functionalities plus some more enhancements;
- InfoBar: a transient window shown at top or bottom of its parent window to display
  non-critical information to the user;
- KnobCtrl: a widget which lets the user select a numerical value by
  rotating it, like a slider with a wheel shape;
- LabelBook and FlatImageBook: these are a quasi-full implementations of
  :class:`Listbook`, with additional features;
- MultiDirDialog: it represents a possible replacement for :class:`DirDialog`,
  with the additional ability of selecting multiple folders at once and a
  fancier look;
- PeakMeter: this widget mimics the behaviour of LED equalizers that are
  usually found in stereos and MP3 players;
- PersistentControls: widgets which automatically save their state
  when they are destroyed and restore it when they are recreated, even during
  another program invocation;
- PieCtrl and ProgressPie: these are simple classes that reproduce the
  behavior of a pie chart, in a static or progress-gauge-like way;
- PyBusyInfo: constructs a busy info window and displays a message in it:
  it is similar to :class:`BusyInfo`;
- PyCollapsiblePane: a pure Python implementation of the original wxWidgets
  C++ code of :class:`CollapsiblePane`, with customizable buttons;
- PyGauge: a generic :class:`Gauge` implementation, it supports the determinate
  mode functions as :class:`Gauge`;
- PyProgress: it is similar to :class:`ProgressDialog` in indeterminated mode, but
  with a different gauge appearance and a different spinning behavior;
- RibbonBar: the RibbonBar library is a set of classes for writing a ribbon
  user interface, similar to the user interface present in recent versions
  of Microsoft Office;
- RulerCtrl: it implements a ruler window that can be placed on top, bottom,
  left or right to any wxPython widget. It is somewhat similar to the rulers
  you can find in text editors software;
- ShapedButton: this class tries to fill the lack of "custom shaped" controls
  in wxPython. It can be used to build round buttons or elliptic buttons;
- ShortcutEditor: a widget that allows the user to customize and change
  keyboard shortcuts via a dialog;
- SpeedMeter: this widget tries to reproduce the behavior of some car
  controls (but not only), by creating an "angular" control;
- SuperToolTip: a class that mimics the behaviour of :class:`TipWindow` and
  generic tooltips, with many features and highly customizable;
- ThumbnailCtrl: a widget that can be used to display a series of images
  in a "thumbnail" format; it mimics, for example, the Windows Explorer
  behavior when you select the "view thumbnails" option;
- ToasterBox: a cross-platform widget to make the creation of MSN-style
  "toaster" popups easier;
- UltimateListCtrl: mimics the behaviour of :class:`ListCtrl`, with almost the same
  base functionalities plus some more enhancements;
- XLSGrid: a class based on :class:`grid.Grid` that can be used to faithfully
  reproduce the appearance of a Microsoft Excel spreadsheets;
- ZoomBar: a class that *appoximatively* mimics the behaviour of the Mac Dock,
  inside a :class:`Panel`.

Bugs and Limitations: many, patches and fixes welcome :-D

See the demos for an example of what AGW can do, and on how to use it.

Copyright: Andrea Gavana

License: Same as the version of wxPython you are using it with.

SVN for latest code:
http://svn.wxwidgets.org/viewvc/wx/wxPython/3rdParty/AGW/

Mailing List:
wxpython-users@lists.wxwidgets.org

My personal web page:
http://xoomer.alice.it/infinity77

Please let me know if you are using AGW!

You can contact me at:

andrea.gavana@gmail.com
andrea.gavana@maerskoil.com

AGW version: 0.9.7

Last updated: 09 January 2014, 23.00 GMT

AUI is an Advanced User Interface library that aims to implement "cutting-edge"
interface usability and design features so developers can quickly and easily create
beautiful and usable application interfaces.

Vision and Design Principles
============================

AUI attempts to encapsulate the following aspects of the user interface:

* **Frame Management**: Frame management provides the means to open, move and hide common
  controls that are needed to interact with the document, and allow these configurations
  to be saved into different perspectives and loaded at a later time.

* **Toolbars**: Toolbars are a specialized subset of the frame management system and should
  behave similarly to other docked components. However, they also require additional
  functionality, such as "spring-loaded" rebar support, "chevron" buttons and end-user
  customizability.

* **Modeless Controls**: Modeless controls expose a tool palette or set of options that
  float above the application content while allowing it to be accessed. Usually accessed
  by the toolbar, these controls disappear when an option is selected, but may also be
  "torn off" the toolbar into a floating frame of their own.

* **Look and Feel**: Look and feel encompasses the way controls are drawn, both when shown
  statically as well as when they are being moved. This aspect of user interface design
  incorporates "special effects" such as transparent window dragging as well as frame animation.

AUI adheres to the following principles:

- Use native floating frames to obtain a native look and feel for all platforms;
- Use existing wxPython code where possible, such as sizer implementation for frame management;
- Use standard wxPython coding conventions.

Usage
=====

The following example shows a simple implementation that uses :class:`framemanager.AuiManager` to manage
three text controls in a frame window::

    import wx
    import wx.lib.agw.aui as aui

    class MyFrame(wx.Frame):

        def __init__(self, parent, id=-1, title="AUI Test", pos=wx.DefaultPosition,
                     size=(800, 600), style=wx.DEFAULT_FRAME_STYLE):

            wx.Frame.__init__(self, parent, id, title, pos, size, style)

            self._mgr = aui.AuiManager()

            # notify AUI which frame to use
            self._mgr.SetManagedWindow(self)

            # create several text controls
            text1 = wx.TextCtrl(self, -1, "Pane 1 - sample text",
                                wx.DefaultPosition, wx.Size(200,150),
                                wx.NO_BORDER | wx.TE_MULTILINE)

            text2 = wx.TextCtrl(self, -1, "Pane 2 - sample text",

            text3 = wx.TextCtrl(self, -1, "Main content window",

            # add the panes to the manager
            self._mgr.AddPane(text1, aui.AuiPaneInfo().Left().Caption("Pane Number One"))
            self._mgr.AddPane(text2, aui.AuiPaneInfo().Bottom().Caption("Pane Number Two"))
            self._mgr.AddPane(text3, aui.AuiPaneInfo().CenterPane())

            # tell the manager to "commit" all the changes just made
            self._mgr.Update()

            self.Bind(wx.EVT_CLOSE, self.OnClose)

        def OnClose(self, event):
            # deinitialize the frame manager
            self._mgr.UnInit()
            event.Skip()

    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()

What's New
==========

Current wxAUI Version Tracked: wxWidgets 2.9.5 (SVN HEAD)

The wxPython AUI version fixes the following bugs or implement the following
missing features (the list is not exhaustive):

- Visual Studio 2005 style docking: http://www.kirix.com/forums/viewtopic.php?f=16&t=596
- Dock and Pane Resizing: http://www.kirix.com/forums/viewtopic.php?f=16&t=582
- Patch concerning dock resizing: http://www.kirix.com/forums/viewtopic.php?f=16&t=610
- Patch to effect wxAuiToolBar orientation switch: http://www.kirix.com/forums/viewtopic.php?f=16&t=641
- AUI: Core dump when loading a perspective in wxGTK (MSW OK): http://www.kirix.com/forums/viewtopic.php?f=15&t=627
- wxAuiNotebook reordered AdvanceSelection(): http://www.kirix.com/forums/viewtopic.php?f=16&t=617
- Vertical Toolbar Docking Issue: http://www.kirix.com/forums/viewtopic.php?f=16&t=181
- Patch to show the resize hint on mouse-down in aui: http://trac.wxwidgets.org/ticket/9612
- The Left/Right and Top/Bottom Docks over draw each other: http://trac.wxwidgets.org/ticket/3516
- MinSize() not honoured: http://trac.wxwidgets.org/ticket/3562
- Layout problem with wxAUI: http://trac.wxwidgets.org/ticket/3597
- Resizing children ignores current window size: http://trac.wxwidgets.org/ticket/3908
- Resizing panes under Vista does not repaint background: http://trac.wxwidgets.org/ticket/4325
- Resize sash resizes in response to click: http://trac.wxwidgets.org/ticket/4547
- "Illegal" resizing of the AuiPane? (wxPython): http://trac.wxwidgets.org/ticket/4599
- Floating wxAUIPane Resize Event doesn't update its position: http://trac.wxwidgets.org/ticket/9773
- Don't hide floating panels when we maximize some other panel: http://trac.wxwidgets.org/ticket/4066
- wxAUINotebook incorrect ALLOW_ACTIVE_PANE handling: http://trac.wxwidgets.org/ticket/4361
- Page changing veto doesn't work, (patch supplied): http://trac.wxwidgets.org/ticket/4518
- Show and DoShow are mixed around in wxAuiMDIChildFrame: http://trac.wxwidgets.org/ticket/4567
- wxAuiManager & wxToolBar - ToolBar Of Size Zero: http://trac.wxwidgets.org/ticket/9724
- wxAuiNotebook doesn't behave properly like a container as far as...: http://trac.wxwidgets.org/ticket/9911
- Serious layout bugs in wxAUI: http://trac.wxwidgets.org/ticket/10620
- wAuiDefaultTabArt::Clone() should just use copy constructor: http://trac.wxwidgets.org/ticket/11388
- Drop down button for check tool on wxAuiToolbar: http://trac.wxwidgets.org/ticket/11139

Plus the following features:

- AuiManager:

  (a) Implementation of a simple minimize pane system: Clicking on this minimize button causes a new
      AuiToolBar to be created and added to the frame manager, (currently the implementation is such
      that panes at West will have a toolbar at the right, panes at South will have toolbars at the
      bottom etc...) and the pane is hidden in the manager.
      Clicking on the restore button on the newly created toolbar will result in the toolbar being
      removed and the original pane being restored;
  (b) Panes can be docked on top of each other to form `AuiNotebooks`; `AuiNotebooks` tabs can be torn
      off to create floating panes;
  (c) On Windows XP, use the nice sash drawing provided by XP while dragging the sash;
  (d) Possibility to set an icon on docked panes;
  (e) Possibility to draw a sash visual grip, for enhanced visualization of sashes;
  (f) Implementation of a native docking art (`ModernDockArt`). Windows XP only, **requires** Mark Hammond's
      pywin32 package (winxptheme);
  (g) Possibility to set a transparency for floating panes (a la Paint .NET);
  (h) Snapping the main frame to the screen in any positin specified by horizontal and vertical
      alignments;
  (i) Snapping floating panes on left/right/top/bottom or any combination of directions, a la Winamp;
  (j) "Fly-out" floating panes, i.e. panes which show themselves only when the mouse hover them;
  (k) Ability to set custom bitmaps for pane buttons (close, maximize, etc...);
  (l) Implementation of the style ``AUI_MGR_ANIMATE_FRAMES``, which fade-out floating panes when
      they are closed (all platforms which support frames transparency) and show a moving rectangle
      when they are docked and minimized (Windows < Vista and GTK only);
  (m) A pane switcher dialog is available to cycle through existing AUI panes;
  (n) Some flags which allow to choose the orientation and the position of the minimized panes;
  (o) The functions [Get]MinimizeMode() in `AuiPaneInfo` which allow to set/get the flags described above;
  (p) Events like ``EVT_AUI_PANE_DOCKING``, ``EVT_AUI_PANE_DOCKED``, ``EVT_AUI_PANE_FLOATING`` and ``EVT_AUI_PANE_FLOATED`` are
      available for all panes *except* toolbar panes;
  (q) Implementation of the RequestUserAttention method for panes;
  (r) Ability to show the caption bar of docked panes on the left instead of on the top (with caption
      text rotated by 90 degrees then). This is similar to what `wxDockIt` did. To enable this feature on any
      given pane, simply call `CaptionVisible(True, left=True)`;
  (s) New Aero-style docking guides: you can enable them by using the `AuiManager` style ``AUI_MGR_AERO_DOCKING_GUIDES``;
  (t) A slide-in/slide-out preview of minimized panes can be seen by enabling the `AuiManager` style
      ``AUI_MGR_PREVIEW_MINIMIZED_PANES`` and by hovering with the mouse on the minimized pane toolbar tool;
  (u) New Whidbey-style docking guides: you can enable them by using the `AuiManager` style ``AUI_MGR_WHIDBEY_DOCKING_GUIDES``;
  (v) Native of custom-drawn mini frames can be used as floating panes, depending on the ``AUI_MGR_USE_NATIVE_MINIFRAMES`` style;
  (w) A "smooth docking effect" can be obtained by using the ``AUI_MGR_SMOOTH_DOCKING`` style (similar to PyQT docking style);
  (x) Implementation of "Movable" panes, i.e. a pane that is set as `Movable()` but not `Floatable()` can be dragged and docked
      into a new location but will not form a floating window in between.

- AuiNotebook:

  (a) Implementation of the style ``AUI_NB_HIDE_ON_SINGLE_TAB``, a la :mod:`lib.agw.flatnotebook`;
  (b) Implementation of the style ``AUI_NB_SMART_TABS``, a la :mod:`lib.agw.flatnotebook`;
  (c) Implementation of the style ``AUI_NB_USE_IMAGES_DROPDOWN``, which allows to show tab images
      on the tab dropdown menu instead of bare check menu items (a la :mod:`lib.agw.flatnotebook`);
  (d) 6 different tab arts are available, namely:

      (1) Default "glossy" theme (as in :class:`~auibook.AuiNotebook`)
      (2) Simple theme (as in :class:`~auibook.AuiNotebook`)
      (3) Firefox 2 theme
      (4) Visual Studio 2003 theme (VC71)
      (5) Visual Studio 2005 theme (VC81)
      (6) Google Chrome theme

  (e) Enabling/disabling tabs;
  (f) Setting the colour of the tab's text;
  (g) Implementation of the style ``AUI_NB_CLOSE_ON_TAB_LEFT``, which draws the tab close button on
      the left instead of on the right (a la Camino browser);
  (h) Ability to save and load perspectives in `AuiNotebook` (experimental);
  (i) Possibility to add custom buttons in the `AuiNotebook` tab area;
  (j) Implementation of the style ``AUI_NB_TAB_FLOAT``, which allows the floating of single tabs.
      Known limitation: when the notebook is more or less full screen, tabs cannot be dragged far
      enough outside of the notebook to become floating pages;
  (k) Implementation of the style ``AUI_NB_DRAW_DND_TAB`` (on by default), which draws an image
      representation of a tab while dragging;
  (l) Implementation of the `AuiNotebook` unsplit functionality, which unsplit a splitted AuiNotebook
      when double-clicking on a sash;
  (m) Possibility to hide all the tabs by calling `HideAllTAbs`;
  (n) wxPython controls can now be added inside page tabs by calling `AddControlToPage`, and they can be
      removed by calling `RemoveControlFromPage`;
  (o) Possibility to preview all the pages in a `AuiNotebook` (as thumbnails) by using the `NotebookPreview`
      method of `AuiNotebook`;
  (p) Tab labels can be edited by calling the `SetRenamable` method on a `AuiNotebook` page;
  (q) Support for multi-lines tab labels in `AuiNotebook`;
  (r) Support for setting minimum and maximum tab widths for fixed width tabs;
  (s) Implementation of the style ``AUI_NB_ORDER_BY_ACCESS``, which orders the tabs by last access time
      inside the Tab Navigator dialog;
  (t) Implementation of the style ``AUI_NB_NO_TAB_FOCUS``, allowing the developer not to draw the tab
      focus rectangle on tne `AuiNotebook` tabs.

|

- AuiToolBar:

  (a) ``AUI_TB_PLAIN_BACKGROUND`` style that allows to easy setup a plain background to the AUI toolbar,
      without the need to override drawing methods. This style contrasts with the default behaviour
      of the :class:`~auibar.AuiToolBar` that draws a background gradient and this break the window design when
      putting it within a control that has margin between the borders and the toolbar (example: put
      :class:`~auibar.AuiToolBar` within a :class:`StaticBoxSizer` that has a plain background);
  (b) `AuiToolBar` allow item alignment: http://trac.wxwidgets.org/ticket/10174;
  (c) `AUIToolBar` `DrawButton()` improvement: http://trac.wxwidgets.org/ticket/10303;
  (d) `AuiToolBar` automatically assign new id for tools: http://trac.wxwidgets.org/ticket/10173;
  (e) `AuiToolBar` Allow right-click on any kind of button: http://trac.wxwidgets.org/ticket/10079;
  (f) `AuiToolBar` idle update only when visible: http://trac.wxwidgets.org/ticket/10075;
  (g) Ability of creating `AuiToolBar` tools with [counter]clockwise rotation. This allows to propose a
      variant of the minimizing functionality with a rotated button which keeps the caption of the pane
      as label;
  (h) Allow setting the alignment of all tools in a toolbar that is expanded;
  (i) Implementation of the ``AUI_MINIMIZE_POS_TOOLBAR`` flag, which allows to minimize a pane inside
      an existing toolbar. Limitation: if the minimized icon in the toolbar ends up in the overflowing
      items (i.e., a menu is needed to show the icon), this style will not work.

TODOs
=====

- Documentation, documentation and documentation;
- Fix `tabmdi.AuiMDIParentFrame` and friends, they do not work correctly at present;
- Allow specification of `CaptionLeft()` to `AuiPaneInfo` to show the caption bar of docked panes
  on the left instead of on the top (with caption text rotated by 90 degrees then). This is
  similar to what `wxDockIt` did - DONE;
- Make developer-created `AuiNotebooks` and automatic (framemanager-created) `AuiNotebooks` behave
  the same way (undocking of tabs) - DONE, to some extent;
- Find a way to dock panes in already floating panes (`AuiFloatingFrames`), as they already have
  their own `AuiManager`;
- Add more gripper styles (see, i.e., PlusDock 4.0);
- Add an "AutoHide" feature to docked panes, similar to fly-out floating panes (see, i.e., PlusDock 4.0);
- Add events for panes when they are about to float or to be docked (something like
  ``EVT_AUI_PANE_FLOATING/ED`` and ``EVT_AUI_PANE_DOCKING/ED``) - DONE, to some extent;
- Implement the 4-ways splitter behaviour for horizontal and vertical sashes if they intersect;
- Extend `tabart.py` with more aui tab arts;
- Implement ``AUI_NB_LEFT`` and ``AUI_NB_RIGHT`` tab locations in `AuiNotebook`;
- Move `AuiDefaultToolBarArt` into a separate module (as with `tabart.py` and `dockart.py`) and
  provide more arts for toolbars (maybe from :mod:`lib.agw.flatmenu`?)
- Support multiple-rows/multiple columns toolbars;
- Integrate as much as possible with :mod:`lib.agw.flatmenu`, from dropdown menus in `AuiNotebook` to
  toolbars and menu positioning;
- Possibly handle minimization of panes in a different way (or provide an option to switch to
  another way of minimizing panes);
- Clean up/speed up the code, especially time-consuming for-loops;
- Possibly integrate `wxPyRibbon` (still on development), at least on Windows.

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

AUI library is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 09 Jan 2014, 22.00 GMT

Version 1.3.

This module contains all the constants used by wxPython-AUI.

Especially important and meaningful are constants for AuiManager, AuiDockArt and
AuiNotebook.

# -*- coding: utf-8 -*-
#----------------------------------------------------------------------------
# Name:         aui_constants.py
# Purpose:
#
# Author:       Andrea Gavana <andrea.gavana@gmail.com>
#
# Created:
# Version:
# Date:         31 March 2009
# Licence:      wxWindows license
# Tags:         phoenix-port, unittest, documented, py3-port

PyEmbeddedImage is primarily intended to be used by code generated
by img2py as a means of embedding image data in a python module so
the image can be used at runtime without needing to access the
image from an image file.  This makes distributing icons and such
that an application uses simpler since tools like py2exe will
automatically bundle modules that are imported, and the
application doesn't have to worry about how to locate the image
files on the user's filesystem.

The class can also be used for image data that may be acquired
from some other source at runtime, such as over the network or
from a database.  In this case pass False for isBase64 (unless the
data actually is base64 encoded.)  Any image type that
wx.Image can handle should be okay.

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

int([x]) -> integer
int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments
are given.  If x is a number, return x.__int__().  For floating point
numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base.  The literal can be preceded by '+' or '-' and be surrounded
by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.
>>> int('0b100', base=0)
4

bytes(iterable_of_ints) -> bytes
bytes(string, encoding[, errors]) -> bytes
bytes(bytes_or_buffer) -> immutable copy of bytes_or_buffer
bytes(int) -> bytes object of size given by the parameter initialized with null bytes
bytes() -> empty bytes object

Construct an immutable array of bytes from:
  - an iterable yielding integers in range(256)
  - a text string encoded using the specified encoding
  - any object implementing the buffer API.
  - an integer

Colour()
Colour(red, green, blue, alpha=ALPHA_OPAQUE)
Colour(colRGB)
Colour(colour)

A colour is an object representing a combination of Red, Green, and
Blue (RGB) intensity values and an Alpha value, and is used to
determine drawing colours.

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.

[b'16 15 3 1', b'       c None', b'.      c #000000', b'+      c #FFFFFF', b'                ', b'     .......... ', b'     .++++++++. ', b'     .......... ', b'     .++++++++. ', b' ..........+++. ', b' .++++++++.+++. ', b' ..........+++. ', b' .++++++++..... ', b' .++++++++.     ', b' .++++++++.     ', b' .++++++++.     ', b' .++++++++.     ', b' ..........     ', b'                ']

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

The idea of `SwitcherDialog` is to make it easier to implement keyboard
navigation in AUI and other applications that have multiple panes and
tabs.

A key combination with a modifier (such as ``Ctrl`` + ``Tab``) shows the
dialog, and the user holds down the modifier whilst navigating with
``Tab`` and arrow keys before releasing the modifier to dismiss the dialog
and activate the selected pane.

The switcher dialog is a multi-column menu with no scrolling, implemented
by the :class:`MultiColumnListCtrl` class. You can have headings for your items
for logical grouping, and you can force a column break if you need to.

The modifier used for invoking and dismissing the dialog can be customised,
as can the colours, number of rows, and the key used for cycling through
the items. So you can use different keys on different platforms if
required (especially since ``Ctrl`` + ``Tab`` is reserved on some platforms).

Items are shown as names and optional 16x16 images.

Base Functionalities
====================

To use the dialog, you set up the items in a `SwitcherItems` object,
before passing this to the `SwitcherDialog` instance.

Call :meth:`SwitcherItems.AddItem` and optionally :meth:`SwitcherItems.AddGroup`
to add items and headings. These functions take a label (to be displayed to the user),
an identifying name, an integer id, and a bitmap. The name and id are purely for
application-defined identification. You may also set a description to be displayed
when each item is selected; and you can set a window pointer for convenience when
activating the desired window after the dialog returns.

Have created the dialog, you call :meth:`~Dialog.ShowModal`, and if the return value is
``wx.ID_OK``, retrieve the selection from the dialog and activate the pane.

The sample code below shows a generic method of finding panes and notebook
tabs within the current :class:`~wx.lib.agw.aui.framemanager.AuiManager`, and using the pane name or notebook
tab position to display the pane.

The only other code to add is a menu item with the desired accelerator,
whose modifier matches the one you pass to :meth:`SwitcherDialog.SetModifierKey`
(the default being ``wx.WXK_CONTROL``).

Usage
=====

Menu item::

    if wx.Platform == "__WXMAC__":
        switcherAccel = "Alt+Tab"
    elif wx.Platform == "__WXGTK__":
        switcherAccel = "Ctrl+/"
    else:
        switcherAccel = "Ctrl+Tab"

    view_menu.Append(ID_SwitchPane, _("S&witch Window...") + "  " + switcherAccel)

Event handler::

    def OnSwitchPane(self, event):

        items = SwitcherItems()
        items.SetRowCount(12)

        # Add the main windows and toolbars, in two separate columns
        # We'll use the item 'id' to store the notebook selection, or -1 if not a page

        for k in range(2):
            if k == 0:
                items.AddGroup(_("Main Windows"), "mainwindows")
            else:
                items.AddGroup(_("Toolbars"), "toolbars").BreakColumn()

            for pane in self._mgr.GetAllPanes():
                name = pane.name
                caption = pane.caption

                toolbar = isinstance(info.window, wx.ToolBar) or isinstance(info.window, aui.AuiToolBar)
                if caption and (toolBar  and k == 1) or (not toolBar and k == 0):
                    items.AddItem(caption, name, -1).SetWindow(pane.window)

        # Now add the wxAuiNotebook pages

        items.AddGroup(_("Notebook Pages"), "pages").BreakColumn()

        for pane in self._mgr.GetAllPanes():
            nb = pane.window
            if isinstance(nb, aui.AuiNotebook):
                for j in range(nb.GetPageCount()):

                    name = nb.GetPageText(j)
                    win = nb.GetPage(j)

                    items.AddItem(name, name, j, nb.GetPageBitmap(j)).SetWindow(win)

        # Select the focused window

        idx = items.GetIndexForFocus()
        if idx != wx.NOT_FOUND:
            items.SetSelection(idx)

        if wx.Platform == "__WXMAC__":
            items.SetBackgroundColour(wx.WHITE)

        # Show the switcher dialog

        dlg = SwitcherDialog(items, wx.GetApp().GetTopWindow())

        # In GTK+ we can't use Ctrl+Tab; we use Ctrl+/ instead and tell the switcher
        # to treat / in the same was as tab (i.e. cycle through the names)

        if wx.Platform == "__WXGTK__":
            dlg.SetExtraNavigationKey(wxT('/'))

            dlg.SetBackgroundColour(wx.WHITE)
            dlg.SetModifierKey(wx.WXK_ALT)

        ans = dlg.ShowModal()

        if ans == wx.ID_OK and dlg.GetSelection() != -1:
            item = items.GetItem(dlg.GetSelection())

            if item.GetId() == -1:
                info = self._mgr.GetPane(item.GetName())
                info.Show()
                self._mgr.Update()
                info.window.SetFocus()

            else:
                nb = item.GetWindow().GetParent()
                win = item.GetWindow();
                if isinstance(nb, aui.AuiNotebook):
                    nb.SetSelection(item.GetId())
                    win.SetFocus()

# Name:         aui_switcherdialog.py
# Purpose:
#
# Author:
#
# Created:
# Version:
# Date:
# Tags:         phoenix-port, documented, py3-port

__init__(self, parent, aui_manager, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="MultiColumnListCtrl")

Set an extra key that can be used to cycle through items,
in case not using the ``Ctrl`` + ``Tab`` combination.

Set the modifier used to invoke the dialog, and therefore to test for release.

SwitcherDialog shows a :class:`Dialog` with a list of panes and tabs for the user to choose.
``Ctrl`` + ``Tab`` cycles through them.

__init__(self, items, parent, aui_manager, id=wx.ID_ANY, title=_("Pane Switcher"), pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.STAY_ON_TOP|wx.DIALOG_NO_PARENT|wx.BORDER_SIMPLE)

Copy operator between 2 :class:`SwitcherItem` instances.

:param `item`: another instance of :class:`SwitcherItem`.

AddItem(self, titleOrItem, name=None, id=0, bitmap=wx.NullBitmap)

Copy operator between 2 :class:`SwitcherItems`.

:param `items`: another instance of :class:`SwitcherItems`.

Find a window with the focus, that is also a descendant of the given window.
This is used to determine the window to initially send commands to.

:param wx.Window `ancestor`: the window to check for ancestry.

This module contains some common functions used by :mod:`lib.agw.aui` to
manipulate colours, bitmaps, text, gradient shadings and custom dragging images
for :class:`~wx.lib.agw.aui.auibook.AuiNotebook` tabs.

# Name:         aui_utilities.py
# Purpose:
#
#
# Created:
# Version:

This class handles the creation of a custom image in case of drag and drop of a notebook tab.

Default class constructor.

For internal use: do not call it in your code!

:param `notebook`: an instance of :class:`~wx.lib.agw.aui.auibook.AuiNotebook`;
:param `page`: the dragged :class:`~wx.lib.agw.aui.auibook.AuiNotebookPage` page;
:param integer `button_state`: the state of the close button on the tab;
:param `tabArt`: an instance of :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt` or one of its derivations.

Actually creates the drag and drop bitmap.

A utility function that creates a masked bitmap from raw bits (XBM format).

:param string `bits`: the raw bits of the bitmap;
:param integer `w`: the bitmap width;
:param integer `h`: the bitmap height;
:param wx.Colour `colour`: the colour which will replace all white pixels in the
 raw bitmap.

Blends the two colour component `fg` and `bg` into one colour component, adding
an optional alpha channel.

:param wx.Colour `fg`: the first colour component;
:param wx.Colour `bg`: the second colour component;
:param integer `alpha`: an optional transparency value.

Chops the input `text` if its size does not fit in `max_size`, by cutting the
text and adding ellipsis at the end.

:param `dc`: a :class:`wx.DC` device context;
:param string `text`: the text to chop;
:param integer `max_size`: the maximum size in which the text should fit.

Clips the value in `a` based on the extremes `b` and `c`.

:param `a`: the value to analyze;
:param `b`: a minimum value;
:param `c`: a maximum value.

Copies pens, brushes, colours and fonts from the old tab art to the new one.

:param `newArt`: the new instance of :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt`;
:param `oldArt`: the old instance of :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt`.

Darkens the input bitmap on wxMAC using the input colour.

:param wx.Bitmap `bmp`: the bitmap to be manipulated;
:param wx.Colour `caption_colour`: the colour of the pane caption;
:param wx.Colour `new_colour`: the colour used to darken the bitmap.

Draws a gradient-shaded rectangle.

:param wx.Rect `rect`: the rectangle in which to draw the gradient;
:param wx.Colour `start_colour`: the first colour of the gradient;
:param wx.Colour `end_colour`: the second colour of the gradient;
:param integer `direction`: the gradient direction (horizontal or vertical).

DrawGradientRectangle(dc, rect, start_colour, end_colour, direction, offset=0, length=0)

Draws the wxMAC tab close button using :class:`GraphicsContext`.

:param wx.Colour `colour`: the colour to use to draw the circle;
:param wx.Colour `backColour`: the optional background colour for the circle.

Returns the face shading colour on push buttons/backgrounds,
mimicking as closely as possible the platform UI colours.

Returns the correct name of the docking bitmap depending on the input parameters.

:param bool `useAero`: whether :class:`~wx.lib.agw.aui.framemanager.AuiManager` is using
 Aero-style or Whidbey-style docking images or not;
:param bool `center`: whether we are looking for the center diamond-shaped bitmap or not.

Returns the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` item label size.

:param string `label`: the toolbar tool label;
:param bool `vertical`: whether the toolbar tool orientation is vertical or not.

Returns the point at which the sliding in and out of a minimized pane begins.

:param wx.Rect `rect`: the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` tool screen rectangle;
:param wx.Size `size`: the pane window size;
:param integer `direction`: the pane docking direction.

Indents the input rectangle `rect` based on the value of `button_state`.

:param wx.Rect `rect`: the button bitmap rectangle;
:param integer `button_state`: the button state.

Brighten input `colour` by `percent`.

:param wx.Colour `colour`: the colour to be brightened;
:param integer `percent`: brightening percentage.

Creates a new, lighter colour based on the input colour `c`.

:param wx.Colour `c`: the input colour to analyze.

Convert the given image (in place) to a grayed-out version, appropriate for a 'disabled' appearance.

:param wx.Bitmap `bitmap`: the bitmap to gray-out.

Creates a stipple bitmap to be used in a :class:`wx.Brush`.

This is used to draw sash resize hints.

Rescales a bitmap to be `thumbnail_size` pixels wide (or tall) at maximum.

:param wx.Bitmap `bmp`: the bitmap to rescale;
:param integer `thumbnail_size`: the maximum size of every page thumbnail.

Darken/lighten the input colour `c`.

:param wx.Colour `c`: a colour to darken/lighten;
:param integer `ialpha`: a transparency value.

Takes a screenshot of the screen at given position and size (`rect`).

:param wx.Rect `rect`: the screen rectangle for which we want to take a screenshot.

`auibar.py` contains an implementation of
:class:`~wx.lib.agw.aui.auibar.AuiToolBar`, which is a completely owner-drawn
toolbar perfectly integrated with the AUI layout system. This allows drag and
drop of toolbars, docking/floating behaviour and the possibility to define
"overflow" items in the toolbar itself.

The default theme that is used is :class:`AuiToolBar`, which provides a modern,
glossy look and feel. The theme can be changed by calling
:meth:`AuiToolBar.SetArtProvider`.

# Name:         auibar.py
# Purpose:
#
#
# Created:
# Version:

Toolbar art provider code - a tab provider provides all drawing functionality to the :class:`AuiToolBar`.
This allows the :class:`AuiToolBar` to have a pluggable look-and-feel.

By default, a :class:`AuiToolBar` uses an instance of this class called :class:`AuiDefaultToolBarArt`
which provides bitmap art and a colour scheme that is adapted to the major platforms'
look. You can either derive from that class to alter its behaviour or write a
completely new tab art class. Call :meth:`AuiToolBar.SetArtProvider` to make use this new tab art.

Draws a toolbar background with a gradient shading.

:param `wnd`: a :class:`wx.Window` derived window;
:param wx.Rect `_rect`: the :class:`AuiToolBarItem` rectangle;
:param bool `horizontal`: ``True`` if the toolbar is horizontal, ``False`` if it is vertical.

Draws a toolbar item button.

:param `item`: an instance of :class:`AuiToolBarItem`;
:param wx.Rect `rect`: the :class:`AuiToolBarItem` rectangle.

Draws a label for a toolbar control.

Draws a toolbar dropdown button.

Draws the toolbar gripper.

Draws a toolbar item label.

Draws the overflow button for the :class:`AuiToolBar`.

:param wx.Rect `rect`: the :class:`AuiToolBarItem` rectangle;
:param integer `state`: the overflow button state.

Draws a toolbar background with a plain colour.

This method contrasts with the default behaviour of the :class:`AuiToolBar` that
draws a background gradient and this break the window design when putting
it within a control that has margin between the borders and the toolbar
(example: put :class:`AuiToolBar` within a :class:`StaticBoxSizer` that has a plain background).

:param wx.Rect `_rect`: the :class:`AuiToolBarItem` rectangle.

Draws a toolbar separator.

Returns the :class:`AuiDefaultToolBarArt` flags.

:see: :meth:`~AuiDefaultToolBarArt.SetAGWFlags` for more details.

Returns the size of a UI element in the :class:`AuiToolBar`.

:param integer `element_id`: can be one of the following:

 ==================================== ==================================
 Element Identifier                   Description
 ``AUI_TBART_SEPARATOR_SIZE``         Separator size in :class:`AuiToolBar`
 ``AUI_TBART_GRIPPER_SIZE``           Gripper size in :class:`AuiToolBar`
 ``AUI_TBART_OVERFLOW_SIZE``          Overflow button size in :class:`AuiToolBar`

Returns the label size for a toolbar item.

:param `item`: an instance of :class:`AuiToolBarItem`.

Returns the :class:`AuiDefaultToolBarArt` text orientation.

:see: :meth:`~AuiDefaultToolBarArt.SetTextOrientation` for more details.

Returns the toolbar item size.

Returns the bitmap and text rectangles for a toolbar item.

:param wx.Rect `rect`: the tool rectangle.

Sets the toolbar art flags.

:param integer `agwFlags`: a combination of the following values:

 Flag name                            Description
 ``AUI_TB_TEXT``                      Shows the text in the toolbar buttons; by default only icons are shown
 ``AUI_TB_NO_TOOLTIPS``               Don't show tooltips on :class:`AuiToolBar` items
 ``AUI_TB_NO_AUTORESIZE``             Do not auto-resize the :class:`AuiToolBar`
 ``AUI_TB_GRIPPER``                   Shows a gripper on the :class:`AuiToolBar`
 ``AUI_TB_OVERFLOW``                  The :class:`AuiToolBar` can contain overflow items
 ``AUI_TB_VERTICAL``                  The :class:`AuiToolBar` is vertical
 ``AUI_TB_HORZ_LAYOUT``               Shows the text and the icons alongside, not vertically stacked. This style
                                      must be used with ``AUI_TB_TEXT``
 ``AUI_TB_PLAIN_BACKGROUND``          Don't draw a gradient background on the toolbar
 ``AUI_TB_HORZ_TEXT``                 Combination of ``AUI_TB_HORZ_LAYOUT`` and ``AUI_TB_TEXT``

Sets the default colours, which are calculated from the given base colour.

:param `base_colour`: an instance of :class:`wx.Colour`. If defaulted to ``None``, a colour
 is generated accordingly to the platform and theme.

Sets the size of a UI element in the :class:`AuiToolBar`.

:param integer `size`: the new size of the UI element.

Sets the :class:`AuiDefaultToolBarArt` font.

:param wx.Font `font`: the font used for displaying toolbar item labels.

Sets the toolbar tool orientation.

:param integer `orientation`: one of ``AUI_TBTOOL_HORIZONTAL``, ``AUI_TBTOOL_VERT_CLOCKWISE`` or
 ``AUI_TBTOOL_VERT_COUNTERCLOCKWISE``.

Sets the text orientation.

:param integer `orientation`: can be one of the following constants:

 Orientation Switches                 Description
 ``AUI_TBTOOL_TEXT_LEFT``             Text in :class:`AuiToolBar` items is aligned left
 ``AUI_TBTOOL_TEXT_RIGHT``            Text in :class:`AuiToolBar` items is aligned right
 ``AUI_TBTOOL_TEXT_TOP``              Text in :class:`AuiToolBar` items is aligned top
 ``AUI_TBTOOL_TEXT_BOTTOM``           Text in :class:`AuiToolBar` items is aligned bottom

Shows the drop down window menu for overflow items.

:param `wnd`: an instance of :class:`wx.Window`;
:param list `items`: a list of the overflow toolbar items.

AuiToolBar is a completely owner-drawn toolbar perfectly integrated with the AUI layout system.
This allows drag and drop of toolbars, docking/floating behaviour and the possibility to define

The default theme that is used is :class:`AuiDefaultToolBarArt`, which provides a modern,
glossy look and feel. The theme can be changed by calling :meth:`AuiToolBar.SetArtProvider`.

:param wx.Window `parent`: the :class:`AuiToolBar` parent;
:param integer `id`: an identifier for the control: a value of -1 is taken to mean a default;
:param wx.Point `pos`: the control position. A value of (-1, -1) indicates a default position,
 chosen by either the windowing system or wxPython, depending on platform;
:param wx.Size `size`: the control size. A value of (-1, -1) indicates a default size,
:param integer `style`: the control window style;
:param integer `agwStyle`: the AGW-specific window style. This can be a combination of the
 following bits:

 ``AUI_TB_HORZ_LAYOUT``               Shows the text and the icons alongside, not vertically stacked.
                                      This style must be used with ``AUI_TB_TEXT``

 The default value for `agwStyle` is: ``AUI_TB_DEFAULT_STYLE`` = 0

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=AUI_TB_DEFAULT_STYLE)

Adds a new check (or toggle) tool to the :class:`AuiToolBar`.

:see: :meth:`AddTool` for an explanation of the input parameters.

AddCheckTool(self, tool_id, label, bitmap, disabled_bitmap, short_help_string="", long_help_string="", client_data=None)

Adds any control to the toolbar, typically e.g. a :class:`ComboBox`.

:param wx.Window `control`: the control to be added;
:param string `label`: the label which appears if the control goes into the
 overflow items in the toolbar.

Adds a label tool to the :class:`AuiToolBar`.

:param integer `tool_id`: an integer by which the tool may be identified in subsequent operations;
:param integer `width`: the tool width.

Adds a new radio tool to the toolbar.

Consecutive radio tools form a radio group such that exactly one button
in the group is pressed at any moment, in other words whenever a button
in the group is pressed the previously pressed button is automatically
released. You should avoid having the radio groups of only one element
as it would be impossible for the user to use such button.

:note: By default, the first button in the radio group is initially pressed,
 the others are not.

AddRadioTool(self, tool_id, label, bitmap, disabled_bitmap, short_help_string="", long_help_string="", client_data=None)

Adds a tool to the toolbar. This is the simplest method you can use to
add an item to the :class:`AuiToolBar`.

:param wx.Bitmap `bitmap`: the primary tool bitmap;
:param string `short_help_string`: this string is used for the tools tooltip;
:param integer `kind`: the item kind. Can be one of the following:

 ========================  =============================
 Item Kind                 Description
 ``ITEM_CONTROL``          The item in the :class:`AuiToolBar` is a control
 ``ITEM_LABEL``            The item in the :class:`AuiToolBar` is a text label
 ``ITEM_SPACER``           The item in the :class:`AuiToolBar` is a spacer
 ``ITEM_SEPARATOR``        The item in the :class:`AuiToolBar` is a separator
 ``ITEM_CHECK``            The item in the :class:`AuiToolBar` is a toolbar check item
 ``ITEM_NORMAL``           The item in the :class:`AuiToolBar` is a standard toolbar item
 ``ITEM_RADIO``            The item in the :class:`AuiToolBar` is a toolbar radio item

:param `target`: a custom string indicating that an instance of :class:`~wx.lib.agw.aui.framemanager.AuiPaneInfo`
 has been minimized into this toolbar.

AddSimpleTool(self, tool_id, label, bitmap, short_help_string="", kind=ITEM_NORMAL, target=None)

Adds a spacer for spacing groups of tools.

:param integer `pixels`: the width of the spacer.

Adds a stretchable spacer for spacing groups of tools.

:param integer `proportion`: the stretchable spacer proportion.

Adds a toggle tool to the toolbar.

:param wx.Bitmap `disabled_bitmap`: the bitmap to use when the tool is disabled. If it is equal to
 :class:`NullBitmap`, the disabled bitmap is automatically generated by greing the normal one;
:param PyObject `client_data`: whatever Python object to associate with the toolbar item;
:param string `long_help_string`: this string is shown in the statusbar (if any) of the parent
 frame when the mouse pointer is inside the tool.

AddToggleTool(self, tool_id, bitmap, disabled_bitmap, toggle=False, client_data=None, short_help_string="", long_help_string="")

Adds a tool to the toolbar. This is the full feature version of :meth:`AddTool`.

:param PyObject `client_data`: whatever Python object to associate with the toolbar item.

AddTool(self, tool_id, label, bitmap, disabled_bitmap, kind, short_help_string='', long_help_string='', client_data=None, target=None)

Removes the specified tool from the toolbar and deletes it.

:param integer `tool_id`: the :class:`AuiToolBarItem` identifier.

:returns: ``True`` if the tool was deleted, ``False`` otherwise.

:note: Note that it is unnecessary to call :meth:`Realize` for the change to
 take place, it will happen immediately.

This function behaves like :meth:`DeleteTool` but it deletes the tool at the specified position and not the one with the given id.

:param integer `pos`: the tool position.

:see: :meth:`~AuiToolBar.DeleteTool`

Gets the size which best suits the window: for a control, it would be the
minimal size which doesn't truncate the control, for a panel - the same
size as it would have after a call to `Fit()`.

:note: Overridden from :class:`wx.Control`.

Sets the position and size of the window in pixels. The `sizeFlags`
parameter indicates the interpretation of the other params if they are
equal to -1.

:param integer `x`: the window `x` position;
:param integer `y`: the window `y` position;
:param integer `width`: the window width;
:param integer `height`: the window height;
:param integer `sizeFlags`: may have one of this bit set:

 ===================================  ======================================
 Size Flags                           Description
 ``wx.SIZE_AUTO``                     A -1 indicates that a class-specific default should be used.
 ``wx.SIZE_AUTO_WIDTH``               A -1 indicates that a class-specific default should be used for the width.
 ``wx.SIZE_AUTO_HEIGHT``              A -1 indicates that a class-specific default should be used for the height.
 ``wx.SIZE_USE_EXISTING``             Existing dimensions should be used if -1 values are supplied.
 ``wx.SIZE_ALLOW_MINUS_ONE``          Allow dimensions of -1 and less to be interpreted as real dimensions, not default values.
 ``wx.SIZE_FORCE``                    Normally, if the position and the size of the window are already the same as the
                                      parameters of this function, nothing is done. but with this flag a window resize may
                                      be forced even in this case (supported in wx 2.6.2 and later and only implemented
                                      for MSW and ignored elsewhere currently)

Enables or disables the tool.

:param integer `tool_id`: identifier for the tool to enable or disable.
:param bool `state`: if ``True``, enables the tool, otherwise disables it.

Returns a pointer to the control identified by `id` or ``None`` if no corresponding control is found.

:param integer `id`: the control identifier.

Finds a tool for the given tool id.

Finds a tool for the given tool position in the :class:`AuiToolBar`.

:param integer `pos`: the tool position in the toolbar.

:returns: a pointer to a :class:`AuiToolBarItem` if a tool is found, or ``None`` otherwise.

Finds a tool for the given label.

:param string `label`: the :class:`AuiToolBarItem` label.

Finds a tool for the given mouse position.

:param integer `x`: mouse `x` position;
:param integer `y`: mouse `y` position.

Finds a tool for the given mouse position, taking into account also the tool packing.

Returns the AGW-specific window style flag.

:see: :meth:`SetAGWWindowStyleFlag` for an explanation of various AGW-specific style.

Returns the :class:`~wx.lib.agw.aui.framemanager.AuiManager` which manages the toolbar. 

Returns the standard size of a toolbar item.

:param string `label`: a test label.

Returns whether the :class:`AuiToolBar` size fits in a specified size. 

Returns the tool bitmap for the tool identified by `tool_id`.

:param integer `tool_id`: the tool identifier.

Returns the size of bitmap that the toolbar expects to have. The default bitmap size is 16 by 15 pixels.

:note: Note that this is the size of the bitmap you pass to :meth:`AddTool`,
 and not the eventual size of the tool button.

.. todo::

   Add :class:`ToolBar` compatibility, actually implementing this method.

Returns the padding between the tool border and the label, in pixels. 

Returns whether the toolbar item identified by `tool_id` has an associated drop down window menu or not.

Returns whether the tool identified by `tool_id` is enabled or not.

Returns whether the tool identified by `tool_id` fits into the toolbar or not.

:param integer `tool_id`: the toolbar item identifier.

Returns the position of the tool in the toolbar given its identifier.

Returns the tool label for the tool identified by `tool_id`.

Returns the long help for the given tool.

Returns the value used for spacing tools. The default value is 1 pixel. 

Returns the tool proportion in the toolbar.

Returns the toolbar item rectangle

Returns the short help for the given tool.

Returns whether the toolbar item identified by `tool_id` has a sticky behaviour or not.

Returns whether a tool is toggled or not.

:note: This only applies to a tool that has been specified as a toggle tool.

:param integer `x`: mouse `x` screen position;
:param integer `y`: mouse `y` screen position.

:note: This method is similar to :meth:`FindToolForPosition` but it works with absolute coordinates.

Returns whether this :class:`AuiToolBar` contains a minimized pane tool. 

Handles custom render for single :class:`AuiToolBar` items.

:param wx.Rect `rect`: the toolbar item rect.

:note: This method must be overridden to provide custom rendering of items.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`AuiToolBar`.

:param `event`: a :class:`EraseEvent` event to be processed.

:note: This is intentionally empty, to reduce flicker.

Handles the ``wx.EVT_IDLE`` event for :class:`AuiToolBar`.

:param `event`: a :class:`IdleEvent` event to be processed.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`AuiToolBar`.

:param `event`: a :class:`MouseEvent` event to be processed.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_MIDDLE_UP`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiToolBar`.

:param `event`: a :class:`PaintEvent` event to be processed.

Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_RIGHT_UP`` event for :class:`AuiToolBar`.

Handles the ``wx.EVT_SET_CURSOR`` event for :class:`AuiToolBar`.

:param `event`: a :class:`SetCursorEvent` event to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`AuiToolBar`.

:param `event`: a :class:`wx.SizeEvent` event to be processed.

Realizes the toolbar. This function should be called after you have added tools. 

Sets the AGW-specific style of the window.

:param integer `agwStyle`: the new window style. This can be a combination of the

:note: Please note that some styles cannot be changed after the window
 creation and that `Refresh` might need to be be called after changing the
 others for the change to take place immediately.

Instructs :class:`AuiToolBar` to use art provider specified by parameter `art`
for all drawing calls. This allows pluggable look-and-feel features.

:param `art`: an art provider.

:note: The previous art provider object, if any, will be deleted by :class:`AuiToolBar`.

Sets the :class:`~wx.lib.agw.aui.framemanager.AuiManager` which manages the toolbar. 

Sets the two lists `prepend` and `append` as custom overflow items.

:param list `prepend`: a list of :class:`AuiToolBarItem` to be prepended;
:param list `append`: a list of :class:`AuiToolBarItem` to be appended.

Sets the :class:`AuiToolBar` font.

:param wx.Font `font`: the new toolbar font.

Sets whether the toolbar gripper is visible or not.

:param bool `visible`: ``True`` for a visible gripper, ``False`` otherwise.

Sets a toolbar item to be currently hovered by the mouse.

:param `pitem`: an instance of :class:`AuiToolBarItem`.

Set the values to be used as margins for the toolbar.

:param integer `left`: the left toolbar margin;
:param integer `right`: the right toolbar margin;
:param integer `top`: the top toolbar margin;
:param integer `bottom`: the bottom toolbar margin.

:param wx.Size `size`: the margin size (an instance of :class:`wx.Size`).

:param integer `x`: left margin, right margin and inter-tool separation value;
:param integer `y`: top margin, bottom margin and inter-tool separation value.

Sets the toolbar orientation.

:param integer `orientation`: either ``wx.VERTICAL`` or ``wx.HORIZONTAL``.

:note: This can be temporarily overridden by :class:`~wx.lib.agw.aui.framemanager.AuiManager` when floating and
 docking a :class:`AuiToolBar`.

Sets whether the overflow button is visible or not.

:param bool `visible`: ``True`` for a visible overflow button, ``False`` otherwise.

Sets a toolbar item to be currently in a "pressed" state.

This sets the alignment for all of the tools within the toolbar
(only has an effect when the toolbar is expanded).

:param integer `alignment`: :class:`wx.Sizer` alignment value
 (``wx.ALIGN_CENTER_HORIZONTAL`` or ``wx.ALIGN_CENTER_VERTICAL``).

Sets the tool bitmap for the tool identified by `tool_id`.

:param integer `tool_id`: the tool identifier;
:param wx.Bitmap `bitmap`: the new bitmap for the toolbar item.

Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.

:param wx.Size `size`: the size of the bitmaps in the toolbar.

:note: This should be called to tell the toolbar what the tool bitmap
 size is. Call it before you add tools.

.. todo::

Sets the padding between the tool border and the label.

:param integer `padding`: the padding in pixels.

Sets the tool disabled bitmap for the tool identified by `tool_id`.

:param wx.Bitmap `bitmap`: the new disabled bitmap for the toolbar item.

Assigns a drop down window menu to the toolbar item.

:param integer `tool_id`: the :class:`AuiToolBarItem` identifier;
:param bool `dropdown`: whether to assign a drop down menu or not.

Sets the tool label for the tool identified by `tool_id`.

:param string `label`: the new toolbar item label.

Sets the long help for the given tool.

:param string `help_string`: the string for the long help.

Sets the tool orientation for the toolbar items.

:param integer `orientation`: the :class:`AuiToolBarItem` orientation.

Sets the value used for spacing tools. The default value is 1 pixel.

:param integer `packing`: the value for packing.

Sets the tool proportion in the toolbar.

:param integer `proportion`: the tool proportion in the toolbar.

Sets the separator size for the toolbar.

:param integer `separation`: the separator size in pixels.

Sets the short help for the given tool.

:param string `help_string`: the string for the short help.

Sets the toolbar item as sticky or non-sticky.

:param bool `sticky`: whether the tool should be sticky or not.

Sets the label orientation for the toolbar items.

:param integer `orientation`: the :class:`AuiToolBarItem` label orientation.

Sets the style of the window.

:param integer `style`: the new window style.

Starts a timer in :class:`~wx.lib.agw.aui.framemanager.AuiManager` to slide-in/slide-out the minimized pane. 

Stops a timer in :class:`~wx.lib.agw.aui.framemanager.AuiManager` to slide-in/slide-out the minimized pane. 

Toggles a tool on or off. This does not cause any event to get emitted.

:param integer `tool_id`: tool in question.
:param bool `state`: if ``True``, toggles the tool on, otherwise toggles it off.

A specialized command event class for events sent by :class:`AuiToolBar`. 

:param `command_type`: the event kind or an instance of :class:`PyCommandEvent`.
:param integer `win_id`: the window identification number.

This is the opposite of :meth:`Veto`: it explicitly allows the event to be
processed. For most events it is not necessary to call this method as the
events are allowed anyhow but some are forbidden by default (this will
be mentioned in the corresponding event description).

Prevents the change announced by this event from happening.

It is in general a good idea to notify the user about the reasons for
vetoing the change because otherwise the applications behaviour (which
just refuses to do what the user wants) might be quite surprising.

AuiToolBarItem is a toolbar element.

It has a unique id (except for the separators which always have id = -1), the
style (telling whether it is a normal button, separator or a control), the
state (toggled or not, enabled or not) and short and long help strings. The
default implementations use the short help string for the tooltip text which
is popped up when the mouse pointer enters the tool and the long help string
for the applications status bar.

:param `item`: another instance of :class:`AuiToolBarItem`.

Assigns the properties of the :class:`AuiToolBarItem` `c` to `self`.

:param `c`: another instance of :class:`AuiToolBarItem`.

Returns the toolbar item kind.

See :meth:`SetKind` for more details.

Returns the correct bitmap depending on the tool orientation.

:param bool `disabled`: whether to return the disabled bitmap or not.

Returns the number of pixels for a toolbar item with kind = ``ITEM_SEPARATOR``. 

Returns the toolbar item state.

:see: :meth:`SetState` for more details.

Returns whether the toolbar item has an associated dropdown menu or not. 

Returns whether the toolbar item has a sticky behaviour or not. 

Activates/deactivates the toolbar item.

:param bool `b`: ``True`` to activate the item, ``False`` to deactivate it.

Sets the toolbar item alignment.

:param integer `align`: the item alignment, which can be one of the available :class:`wx.Sizer`
 alignments.

Sets the toolbar item bitmap.

:param wx.Bitmap `bmp`: the image associated with this :class:`AuiToolBarItem`.

Sets the toolbar item disabled bitmap.

:param wx.Bitmap `bmp`: the disabled image associated with this :class:`AuiToolBarItem`.

Sets whether the toolbar item has an associated dropdown menu.

:param bool `b`: ``True`` to set a dropdown menu, ``False`` otherwise.

Sets the toolbar item hover bitmap.

:param wx.Bitmap `bmp`: the hover image associated with this :class:`AuiToolBarItem`.

Sets the toolbar item identifier.

:param integer `new_id`: the new tool id.

Sets the :class:`AuiToolBarItem` kind.

:param integer `new_kind`: can be one of the following items:

Sets the toolbar item label.

:param string `s`: the toolbar item label.

Sets the long help string for the toolbar item. This string is shown in the
statusbar (if any) of the parent frame when the mouse pointer is inside the
tool.

:param string `s`: the tool long help string.

Sets the toolbar item minimum size.

:param wx.Size `s`: the toolbar item minimum size.

:param integer `a`: one of ``AUI_TBTOOL_HORIZONTAL``, ``AUI_TBTOOL_VERT_CLOCKWISE`` or

Sets the :class:`AuiToolBarItem` proportion in the toolbar.

:param integer `p`: the item proportion.

Sets the short help string for the :class:`AuiToolBarItem`, to be displayed in a
:class:`ToolTip` when the mouse hover over the toolbar item.

:param string `s`: the tool short help string.

Associates a sizer item to this toolbar item.

:param `s`: an instance of :class:`wx.SizerItem`.

Sets the number of pixels for a toolbar item with kind = ``ITEM_SEPARATOR``.

:param integer `s`: number of pixels.

Sets the toolbar item state.

:param `new_state`: can be one of the following states:

 ============================================  ======================================
 Button State Constant                         Description
 ``AUI_BUTTON_STATE_NORMAL``                   Normal button state
 ``AUI_BUTTON_STATE_HOVER``                    Hovered button state
 ``AUI_BUTTON_STATE_PRESSED``                  Pressed button state
 ``AUI_BUTTON_STATE_DISABLED``                 Disabled button state
 ``AUI_BUTTON_STATE_HIDDEN``                   Hidden button state
 ``AUI_BUTTON_STATE_CHECKED``                  Checked button state

Sets whether the toolbar item is sticky (permanent highlight after mouse enter)
or not.

:param bool `b`: ``True`` to set the item as sticky, ``False`` otherwise.

Associates some kind of user data to the toolbar item.

:param PyObject `data`: a Python object.

:note: The user data can be any Python object.

Assigns a window to the toolbar item.

:param wx.Window `w`: associate this window `w` to the :class:`AuiToolBarItem`.

Sets the clicking point.

:param wx.Point `p`: the location of the mouse click.

Sets whether the drop down menu has been clicked.

:param bool `c`: ``True`` to set the drop down as clicked, ``False`` otherwise.

Sets the :class:`AuiToolBarItem` rectangle.

:param wx.Rect `r`: the toolbar item rectangle.

Sets the :class:`AuiToolBarItem` identifier.

:param integer `id`: the toolbar item identifier.

Processes an event, searching event tables and calling zero or more suitable
event handler function(s).

:param `event`: the event to process.

:note: Normally, your application would not call this function: it is called
 in the wxPython implementation to dispatch incoming user interface events
 to the framework (and application).
 However, you might need to call it if implementing new functionality (such as
 a new control) where you define new event types, as opposed to allowing the
 user to override functions.

 An instance where you might actually override the :meth:`ProcessEvent` function is where
 you want to direct event processing to event handlers not normally noticed by
 wxPython. For example, in the document/view architecture, documents and views
 are potential event handlers. When an event reaches a frame, :meth:`ProcessEvent` will
 need to be called on the associated document and view in case event handler
 functions are associated with these objects.

 The normal order of event table searching is as follows:

 1. If the object is disabled (via a call to :meth:`~EvtHandler.SetEvtHandlerEnabled`) the function
    skips to step (6).
 2. If the object is a :class:`wx.Window`, :meth:`ProcessEvent` is recursively called on the window's
    :class:`wx.Validator`. If this returns ``True``, the function exits.
 3. wxWidgets `SearchEventTable` is called for this event handler. If this fails, the
    base class table is tried, and so on until no more tables exist or an appropriate
    function was found, in which case the function exits.
 4. The search is applied down the entire chain of event handlers (usually the chain
    has a length of one). If this succeeds, the function exits.
 5. If the object is a :class:`wx.Window` and the event is a :class:`CommandEvent`, :meth:`ProcessEvent` is
    recursively applied to the parent window's event handler. If this returns ``True``,
    the function exits.
 6. Finally, :meth:`ProcessEvent` is called on the :class:`App` object.

Instances of this class are used to bind specific events to event handlers.

`auibook.py` contains a notebook control which implements many features common in
applications with dockable panes. Specifically, :class:`AuiNotebook` implements functionality
which allows the user to rearrange tab order via drag-and-drop, split the tab window
into many different splitter configurations, and toggle through different themes to
customize the control's look and feel.

An effort has been made to try to maintain an API as similar to that of :class:`Notebook`.

The default theme that is used is :class:`~wx.lib.agw.aui.tabart.AuiDefaultTabArt`, which provides a modern, glossy
look and feel. The theme can be changed by calling :meth:`AuiNotebook.SetArtProvider() <AuiNotebook.SetArtProvider>`.

# Name:         auibook.py
# Purpose:
#
#
# Created:
# Version:

AuiNotebook is a notebook control which implements many features common in applications with dockable panes.
Specifically, AuiNotebook implements functionality which allows the user to rearrange tab
order via drag-and-drop, split the tab window into many different splitter configurations, and toggle
through different themes to customize the control's look and feel.

look and feel. The theme can be changed by calling :meth:`AuiNotebook.SetArtProvider`.

:param wx.Window `parent`: the :class:`AuiNotebook` parent;
:param integer `style`: the underlying :class:`Panel` window style;
:param integer `agwStyle`: the AGW-specific window style. This can be a combination of the following bits:

 ``AUI_NB_TOP``                       With this style, tabs are drawn along the top of the notebook
 ``AUI_NB_LEFT``                      With this style, tabs are drawn along the left of the notebook. Not implemented yet.
 ``AUI_NB_RIGHT``                     With this style, tabs are drawn along the right of the notebook. Not implemented yet.
 ``AUI_NB_BOTTOM``                    With this style, tabs are drawn along the bottom of the notebook
 ``AUI_NB_TAB_SPLIT``                 Allows the tab control to be split by dragging a tab
 ``AUI_NB_TAB_MOVE``                  Allows a tab to be moved horizontally by dragging
 ``AUI_NB_TAB_EXTERNAL_MOVE``         Allows a tab to be moved to another tab control
 ``AUI_NB_TAB_FIXED_WIDTH``           With this style, all tabs have the same width
 ``AUI_NB_SCROLL_BUTTONS``            With this style, left and right scroll buttons are displayed
 ``AUI_NB_WINDOWLIST_BUTTON``         With this style, a drop-down list of windows is available
 ``AUI_NB_CLOSE_BUTTON``              With this style, a close button is available on the tab bar
 ``AUI_NB_CLOSE_ON_ACTIVE_TAB``       With this style, a close button is available on the active tab
 ``AUI_NB_CLOSE_ON_ALL_TABS``         With this style, a close button is available on all tabs
 ``AUI_NB_MIDDLE_CLICK_CLOSE``        Allows to close :class:`AuiNotebook` tabs by mouse middle button click
 ``AUI_NB_SUB_NOTEBOOK``              This style is used by :class:`~wx.lib.agw.aui.framemanager.AuiManager` to create automatic AuiNotebooks
 ``AUI_NB_HIDE_ON_SINGLE_TAB``        Hides the tab window if only one tab is present
 ``AUI_NB_SMART_TABS``                Use Smart Tabbing, like ``Alt`` + ``Tab`` on Windows
 ``AUI_NB_USE_IMAGES_DROPDOWN``       Uses images on dropdown window list menu instead of check items
 ``AUI_NB_CLOSE_ON_TAB_LEFT``         Draws the tab close button on the left instead of on the right (a la Camino browser)
 ``AUI_NB_TAB_FLOAT``                 Allows the floating of single tabs. Known limitation: when the notebook is more or less full screen,
                                      tabs cannot be dragged far enough outside of the notebook to become floating pages
 ``AUI_NB_DRAW_DND_TAB``              Draws an image representation of a tab while dragging (on by default)
 ``AUI_NB_ORDER_BY_ACCESS``           Tab navigation order by last access time for the tabs
 ``AUI_NB_NO_TAB_FOCUS``              Don't draw tab focus rectangle

 Default value for `agwStyle` is:
 ``AUI_NB_DEFAULT_STYLE`` = ``AUI_NB_TOP`` | ``AUI_NB_TAB_SPLIT`` | ``AUI_NB_TAB_MOVE`` | ``AUI_NB_SCROLL_BUTTONS`` | ``AUI_NB_CLOSE_ON_ACTIVE_TAB`` | ``AUI_NB_MIDDLE_CLICK_CLOSE`` | ``AUI_NB_DRAW_DND_TAB``

:param string `name`: the window name.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=AUI_NB_DEFAULT_STYLE, name="AuiNotebook")

Adds a control inside a tab (not in the tab area).

:param integer `page_idx`: the page index;
:param wx.Window `control`: almost any :class:`wx.Window` -derived instance to be located
 inside a tab.

Adds a page. If the `select` parameter is ``True``, calling this will generate a
page change event.

:param wx.Window `page`: the page to be added;
:param string `caption`: specifies the text for the new page;
:param bool `select`: specifies whether the page should be selected;
:param wx.Bitmap `bitmap`: the bitmap to display in the enabled tab;
:param wx.Bitmap `disabled_bitmap`: the bitmap to display in the disabled tab;
 inside a tab;
:param string `tooltip`: the tooltip to display when the mouse hovers over the tab.

AddPage(self, page, caption, select=False, bitmap=wx.NullBitmap, disabled_bitmap=wx.NullBitmap, control=None, tooltip="")

Adds a button in the tab area.

:param integer `id`: the button identifier. This can be one of the following:

 ==============================  =================================
 Button Identifier               Description
 ``AUI_BUTTON_CLOSE``            Shows a close button on the tab area
 ``AUI_BUTTON_WINDOWLIST``       Shows a window list button on the tab area
 ``AUI_BUTTON_LEFT``             Shows a left button on the tab area
 ``AUI_BUTTON_RIGHT``            Shows a right button on the tab area

:param integer `location`: the button location. Can be ``wx.LEFT`` or ``wx.RIGHT``;
:param wx.Bitmap `normal_bitmap`: the bitmap for an enabled tab;
:param wx.Bitmap `disabled_bitmap`: the bitmap for a disabled tab;
:param string `name`: the button name.

AddTabAreaButton(self, id, location, normal_bitmap=wx.NullBitmap, disabled_bitmap=wx.NullBitmap, name="")

Cycles through the tabs.

:param bool `forward`: whether to advance forward or backward;
:param bool `wrap`: ``True`` to return to the first tab if we reach the last tab.

:note: The call to this function generates the page changing events.

Sets the image list for the :class:`AuiNotebook` control.

:param `imageList`: an instance of :class:`wx.ImageList`.

Clones the tab area buttons when the :class:`AuiNotebook` is being split.

:see: :meth:`AddTabAreaButton`

:note: Standard buttons for :class:`AuiNotebook` are not cloned, only custom ones.

Deletes a page at the given index. Calling this method will generate a page
change event.

:param integer `page_idx`: the page index to be deleted.

:note:

 :meth:`DeletePage` removes a tab from the multi-notebook, and destroys the window as well.

:see: :meth:`RemovePage`

Destroys the window safely.

Use this function instead of the ``del`` operator, since different window
classes can be destroyed differently. Frames and dialogs are not destroyed
immediately when this function is called -- they are added to a list of
windows to be deleted on idle time, when all the window's events have been
processed. This prevents problems with events being sent to non-existent windows.

:return: ``True`` if the window has either been successfully deleted, or
 it has been added to the list of windows pending real deletion.

.. note::

   This method has been added to safely un-initialize the underlying
   :class:`~wx.lib.agw.aui.framemanager.AuiManager` which manages the :class:`AuiNotebook`
   layout (i.e., tab split, re-ordering, tab floating etc...).

Starts the editing of an item label, sending a ``EVT_AUINOTEBOOK_BEGIN_LABEL_EDIT`` event.

:param integer `page_index`: the page index we want to edit.

Enables/disables a page in the notebook.

:param bool `enable`: ``True`` to enable the page, ``False`` to disable it.

Ensures the input page index `indx` is visible.

:param integer `indx`: the page index.

Finds the next active tab (used mainly when :class:`AuiNotebook` has inactive/disabled
tabs in it).

:param integer `idx`: the index of the first (most obvious) tab to check for active status;

Finds the tab control that currently contains the window as well
as the index of the window in the tab control. It returns ``True`` if the
window was found, otherwise ``False``.

:param `page`: an instance of :class:`AuiNotebookPage`.

Float the page in `page_index` by reparenting it to a floating frame.

:param integer `page_index`: the index of the page to be floated.

.. warning::

   When the notebook is more or less full screen, tabs cannot be dragged far
   enough outside of the notebook to become floating pages.

Returns the active tab control. It is called to determine which control
gets new windows being added.

Returns the AGW-specific style of the window.

:see: :meth:`SetAGWWindowStyleFlag` for a list of possible AGW-specific window styles.

Returns the associated :class:`~wx.lib.agw.aui.framemanager.AuiManager`. 

Returns the currently active page (not the index), or ``None`` if none was selected. 

Returns whether the page specified by the index `page_idx` is enabled.

:param integer `page_idx`: the page index.

Gets the height of the notebook for a given page height.

:param integer `pageHeight`: the given page height.

Returns whether the page specified by the index `page_idx` is hidden.

Returns the minimum and the maximum tab widths for :class:`AuiNotebook` when the
``AUI_NB_TAB_FIXED_WIDTH`` style is defined.

:note: Minimum and maximum tabs widths are used only when the ``AUI_NB_TAB_FIXED_WIDTH``
 style is present.

:see: :meth:`SetMinMaxTabWidth` for more information.

Returns the page specified by the given index.

Returns the tab bitmap for the page.

Returns the image index for the given page.

:param integer `page`: the given page for which to retrieve the image index.

Returns the page index for the specified window. If the window is not
found in the notebook, ``wx.NOT_FOUND`` is returned.

:param wx.Window `page_wnd`: the window we are looking for.

Returns the :class:`AuiNotebookPage` info structure specified by the given index.

Returns the tab label for the page.

Returns the tab text colour for the page.

Returns the tab tooltip for the page.

Returns whether a splitted :class:`AuiNotebook` can be unsplitted by double-clicking
on the splitter sash.

Returns the index of the currently active page, or -1 if none was selected. 

Returns the tab control at the specified point.

:param wx.Point `pt`: the mouse location.

Returns the tab frame associated with a tab control.

:param `tab_ctrl`: an instance of :class:`AuiTabCtrl`.

Returns the tab frame associated with a window.

:param wx.Window `wnd`: the window for which we want to locate the :class:`TabFrame`.

Returns whether a tab displays a close button or not.

:note: This can only be called if ``AUI_NB_CLOSE_ON_ALL_TABS`` is specified.

This method should be overridden to return ``True`` if this window has multiple pages. All
standard class with multiple pages such as :class:`Notebook`, :class:`Listbook` and :class:`Treebook`
already override it to return ``True`` and user-defined classes with similar behaviour
should do it as well to allow the library to handle such windows appropriately.

:note: Overridden from :class:`Panel`.

Hides all tabs on the :class:`AuiNotebook` control.

:param bool `hidden`: if ``True`` hides all tabs.

Sets whether a page is hidden.

:param bool `hidden`: ``True`` to hide the page, ``False`` to show it.

Contains common initialization code called by all constructors.

:param integer `agwStyle`: the notebook style.

:see: :meth:`~AuiNotebook.__init__` for a list of available `agwStyle` bits.

This is similar to :meth:`AddPage`, but allows the ability to specify the insert location.

:param integer `page_idx`: specifies the position for the new page;
 inside a ;

InsertPage(self, page_idx, page, caption, select=False, bitmap=wx.NullBitmap, disabled_bitmap=wx.NullBitmap, control=None, tooltip="")

Returns whether the mouse is well outside the :class:`AuiNotebook` screen rectangle. 

Returns whether a tab can be renamed or not.

:returns: ``True`` is a page can be renamed, ``False`` otherwise.

Loads a layout which was saved with :meth:`SavePerspective`.

:param string `layout`: a string which contains a saved :class:`AuiNotebook` layout.

Generates a preview of all the pages in the notebook (MSW and GTK only).

:param integer `thumbnail_size`: the maximum size of every page thumbnail
 (default=200 pixels).

:note: this functionality is currently unavailable on wxMAC.

Handles the ``wx.EVT_CHILD_FOCUS`` event for :class:`AuiNotebook`.

:param `event`: a :class:`ChildFocusEvent` event to be processed.

Handles the ``wx.EVT_CLOSE`` event for a floating page in :class:`AuiNotebook`.

:param `event`: a :class:`CloseEvent` event to be processed.

Handles the ``wx.EVT_NAVIGATION_KEY`` event for :class:`AuiNotebook`.

:param `event`: a :class:`NavigationKeyEvent` event to be processed.

Called by :class:`TabTextCtrl`, to accept the changes and to send the
``EVT_AUINOTEBOOK_END_LABEL_EDIT`` event.

:param integer `page_index`: the page index in the notebook;
:param string `value`: the new label for the tab.

Called by :class:`TabTextCtrl`, to cancel the changes and to send the

:param integer `page_index`: the page index in the notebook.

Handles the ``wx.EVT_SIZE`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_BEGIN_DRAG`` event for :class:`AuiNotebook`.

:param `event`: a :class:`AuiNotebookEvent` event to be processed.

Handles the ``EVT_AUINOTEBOOK_BG_DCLICK`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_BUTTON`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_CANCEL_DRAG`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_PAGE_CHANGING`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_TAB_DCLICK`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_DRAG_MOTION`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_END_DRAG`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_TAB_MIDDLE_DOWN`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_TAB_MIDDLE_UP`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_TAB_RIGHT_DOWN`` event for :class:`AuiNotebook`.

Handles the ``EVT_AUINOTEBOOK_TAB_RIGHT_UP`` event for :class:`AuiNotebook`.

Re-docks a floating :class:`AuiNotebook` tab in the original position, when possible.

:param `pane`: an instance of :class:`~wx.lib.agw.aui.framemanager.AuiPaneInfo`.

Removes a control from a tab (not from the tab area).

Removes a page, without deleting the window pointer.

:param integer `page_idx`: the page index to be removed.

:note:

 :meth:`RemovePage` removes a tab from the multi-notebook, but does not destroy the window.

:see: :meth:`DeletePage`

Removes a button from the tab area.

:param integer `id`: the button identifier.

:see: :meth:`AddTabAreaButton` for a list of button identifiers.

Reparents a control added inside a tab.

:param `dest_tabs`: the destination :class:`AuiTabCtrl`.

Called by :class:`TabTextCtrl` when it marks itself for deletion. 

Saves the entire user interface layout into an encoded string, which can then
be stored by the application (probably using :class:`Config <ConfigBase>`). When a perspective
is restored using :meth:`LoadPerspective`, the entire user interface will return
to the state it was when the perspective was saved.

:param integer `agwStyle`: the new window style. This can be a combination of the following bits:

.. todo:: Implementation of flags ``AUI_NB_RIGHT`` and ``AUI_NB_LEFT``.

Sets the art provider to be used by the notebook.

Sets whether a tab should display a close button or not.

:param bool `hasCloseButton`: ``True`` if the page displays a close button.

Sets the tab font.

:param wx.Font `font`: the new font to use to draw tab labels in their normal, un-selected state.

:param wx.ImageList `imageList`: the bitmap image list to associate to :class:`AuiNotebook`.

Sets the font for calculating text measurements.

:param wx.Font `font`: the new font to use to measure tab label text extents.

Sets the minimum and/or the maximum tab widths for :class:`AuiNotebook` when the

Pass -1 to either `minTabWidth` or `maxTabWidth` to reset to the default tab
width behaviour for :class:`AuiNotebook`.

:param integer `minTabWidth`: the minimum allowed tab width, in pixels;
:param integer `maxTabWidth`: the maximum allowed tab width, in pixels.

Sets the icon used by the :class:`TabNavigatorWindow`.

:param wx.Bitmap `bmp`: the new bitmap for the :class:`TabNavigatorWindow`.

Sets the normal font for drawing tab labels.

Sets the tab bitmap for the page.

:param wx.Bitmap `bitmap`: the bitmap to display on the page tab.

Sets the image index for the given page.

:param integer `page`: the page index;
:param integer `image`: an index into the image list which was set with :meth:`SetImageList`.

Sets the tab label for the page.

:param string `text`: the new tab label.

Sets the tab text colour for the page.

:param wx.Colour `colour`: the new tab label text colour.

Sets the tab tooltip for the page.

:param string `tooltip`: the new tooltip.

:returns: ``True`` if the page tooltip has been set, ``False`` otherwise
 (for example when the input `page_idx` is greater than the number of
 pages in the notebook.

Sets whether a tab can be renamed via a left double-click or not.

:param bool `renamable`: ``True`` if the page can be renamed.

Sets whether to unsplit a splitted :class:`AuiNotebook` when double-clicking on a sash.

:param bool `unsplit`: ``True`` to unsplit on sash double-clicking, ``False`` otherwise.

Sets the selected tab font for drawing tab labels.

:param wx.Font `font`: the new font to use to draw tab labels in their selected state.

Sets the page selection. Calling this method will generate a page change event.

:param integer `new_page`: the index of the new selection;
:param bool `force`: whether to force the selection or not.

Sets the selection based on the input page.

Sets the selection based on the input window `win`.

:param `win`: a :class:`wx.Window` derived window.

Sets the tab height.

By default, the tab control height is calculated by measuring the text
height and bitmap sizes on the tab captions.

Calling this method will override that calculation and set the tab control
to the specified height parameter. A call to this method will override
any call to :meth:`SetUniformBitmapSize`. Specifying -1 as the height will
return the control to its default auto-sizing behaviour.

:param integer `height`: the tab control area height.

Ensures that all tabs will have the same height, even if some tabs don't have bitmaps.
Passing ``wx.DefaultSize`` to this method will instruct the control to use dynamic tab
height, which is the default behaviour. Under the default behaviour, when a tab with a
large bitmap is added, the tab control's height will automatically increase to accommodate
the larger bitmap.

:param wx.Size `size`: the tab bitmap size.

Shows the window menu for the active tab control associated with this
notebook, and returns ``True`` if a selection was made.

Performs a split operation programmatically.

:param integer `page`: indicates the page that will be split off. This page will also become
 the active page after the split.
:param integer `direction`: specifies where the pane should go, it should be one of the
 following: ``wx.TOP``, ``wx.BOTTOM``, ``wx.LEFT``, or ``wx.RIGHT``.

Unsplit the :class:`AuiNotebook` on sash double-click.

:param `part`: an UI part representing the sash;
:param integer `sash_size`: the sash size;
:param wx.Point `pos`: the double-click mouse position.

   Due to a bug on MSW, for disabled pages :func:`FindWindowAtPoint`
   returns the wrong window. See http://trac.wxwidgets.org/ticket/2942

Updates the :class:`~wx.lib.agw.aui.framemanager.AuiManager` hint window size. 

:meth:`UpdateTabCtrlHeight` does the actual tab resizing. It's meant
to be used internally.

:param bool `force`: ``True`` to force the tab art to repaint.

A specialized command event class for events sent by :class:`AuiNotebook`. 

A simple class which holds information about tab captions, bitmaps and
colours.

Used internally, do not call it in your code!

AuiTabContainer is a class which contains information about each tab.
It also can render an entire tab control to a specified DC.
It's not a window class itself, because this code will be used by
the :class:`AuiNotebook`, where it is disadvantageous to have separate
windows for each tab control in the case of "docked tabs".

A derived class, :class:`AuiTabCtrl`, is an actual :class:`wx.Window` - derived window
which can be used as a tab control in the normal sense.

:param `auiNotebook`: the parent :class:`AuiNotebook` window.

AddButton(self, id, location, normal_bitmap=wx.NullBitmap, disabled_bitmap=wx.NullBitmap, name="")

Adds a page to the tab control.

:param wx.Window `page`: the window associated with this tab;
:param `info`: an instance of :class:`AuiNotebookPage`.

Tests if a button was hit.

:param integer `x`: the mouse `x` position;
:param integer `y`: the mouse `y` position;
:param integer `state_flags`: the current button state (hidden, disabled, etc...).

:returns: and instance of :class:`AuiTabContainerButton` if a button was hit, ``None`` otherwise.

ButtonHitTest(self, x, y, state_flags=AUI_BUTTON_STATE_HIDDEN|AUI_BUTTON_STATE_DISABLED)

:see: :meth:`AddButton`

This function shows the active window, then hides all of the other windows
(in that order).

Enables/disables a tab in the :class:`AuiTabContainer`.

:param integer `idx`: the tab index;
:param bool `enable`: ``True`` to enable a tab, ``False`` to disable it.

Finds the next active tab in the :class:`AuiTabContainer`.

Returns the current selected tab or ``wx.NOT_FOUND`` if none is selected. 

Returns the tab art flags.

.. seealso:: :meth:`SetAGWFlags` for a list of possible return values.

Returns whether a tab is enabled or not.

:param integer `idx`: the tab index.

Returns whether a tab is hidden or not.

Returns the tab index based on the window `wnd` associated with it.

:param `wnd`: an instance of :class:`wx.Window`.

Returns a list of all the pages in this :class:`AuiTabContainer`. 

Returns the number of pages shown in the :class:`AuiTabContainer`. 

Returns the window associated with the tab with index `idx`.

hides/shows a tab in the :class:`AuiTabContainer`.

:param bool `hidden`: ``True`` to hide a tab, ``False`` to show it.

Inserts a page in the tab control in the position specified by `idx`.

:param `info`: an instance of :class:`AuiNotebookPage`;
:param integer `idx`: the page insertion index.

Returns whether a tab is visible or not.

:param integer `tabPage`: the tab index;
:param integer `tabOffset`: the tab offset;
:param `wnd`: an instance of :class:`wx.Window` derived window.

Make the tab visible if it wasn't already.

:param `win`: an instance of :class:`wx.Window` derived window.

Moves a page in a new position specified by `new_idx`.

:param integer `new_idx`: the new page position.

:param integer `id`: the button identifier. See :meth:`AddButton` for a list of button identifiers.

Removes a page from the tab control.

:param `wnd`: an instance of :class:`wx.Window`, a window associated with this tab.

Renders the tab catalog to the specified :class:`wx.DC`.

It is a virtual function and can be overridden to provide custom drawing
capabilities.

:param `raw_dc`: a :class:`wx.DC` device context;

Sets the :class:`AuiNotebook` active page.

:param `wndOrInt`: an instance of :class:`wx.Window` or an integer specifying a tab index.

Sets the tab art flags.

 ``AUI_NB_LEFT``                      With this style, tabs are drawn along the left of the notebook. Not implemented yet
 ``AUI_NB_RIGHT``                     With this style, tabs are drawn along the right of the notebook. Not implemented yet

Instructs :class:`AuiTabContainer` to use art provider specified by parameter `art`

:note: The previous art provider object, if any, will be deleted by :class:`AuiTabContainer`.

Sets the tab area rectangle.

:param wx.Rect `rect`: the available area for :class:`AuiTabContainer`.

TabHitTest() tests if a tab was hit, passing the window pointer
back if that condition was fulfilled.

:param integer `y`: the mouse `y` position.

A simple class which holds information about tab buttons and their state.

This is an actual :class:`wx.Window` - derived window which can be used as a tab control in the normal sense.

:param `parent`: the :class:`AuiNotebook` parent;
:param integer `style`: the window style.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER|wx.WANTS_CHARS|wx.TAB_TRAVERSAL)

Returns the page at which the mouse is pointing (if any).

:rtype: :class:`wx.Window`.

Returns whether the user is dragging a tab with the mouse or not. 

Handles the ``EVT_AUINOTEBOOK_BUTTON`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_MOUSE_CAPTURE_LOST`` event for :class:`AuiTabCtrl`.

:param `event`: a :class:`MouseCaptureLostEvent` event to be processed.

Handles the ``wx.EVT_ENTER_WINDOW`` event fof :class:`AuiTabCtrl`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`AuiTabCtrl`.

:param `event`: a :class:`KeyEvent` event to be processed.

.. deprecated:: 0.6
   This implementation is now deprecated. Refer to :meth:`OnKeyDown` for the correct one.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`AuiTabCtrl`.

:param `event`: a :class:`FocusEvent` event to be processed.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_MIDDLE_UP`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_MOTION`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_RIGHT_UP`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`AuiTabCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`AuiTabCtrl`.

Starts a timer: when it fires, a tooltip will be shown on the notebook tab
the mouse is pointing at.

:param wx.Window `wnd`: the window pointed by the mouse.

Stops the timer keeping track of tooltips and mouse movements on the tab area. 

A specialized command event class for events sent by :class:`AuiNotebook` . 

Returns whether the event was dispatched (used for automatic :class:`AuiNotebook` ). 

Returns the label-itemtext (for ``EVT_AUINOTEBOOK_BEGIN`` | ``END_LABEL_EDIT`` only).

Returns the page that was selected before the change, or -1 if none was
selected.

Returns the currently selected page, or -1 if none was selected. 

Returns the edit cancel flag (for ``EVT_AUINOTEBOOK_BEGIN`` | ``END_LABEL_EDIT`` only).

Sets the event as dispatched (used for automatic :class:`AuiNotebook` ).

:param `b`: whether the event was dispatched or not.

Sets the edit cancel flag (for ``EVT_AUINOTEBOOK_BEGIN`` | ``END_LABEL_EDIT`` only).

:param bool `editCancelled`: whether the editing action has been cancelled or not.

Sets the label. Useful only for ``EVT_AUINOTEBOOK_END_LABEL_EDIT``.

:param string `label`: the new label.

Sets the id of the page selected before the change.

:param integer `s`: the old selection.

Sets the selection member variable.

:param integer `s`: the new selection.

The ExpandoTextCtrl is a multi-line wx.TextCtrl that will
adjust its height on the fly as needed to accommodate the number of
lines needed to display the current content of the control.  It is
assumed that the width of the control will be a fixed value and
that only the height will be adjusted automatically.  If the
control is used in a sizer then the width should be set as part of
the initial or min size of the control.

When the control resizes itself it will attempt to also make
necessary adjustments in the sizer hierarchy it is a member of (if
any) but if that is not suffiecient then the programmer can catch
the EVT_ETC_LAYOUT_NEEDED event in the container and make any
other layout adjustments that may be needed.

:param `parent`: parent window, must not be ``None``;
:param integer `id`: window identifier. A value of -1 indicates a default value;
:param string `value`: the control text label;
:param `pos`: the control position. A value of (-1, -1) indicates a default position,
:param `size`: the control size. A value of (-1, -1) indicates a default size,
:param integer `style`: the underlying :class:`wx.Control` style;
:param wx.Validator `validator`: the window validator;
:param string `name`: the widget name.

:type parent: :class:`wx.Window`
:type pos: tuple or :class:`wx.Point`
:type size: tuple or :class:`wx.Size`

__init__(self, parent, id=-1, value="", pos=wx.DefaultPosition,  size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="expando")

Appends the text to the end of the text control.

:param string `text`: text to write to the text control.

.. seealso:: :meth:`WriteText`

Returns the maximum height that the control will expand to on its own.

:rtype: int

GetNumberOfLines() -> int

Returns the number of lines in the text control buffer.

Handles the ``wx.EVT_SIZE`` event for :class:`ExpandoTextCtrl`.

Handles the ``wx.EVT_TEXT`` event for :class:`ExpandoTextCtrl`.

:param `event`: a :class:`CommandEvent` event to be processed.

Sets the font for the :class:`ExpandoTextCtrl`.

:param wx.Font font: font to associate with the :class:`ExpandoTextCtrl`, pass
 ``NullFont`` to reset to the default font.

:rtype: bool
:returns: ``True`` if the font was really changed, ``False`` if it was already
 set to this font and nothing was done.

Sets the maximum height that the control will expand to on its
own, and adjusts it down if needed.

:param integer `h`: the maximum control height, in pixels.

Writes the text into the text control at the current insertion position.

.. note::

   Newlines in the text string are the only control characters allowed, and they
   will cause appropriate line breaks. See :meth:`AppendText` for more convenient
   ways of writing to the window. After the write operation, the insertion point
   will be at the end of the inserted text, so subsequent write operations will
   be appended. To append text after the user may have interacted with the control,
   call :meth:`TextCtrl.SetInsertionPointEnd` before writing.

TabFrame is an interesting case. It's important that all child pages
of the multi-notebook control are all actually children of that control
(and not grandchildren). TabFrame facilitates this. There is one
instance of TabFrame for each tab control inside the multi-notebook.

It's important to know that TabFrame is not a real window, but it merely
used to capture the dimensions/positioning of the internal tab control and
it's managed page windows.

Returns the window client size.

Returns the window size.

Sets the position and size of the window in pixels. The `flags`

:param integer `flags`: may have one of this bit set:

                                      parameters of this function, nothing is done. but with this flag a window resize
                                      may be forced even in this case (supported in wx 2.6.2 and later and only implemented

Sets the tab control height.

:param integer `h`: the tab area height.

Shows/hides the window.

:param bool `show`: ``True`` to show the window, ``False`` otherwise.

:note:

 Overridden from :class:`wx.Control`, this method always returns ``False`` as
 :class:`TabFrame` should never be phisically shown on screen.

Calling this method immediately repaints the invalidated area of the window
and all of its children recursively while this would usually only happen when
the flow of control returns to the event loop.

:note: Notice that this function doesn't invalidate any area of the window so
 nothing happens if nothing has been invalidated (i.e. marked as requiring a redraw).
 Use `Refresh` first if you want to immediately redraw the window unconditionally.

Data storage class for managing and providing access to :class:`TabNavigatorWindow` properties.

Sets/Gets the font for the L{TabNavigatorWindow}, an instance of :class:`wx.Font`.

Sets/Gets the icon for the L{TabNavigatorWindow}, an instance of :class:`wx.Bitmap`.

Sets/Gets the minimum size for the L{TabNavigatorWindow}, an instance of :class:`wx.Size`.

This class is used to create a modal dialog that enables "Smart Tabbing",
similar to what you would get by hitting ``Alt`` + ``Tab`` on Windows.

Default class constructor. Used internally.

:param `parent`: the :class:`TabNavigatorWindow` parent;
:param `props`: the :class:`TabNavigatorProps` object.
:param `centreOnMouse`: popup position of the dialog at mouse cursor. Defaults to Centre.

Closes the :class:`TabNavigatorWindow` dialog, setting selection in :class:`AuiNotebook`. 

Gets the page index that was selected when the dialog was closed. 

Handles the ``wx.EVT_LISTBOX_DCLICK`` event for the :class:`ListBox` inside :class:`TabNavigatorWindow`.

:param `event`: a :class:`ListEvent` event to be processed.

Handles the ``wx.EVT_KEY_UP`` for the :class:`TabNavigatorWindow`.

Handles the ``wx.EVT_LEFT_DOWN`` event for self._panel.

Handles the ``wx.EVT_LEFT_UP`` event for self._panel.

Handles the ``wx.EVT_MOTION`` event for self._panel.

Handles the ``wx.EVT_NAVIGATION_KEY`` for the :class:`TabNavigatorWindow`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`TabNavigatorWindow` top panel.

Handles the ``wx.EVT_PAINT`` event for :class:`TabNavigatorWindow` top panel.

Populates the :class:`TabNavigatorWindow` listbox with a list of tabs.

:param `book`: the actual :class:`AuiNotebook`.

:param `owner`: the :class:`AuiNotebook` owning the tab;
:param `tab`: the actual :class:`AuiTabCtrl` tab;
:param integer `page_index`: the :class:`AuiTabContainer` page index for the tab.

Handles the ``wx.EVT_CHAR`` event for :class:`TabTextCtrl`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`TabTextCtrl`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`TabTextCtrl`.

Dock art provider code - a dock provider provides all drawing functionality to
the AUI dock manager. This allows the dock manager to have a pluggable look-and-feel.

By default, a :class:`~wx.lib.agw.aui.framemanager` uses an instance of this class called :mod:`~wx.lib.agw.aui.dockart`
completely new dock art class. Call :meth:`AuiManager.SetArtProvider() <lib.agw.aui.framemanager.AuiManager.SetArtProvider>`
to make use this new dock art.

# Name:         dockart.py
# Purpose:
#
#
# Created:
# Version:

Dock art provider code - a dock provider provides all drawing functionality to the AUI dock manager.
This allows the dock manager to have a pluggable look-and-feel.

By default, a :class:`~wx.lib.agw.aui.framemanager.AuiManager` uses an instance of this class called
:class:`AuiDefaultDockArt` which provides bitmap art and a colour scheme that is adapted to the major
platforms' look. You can either derive from that class to alter its behaviour or
write a completely new dock art class.

Call :meth:`AuiManager.SetArtProvider() <lib.agw.aui.framemanager.AuiManager.SetArtProvider>`

**Metric Ordinals**

These are the possible pane dock art settings for :class:`AuiDefaultDockArt`:

================================================  ======================================
Metric Ordinal Constant                           Description
``AUI_DOCKART_SASH_SIZE``                         Customizes the sash size
``AUI_DOCKART_CAPTION_SIZE``                      Customizes the caption size
``AUI_DOCKART_GRIPPER_SIZE``                      Customizes the gripper size
``AUI_DOCKART_PANE_BORDER_SIZE``                  Customizes the pane border size
``AUI_DOCKART_PANE_BUTTON_SIZE``                  Customizes the pane button size
``AUI_DOCKART_BACKGROUND_COLOUR``                 Customizes the background colour
``AUI_DOCKART_BACKGROUND_GRADIENT_COLOUR``        Customizes the background gradient colour
``AUI_DOCKART_SASH_COLOUR``                       Customizes the sash colour
``AUI_DOCKART_ACTIVE_CAPTION_COLOUR``             Customizes the active caption colour
``AUI_DOCKART_ACTIVE_CAPTION_GRADIENT_COLOUR``    Customizes the active caption gradient colour
``AUI_DOCKART_INACTIVE_CAPTION_COLOUR``           Customizes the inactive caption colour
``AUI_DOCKART_INACTIVE_CAPTION_GRADIENT_COLOUR``  Customizes the inactive gradient caption colour
``AUI_DOCKART_ACTIVE_CAPTION_TEXT_COLOUR``        Customizes the active caption text colour
``AUI_DOCKART_INACTIVE_CAPTION_TEXT_COLOUR``      Customizes the inactive caption text colour
``AUI_DOCKART_BORDER_COLOUR``                     Customizes the border colour
``AUI_DOCKART_GRIPPER_COLOUR``                    Customizes the gripper colour
``AUI_DOCKART_CAPTION_FONT``                      Customizes the caption font
``AUI_DOCKART_GRADIENT_TYPE``                     Customizes the gradient type (no gradient, vertical or horizontal)
``AUI_DOCKART_DRAW_SASH_GRIP``                    Draw a sash grip on the sash
``AUI_DOCKART_HINT_WINDOW_COLOUR``                Customizes the hint window background colour (currently light blue)
``AUI_DOCKART_HINT_WINDOW_BORDER_COLOUR``         Customizes the hint window border background colour (currently grey)

**Gradient Types**

These are the possible gradient dock art settings for :class:`AuiDefaultDockArt`:

============================================  ======================================
Gradient Constant                             Description
``AUI_GRADIENT_NONE``                         No gradient on the captions
``AUI_GRADIENT_VERTICAL``                     Vertical gradient on the captions
``AUI_GRADIENT_HORIZONTAL``                   Horizontal gradient on the captions

**Button States**

These are the possible pane button / :class:`~wx.lib.agw.aui.auibook.AuiNotebook` button /
:class:`~wx.lib.agw.aui.auibar.AuiToolBar` button states:

Button State Constant                         Description
``AUI_BUTTON_STATE_NORMAL``                   Normal button state
``AUI_BUTTON_STATE_HOVER``                    Hovered button state
``AUI_BUTTON_STATE_PRESSED``                  Pressed button state
``AUI_BUTTON_STATE_DISABLED``                 Disabled button state
``AUI_BUTTON_STATE_HIDDEN``                   Hidden button state
``AUI_BUTTON_STATE_CHECKED``                  Checked button state

**Button Identifiers**

:class:`~wx.lib.agw.aui.auibar.AuiToolBar` button identifiers:

Button Identifier                             Description
``AUI_BUTTON_CLOSE``                          Shows a close button on the pane
``AUI_BUTTON_MAXIMIZE_RESTORE``               Shows a maximize/restore button on the pane
``AUI_BUTTON_MINIMIZE``                       Shows a minimize button on the pane
``AUI_BUTTON_PIN``                            Shows a pin button on the pane
``AUI_BUTTON_OPTIONS``                        Shows an option button on the pane (not implemented)
``AUI_BUTTON_WINDOWLIST``                     Shows a window list button on the pane (for :class:`~wx.lib.agw.aui.auibook.AuiNotebook`)
``AUI_BUTTON_LEFT``                           Shows a left button on the pane (for :class:`~wx.lib.agw.aui.auibook.AuiNotebook`)
``AUI_BUTTON_RIGHT``                          Shows a right button on the pane (for :class:`~wx.lib.agw.aui.auibook.AuiNotebook`)
``AUI_BUTTON_UP``                             Shows an up button on the pane (not implemented)
``AUI_BUTTON_DOWN``                           Shows a down button on the pane (not implemented)
``AUI_BUTTON_CUSTOM1``                        Shows a custom button on the pane (not implemented)
``AUI_BUTTON_CUSTOM2``                        Shows a custom button on the pane (not implemented)
``AUI_BUTTON_CUSTOM3``                        Shows a custom button on the pane (not implemented)

Draws a background.

:param `window`: an instance of :class:`wx.Window`;
:param integer `orient`: the gradient (if any) orientation;
:param wx.Rect `rect`: the background rectangle.

Draws the pane border.

:param wx.Rect `rect`: the border rectangle;
:param `pane`: the pane for which the border is drawn.

Draws the text in the pane caption.

:param string `text`: the text to be displayed;
:param wx.Rect `rect`: the pane caption rectangle;
:param `pane`: the pane for which the text is drawn.

Draws the text caption background in the pane.

:param wx.Rect `rect`: the text caption rectangle;
:param `pane`: the pane for which the text background is drawn.

Draws a gripper on the pane.

:param `pane`: the pane for which the gripper is drawn.

Draws the icon in the pane caption area.

:param `pane`: the pane for which the icon is drawn.

Draws a pane button in the pane caption area.

:param integer `button`: the button to be drawn;
:param integer `button_state`: the pane button state;
:param wx.Rect `_rect`: the pane caption rectangle;
:param `pane`: the pane for which the button is drawn.

DrawPaneButton(self, dc, window, button, button_state, _rect, pane)

Draws a sash between two windows.

:param integer `orient`: the sash orientation;
:param wx.Rect `rect`: the sash rectangle.

Draws a sash gripper on a sash between two windows.

Gets the colour of a certain setting.

:param integer `id`: can be one of the colour values in `Metric Ordinals`.

Gets a font setting.

:param integer `id`: must be ``AUI_DOCKART_CAPTION_FONT``, otherwise :class:`NullFont` is returned.

Gets the value of a certain setting.

:param integer `id`: can be one of the size values in `Metric Ordinals`.

Requests the user attention by intermittently highlighting the pane caption.

:param `pane`: the pane for which we want to attract the user attention.

Sets the colour of a certain setting.

:param integer `id`: can be one of the colour values in `Metric Ordinals`;
:param `colour`: the new value of the setting.
:type `colour`: :class:`wx.Colour` or tuple or integer

Sets a custom button bitmap for the pane button.

:param wx.Bitmap `bmp`: the actual bitmap to set;
:param integer `button`: the button identifier;
:param bool `active`: whether it is the bitmap for the active button or not;
:param bool `maximize`: used to distinguish between the maximize and restore bitmaps.

Assigns the default pane bitmaps.

:param bool `isMac`: whether we are on wxMAC or not.

Sets a font setting.

:param integer `id`: must be ``AUI_DOCKART_CAPTION_FONT``;
:param `font`: an instance of :class:`wx.Font`.

Sets the value of a certain setting using `new_val`

:param integer `id`: can be one of the size values in `Metric Ordinals`;
:param `new_val`: the new value of the setting.

ModernDockArt is a custom `AuiDockArt` class, that implements a look similar to Firefox and other recents applications.

Is uses the `winxptheme <https://sourceforge.net/projects/pywin32/>`_ module and
XP themes whenever possible, so it should look good even if the user has a custom theme.

:note: This dock art is Windows only and will only work if you have installed
 Mark Hammond's `pywin32` module (https://sourceforge.net/projects/pywin32/).

:param wx.Window `win`: the window managed by :class:`~wx.lib.agw.aui.framemanager.AuiManager`.

:param `pane`: the pane for which we are drawing the caption background.

DrawPaneButton(self, dc, window, button, button_state, rect, pane)

bool(x) -> bool

Returns True when the argument x is true, False otherwise.
The builtins True and False are the only two instances of the class bool.
The class bool is a subclass of the class int, and cannot be subclassed.

`framemanager.py` is the central module of the AUI class framework.

:class:`AuiManager` manages the panes associated with it for a particular :class:`wx.Frame`, using
a pane's :class:`AuiPaneInfo` information to determine each pane's docking and floating
behavior. AuiManager uses wxPython' sizer mechanism to plan the layout of each frame.
It uses a replaceable dock art class to do all drawing, so all drawing is localized
in one area, and may be customized depending on an application's specific needs.

AuiManager works as follows: the programmer adds panes to the class, or makes
changes to existing pane properties (dock position, floating state, show state, etc...).
To apply these changes, AuiManager's :meth:`AuiManager.Update() <AuiManager.Update>` function is called. This batch
processing can be used to avoid flicker, by modifying more than one pane at a time,
and then "committing" all of the changes at once by calling `Update()`.

Panes can be added quite easily::

    text1 = wx.TextCtrl(self, -1)
    text2 = wx.TextCtrl(self, -1)
    self._mgr.AddPane(text1, AuiPaneInfo().Left().Caption("Pane Number One"))
    self._mgr.AddPane(text2, AuiPaneInfo().Bottom().Caption("Pane Number Two"))

    self._mgr.Update()

Later on, the positions can be modified easily. The following will float an
existing pane in a tool window::

    self._mgr.GetPane(text1).Float()

Layers, Rows and Directions, Positions
======================================

Inside AUI, the docking layout is figured out by checking several pane parameters.
Four of these are important for determining where a pane will end up.

**Direction** - Each docked pane has a direction, `Top`, `Bottom`, `Left`, `Right`, or `Center`.
This is fairly self-explanatory. The pane will be placed in the location specified
by this variable.

**Position** - More than one pane can be placed inside of a "dock". Imagine two panes
being docked on the left side of a window. One pane can be placed over another.
In proportionally managed docks, the pane position indicates it's sequential position,
starting with zero. So, in our scenario with two panes docked on the left side, the
top pane in the dock would have position 0, and the second one would occupy position 1.

**Row** - A row can allow for two docks to be placed next to each other. One of the most
common places for this to happen is in the toolbar. Multiple toolbar rows are allowed,
the first row being in row 0, and the second in row 1. Rows can also be used on
vertically docked panes.

**Layer** - A layer is akin to an onion. Layer 0 is the very center of the managed pane.
Thus, if a pane is in layer 0, it will be closest to the center window (also sometimes
known as the "content window"). Increasing layers "swallow up" all layers of a lower
value. This can look very similar to multiple rows, but is different because all panes
in a lower level yield to panes in higher levels. The best way to understand layers
is by running the AUI sample (`AUI.py`).

# --------------------------------------------------------------------------- #
# AUI Library wxPython IMPLEMENTATION
#
# Original C++ Code From Kirix (wxAUI). You Can Find It At:
#
#    License: wxWidgets license
#
# http:#www.kirix.com/en/community/opensource/wxaui/about_wxaui.html
#
# Current wxAUI Version Tracked: wxWidgets 2.9.4 SVN HEAD
#
#
# Python Code By:
#
# Andrea Gavana, @ 23 Dec 2005
# Latest Revision: 17 Feb 2013, 21.00 GMT
#
# For All Kind Of Problems, Requests Of Enhancements And Bug Reports, Please
# Write To Me At:
#
# andrea.gavana@gmail.com
# andrea.gavana@maerskoil.com
#
# Or, Obviously, To The wxPython Mailing List!!!
#
# Tags:        phoenix-port, unittest, documented, py3-port
#
# End Of Comments

A docking guide window for multiple docking hint (diamond-shaped HUD). 

:param `parent`: the :class:`AuiManager` parent.

Moves the docking guide window to the new position.

:param wx.Point `pos`: the new docking guide position.

Creates the docking guide window shape based on which docking bitmaps are used. 

Checks if the mouse position is inside the target windows rect.

:param integer `x`: the `x` mouse position;
:param integer `y`: the `y` mouse position.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`AuiCenterDockingGuide`.

:param `event`: :class:`EraseEvent` to be processed.

:note: This is intentionally empty to reduce flickering while drawing.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiCenterDockingGuide`.

:param `event`: a :class:`PaintEvent` to be processed.

Sets the correct shape for the docking guide window.

:param `event`: on wxGTK, a :class:`wx.WindowCreateEvent` event to process.

Updates the docking guides images depending on the mouse position, using focused
images if the mouse is inside the docking guide or unfocused images if it is
outside.

:param wx.Point `pos`: the mouse position.

Sets whether a pane can be docked on top of another to create an automatic
:class:`~wx.lib.agw.aui.auibook.AuiNotebook`.

:param bool `valid`: whether a pane can be docked on top to another to form an automatic
 :class:`~wx.lib.agw.aui.auibook.AuiNotebook`.

Returns whether a dock is valid or not.

In order to be valid, a dock needs to have a non-zero `dock_direction`.

Base class for :class:`AuiSingleDockingGuide` and :class:`AuiCenterDockingGuide`.

Default class constructor. Used internally, do not call it in your code!

:param `parent`: the :class:`AuiManager` parent;
:param integer `id`: the window identifier. It may take a value of -1 to indicate a default value.
:param string `title`: the caption to be displayed on the frame's title bar.
:param wx.Point `pos`: the window position. A value of (-1, -1) indicates a default position,
 chosen by either the windowing system or wxPython, depending on platform.
:param wx.Size `size`: the window size. A value of (-1, -1) indicates a default size, chosen by
 either the windowing system or wxPython, depending on platform.
:param string `name`: the name of the window. This parameter is used to associate a name with the
 item, allowing the application user to set Motif resource values for individual windows.

wx.FRAME_TOOL_WINDOW | wx.STAY_ON_TOP | wx.FRAME_NO_TASKBAR | wx.NO_BORDER

__init__(self, parent, id=wx.ID_ANY, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.FRAME_TOOL_WINDOW | wx.STAY_ON_TOP | wx.FRAME_NO_TASKBAR | wx.NO_BORDER, name="AuiDockingGuide")

To be overridden by parent classes.

A class which holds information about VS2005 docking guide windows. 

:param `other`: another instance of :class:`AuiDockingGuideInfo`.

Assigns the properties of the `other` :class:`AuiDockingGuideInfo` to `self`.

Hosts a docking guide window.

:param `h`: an instance of :class:`AuiDockingGuideWindow` or :class:`AuiDockingHintWindow`.

Target class for :class:`AuiDockingGuide` and :class:`AuiCenterDockingGuide`. 

:param wx.Rect `rect`: the window rect;
:param integer `direction`: one of ``wx.TOP``, ``wx.BOTTOM``, ``wx.LEFT``, ``wx.RIGHT``,
 ``wx.CENTER``;
:param bool `center`: whether the calling class is a :class:`AuiCenterDockingGuide`;
:param bool `useAero`: whether to use the new Aero-style bitmaps or Whidbey-style bitmaps
 for the docking guide.

__init__(self, parent, rect, direction=0, center=False, useAero=False)

Draws the whole docking guide window (not used if the docking guide images are ok).

:param `dc`: a :class:`wx.DC` device context object.

Draws the docking guide arrow icon (not used if the docking guide images are ok).

Draws the docking guide background.

Draws a dotted line (not used if the docking guide images are ok).

:param `dc`: a :class:`wx.DC` device context object;
:param `point`: a :class:`wx.Point` where to start drawing the dotted line;
:param integer `length`: the length of the dotted line;
:param bool `vertical`: whether it is a vertical docking guide window or not.

Draws the docking guide icon (not used if the docking guide images are ok).

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`AuiDockingGuideWindow`.

:param `event`: a :class:`EraseEvent` to be processed.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiDockingGuideWindow`.

Sets the docking direction as valid or invalid.

:param bool `valid`: whether the docking direction is allowed or not.

Updates the docking guide images depending on the mouse position, using focused
outside.

:param `pos`: a :class:`wx.Point` mouse position.

:param string `title`: the caption to be displayed on the frame's title bar;
 either the windowing system or wxPython, depending on platform;
:param integer `style`: the window style;

wx.FRAME_TOOL_WINDOW | wx.FRAME_FLOAT_ON_PARENT | wx.FRAME_NO_TASKBAR | wx.NO_BORDER | wx.FRAME_SHAPED

__init__(self, parent, id=wx.ID_ANY, title="", pos=wx.DefaultPosition, size=wx.Size(1, 1), style=wx.FRAME_TOOL_WINDOW | wx.FRAME_FLOAT_ON_PARENT | wx.FRAME_NO_TASKBAR | wx.NO_BORDER | wx.FRAME_SHAPED, name="auiHintWindow")

Creates the "venetian blind" effect if :class:`AuiManager` has the ``AUI_MGR_VENETIAN_BLINDS_HINT``
flag set.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiDockingHintWindow`.

:param `event`: an instance of :class:`PaintEvent` to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`AuiDockingHintWindow`.

:param `event`: a :class:`wx.SizeEvent` to be processed.

Sets whether venetian blinds or transparent hints will be shown as docking hint.
This depends on the :class:`AuiManager` flags.

:param integer `agwFlags`: the :class:`AuiManager` flags.

If the platform supports it, sets the shape of the window to that depicted by `region`.
The system will not display or respond to any mouse event for the pixels that lie
outside of the region. To reset the window to the normal rectangular shape simply call
:meth:`SetShape` again with an empty region.

:param Region `region`: the shape of the frame.

:note: Overridden for wxMAC.

Show the hint window.

:param bool `show`: whether to show or hide the hint docking window.

:param `owner_mgr`: the :class:`AuiManager` that manages the floating pane;
:param `pane`: the :class:`AuiPaneInfo` pane that is about to float;

wx.FRAME_TOOL_WINDOW | wx.FRAME_FLOAT_ON_PARENT | wx.FRAME_NO_TASKBAR | wx.CLIP_CHILDREN

__init__(self, parent, owner_mgr, pane=None, id=wx.ID_ANY, title="", style=wx.FRAME_TOOL_WINDOW | wx.FRAME_FLOAT_ON_PARENT | wx.FRAME_NO_TASKBAR | wx.CLIP_CHILDREN)

Copies all the attributes of the input `pane` into another :class:`AuiPaneInfo`.

:param `pane`: the source :class:`AuiPaneInfo` from where to copy attributes.

Handles the ``wx.EVT_ACTIVATE`` event for :class:`AuiFloatingFrame`.

:param `event`: a :class:`ActivateEvent` to be processed.

Handles the ``wx.EVT_TIMER`` event for :class:`AuiFloatingFrame`.

:param `event`: a :class:`TimerEvent` to be processed.

:note: This is used solely for "fly-out" panes.

Handles the ``wx.EVT_CLOSE`` event for :class:`AuiFloatingFrame`.

:param `event`: a :class:`CloseEvent` to be processed.

Handles the ``EVT_AUI_FIND_MANAGER`` event for :class:`AuiFloatingFrame`.

:param `event`: a :class:`AuiManagerEvent` event to be processed.

Handles the ``wx.EVT_IDLE`` event for :class:`AuiFloatingFrame`.

.. note::

   This event is only processed on wxMAC if :class:`AuiManager` is using the
   ``AUI_MGR_USE_NATIVE_MINIFRAMES`` style.

Handles the ``wx.EVT_MOVE`` event for :class:`AuiFloatingFrame`.

:param `event`: a :class:`MoveEvent` to be processed.

.. note::

   This event is not processed on wxMAC or if :class:`AuiManager` is not using the

Handles the ``wx.EVT_MOVE`` and ``wx.EVT_MOVING`` events for :class:`AuiFloatingFrame`.

.. note::

   This event is only processed on wxMAC or if :class:`AuiManager` is using the

The user has just finished moving the floating pane.

.. note::

   This method is used only on wxMAC if :class:`AuiManager` is using the

The user has just started moving the floating pane.

:param `event`: an instance of :class:`MouseEvent`.

.. note::

The user is moving the floating pane.

:param wx.Rect `rect`: the pane client rectangle;
:param integer `direction`: the direction in which the pane is moving, can be one of
 ``wx.NORTH``, ``wx.SOUTH``, ``wx.EAST`` or ``wx.WEST``.

.. note::

Handles the ``wx.EVT_SIZE`` event for :class:`AuiFloatingFrame`.

Sets all the properties of a pane.

:param `pane`: the :class:`AuiPaneInfo` to analyze.

AuiManager manages the panes associated with it for a particular :class:`wx.Frame`,
using a pane's :class:`AuiManager` information to determine each pane's docking and
floating behavior. :class:`AuiManager` uses wxPython's sizer mechanism to plan the
layout of each frame. It uses a replaceable dock art class to do all drawing,
so all drawing is localized in one area, and may be customized depending on an
applications' specific needs.

:class:`AuiManager` works as follows: the programmer adds panes to the class, or makes
To apply these changes, the :meth:`AuiManager.Update() <AuiManager.Update>` function is called. This batch

**Layers, Rows and Directions, Positions:**

:param wx.Window `managed_window`: specifies the window which should be managed;
:param integer `agwFlags`: specifies options which allow the frame management behavior to be
 modified. `agwFlags` can be a combination of the following style bits:

 ``AUI_MGR_ALLOW_FLOATING``           Allow floating of panes
 ``AUI_MGR_ALLOW_ACTIVE_PANE``        If a pane becomes active, "highlight" it in the interface
 ``AUI_MGR_TRANSPARENT_DRAG``         If the platform supports it, set transparency on a floating pane while it is dragged by the user
 ``AUI_MGR_TRANSPARENT_HINT``         If the platform supports it, show a transparent hint window when the user is about to dock a floating pane
 ``AUI_MGR_VENETIAN_BLINDS_HINT``     Show a "venetian blind" effect when the user is about to dock a floating pane
 ``AUI_MGR_RECTANGLE_HINT``           Show a rectangle hint effect when the user is about to dock a floating pane
 ``AUI_MGR_HINT_FADE``                If the platform supports it, the hint window will fade in and out
 ``AUI_MGR_NO_VENETIAN_BLINDS_FADE``  Disables the "venetian blind" fade in and out
 ``AUI_MGR_LIVE_RESIZE``              Live resize when the user drag a sash
 ``AUI_MGR_ANIMATE_FRAMES``           Fade-out floating panes when they are closed (all platforms which support frames transparency)
                                      and show a moving rectangle when they are docked (Windows < Vista and GTK only)
 ``AUI_MGR_AERO_DOCKING_GUIDES``      Use the new Aero-style bitmaps as docking guides
 ``AUI_MGR_PREVIEW_MINIMIZED_PANES``  Slide in and out minimized panes to preview them
 ``AUI_MGR_WHIDBEY_DOCKING_GUIDES``   Use the new Whidbey-style bitmaps as docking guides
 ``AUI_MGR_SMOOTH_DOCKING``           Performs a "smooth" docking of panes (a la PyQT)
 ``AUI_MGR_USE_NATIVE_MINIFRAMES``    Use miniframes with native caption bar as floating panes instead or custom drawn caption bars (forced on wxMAC)
 ``AUI_MGR_AUTONB_NO_CAPTION``        Panes that merge into an automatic notebook will not have the pane caption visible

 Default value for `agwFlags` is:
 ``AUI_MGR_DEFAULT`` = ``AUI_MGR_ALLOW_FLOATING`` | ``AUI_MGR_TRANSPARENT_HINT`` | ``AUI_MGR_HINT_FADE`` | ``AUI_MGR_NO_VENETIAN_BLINDS_FADE``

 .. note::

    If using the ``AUI_MGR_USE_NATIVE_MINIFRAMES``, double-clicking on a
    floating pane caption will not re-dock the pane, but simply maximize it (if
    :meth:`AuiPaneInfo.MaximizeButton` has been set to ``True``) or do nothing.

Activates the pane to which `window` is associated.

:param `window`: a :class:`wx.Window` derived window.

Tells the frame manager to start managing a child window. There
are four versions of this function. The first version allows the full spectrum
of pane parameter possibilities (:meth:`AddPane1`). The second version is used for
simpler user interfaces which do not require as much configuration (:meth:`AddPane2`).
The :meth:`AddPane3` version allows a drop position to be specified, which will determine
where the pane will be added. The :meth:`AddPane4` version allows to turn the target
:class:`AuiPaneInfo` pane into a notebook and the added pane into a page.

In your code, simply call :meth:`AddPane`.

:param wx.Window `window`: the child window to manage;
:param `arg1`: a :class:`AuiPaneInfo` or an integer value (direction);
:param `arg2`: a :class:`AuiPaneInfo` or a :class:`wx.Point` (drop position);
:param `target`: a :class:`AuiPaneInfo` to be turned into a notebook
 and new pane added to it as a page. (additionally, target can be any pane in
 an existing notebook)
 
Animates the minimization/docking of a pane a la Eclipse, using a :class:`ScreenDC`
to draw a "moving docking rectangle" on the screen.

:param wx.Rect `win_rect`: the original pane screen rectangle;
:param wx.Rect `pane_rect`: the newly created toolbar/pane screen rectangle.

:note: This functionality is not available on wxMAC as this platform doesn't have
 the ability to use :class:`ScreenDC` to draw on-screen and on Windows > Vista.

Calculates the minimum and maximum sizes allowed for the input dock.

:param `dock`: the :class:`AuiDockInfo` structure to analyze.

Calculates the drop hint rectangle.

The method first calls :meth:`DoDrop` to determine the exact position the pane would
be at were if dropped. If the pane would indeed become docked at the
specified drop point, the the rectangle hint will be returned in
screen coordinates. Otherwise, an empty rectangle is returned.

:param wx.Window `pane_window`: it is the window pointer of the pane being dragged;
:param wx.Point `pt`: is the mouse position, in client coordinates;
:param wx.Point `offset`: describes the offset that the mouse is from the upper-left
 corner of the item being dragged.

Calculates the minimum and maximum sizes allowed for the input pane.

:param `dock`: the :class:`AuiDockInfo` structure to which `pane` belongs to;
:param `pane`: a :class:`AuiPaneInfo` class for which calculation are requested.

Returns whether a pane can be docked or not.

:param `p`: the :class:`AuiPaneInfo` class with all the pane's information.

Returns whether :class:`dockart` can be used (Windows XP / Vista / 7 only,
requires Mark Hammonds's `pywin32 <https://sourceforge.net/projects/pywin32/>`_ package).

Checks if a UI part can be actually resized.

:param `part`: a UI part, an instance of :class:`AuiDockUIPart`.

Checks if a pane has moved by a visible amount.

:param `pane`: an instance of :class:`AuiPaneInfo`.

Destroys or hides the pane depending on its flags.

:param `pane_info`: a :class:`AuiPaneInfo` instance.

Copies all the attributes of the input `target` into another :class:`AuiPaneInfo`.

:param `target`: the source :class:`AuiPaneInfo` from where to copy attributes.

Creates a floating frame for the windows.

:param wx.Window `parent`: the floating frame parent;
:param `pane_info`: the :class:`AuiPaneInfo` class with all the pane's information.

Creates an automatic :class:`~wx.lib.agw.aui.auibook.AuiNotebook` when a pane is docked on
top of another pane.

Creates an auto-notebook base from a pane, and then add that pane as a page.

:param list `panes`: set of panes to append new notebook base pane to
:param `paneInfo`: the pane to be converted to a new notebook, an instance of
 :class:`AuiPaneInfo`.

Tells the :class:`AuiManager` to stop managing the pane specified
by `window`. The window, if in a floated frame, is reparented to the frame
managed by :class:`AuiManager`.

:param wx.Window `window`: the window to be un-managed.

This is an important function. It basically takes a mouse position,
and determines where the panes new position would be. If the pane is to be
dropped, it performs the drop operation using the specified dock and pane
arrays. By specifying copy dock and pane arrays when calling, a "what-if"
scenario can be performed, giving precise coordinates for drop hints.

:param `docks`: a list of :class:`AuiDockInfo` classes;
:param `panes`: a list of :class:`AuiPaneInfo` instances;
:param wx.Point `pt`: a mouse position to check for a drop operation;
:param wx.Point `offset`: a possible offset from the input point `pt`.

Handles the situation in which the dropped pane contains a normal window.

:param `target`: the target pane containing the window, an instance of
 :class:`AuiPaneInfo`;
:param wx.Point `pt`: a mouse position to check for a drop operation.

Handles the situation in which `target` is a single dock guide.

:param `target`: the target pane, an instance of :class:`AuiPaneInfo`;
:param integer `dock_direction`: the docking direction.

Handles the situation in which the dropped pane is not floating.

:param `target`: the target pane containing the toolbar, an instance of :class:`AuiPaneInfo`;

Drop a pane in the interface.

:param `panes`: a list of :class:`AuiPaneInfo` classes;
:param integer `dock_direction`: the docking direction;
:param integer `dock_layer`: the docking layer;
:param integer `dock_row`: the docking row;
:param integer `dock_pos`: the docking position.

DoDropPane(self, panes, target, dock_direction, dock_layer, dock_row, dock_pos)

Insert a row in the interface before dropping.

:param integer `dock_row`: the docking row.

DoDropRow(self, panes, target, dock_direction, dock_layer, dock_row)

Handles the situation in which the dropped pane contains a toolbar.

Ends a resize action, or for live update, resizes the sash.

:param `event`: a :class:`MouseEvent` to be processed.

This is an internal function which invokes :meth:`wx.Sizer.Layout() <Sizer.Layout>`
on the frame's main sizer, then measures all the various UI items
and updates their internal rectangles.

:note: This should always be called instead of calling
 `self._managed_window.Layout()` directly.

This method is called after any number of changes are made to any of the
managed panes. :meth:`Update` must be invoked after :meth:`AddPane`
or :meth:`InsertPane` are called in order to "realize" or "commit" the changes.

In addition, any number of changes may be made to :class:`AuiManager` structures
(retrieved with :meth:`GetPane`), but to realize the changes, :meth:`Update`
must be called. This construction allows pane flicker to be avoided by updating
the whole layout at one time.

Calculates the hint rectangle by calling :meth:`CalculateHintRect`. If there is a
rectangle, it shows it by calling :meth:`ShowHint`, otherwise it hides any hint
rectangle currently shown.

Draws a pane button in the caption (convenience function).

:param `part`: the UI part to analyze, an instance of :class:`AuiDockUIPart`;

Fires one of the ``EVT_AUI_PANE_FLOATED`` / ``FLOATING`` / ``DOCKING`` / ``DOCKED`` / ``ACTIVATED`` event.

:param integer `evtType`: one of the aforementioned events;
:param `pane`: the :class:`AuiPaneInfo` instance associated to this event;
:param bool `canVeto`: whether the event can be vetoed or not.

Returns the current manager's flags.

:see: :meth:`SetAGWFlags` for a list of possible :class:`AuiManager` flags.

Returns the animation step speed (a float) to use in :meth:`AnimateDocking`. 

Returns all the attributes of a :class:`AuiPaneInfo`.

:param `pane`: a :class:`AuiPaneInfo` instance.

Returns the default AGW-specific window style for automatic notebooks.

:see: :meth:`SetAutoNotebookStyle` method for a list of possible styles.

This is an internal function which returns a dock's offset in pixels from
the left side of the window (for horizontal docks) or from the top of the
window (for vertical docks).

This value is necessary for calculating fixed-pane/toolbar offsets
when they are dragged.

:param `test`: a fake :class:`AuiPaneInfo` for testing purposes.

Returns the current dock constraint values.

:see: :meth:`SetDockSizeConstraint`

Returns the window being managed by :class:`AuiManager`.

   This method is now deprecated, use :meth:`GetManagedWindow` instead.

Returns all the automatic :class:`~wx.lib.agw.aui.auibook.AuiNotebook` in the :class:`AuiManager`. 

Returns the dimensions of the dock which lives opposite of the input dock.

:param `docks`: a list of :class:`AuiDockInfo` structures to analyze;
:param integer `direction`: the direction in which to look for the opposite dock.

Looks up a :class:`AuiPaneInfo` structure based on the supplied window pointer. Upon failure,
:meth:`GetPane` returns an empty :class:`AuiPaneInfo`, a condition which can be checked
by calling :meth:`AuiPaneInfo.IsOk() <AuiPaneInfo.IsOk>`.

The pane info's structure may then be modified. Once a pane's info is modified, :meth:`Update`
must be called to realize the changes in the UI.

:param `item`: either a pane name or a :class:`wx.Window`.

This version of :meth:`GetPane` looks up a pane based on a 'pane name'.

:param string `name`: the pane name.

:see: :meth:`GetPane`

This version of :meth:`GetPane` looks up a pane based on a 'pane window'.

:see: :meth:`~AuiManager.GetPane`

Looks up the pane border UI part of the
pane specified. This allows the caller to get the exact rectangle
of the pane in question, including decorations like caption and border.

:param wx.Window `wnd`: the window to which the pane border belongs to.

Returns all the panes positions and sizes in a dock.

:param `dock`: a :class:`AuiDockInfo` instance.

Returns the partner dock for the input dock.

Returns the partner pane for the input pane. They both need to live
in the same :class:`AuiDockInfo`.

:param `dock`: a :class:`AuiDockInfo` instance;
:param `pane`: a :class:`AuiPaneInfo` class.

Returns the rectangle surrounding the specified UI parts.

:param list `uiparts`: list of :class:`AuiDockUIPart` parts.

Returns the dimensions and proportion of the input dock.

This is an internal function which determines
which UI item the specified coordinates are over.

:param integer `x`: specifies a x position in client coordinates;
:param integer `y`: specifies a y position in client coordinates.

This method is used to insert either a previously unmanaged pane window
into the frame manager, or to insert a currently managed pane somewhere else.
:meth:`InsertPane` will push all panes, rows, or docks aside and insert the window
into the position specified by `pane_info`.

Because `pane_info` can specify either a pane, dock row, or dock layer, the
`insert_level` parameter is used to disambiguate this. The parameter `insert_level`
can take a value of ``AUI_INSERT_PANE``, ``AUI_INSERT_ROW`` or ``AUI_INSERT_DOCK``.

:param wx.Window `window`: the window to be inserted and managed;
:param `pane_info`: the insert location for the new window;
:param integer `insert_level`: the insertion level of the new pane.

InsertPane(self, window, pane_info, insert_level=AUI_INSERT_PANE)

Returns whether a pane button in the pane caption is visible.

:param `part`: the UI part to analyze, an instance of :class:`AuiDockUIPart`.

Adds a dock into the existing layout.

:param `cont`: a :class:`wx.Sizer` object;
:param `dock`: the :class:`AuiDockInfo` structure to add to the layout;
:param `uiparts`: a list of UI parts in the interface;
:param bool `spacer_only`: whether to add a simple spacer or a real window.

Adds a pane into the existing layout (in an existing dock).

:param `dock`: the :class:`AuiDockInfo` structure in which to add the pane;
:param `pane`: the :class:`AuiPaneInfo` instance to add to the dock;

Layouts all the UI structures in the interface.

:param bool `spacer_only`: whether to add a simple spacer or a real window;
:param bool `oncheck`: whether to store the results in a class member or not.

LayoutAll(self, panes, docks, uiparts, spacer_only=False, oncheck=True)

This method is similar to to :meth:`LoadPerspective`, with the exception that
it only loads information about a single pane. It is used in combination
with :meth:`SavePaneInfo`.

:param string `pane_part`: the string to analyze;
:param `pane`: the :class:`AuiPaneInfo` structure in which to load `pane_part`.

If the `update` flag parameter is ``True``, :meth:`Update` will be
automatically invoked, thus realizing the saved perspective on screen.

:param string `layout`: a string which contains a saved AUI layout;
:param bool `update`: whether to update immediately the window or not;
:param bool `restorecaption`: ``False``, restore from persist storage,
 otherwise use the caption defined in code.

LoadPerspective(self, layout, update=True, restorecaption=False)

Maximizes the input pane.

:param bool `savesizes`: whether to save previous dock sizes.

Minimizes a pane in a newly and automatically created :class:`~wx.lib.agw.aui.auibar.AuiToolBar`.

Clicking on the minimize button causes a new :class:`~wx.lib.agw.aui.auibar.AuiToolBar` to be created
and added to the frame manager (currently the implementation is such that
panes at West will have a toolbar at the right, panes at South will have
toolbars at the bottom etc...) and the pane is hidden in the manager.

Clicking on the restore button on the newly created toolbar will result in the
toolbar being removed and the original pane being restored.

:param `paneInfo`: a :class:`AuiPaneInfo` instance for the pane to be minimized;
:param bool `mgrUpdate`: ``True`` to call :meth:`Update` to realize the new layout,
 ``False`` otherwise.

.. note::

   The `mgrUpdate` parameter is currently only used while loading perspectives using
   :meth:`LoadPerspective`, as minimized panes were not correctly taken into account before.

Handles the mouse double click on the pane caption.

:param wx.Window `pane_window`: the window managed by the pane.

Handles the ``wx.EVT_MOUSE_CAPTURE_LOST`` event for :class:`AuiManager`.

:param `event`: a :class:`MouseCaptureLostEvent` to be processed.

Handles the ``wx.EVT_CHILD_FOCUS`` event for :class:`AuiManager`.

:param `event`: a :class:`ChildFocusEvent` to be processed.

Called when the managed window is closed. Makes sure that :meth:`UnInit`
is called.

Called when the managed window is destroyed. Makes sure that :meth:`UnInit`
is called.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`AuiManager`.

:note: This is intentionally empty (excluding wxMAC) to reduce
 flickering while drawing.

Handles the ``EVT_AUI_FIND_MANAGER`` event for :class:`AuiManager`.

Handles the activation event of a floating pane.

:param wx.Window `wnd`: the window managed by the pane.

Handles the close event of a floating pane.

:param wx.Window `wnd`: the window managed by the pane;

Handles the move event of a floating pane.

:param `eventOrPt`: a :class:`MoveEvent` to be processed or an instance of :class:`wx.Point`.

Handles the resizing of a floating pane.

:param wx.Size `size`: the new pane floating size.

Handles the mouse click on the pane gripper.

:param wx.Window `pane_window`: the window managed by the pane;
:param wx.Point `start`: the mouse-click position;
:param wx.Point `offset`: an offset point from the `start` position.

Handles the ``wx.EVT_TIMER`` event for :class:`AuiManager`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`AuiManager`.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`AuiManager`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AuiManager`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`AuiManager`.

Sub-handler for the :meth:`OnLeftUp` event.

Handles the ``wx.EVT_MOTION`` event for :class:`AuiManager`.

Sub-handler for the :meth:`OnMotion` event.

Handles the ``wx.EVT_MOVE`` event for :class:`AuiManager`.

Handles the ``wx.EVT_PAINT`` event for :class:`AuiManager`.

Handles the ``EVT_AUI_PANE_BUTTON`` event for :class:`AuiManager`.

Handles the ``EVT_AUI_PANE_DOCKED`` event for :class:`AuiManager`.

:param `event`: an instance of :class:`AuiManagerEvent` to be processed.

Draws all of the pane captions, sashes, backgrounds, captions, grippers, pane borders and buttons.
It renders the entire user interface. It binds the ``EVT_AUI_RENDER`` event.

:param `event`: an instance of :class:`AuiManagerEvent`.

Handles the ``EVT_AUI_PANE_MIN_RESTORE`` event for :class:`AuiManager`.

Handles the ``wx.EVT_SET_CURSOR`` event for :class:`AuiManager`.

:param `event`: a :class:`SetCursorEvent` to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`AuiManager`.

Handles the ``wx.EVT_SYS_COLOUR_CHANGED`` event for :class:`AuiManager`.

:param `event`: a :class:`SysColourChangedEvent` to be processed.

Handles the ``EVT_AUINOTEBOOK_BEGIN_DRAG`` event.

:param `event`: a :class:`~wx.lib.agw.aui.auibook.AuiNotebookEvent` event to be processed.

Handles the ``EVT_AUINOTEBOOK_END_DRAG`` event.

Handles the ``EVT_AUINOTEBOOK_PAGE_CLOSE`` event.

Handles the ``EVT_AUINOTEBOOK_PAGE_CHANGED`` event.

Returns a :class:`AuiPaneInfo` from a :class:`~wx.lib.agw.aui.auibook.AuiNotebook` event.

:param `event`: a :class:`~wx.lib.agw.aui.auibook.AuiNotebookEvent` event.

Similar to :meth:`HitTest`, but it checks in which :class:`AuiManager` rectangle the
input point belongs to.

:param wx.Point `pt`: the mouse position.

This is a utility function used by :meth:`DoDrop` - it checks
if a dock operation is allowed, the new dock position is copied into
the target info. If the operation was allowed, the function returns ``True``.

:param `target`: the :class:`AuiPaneInfo` instance to be docked;
:param integer `new_pos`: the new docking position if the docking operation is allowed.

Process the AUI events sent to the manager.

:param `event`: the event to process, an instance of :class:`AuiManagerEvent`.

Refreshes a pane button in the caption.

Removes the caption on newly created automatic notebooks.

:param `pane`: an instance of :class:`AuiPaneInfo` (the target notebook).

Fires a render event, which is normally handled by :meth:`OnRender`. This allows the
render function to be overridden via the render event.

This can be useful for painting custom graphics in the main window.
Default behavior can be invoked in the overridden function by calling
:meth:`OnRender`.

Repaints the entire frame decorations (sashes, borders, buttons and so on).
It renders the entire user interface.

:param `dc`: if not ``None``, an instance of :class:`PaintDC`.

Repositions a pane after the main frame has been moved/resized.

:param `pane`: a :class:`AuiPaneInfo` instance;
:param wx.Point `wnd_pos`: the main frame position;
:param wx.Size `wnd_size`: the main frame size.

Restores a previously minimized pane.

:param `paneInfo`: a :class:`AuiPaneInfo` instance for the pane to be restored.

Restores the input pane from a previous maximized or minimized state.

Common method between :meth:`DoEndResizeAction` and :meth:`OnLeftUp_Resize`. 

This method is similar to :meth:`SavePerspective`, with the exception
that it only saves information about a single pane. It is used in
combination with :meth:`LoadPaneInfo`.

:param `pane`: a :class:`AuiPaneInfo` instance to save.

be stored by the application (probably using :class:`Config <ConfigBase>`).

When a perspective is restored using :meth:`LoadPerspective`, the entire user
interface will return to the state it was when the perspective was saved.

Stores the previous dock sizes, to be used in a "restore" action later.

This method is used to specify :class:`AuiManager` 's settings flags.

:param integer `agwFlags`: specifies options which allow the frame management behavior
 to be modified. `agwFlags` can be one of the following style bits:

 .. note::

Sets the animation step speed (a float) to use in :meth:`AnimateDocking`.

:param float `step`: the animation speed.

Instructs :class:`AuiManager` to use art provider specified by the parameter
`art_provider` for all drawing calls. This allows pluggable look-and-feel
features.

:param `art_provider`: a AUI dock art provider.

:note: The previous art provider object, if any, will be deleted by :class:`AuiManager`.

Sets all the attributes contained in `attrs` to a :class:`AuiPaneInfo`.

:param list `attrs`: a list of attributes.

Sets the default AGW-specific window style for automatic notebooks.

:param integer `agwStyle`: the underlying :class:`~wx.lib.agw.aui.auibook.AuiNotebook` window style.
 This can be a combination of the following bits:

 ``AUI_NB_MIDDLE_CLICK_CLOSE``        Allows to close :class:`~wx.lib.agw.aui.auibook.AuiNotebook` tabs by mouse middle button click
 ``AUI_NB_SUB_NOTEBOOK``              This style is used by :class:`AuiManager` to create automatic AuiNotebooks
 ``AUI_NB_TAB_FLOAT``                 Allows the floating of single tabs. Known limitation: when the notebook is more or less
                                      full screen, tabs cannot be dragged far enough outside of the notebook to become floating pages

Sets the default tab art provider for automatic notebooks.

:param `art`: a tab art provider.

When a user creates a new dock by dragging a window into a docked position,
often times the large size of the window will create a dock that is unwieldy
large.

:class:`AuiManager` by default limits the size of any new dock to 1/3 of the window
size. For horizontal docks, this would be 1/3 of the window height. For vertical
docks, 1/3 of the width. Calling this function will adjust this constraint value.

The numbers must be between 0.0 and 1.0. For instance, calling :meth:`SetDockSizeConstraint`
with (0.5, 0.5) will cause new docks to be limited to half of the size of the entire
managed window.

:param float `width_pct`: a number representing the `x` dock size constraint;
:param float `width_pct`: a number representing the `y` dock size constraint.

Called to specify the frame or window which is to be managed by :class:`AuiManager`.
Frame management is not restricted to just frames. Child windows or custom
controls are also allowed.

:param wx.Window `managed_window`: specifies the window which should be managed by
 the AUI manager.

   This method is now deprecated, use :meth:`SetManagedWindow` instead.

Sets the master manager for an automatic :class:`~wx.lib.agw.aui.auibook.AuiNotebook`.

:param `manager`: an instance of :class:`AuiManager`.

Modifies the snap limits used when snapping the `managed_window` to the screen
(using :meth:`SnapToScreen`) or when snapping the floating panes to one side of the
`managed_window` (using :meth:`SnapPane`).

To change the limit after which the `managed_window` or the floating panes are
automatically stickled to the screen border (or to the `managed_window` side),
set these two variables. Default values are 15 pixels.

:param integer `x`: the minimum horizontal distance below which the snap occurs;
:param integer `y`: the minimum vertical distance below which the snap occurs.

Shows the AUI hint window.

:param wx.Rect `rect`: the hint rect calculated in advance.

Shows or hides a pane based on the window passed as input.

:param wx.Window `window`: any subclass or derivation of :class:`wx.Window`;
:param bool `show`: ``True`` to show the pane, ``False`` otherwise.

:note: This is used solely for sliding in and out minimized panes.

Slides out a preview of a minimized pane.

Used to intelligently shrink the docks' size (if needed).

:param `docks`: a list of :class:`AuiDockInfo` instances;
:param integer `direction`: the direction in which to shrink.

This method implements a smooth docking effect for floating panes, similar to
what the PyQT library does with its floating windows.

:param `paneInfo`: an instance of :class:`AuiPaneInfo`.

:note: The smooth docking effect can only be used if you set the ``AUI_MGR_SMOOTH_DOCKING``
 style to :class:`AuiManager`.

Snaps the main frame to specified position on the screen.

:see: :meth:`SnapToScreen`

Snaps a floating pane to one of the main frame sides.

:param wx.Point `pane_pos`: the new pane floating position;
:param wx.Size `pane_size`: the new pane floating size;
:param bool `toSnap`: a bool variable to check if :meth:`SnapPane` was called from
 a move event.

:param bool `snap`: whether to snap the main frame or not;
:param integer `monitor`: the monitor display in which snapping the window;
:param integer `hAlign`: the horizontal alignment of the snapping position;
:param integer `vAlign`: the vertical alignment of the snapping position.

SnapToScreen(self, snap=True, monitor=0, hAlign=wx.RIGHT, vAlign=wx.TOP)

Starts a timer for sliding in and out a minimized pane.

:param `toolbar`: the :class:`~wx.lib.agw.aui.auibar.AuiToolBar` containing the minimized pane tool.

Switches the toolbar orientation from vertical to horizontal and vice-versa.
This is especially useful for vertical docked toolbars once they float.

:param `pane`: an instance of :class:`AuiPaneInfo`, which may have a :class:`~wx.lib.agw.aui.auibar.AuiToolBar`
 window associated with it.

Uninitializes the framework and should be called before a managed frame or
window is destroyed. :meth:`UnInit` is usually called in the managed :class:`wx.Frame` / :class:`wx.Window`
destructor.

It is necessary to call this function before the managed frame or window is
destroyed, otherwise the manager cannot remove its custom event handlers
from a window.

Updates/redraws the UI part containing a pane button.

:param `button_ui_part`: the UI part the button belongs to, an instance of :class:`AuiDockUIPart`.;

Updates the docking guide windows positions and appearance.

:param `paneInfo`: a :class:`AuiPaneInfo` instance.

Updates the automatic :class:`~wx.lib.agw.aui.auibook.AuiNotebook` in the layout (if any exists). 

A class similar to :class:`AuiManager` but with a Dummy Center Pane (**DCP**).
The code for this class is still flickery due to the call to :func:`CallAfter`
and the double-update call.

managed panes. :meth:`Update` must be invoked after :meth:`AuiManager.AddPane` or
:meth:`AuiManager.InsertPane` are called in order to "realize" or "commit" the changes.

(retrieved with :meth:`AuiManager.GetPane`), but to realize the changes,
:meth:`Update` must be called. This construction allows pane flicker to
be avoided by updating the whole layout at one time.

A specialized command event class for events sent by :class:`AuiManager`. 

:param integer `eventType`: the event kind;
:param integer `id`: the event identification number.

Returns the associated :class:`AuiPaneButton` instance (if any). 

Returns the associated :class:`AuiPaneInfo` structure (if any). 

Associates a :class:`AuiPaneButton` instance to this event.

:param `b`: a :class:`AuiPaneButton` instance.

Sets whether the event can be vetoed or not.

:param bool `can_veto`: ``True`` if the event can be vetoed, ``False`` otherwise.

Associates a :class:`wx.DC` device context to this event.

:param `pdc`: a :class:`wx.DC` device context object.

Associates a :class:`AuiManager` to the current event.

:param `mgr`: an instance of :class:`AuiManager`.

Associates a :class:`AuiPaneInfo` instance to this event.

:param `p`: a :class:`AuiPaneInfo` instance.

:param bool `veto`: ``True`` to veto the event, ``False`` otherwise.

A simple class which describes the caption pane button attributes. 

:param integer `button_id`: the pane button identifier.

AuiPaneInfo specifies all the parameters for a pane. These parameters specify where
the pane is on the screen, whether it is docked or floating, or hidden. In addition,
these parameters specify the pane's docked position, floating position, preferred
size, minimum size, caption text among many other parameters.

Sets the ideal size for the pane. The docking manager will attempt to use
this size as much as possible when docking or floating the pane.

This method is split in 2 versions depending on the input type. If `arg1` is
a :class:`wx.Size` object, then :meth:`BestSize1` is called. Otherwise, :meth:`BestSize2` is called.

:param `arg1`: a :class:`wx.Size` object, a (x, y) tuple or a `x` coordinate.
:param `arg2`: a `y` coordinate (only if `arg1` is a `x` coordinate, otherwise unused).

Sets the best size of the pane.

:see: :meth:`BestSize` for an explanation of input parameters.

Sets the pane dock position to the bottom of the frame.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_BOTTOM`` as
 parameter.

Indicates whether a pane can be docked at the bottom of the frame.

:param bool `b`: whether the pane can be docked at the bottom or not.

Indicates whether a pane can be snapped at the bottom of the main frame.

:param bool `b`: whether the pane can be snapped at the bottom of the main frame or not.

Sets the caption of the pane.

:param string `caption`: a string specifying the pane caption.

Indicates that a pane caption should be visible. If `visible` is ``False``, no pane
caption is drawn.

:param bool `visible`: whether the caption should be visible or not;
:param bool `left`: whether the caption should be drawn on the left (rotated by 90 degrees) or not.

Sets the pane to the center position of the frame.

The centre pane is the space in the middle after all border panes (left, top,
right, bottom) are subtracted from the layout.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_CENTER`` as

Specifies that the pane should adopt the default center pane settings.

Centre panes usually do not have caption bars. This function provides an easy way of
preparing a pane to be displayed in the center dock position.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_CENTRE`` as

Indicates that a close button should be drawn for the pane.

:param bool `visible`: whether the close button should be visible or not.

Specifies that the pane should adopt the default pane settings. 

Indicates whether a pane should be destroyed when it is closed.

Normally a pane is simply hidden when the close button is clicked. Setting
`b` to ``True`` will cause the window to be destroyed when the user clicks
the pane's close button.

:param bool `b`: whether the pane should be destroyed when it is closed or not.

Determines the direction of the docked pane. It is functionally the
same as calling :meth:`Left`, :meth:`Right`, :meth:`Top` or :meth:`Bottom`,
except that docking direction may be specified programmatically via the parameter `direction`.

:param integer `direction`: the direction of the docked pane.

:see: :meth:`dock_direction_set` for a list of valid docking directions.

Indicates that a pane should be docked. It is the opposite of :meth:`Float`. 

Getter for the `dock_direction`.

:see: :meth:`~AuiPaneInfo.dock_direction_set` for a set of valid docking directions.

Setter for the `dock_direction`.

:param integer `value`: the docking direction. This can be one of the following bits:

============================ ======= =============================================
Dock Flag                     Value  Description
``AUI_DOCK_NONE``                  0 No docking direction.
``AUI_DOCK_TOP``                   1 Top docking direction.
``AUI_DOCK_RIGHT``                 2 Right docking direction.
``AUI_DOCK_BOTTOM``                3 Bottom docking direction.
``AUI_DOCK_LEFT``                  4 Left docking direction.
``AUI_DOCK_CENTER``                5 Center docking direction.
``AUI_DOCK_CENTRE``                5 Centre docking direction.
``AUI_DOCK_NOTEBOOK_PAGE``         6 Automatic AuiNotebooks docking style.

Specifies whether a frame can be docked or not. It is the same as specifying
:meth:`TopDockable` . :meth:`BottomDockable` . :meth:`LeftDockable` . :meth:`RightDockable` .

:param bool `b`: whether the frame can be docked or not.

Causes the containing dock to have no resize sash. This is useful
for creating panes that span the entire width or height of a dock, but should
not be resizable in the other direction.

:param bool `b`: whether the pane will have a resize sash or not.

Forces a pane to be fixed size so that it cannot be resized.
After calling :meth:`Fixed`, :meth:`IsFixed` will return ``True``.

Indicates that a pane should be floated. It is the opposite of :meth:`Dock`. 

Sets whether the user will be able to undock a pane and turn it
into a floating window.

:param bool `b`: whether the pane can be floated or not.

Sets the position of the floating pane.

:param `pos`: a :class:`wx.Point` or a tuple indicating the pane floating position.

Sets the size of the floating pane.

:param `size`: a :class:`wx.Size` or a tuple indicating the pane floating size.

Indicates whether a pane, when floating, has a "fly-out" effect
(i.e., floating panes which only show themselves when moused over).

:param bool `b`: whether the pane can be snapped on the main frame or not.

Returns the minimization style for this pane.

Possible return values are:

============================== ========= ==============================
Minimize Mode Flag             Hex Value Description
``AUI_MINIMIZE_POS_SMART``          0x01 Minimizes the pane on the closest tool bar
``AUI_MINIMIZE_POS_TOP``            0x02 Minimizes the pane on the top tool bar
``AUI_MINIMIZE_POS_LEFT``           0x03 Minimizes the pane on its left tool bar
``AUI_MINIMIZE_POS_RIGHT``          0x04 Minimizes the pane on its right tool bar
``AUI_MINIMIZE_POS_BOTTOM``         0x05 Minimizes the pane on its bottom tool bar
``AUI_MINIMIZE_POS_TOOLBAR``        0x06 Minimizes the pane on a target :class:`~wx.lib.agw.aui.auibar.AuiToolBar`
``AUI_MINIMIZE_POS_MASK``           0x17 Mask to filter the position flags
``AUI_MINIMIZE_CAPT_HIDE``           0x0 Hides the caption of the minimized pane
``AUI_MINIMIZE_CAPT_SMART``         0x08 Displays the caption in the best rotation (horizontal or clockwise)
``AUI_MINIMIZE_CAPT_HORZ``          0x10 Displays the caption horizontally
``AUI_MINIMIZE_CAPT_MASK``          0x18 Mask to filter the caption flags

The flags can be filtered with the following masks:

Minimize Mask Flag             Hex Value Description
``AUI_MINIMIZE_POS_MASK``           0x17 Filters the position flags
``AUI_MINIMIZE_CAPT_MASK``          0x18 Filters the caption flags

Indicates that a gripper should be drawn for the pane.

:param bool `visible`: whether the gripper should be visible or not.

Indicates that a gripper should be drawn at the top of the pane.

:param bool `attop`: whether the gripper should be drawn at the top or not.

Returns ``True`` if the pane displays a caption on the left (rotated by 90 degrees). 

Returns ``True`` if the pane displays a button to close the pane. 

Returns ``True`` if the the property specified by flag is active for the pane.

:param integer `flag`: the property to check for activity.

Returns ``True`` if the pane displays a button to maximize the pane. 

Returns ``True`` if the pane displays a button to minimize the pane. 

Returns whether a pane has a :class:`~wx.lib.agw.aui.auibook.AuiNotebook` or not. 

Returns ``True`` if the pane displays a button to float the pane. 

Indicates that a pane should be hidden.

Calling :meth:`Show(False) <Show>` achieve the same effect.

Specifies whether an icon is drawn on the left of the caption text when
the pane is docked. If `icon` is ``None`` or :class:`NullIcon`, no icon is drawn on
the caption space.

:param icon: an icon to draw on the caption space, or ``None``.
:type `icon`: :class:`Icon` or ``None``

Returns ``True`` if the pane can be docked at the bottom
of the managed frame.

Returns ``True`` if the pane can be snapped at the bottom of the managed frame. 

Returns ``True`` if the pane should be destroyed when it is closed.

Normally a pane is simply hidden when the close button is clicked. Calling :meth:`~AuiPaneInfo.DestroyOnClose`
with a ``True`` input parameter will cause the window to be destroyed when the user clicks

Returns ``True`` if the pane can be undocked and displayed as a
floating window.

Returns ``True`` if the pane can be docked at the left

Returns ``True`` if the pane can be snapped on the left of the managed frame. 

Returns ``True`` if the docked frame can be undocked or moved to
another dock position.

Returns whether the pane is a notebook control (:class:`~wx.lib.agw.aui.auibook.AuiNotebook`). 

Returns ``True`` if a pane can be docked on top to another to create a

Returns whether the pane is a notebook page in a :class:`~wx.lib.agw.aui.auibook.AuiNotebook`. 

Returns ``True`` if the :class:`AuiPaneInfo` structure is valid.

:note: A pane structure is valid if it has an associated window.

Returns ``True`` if the pane can be docked at the right

Returns ``True`` if the pane can be snapped on the right of the managed frame. 

Returns ``True`` if the pane can be docked at the top

Returns ``True`` if the pane can be snapped at the top of the managed frame. 

Determines the layer of the docked pane.

The dock layer is similar to an onion, the inner-most layer being layer 0. Each
shell moving in the outward direction has a higher layer number. This allows for
more complex docking layout formation.

:param integer `layer`: the layer of the docked pane.

Sets the pane dock position to the left side of the frame.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_LEFT`` as

Indicates whether a pane can be docked on the left of the frame.

:param bool `b`: whether the pane can be docked at the left or not.

Indicates whether a pane can be snapped on the left of the main frame.

:param bool `b`: whether the pane can be snapped at the left of the main frame or not.

Indicates that a maximize button should be drawn for the pane.

:param bool `visible`: whether the maximize button should be visible or not.

Sets the maximum size of the pane.

a :class:`wx.Size` object, then :meth:`~AuiPaneInfo.MaxSize1` is called. Otherwise, :meth:`~AuiPaneInfo.MaxSize2` is called.

:see: :meth:`MaxSize` for an explanation of input parameters.

Makes the pane minimized in a :class:`~wx.lib.agw.aui.auibar.AuiToolBar`.

and added to the frame manager, (currently the implementation is such that

Indicates that a minimize button should be drawn for the pane.

:param bool `visible`: whether the minimize button should be visible or not.

Sets the expected minimized mode if the minimize button is visible.

:param integer `mode`: the minimized pane can have a specific position in the work space:

The caption of the minimized pane can be displayed in different modes:

Caption Mode Flag              Hex Value Description
``AUI_MINIMIZE_CAPT_SMART``         0x08 Displays the caption in the best rotation (horizontal in the top and in
                                         the bottom tool bar or clockwise in the right and in the left tool bar)

.. note::

   In order to use the ``AUI_MINIMIZE_POS_TOOLBAR`` flag, the instance of :class:`AuiManager`
   you pass as an input for :meth:`MinimizeTarget` **must** have a real name and not the randomly
   generated one. Remember to set the :meth:`Name` property of the toolbar pane before calling this method.

Minimizes the panes using a :class:`AuiPaneInfo` as a target. As :class:`AuiPaneInfo` properties
need to be copied back and forth every time the perspective has changed, we
only store the toobar **name**.

:param `toolbarPane`: an instance of :class:`AuiPaneInfo`, containing a :class:`~wx.lib.agw.aui.auibar.AuiToolBar`.

.. note::

   In order to use this functionality (and with the ``AUI_MINIMIZE_POS_TOOLBAR``
   flag set), the instance of :class:`AuiPaneInfo` you pass as an input **must** have a real
   name and not the randomly generated one. Remember to set the :meth:`Name` property of
   the toolbar pane before calling this method.

Sets the minimum size of the pane.

a :class:`wx.Size` object, then :meth:`~AuiPaneInfo.MinSize1` is called. Otherwise, :meth:`~AuiPaneInfo.MinSize2` is called.

:param `arg1`: a :class:`wx.Size` object, a (x, y) tuple or or a `x` coordinate.

:see: :meth:`MinSize` for an explanation of input parameters.

Indicates whether a pane can be moved.

:param bool `b`: whether the pane can be moved or not.

Sets the name of the pane so it can be referenced in lookup functions.

If a name is not specified by the user, a random name is assigned to the pane
when it is added to the manager.

:param `name`: a string specifying the pane name.

   If you are using :meth:`AuiManager.SavePerspective` and :meth:`AuiManager.LoadPerspective`,
   you will have to specify a name for your pane using :meth:`~AuiPaneInfo.Name`, as perspectives
   containing randomly generated names can not be properly restored.

Forces a pane to be a notebook control (:class:`~wx.lib.agw.aui.auibook.AuiNotebook`).

:param integer `id`: the notebook id.

Indicates whether a pane can be docked in an automatic :class:`~wx.lib.agw.aui.auibook.AuiNotebook`.

:param bool `b`: whether the pane can be docked in a notebook or not.

Forces a pane to be a notebook page, so that the pane can be
docked on top to another to create a :class:`~wx.lib.agw.aui.auibook.AuiNotebook`.

:param integer `id`: the notebook id;
:param integer `tab_position`: the tab number of the pane once docked in a notebook.

Indicates that a border should be drawn for the pane.

:param bool `visible`: whether the pane border should be visible or not.

Indicates that a pin button should be drawn for the pane.

:param bool `visible`: whether the pin button should be visible or not.

Determines the position of the docked pane.

:param integer `pos`: the position of the docked pane.

Resets all the buttons and recreates them from scratch depending on the
:class:`AuiManager` flags.

Allows a pane to be resizable if `resizable` is ``True``, and forces
it to be a fixed size if `resizeable` is ``False``.

If `resizable` is ``False``, this is simply an antonym for :meth:`Fixed`.

:param bool `resizable`: whether the pane will be resizeable or not.

Sets the pane dock position to the right side of the frame.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_RIGHT`` as

Indicates whether a pane can be docked on the right of the frame.

:param bool `b`: whether the pane can be docked at the right or not.

Indicates whether a pane can be snapped on the right of the main frame.

:param bool `b`: whether the pane can be snapped at the right of the main frame or not.

Determines the row of the docked pane.

:param integer `row`: the row of the docked pane.

Copies the `source` pane members that pertain to docking position to `self`.

:param `source`: the source pane from where to copy the attributes,
 an instance of :class:`AuiPaneInfo`.

Turns the property given by `flag` on or off with the `option_state`
parameter.

:param integer `flag`: the property to set;
:param bool `option_state`: either ``True`` or ``False``.

Sets the pane name once docked in a :class:`~wx.lib.agw.aui.auibook.AuiNotebook` using the notebook id. 

Indicates that a pane should be shown.

:param bool `show`: whether the pane should be shown or not.

Indicates whether a pane can be snapped on the main frame. This is
equivalent as calling :meth:`TopSnappable` . :meth:`BottomSnappable` . :meth:`LeftSnappable` . :meth:`RightSnappable` .

Specifies that the pane should adopt the default toolbar pane settings. 

Sets the pane dock position to the top of the frame.

:note: This is the same thing as calling :meth:`~AuiPaneInfo.Direction` with ``AUI_DOCK_TOP`` as

Indicates whether a pane can be docked at the top of the frame.

:param bool `b`: whether the pane can be docked at the top or not.

Indicates whether a pane can be snapped at the top of the main frame.

:param bool `b`: whether the pane can be snapped at the top of the main frame or not.

Makes the pane transparent when floating.

:param integer `alpha`: a value between 0 and 255 for pane transparency.

Associate a :class:`wx.Window` derived window to this pane.

This normally does not need to be specified, as the window pointer is
automatically assigned to the :class:`AuiPaneInfo` structure as soon as it is
added to the manager.

:param `w`: a :class:`wx.Window` derived window.

A docking guide window for single docking hint (not diamond-shaped HUD). 

:param integer `direction`: one of ``wx.TOP``, ``wx.BOTTOM``, ``wx.LEFT``, ``wx.RIGHT``.

Moves the docking window to the new position. Overridden in children classes.

Creates the docking guide window shape based on which docking bitmaps are used.

:param bool `useWhidbey`: if ``True``, use Whidbey-style bitmaps; if ``False``, use the
 Aero-style bitmaps.
 
Checks if the mouse position is inside the target window rect.

outside.

Static function which returns if the input `manager` should have "live resize"
behaviour.

.. note::

   This method always returns ``True`` on wxMAC as this platform doesn't have
   the ability to use :class:`ScreenDC` to draw sashes.

Static function which returns if the input `manager` should use native :class:`MiniFrame` as
floating panes.

.. note::

   the ability to use custom drawn miniframes.

Checks on which edge of a window the drop action has taken place.

:param `window`: a :class:`wx.Window` derived window;
:param `docks`: a list of :class:`AuiDockInfo` structures;
:param `pt`: a :class:`wx.Point` object.

Checks if a point is outside the window rectangle.

This utility function creates shallow copies of
the dock and pane info. :class:`AuiManager` usually contain pointers
to :class:`AuiPaneInfo` classes, thus this function is necessary to reliably
reconstruct that relationship in the new dock info and pane info arrays.

:param `src_docks`: a list of :class:`AuiDockInfo` classes;
:param `src_panes`: a list of :class:`AuiPaneInfo` classes.

This utility function creates full copies of

This is an internal function that inserts a new dock
layer by incrementing all existing dock layer values by one.

:param `panes`: a list of :class:`AuiPaneInfo`;
:param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
:param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze.

row by incrementing all existing dock row values by one.

:param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze;
:param integer `dock_row`: the :class:`AuiDockInfo` row to analyze.

This is an internal function that inserts a new pane
by incrementing all existing dock position values by one.

:param integer `dock_row`: the :class:`AuiDockInfo` row to analyze;
:param integer `dock_pos`: the :class:`AuiDockInfo` position to analyze.

DoInsertPane(panes, dock_direction, dock_layer, dock_row, dock_pos)

Draws a resize hint while a sash is dragged.

:param wx.Rect `rect`: a rectangle which specifies the sash dimensions.

Changes ``;`` into ``\`` and ``|`` into ``|\`` in the input string.

:param string `s`: the string to be analyzed.

:note: This is an internal functions which is used for saving perspectives.

This is an internal function that returns a list of docks which meet
the specified conditions in the parameters and returns a sorted array
(sorted by layer and then row).

:param `docks`: a list of :class:`AuiDockInfo`;

FindDocks(docks, dock_direction, dock_layer=-1, dock_row=-1, reverse=False)

This is an internal function that returns a list of docks
which is related to the opposite direction.

This method looks up a specified window pointer inside a dock.
If found, the corresponding :class:`AuiDockInfo` pointer is returned, otherwise ``None``.

:param `dock`: a :class:`AuiDockInfo` structure;
:param wx.Window `window`: the window associated to the pane we are seeking.

Returns the window rectangle excluding toolbars.

:param `docks`: a list of :class:`AuiDockInfo` structures.

This function will return the aui manager for a given window.

:param wx.Window `window`: this parameter should be any child window or grand-child
 window (and so on) of the frame/window managed by :class:`AuiManager`. The window
 does not need to be managed by the manager itself, nor does it even need
 to be a child or sub-child of a managed window. It must however be inside
 the window hierarchy underneath the managed window.

This is an internal function which returns
the highest layer inside the specified dock.

:param `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze.

Returns the :class:`~wx.lib.agw.aui.auibook.AuiNotebook` which has the specified `notebook_id`.

:param integer `notebook_id`: the target notebook id.

Returns the toolbar dock offsets (top-left and bottom-right).

:param `docks`: a list of :class:`AuiDockInfo` to analyze.

Returns whether `pane1` and `pane2` are in a different docking position
based on pane status, docking direction, docking layer and docking row.

:param `pane1`: a :class:`AuiPaneInfo` instance;
:param `pane2`: another :class:`AuiPaneInfo` instance.

This function is used to sort panes by dock position.

:param `p1`: the first pane instance to compare, an instance of :class:`AuiPaneInfo`;
:param `p2`: the second pane instance to compare, an instance of :class:`AuiPaneInfo`.

Refreshes the docking guide windows.

:param `guides`: a list of :class:`AuiDockingGuide` classes;

Removes a pane window from all docks
with a possible exception specified by parameter `exc`.

:param `pane`: the pane to be removed, an instance of :class:`AuiPaneInfo`;
:param `exc`: the possible pane exception, an instance of :class:`AuiPaneInfo`.

Takes a dock and assigns sequential numbers
to existing rows.  Basically it takes out the gaps so if a
dock has rows with numbers 0, 2, 5, they will become 0, 1, 2.

Sets the active pane, as well as cycles through
every other pane and makes sure that all others' active flags
are turned off.

:param `panes`: a list of :class:`AuiPaneInfo` structures;
:param `active_pane`: the pane to be made active (if found), an instance of :class:`AuiPaneInfo`.

Shows or hide the docking guide windows.

:param bool `show`: whether to show or hide the docking guide windows.

<wx.lib.agw.aui.framemanager.AuiPaneInfo object at 0x7fe26aa52110>

Tab art provider code - a tab provider provides all drawing functionality to
the :class:`~wx.lib.agw.aui.auibook.AuiNotebook`. This allows the
:class:`~wx.lib.agw.aui.auibook.AuiNotebook` to have a pluggable look-and-feel.

By default, a :class:`~wx.lib.agw.aui.auibook.AuiNotebook` uses an instance of this class
called :class:`AuiDefaultTabArt` which provides bitmap art and a colour scheme that is
adapted to the major platforms' look. You can either derive from that class to alter its
behaviour or write a completely new tab art class.
Call :meth:`AuiNotebook.SetArtProvider() <lib.agw.aui.auibook.AuiNotebook.SetArtProvider>`
to make use this new tab art.

# Name:         tabart.py
# Purpose:
#
#
# Created:
# Version:

 1. If the object is disabled (via a call to :meth:`EvtHandler.SetEvtHandlerEnabled`) the function

Tab art provider code - a tab provider provides all drawing functionality to the :class:`~wx.lib.agw.aui.auibook.AuiNotebook`.
This allows the :class:`~wx.lib.agw.aui.auibook.AuiNotebook` to have a pluggable look-and-feel.

By default, a :class:`~wx.lib.agw.aui.auibook.AuiNotebook` uses an instance of this class called
:class:`AuiDefaultTabArt` which provides bitmap art and a colour scheme that is adapted to the major platforms'
completely new tab art class. Call :meth:`AuiNotebook.SetArtProvider() <lib.agw.aui.auibook.AuiNotebook.SetArtProvider>` to make use this
new tab art.

Draws the tab area background.

:param `wnd`: a :class:`wx.Window` instance object;
:param wx.Rect `rect`: the tab control rectangle.

Draws a button on the tab or on the tab area, depending on the button identifier.

:param wx.Rect `in_rect`: rectangle the tab should be confined to;
:param `button`: an instance of the button class;
:param integer `orientation`: the tab orientation.

Draws the focus rectangle on a tab.

:param `page`: the page associated with the tab;
:param string `draw_text`: the text that has been drawn on the tab;
:param integer `text_offset`: the text offset on the tab;
:param integer `bitmap_offset`: the bitmap offset on the tab;
:param integer `drawn_tab_yoff`: the y offset of the tab text;
:param integer `drawn_tab_height`: the height of the tab;
:param integer `textx`: the x text extent;
:param integer `texty`: the y text extent.

DrawFocusRectangle(self, dc, page, wnd, draw_text, text_offset, bitmap_offset, drawn_tab_yoff, drawn_tab_height, textx, texty)

Draws a single tab.

:param `page`: the tab control page associated with the tab;
:param integer `close_button_state`: the state of the close button on the tab;
:param bool `paint_control`: whether to draw the control inside a tab (if any) on a :class:`MemoryDC`.

DrawTab(self, dc, wnd, page, in_rect, close_button_state, paint_control=False)

:see: :meth:`~AuiDefaultTabArt.SetAGWFlags` for a list of possible return values.

Returns the best tab control size.

:param list `pages`: the pages associated with the tabs;
:param wx.Size `required_bmp_size`: the size of the bitmap on the tabs.

Returns the tab size for the given caption, bitmap and button state.

:param string `caption`: the tab text caption;
:param wx.Bitmap `bitmap`: the bitmap displayed on the tab;
:param bool `active`: whether the tab is selected or not;
:param wx.Window `control`: a :class:`wx.Window` instance inside a tab (or ``None``).

GetTabSize(self, dc, wnd, caption, bitmap, active, close_button_state, control=None)

Sets a new base colour.

:param `base_colour`: an instance of :class:`wx.Colour`.

Sets a custom bitmap for the close, left, right and window list buttons.

:param integer `bitmap_id`: the button identifier;
:param integer `button_state`: the button state;
:param wx.Bitmap `bmp`: the custom bitmap to use for the button.

:param wx.Font `font`: the new font to use to measure tab labels text extents.

Sets the tab sizing information.

:param wx.Size `tab_ctrl_size`: the size of the tab control area;
:param integer `tab_count`: the number of tabs;
:param tuple `minMaxTabWidth`: a tuple containing the minimum and maximum tab widths
 to be used when the ``AUI_NB_TAB_FIXED_WIDTH`` style is active.

Shows the drop-down window menu on the tab area.

:param `wnd`: a :class:`wx.Window` derived window instance;
:param integer `active_idx`: the active tab index.

Convenience method to draw tab buttons.

:param wx.Rect `_rect`: the tab rectangle;
:param wx.Bitmap `bmp`: the tab bitmap;
:param wx.Colour `bkcolour`: the tab background colour;
:param integer `button_state`: the state of the tab button.

:see: :meth:`~AuiSimpleTabArt.SetAGWFlags` for a list of possible return values.

 ``AUI_NB_TAB_FLOAT``                 Allows the floating of single tabs. Known limitation: when the notebook is more or less full
                                      screen, tabs cannot be dragged far enough outside of the notebook to become floating pages

A class to draw tabs using the Google Chrome browser style.
It uses custom bitmap to render the tabs, so that the look and feel is as close
as possible to the Chrome style.

:note: Overridden from :class:`AuiDefaultTabArt`.

Assigns the tab custom bitmaps

:param bool `mirror`: whether to vertically mirror the bitmap or not.

Draws the tab background for the Firefox 2 style.
This is more consistent with :class:`~wx.lib.agw.flatnotebook.FlatNotebook` than before.

:param wx.Rect `rect`: rectangle the tab should be confined to;
:param bool `focus`: whether the tab has focus or not;
:param bool `upperTabs`: whether the style is ``AUI_NB_TOP`` or ``AUI_NB_BOTTOM``.

GetTabSize(self, dc, wnd, caption, bitmap, active, close_button_state, control)

A class to draw tabs using the Visual Studio 2003 (VC71) style. 

Fills the tab with the Visual Studio 2005 gradient background.

:param list `tabPoints`: a list of :class:`wx.Point` objects describing the tab shape;
:param bool `active`: whether the tab is selected or not.

# Name:         auimdi.py
# Purpose:
#
#
# Created:
# Version:
# Tags:         phoenix-port, documented

Panel()
Panel(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=TAB_TRAVERSAL, name=PanelNameStr)

A panel is a window on which controls are placed.

__init__(self, parent, id=wx.ID_ANY, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="AuiMDIChildFrame")

IsTopLevel() -> bool

Returns true if the given window is a top-level one.

Frame()
Frame(parent, id=ID_ANY, title=EmptyString, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_FRAME_STYLE, name=FrameNameStr)

A frame is a window whose size and position can (usually) be changed
by the user.

__init__(self, parent, id=wx.ID_ANY, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE|wx.VSCROLL|wx.HSCROLL, name="AuiMDIParentFrame")

SetMenuBar(menuBar)

Tells the frame to show the given menu bar.

Persistent objects are simply the objects which automatically save their state
when they are destroyed and restore it when they are recreated, even during
another program invocation.

.. _persistent-overview:

Persistent Object Overview
==========================

Most often, persistent objects are, in fact, persistent windows as it is especially
convenient to automatically restore the UI state when the program is restarted but
an object of any class can be made persistent. Moreover, persistence is implemented
in a non-intrusive way so that the original object class doesn't need to be modified
at all in order to add support for saving and restoring its properties.

The persistence framework involves:

* **PersistenceManager** which all persistent objects register themselves with. This class
  handles actual saving and restoring of persistent data as well as various global
  aspects of persistence, e.g. it can be used to disable restoring the saved data;
* **PersistentObject** is the base class for all persistent objects or, rather, adaptors
  for the persistent objects as this class main purpose is to provide the bridge between
  the original class -- which has no special persistence support -- and PersistenceManager;
* **PersistentHandlers** which handle different kind of saving/restoring actions depending
  on the widget kind.

Using Persistent Windows
========================

wxPython has built-in support for a (constantly growing) number of controls. Currently the
following classes are supported:

* wx.TopLevelWindow (and hence wx.Frame and wx.Dialog, together with their own AUI perspectives);
* wx.MenuBar, FlatMenuBar;
* AuiToolBar;
* wx.Notebook, wx.Toolbook, wx.Treebook, wx.Choicebook, AuiNotebook (together with its own AUI perspective),
  FlatNotebook, LabelBook, FlatImageBook;
* wx.CheckBox;
* wx.ListBox, wx.VListBox, wx.HtmlListBox, wx.SimpleHtmlListBox, wx.adv.EditableListBox;
* wx.ListCtrl, wx.ListView, UltimateListCtrl;
* wx.CheckListBox;
* wx.Choice, wx.ComboBox, wx.adv.OwnerDrawnComboBox;
* wx.RadioBox;
* wx.RadioButton;
* wx.ScrolledWindow, wx.lib.scrolledpanel.ScrolledPanel;
* wx.Slider, KnobCtrl;
* wx.SpinButton, wx.SpinCtrl, FloatSpin;
* wx.SplitterWindow;
* wx.TextCtrl, wx.SearchCtrl, wx.lib.expando.ExpandoTextCtrl, wx.lib.masked.Ctrl;
* wx.ToggleButton, wx.lib.buttons.GenToggleButton, wx.lib.buttons.GenBitmapToggleButton,
  wx.lib.buttons.GenBitmapTextToggleButton, SToggleButton,
  SBitmapToggleButton, SBitmapTextToggleButton;
* wx.TreeCtrl, wx.GenericDirCtrl, CustomTreeCtrl;
* HyperTreeList;
* wx.lib.calendar.CalendarCtrl, wx.adv.CalendarCtrl;
* wx.CollapsiblePane, PyCollapsiblePane;
* wx.adv.DatePickerCtrl, wx.adv.GenericDatePickerCtrl;
* wx.media.MediaCtrl;
* wx.ColourPickerCtrl, wx.lib.colourselect.ColourSelect;
* wx.FilePickerCtrl, wx.DirPickerCtrl;
* wx.FontPickerCtrl;
* wx.FileHistory;
* wx.DirDialog, wx.FileDialog;
* wx.FindReplaceDialog;
* wx.FontDialog;
* wx.ColourDialog, CubeColourDialog;
* FoldPanelBar;
* wx.SingleChoiceDialog, wx.MultiChoiceDialog;
* wx.TextEntryDialog, wx.PasswordEntryDialog.

To automatically save and restore the properties of the windows of classes listed
above you need to:

* Set a unique name for the window using `SetName()`: this step is important as the
  name is used in the configuration file and so must be unique among all windows of
  the same class;
* Call `PersistenceManager.Register(window)` at any moment after creating the window
  and then `PersistenceManager.Restore(window)` when the settings may be restored
  (which can't be always done immediately, e.g. often the window needs to be populated
  first). If settings can be restored immediately after the window creation, as is often
  the case for wx.TopLevelWindow, for example, then `PersistenceManager.RegisterAndRestore(window)`
  can be used to do both at once.
* If you want the settings for the window to be saved when your main frame is destroyed (or your app closes), simply call
  `PersistenceManager.SaveAndUnregister(window)` with no arguments.

Usage
=====

Example of using a notebook control which automatically remembers the last open page::

    import wx, os
    import wx.lib.agw.persist as PM

        def __init__(self, parent):

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

            self.book = wx.Notebook(self, wx.ID_ANY)

            # Very important step!!
            self.book.SetName("MyBook") # Do not use the default name!!

            self.book.AddPage(wx.Panel(self.book), "Hello")
            self.book.AddPage(wx.Panel(self.book), "World")

            self._persistMgr = PM.PersistenceManager.Get()

            _configFile = os.path.join(os.getcwd(), self.book.GetName())
            self._persistMgr.SetPersistenceFile(_configFile)

            if not self._persistMgr.RegisterAndRestoreAll(self.book):
                # Nothing was restored, so choose the default page ourselves
                self.book.SetSelection(0)

            self._persistMgr.SaveAndUnregister(self.book)

.. _persistent-windows:

Defining Custom Persistent Windows
==================================

User-defined classes can be easily integrated with PersistenceManager. To add support
for your custom class MyWidget you just need to:

* Define a MyWidgetHandler class inheriting from `AbstractHandler`;
* Implement its `GetKind()` method returning a unique string identifying all MyWidget
  objects, typically something like "widget";
* Implement its `Save()` and `Restore()` methods to actually save and restore the widget
  settings using `PersistentObject.SaveValue()` and `PersistentObject.RestoreValue()` methods.

If you want to add persistence support for a class not deriving from wx.Window, you need
to derive MyPersistentWidget directly from PersistentObject and so implement its
`PersistentObject.GetName()` method too. Additionally, you must ensure that
`PersistenceManager.SaveAndUnregister()` is called when your object is destroyed as this
can be only done automatically for windows.

TODOs
=====

* Find a way to handle :class:`ToolBar` UI settings as it has been done for :class:`~wx.lib.agw.aui.auibar.AuiToolBar`:
  current :class:`ToolBar` doesn't seem to have easy access to the underlying toolbar tools;
* Implement handler(s) for :class:`grid.Grid` for row/columns sizes (possibly adding another style
  to `PersistenceManager` as :class:`grid.Grid` sets up arrays to store individual row and column
  sizes when non-default sizes are used. The memory requirements for this could become prohibitive
  if the grid is very large);
* Find a way to properly save and restore dialog data (:class:`wx.ColourDialog`, :class:`wx.FontDialog` etc...);
* Add handlers for the remaining widgets not yet wrapped (mostly in :mod:`lib`).

`PersistentObjects` library is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 27 Mar 2013, 21.00 GMT
Version 0.5.

This module contains all the constants used by the persistent objects.

#
#

['widget', 'wxSpinButton', 'auiFloating', 'AuiTabCtrl', 'maskedTextCtrl', 'numctrl', 'IpAddrCtrl', 'masked.num', 'time', 'scrolledpanel', 'cPanel', 'wxdataviewctrlmainwindow', 'button', 'check', 'choice', 'collapsibleHeader', 'collapsiblePane', 'colourpicker', 'colourpickerwidget', 'comboBox', 'control', 'dialog', 'wxDirCtrl', 'dirpicker', 'dirpickerwidget', 'wxfilectrl', 'filedlg', 'filepicker', 'filepickerwidget', 'fontpicker', 'fontpickerwidget', 'frame', 'gauge', 'wxHeaderCtrl', 'listBox', 'listCtrl', 'notebook', 'panel', 'radioBox', 'radioButton', 'wxRearrangeDlg', 'wxRearrangeList', 'scrollBar', 'searchCtrl', 'slider', 'staticBitmap', 'groupBox', 'staticLine', 'staticText', 'statusBar', 'text', 'toolbar', 'treeCtrl', 'wxVListBox', 'dataviewCtrl', 'wxTreeListCtrl']

This module contains different classes which handle different kind of saving/restoring
actions depending on the widget kind.

Base class for persistent windows, uses the window name as persistent name by
default and automatically reacts to the window destruction.

.. note::

   This is an abstract class. If you wish to add another (custom) handler
   for your widgets, you should derive from :class:`AbstractHandler` and override
   the :meth:`Save() <AbstractHandler.Save>`,
   :meth:`Restore() <AbstractHandler.Restore>` and
   :meth:`GetKind() <AbstractHandler.GetKind>` methods.

:param `pObject`: a :class:`~wx.lib.agw.persist.persistencemanager.PersistentObject` containing information about the
 persistent widget.

Returns a short and meaningful *string* description of your widget.

:note: This method must be overridden in derived classes.

Restores the widget's settings by calling :meth:`PersistentObject.RestoreValue() <lib.agw.persist.persistencemanager.PersistentObject.RestoreValue>`, which in
turns calls :meth:`PersistenceManager.RestoreValue() <lib.agw.persist.persistencemanager.PersistenceManager.RestoreValue>`.

Saves the widget's settings by calling :meth:`PersistentObject.SaveValue() <lib.agw.persist.persistencemanager.PersistentObject.SaveValue>`, which in
turns calls :meth:`PersistenceManager.SaveValue() <lib.agw.persist.persistencemanager.PersistenceManager.SaveValue>`.

Supports saving/restoring :class:`lib.agw.aui.framemanager.AuiManager` perspectives.

Supports saving/restoring book control selection.

This class handles the following wxPython widgets:

- :class:`Toolbook`;
- :class:`Choicebook`;
- :class:`Listbook`;
- :class:`Treebook` (except for opened tree branches, see :class:`TreebookHandler` for this);
- :class:`Notebook`;
- :class:`lib.agw.aui.auibook.AuiNotebook`;
- :class:`lib.agw.flatnotebook.FlatNotebook`;
- :class:`lib.agw.labelbook.LabelBook`;
- :class:`lib.agw.labelbook.FlatImageBook`.

Supports saving/restoring a :class:`adv.CalendarCtrl` date.

- :class:`adv.CalendarCtrl`.

Supports saving/restoring a :class:`CheckBox` state.

- :class:`CheckBox`.

Supports saving/restoring checked and selected items in :class:`CheckListBox`.

- :class:`CheckListBox` (only for checked items. For selected items see :class:`ListBoxHandler`).

Supports saving/restoring :class:`Choice`, :class:`ComboBox` and :class:`adv.OwnerDrawnComboBox`
selection.

- :class:`Choice`;
- :class:`ComboBox`;
- :class:`adv.OwnerDrawnComboBox`.

Supports saving/restoring a :class:`MultiChoiceDialog` / :class:`SingleChoiceDialog` choices.

- :class:`SingleChoiceDialog`;
- :class:`MultiChoiceDialog`.

Supports saving/restoring a :class:`CollapsiblePane` / :class:`lib.agw.pycollapsiblepane.PyCollapsiblePane` state.

- :class:`CollapsiblePane`;
- :class:`lib.agw.pycollapsiblepane.PyCollapsiblePane`.

Supports saving/restoring a :class:`wx.ColourDialog` data (colour, custom colours and full
choice in the dialog).

- :class:`wx.ColourDialog`;
- :class:`lib.agw.cubecolourdialog.CubeColourDialog`.

.. todo:: Find a way to properly save and restore dialog data (:class:`wx.ColourDialog`, :class:`wx.FontDialog` etc...).

Supports saving/restoring a :class:`wx.ColourPickerCtrl` / :class:`lib.colourselect.ColourSelect` colour.

- :class:`wx.ColourPickerCtrl`;
- :class:`lib.colourselect.ColourSelect`.

Supports saving/restoring a :class:`adv.DatePickerCtrl` date.

- :class:`~adv.DatePickerCtrl`.

Supports saving/restoring a :class:`DirDialog` / :class:`FileDialog` path.

- :class:`DirDialog`;
- :class:`FileDialog`.

Supports saving/restoring a :class:`FilePickerCtrl` / :class:`DirPickerCtrl` path.

- :class:`FilePickerCtrl`;
- :class:`DirPickerCtrl`.

Supports saving/restoring a :class:`FileHistory` list of file names.

- :class:`FileHistory`.

Supports saving/restoring a :class:`FindReplaceDialog` data (search string, replace string
and flags).

- :class:`FindReplaceDialog`.

Supports saving/restoring of :class:`lib.agw.foldpanelbar.FoldPanelBar`.

This class handles the following wxPython widgets

- :class:`lib.agw.foldpanelbar.FoldPanelBar`

Supports saving/restoring a :class:`wx.FontDialog` data (effects, symbols, colour, font, help).

- :class:`wx.FontDialog`.

Supports saving/restoring a :class:`wx.FontPickerCtrl` font.

- :class:`wx.FontPickerCtrl`.

Supports saving/restoring selected items in :class:`ListBox`, :class:`ListCtrl`, :class:`ListView`,
:class:`VListBox`, :class:`html.HtmlListBox`, :class:`html.SimpleHtmlListBox`, :class:`adv.EditableListBox`.

- :class:`ListBox`;
- :class:`ListCtrl` (only for selected items. For column sizes see :class:`ListCtrlHandler`);
- :class:`ListView` (only for selected items. For column sizes see :class:`ListCtrlHandler`);
- :class:`VListBox`;
- :class:`html.HtmlListBox`;
- :class:`html.SimpleHtmlListBox`;
- :class:`adv.EditableListBox`.

Returns a list of selected items for :class:`ListBox`, :class:`ListCtrl`, :class:`ListView`,

:param `listBox`: an instance of :class:`ListBox`, :class:`ListCtrl`, :class:`ListView`,
 :class:`VListBox`, :class:`html.HtmlListBox`, :class:`html.SimpleHtmlListBox`, :class:`adv.EditableListBox`..

Supports saving/restoring selected items and column sizes in :class:`ListCtrl`.

- :class:`ListCtrl` (only for column sizes. For selected items see :class:`ListBoxHandler`);
- :class:`ListView` (only for column sizes. For selected items see :class:`ListBoxHandler`).

Supports saving/restoring a :class:`media.MediaCtrl` movie position, volume and playback
rate.

- :class:`media.MediaCtrl`.

Supports saving/restoring the :class:`wx.MenuBar` and :class:`lib.agw.flatmenu.FlatMenuBar` items state.

- :class:`wx.MenuBar`;
- :class:`lib.agw.flatmenu.FlatMenuBar`.

Supports saving/restoring a :class:`RadioBox` state.

- :class:`RadioBox`.

Supports saving/restoring a :class:`RadioButton` state.

- :class:`RadioButton`.

Supports saving/restoring a :class:`ScrolledWindow` / :class:`lib.scrolledpanel.ScrolledPanel`
scroll position.

- :class:`ScrolledWindow`;
- :class:`lib.scrolledpanel.ScrolledPanel`.

Supports saving/restoring a :class:`Slider` / :class:`lib.agw.knobctrl.KnobCtrl` thumb position.

- :class:`Slider`;
- :class:`lib.agw.knobctrl.KnobCtrl`.

Supports saving/restoring a :class:`SpinButton` / :class:`SpinCtrl` value.

- :class:`SpinCtrl`;
- :class:`SpinButton`.

Supports saving/restoring a :class:`SplitterWindow` splitter position.

- :class:`SplitterWindow`.

Supports saving/restoring a :class:`TextCtrl` entered string.

- :class:`TextCtrl`;
- :class:`SearchCtrl`;
- :class:`lib.expando.ExpandoTextCtrl`;
- :class:`lib.masked.textctrl.TextCtrl`;
- :class:`lib.masked.combobox.ComboBox`;
- :class:`lib.masked.ipaddrctrl.IpAddrCtrl`;
- :class:`lib.masked.timectrl.TimeCtrl`;
- :class:`lib.masked.numctrl.NumCtrl`;

Supports saving/restoring a :class:`TextEntryDialog` string.

- :class:`TextEntryDialog`;
- :class:`PasswordEntryDialog`.

Supports saving/restoring window position and size as well as
maximized/iconized/restore state for toplevel windows.

- All :class:`wx.Frame` derived classes;
- All :class:`Dialog` derived classes.

|

In addition, if the toplevel window has an associated AuiManager (whether it is
:class:`~wx.lib.agw.aui.framemanager.AuiManager`) and
:class:`~wx.lib.agw.persist.persistencemanager.PersistenceManager`
has the ``PM_SAVE_RESTORE_AUI_PERSPECTIVES`` style set (the default), this class
will also save and restore AUI perspectives using the underlying :class:`AUIHandler`
class.

Supports saving/restoring a :class:`ToggleButton` and friends state.

- :class:`ToggleButton`;
- :class:`lib.buttons.GenToggleButton`;
- :class:`lib.buttons.GenBitmapToggleButton`;
- :class:`lib.buttons.GenBitmapTextToggleButton`;
- :class:`lib.agw.shapedbutton.SToggleButton`;
- :class:`lib.agw.shapedbutton.SBitmapToggleButton`;
- :class:`lib.agw.shapedbutton.SBitmapTextToggleButton`.

Supports saving/restoring the :class:`lib.agw.aui.auibar.AuiToolBar` items state.

- :class:`lib.agw.aui.auibar.AuiToolBar`.

.. todo::

   Find a way to handle :class:`ToolBar` UI settings as it has been done for
   :class:`lib.agw.aui.auibar.AuiToolBar`: currently :class:`ToolBar` doesn't seem
   to have easy access to the underlying toolbar tools.

Supports saving/restoring open tree branches.

- :class:`Treebook` (except for page selection, see :class:`BookHandler` for this).

Supports saving/restoring a :class:`TreeCtrl` expansion state, selections and
checked items state (meaningful only for :class:`lib.agw.customtreectrl.CustomTreeCtrl`).

- :class:`TreeCtrl`;
- :class:`GenericDirCtrl`;
- :class:`lib.agw.customtreectrl.CustomTreeCtrl`;
- :class:`lib.agw.hypertreelist.HyperTreeList`;

Returns a list of checked items. Checked items are coded as determined by
the result of :meth:`TreeCtrlHandler.GetItemIdentity() <TreeCtrlHandler.GetItemIdentity>`.

:note:

 This is meaningful only for :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` and
 :class:`~wx.lib.agw.hypertreelist.HyperTreeList`.

Returns the checked/unchecked state of the children of a tree item.

:param `item`: a :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` item.

Returns the checked/unchecked state of a tree item.

Returns list of expanded items. Expanded items are coded as determined by

Returns the expansion state of the children of a tree item.

:param `item`: a :class:`TreeCtrl` item or a :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` item.

Returns the expansion state of a tree item.

Return the index of item.

:param `item`: a :class:`TreeCtrl` item or a :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` item;

Return the children of item as a list.

:param `recursively`: whether to recurse into the item hierarchy or not.

Return a hashable object that represents the identity of the
item. By default this returns the position of the item in the
tree. You may want to override this to return the item label
(if you know that labels are unique and don't change), or return
something that represents the underlying domain object, e.g.
a database key.

Returns a list of selected items. Selected items are coded as determined by

Returns the selection state of the children of a tree item.

Returns the selection state of a tree item.

Checks all tree items whose identity, as determined by :meth:`TreeCtrlHandler.GetItemIdentity() <TreeCtrlHandler.GetItemIdentity>`, is present
in the list and unchecks all other tree items.

:param `listOfCheckedItems`: a list of checked :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` items.

:note:

Sets the checked/unchecked state of the children of a tree item.

:param `listOfCheckedItems`: a list of checked :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` items;

Sets the checked/unchecked state of a tree item.

Expands all tree items whose identity, as determined by :meth:`TreeCtrlHandler.GetItemIdentity() <TreeCtrlHandler.GetItemIdentity>`,
is present in the list and collapses all other tree items.

:param `listOfExpandedItems`: a list of expanded :class:`TreeCtrl` or
 :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` items.

Sets the expansion state of the children of a tree item (expanded or collapsed).

 :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` items;

Sets the expansion state of a tree item (expanded or collapsed).

Sets the selection state of the children of a tree item.

:param `listOfSelectedItems`: a list of selected :class:`TreeCtrl` or

Sets the selection state of a tree item.

Selects all tree items whose identity, as determined by :meth:`TreeCtrlHandler.GetItemIdentity() <TreeCtrlHandler.GetItemIdentity>`,
is present in the list and unselects all other tree items.

Supports saving/restoring a :class:`lib.agw.hypertreelist.HyperTreeList` expansion state,
selections, column widths and checked items state (meaningful only for :class:`~wx.lib.agw.hypertreelist.HyperTreeList`).

- :class:`lib.agw.hypertreelist.HyperTreeList`.

Creates a tuple of 7 :class:`wx.Font` attributes from the `font` input parameter.

:param `font`: a :class:`wx.Font` instance.

:returns: A tuple of 7 :class:`wx.Font` attributes from the `font` input parameter.

Finds a suitable handler for the input `Persistent Object` depending on the
widget kind.

:param `pObject`: an instance of :class:`~wx.lib.agw.persist.persistencemanager.PersistentObject` class.

Is there a suitable handler for this control

:param `control`: the control instance to check if a handler for it exists.

Transforms a datetime.date object into a :class:`DateTime` one.

:param `date`: a `datetime.date` object.

Transforms a :class:`DateTime` object into a `datetime.date` one.

:param date: a :class:`DateTime` object.

[('BookHandler', (<class 'wx._core.BookCtrlBase'>, <class 'wx.lib.agw.aui.auibook.AuiNotebook'>, <class 'wx.lib.agw.flatnotebook.FlatNotebook'>, <class 'wx.lib.agw.labelbook.LabelBook'>, <class 'wx.lib.agw.labelbook.FlatImageBook'>)), ('TLWHandler', (<class 'wx._core.TopLevelWindow'>,)), ('CheckBoxHandler', (<class 'wx._core.CheckBox'>,)), ('TreeCtrlHandler', (<class 'wx._core.TreeCtrl'>, <class 'wx._core.GenericDirCtrl'>, <class 'wx.lib.agw.customtreectrl.CustomTreeCtrl'>, <class 'wx._dataview.TreeListCtrl'>)), ('MenuBarHandler', (<class 'wx._core.MenuBar'>, <class 'wx.lib.agw.flatmenu.FlatMenuBar'>)), ('ToolBarHandler', (<class 'wx.lib.agw.aui.auibar.AuiToolBar'>,)), ('ListBoxHandler', (<class 'wx._core.ListBox'>, <class 'wx._core.VListBox'>, <class 'wx._html.HtmlListBox'>, <class 'wx._html.SimpleHtmlListBox'>, <class 'wx._adv.EditableListBox'>)), ('ListCtrlHandler', (<class 'wx._core.ListCtrl'>, <class 'wx._core.ListView'>)), ('ChoiceComboHandler', (<class 'wx._core.Choice'>, <class 'wx._core.ComboBox'>, <class 'wx._adv.OwnerDrawnComboBox'>)), ('RadioBoxHandler', (<class 'wx._core.RadioBox'>,)), ('RadioButtonHandler', (<class 'wx._core.RadioButton'>,)), ('ScrolledWindowHandler', (<class 'wx._core.ScrolledWindow'>, <class 'wx.lib.scrolledpanel.ScrolledPanel'>)), ('SliderHandler', (<class 'wx._core.Slider'>, <class 'wx.lib.agw.knobctrl.KnobCtrl'>)), ('SpinHandler', (<class 'wx._core.SpinButton'>, <class 'wx._core.SpinCtrl'>, <class 'wx.lib.agw.floatspin.FloatSpin'>)), ('SplitterHandler', (<class 'wx._core.SplitterWindow'>,)), ('TextCtrlHandler', (<class 'wx._core.TextCtrl'>, <class 'wx._core.SearchCtrl'>, <class 'wx.lib.expando.ExpandoTextCtrl'>, <class 'wx.lib.masked.textctrl.TextCtrl'>, <class 'wx.lib.masked.combobox.ComboBox'>, <class 'wx.lib.masked.ipaddrctrl.IpAddrCtrl'>, <class 'wx.lib.masked.timectrl.TimeCtrl'>, <class 'wx.lib.masked.numctrl.NumCtrl'>)), ('TreeListCtrlHandler', (<class 'wx.lib.agw.hypertreelist.HyperTreeList'>,)), ('CalendarCtrlHandler', (<class 'wx._adv.CalendarCtrl'>,)), ('CollapsiblePaneHandler', (<class 'wx._core.CollapsiblePane'>, <class 'wx.lib.agw.pycollapsiblepane.PyCollapsiblePane'>)), ('AUIHandler', (<class 'wx._core.Panel'>,)), ('DatePickerHandler', (<class 'wx._adv.DatePickerCtrl'>,)), ('ColourPickerHandler', (<class 'wx._core.ColourPickerCtrl'>, <class 'wx.lib.colourselect.ColourSelect'>)), ('FileDirPickerHandler', (<class 'wx._core.FilePickerCtrl'>, <class 'wx._core.DirPickerCtrl'>)), ('FontPickerHandler', (<class 'wx._core.FontPickerCtrl'>,)), ('FileHistoryHandler', (<class 'wx._core.FileHistory'>,)), ('ToggleButtonHandler', (<class 'wx._core.ToggleButton'>, <class 'wx.lib.buttons.GenToggleButton'>, <class 'wx.lib.buttons.GenBitmapToggleButton'>, <class 'wx.lib.buttons.GenBitmapTextToggleButton'>, <class 'wx.lib.agw.shapedbutton.SToggleButton'>, <class 'wx.lib.agw.shapedbutton.SBitmapToggleButton'>, <class 'wx.lib.agw.shapedbutton.SBitmapTextToggleButton'>))]

[('TreebookHandler', (<class 'wx._core.Treebook'>,)), ('CheckListBoxHandler', (<class 'wx._core.CheckListBox'>,)), ('FileDirDialogHandler', (<class 'wx._core.DirDialog'>, <class 'wx._core.FileDialog'>)), ('FindReplaceHandler', (<class 'wx._core.FindReplaceDialog'>,)), ('FontDialogHandler', (<class 'wx._core.FontDialog'>,)), ('ColourDialogHandler', (<class 'wx._core.ColourDialog'>, <class 'wx.lib.agw.cubecolourdialog.CubeColourDialog'>)), ('ChoiceDialogHandler', (<class 'wx._core.SingleChoiceDialog'>, <class 'wx._core.MultiChoiceDialog'>)), ('TextEntryHandler', (<class 'wx._core.TextEntryDialog'>, <class 'wx._core.PasswordEntryDialog'>))]

This module contains the definitions of :class:`~wx.lib.agw.persist.persitencemanager.PersistentObject`
and :class:`~wx.lib.agw.persist.persitencemanager.PersistenceManager` objects.

# PersistentControls Library wxPython IMPLEMENTATION
#
# Inspired by the wxWidgets implementation by Vadim Zeitlin.
#
# License: wxWidgets license
#
#
# Andrea Gavana, @ 16 Nov 2009
# Latest Revision: 27 Mar 2013, 21.00 GMT
#
#
#
#
#

:class:`PersistenceManager`: global aspects of persistent windows.

Provides support for automatically saving and restoring object properties
to persistent storage.

This class is the central element of wxPython persistence framework, see
the :ref:`persistent-overview` in the `__init__.py` file for its overview.

This is a singleton class and its unique instance can be retrieved using
:meth:`PersistenceManager.Get() <PersistenceManager.Get>` method.

This method should **not** be called directly: you should use the object
obtained by :meth:`PersistenceManager.Get() <PersistenceManager.Get>` and assign manager styles, custom
configuration files and custom configuration handlers using the appropriate
methods in this class.

Interesting attributes you can set for this class are:

- `configFile`: the persistent configuration file for :class:`PersistenceManager`,
  a custom file name to which :class:`FileConfig` will access to store and
  retrieve UI settings;
- `configKey`: the persistent key name inside the configuration file for
  :class:`PersistenceManager`;
- `customConfigHandler`: the persistent configuration handler for :class:`PersistenceManager`;
  this attribute is an object capable of saving/restoring UI settings. This
  can be a cPickle object or a ConfigObj one, for example.
- `style`: a combination of the following values:

  ======================================== ==================================
  Flag name                                Description
  ``PM_SAVE_RESTORE_AUI_PERSPECTIVES``     If a toplevel window has an AUI manager associated, the manager will save and restore its AUI perspective
  ``PM_SAVE_RESTORE_TREE_LIST_SELECTIONS`` If set, the manager will save items selections in list and tree controls
  ``PM_PERSIST_CONTROL_VALUE``             If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
  ``PM_DEFAULT_STYLE``                     Same as ``PM_SAVE_RESTORE_AUI_PERSPECTIVES``

:note: An individual window can also set the variable `persistValue` to
 indicate that its value should be saved/restored even so the style
 `PM_PERSIST_CONTROL_VALUE` is not set.

:note: UI settings are stored as dictionaries key <=> tuple: the tuple value
 contains two items. The first is the value *type* (i.e., float, int, bool etc...)
 while the second is the actual key value.

Adds a name to the ``BAD_DEFAULT_NAMES`` constant.

:param `name`: a string specifying the control's default name.

Globally disables restoring the persistent properties (enabled by default).

:note: By default, restoring properties in :meth:`~PersistenceManager.Restore` is enabled but this
 function allows to disable it. This is mostly useful for testing.

Globally disables saving the persistent properties (enabled by default).

:note: By default, saving properties in :meth:`~PersistenceManager.Save` is enabled but the program
 may wish to disable if, for example, it detects that it is running on a
 system which shouldn't be modified in any way and so configuration file
 (or Windows registry) shouldn't be written to.

Method used by the persistent objects to restore the data.

By default this method simply use :class:`FileConfig` but this behaviour may be
overridden by passing a custom config handler in the PersistenceManager
constructor.

:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name.

Method used by the persistent objects to save the data.

overridden by passing a custom configuration handler in the :class:`PersistenceManager`

:param `keyName`: a string specifying the key name;
:param `value`: the value to store in the configuration file.

Globally enables restoring the persistent properties (enabled by default).

Globally enables saving the persistent properties (enabled by default).

Checks if the object is registered and return the associated :class:`PersistentObject`
if it is or ``None`` otherwise.

:param `window`: an instance of :class:`wx.Window`.

Returns the persistent configuration handler for :class:`PersistenceManager`.

Returns a correctly formatted key name for the object `obj` and `keyName` parameters.

Returns the :class:`PersistenceManager` style.

:see: :meth:`~PersistenceManager.SetManagerStyle` for a list of possible styles.

Returns a default persistent option directory for :class:`PersistenceManager`.

:note: The return value of this method is not used if you are using your own
 custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc...)
 or if you have specified a custom configuration file to use with :class:`FileConfig`.

Returns the persistent configuration file for :class:`PersistenceManager`.

 custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc...).

Returns the persistent key name inside the configuration file for :class:`PersistenceManager`.

This method returns ``True`` if any of the windows managed by
:class:`PersistenceManager` has had its settings restored.

:returns: ``True`` if any window was restored, ``False`` otherwise.

.. versionadded:: 0.9.7

Register an object with the manager.

:param `persistenceHandler`: if not ``None``, this should a custom handler derived
 from :class:`~wx.lib.agw.persist.persist_handlers.AbstractHandler`.

.. note::

   Note that registering the object doesn't do anything except allowing to call
   :meth:`~PersistenceManager.Restore` for it later. If you want to register the object and restore its
   properties, use :meth:`~PersistenceManager.RegisterAndRestore`.

.. note::

   The manager takes ownership of the :class:`PersistentObject` and will delete it when
   it is unregistered.

Combines both :meth:`~PersistenceManager.Register` and :meth:`~PersistenceManager.Restore` calls.

Recursively registers and restore the state of the input `window` and of
all of its children.

:param `children`: list of children of the input `window`, on first call it is equal to ``None``.

Restores the state of an object.

:returns: ``True`` if the object properties were restored or ``False`` if nothing
 was found to restore or the saved settings were invalid.

:note: This methods does nothing if :meth:`~PersistenceManager.DisableRestoring` was called.

Recursively restore the state of the input `window` and of

Check if we should restore the widget value, if so pass it to :meth:`~PersistenceManager.DoRestoreValue`,
this method checks the style `PM_PERSIST_CONTROL_VALUE` and if if it is
not set it will also check the variable `persistValue` of the individual
window.

Convenience method, all the action is done in :meth:`~PersistenceManager.DoRestoreValue`.

Saves the state of an object.

:note: This methods does nothing if :meth:`~PersistenceManager.DisableSaving` was called.

Combines both :meth:`~PersistenceManager.Save` and :meth:`~PersistenceManager.Unregister` calls.

:param `window`: an instance of :class:`wx.Window`. If it is ``None``, all the
 windows previously registered are saved and then unregistered.

Check if we persist the widget value, if so pass it to :meth:`~PersistenceManager.DoSaveValue`,
this method checks the style `PM_PERSIST_CONTROL_VALUE` and if it is not
set it will also check the variable `persistValue` of the individual
window.

Convenience method, all the action is done in :meth:`~PersistenceManager.DoSaveValue`.

Sets the persistent configuration handler for :class:`PersistenceManager`.

:param `handler`: an object capable of saving/restoring UI settings. This
 can be a cPickle object or a ConfigObj one, for example.

Sets the :class:`PersistenceManager` style.

:param `style`: a combination of the following values:

======================================== ==================================
Flag name                                Description
``PM_SAVE_RESTORE_AUI_PERSPECTIVES``     If a toplevel window has an AUI manager associated, the manager will save and restore its AUI perspective
``PM_SAVE_RESTORE_TREE_LIST_SELECTIONS`` If set, the manager will save items selections in list and tree controls
``PM_PERSIST_CONTROL_VALUE``             If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
``PM_DEFAULT_STYLE``                     Same as ``PM_SAVE_RESTORE_AUI_PERSPECTIVES``.

Sets the persistent configuration file for :class:`PersistenceManager`.

:param `fileName`: the file name where to store the persistent options.

:note: Calling this method has no influence if you are using your own

Sets the persistent key name inside the configuration file for :class:`PersistenceManager`.

:param `key`: a short meaningful name for your unique preferences key.

Unregister the object, this is called by :class:`PersistenceManager` itself so there is
usually no need to do it explicitly.

:param `window`: an instance of :class:`wx.Window`, which must have been previously
 registered with :meth:`~PersistenceManager.Register`.

:note: For the persistent windows this is done automatically (via :meth:`~PersistenceManager.SaveAndUnregister`)
 when the window is destroyed so you only need to call this function explicitly if you
 are using custom persistent objects or if you want to prevent the object properties
 from being saved.

:note: This deletes the associated :class:`PersistentObject`.

This property returns ``True`` if any of the windows managed by

:class:`PersistentObject`: ABC for anything persistent.

This is the base class for persistent object adapters.
wxPython persistence framework is non-intrusive, i.e. can work with the
classes which have no relationship to nor knowledge of it. To allow this,
an intermediate persistence adapter is used: this is just a simple object
which provides the methods used by :class:`PersistenceManager` to save and restore
the object properties and implements them using the concrete class methods.

You may derive your own classes from :class:`PersistentObject` to implement persistence
support for your common classes, see :ref:`persistent-windows` in the
`__init__.py` file.

Returns the string uniquely identifying the objects supported by this adapter.

:note: This method is called from :meth:`~PersistentObject.SaveValue` and :meth:`~PersistentObject.RestoreValue` and normally
 returns some short (but not too cryptic) strings, e.g. "Checkbox".

Returns the string uniquely identifying the window we're associated with
among all the other objects of the same type.

:note: This method is used together with :meth:`~PersistentObject.GetKind` to construct the unique
 full name of the object in e.g. a configuration file.

Restores the corresponding window settings.

:note: This method shouldn't be used directly as it doesn't respect the
 global :meth:`PersistenceManager.DisableRestoring() <PersistenceManager.DisableRestoring>` settings, use :class:`PersistenceManager`
 methods with the same name instead.

Restore the value saved by :meth:`~PersistentObject.SaveCtrlValue`, should be used only for
controls data value.

:param `name`: the same name as was used by :meth:`~PersistentObject.SaveCtrlValue`.

:returns: ``True`` if the value was successfully read or ``False`` if
 it was not found or an error occurred.

Restore the value saved by :meth:`~PersistentObject.SaveValue`.

:param `name`: the same name as was used by :meth:`~PersistentObject.SaveValue`.

Saves the corresponding window settings.

.. note::

   This method shouldn't be used directly as it doesn't respect the
   global :meth:`PersistenceManager.DisableSaving() <PersistenceManager.DisableSaving>` settings, use :class:`PersistenceManager`
   methods with the same name instead.

Save the specified value using the given name, should be used only for

:param `name`: the name of the value in the configuration file;
:param `value`: the value to save.

:returns: ``True`` if the value was saved or ``False`` if an error occurred.

Save the specified value using the given name.

The `RibbonBar` library is a set of classes for writing a ribbon user interface.

At the most generic level, this is a combination of a tab control with a toolbar.
At a more functional level, it is similar to the user interface present in recent
versions of Microsoft Office.

A ribbon user interface typically has a :class:`bar.RibbonBar`, which contains one or more
:class:`page.RibbonPage`, which in turn each contains one or more :class:`panel.RibbonPanel`, which in turn
contain controls.

Usage
=====

Usage example::

    import wx
    import wx.lib.agw.ribbon as RB

        def __init__(self, parent, id=-1, title="Ribbon Demo", pos=wx.DefaultPosition,

            self._ribbon = RB.RibbonBar(self, wx.ID_ANY)

            home = RB.RibbonPage(self._ribbon, wx.ID_ANY, "Examples", CreateBitmap("ribbon"))
            toolbar_panel = RB.RibbonPanel(home, wx.ID_ANY, "Toolbar", wx.NullBitmap, wx.DefaultPosition,
                                           wx.DefaultSize, agwStyle=RB.RIBBON_PANEL_NO_AUTO_MINIMISE)

            toolbar = RB.RibbonToolBar(toolbar_panel, ID_MAIN_TOOLBAR)
            toolbar.AddTool(wx.ID_ANY, CreateBitmap("align_left"))
            toolbar.AddTool(wx.ID_ANY, CreateBitmap("align_center"))
            toolbar.AddTool(wx.ID_ANY, CreateBitmap("align_right"))
            toolbar.AddSeparator()
            toolbar.AddHybridTool(wx.ID_NEW, wx.ArtProvider.GetBitmap(wx.ART_NEW, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddTool(wx.ID_ANY, wx.ArtProvider.GetBitmap(wx.ART_FILE_OPEN, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddTool(wx.ID_ANY, wx.ArtProvider.GetBitmap(wx.ART_FILE_SAVE, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddTool(wx.ID_ANY, wx.ArtProvider.GetBitmap(wx.ART_FILE_SAVE_AS, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddDropdownTool(wx.ID_UNDO, wx.ArtProvider.GetBitmap(wx.ART_UNDO, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddDropdownTool(wx.ID_REDO, wx.ArtProvider.GetBitmap(wx.ART_REDO, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddTool(wx.ID_ANY, wx.ArtProvider.GetBitmap(wx.ART_REPORT_VIEW, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddTool(wx.ID_ANY, wx.ArtProvider.GetBitmap(wx.ART_LIST_VIEW, wx.ART_OTHER, wx.Size(16, 15)))
            toolbar.AddHybridTool(ID_POSITION_LEFT, CreateBitmap("position_left"),
                                  "Align ribbonbar vertically on the left for demonstration purposes")
            toolbar.AddHybridTool(ID_POSITION_TOP, CreateBitmap("position_top"),
                                  "Align the ribbonbar horizontally at the top for demonstration purposes")
            toolbar.AddHybridTool(wx.ID_PRINT, wx.ArtProvider.GetBitmap(wx.ART_PRINT, wx.ART_OTHER, wx.Size(16, 15)),
                                  "This is the Print button tooltip demonstrating a tooltip")
            toolbar.SetRows(2, 3)

            selection_panel = RB.RibbonPanel(home, wx.ID_ANY, "Selection", CreateBitmap("selection_panel"))
            selection = RB.RibbonButtonBar(selection_panel)
            selection.AddSimpleButton(ID_SELECTION_EXPAND_V, "Expand Vertically", CreateBitmap("expand_selection_v"),
                                      "This is a tooltip for Expand Vertically demonstrating a tooltip")
            selection.AddSimpleButton(ID_SELECTION_EXPAND_H, "Expand Horizontally", CreateBitmap("expand_selection_h"), "")
            selection.AddSimpleButton(ID_SELECTION_CONTRACT, "Contract", CreateBitmap("auto_crop_selection"),
                                      CreateBitmap("auto_crop_selection_small"))

            shapes_panel = RB.RibbonPanel(home, wx.ID_ANY, "Shapes", CreateBitmap("circle_small"))
            shapes = RB.RibbonButtonBar(shapes_panel)

            # Show toggle buttons behaviour
            shapes.AddButton(ID_CIRCLE, "Circle", CreateBitmap("circle"), CreateBitmap("circle_small"),
                             help_string="This is a tooltip for the circle button demonstrating another tooltip",
                             kind=RB.RIBBON_BUTTON_TOGGLE)

            shapes.AddSimpleButton(ID_CROSS, "Cross", CreateBitmap("cross"), "")
            shapes.AddHybridButton(ID_TRIANGLE, "Triangle", CreateBitmap("triangle"))
            shapes.AddSimpleButton(ID_SQUARE, "Square", CreateBitmap("square"), "")
            shapes.AddDropdownButton(ID_POLYGON, "Other Polygon", CreateBitmap("hexagon"), "")

            sizer_panel = RB.RibbonPanel(home, wx.ID_ANY, "Panel with Sizer",
                                         wx.NullBitmap, wx.DefaultPosition, wx.DefaultSize,
                                         agwStyle=RB.RIBBON_PANEL_DEFAULT_STYLE)

            scheme = RB.RibbonPage(self._ribbon, wx.ID_ANY, "Appearance", CreateBitmap("eye"))
            self._default_primary, self._default_secondary, self._default_tertiary = self._ribbon.GetArtProvider().GetColourScheme(1, 1, 1)

            provider_panel = RB.RibbonPanel(scheme, wx.ID_ANY, "Art", wx.NullBitmap, wx.DefaultPosition, wx.DefaultSize,
                                            agwStyle=RB.RIBBON_PANEL_NO_AUTO_MINIMISE)
            provider_bar = RB.RibbonButtonBar(provider_panel, wx.ID_ANY)
            provider_bar.AddSimpleButton(ID_DEFAULT_PROVIDER, "Default Provider",
                                         wx.ArtProvider.GetBitmap(wx.ART_QUESTION, wx.ART_OTHER, wx.Size(32, 32)), "")
            provider_bar.AddSimpleButton(ID_AUI_PROVIDER, "AUI Provider", CreateBitmap("aui_style"), "")
            provider_bar.AddSimpleButton(ID_MSW_PROVIDER, "MSW Provider", CreateBitmap("msw_style"), "")

            primary_panel = RB.RibbonPanel(scheme, wx.ID_ANY, "Primary Colour", CreateBitmap("colours"))
            self._primary_gallery = self.PopulateColoursPanel(primary_panel, self._default_primary, ID_PRIMARY_COLOUR)

            secondary_panel = RB.RibbonPanel(scheme, wx.ID_ANY, "Secondary Colour", CreateBitmap("colours"))
            self._secondary_gallery = self.PopulateColoursPanel(secondary_panel, self._default_secondary, ID_SECONDARY_COLOUR)

            dummy_2 = RB.RibbonPage(self._ribbon, wx.ID_ANY, "Empty Page", CreateBitmap("empty"))
            dummy_3 = RB.RibbonPage(self._ribbon, wx.ID_ANY, "Another Page", CreateBitmap("empty"))

            self._ribbon.Realize()

            self._logwindow = wx.TextCtrl(self, wx.ID_ANY, "", wx.DefaultPosition, wx.DefaultSize,
                                          wx.TE_MULTILINE | wx.TE_READONLY | wx.TE_LEFT | wx.TE_BESTWRAP | wx.BORDER_NONE)

            s = wx.BoxSizer(wx.VERTICAL)

            s.Add(self._ribbon, 0, wx.EXPAND)
            s.Add(self._logwindow, 1, wx.EXPAND)

            self.SetSizer(s)

What's New

Current wxRibbon version tracked: wxWidgets 2.9.5 (SVN HEAD)

New features recently implemented:

- Possibility to hide panels in the :class:`bar.RibbonBar`;
- Added the ``EVT_RIBBONBAR_TAB_LEFT_DCLICK`` event, which generates a special event
  when a ribbon bar tab is double-clicked;
- Added support for toggle buttons in the :class:`bar.RibbonBar`;
- Improved support for ribbon panel sizers: panels with sizers should now automatically
  minimise at small sizes, and behave properly when popping up from a minimised state;
- Added tooltips via `SetToolTip` for those buttons which have the `help_string` attribute set.

RIBBON library is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.3.

# --------------------------------------------------------------------------------- #
# ribbon wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 03 Nov 2006
#
#
# TODO List
#
#
#
#
#
#

# Name:         art.py
# Purpose:
#
#
# Created:
# Version:
# Date:

`art_aui` is responsible for drawing all the components of the ribbon
interface using an AUI-compatible appearance.

This allows a ribbon bar to have a pluggable look-and-feel, while retaining the same
underlying behaviour. As a single art provider is used for all ribbon components, a
ribbon bar usually has a consistent (though unique) appearance.

By default, a :class:`~wx.lib.agw.ribbon.bar.RibbonBar` uses an instance of a class called
:class:`~wx.lib.agw.ribbon.art_default.RibbonDefaultArtProvider`,
which resolves to :class:`~wx.lib.agw.ribbon.art_aui.RibbonAUIArtProvider`,
:class:`~wx.lib.agw.ribbon.art_msw.RibbonMSWArtProvider`, or
:class:`~wx.lib.agw.ribbon.art_osx.RibbonOSXArtProvider` - whichever is most appropriate
to the current platform. These art providers are all
slightly configurable with regard to colours and fonts, but for larger modifications,
you can derive from one of these classes, or write a completely new art provider class.

Call :meth:`RibbonBar.SetArtProvider() <lib.agw.ribbon.bar.RibbonBar.SetArtProvider>` to change the art provider being used.

See Also
========

:class:`~wx.lib.agw.ribbon.bar.RibbonBar`

# Name:         art_aui.py
# Purpose:
#
#
# Created:
# Version:
# Date:

Draw the background for a :class:`~wx.lib.agw.ribbon.buttonbar.RibbonButtonBar` control.

:param `dc`: The device context to draw onto;
:param `wnd`: The window which is being drawn onto (which will typically
 be the button bar itself, though this is not guaranteed);
:param `rect`: The rectangle within which to draw.

Draw a single button for a :class:`~wx.lib.agw.ribbon.buttonbar.RibbonButtonBar` control.

:param `wnd`: The window which is being drawn onto;
:param `rect`: The rectangle within which to draw. The size of this rectangle
 will be a size previously returned by :meth:`RibbonMSWArtProvider.GetButtonBarButtonSize() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetButtonBarButtonSize>`, and the
 rectangle will be entirely within a rectangle on the same device context
 previously painted with :meth:`~RibbonAUIArtProvider.DrawButtonBarBackground`;
:param `kind`: The kind of button to draw (normal, dropdown or hybrid);
:param `state`: Combination of a size flag and state flags from the
 `RibbonButtonBarButtonState` enumeration;
:param `label`: The label of the button;
:param `bitmap_large`: The large bitmap of the button (or the large disabled
 bitmap when ``RIBBON_BUTTONBAR_BUTTON_DISABLED`` is set in );
:param `bitmap_small`: The small bitmap of the button (or the small disabled
 bitmap when ``RIBBON_BUTTONBAR_BUTTON_DISABLED`` is set in ).

DrawButtonBarButton(self, dc, wnd, rect, kind, state, label, bitmap_large, bitmap_small)

Draw the background and chrome for a :class:`~wx.lib.agw.ribbon.gallery.RibbonGallery` control.

This should draw the border, background, scroll buttons, extension button, and
any other UI elements which are not attached to a specific gallery item.

:param `wnd`: The window which is being drawn onto, which is always the gallery
 whose background and chrome is being drawn. Attributes used during drawing like
 the gallery hover state and individual button states can be queried from this
 parameter by :meth:`RibbonGallery.IsHovered() <lib.agw.ribbon.gallery.RibbonGallery.IsHovered>`,
 :meth:`RibbonGallery.GetExtensionButtonState() <lib.agw.ribbon.gallery.RibbonGallery.GetExtensionButtonState>`,
 :meth:`RibbonGallery.GetUpButtonState() <lib.agw.ribbon.gallery.RibbonGallery.GetUpButtonState>`, and
 :meth:`RibbonGallery.GetDownButtonState() <lib.agw.ribbon.gallery.RibbonGallery.GetDownButtonState>`;
:param `rect`: The rectangle within which to draw. This rectangle is the entire
 area of the gallery control, not just the client rectangle.

Draw the background of a single item in a :class:`~wx.lib.agw.ribbon.gallery.RibbonGallery` control.

This is painted on top of a gallery background, and behind the items bitmap.
Unlike :meth:`~RibbonAUIArtProvider.DrawButtonBarButton` and :meth:`~RibbonAUIArtProvider.DrawTool`, it is not expected to draw the
item bitmap - that is done by the gallery control itself.

 which contains the item being drawn;
 will be the size of the item's bitmap, expanded by gallery item padding values
 (``RIBBON_ART_GALLERY_BITMAP_PADDING_LEFT_SIZE``, ``RIBBON_ART_GALLERY_BITMAP_PADDING_RIGHT_SIZE``,
 ``RIBBON_ART_GALLERY_BITMAP_PADDING_TOP_SIZE``, and ``RIBBON_ART_GALLERY_BITMAP_PADDING_BOTTOM_SIZE``).
 The drawing rectangle will be entirely within a rectangle on the same device
 context previously painted with :meth:`~RibbonAUIArtProvider.DrawGalleryBackground`;
:param `item`: The item whose background is being painted. Typically the
 background will vary if the item is hovered, active, or selected;
 :meth:`RibbonGallery.GetSelection() <lib.agw.ribbon.gallery.RibbonGallery.GetSelection>`,
 :meth:`RibbonGallery.GetActiveItem() <lib.agw.ribbon.gallery.RibbonGallery.GetActiveItem>`, and
 :meth:`RibbonGallery.GetHoveredItem() <lib.agw.ribbon.gallery.RibbonGallery.GetHoveredItem>`
 can be called to test if the given item is in one of these states.

Draw a minimised ribbon panel.

:param `wnd`: The window which is being drawn onto, which is always the panel
 which is minimised. The panel label can be obtained from this window. The
 minimised icon obtained from querying the window may not be the size requested
 by :meth:`RibbonMSWArtProvider.GetMinimisedPanelMinimumSize() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetMinimisedPanelMinimumSize>` - the argument contains the icon in the
 requested size;
:param `rect`: The rectangle within which to draw. The size of the rectangle
 will be at least the size returned by :meth:`RibbonMSWArtProvider.GetMinimisedPanelMinimumSize() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetMinimisedPanelMinimumSize>`;
:param `bitmap`: A copy of the panel's minimised bitmap rescaled to the size
 returned by :meth:`RibbonMSWArtProvider.GetMinimisedPanelMinimumSize() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetMinimisedPanelMinimumSize>`.

Draw the background of a ribbon page.

:param `wnd`: The window which is being drawn onto (which is commonly the
 :class:`~wx.lib.agw.ribbon.page.RibbonPage` whose background is being drawn, but doesn't have to be);

:see: :meth:`RibbonMSWArtProvider.GetPageBackgroundRedrawArea() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetPageBackgroundRedrawArea>`

Draw the background and chrome for a ribbon panel.

This should draw the border, background, label, and any other items of a panel
which are outside the client area of a panel. Note that when a panel is
minimised, this function is not called - only :meth:`~RibbonAUIArtProvider.DrawMinimisedPanel` is called,
so a background should be explicitly painted by that if required.

 whose background and chrome is being drawn. The panel label and other panel
 attributes can be obtained by querying this;

Draw a ribbon-style scroll button.

 will be at least the size returned by :meth:`~RibbonAUIArtProvider.GetScrollButtonMinimumSize` for a
 scroll button with the same style. For tab scroll buttons, this rectangle
 will be entirely within a rectangle on the same device context previously
 painted with :meth:`~RibbonAUIArtProvider.DrawTabCtrlBackground`, but this is not guaranteed for other
 types of button (for example, page scroll buttons will not be painted on
 an area previously painted with :meth:`~RibbonAUIArtProvider.DrawPageBackground`);
:param `style`: A combination of flags from `RibbonScrollButtonStyle`,
 including a direction, a for flag, and one or more states.

Draw a single tab in the tab region of a ribbon bar.

:param `wnd`: The window which is being drawn onto (not the :class:`~wx.lib.agw.ribbon.page.RibbonPage`
 associated with the tab being drawn);
:param `tab`: The rectangle within which to draw, and also the tab label,
 icon, and state (active and/or hovered). The drawing rectangle will be
 entirely within a rectangle on the same device context previously painted
 with :meth:`~RibbonAUIArtProvider.DrawTabCtrlBackground`. The rectangle's width will be at least the
 minimum value returned by :meth:`~RibbonAUIArtProvider.GetBarTabWidth`, and height will be the value
 returned by :meth:`~RibbonAUIArtProvider.GetTabCtrlHeight`.

Draw the background of the tab region of a ribbon bar.

Draw a separator between two tabs in a ribbon bar.

:param `rect`: The rectangle within which to draw, which will be entirely
 within a rectangle on the same device context previously painted with
 :meth:`~RibbonAUIArtProvider.DrawTabCtrlBackground`;
:param `visibility`: The opacity with which to draw the separator. Values
 are in the range [0, 1], with 0 being totally transparent, and 1 being totally
 opaque.

Draw a single tool (for a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar` control).

:param `wnd`: The window which is being drawn onto. In most cases this will
 be a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar`, but it doesn't have to be;
 will at least the size returned by :meth:`RibbonMSWArtProvider.GetToolSize() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetToolSize>`,
 and the height of it will
 be equal for all tools within the same group. The rectangle will be entirely
 :meth:`~RibbonAUIArtProvider.DrawToolGroupBackground`;
:param `bitmap`: The bitmap to use as the tool's foreground. If the tool is a
 hybrid or dropdown tool, then the foreground should also contain a standard
 dropdown button;
:param `kind`: The kind of tool to draw (normal, dropdown, or hybrid);
:param `state`: A combination of `RibbonToolBarToolState` flags giving the
 state of the tool and it's relative position within a tool group.

Draw the background for a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar` control.

:param `wnd`: The which is being drawn onto. In most cases this will be
 a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar`, but it doesn't have to be;
:param `rect`: The rectangle within which to draw. Some of this rectangle
 will later be drawn over using :meth:`~RibbonAUIArtProvider.DrawToolGroupBackground` and :meth:`~RibbonAUIArtProvider.DrawTool`,
 but not all of it will (unless there is only a single group of tools).

Draw the background for a group of tools on a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar` control.

:param `rect`: The rectangle within which to draw. This rectangle is a union
 of the individual tools' rectangles. As there are no gaps between tools, this
 rectangle will be painted over exactly once by calls to :meth:`~RibbonAUIArtProvider.DrawTool`. The
 group background could therefore be painted by :meth:`~RibbonAUIArtProvider.DrawTool`, though it can be
 conceptually easier and more efficient to draw it all at once here. The
 previously painted with :meth:`~RibbonAUIArtProvider.DrawToolBarBackground`.

Calculate the ideal and minimum width (in pixels) of a tab in a ribbon bar.

:param `dc`: A device context to use when one is required for size calculations;
:param `wnd`: The window onto which the tab will eventually be drawn;
:param `label`: The tab's label (or an empty string if it has none);
:param `bitmap`: The tab's icon (or :class:`NullBitmap` if it has none);
:param `ideal`: The ideal width (in pixels) of the tab;
:param `small_begin_need_separator`: A size less than the size, at which a tab
 separator should begin to be drawn (i.e. drawn, but still fairly transparent);
:param `small_must_have_separator`: A size less than the size, at which a tab
 separator must be drawn (i.e. drawn at full opacity);
:param `minimum`: A size less than the size, and greater than or equal to zero,
 which is the minimum pixel width for the tab.

GetBarTabWidth(self, dc, wnd, label, bitmap, ideal=None, small_begin_need_separator=None, small_must_have_separator=None, minimum=None)

Get the value of a certain colour setting.

can be one of the colour values of `RibbonArtSetting`.

:param `id`: the colour id.

Calculate the client size of a panel for a given overall size.

This should act as the inverse to :meth:`~RibbonAUIArtProvider.GetPanelSize`, and decrement the given size
by enough to fit the panel label and other chrome.

:param `dc`: A device context to use if one is required for size calculations;
:param `wnd`: The ribbon panel in question;
:param `size`: The overall size to calculate client size for;
:param `client_offset`: The offset where the returned client size begins within
 the given (may be ``None``).

:see: :meth:`~RibbonAUIArtProvider.GetPanelSize`

Retrieve the extension button area rectangle.

:param `dc`: The device context used to measure text extents;
:param `wnd`: The panel where the extension button resides;
:param `rect`: The panel client rectangle.

Calculate the size of a panel for a given client size.

This should increment the given size by enough to fit the panel label and other
chrome.

:param `client_size`: The client size;
:param `client_offset`: The offset where the client rectangle begins within
 the panel (may be ``None``).

:see: :meth:`~RibbonAUIArtProvider.GetPanelClientSize`

Calculate the minimum size (in pixels) of a scroll button.

:param `wnd`: The window onto which the scroll button will eventually be drawn;
:param `style`: A combination of flags from `RibbonScrollButtonStyle`, including
 a direction, and a for flag (state flags may be given too, but should be ignored,
 as a button should retain a constant size, regardless of its state).

Calculate the height (in pixels) of the tab region of a ribbon bar.

Note that as the tab region can contain scroll buttons, the height should be
greater than or equal to the minimum height for a tab scroll button.

:param `wnd`: The window onto which the tabs will eventually be drawn;
:param `pages`: The tabs which will acquire the returned height.

Set the value of a certain colour setting to the value.

can be one of the colour values of `RibbonArtSetting`, though not all colour
settings will have an affect on every art provider.

:param `id`: the colour id;
:param `colour`: MISSING DESCRIPTION.

:see: :meth:`~RibbonAUIArtProvider.SetColourScheme`

Set all applicable colour settings from a few base colours.

Uses any or all of the three given colours to create a colour scheme, and then
sets all colour settings which are relevant to the art provider using that
scheme. Note that some art providers may not use the tertiary colour for
anything, and some may not use the secondary colour either.

:param `primary`: MISSING DESCRIPTION;
:param `secondary`: MISSING DESCRIPTION;
:param `tertiary`: MISSING DESCRIPTION.

:see: :meth:`~RibbonAUIArtProvider.SetColour`, :meth:`RibbonMSWArtProvider.GetColourScheme() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.GetColourScheme>`

Set the value of a certain font setting to the value.

can be one of the font values of `RibbonArtSetting`.

:param `id`: the font id;
:param `font`: MISSING DESCRIPTION.

:param `wnd`: The window which is being drawn onto (which will typically be
 the button bar itself, though this is not guaranteed);

 will be a size previously returned by :meth:`~RibbonMSWArtProvider.GetButtonBarButtonSize`, and the
 previously painted with :meth:`~RibbonMSWArtProvider.DrawButtonBarBackground`;
 bitmap when ``RIBBON_BUTTONBAR_BUTTON_DISABLED`` is set in `state`);
 bitmap when ``RIBBON_BUTTONBAR_BUTTON_DISABLED`` is set in `state`).

DrawButtonBarButtonForeground(self, dc, rect, kind, state, label, bitmap_large, bitmap_small)

Unlike :meth:`~RibbonMSWArtProvider.DrawButtonBarButton` and :meth:`~RibbonMSWArtProvider.DrawTool`, it is not expected to draw the

 context previously painted with :meth:`~RibbonMSWArtProvider.DrawGalleryBackground`;
:param `item`: The item whose background is being painted. Typically the background
 will vary if the item is hovered, active, or selected; :meth:`RibbonGallery.GetSelection() <lib.agw.ribbon.gallery.RibbonGallery.GetSelection>`,
 :meth:`RibbonGallery.GetHoveredItem() <lib.agw.ribbon.gallery.RibbonGallery.GetHoveredItem>` can be
 called to test if the given item is in one of these states.

 by :meth:`~RibbonMSWArtProvider.GetMinimisedPanelMinimumSize` - the argument contains the icon in the
 will be at least the size returned by :meth:`~RibbonMSWArtProvider.GetMinimisedPanelMinimumSize`;
 returned by :meth:`~RibbonMSWArtProvider.GetMinimisedPanelMinimumSize`.

:see: :meth:`~RibbonMSWArtProvider.GetPageBackgroundRedrawArea`

minimised, this function is not called - only :meth:`~RibbonMSWArtProvider.DrawMinimisedPanel` is called,

DrawPanelBorder(self, dc, rect, primary_colour, secondary_colour)

DrawPartialPageBackground(self, dc, wnd, rect, allow_hovered_or_page=True, offset=None, hovered=False)

DrawPartialPageBackground1(self, dc, wnd, rect, page, offset, hovered=False)

DrawPartialPageBackground2(self, dc, wnd, rect, allow_hovered=True)

 will be at least the size returned by :meth:`~RibbonMSWArtProvider.GetScrollButtonMinimumSize` for a
 painted with :meth:`~RibbonMSWArtProvider.DrawTabCtrlBackground`, but this is not guaranteed for other
 types of button (for example, page scroll buttons will not be painted on an
 area previously painted with :meth:`~RibbonMSWArtProvider.DrawPageBackground` );

:param `wnd`: The window which is being drawn onto (not the :class:`~wx.lib.agw.ribbon.page.RibbonPage` associated
 with the tab being drawn);
:param `tab`: The rectangle within which to draw, and also the tab label, icon, and
 state (active and/or hovered). The drawing rectangle will be entirely within a
 rectangle on the same device context previously painted with :meth:`~RibbonMSWArtProvider.DrawTabCtrlBackground`.
 The rectangle's width will be at least the minimum value returned by :meth:`~RibbonMSWArtProvider.GetBarTabWidth`,
 and height will be the value returned by :meth:`~RibbonMSWArtProvider.GetTabCtrlHeight`.

 :meth:`~RibbonMSWArtProvider.DrawTabCtrlBackground`;
 opaque.

 will at least the size returned by :meth:`~RibbonMSWArtProvider.GetToolSize`, and the height of it will
 :meth:`~RibbonMSWArtProvider.DrawToolGroupBackground`;

:param `wnd`: The which is being drawn onto. In most cases this will be a
 :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar`, but it doesn't have to be;
 will later be drawn over using :meth:`~RibbonMSWArtProvider.DrawToolGroupBackground` and :meth:`~RibbonMSWArtProvider.DrawTool`,

 of the individual tools' rectangles. As there are no gaps between tools,
 this rectangle will be painted over exactly once by calls to :meth:`~RibbonMSWArtProvider.DrawTool`.
 The group background could therefore be painted by :meth:`~RibbonMSWArtProvider.DrawTool`, though it
 can be conceptually easier and more efficient to draw it all at once here.
 The rectangle will be entirely within a rectangle on the same device context
 previously painted with :meth:`~RibbonMSWArtProvider.DrawToolBarBackground`.

:param `label`: The tab's label (or "" if it has none);
:param `small_begin_need_separator`: A size less than the size, at which a
 tab separator should begin to be drawn (i.e. drawn, but still fairly transparent);
:param `small_must_have_separator`: A size less than the size, at which a
 tab separator must be drawn (i.e. drawn at full opacity);
:param `minimum`: A size less than the size, and greater than or equal to
 zero, which is the minimum pixel width for the tab.

Calculate the size of a button within a :class:`~wx.lib.agw.ribbon.buttonbar.RibbonButtonBar`.

:param `wnd`: The window onto which the button will eventually be drawn
 (which is normally a :class:`~wx.lib.agw.ribbon.buttonbar.RibbonButtonBar`, though this is not guaranteed);
:param `kind`: The kind of button;
:param `size`: The size-class to calculate the size for. Buttons on a button
 bar can have three distinct sizes: ``RIBBON_BUTTONBAR_BUTTON_SMALL``,
 ``RIBBON_BUTTONBAR_BUTTON_MEDIUM``, and ``RIBBON_BUTTONBAR_BUTTON_LARGE``.
 If the requested size-class is not applicable, then ``False`` should be returned;
:param `bitmap_size_large`: The size of all "large" bitmaps on the button bar;
:param `bitmap_size_small`: The size of all "small" bitmaps on the button bar;
:param `button_size`: The size, in pixels, of the button;
:param `normal_region`: The region of the button which constitutes the normal button;
:param `dropdown_region`: The region of the button which constitutes the dropdown button.

:returns: ``True`` if a size exists for the button, ``False`` otherwise.

GetButtonBarButtonSize(self, dc, wnd, kind, size, label, bitmap_size_large, bitmap_size_small, button_size=None, normal_region=None, dropdown_region=None)

Get the current colour scheme.

Returns three colours such that if :meth:`~RibbonMSWArtProvider.SetColourScheme` were called with them, the
colour scheme would be restored to what it was when :meth:`~RibbonMSWArtProvider.SetColourScheme` was last
called. In practice, this usually means that the returned values are the three
colours given in the last call to :meth:`~RibbonMSWArtProvider.SetColourScheme`, however if
:meth:`~RibbonMSWArtProvider.SetColourScheme` performs an idempotent operation upon the colours it is given
(like clamping a component of the colour), then the returned values may not be
the three colours given in the last call to :meth:`~RibbonMSWArtProvider.SetColourScheme`.

If :meth:`~RibbonMSWArtProvider.SetColourScheme` has not been called, then the returned values should result
in a colour scheme similar to, if not identical to, the default colours of the
art provider. Note that if :meth:`~RibbonMSWArtProvider.SetColour` is called, then :meth:`~RibbonMSWArtProvider.GetColourScheme` does
not try and return a colour scheme similar to colours being used - it's return
values are dependent upon the last values given to :meth:`~RibbonMSWArtProvider.SetColourScheme`, as
described above.

:param `primary`: Pointer to a location to store the primary colour, or ``None``;
:param `secondary`: Pointer to a location to store the secondary colour, or ``None``;
:param `tertiary`: Pointer to a location to store the tertiary colour, or ``None``.

Get the value of a certain font setting.

:param `id`: the font id.

Calculate the client size of a :class:`~wx.lib.agw.ribbon.gallery.RibbonGallery` control for a given size.

This should act as the inverse to :meth:`~RibbonMSWArtProvider.GetGallerySize`, and decrement the given
size by enough to fir the gallery border, buttons, and other chrome.

:param `wnd`: The gallery in question;
:param `size`: The overall size to calculate the client size for;
:param `client_offset`: The position within the given size at which the
 returned client size begins;
:param `scroll_up_button`: The rectangle within the given size which the
 scroll up button occupies;
:param `scroll_down_button`: The rectangle within the given size which the
 scroll down button occupies;
:param `extension_button`: The rectangle within the given size which the
 extension button occupies.

GetGalleryClientSize(self, dc, wnd, size, client_offset=None, scroll_up_button=None, scroll_down_button=None, extension_button=None)

Calculate the size of a :class:`~wx.lib.agw.ribbon.gallery.RibbonGallery` control for a given client size.

This should increment the given size by enough to fit the gallery border,
buttons, and any other chrome.

:param `client_size`: The client size.

:see: :meth:`~RibbonMSWArtProvider.GetGalleryClientSize`

Get the value of a certain integer setting.

can be one of the size values of `RibbonArtSetting`.

:param `id`: a metric id.

Calculate the size of a minimised ribbon panel.

:param `wnd`: The ribbon panel in question. Attributes like the panel label can
 be queried from this;
:param `desired_bitmap_size`: MISSING DESCRIPTION;
:param `expanded_panel_direction`: MISSING DESCRIPTION.

GetMinimisedPanelMinimumSize(self, dc, wnd, desired_bitmap_size=None, expanded_panel_direction=None)

Calculate the portion of a page background which needs to be redrawn when a page
is resized.

To optimise the drawing of page backgrounds, as small an area as possible should
be returned. Of course, if the way in which a background is drawn means that the
entire background needs to be repainted on resize, then the entire new size
should be returned.

:param `wnd`: The page which is being resized;
:param `page_old_size`: The size of the page prior to the resize (which has
 already been painted);
:param `page_new_size`: The size of the page after the resize.

GetPageBackgroundRedrawArea(self, dc, wnd, page_old_size, page_new_size)

This should act as the inverse to :meth:`~RibbonMSWArtProvider.GetPanelSize`, and decrement the given size

:see: :meth:`~RibbonMSWArtProvider.GetPanelSize`

chrome.

:param `client_offset`: The offset where the client rectangle begins within the
 panel (may be ``None``).

:see: :meth:`~RibbonMSWArtProvider.GetPanelClientSize`

Calculate the size of a tool within a :class:`~wx.lib.agw.ribbon.toolbar.RibbonToolBar`.

:param `wnd`: The window onto which the tool will eventually be drawn;
:param `bitmap_size`: The size of the tool's foreground bitmap;
:param `kind`: The kind of tool (normal, dropdown, or hybrid);
:param `is_first`: ``True`` if the tool is the first within its group. ``False``
 otherwise;
:param `is_last`: ``True`` if the tool is the last within its group. ``False``
:param `dropdown_region`: For dropdown and hybrid tools, the region within the
 returned size which counts as the dropdown part.

GetToolSize(self, dc, wnd, bitmap_size, kind, is_first, is_last, dropdown_region=None)

:param `colour`: the colour.

:see: :meth:`~RibbonMSWArtProvider.SetColourScheme`

:see: :meth:`~RibbonMSWArtProvider.SetColour`, :meth:`~RibbonMSWArtProvider.GetColourScheme`

Set the style flags.

Normally called automatically by :meth:`RibbonBar.SetArtProvider() <lib.agw.ribbon.bar.RibbonBar.SetArtProvider>` with the ribbon
bar's style flags, so that the art provider has the same flags as the bar which
it is serving.

:param `flags`: MISSING DESCRIPTION.

:param `id`: a font id;
:param `font`: the new font.

Set the value of a certain integer setting to the value.

:param `id`: a metric id;
:param `new_val`: the new value of the metric setting.

RibbonInterpolateColour(start_colour, end_colour, position, start_position, end_position)

Convert a string or number to a floating point number, if possible.

`art_default` is responsible for drawing all the components of the ribbon
interface using a Windows/Mac or AUI appearance.

See Also
========

# Name:         art_default.py
# Purpose:
#
#
# Created:
# Version:
# Date:

This module contains methods used throughout the :class:`bar` library.

# Name:         art_internal.py
# Purpose:
#
#
# Created:
# Version:
# Date:

RibbonDrawParallelGradientLines(dc, nlines, line_origins, stepx, stepy, numsteps, offset_x, offset_y, start_colour, end_colour)

`art_msw` is responsible for drawing all the components of the ribbon
interface using a Windows appearance.

See Also
========

# Name:         art_msw.py
# Purpose:
#
#
# Created:
# Version:
# Date:

[b'5 5 2 1', b'  c None', b'x c #FF00FF', b'     ', b'xxxxx', b' xxx ', b'  x  ', b'     ']

[b'5 5 2 1', b'  c None', b'x c #FF00FF', b'xxxxx', b'     ', b'xxxxx', b' xxx ', b'  x  ']

[b'5 5 2 1', b'  c None', b'x c #FF00FF', b'   x ', b'  xx ', b' xxx ', b'  xx ', b'   x ']

[b'5 5 2 1', b'  c None', b'x c #FF00FF', b' x   ', b' xx  ', b' xxx ', b' xx  ', b' x   ']

[b'5 5 2 1', b'  c None', b'x c #FF00FF', b'     ', b'  x  ', b' xxx ', b'xxxxx', b'     ']

[b'7 7 2 1', b'  c None', b'x c #FF00FF', b'xxxxxx ', b'x      ', b'x      ', b'x  x  x', b'x   xxx', b'x   xxx', b'   xxxx']

`art_osx` is responsible for drawing all the components of the ribbon
interface using an AUI-compatible appearance on Mac, because as of now there is no
customized version of the ribbon art provider to provide a more or less native look
on the Mac platform.

See Also
========

Top-level control in a ribbon user interface.

Serves as a tabbed container for :class:`~wx.lib.agw.ribbon.page.RibbonPage` - a ribbon user interface typically
has a ribbon bar, which contains one or more RibbonPages, which in turn each contains
one or more RibbonPanels, which in turn contain controls. While a :class:`RibbonBar` has
tabs similar to a :class:`Notebook`, it does not follow the same API for adding pages.
Containers like :class:`Notebook` can contain any type of window as a page, hence the
normal procedure is to create the sub-window and then call :meth:`BookCtrlBase.AddPage` ().

As :class:`RibbonBar` can only have :class:`~wx.lib.agw.ribbon.page.RibbonPage` as children
(and a :class:`~wx.lib.agw.ribbon.page.RibbonPage` can only have a :class:`RibbonBar` as parent),
when a page is created, it is automatically added to the bar - there is no `AddPage` equivalent to call.

After all pages have been created, and all controls and panels placed on those pages,
:meth:`~RibbonBar.Realize` must be called.

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

This class supports the following window styles:

========================================== =========== ==========================================
Window Styles                              Hex Value   Description
``RIBBON_BAR_DEFAULT_STYLE``                       0x9 Defined as ``RIBBON_BAR_FLOW_HORIZONTAL`` | ``RIBBON_BAR_SHOW_PAGE_LABELS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``
``RIBBON_BAR_FOLDBAR_STYLE``                      0x1e Defined as ``RIBBON_BAR_FLOW_VERTICAL`` | ``RIBBON_BAR_SHOW_PAGE_ICONS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` | ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``
``RIBBON_BAR_SHOW_PAGE_LABELS``                    0x1 Causes labels to be shown on the tabs in the ribbon bar.
``RIBBON_BAR_SHOW_PAGE_ICONS``                     0x2 Causes icons to be shown on the tabs in the ribbon bar.
``RIBBON_BAR_FLOW_HORIZONTAL``                     0x0 Causes panels within pages to stack horizontally.
``RIBBON_BAR_FLOW_VERTICAL``                       0x4 Causes panels within pages to stack vertically.
``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``              0x8 Causes extension buttons to be shown on panels (where the panel has such a button).
``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``        0x10 Causes minimise buttons to be shown on panels (where the panel has such a button).
``RIBBON_BAR_ALWAYS_SHOW_TABS``                   0x20 Always shows the tabs area even when only one tab is added.

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

This class processes the following events:

================================= =================================
Event Name                        Description
``EVT_RIBBONBAR_PAGE_CHANGED``    Triggered after the transition from one page being active to a different page being active.
``EVT_RIBBONBAR_PAGE_CHANGING``   Triggered prior to the transition from one page being active to a different page being active, and can veto the change.
``EVT_RIBBONBAR_TAB_MIDDLE_DOWN`` Triggered when the middle mouse button is pressed on a tab.
``EVT_RIBBONBAR_TAB_MIDDLE_UP``   Triggered when the middle mouse button is released on a tab.
``EVT_RIBBONBAR_TAB_RIGHT_DOWN``  Triggered when the right mouse button is pressed on a tab.
``EVT_RIBBONBAR_TAB_RIGHT_UP``    Triggered when the right mouse button is released on a tab.
``EVT_RIBBONBAR_TAB_LEFT_DCLICK`` Triggered when the user double-clicks on a tab.

See Also
========

:class:`~wx.lib.agw.ribbon.page.RibbonPage`, :class:`~wx.lib.agw.ribbon.panel.RibbonPanel`

# Name:         bar.py
#
#
# RIBBONBAR Library wxPython IMPLEMENTATION
#
# Original C++ Code From Peter Cawley.
#
# Current wxRibbon Version Tracked: wxWidgets 2.9.0 SVN HEAD
#
#
#
# Andrea Gavana, @ 15 Oct 2009
# Latest Revision: 27 Dec 2012, 21.00 GMT
#
# For All Kind Of Problems, Requests Or Enhancements And Bug Reports, Please
#
#
#
#---------------------------------------------------------------------------

Default constructor.

:param `parent`: pointer to a parent window, must not be ``None``;
:type `parent`: :class:`wx.Window`
:param integer `id`: window identifier. If ``wx.ID_ANY``, will automatically create
 an identifier;
:param `pos`: window position. ``wx.DefaultPosition`` indicates that wxPython
 should generate a default position for the window;
:type `pos`: tuple or :class:`wx.Point`
:param `size`: window size. ``wx.DefaultSize`` indicates that wxPython should
 generate a default size for the window. If no suitable size can be found, the
 window will be sized to 20x20 pixels so that the window is visible but obviously
 not correctly sized;
:type `size`: tuple or :class:`wx.Size`
:param `agwStyle`: the AGW-specific window style. This can be a combination of the

 ========================================== =========== ==========================================
 Window Styles                              Hex Value   Description
 ``RIBBON_BAR_DEFAULT_STYLE``                       0x9 Defined as ``RIBBON_BAR_FLOW_HORIZONTAL`` | ``RIBBON_BAR_SHOW_PAGE_LABELS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``
 ``RIBBON_BAR_FOLDBAR_STYLE``                      0x1e Defined as ``RIBBON_BAR_FLOW_VERTICAL`` | ``RIBBON_BAR_SHOW_PAGE_ICONS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` | ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``
 ``RIBBON_BAR_SHOW_PAGE_LABELS``                    0x1 Causes labels to be shown on the tabs in the ribbon bar.
 ``RIBBON_BAR_SHOW_PAGE_ICONS``                     0x2 Causes icons to be shown on the tabs in the ribbon bar.
 ``RIBBON_BAR_FLOW_HORIZONTAL``                     0x0 Causes panels within pages to stack horizontally.
 ``RIBBON_BAR_FLOW_VERTICAL``                       0x4 Causes panels within pages to stack vertically.
 ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``              0x8 Causes extension buttons to be shown on panels (where the panel has such a button).
 ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``        0x10 Causes minimise buttons to be shown on panels (where the panel has such a button).
 ``RIBBON_BAR_ALWAYS_SHOW_TABS``                   0x20 Always shows the tabs area even when only one tab is added.

:param `validator`: the window validator;
:type `validator`: :class:`wx.Validator`

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=RIBBON_BAR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="RibbonBar")

Adds a page to the :class:`RibbonBar`.

:param `page`: an instance of :class:`~wx.lib.agw.ribbon.page.RibbonPage`.

Common initialization procedures.

:param integer `agwStyle`: the AGW-specific window style.

:see: :meth:`~RibbonBar.SetAGWWindowStyleFlag` for a list of valid window styles.

Dismiss the expanded panel of the currently active page.

Calls and returns the value from :meth:`RibbonPage.DismissExpandedPanel() <lib.agw.ribbon.page.RibbonPage.DismissExpandedPanel>` for the
currently active page, or ``False`` if there is no active page.

Does the initial painting of stuff from the :meth:`~RibbonBar.OnPaint` event.

:param `dc`: an instance of :class:`wx.DC`.

minimal size which doesn't truncate the control, for a panel - the same size
as it would have after a call to `Fit()`.

:return: An instance of :class:`wx.Size`.

Common methods for all the mouse move/click events.

:param `event`: a :class:`MouseEvent` event to be processed;
:param integer `tab_event_type`: one of the :class:`RibbonBar` events.

Get the index of the active page.

In the rare case of no page being active, -1 is returned.

Returns the :class:`RibbonBar` window style flag.

Get a page by index.

``None`` will be returned if the given index is out of range.

:param integer `n`: the zero-based index indicating the page position.

This method should be overridden to return true if this window has multiple pages.

All standard class with multiple pages such as :class:`Notebook`, :class:`Listbook` and :class:`Treebook`
already override it to return true and user-defined classes with similar behaviour should also
do so, to allow the library to handle such windows appropriately.

Hit test method for :class:`RibbonBar`, testing where the given (in client coordinates)
point lies.

:param `position`: an instance of :class:`wx.Point` in client coordinates.

:return: a tuple containing the tab index and the :class:`~wx.lib.agw.ribbon.page.RibbonPage` if the :meth:`~RibbonBar.HitTestTabs`
 successfully found such combination, or a tuple `(-1, None)` if no tab has been hit.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_MIDDLE_UP`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_RIGHT_UP`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonBar`.

Perform initial layout and size calculations of the bar and its children.

This must be called after all of the bar's children have been created (and their
children created, etc.) - if it is not, then windows may not be laid out or
sized correctly. Also calls :meth:`RibbonPage.Realize() <lib.agw.ribbon.page.RibbonPage.Realize>`
on each child page.

:note: Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.

Scrolls the tab area left/right/up/down by the specified `amount`.

:param integer `amount`: the amount by which the tab area is scrolled, in pixels.

See comments on :meth:`~RibbonBar.SetActivePageByIndex` and :meth:`~RibbonBar.SetActivePageByPage`. 

Set the active page by index, without triggering any events.

:param integer `page`: The zero-based index of the page to activate.

:returns: ``True`` if the specified page is now active, ``False`` if it could
 not be activated (for example because the page index is invalid).

Set the active page, without triggering any events.

:param `page`: the page to activate, an instance of :class:`~wx.lib.agw.ribbon.page.RibbonPage`.

 not be activated (for example because the given page is not a child of the
 ribbon bar).

Sets the window style for :class:`RibbonBar`.

:param integer `agwStyle`: can be a combination of the following bits:

:note: Please note that some styles cannot be changed after the window creation
 and that `Refresh()` might need to be be called after changing the others for
 the change to take place immediately.

Set the art provider to be used be the ribbon bar.

Also sets the art provider on all current :class:`~wx.lib.agw.ribbon.page.RibbonPage` children, and any
:class:`~wx.lib.agw.ribbon.page.RibbonPage` children added in the future.

Note that unlike most other ribbon controls, the ribbon bar creates a default
art provider when initialised, so an explicit call to :meth:`~RibbonBar.SetArtProvider` is
not required if the default art provider is sufficient. Also unlike other
ribbon controls, the ribbon bar takes ownership of the given pointer, and
will delete it when the art provider is changed or the bar is destroyed.

If this behaviour is not desired, then clone the art provider before setting
it.

Set the margin widths (in pixels) on the left and right sides of the tab bar
region of the ribbon bar.

These margins will be painted with the tab background, but tabs and scroll
buttons will never be painted in the margins. The left margin could be used for
rendering something equivalent to the "Office Button", though this is not
currently implemented. The right margin could be used for rendering a help
button, and/or MDI buttons, but again, this is not currently implemented.

:param integer `left`: the left margin (in pixels);
:param integer `right`: the right margin (in pixels).

Shows or hides the panels inside :class:`RibbonBar`.

:param bool `show`: ``True`` to show the panels, ``False`` to hide them.

Event used to indicate various actions relating to a :class:`RibbonBar`.

.. seealso:: :class:`RibbonBar` for available event types.

:param integer `command_type`: the event type;
:param integer `win_id`: the event identifier;

This is the opposite of :meth:`~RibbonBarEvent.Veto`: it explicitly allows the event to be processed.
For most events it is not necessary to call this method as the events are
allowed anyhow but some are forbidden by default (this will be mentioned
in the corresponding event description).

Returns the page being changed to, or being clicked on.

:returns: An instance of :class:`~wx.lib.agw.ribbon.page.RibbonPage`.

Returns ``True`` if the change is allowed (:meth:`~RibbonBarEvent.Veto` hasn't been called) or
``False`` otherwise (if it was).

Sets the page relating to this event.

:note: It is in general a good idea to notify the user about the reasons
 for vetoing the change because otherwise the applications behaviour (which
 just refuses to do what the user wants) might be quite surprising.

:param wx.Window `parent`: pointer to a parent window;
:type `size`: tuple or :class:`wx.Point`
:param wx.Validator `validator`: window validator;
:param string `name`: window name.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="RibbonControl")

Implementation of :meth:`~RibbonControl.GetNextLargerSize`.

Controls which have non-continuous sizing must override this virtual function
rather than :meth:`~RibbonControl.GetNextLargerSize`.

:param integer `direction`: the direction(s) in which the size should increase;
:param wx.Size `size`: the size for which a larger size should be found.

Implementation of :meth:`~RibbonControl.GetNextSmallerSize`.

rather than :meth:`~RibbonControl.GetNextSmallerSize`.

Get the art provider to be used.

Note that until an art provider has been set in some way, this function may
return ``None``.

If sizing is not continuous, then return a suitable size for the control which
is larger then the given size.

:param integer `direction`: The direction(s) in which the size should reduce;
:param wx.Size `relative_to`: The size for which a smaller size should be found.

:returns: if there is no larger size, otherwise a suitable size which is larger
 in the given direction(s), and the same as in the other direction (if any).

:see: :meth:`~RibbonControl.IsSizingContinuous`, :meth:`~RibbonControl.DoGetNextLargerSize`

is smaller than the given size.

:returns: if there is no smaller size, otherwise a suitable size which is smaller

:see: :meth:`~RibbonControl.IsSizingContinuous`, :meth:`~RibbonControl.DoGetNextSmallerSize`

Returns ``True`` if this window can take any size (greater than its minimum size),
``False`` if it can only take certain sizes.

:see: :meth:`~RibbonControl.GetNextSmallerSize`, :meth:`~RibbonControl.GetNextLargerSize`

Perform initial size and layout calculations after children have been added,
and/or realize children.

Set the art provider to be used.

In many cases, setting the art provider will also set the art provider on all
child windows which extend :class:`RibbonControl`. In most cases, controls will not
take ownership of the given pointer, with the notable exception being
:meth:`RibbonBar.SetArtProvider() <lib.agw.ribbon.bar.RibbonBar.SetArtProvider>`.

A ribbon button bar is similar to a traditional toolbar.

It contains one or more buttons (button bar buttons, not :class:`Button`), each of which
has a label and an icon. It differs from a :class:`toolbar` in several ways:

- Individual buttons can grow and contract.
- Buttons have labels as well as bitmaps.
- Bitmaps are typically larger (at least 32x32 pixels) on a button bar compared to
  a tool bar (which typically has 16x15).
- There is no grouping of buttons on a button bar
- A button bar typically has a border around each individual button, whereas a tool
  bar typically has a border around each group of buttons.

======================================== ========================================
Event Name                               Description
``EVT_RIBBONBUTTONBAR_CLICKED``          Triggered when the normal (non-dropdown) region of a button on the button bar is clicked.
``EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED`` Triggered when the dropdown region of a button on the button bar is clicked. :meth:`RibbonButtonBarEvent.PopupMenu() <RibbonButtonBarEvent.PopupMenu>` should be called by the event handler if it wants to display a popup menu (which is what most dropdown buttons should be doing).

# Name:         buttonbar.py
# Purpose:
#
#
# Created:
# Version:
# Date:

:param `parent`: pointer to a parent window, typically a :class:`~wx.lib.agw.ribbon.panel.RibbonPanel`;
:param integer `agwStyle`: the AGW-specific window style, currently unused.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=0)

Add a button to the button bar.

:param integer `button_id`: id of the new button (used for event callbacks);
:param string `label`: label of the new button;
:param `bitmap`: large bitmap of the new button, an instance of :class:`wx.Bitmap`. Must be the same size as
 all other large bitmaps used on the button bar;
:param `bitmap_small`: small bitmap of the new button, an instance of :class:`wx.Bitmap`. If left as :class:`NullBitmap`,
 then a small bitmap will be automatically generated. Must be the same size
 as all other small bitmaps used on the button bar;
:param `bitmap_disabled`: large bitmap of the new button when it is disabled, an instance of :class:`wx.Bitmap`.
 If left as :class:`NullBitmap`, then a bitmap will be automatically generated from `bitmap`;
:param `bitmap_small_disabled`: small bitmap of the new button when it is disabled, an instance of :class:`wx.Bitmap`.
 If left as :class:`NullBitmap`, then a bitmap will be automatically generated from `bitmap_small`;
:param integer `kind`: the kind of button to add, one of the following values:

 Button Kind                                Hex Value   Description
 ``RIBBON_BUTTON_NORMAL``                           0x1 Normal button or tool with a clickable area which causes some generic action.
 ``RIBBON_BUTTON_DROPDOWN``                         0x2 Dropdown button or tool with a clickable area which typically causes a dropdown menu.
 ``RIBBON_BUTTON_HYBRID``                           0x3 Button or tool with two clickable areas - one which causes a dropdown menu, and one which causes a generic action.
 ``RIBBON_BUTTON_TOGGLE``                           0x4 Normal button or tool with a clickable area which toggles the button between a pressed and unpressed state.

:param string `help_string`: the UI help string to associate with the new button;
:param object `client_data`: client data to associate with the new button (any Python object).

:returns: An opaque pointer which can be used only with other button bar methods.

:see: :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.AddDropdownButton`, :meth:`~RibbonButtonBar.AddHybridButton`

AddButton(self, button_id, label, bitmap, bitmap_small=wx.NullBitmap, bitmap_disabled=wx.NullBitmap, bitmap_small_disabled=wx.NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string="", client_data=None)

Add a dropdown button to the button bar (simple version).

:param string `help_string`: the UI help string to associate with the new button.

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertDropdownButton`, :meth:`~RibbonButtonBar.InsertButton`

AddDropdownButton(self, button_id, label, bitmap, help_string="")

Add a hybrid button to the button bar (simple version).

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.InsertHybridButton`

Add a button to the button bar (simple version).

:param integer `kind`: the kind of button to add.

:see: :meth:`~RibbonButtonBar.AddButton` for a list of valid button `kind` values.

AddSimpleButton(self, button_id, label, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

Add a toggle button to the button bar.

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.InsertToggleButton`

Delete all buttons from the button bar.

:see: :meth:`~RibbonButtonBar.DeleteButton`

Delete a single button from the button bar.

:param integer `button_id`: id of the button to delete.

:return: ``True`` if the button has been found and successfully deleted, ``False`` otherwise.

:see: :meth:`~RibbonButtonBar.ClearButtons`

Implementation of :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.

rather than :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.

Implementation of :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.

rather than :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.

Enable or disable a single button on the bar.

:param integer `button_id`: id of the button to enable or disable;
:param bool `enable`: ``True`` to enable the button, ``False`` to disable it.

:raise: `Exception` when the input `button_id` could not be associated
 with a :class:`RibbonButtonBar` button.

Returns the number of buttons in this :class:`RibbonButtonBar`.

.. versionadded:: 0.9.5

Returns the minimum size of the window, an indication to the sizer layout mechanism
that this is the minimum required size.

This method normally just returns the value set by `SetMinSize`, but it can be
overridden to do the calculation on demand.

Inserts a button in the button bar at the position specified by `pos`.

:param integer `pos`: the position at which the new button must be inserted (zero-based);
:param integer `kind`: the kind of button to add;
:param object `client_data`: client data to associate with the new button.

:raise: `Exception` if both `bitmap` and `bitmap_small` are invalid or if the input `help_string` is not
 a valid Python `basestring`.

:see: :meth:`~RibbonButtonBar.AddDropdownButton`, :meth:`~RibbonButtonBar.AddHybridButton` and :meth:`~RibbonButtonBar.AddButton` for a list of valid button `kind` values.

InsertButton(self, pos, button_id, label, bitmap, bitmap_small=wx.NullBitmap, bitmap_disabled=wx.NullBitmap, bitmap_small_disabled=wx.NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string="", client_data=None)

Inserts a dropdown button in the button bar at the position specified by `pos`.

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.AddDropdownButton`

InsertDropdownButton(self, pos, button_id, label, bitmap, help_string="")

Inserts a hybrid button in the button bar at the position specified by `pos`.

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.AddHybridButton`

InsertHybridButton(self, pos, button_id, label, bitmap, help_string="")

Inserts a toggle button in the button bar at the position specified by `pos`.

:see: :meth:`~RibbonButtonBar.AddButton`, :meth:`~RibbonButtonBar.InsertButton`, :meth:`~RibbonButtonBar.AddToggleButton`

InsertToggleButton(self, pos, button_id, label, bitmap, help_string="")

Returns whether a button in the bar is enabled or not.

:param integer `button_id`: id of the button to check.

:return: ``True`` if the button is enabled, ``False`` otherwise.

:see: :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`,
 :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`

Converts the `original` bitmap into a visually-looking disabled one.

:param `original`: the original bitmap, an instance of :class:`wx.Bitmap`.

:return: A visually-looking disabled representation of the input bitmap.

Resize and scale the `original` bitmap to the dimensions specified in `size`.

:param `original`: the original bitmap, an instance of :class:`wx.Bitmap`;
:param `size`: the size to which the input bitmap must be rescaled, an instance of :class:`wx.Size`.

:return: A scaled representation of the input bitmap.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonButtonBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonButtonBar`.

Calculate button layouts and positions.

Must be called after buttons are added to the button bar, as otherwise the newly
added buttons will not be displayed. In normal situations, it will be called
automatically when :meth:`RibbonBar.Realize() <lib.agw.ribbon.bar.RibbonBar.Realize>` is called.

child windows which extend :class:`~wx.lib.agw.ribbon.control.RibbonControl`. In most cases, controls will not

Toggles/untoggles a :class:`RibbonButtonBar` toggle button.

:param integer `button_id`: id of the button to be toggles/untoggled;
:param bool `checked`: ``True`` to toggle the button, ``False`` to untoggle it.

This function sends one or more :class:`UpdateUIEvent` to the window.

The particular implementation depends on the window; for example a :class:`ToolBar` will
send an update UI event for each toolbar button, and a :class:`wx.Frame` will send an
update UI event for each menubar menu item.

You can call this function from your application to ensure that your UI is up-to-date
at this point (as far as your :class:`UpdateUIEvent` handlers are concerned). This may be
necessary if you have called :meth:`UpdateUIEvent.SetMode` or :meth:`UpdateUIEvent.SetUpdateInterval`
to limit the overhead that wxWidgets incurs by sending update UI events in idle time.

:param integer `flags`: should be a bitlist of one or more of ``wx.UPDATE_UI_NONE``,
 ``wx.UPDATE_UI_RECURSE`` or ``wx.UPDATE_UI_FROMIDLE``.

If you are calling this function from an `OnInternalIdle` or `OnIdle` function, make sure
you pass the ``wx.UPDATE_UI_FROMIDLE`` flag, since this tells the window to only update
the UI elements that need to be updated in idle time. Some windows update their elements
only when necessary, for example when a menu is about to be shown. The following is an
example of how to call :meth:`~RibbonButtonBar.UpdateWindowUI` from an idle function::

    def OnInternalIdle(self):

        if wx.UpdateUIEvent.CanUpdate(self):
            self.UpdateWindowUI(wx.UPDATE_UI_FROMIDLE)

Event used to indicate various actions relating to a button on a :class:`RibbonButtonBar`.

.. seealso:: :class:`RibbonButtonBar` for available event types.

:param `bar`: an instance of :class:`RibbonButtonBar`.

Returns the bar which contains the button which the event relates to.

:returns: An instance of :class:`RibbonButtonBar`.

Display a popup menu as a result of this (dropdown clicked) event.

:param `menu`: an instance of :class:`wx.Menu`.

Sets the button bar relating to this event.

`RibbonControl` serves as a base class for all controls which share the ribbon
charactertics of having a ribbon art provider, and (optionally) non-continous
resizing.

Despite what the name may imply, it is not the top-level control for creating a
ribbon interface - that is :class:`~wx.lib.agw.ribbon.bar.RibbonBar`. Ribbon controls often have a region which
is "transparent", and shows the contents of the ribbon page or panel behind it.

If implementing a new ribbon control, then it may be useful to realise that this
effect is done by the art provider when painting the background of the control,
and hence in the paint handler for the new control, you should call a draw background
method on the art provider (:meth:`RibbonMSWArtProvider.DrawButtonBarBackground() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.DrawButtonBarBackground>` and
:meth:`RibbonMSWArtProvider.DrawToolBarBackground() <lib.agw.ribbon.art_msw.RibbonMSWArtProvider.DrawToolBarBackground>` typically just redraw what is behind the
rectangle being painted) if you want transparent regions.

# Name:         control.py
# Purpose:
#
#
# Created:
# Version:
# Date:

A ribbon gallery is like a :class:`ListBox`, but for bitmaps rather than strings.

It displays a collection of bitmaps arranged in a grid and allows the user to
choose one. As there are typically more bitmaps in a gallery than can be displayed
in the space used for a ribbon, a gallery always has scroll buttons to allow the
user to navigate through the entire gallery.

It also has an "extension" button, the behaviour of which is outside the scope of
the gallery control itself, though it typically displays some kind of dialog related
to the gallery.

=================================== ===================================
Event Name                          Description
``EVT_RIBBONGALLERY_SELECTED``      Triggered when the user selects an item from the gallery. Note that the ID is that of the gallery, not of the item.
``EVT_RIBBONGALLERY_HOVER_CHANGED`` Triggered when the item being hovered over by the user changes. The item in the event will be the new item being hovered, or ``None`` if there is no longer an item being hovered. Note that the ID is that of the gallery, not of the item.
``EVT_RIBBONGALLERY_CLICKED``       Triggered when the user clicks on an item in the gallery.
``EVT_BUTTON``                      Triggered when the "extension" button of the gallery is pressed.

# Name:         gallery.py
# Purpose:
#
#
# Created:
# Version:
# Date:

:param `id`: window identifier. If ``wx.ID_ANY``, will automatically create an
 identifier;
:param `agwStyle`: the AGW-specific window style, currently unused;
:param `name`: the window name.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=0, name="RibbonGallery")

Add an item to the gallery (with complex client data).

:param `bitmap`: the bitmap to display for the item. Note that all items must
 have equally sized bitmaps;
:param `id`: id number to associate with the item. Not currently used for
 anything important;
:param `clientData`: an object which contains data to associate with the item.
 The item takes ownership of this pointer, and will delete it when the item
 client data is changed to something else, or when the item is destroyed.

Scroll the gallery to ensure that the given item is visible.

:param `item`: an instance of :class:`RibbonGalleryItem`.

Get the currently active item, or ``None`` if there is none.

The active item is the item being pressed by the user, and will thus become the
selected item if the user releases the mouse button.

Get the currently hovered item, or ``None`` if there is none.

The hovered item is the item underneath the mouse cursor.

Get an item by index.

:param `n`: the zero-based item in the gallery, which is an instance of :class:`RibbonGalleryItem`.

Get the client data associated with a gallery item.

Get the currently selected item, or ``None`` if there is none.

The selected item is set by :meth:`~RibbonGallery.SetSelection`, or by the user clicking on an item.

Query is the mouse is currently hovered over the gallery.

:returns: ``True`` if the cursor is within the bounds of the gallery (not
 just hovering over an item), ``False`` otherwise.

Layout() -> bool

Lays out the children of this window using the associated sizer.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_MOTION`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonGallery`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonGallery`.

Scroll the gallery contents by some amount.

:param `lines`: Positive values scroll toward the end of the gallery, while
 negative values scroll toward the start.

:returns: ``True`` if the gallery scrolled at least one pixel in the given
 direction, ``False`` if it did not scroll.

:note: Reimplemented from :class:`wx.Window`.

Set the client data associated with a gallery item.

:param `item`: an instance of :class:`RibbonGalleryItem`;
:param `data`: any Python object.

Set the selection to the given item, or removes the selection if `item` == ``None``.

Note that this not cause any events to be emitted.

:param `item`: an instance of :class:`RibbonGalleryItem`, can also be ``None`` to remove the selection.

:param `gallery`: an instance of :class:`RibbonGallery`;

__init__(self, command_type=None, win_id=0, gallery=None, item=None)

Returns the gallery item which the event relates to, or ``None`` if it does not relate to an item. 

Sets the gallery relating to this event.

:param `gallery`: an instance of :class:`RibbonGallery`.

Sets the gallery item relating to this event.

Container for related ribbon panels, and a tab within a ribbon bar.

See Also
========

:class:`~wx.lib.agw.ribbon.bar.RibbonBar`, :class:`~wx.lib.agw.ribbon.panel.RibbonPanel`

# Name:         page.py
# Purpose:
#
#
# Created:
# Version:
# Date:

:param `parent`: pointer to a parent window, an instance of :class:`~wx.lib.agw.ribbon.bar.RibbonBar`;
:param `id`: window identifier. If ``wx.ID_ANY``, will automatically create an identifier;
:param `label`: label to be used in the :class:`~wx.lib.agw.ribbon.bar.RibbonBar`'s tab list for this page (if the
 ribbon bar is set to display labels);
:param `icon`: the icon used for the page in the ribbon bar tab area (if the ribbon bar is
 set to display icons);
:param `style`: window style. Currently unused, should be zero.

__init__(self, parent, id=wx.ID_ANY, label="", icon=wx.NullBitmap, style=0)

Expand a rectangle of the page to include external scroll buttons (if any).

When no scroll buttons are shown, has no effect.

:param `rect`: The rectangle to adjust. The width and height will not be
 reduced, and the x and y will not be increased.

Dismiss the current externally expanded panel, if there is one.

When a ribbon panel automatically minimises, it can be externally expanded into
a floating window. When the user clicks a button in such a panel, the panel
should generally re-minimise. Event handlers for buttons on ribbon panels should
call this method to achieve this behaviour.

:returns: ``True`` if a panel was minimised, ``False`` otherwise.

Sets the size of the window in pixels.

:param integer `x`: required `x` position in pixels, or ``wx.DefaultCoord`` to
 indicate that the existing value should be used;
:param integer `y`: required `y` position in pixels, or ``wx.DefaultCoord`` to
:param integer `width`: required width in pixels, or ``wx.DefaultCoord`` to
:param integer `height`: required height in pixels, or ``wx.DefaultCoord`` to
:param integer `sizeFlags`: indicates the interpretation of other parameters.
 It is a bit list of the following:

 * ``wx.SIZE_AUTO_WIDTH``: a ``wx.DefaultCoord`` width value is taken to indicate a
   wxPython-supplied default width.
 * ``wx.SIZE_AUTO_HEIGHT``: a ``wx.DefaultCoord`` height value is taken to indicate a
   wxPython-supplied default height.
 * ``wx.SIZE_AUTO``: ``wx.DefaultCoord`` size values are taken to indicate a wxPython-supplied
   default size.
 * ``wx.SIZE_USE_EXISTING``: existing dimensions should be used if ``wx.DefaultCoord`` values are supplied.
 * ``wx.SIZE_ALLOW_MINUS_ONE``: allow negative dimensions (i.e. value of ``wx.DefaultCoord``)
   to be interpreted as real dimensions, not default values.
 * ``wx.SIZE_FORCE``: normally, if the position and the size of the window are already
   the same as the parameters of this function, nothing is done. but with this flag a window
   resize may be forced even in this case (supported in wx 2.6.2 and later and only implemented
   for MSW and ignored elsewhere currently).

Get the icon used for the page in the ribbon bar tab area (only displayed if the
ribbon bar is actually showing icons).

Get the direction in which ribbon panels are stacked within the page.

This is controlled by the style of the containing :class:`~wx.lib.agw.ribbon.bar.RibbonBar`, meaning that all
pages within a bar will have the same major axis. As well as being the direction
in which panels are stacked, it is also the axis in which scrolling will occur
(when required).

:returns: ``wx.HORIZONTAL`` or ``wx.VERTICAL`` (never ``wx.BOTH``).

This method normally just returns the value set by `SetMinSize`, but it can be overridden
to do the calculation on demand.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonPage`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonPage`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonPage`.

Perform a full re-layout of all panels on the page.

Should be called after panels are added to the page, or the sizing behaviour of
a panel on the page changes (i.e. due to children being added to it). Usually
called automatically when :meth:`RibbonBar.Realize() <lib.agw.ribbon.bar.RibbonBar.Realize>` is called. Will invoke
:meth:`RibbonPanel.Realize() <lib.agw.ribbon.panel.RibbonPanel.Realize>` for all child panels.

Scroll the page by some amount up / down / left / right.

When the page's children are too big to fit in the onscreen area given to the
page, scroll buttons will appear, and the page can be programmatically scrolled.
Positive values of will scroll right or down, while negative values will scroll
up or left (depending on the direction in which panels are stacked). A line is
equivalent to a constant number of pixels.

:param integer `lines`: number of lines to scroll the page.

:returns: ``True`` if the page scrolled at least one pixel in the given direction,
 ``False`` if it did not scroll.

:see: :meth:`~RibbonPage.GetMajorAxis`, :meth:`~RibbonPage.ScrollPixels`

Scroll the page by a set number of pixels up / down / left / right.

up or left (depending on the direction in which panels are stacked).

:param integer `pixels`: number of pixels to scroll the page.

:see: :meth:`~RibbonPage.GetMajorAxis`, :meth:`~RibbonPage.ScrollLines`

Normally called automatically by :class:`~wx.lib.agw.ribbon.bar.RibbonBar` when the page is created, or the
art provider changed on the bar. The new art provider will be propagated to the
children of the page.

Set the size of the page and the external scroll buttons (if any).

When a page is too small to display all of its children, scroll buttons will
appear (and if the page is sized up enough, they will disappear again). Slightly
counter-intuively, these buttons are created as siblings of the page rather than
children of the page (to achieve correct cropping and paint ordering of the
children and the buttons).

When there are no scroll buttons, this function behaves the same as `SetSize`,
however when there are scroll buttons, it positions them at the edges of the
given area, and then calls `SetSize` with the remaining area. This is provided
as a separate function to `SetSize` rather than within the implementation
of `SetSize`, as iteracting algorithms may not expect `SetSize` to also
set the size of siblings.

:param `x`: the page `x` position, in pixels;
:param `y`: the page `y` position, in pixels;
:param `width`: the page width, in pixels;
:param `height`: the page height, in pixels.

__init__(self, sibling, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0)

:param `parent`: pointer to a parent window, typically a :class:`~wx.lib.agw.ribbon.page.RibbonPage`, though
 it can be any window;
:param `id`: window identifier. If ``wx.ID_ANY``, will automatically create
:param `label`: label of the new button;
:param `minimised_icon`: the bitmap to be used in place of the panel children
 when it is minimised;
:param `agwStyle`: the AGW-specific window style. This can be one of the following
 bits:

 ================================= =========== =================================
 Window Styles                     Hex Value   Description
 ``RIBBON_PANEL_DEFAULT_STYLE``            0x0 Defined as no other flags set.
 ``RIBBON_PANEL_NO_AUTO_MINIMISE``         0x1 Prevents the panel from automatically minimising to conserve screen space.
 ``RIBBON_PANEL_EXT_BUTTON``               0x8 Causes an extension button to be shown in the panel's chrome (if the bar in which it is contained has ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` set). The behaviour of this button is application controlled, but typically will show an extended drop-down menu relating to the panel.
 ``RIBBON_PANEL_MINIMISE_BUTTON``         0x10 Causes a (de)minimise button to be shown in the panel's chrome (if the bar in which it is contained has the ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS`` style set). This flag is typically combined with ``RIBBON_PANEL_NO_AUTO_MINIMISE`` to make a panel which the user always has manual control over when it minimises.
 ``RIBBON_PANEL_STRETCH``                 0x20 Allows a single panel to stretch to fill the parent page.
 ``RIBBON_PANEL_FLEXIBLE``                0x40 Allows toolbars to wrap, taking up the optimum amount of space when used in a vertical palette.

__init__(self, parent, id=wx.ID_ANY, label="", minimised_icon=wx.NullBitmap, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=RIBBON_PANEL_DEFAULT_STYLE, name="RibbonPanel")

Query if the panel can automatically minimise itself at small sizes. 

Finds the best width and height given the parent's width and height. 

Get the dummy panel of an expanded panel.

:note: This should be called on an expanded panel to get the dummy associated
 with it - it will return ``None`` when called on the dummy itself.

:see: :meth:`~RibbonPanel.ShowExpanded`, :meth:`~RibbonPanel.GetExpandedPanel`

Get the expanded panel of a dummy panel.

:note: This should be called on a dummy panel to get the expanded panel
 associated with it - it will return ``None`` when called on the expanded panel
 itself.

:see: :meth:`~RibbonPanel.ShowExpanded`, :meth:`~RibbonPanel.GetExpandedDummy`

Returns the AGW-specific window style for :class:`RibbonPanel`. 

Get the bitmap to be used in place of the panel children when it is minimised.

Hide the panel's external expansion.

:returns: ``True`` if the panel was un-expanded, ``False`` if it was not
 (normally due to it not being expanded in the first place).

:see: :meth:`~RibbonPanel.HideExpanded`, :meth:`~RibbonPanel.GetExpandedPanel`

Query is the mouse is currently hovered over the panel.

:returns: ``True`` if the cursor is within the bounds of the panel (i.e.
 hovered over the panel or one of its children), ``False`` otherwise.

Query if the panel would be minimised at a given size.

:param `at_size`: an instance of :class:`wx.Size`, giving the size at which the
 panel should be tested for minimisation.

Handles the ``wx.EVT_KILL_FOCUS`` event for children of :class:`RibbonPanel`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_MOTION`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for children of :class:`RibbonPanel`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for children of :class:`RibbonPanel`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonPanel`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonPanel`.

Realize all children of the panel.

Normally called automatically by :class:`~wx.lib.agw.ribbon.page.RibbonPage` when the panel is created, or the
art provider changed on the page. The new art provider will be propagated to the
children of the panel.

Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.

Show the panel externally expanded.

When a panel is minimised, it can be shown full-size in a pop-out window, which
is referred to as being (externally) expanded.

:returns: ``True`` if the panel was expanded, ``False`` if it was not (possibly
 due to it not being minimised, or already being expanded).

:note: When a panel is expanded, there exist two panels - the original panel
 (which is referred to as the dummy panel) and the expanded panel. The original
 is termed a dummy as it sits in the ribbon bar doing nothing, while the expanded
 panel holds the panel children.

Serves as a container for a group of (ribbon) controls.

A :class:`RibbonPanel` will typically have panels for children, with the controls for that
page placed on the panels. A panel adds a border and label to a group of controls,
and can be minimised (either automatically to conserve space, or manually by the user).

================================= =========== =================================
Window Styles                     Hex Value   Description
``RIBBON_PANEL_DEFAULT_STYLE``            0x0 Defined as no other flags set.
``RIBBON_PANEL_NO_AUTO_MINIMISE``         0x1 Prevents the panel from automatically minimising to conserve screen space.
``RIBBON_PANEL_EXT_BUTTON``               0x8 Causes an extension button to be shown in the panel's chrome (if the bar in which it is contained has ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` set). The behaviour of this button is application controlled, but typically will show an extended drop-down menu relating to the panel.
``RIBBON_PANEL_MINIMISE_BUTTON``         0x10 Causes a (de)minimise button to be shown in the panel's chrome (if the bar in which it is contained has the ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS`` style set). This flag is typically combined with ``RIBBON_PANEL_NO_AUTO_MINIMISE`` to make a panel which the user always has manual control over when it minimises.
``RIBBON_PANEL_STRETCH``                 0x20 Allows a single panel to stretch to fill the parent page.
``RIBBON_PANEL_FLEXIBLE``                0x40 Allows toolbars to wrap, taking up the optimum amount of space when used in a vertical palette.

======================================= ===================================
Event Name                              Description
``EVT_RIBBONPANEL_EXTBUTTON_ACTIVATED`` Triggered when the user activate the panel extension button.

See Also
========

:class:`~wx.lib.agw.ribbon.page.RibbonPage`

# Name:         panel.py
# Purpose:
#
#
# Created:
# Version:
# Date:

:param `panel`: an instance of :class:`RibbonPanel`;

Sets the panel relating to this event.

:param `panel`: an instance of :class:`RibbonPanel`.

A ribbon tool bar is similar to a traditional toolbar which has no labels.

It contains one or more tool groups, each of which contains one or more tools.
Each tool is represented by a (generally small, i.e. 16x15) bitmap.

====================================== ======================================
Event Name                             Description
``EVT_RIBBONTOOLBAR_CLICKED``          Triggered when the normal (non-dropdown) region of a tool on the tool bar is clicked.
``EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED`` Triggered when the dropdown region of a tool on the tool bar is clicked. LRibbonToolBarEvent.PopupMenu should be called by the event handler if it wants to display a popup menu (which is what most dropdown tools should be doing).

# Name:         toolbar.py
# Purpose:
#
#
# Created:
# Version:
# Date:

:param `style`: window style, currently unused.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="RibbonToolBar")

Add a dropdown tool to the tool bar (simple version).

:param `tool_id`: id of the new tool (used for event callbacks);
:param `bitmap`: large bitmap of the new button. Must be the same size as all
 other large bitmaps used on the button bar;
:param `help_string`: the UI help string to associate with the new button.

:see: :meth:`~RibbonToolBar.AddTool`

Add a hybrid tool to the tool bar (simple version).

Adds a separator to the tool bar.

Separators are used to separate tools into groups. As such, a separator is not
explicitly drawn, but is visually seen as the gap between tool groups.

Add a tool to the tool bar (simple version).

:param `help_string`: the UI help string to associate with the new button;
:param `kind`: the kind of button to add.

:see: :meth:`~RibbonToolBar.AddDropdownTool`, :meth:`~RibbonToolBar.AddHybridTool`, :meth:`~RibbonToolBar.AddTool`

AddSimpleTool(self, tool_id, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

Add a toggle tool to the tool bar (simple version).

Add a tool to the tool bar.

:param `bitmap`: bitmap to use as the foreground for the new tool. Does not
 have to be the same size as other tool bitmaps, but should be similar as
 otherwise it will look visually odd;
:param `bitmap_disabled`: bitmap to use when the tool is disabled. If left
 as :class:`NullBitmap`, then a bitmap will be automatically generated from `bitmap`;
:param `help_string`: the UI help string to associate with the new tool;
:param `kind`: the kind of tool to add;
:param `client_data`: client data to associate with the new tool.

:returns: An opaque pointer which can be used only with other tool bar methods.

:see: :meth:`~RibbonToolBar.AddDropdownTool`, :meth:`~RibbonToolBar.AddHybridTool`, :meth:`~RibbonToolBar.AddSeparator`

AddTool(self, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string="", kind=RIBBON_BUTTON_NORMAL, client_data=None)

:param `tool_id`: id of the tool to delete.

:see: :meth:`~RibbonToolBar.DeleteToolByPos`

This function behaves like :meth:`~RibbonToolBar.DeleteTool` but it deletes the tool at the
specified position `pos` and not the one with the given id.

Useful to delete separators.

:param `pos`: zero-based position of the tool to delete.

:see: :meth:`~RibbonToolBar.DeleteTool`

Enables or disables a single tool on the bar.

:param `tool_id`: id of the tool in question, as passed to :meth:`~RibbonToolBar.AddTool`;
:param `enable`: ``True`` to enable the tool, ``False`` to disable it.

Returns a pointer to the tool opaque structure by `tool_id` or ``None`` if
no corresponding tool is found.

:param `tool_id`: id of the tool to find.

Returns a pointer to the tool opaque structure by `pos` or ``None`` if

:param `pos`: zero-based position of the tool to retrieve.

:returns: An instance of :class:`RibbonToolBarToolBase` if the tool was found,
 ``None`` if it was not found.

Get any client data associated with the tool.

:param `tool_id`: id of the tool in question, as passed to :meth:`~RibbonToolBar.AddTool`.

:return: Client data (any Python object), or ``None`` if there is none.

Returns the number of tools in this :class:`RibbonToolBar`.

Called to determine whether a tool is enabled (responds to user input).

:return: ``True`` if the tool was found and it is enabled, ``False`` otherwise.

Returns the tool short help string.

Returns the tool id for the specified input `tool`.

:param `tool`: an instance of :class:`RibbonToolBarToolBase`.

Returns the kind of the given tool.

Returns the tool position in the toolbar, or ``wx.NOT_FOUND`` if the tool is not found.

Gets the on/off state of a toggle tool.

:return: ``True`` if the tool is toggled on, ``False`` otherwise.

:see: :meth:`~RibbonToolBar.ToggleTool`

Inserts a dropdown tool in the tool bar at the position specified by `pos`.

:param `pos`: the position of the new tool in the toolbar (zero-based);

:see: :meth:`~RibbonToolBar.AddTool`, :meth:`~RibbonToolBar.InsertTool`

Inserts a hybrid tool in the tool bar at the position specified by `pos`.

Inserts a separator into the tool bar at the position specified by `pos`.

:param `pos`: the position of the new tool in the toolbar (zero-based).

Inserts a toggle tool in the tool bar at the position specified by `pos`.

Inserts a tool in the tool bar at the position specified by `pos`.

:see: :meth:`~RibbonToolBar.AddTool`, :meth:`~RibbonToolBar.AddDropdownTool`, :meth:`~RibbonToolBar.AddHybridTool`, :meth:`~RibbonToolBar.AddSeparator`

InsertTool(self, pos, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string="", kind=RIBBON_BUTTON_NORMAL, client_data=None)

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`RibbonToolBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`RibbonToolBar`.

Calculates tool layouts and positions.

Must be called after tools are added to the tool bar, as otherwise the newly
added tools will not be displayed.

Set the number of rows to distribute tool groups over.

Tool groups can be distributed over a variable number of rows. The way in which
groups are assigned to rows is not specified, and the order of groups may
change, but they will be distributed in such a way as to minimise the overall
size of the tool bar.

:param `nMin`: the minimum number of rows to use;
:param `nMax`: the maximum number of rows to use (defaults to `nMin`).

Sets the client data associated with the tool.

:param `clientData`: any Python object.

Sets the bitmap to be used by the tool with the given ID when the tool is in a disabled state.

:param `bitmap`: an instance of :class:`wx.Bitmap`.

Sets the tool short help string.

:param `helpString`: a string for the help.

Sets the bitmap to be used by the tool with the given ID when the tool is enabled.

Toggles on or off a single tool on the bar.

:param `checked`: ``True`` to toggle on the tool, ``False`` to toggle it off.

example of how to call :meth:`~RibbonToolBar.UpdateWindowUI` from an idle function::

:param `bar`: an instance of :class:`RibbonToolBar`.

Pops up the given menu and returns control when the user has dismissed the menu.

If a menu item is selected, the corresponding menu event is generated and will
be processed as usual.

:param `menu`: the menu to pop up, an instance of :class:`wx.Menu`.

:note: Just before the menu is popped up, :meth:`wx.Menu.UpdateUI` is called to ensure
 that the menu items are in the correct state. The menu does not get deleted by
 the window.

Sets the current :class:`RibbonToolBar` for this event.

:class:`~wx.lib.agw.advancedsplash.AdvancedSplash` tries to reproduce the behavior of :class:`~adv.SplashScreen`, with
some enhancements.

:class:`AdvancedSplash` tries to reproduce the behavior of :class:`~adv.SplashScreen`, but with
some enhancements (in my opinion).

:class:`AdvancedSplash` starts its construction from a simple frame. Then, depending on
the options passed to it, it sets the frame shape accordingly to the image passed
as input. :class:`AdvancedSplash` behaves somewhat like :class:`~adv.SplashScreen`, and almost
all the methods available in :class:`~adv.SplashScreen` are available also in
this module.

Usage
=====

Sample usage::

    import wx
    import wx.lib.agw.advancedsplash as AS

    frame = wx.Frame(None, -1, "AdvancedSplash Test")

    imagePath = "my_splash_image.png"
    bitmap = wx.Bitmap(imagePath, wx.BITMAP_TYPE_PNG)
    shadow = wx.WHITE

    splash = AS.AdvancedSplash(frame, bitmap=bitmap, timeout=5000,
                               agwStyle=AS.AS_TIMEOUT |
                               AS.AS_CENTER_ON_PARENT |
                               AS.AS_SHADOW_BITMAP,
                               shadowcolour=shadow)

None of the options are strictly required (a part of the `bitmap` parameter).
If you use the defaults you get a very simple :class:`AdvancedSplash`.

Methods and Settings

:class:`AdvancedSplash` is customizable, and in particular you can set:

- Whether you want to mask a colour or not in your input bitmap;
- Where to center the splash screen (on screen, on parent or nowhere);
- Whether it is a "timeout" splashscreen or not;
- The time after which :class:`AdvancedSplash` is destroyed (if it is a timeout splashscreen);
- The (optional) text you wish to display;
- The font, colour and position of the displayed text (optional).

======================= =========== ==================================================
Window Styles           Hex Value   Description
``AS_TIMEOUT``                  0x1 :class:`AdvancedSplash` will be destroyed after `timeout` milliseconds.
``AS_NOTIMEOUT``                0x2 :class:`AdvancedSplash` can be destroyed by clicking on it, pressing a key or by explicitly call the `Close()` method.
``AS_CENTER_ON_SCREEN``         0x4 :class:`AdvancedSplash` will be centered on screen.
``AS_CENTER_ON_PARENT``         0x8 :class:`AdvancedSplash` will be centered on parent.
``AS_NO_CENTER``               0x10 :class:`AdvancedSplash` will not be centered.
``AS_SHADOW_BITMAP``           0x20 If the bitmap you pass as input has no transparency, you can choose one colour that will be masked in your bitmap. the final shape of :class:`AdvancedSplash` will be defined only by non-transparent (non-masked) pixels.

`No custom events are available for this class.`

:class:`AdvancedSplash` control is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 19 Dec 2012, 21.00 GMT

Version 0.5

# ADVANCEDSPLASH Control wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 10 Oct 2005
# Latest Revision: 19 Dec 2012, 21.00 GMT
#
#
# TODO List/Caveats
#
# 1. Actually, Setting The Shape Of AdvancedSplash Is Done Using "SetShape"
#    Function On A Frame. This Works, AFAIK, On This Following Platforms:
#
#    - MSW
#    - UNIX/Linux
#    - MacOS Carbon
#
#    Obviously I May Be Wrong Here. Could Someone Verify That Lines 139-145
#    Work Correctly On Other Platforms Than Mine (MSW XP/2000)?
#    Moreover, Is There A Way To Avoid The Use Of The "SetShape" Method?
#    I Don't Know.
#
#
#
#
#
#

:class:`AdvancedSplash` tries to reproduce the behavior of :class:`~adv.SplashScreen`, with

This is the main class implementation.

:param `parent`: parent window;
:param integer `style`: the underlying :class:`wx.Frame` style;
:param `bitmap`: this must be a valid bitmap, that you may construct using
 whatever image file format supported by wxPython. If the file you load
 already supports mask/transparency (like png), the transparent areas
 will not be drawn on screen, and the :class:`AdvancedSplash` frame will have
 the shape defined only by *non-transparent* pixels.
 If you use other file formats that does not supports transparency, you
 can obtain the same effect as above by masking a specific colour in
 your :class:`wx.Bitmap`.
:param integer `timeout`: if you construct :class:`AdvancedSplash` using the style ``AS_TIMEOUT``,
 :class:`AdvancedSplash` will be destroyed after `timeout` milliseconds;
:param integer `agwStyle`: this value specifies the :class:`AdvancedSplash` styles:

 ======================= =========== ==================================================
 Window Styles           Hex Value   Description
 ``AS_TIMEOUT``                  0x1 :class:`AdvancedSplash` will be destroyed after `timeout` milliseconds.
 ``AS_NOTIMEOUT``                0x2 :class:`AdvancedSplash` can be destroyed by clicking on it, pressing a key or by explicitly call the `Close()` method.
 ``AS_CENTER_ON_SCREEN``         0x4 :class:`AdvancedSplash` will be centered on screen.
 ``AS_CENTER_ON_PARENT``         0x8 :class:`AdvancedSplash` will be centered on parent.
 ``AS_NO_CENTER``               0x10 :class:`AdvancedSplash` will not be centered.
 ``AS_SHADOW_BITMAP``           0x20 If the bitmap you pass as input has no transparency, you can choose one colour that will be masked in your bitmap. the final shape of :class:`AdvancedSplash` will be defined only by non-transparent (non-masked) pixels.

:param `shadowcolour`: if you construct :class:`AdvancedSplash` using the style
 ``AS_SHADOW_BITMAP``, here you can specify the colour that will be masked on
 your input bitmap. This has to be a valid wxPython colour.

:type bitmap: :class:`wx.Bitmap`
:type shadowcolour: :class:`wx.Colour`

:raise: `Exception` in the following cases:

 - The ``AS_TIMEOUT`` style is set but `timeout` is not a positive integer;
 - The ``AS_SHADOW_BITMAP`` style is set but `shadowcolour` is not a valid wxPython colour;
 - The :class:`AdvancedSplash` bitmap is an invalid :class:`wx.Bitmap`.

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.FRAME_NO_TASKBAR | wx.FRAME_SHAPED | wx.STAY_ON_TOP, bitmap=None, timeout=5000, agwStyle=AS_TIMEOUT | AS_CENTER_ON_SCREEN, shadowcolour=wx.NullColour)

Returns a list of strings and a list of integers containing the styles.

:return: Two Python lists containing the style name and style values for :class:`AdvancedSplash`.

Returns the text displayed on :class:`AdvancedSplash`.

:return: A string representing the text drawn on top of the :class:`AdvancedSplash` bitmap.

Gets the colour for the text in :class:`AdvancedSplash`.

:return: An instance of :class:`wx.Colour`.

Gets the font for the text in :class:`AdvancedSplash`.

:return: An instance of :class:`wx.Font` to draw the text and a :class:`wx.Size` object containing
 the text width an height, in pixels.

Returns the text position inside :class:`AdvancedSplash` frame.

:return: A tuple containing the text `x` and `y` position inside the :class:`AdvancedSplash` frame.

Handles the ``wx.EVT_CHAR`` event for :class:`AdvancedSplash`.

:param `event`: a :class:`KeyEvent` to be processed.

:note: This reproduces the behavior of :class:`~adv.SplashScreen`.

Handles the ``wx.EVT_CLOSE`` event for :class:`AdvancedSplash`.

Handles the ``wx.EVT_MOUSE_EVENTS`` events for :class:`AdvancedSplash`.

Handles the timer expiration, and calls the `Close()` method.

:param `event`: a :class:`wx.TimerEvent` to be processed.

Handles the ``wx.EVT_PAINT`` event for :class:`AdvancedSplash`.

Sets :class:`AdvancedSplash` shape using the region created from the bitmap.

:param `event`: a :class:`wx.WindowCreateEvent` event (GTK only, as GTK supports setting
 the window shape only during window creation).

Sets the text to be displayed on :class:`AdvancedSplash`.

:param `text`: the text we want to display on top of the bitmap. If `text` is
 set to ``None``, nothing will be drawn on top of the bitmap.
:type text: string or ``None``

Sets the colour for the text in :class:`AdvancedSplash`.

:param `colour`: the text colour to use while drawing the text on top of our
 bitmap. If `colour` is ``None``, then ``wx.BLACK`` is used.
:type colour: :class:`wx.Colour` or ``None``

Sets the font for the text in :class:`AdvancedSplash`.

:param `font`: the font to use while drawing the text on top of our bitmap. If `font`
 is ``None``, a simple generic font is generated.
:type font: :class:`wx.Font` or ``None``

Sets the text position inside :class:`AdvancedSplash` frame.

:param `position`: the text position inside our bitmap. If `position` is ``None``,
 the text will be placed at the top-left corner.
:type position: tuple or ``None``

Applies a mask on the bitmap accordingly to user input.

:param `bmp`: the bitmap to which we want to apply the mask colour `shadowcolour`;
:param `shadowcolour`: the mask colour for our bitmap.
:type bmp: :class:`wx.Bitmap`

:return: A masked version of the input bitmap, an instance of :class:`wx.Bitmap`.

:class:`~wx.lib.agw.aquabutton.AquaButton` is another custom-drawn button class which *approximately* mimics
the behaviour of Aqua buttons on the Mac.

:class:`AquaButton` is another custom-drawn button class which *approximately* mimics
the behaviour of Aqua buttons on the Mac. At the moment this class supports:

* Bubble and shadow effects;
* Customizable background, foreground and hover colours;
* Rounded-corners buttons;
* Text-only or image+text buttons;
* Pulse effect on gaining focus.

And a lot more. Check the demo for an almost complete review of the functionalities.

Usage
=====

    import wx
    import wx.lib.agw.aquabutton as AB

    frame = wx.Frame(None, -1, "AquaButton Test")

    mainPanel = wx.Panel(frame)
    mainPanel.SetBackgroundColour(wx.WHITE)

    # Initialize AquaButton 1 (with image)
    bitmap = wx.Bitmap("my_button_bitmap.png", wx.BITMAP_TYPE_PNG)
    btn1 = AB.AquaButton(mainPanel, -1, bitmap, "AquaButton")

    # Initialize AquaButton 2 (no image)
    btn2 = AB.AquaButton(mainPanel, -1, None, "Hello World!")

Supported Platforms

AquaButton has been tested on the following platforms:
  * Windows (Windows XP);
  * Linux Ubuntu (10.10).

`No particular window styles are available for this class.`

================= ==================================================
Event Name        Description
``wx.EVT_BUTTON`` Process a `wxEVT_COMMAND_BUTTON_CLICKED` event, when the button is clicked.

:class:`AquaButton` control is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.4

# AQUABUTTON wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 07 October 2008
#
#
# TODO List
#
# 1) Anything to do?
#
#
# For all kind of problems, requests of enhancements and bug reports, please
# write to me at:
#
#
# Or, obviously, to the wxPython mailing list!!!
#
#

A mixin that allows to transform :class:`AquaButton` in the corresponding toggle button.

Returns the toggled state of a button.

:return: ``True`` is the button is toggled, ``False`` if it is not toggled.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`AquaButton` when used as toggle button.

Handles the ``wx.EVT_KEY_UP`` event for :class:`AquaButton` when used as toggle button.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AquaButton` when used as toggle button.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`AquaButton` when used as toggle button.

Handles the ``wx.EVT_MOTION`` event for :class:`AquaButton` when used as toggle button.

Handles the ``wx.EVT_PAINT`` event for :class:`AquaButton` when used as toggle button.

Sets the button as toggled/not toggled.

:param bool `flag`: ``True`` to set the button as toggled, ``False`` otherwise.

:param wx.Window `parent`: parent window. Must not be ``None``;
:param wx.Bitmap `bitmap`: the button bitmap (if any);
:param string `label`: the button text label;
:param integer `style`: the button style (unused);
:param wx.Validator `validator`: the validator associated to the button;

__init__(self, parent, id=wx.ID_ANY, bitmap=None, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, validator=wx.DefaultValidator, name="aquabutton")

Can this window be given focus by mouse click?

Overridden base class virtual.

Need to Refresh otherwise Enable state change done from a
`wx.EVT_UPDATE_UI` will not show.

Overridden base class virtual. Determines the best size of the
button based on the label and bezel size.

Enables/disables the button.

Returns the button colour when the mouse is not hovering on the button.

Overridden base class virtual. By default we should use
the same font/colour attributes as the native :class:`Button`.

:return: an instance of :class:`VisualAttributes`.

Returns the button colour when it is disabled.

Returns the button colour when the button has focus.

Returns the text colour for :class:`AquaButton`.

Returns the button colour when the mouse is hovering on the button.

Returns a rounded :class:`GraphicsPath` rectangle.

:param `gc`: an instance of :class:`GraphicsContext`;
:param wx.Rect `rc`: a client rectangle;
:param float `r`: the radius of the rounded part of the rectangle.

:return: A rounded rectangle, an instance of :class:`GraphicsPath`.

Returns whether the pulsing effect is active.

:return: ``True`` if the pulsing effect is active, ``False`` otherwise.

Returns the button rectangular background colour.

Returns the button shadow colour.

Return light contrast of `colour`. The colour returned is from the scale of
`colour` ==> white.

:param `colour`: the input colour to be brightened, a valid instance of :class:`wx.Colour`;
:param integer `percent`: determines how light the colour will be. `percent` = ``100``
 returns white, `percent` = ``0`` returns `colour`.

:return: A light contrast of the input `colour`, an instance of :class:`wx.Colour`.

Actually sends a ``wx.EVT_BUTTON`` event to the listener (if any). 

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`AquaButton`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`AquaButton`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`AquaButton`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AquaButton`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`AquaButton`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`AquaButton`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`AquaButton`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`AquaButton`.

Handles the ``wx.EVT_PAINT`` event for :class:`AquaButton`.

Handles the ``wx.EVT_TIMER`` event for :class:`AquaButton`.

:param `event`: a :class:`TimerEvent` event to be processed.

:note: This method is only invoked when `pulseOnFocus` is ``True``.

Handles the ``wx.EVT_SIZE`` event for :class:`AquaButton`.

Sets the :class:`AquaButton` background colour.

:param `colour`: a valid :class:`wx.Colour` object.

Sets the bitmap label for the button.

:param `bitmap`: the bitmap label to set, an instance of :class:`wx.Bitmap`.

This sets the :class:`AquaButton` to be the default item for the panel or dialog box.

:note: Under Windows, only dialog box buttons respond to this function. As normal
 under Windows and Motif, pressing return causes the default button to be depressed
 when the return key is pressed. See also :meth:`wx.Window.SetFocus` which sets the
 keyboard focus for windows and text panel items, and :meth:`TopLevelWindow.SetDefaultItem`.

:note: Note that under Motif, calling this function immediately after creation of a button
 and before the creation of other buttons will cause misalignment of the row of buttons,
 since default buttons are larger. To get around this, call :meth:`SetDefault` after you
 have created a row of buttons: wxPython will then set the size of all buttons currently
 on the panel to the same size.

Sets the button colour when it is disabled.

Sets the button colour when the button has focus.

Sets the :class:`AquaButton` foreground (text) colour.

Sets the button colour when the mouse is hovering on the button.

Given the current font and bezel width settings, calculate
and set a good size.

:param `size`: an instance of :class:`wx.Size` or ``None``, in which case the wxWidgets
 :class:`DefaultSize` is used instead.

Sets whether to enable the pulsing effect on gaining focus or not.

:param bool `pulse`: ``True`` to enable pulsing when the :class:`AquaButton` gains focus,
 ``False`` to disable this effect.

Sets the button rectangular background colour.

Sets the button shadow colour.

Overridden base class virtual. Buttons usually don't inherit
the parent's colours.

Event sent from the :class:`AquaButton` buttons when the button is activated. 

:param integer `eventType`: the event type;
:param integer `eventId`: the event identifier.

Returns the object associated with this event.

:return: An instance of :class:`AquaButton`.

Sets the event object for the event.

:param `btn`: the button object, an instance of :class:`AquaButton`.

This module contains drawing routines and customizations for the AGW widgets
:class:`~wx.lib.agw.labelbook.LabelBook` and :class:`~wx.lib.agw.flatmenu.FlatMenu`.

This class provides various art utilities, such as creating shadow, providing
lighter / darker colours for a given colour, etc...

Adds a new theme to the stock.

:param `render`: a rendering theme class, which must be derived from
 :class:`RendererBase`.

:return: An integer representing the size of the renderers dictionary.

Returns the background colour of a control when not in focus.

Returns the best fit size for the supplied label & bitmap.

:param string `label`: the button label;
:param `bmp`: the bitmap associated with the button, an instance of :class:`wx.Bitmap`.

:return: An instance of :class:`wx.Size`, representing the best fit size for the supplied label & bitmap.

Used internally.

:return: ``True`` if the system supports transparency of toplevel windows,
 otherwise returns ``False``.

Convert the given image to a bitmap, optionally overlaying an alpha
channel to it.

:param `xpm`: a list of strings formatted as XPM;
:type `xpm`: list of strings
:param `alpha`: a list of alpha values, the same size as the xpm bitmap.
:type `alpha`: list of integers

:return: An instance of :class:`wx.Bitmap`.

Creates a grey bitmap image from the input bitmap.

:param `bmp`: a valid :class:`wx.Bitmap` object to be greyed out.

:return: A greyed-out representation of the input bitmap, an instance of :class:`wx.Bitmap`.

Like the :meth:`~ArtManager.LightColour` function, but create the colour darker by `percent`.

:param `colour`: the input colour to be darkened, an instance of :class:`wx.Colour`;
:param integer `percent`: determines how dark the colour will be. `percent` = ``100``
 returns black, `percent` = ``0`` returns `colour`.

:return: A dark contrast of the input `colour`, an instance of :class:`wx.Colour`.

Draws a shadow using background bitmap.

:param `dc`: an instance of :class:`wx.DC`;
:param wx.Rect `rect`: the bitmap's client rectangle;
:param integer `where`: where to draw the shadow. This can be any combination of the

 ========================== ======= ================================
 Shadow Settings             Value  Description
 ``RightShadow``                  1 Right side shadow
 ``BottomShadow``                 2 Not full bottom shadow
 ``BottomShadowFull``             4 Full bottom shadow

DrawBitmapShadow(self, dc, rect, where=BottomShadow|RightShadow)

Colour rectangle according to the theme.

:param wx.Rect `rect`: the rectangle to be filled with gradient shading;
:param string `theme`: the theme to use to draw the button;
:param integer `state`: the button state;
:param `input`: a flag used to call the right method.

Draws a button using the appropriate theme.

:param wx.Rect `rect`: the button's client rectangle;
:param `colour`: a valid :class:`wx.Colour` instance.

:param bool  `useLightColours`: ``True`` to use light colours, ``False`` otherwise.

DrawButtonTheme(self, dc, rect, theme, state, useLightColours=True)

Draws resize sash.

:param wx.Rect `rect`: the sash client rectangle.

Draws the menu bar background according to the active theme.

:param wx.Rect `rect`: the menubar's client rectangle.

Enables menu border drawing (XP style only).

:param bool `border`: ``True`` to draw the menubar border, ``False`` otherwise.

Draws the text & bitmap on the input dc.

:param wx.Rect `rect`: the text and bitmap client rectangle;
:param string `text`: the button label;
:param bool `enable`: ``True`` if the button is enabled, ``False`` otherwise;
:param `font`: the font to use to draw the text, an instance of :class:`wx.Font`;
:param `fontColour`: the colour to use to draw the text, an instance of
 :class:`wx.Colour`;
:param `bitmap`: the bitmap associated with the button, an instance of :class:`wx.Bitmap`;
:param `grayBitmap`: a greyed-out version of the input `bitmap` representing
 a disabled bitmap, an instance of :class:`wx.Bitmap`;
:param integer `style`: the button style.

:see: :meth:`~ArtManager.GetBitmapStartLocation` for a list of valid button styles.

DrawTextAndBitmap(self, dc, rect, text, enable=True, font=wx.NullFont, fontColour=wx.BLACK, bitmap=wx.NullBitmap, grayBitmap=wx.NullBitmap, style=0)

Draws the toolbar background according to the active theme.

:param wx.Rect `rect`: the toolbar's client rectangle.

Adds a shadow under the window (Windows only).

:param `wnd`: the window for which we are dropping a shadow, an instance of :class:`TopLevelWindow`;
:param bool `drop`: ``True`` to drop a shadow, ``False`` to remove it.

Return the surrounding colour for a control.

Returns the mnemonic index of the label and the label stripped of the ampersand mnemonic
(e.g. 'lab&el' ==> will result in 3 and labelOnly = label).

:param string `label`: a string containing an ampersand.

:return: A tuple containing the mnemonic index of the label and the label
 stripped of the ampersand mnemonic.

Return the padding buffer for a text or bitmap.

:return: An integer representing the padding buffer.

Returns the top left `x` and `y` coordinates of the bitmap drawing.

:param wx.Bitmap `bitmap`: the bitmap associated with the button;
:param integer `style`: the button style. This can be one of the following bits:

 ============================== ======= ================================
 Button style                    Value  Description
 ``BU_EXT_XP_STYLE``               1    A button with a XP style
 ``BU_EXT_2007_STYLE``             2    A button with a MS Office 2007 style
 ``BU_EXT_LEFT_ALIGN_STYLE``       4    A left-aligned button
 ``BU_EXT_CENTER_ALIGN_STYLE``     8    A center-aligned button
 ``BU_EXT_RIGHT_ALIGN_STYLE``      16   A right-aligned button
 ``BU_EXT_RIGHT_TO_LEFT_STYLE``    32   A button suitable for right-to-left languages

:return: A tuple containing the top left `x` and `y` coordinates of the bitmap drawing.

GetBitmapStartLocation(self, dc, rect, bitmap, text="", style=0)

Returns the available colour schemes.

:return: A list of strings representing the available colour schemes.

Returns the font used by this theme.

:return: An instance of :class:`wx.Font`.

Returns ``True`` if the menu bar should be painted with vertical gradient. 

Returns menu bar border drawing flag.

:return: ``True`` if the menu bar border is to be drawn, ``False`` otherwise.

Returns the current colour scheme.

:return: A string representing the current colour scheme.

Returns the menu bar face colour.

Returns the menu bar selection colour.

Gets the visibility depth of the menu in Metallic style.
The higher the value, the menu bar will look more raised

Returns the colour used for the menu foreground.

Returns the currently used menu theme.

:return: A string containing the currently used theme for the menu.

Returns the sunken flag for MS 2007 buttons.

:return: ``True`` if the MS 2007 buttons are sunken, ``False`` otherwise.

Returns a bitmap from a stock.

:param string `name`: the bitmap name.

:return: The stock bitmap, if `name` was found in the stock bitmap dictionary.
 Otherwise, :class:`NullBitmap` is returned.

Returns the colour used for disabled menu items.

Returns the colour used for enabled menu items.

Returns the top left `x` and `y` coordinates of the text drawing.
In case the text is too long, the text is being fixed (the text is cut and
a '...' mark is added in the end).

:param wx.Rect `rect`: the text's client rectangle;

:return: A tuple containing the top left `x` and `y` coordinates of the text drawing, plus
 the truncated version of the input `text`.

Returns the theme (Blue, Silver, Green etc.) base colour, if no theme is active
it return the active caption colour, lighter in 30%.

:param bool `useLightColours`: ``True`` to use light colours, ``False`` otherwise.

Returns the alpha channel value for transparent windows.

:return: An integer representing the alpha channel value.

Returns the background colour of a control when it is in focus.

Returns whether a colour is dark or light.

:param `colour`: an instance of :class:`wx.Colour`.

:return: ``True`` if the average RGB values are dark, ``False`` otherwise.

:param `colour`: the input colour to be brightened, an instance of :class:`wx.Colour`;

Used internally. Makes a toplevel window transparent if the system supports it.

:param `wnd`: the toplevel window to make transparent, an instance of :class:`TopLevelWindow`;
:param integer `amount`: the window transparency to apply.

Return mix of input colours.

:param `firstColour`: the first colour to be mixed, an instance of :class:`wx.Colour`;
:param `secondColour`: the second colour to be mixed, an instance of :class:`wx.Colour`;
:param integer `percent`: the relative percentage of `firstColour` with respect to
 `secondColour`.

Handles the ``wx.EVT_SYS_COLOUR_CHANGED`` event for :class:`ArtManager`.

:param `event`: a :class:`SysColourChangedEvent` event to be processed.

Paint a region with gradient colouring. The gradient is in crescent shape
which fits the 2007 style.

:param wx.Colour `startColour`: the first colour of the gradient shading;
:param wx.Colour `endColour`: the second colour of the gradient shading;
:param bool `concave`: ``True`` for a concave effect, ``False`` for a convex one.

PaintCrescentGradientBox(self, dc, rect, startColour, endColour, concave=True)

Paint rectangle with gradient colouring; the gradient lines are diagonal
and may start from the upper left corner or from the upper right corner.

:param bool `startAtUpperLeft`: ``True`` to start the gradient lines at the upper
 left corner of the rectangle, ``False`` to start at the upper right corner;
:param bool `trimToSquare`: ``True`` to trim the gradient lines in a square.

PaintDiagonalGradientBox(self, dc, rect, startColour, endColour, startAtUpperLeft=True, trimToSquare=True)

Paint a region with gradient colouring.

:param `region`: a region to be filled with gradient shading (an instance of
 :class:`Region`);
:param bool `vertical`: ``True`` for gradient colouring in the vertical direction,
 ``False`` for horizontal shading.

PaintGradientRegion(self, dc, region, startColour, endColour, vertical=True)

Paint the rectangle with gradient colouring; the gradient lines are either
horizontal or vertical.

PaintStraightGradientBox(self, dc, rect, startColour, endColour, vertical=True)

Creates a random colour.

Sets the menu bar gradient style.

:param bool `v`: ``True`` for a vertical shaded gradient, ``False`` otherwise.

Sets the menu bar colour scheme to use.

:param string `scheme`: a string representing a colour scheme (i.e., 'Default',
 'Dark', 'Dark Olive Green', 'Generic').

Set the menu theme, possible values (Style2007, StyleXP, StyleVista).

:param string `theme`: a rendering theme class, either `StyleXP`, `Style2007` or `StyleVista`.

Sets MS 2007 button style sunken or not.

:param bool `sunken`: ``True`` to have a sunken border effect, ``False`` otherwise.

Enables/disables toobar shadow drop.

:param bool `rais`: ``True`` to drop a shadow below a toolbar, ``False`` otherwise.

Sets the alpha channel value for transparent windows.

:param integer `amount`: the actual transparency value (between 0 and 255).

:raise: `Exception` if the `amount` parameter is lower than ``0`` or greater than ``255``.

Takes a screenshot of the screen at given position & size (rect).

:param wx.Rect `rect`: the screen rectangle we wish to capture;
:param wx.Bitmap `bmp`: currently unused.

Truncates a given string to fit given width size. if the text does not fit
into the given width it is truncated to fit. The format of the fixed text
is ``truncate text ...``.

:param string `text`: the text to be (eventually) truncated;
:param integer `maxWidth`: the maximum width allowed for the text.

:return: A new string containing the (possibly) truncated text.

Always returns False.

BytesIO objects are not connected to a TTY-like device.

Read at most size bytes, returned as a bytes object.

If the size argument is negative, read until EOF is reached.
Return an empty bytes object at EOF.

If the size argument is negative or omitted, read until EOF is reached.

Read bytes into buffer.

Returns number of bytes read (0 for EOF), or None if the object
is set not to block and has no data to read.

Next line from the file, as a bytes object.

Retain newline.  A non-negative size argument limits the maximum
number of bytes to return (an incomplete line may be returned then).

List of bytes objects, each a line from the file.

Call readline() repeatedly and return a list of the lines so read.
The optional size argument, if given, is an approximate bound on the
total number of bytes in the lines returned.

Change stream position.

Seek to byte offset pos relative to position indicated by whence:
     0  Start of stream (the default).  pos should be >= 0;
     1  Current position - pos may be negative;
     2  End of stream - pos usually negative.
Returns the new absolute position.

Truncate the file to at most size bytes.

Size defaults to the current file position, as returned by tell().
The current file position is unchanged.  Returns the new size.

Write lines to the file.

Note that newlines are not added.  lines can be any iterable object
producing bytes-like objects. This is equivalent to calling write() for
each element.

:param `pdc`: an instance of :class:`wx.DC`.

Draws the area below a bitmap and the bitmap itself using a gradient shading.

:param string `xpm_name`: a name of a XPM bitmap;
:param wx.Rect `rect`: the bitmap client rectangle;
:param `baseColour`: a valid :class:`wx.Colour` for the bitmap background;
:param bool `flipSide`: ``True`` to flip the gradient direction, ``False`` otherwise.

Draws borders for a bitmap.

:param `penColour`: a valid :class:`wx.Colour` for the pen border;
:param `bitmapBorderUpperLeftPen`: a valid :class:`wx.Colour` for the pen upper
 left border.

DrawBitmapBorders(self, dc, rect, penColour, bitmapBorderUpperLeftPen)

Draws borders for buttons.

:param `brushColour`: a valid :class:`wx.Colour` for the brush.

Returns the font used for text.

Returns the foreground colour for the menu.

Returns the colour used for text colour when disabled.

Returns the colour used for text colour when enabled.

Draws a button using the MS Office 2007 theme.

:param wx.Rect `rect`: the menu bar's client rectangle.

Returns a :class:`wx.Colour` according to the menu item state.

:param integer `state`: one of the following bits:

 ==================== ======= ==========================
 Item State            Value  Description
 ``ControlPressed``         0 The item is pressed
 ``ControlFocus``           1 The item is focused
 ``ControlDisabled``        2 The item is disabled
 ``ControlNormal``          3 Normal state

Draws a button using the XP theme.

[b'16 16 3 1', b'. c Black', b'X c #FFFFFF', b'  c #008080', b'                ', b'                ', b'                ', b'                ', b'    .......     ', b'    XXXXXXX     ', b'                ', b'    .......     ', b'    X.....X     ', b'     X...X      ', b'      X.X       ', b'       X        ', b'                ', b'                ', b'                ', b'                ']

[b'    16    16       16            1', b'` c #000000', b'. c #800000', b'# c #008000', b'a c #808000', b'b c #000080', b'c c #800080', b'd c #008080', b'e c #808080', b'f c #c0c0c0', b'g c #ff0000', b'h c #00ff00', b'i c #ffff00', b'j c #0000ff', b'k c #ff00ff', b'l c #00ffff', b'm c #ffffff', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmm`mmmmm', b'mmmmmmmmm``mmmmm', b'mmmm`mmm```mmmmm', b'mmmm``m```mmmmmm', b'mmmm`````mmmmmmm', b'mmmmm```mmmmmmmm', b'mmmmmm`mmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm']

[b'16 16 2 1', b'. c Black', b'  c White', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ', b'     .....      ', b'      ...       ', b'       .        ', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ']

[b'    16    16        8            1', b'` c #ffffff', b'. c #000000', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'``````.`````````', b'``````..````````', b'``````...```````', b'``````....``````', b'``````...```````', b'``````..````````', b'``````.`````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

[b'16 16 2 1', b'. c Black', b'  c White', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ', b'       .        ', b'      ...       ', b'     .....      ', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ', b'                ']

[b'    16    16        8            1', b'` c #ffffff', b'. c #000000', b'# c #808080', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````.......`````', b'````.``##..`````', b'````.``##..`````', b'````.``##..`````', b'````.``##..`````', b'````.``##..`````', b'``...........```', b'``````...```````', b'``````...```````', b'```````.````````', b'```````.````````', b'```````.````````', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #ffffff', b'. c #000000', b'# c #808080', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'```````.````````', b'```````.````````', b'```````.......``', b'```````.`````.``', b'`````...`````.``', b'``......#####.``', b'`````...#####.``', b'```````.......``', b'```````.......``', b'```````.````````', b'```````.````````', b'````````````````', b'````````````````', b'````````````````']

[b'    16    16       16            1', b'` c #000000', b'. c #800000', b'# c #008000', b'a c #808000', b'b c #000080', b'c c #800080', b'd c #008080', b'e c #808080', b'f c #c0c0c0', b'g c #ff0000', b'h c #00ff00', b'i c #ffff00', b'j c #0000ff', b'k c #ff00ff', b'l c #00ffff', b'm c #ffffff', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmm```mmmmmmm', b'mmmmm`````mmmmmm', b'mmmmm`````mmmmmm', b'mmmmmm```mmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm', b'mmmmmmmmmmmmmmmm']

[b'10 5 1 1', b'  c Black', b'          ', b'          ', b'          ', b'          ', b'          ']

[b'5 5 1 1', b'  c Black', b'     ', b'     ', b'     ', b'     ', b'     ']

[b'5 10 1 1', b'  c Black', b'     ', b'     ', b'     ', b'     ', b'     ', b'     ', b'     ', b'     ', b'     ', b'     ']

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

: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
=====

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

            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)

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

BalloonTip is distributed under the wxPython license.

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

Version 0.3

# BALLOONTIP wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 29 May 2005
# Latest Revision: 16 Jul 2012, 15.00 GMT
#
#
#
# 1. With wx.ListBox (And Probably Other Controls), The BalloonTip Sometimes
#    Flashes (It Is Created And Suddenly Destroyed). I Don't Know What Is
#    Happening. Probably I Don't Handle Correctly The wx.EVT_ENTER_WINDOW
#    wx.EVT_LEAVE_WINDOW?
#
# 2. wx.RadioBox Seems Not To Receive The wx.EVT_ENTER_WINDOW Event
#
# 3. wx.SpinCtrl (And Probably Other Controls), When Put In A Sizer, Does Not
#    Return The Correct Size/Position. Probably Is Something I Am Missing.
#
# 4. Other Issues?
#
#
# FIXED Problems
#
# 1. Now BalloonTip Control Works Also For TaskBarIcon (Thanks To Everyone
#    For The Suggetions I Read In The wxPython Mailing List)
#
#
#
#
#
# Tags:        phoenix-port, unittest, documented
#

This class is called by the main :class:`BalloonTip` class, and it is
responsible for the frame creation/positioning on screen
depending on target control/window, the frame can position
itself to NW (default), NE, SW, SE. The switch on positioning
is done by calculating the absolute position of the target
control/window plus/minus the balloontip size. The pointing
arrow is positioned accordingly.

Used internally. Do not call directly this class in your application!

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, classparent=None)

Handles the ``wx.EVT_CLOSE`` event for :class:`BalloonTip`.

Handles the ``wx.EVT_ENTER_WINDOW`` for the :class:`BalloonTip` button.

When the :class:`BalloonTip` is created with the `tipstyle` = ``BT_BUTTON``, this event
provide some kind of 3D effect when the mouse enters the button area.

Handles the ``wx.EVT_LEAVE_WINDOW`` for the :class:`BalloonTip` button.

Sets the balloon shape.

window.

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

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

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

The destruction timer has expired. Destroys the :class:`BalloonTip` frame.

Enable/disable globally the :class:`BalloonTip`.

:param bool `enable`: ``True`` to enable :class:`BalloonTip`, ``False`` otherwise.

Returns the :class:`BalloonTip` background colour.

Returns the :class:`BalloonTip` top-left icon.

Returns the :class:`BalloonTip` tip message.

:return: A string containing the main message.

Returns the :class:`BalloonTip` frame shape.

:return: An integer, one of ``BT_ROUNDED``, ``BT_RECTANGLE``.

Returns the :class:`BalloonTip` `tipstyle` parameter.

:return: An integer representing the style.

:see: :meth:`~BalloonTip.SetBalloonTipStyle`

Returns the :class:`BalloonTip` top title.

:return: A string containing the top title.

Returns the delay time after which the :class:`BalloonTip` is destroyed.

:return: the delay time, in milliseconds.

Returns the colour for the tip message.

Returns the font for the tip message.

Returns the delay time after which the :class:`BalloonTip` is created.

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.

Returns the colour for the top title.

Returns the font for the top title.

The creation timer has expired. Creates the :class:`BalloonTip` frame.

Handles the target destruction, specifically handling the ``wx.EVT_WINDOW_DESTROY``
event.

:param `event`: a :class:`wx.WindowDestroyEvent` event to be processed.

Handles the mouse motion inside the taskbar icon area.

Handles the ``wx.EVT_ENTER_WINDOW`` for the target control/window and
starts the :class:`BalloonTip` timer for creation.

Handles the ``wx.EVT_LEAVE_WINDOW`` for the target control/window.

:note: If the BalloonTip `tipstyle` is set to ``BT_LEAVE``, the :class:`BalloonTip` is destroyed.

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.

Sets the :class:`BalloonTip` background colour.

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

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.

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``);

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

Sets the :class:`BalloonTip` top title.

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

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.

Sets the colour for the tip message.

Sets the font for the tip message.

:param `font`: a valid :class:`wx.Font` instance.

Sets the delay time after which the :class:`BalloonTip` is created.

:param integer `delay`: the number of milliseconds after which :class:`BalloonTip` is created.

Sets the target control/window for the :class:`BalloonTip`.

:param `widget`: any subclass of :class:`wx.Window`.

Sets the colour for the top title.

Sets the font for the top title.

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.

A generic button, and base class for the other generic buttons. 

:param `pos`: the control position. A value of (-1, -1) indicates a default
 position, chosen by either the windowing system or wxPython, depending on
 platform;
:param integer `style`: the button style;
:param wx.Validator `validator`: the validator associated with the button;

.. seealso:: :class:`wx.Button` for a list of valid window styles.

__init__(self, parent, id=-1, label='', pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, validator = wx.DefaultValidator, name = "genbutton")

.. note:: Overridden from :class:`wx.Control`.

Returns the current :class:`wx.Brush` to be used to draw the button background.

:param wx.DC `dc`: the device context used to draw the button background.

the same font/colour attributes as the native :class:`wx.Button`.

:return: an instance of :class:`wx.VisualAttributes`.

Returns the focus indicator flag, specifying if a focus indicator
(dotted line) is being used.

Calculate a new set of highlight and shadow colours based on
the background colour. Works okay if the colour is dark...

Override this method in a subclass to initialize any other events that
need to be bound.  Added so :meth:`__init__` doesn't need to be
overridden, which is complicated with multiple inheritance.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`GenButton`.

:param `event`: a :class:`wx.FocusEvent` event to be processed.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`GenButton`.

:param `event`: a :class:`wx.KeyEvent` event to be processed.

Handles the ``wx.EVT_KEY_UP`` event for :class:`GenButton`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`GenButton`.

:param `event`: a :class:`wx.MouseEvent` event to be processed.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`GenButton`.

Handles the ``wx.EVT_MOUSE_CAPTURE_LOST`` event for :class:`GenButton`.

:param `event`: a :class:`wx.MouseCaptureLostEvent` event to be processed.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`GenButton`.

Handles the ``wx.EVT_MOTION`` event for :class:`GenButton`.

Handles the ``wx.EVT_PAINT`` event for :class:`GenButton`.

:param `event`: a :class:`wx.PaintEvent` event to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`GenButton`.

Sets the :class:`GenButton` background colour.

Sets the width of the 3D effect.

:param integer `width`: the 3D border width, in pixels.

This sets the :class:`GenButton` to be the default item for
the panel or dialog box.

.. note:: Under Windows, only dialog box buttons respond to this function.
   As normal under Windows and Motif, pressing return causes the
   default button to be depressed when the return key is pressed. See
   also :meth:`wx.Window.SetFocus` which sets the keyboard focus for
   windows and text panel items, and
   :meth:`wx.TopLevelWindow.SetDefaultItem`.

.. note:: Note that under Motif, calling this function immediately after
   creation of a button and before the creation of other buttons will
   cause misalignment of the row of buttons, since default buttons are
   larger. To get around this, call :meth:`wx.SetDefault` after you
   have created a row of buttons: wxPython will then set the size of
   all buttons currently on the panel to the same size.

Sets the :class:`wx.GenButton` foreground colour.

:param `size`: an instance of :class:`wx.Size` or ``None``,
 in which case the wxPython
 ``wx.DefaultSize`` is used instead.

Specifies if a focus indicator (dotted line) should be used.

:param bool `flag`: ``True`` to draw a focus ring, ``False`` otherwise.

A custom panel class with gradient background shading with the possibility to
add buttons and controls still respecting the gradient background.

With :class:`ButtonPanel` class you have a panel with gradient colouring
on it and with the possibility to place some buttons on it. Using a
standard panel with normal :class:`Button` leads to an ugly result: the
buttons are placed correctly on the panel - but with grey area around
them. Gradient colouring is kept behind the images - this was achieved
due to the PNG format and the transparency of the bitmaps.

The image are functioning like a buttons and can be caught in your
code using the usual::

  self.Bind(wx.EVT_BUTTON, self.OnButton)

method.

The control is generic, and support theming (well, I tested it under
Windows with the three default themes: grey, blue, silver and the
classic look).

Usage
=====

:class:`ButtonPanel` supports 4 alignments: left, right, top, bottom, which have a
different meaning and behavior with respect to :class:`ToolBar`. The easiest
thing is to try the demo to understand, but I'll try to explain how it works.

**CASE 1**: :class:`ButtonPanel` has a main caption text.

- Left alignment means :class:`ButtonPanel` is horizontal, with the text aligned to the
  left. When you shrink the demo frame, if there is not enough room for all
  the controls to be shown, the controls closest to the text are hidden;

- Right alignment means :class:`ButtonPanel` is horizontal, with the text aligned to the
  right. Item layout as above;

- Top alignment means :class:`ButtonPanel` is vertical, with the text aligned to the top.
  Item layout as above;

- Bottom alignment means :class:`ButtonPanel` is vertical, with the text aligned to the
  bottom. Item layout as above.

**CASE 2**: :class:`ButtonPanel` has **no** main caption text.

- In this case, left and right alignment are the same (as top and bottom are the same),
  but the layout strategy changes: now if there is not enough room for all the controls
  to be shown, the last added items are hidden ("last" means on the far right for an
  horizontal :class:`ButtonPanel` and far bottom for a vertical :class:`ButtonPanel`).

    import wx
    import wx.lib.agw.buttonpanel as BP

        def __init__(self, parent, id=-1, title="ButtonPanel", pos=wx.DefaultPosition,

            mainPanel = wx.Panel(self, -1)
            self.logtext = wx.TextCtrl(mainPanel, -1, "", style=wx.TE_MULTILINE)

            vSizer = wx.BoxSizer(wx.VERTICAL)
            mainPanel.SetSizer(vSizer)

            titleBar = BP.ButtonPanel(mainPanel, -1, "A Simple Test & Demo")

            btn1 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png4.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn1)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn1)

            btn2 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png3.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn2)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn2)

            btn3 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png2.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn3)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn3)

            btn4 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png1.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn4)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn4)

            vSizer.Add(titleBar, 0, wx.EXPAND)
            vSizer.Add((20, 20))
            vSizer.Add(self.logtext, 1, wx.EXPAND | wx.ALL, 5)

            titleBar.DoLayout()
            vSizer.Layout()

        def OnButton(self, event):
            ''' Handler for the ``wx.EVT_BUTTON`` event. '''

            obj = event.GetEventObject()

            # This will print the button label
            print(obj.GetText())

==================== =========== ==================================================
Window Styles        Hex Value   Description
``BP_DEFAULT_STYLE``         0x1 :class:`ButtonPanel` has a plain solid background.
``BP_USE_GRADIENT``          0x2 :class:`ButtonPanel` has a gradient shading background.

``wx.EVT_BUTTON`` Process a `wxEVT_COMMAND_BUTTON_CLICKED` event, when a button is clicked.

:class:`ButtonPanel` is distributed under the wxPython license.

Version 0.7.

# BUTTONPANEL Widget wxPython IMPLEMENTATION
#
# Original C++ Code From Eran. You Can Find It At:
#
# http://wxforum.shadonet.com/viewtopic.php?t=6619
#
#
#
#
# Andrea Gavana, @ 02 Oct 2006
#
#
#
#
#
#

Constructor for :class:`BoxSizer`.

:param integer `orient`: may be one of ``wx.VERTICAL`` or ``wx.HORIZONTAL`` for creating
 either a column sizer or a row sizer.

Appends a child item to the sizer.

:param `item`: the item to be added to :class:`BoxSizer`. Can be an instance of :class:`wx.Window`,
 :class:`wx.Sizer` or a spacer;
:param integer `proportion`: this parameter is used in :class:`BoxSizer` to indicate if a child of
 a sizer can change its size in the main orientation of the :class:`BoxSizer` - where 0
 stands for not changeable and a value of more than zero is interpreted relative
 to the value of other children of the same :class:`BoxSizer`. For example, you might have
 a horizontal :class:`BoxSizer` with three children, two of which are supposed to change their
 size with the sizer. Then the two stretchable windows would get a value of 1 each to
 make them grow and shrink equally with the sizer's horizontal dimension.
:param integer `flag`: this parameter can be used to set a number of flags which can be combined using the binary OR operator ``|``.
 Two main behaviours are defined using these flags. One is the border around a window: the border parameter determines the border
 width whereas the flags given here determine which side(s) of the item that the border will be added. The other flags determine
 how the sizer item behaves when the space allotted to the sizer changes, and is somewhat dependent on the specific kind of sizer used:

 +-----------------------------------------------------------------------+------------------------------------------------------------------------------+
 | Sizer Flag                                                            | Description                                                                  |
 +=======================================================================+==============================================================================+
 | | ``wx.TOP``                                                          | These flags are used to specify which side(s) of the sizer                   |
 | | ``wx.BOTTOM``                                                       | item the border width will apply to.                                         |
 | | ``wx.LEFT``                                                         |                                                                              |
 | | ``wx.RIGHT``                                                        |                                                                              |
 | | ``wx.ALL``                                                          |                                                                              |
 | ``wx.EXPAND``                                                         | The item will be expanded to fill the space assigned to                      |
 |                                                                       | the item.                                                                    |
 | ``wx.SHAPED``                                                         | The item will be expanded as much as possible while also                     |
 |                                                                       | maintaining its aspect ratio                                                 |
 | ``wx.FIXED_MINSIZE``                                                  | Normally :class:`wx.Sizer` will use                                          |
 |                                                                       | :meth:`wx.Window.GetEffectiveMinSize` to                                     |
 |                                                                       | determine what the minimal size of window items should be, and will use that |
 |                                                                       | size to calculate the layout. This allows layouts to adjust when an item     |
 |                                                                       | changes and its best size becomes different. If you would rather have a      |
 |                                                                       | window item stay the size it started with then use ``wx.FIXED_MINSIZE``.     |
 | ``wx.RESERVE_SPACE_EVEN_IF_HIDDEN``                                   | Normally `Sizers` don't allocate space for hidden windows or other items.    |
 |                                                                       | This flag overrides this behavior so that sufficient space is allocated for  |
 |                                                                       | the window even if it isn't visible. This makes it possible to dynamically   |
 |                                                                       | show and hide controls without resizing parent dialog, for example. This     |
 |                                                                       | function is new since wxWidgets version 2.8.8                                |
 | | ``wx.ALIGN_CENTER`` **or** ``wx.ALIGN_CENTRE``                      | The ``wx.ALIGN*`` flags allow you to specify the alignment of the item       |
 | | ``wx.ALIGN_LEFT``                                                   | within the space allotted to it by the sizer, adjusted for the border if     |
 | | ``wx.ALIGN_RIGHT``                                                  | any.                                                                         |
 | | ``wx.ALIGN_TOP``                                                    |                                                                              |
 | | ``wx.ALIGN_BOTTOM``                                                 |                                                                              |
 | | ``wx.ALIGN_CENTER_VERTICAL`` **or** ``wx.ALIGN_CENTRE_VERTICAL``    |                                                                              |
 | | ``wx.ALIGN_CENTER_HORIZONTAL`` **or** ``wx.ALIGN_CENTRE_HORIZONTAL``|                                                                              |

:param integer `border`: determines the border width, if the flag parameter is set
 to include any border flag.
:param object `userData`: Allows an extra object to be attached to the sizer item,
 for use in derived classes when sizing information is more complex than the
 proportion and flag will allow for.

:note: there is no support for `userData` parameter if `item` is a pseudocontrol,
 since that is already used.

Inserts a child item into the sizer.

:see: :meth:`BoxSizer.Add` method for an explanation of the input parameters.

Insert(self, before, item, proportion=0, flag=0, border=0, userData=None, realIndex=None)

Call this to force layout of the children anew, e.g. after having added a
child to or removed a child (window, other sizer or space) from the sizer
while keeping the current dimension.

Prepends a child item to the sizer.

Prepend(self, item, proportion=0, flag=0, border=0, userData=None)

Removes an item from the sizer and destroys it.

This method does not cause any layout or resizing to take place, call
:meth:`BoxSizer.Layout() <BoxSizer.Layout>` to update the layout on screen after removing a child from
the sizer.

:param integer `indx`: the zero-based index of an item to remove;
:param bool `pop`: whether to remove the sizer item from the list of children.

Shows or hides the sizer item.

:param `item`: the sizer item we want to show/hide;
:param bool `show`: ``True`` to show the item, ``False`` to hide it.

:class:`BPArt` is an art provider class which does all of the drawing for :class:`ButtonPanel`.
This allows the library caller to customize the :class:`BPArt` or to completely replace
all drawing with custom BPArts.

:param integer `parentStyle`: the window style for :class:`ButtonPanel`.

Draws a button in :class:`ButtonPanel`, together with its text (if any).

:param wx.Rect `rect`: the button client rectangle;
:param wx.Bitmap `buttonBitmap`: the bitmap associated with the button;
:param bool `isVertical`: ``True`` if :class:`ButtonPanel` is in vertical orientation,
 ``False`` otherwise;
:param string `buttonStatus`: one of "Normal", "Toggled", "Pressed", "Disabled" or "Hover";
:param bool `isToggled`: whether the button is toggled or not;
:param integer `textAlignment`: the text alignment inside the button;
:param string `text`: the button label.

DrawButton(self, dc, rect, buttonBitmap, isVertical, buttonStatus, isToggled, textAlignment, text="")

Paint the :class:`ButtonPanel`'s background.

:param wx.Rect `rect`: the :class:`ButtonPanel` client rectangle;
:param integer `style`: the :class:`ButtonPanel` window style.

Draws the main caption text in :class:`ButtonPanel`.

:param wx.Rect `rect`: the main caption text rectangle;
:param string `captionText`: the caption text string.

Draws the label for a button.

:param bool `isEnabled`: ``True`` if the button is enabled, ``False`` otherwise;
:param integer `xpos`: the text `x` position inside the button;
:param integer `ypos`: the text `y` position inside the button.

Draws a separator in :class:`ButtonPanel`.

:param wx.Rect `rect`: the separator client rectangle;

Gradient fill from colour 1 to colour 2 with top to bottom or left to right.

:param wx.Rect `rect`: the :class:`ButtonPanel` client rectangle.

Returns the option value for the specified colour `id`.

:param integer `id`: the identification bit for the colour value. This can be one of the

 ================================== ======= =====================================
 Colour Id                           Value  Description
 ``BP_BACKGROUND_COLOUR``                 0 Background brush colour when no gradient shading exists
 ``BP_GRADIENT_COLOUR_FROM``              1 Starting gradient colour, used only when ``BP_USE_GRADIENT`` style is applied
 ``BP_GRADIENT_COLOUR_TO``                2 Ending gradient colour, used only when ``BP_USE_GRADIENT`` style is applied
 ``BP_BORDER_COLOUR``                     3 Pen colour to paint the border of :class:`ButtonPanel`
 ``BP_TEXT_COLOUR``                       4 Main :class:`ButtonPanel` caption colour
 ``BP_BUTTONTEXT_COLOUR``                 5 Text colour for buttons with text
 ``BP_BUTTONTEXT_INACTIVE_COLOUR``        6 Text colour for inactive buttons with text
 ``BP_SELECTION_BRUSH_COLOUR``            7 Brush colour to be used when hovering or selecting a button
 ``BP_SELECTION_PEN_COLOUR``              8 Pen colour to be used when hovering or selecting a button
 ``BP_SEPARATOR_COLOUR``                  9 Pen colour used to paint the separators

:return: An instance of :class:`wx.Colour` for the input `id`.

:raise: `Exception` if the `id` is not recognized.

Returns the option value for the specified font `id`.

:param integer `id`: the identification bit for the font value. This can be one of the

 ============================== ======= =====================================
 Size Id                         Value  Description
 ``BP_TEXT_FONT``                    10 Font of the :class:`ButtonPanel` main caption
 ``BP_BUTTONTEXT_FONT``              11 Text font for the buttons with text

:return: An instance of :class:`wx.Font` for the input `id`.

Returns the gradient type for :class:`BPArt` drawings.

:return: An integer representing the gradient type.

:see: :meth:`~BPArt.SetGradientType` for a list of possible gradient types.

Returns the option value for the specified size `id`.

:param integer `id`: the identification bit for the size value. This can be one of the

 ``BP_SEPARATOR_SIZE``               14 Separator size. Note: This is not the line width, but the sum of the space before and after the separator line plus the width of the line
 ``BP_MARGINS_SIZE``                 15 Size of the left/right margins in :class:`ButtonPanel` (top/bottom for vertically aligned :class:`ButtonPanel`)
 ``BP_BORDER_SIZE``                  16 Size of the border
 ``BP_PADDING_SIZE``                 17 Inter-tool separator size

:return: An integer representing the option value for the input `id`.

Sets the option value for the specified colour `id`.

:param integer `id`: the identification bit for the colour value;
:param `colour`: the new value for the colour (a valid :class:`wx.Colour` instance).

:see: :meth:`~BPArt.GetColour` for a list of meaningful colour ids.

Sets the option value for the specified font `id`.

:param integer `id`: the identification bit for the font value;
:param `colour`: the new value for the font (a valid :class:`wx.Font` instance).

:see: :meth:`~BPArt.GetFont` for a list of meaningful font ids.

Sets the gradient type for :class:`BPArt` drawings.

:param integer `gradient`: can be one of the following bits:

 ============================ ======= ============================
 Gradient Type                 Value  Description
 ``BP_GRADIENT_NONE``               0 No gradient shading should be used to paint the background
 ``BP_GRADIENT_VERTICAL``           1 Vertical gradient shading should be used to paint the background
 ``BP_GRADIENT_HORIZONTAL``         2 Horizontal gradient shading should be used to paint the background

Sets the option value for the specified size `id`.

:param integer `id`: the identification bit for the size value;
:param integer `new_val`: the new value for the size.

:see: :meth:`~BPArt.GetMetric` for a list of meaningful size ids.

This class holds information about every button that is added to
:class:`ButtonPanel`. It is an auxiliary class that you should use
every time you add a button.

:param `parent`: the parent window (:class:`ButtonPanel`);
:param integer `id`: the button id;
:param wx.Bitmap `bmp`: the associated bitmap;
:param string `status`: button status ("Pressed", "Hover", "Normal", "Toggled", "Disabled");
:param string `text`: text to be displayed either below of to the right of the button;
:param integer `kind`: button kind, may be ``wx.ITEM_NORMAL`` for standard buttons or
 ``wx.ITEM_CHECK`` for toggle buttons;
:param string `shortHelp`: a short help to be shown in the button tooltip;
:param string `longHelp`: this string is shown in the statusbar (if any) of the parent
 frame when the mouse pointer is inside the button.

__init__(self, parent, id=wx.ID_ANY, bmp=wx.NullBitmap, status="Normal", text="", kind=wx.ITEM_NORMAL, shortHelp="", longHelp="")

Add a programmer-defined status in addition to the 5 default status:

- Normal;
- Disabled;
- Hover;
- Pressed;
- Toggled.

:param string `name`: the new status name;
:param wx.Bitmap `bmp`: the bitmap associated with the new status.

Checks whether a :class:`ButtonPanel` repaint is needed or not. This is a convenience function.

:param bool `status`: the status of a newly added :class:`ButtonInfo` or a change in the
 :class:`ButtonInfo` status.

Draws the button on :class:`ButtonPanel`. Actually the drawing is done in :class:`BPArt`.

:param wx.Rect `rect`: the main caption text client rectangle.

Enables/disables this instance of :class:`ButtonInfo`.

:param bool `enable`: ``True`` to enable the button, ``False`` otherwise.

Returns the best size for the button.

Returns the bitmap associated with this instance of :class:`ButtonInfo`.

:param string `status`: the :class:`ButtonInfo` status ("Pressed", "Hover", "Normal",
 "Toggled", "Disabled").

Returns the :class:`ButtonInfo` id.

:return: An integer representing the button id.

Returns the button type (standard or toggle).

:return: An integer representing the button type, one of ``wx.ITEM_NORMAL``, ``wx.ITEM_CHECK``.

Returns the help string shown in the statusbar.

:return: A string containing the :class:`ButtonInfo` long help string.

Returns the :class:`ButtonInfo` client rectangle.

:return: An instance of :class:`wx.Rect`.

Returns the help string shown in a tooltip.

:return: A string containing the :class:`ButtonInfo` short help string.

Returns the :class:`ButtonInfo` status.

:return: A string containing the :class:`ButtonInfo` status (one of "Pressed", "Hover", "Normal",

Returns the text associated to the button.

:return: A string containing the :class:`ButtonInfo` text.

Returns the text alignment in the button (bottom or right).

:return: An integer representing the :class:`ButtonInfo` text alignment.

Returns whether a ``wx.ITEM_CHECK`` button is toggled or not.

:return: ``True`` if the button is toggled, ``False`` otherwise.

Returns whether the button has text or not.

:return: ``True`` if this :class:`ButtonInfo` instance has a label, ``False`` otherwise.

Returns ``True`` if this instance of :class:`ButtonInfo` is enabled for input,
``False`` otherwise.

Sets the bitmap associated with this instance of :class:`ButtonInfo`.

:param `bmp`: a valid :class:`wx.Bitmap` object;

Sets the :class:`ButtonInfo` identifier.

:param integer `id`: the identifier of the window.

Sets the button type (standard or toggle).

:param integer `kind`: one of ``wx.ITEM_NORMAL``, ``wx.ITEM_CHECK``.

Sets the help string to be shown in the statusbar.

:param string `help`: the string for the long help.

Sets the :class:`ButtonInfo` client rectangle.

:param `rect`: an instance of :class:`wx.Rect`.

Sets the help string to be shown in a tooltip.

:param string `help`: the string for the short help.

Sets the :class:`ButtonInfo` status.

:param string `status`: one of "Pressed", "Hover", "Normal", "Toggled", "Disabled".

Sets the button label text.

:param string `text`: the button label string.

Sets the text alignment in the button (bottom or right).

:param integer `alignment`: the text alignment in this :class:`ButtonInfo` instance.

Sets a ``wx.ITEM_CHECK`` button toggled/not toggled.

:param bool `toggle`: ``True`` to toggle the button, ``False`` otherwise.

:param wx.Window `parent`: the parent window. Must not be ``None``;
:param integer `id`: window identifier. If ``wx.ID_ANY``, will automatically create an identifier;
:param string `text`: the main caption text for :class:`ButtonPanel`;
:param integer `agwStyle`: the AGW-specific window style (one of ``BP_DEFAULT_STYLE``, ``BP_USE_GRADIENT``);
:param integer `alignment`: alignment of buttons (left or right);
:param string `name`: window class name.

__init__(self, parent, id=wx.ID_ANY, text="", agwStyle=BP_DEFAULT_STYLE, alignment=BP_ALIGN_LEFT, name="buttonPanel")

Adds a button to :class:`ButtonPanel`.

:param `btnInfo`: an instance of :class:`ButtonInfo`.

:note: Remember to pass a :class:`ButtonInfo` instance to this method, and not a
 standard :class:`Button` or a :class:`ToolBar` tool.

Adds a wxPython control to :class:`ButtonPanel`.

:param `control`: an instance of :class:`wx.Window`;
:param integer `proportion`: the control proportion (0 for fixed-size, 1 or more for a
 stretchable one);
:param integer `flag`: one of the :class:`BoxSizer` flags;
:param integer `border`: the control border width (in pixels), if the `flag` parameter
 is set to include any border flag.

AddControl(self, control, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=None)

Adds a spacer (stretchable or fixed-size) to :class:`ButtonPanel`.

:param tuple `size`: the spacer size as a tuple;
:param integer `proportion`: the spacer proportion (0 for fixed-size, 1 or more for a
:param integer `flag`: one of the :class:`BoxSizer` flags.

Clears the :class:`ButtonPanel`.

Can be used to reset the :class:`ButtonPanel` if you'd like have a new set of
buttons on the panel.

Gets the size which best suits :class:`ButtonPanel`: for a control, it would be
the minimal size which doesn't truncate the control, for a panel - the
same size as it would have after a call to `Fit()`.

Shows tooltips and long help strings in :class:`StatusBar`.

:param `hit`: an instance of :class:`ButtonInfo` where the mouse is hovering.

Do the Layout for :class:`ButtonPanel`.

:note: Call this method every time you make a modification to the layout
 or to the customizable sizes of the pseudo controls.

Layout the items when the main caption exists.

:param list `nonspacers`: a list of items which are not spacers;
:param list `allchildren`: a list of all the children of :class:`ButtonPanel`.

Returns the buttons alignment.

:return: An integer specifying the buttons alignment.

:see: :meth:`~ButtonPanel.SetAlignment` for a set of valid alignment bits.

Returns the main caption text.

:return: A string representing the caption text.

Returns the wxPython controls that belongs to :class:`ButtonPanel`.

:return: A list of items inside :class:`ButtonPanel` that are wxPython controls.

Returns the size of an item in the main :class:`ButtonPanel` sizer.

:param `item`: an instance of :class:`ButtonInfo`;

Returns all the :class:`ButtonPanel` main sizer's children that are not
flexible spacers.

:return: A list of items inside :class:`ButtonPanel` that are not flexible spacers.

Returns the :class:`ButtonPanel` window style.

:see: :meth:`~ButtonPanel.SetStyle` for a list of valid window styles.

Returns whether or not short and long help strings should be displayed as tooltips
and :class:`StatusBar` items respectively.

:return: ``True`` if the short and long help strings should be displayed as tooltips
 and :class:`StatusBar` items respectively, ``False`` otherwise.

Returns whether :class:`ButtonPanel` has a main caption text or not.

:return: ``True`` if :class:`ButtonPanel` has a main caption text, ``False`` otherwise.

HitTest method for :class:`ButtonPanel`.

:param `pt`: the mouse position, an instance of :class:`wx.Point`.

:returns: an instance of :class:`ButtonInfo` and the hit flag ``BP_HT_BUTTON`` if a button
 client rectangle contains the input point `pt`, or ``wx.NOT_FOUND`` and ``BP_HT_NONE``.

Returns whether :class:`ButtonPanel` is aligned "Standard" (left/top) or not.

:return: ``True`` if :class:`ButtonPanel` is aligned "standard", ``False`` otherwise.

Returns whether :class:`ButtonPanel` is vertically aligned or not.

:return: ``True`` if :class:`ButtonPanel` is vertically aligned, ``False`` otherwise.

Layout the items using a different algorithms depending on the existence
of the main caption.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`ButtonPanel`.

:note: This is intentionally empty to reduce flicker.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_MOTION`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_PAINT`` event for :class:`ButtonPanel`.

Handles the ``wx.EVT_SIZE`` event for :class:`ButtonPanel`.

.. todo::

   Improve the chain of methods :meth:`~ButtonPanel.OnSize` ==> :meth:`~ButtonPanel.DoLayout` ==> :meth:`~ButtonPanel.LayoutItems`
   to avoid multiple calls to :meth:`~ButtonPanel.LayoutItems`.

Handles the timer expiring to delete the long help string in :class:`StatusBar`. 

Recreates the :class:`ButtonPanel` sizer accordingly to the alignment specified.

:param string `text`: the text to display as main caption. If `text` is set to ``None``,
 the main caption will not be displayed.

Remove all the buttons from :class:`ButtonPanel`.

:note: This function is for internal use only. If you are interested in
 manipulating a :class:`ButtonPanel` in real time (ie. removing things on it)
 have a look at the :meth:`~ButtonPanel.Clear` method.

Remove all the separators from :class:`ButtonPanel`.

Sets the buttons alignment.

:param integer `alignment`: can be one of the following bits:

 ====================== ======= ==========================
 Alignment Flag          Value  Description
 ``BP_ALIGN_RIGHT``           1 Buttons are aligned on the right
 ``BP_ALIGN_LEFT``            2 Buttons are aligned on the left
 ``BP_ALIGN_TOP``             4 Buttons are aligned at the top
 ``BP_ALIGN_BOTTOM``          8 Buttons are aligned at the bottom

Sets the main caption text.

:param string `text`: the main caption text label. An empty string erases the
 main caption text.
 
Sets a new :class:`BPArt` art provider to :class:`ButtonPanel`.

:param `art`: an instance of :class:`BPArt`.

Sets the :class:`ButtonPanel` window style.

:param integer `agwStyle`: one of the following bits:

 ==================== =========== ==================================================
 Window Styles        Hex Value   Description
 ``BP_DEFAULT_STYLE``         0x1 :class:`ButtonPanel` has a plain solid background.
 ``BP_USE_GRADIENT``          0x2 :class:`ButtonPanel` has a gradient shading background.

Sets whether or not short and long help strings should be displayed as tooltips

:param bool `useHelp`: ``True`` to display short and long help strings as tooltips

Layout the items when no main caption exists.

:param list `children`: a list of all the children of :class:`ButtonPanel`.

This class is used to hold data about the main caption in :class:`ButtonPanel`. 

:param `parent`: the text parent object, an instance of :class:`ButtonPanel`;
:param string `text`: the actual main caption string.

Draws the main caption. Actually the drawing is done in :class:`BPArt`.

Returns the best size for the main caption in :class:`ButtonPanel`.

Returns the caption text.

Sets the caption text.

:param string `text`: the main caption string.

This class represents a base class for all pseudo controls used in
:class:`ButtonPanel`.

:param wx.Window `parent`: the control parent object. Must not be ``None``;
:param integer `id`: window identifier. A value of -1 indicates a default value.

Disables the control.

:returns: ``True`` if the window has been disabled, ``False`` if it had been
 already disabled before the call to this function.

:note: This is functionally equivalent of calling :meth:`~Control.Enable` with a ``False`` flag.

Handles the drawing of the control.

:param wx.Rect `rect`: the control client rectangle.

Enable or disable the window for user input.

:param bool `enable`: If ``True``, enables the window for input. If ``False``, disables the window.

:returns: ``True`` if the window has been enabled or disabled, ``False`` if nothing was
 done, i.e. if the window had already been in the specified state.

:note: Note that when a parent window is disabled, all of its children are disabled as
 well and they are re-enabled again when the parent is.

This functions returns the best acceptable minimal size for the window. For
example, for a static control, it will be the minimal size such that the control
label is not truncated. For windows containing subwindows (typically :class:`Panel`),
the size returned by this function will be the same as the size the window would
have had after calling `Fit()`.

Returns the identifier of the window.

:return: An integer representing the identifier of the window.

:note: Each window has an integer identifier. If the application has not provided
 one (or the default ``wx.ID_ANY``) an unique identifier with a negative value will
 be generated.

Returns whether the control has the focus or not.

:return: ``True`` if the control has the focus, ``False`` otherwise.

Hides the control.

:note: This is functionally equivalent of calling :meth:`~Control.Show` with a ``False`` input.

Returns ``True`` if the window is shown, ``False`` if it has been hidden. 

Handles the ``wx.EVT_MOUSE_EVENTS`` events for the control.

:param `event`: the :class:`MouseEvent` event to be processed.

Sets or kills the focus on the control.

:param bool `focus`: whether the control can receive keyboard inputs or not.

Shows or hide the control.

:param bool `show`: If ``True`` displays the window. Otherwise, it hides it.

This class holds all the information to size and draw a separator inside

:param `parent`: the separator parent object, an instance of :class:`ButtonPanel`.

Draws the separator. Actually the drawing is done in :class:`BPArt`.

:param wx.Rect `rect`: the separator client rectangle.

Returns the separator best size.

This is a mix-in class to add pseudo support to :class:`wx.Sizer`. Just create
a new class that derives from this class and :class:`wx.Sizer` and intercepts
any methods that add to the wx sizer.

This functions returns the best acceptable minimal size for the sizer object.

Timer used for deleting :class:`StatusBar` long help after ``_DELAY`` seconds.

:param `owner`: an instance of :class:`ButtonPanel`.

Brighten the input colour by a factor.

:param `colour`: a valid :class:`wx.Colour` instance;
:param integer `factor`: the factor by which the input colour should be brightened.

:return: An instance of :class:`wx.Colour`, a brightened version of the input `colour`.

Creates a disabled-looking bitmap starting from the input one.

:param `original`: an instance of :class:`wx.Bitmap` to be greyed-out.

:class:`~wx.lib.agw.cubecolourdialog.CubeColourDialog` is an alternative implementation of :class:`wx.ColourDialog`.

The :class:`CubeColourDialog` is an alternative implementation of :class:`wx.ColourDialog`, and it
offers different functionalities with respect to the default wxPython one. It
can be used as a replacement of :class:`wx.ColourDialog` with exactly the same syntax and
methods.

Some features:

- RGB components may be controlled using spin controls or with mouse gestures
  on a 3D RGB cube, with the 3 components laying on the X, Y, Z axes;
- HSB components may be controlled using spin controls or with mouse gestures
  on a 2D colour wheel;
- Brightness has its own vertical slider to play with;
- The colour alpha channel can be controlled using another vertical slider, or
  via spin control;
- The colour alpha channel controls can be completely hidden at startup or the
  choice to use the alpha channel can be left to the user while playing with the
  dialog, via a simple :class:`CheckBox`;
- The "old colour" and "new colour" are displayed in two small custom panel,
  which support alpha transparency and texture;
- :class:`CubeColourDialog` displays also the HTML colour code in hexadecimal format;
- When available, a corresponding "Web Safe" colour is generated using a 500
  web colours "database" (a dictionary inside the widget source code). Web Safe
  colours are recognized by all the browsers;
- When available, a corresponding "HTML name" for the selected colour is displayed,
  by using the same 500 web colours "database";
- When available, a corresponding "Microsoft Access Code" for the selected colour
  is displayed, by using the same 500 web colours "database".

And much more.

Usage
=====

    import wx
    import wx.lib.agw.cubecolourdialog as CCD

    # Our normal wxApp-derived class, as usual

    colourData = wx.ColourData()
    dlg = CCD.CubeColourDialog(None, colourData)

    if dlg.ShowModal() == wx.ID_OK:

        # If the user selected OK, then the dialog's wx.ColourData will
        # contain valid information. Fetch the data ...
        colourData = dlg.GetColourData()
        h, s, v, a = dlg.GetHSVAColour()

        # ... then do something with it. The actual colour data will be
        # returned as a three-tuple (r, g, b) in this particular case.
        colour = colourData.GetColour()
        r, g, b, alpha = colour.Red(), colour.Green(), colour.Blue(), colour.Alpha()
        print("You selected (RGBA): %d, %d, %d, %d"%(r, g, b, alpha))
        print("You selected (HSVA): %d, %d, %d, %d"%(h, s, v, a))

    # Once the dialog is destroyed, Mr. wx.ColourData is no longer your
    # friend. Don't use it again!
    dlg.Destroy()

================== =========== ==================================================
Window Styles      Hex Value   Description
``CCD_SHOW_ALPHA``         0x1 Show the widget used to control colour alpha channels in :class:`CubeColourDialog`.

:class:`CubeColourDialog` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 19 Dec 2012, 21.00 GMT

# CUBECOLOURDIALOG Widget wxPython IMPLEMENTATION
#
#
# Andrea Gavana, @ 16 Aug 2007
#
#
# TODO List
#
# 1. Find A Way To Reduce Flickering On The 2 ColourPanels;
#
# 2. See Why wx.GCDC Doesn't Work As I Thought (!). It Looks Slow As A Turtle,
#    But Probably I Am Doing Something Wrong While Painting The Alpha Textures.
#
#
#
#
#
#

Implements the drawing, mouse handling and sizing routines for the alpha
channel control.

Used internally. Do not call it in your code!

:param `parent`: the control parent window.

Draws the alpha shading on top of the checkerboard.

:param `rect`: the :class:`AlphaCtrl` client rectangle.

Draws square markers used with mouse gestures.

Handles the ``wx.EVT_PAINT`` for :class:`AlphaCtrl`.

Tracks a mouse action inside the Alpha channel control.

:param `pt`: an instance of :class:`wx.Point`.

Base class used to hold common code for the Alpha channel control and the
brightness palette control.

:note: This method always returns ``False`` as we do not accept focus from
 mouse click.

Can this window be given focus by keyboard navigation? If not, the
only way to give it focus (provided it accepts it at all) is to click
it.

 the keyboard.

Overridden base class virtual. Determines the best size of the control.

Handles the ``wx.EVT_ERASE_BACKGROUND`` for :class:`BaseLineCtrl`.

Handles the ``wx.EVT_LEFT_DOWN`` for :class:`BaseLineCtrl`.

Handles the ``wx.EVT_LEFT_UP`` for :class:`BaseLineCtrl`.

Handles the ``wx.EVT_MOTION`` for :class:`BaseLineCtrl`.

Handles the ``wx.EVT_SIZE`` for :class:`BaseLineCtrl`.

Base class used to hold common code for the HSB colour wheel and the RGB
colour cube.

:param `parent`: the control parent;
:param `bitmap`: the background bitmap for this custom control.

control based on the bitmap size.

Draws the lines connecting the markers on top of the background bitmap.

Draws the markers on top of the background bitmap.

Handles the ``wx.EVT_ERASE_BACKGROUND`` for :class:`BasePyControl`.

Handles the ``wx.EVT_LEFT_DOWN`` for :class:`BasePyControl`.

Handles the ``wx.EVT_LEFT_UP`` for :class:`BasePyControl`.

Handles the ``wx.EVT_MOTION`` for :class:`BasePyControl`.

Handles the ``wx.EVT_PAINT`` for :class:`BasePyControl`.

Handles the ``wx.EVT_SIZE`` for :class:`BasePyControl`.

Implements the drawing, mouse handling and sizing routines for the brightness
palette control.

Handles the ``wx.EVT_PAINT`` for :class:`BrightCtrl`.

Tracks a mouse action inside the palette control.

This is a subclass of :class:`wx.Colour`, which adds Hue, Saturation and Brightness
capability to the base class. It contains also methods to convert RGB triplets
into HSB triplets and vice-versa.

:param `colour`: a standard :class:`wx.Colour`.

Returns the wxPython :class:`wx.Colour` associated with this instance. 

Simple custom class used to display "old" and "new" colour panels, with alpha
blending capabilities.

:param `parent`: the control parent window;
:param `style`: the :class:`wx.ColourPanel` window style.

it.

Handles the ``wx.EVT_ERASE_BACKGROUND`` for :class:`wx.ColourPanel`.

Handles the ``wx.EVT_PAINT`` for :class:`wx.ColourPanel`.

Handles the ``wx.EVT_SIZE`` for :class:`wx.ColourPanel`.

Refresh the panel after a colour/alpha change.

:param `colour`: the new background colour of :class:`wx.ColourPanel`.

:param `colourData`: a standard :class:`wx.ColourData` (as used in :class:`wx.ColourDialog`);
:param `agwStyle`: can be either ``None`` or ``CCD_SHOW_ALPHA``, depending if you want
 to hide the alpha channel control or not.

__init__(self, parent, colourData=None, agwStyle=CCD_SHOW_ALPHA)

Draws the markers for all the controls.

:param `dc`: an instance of :class:`wx.DC`. If `dc` is ``None``, a :class:`ClientDC` is
 created on the fly.

Returns the :class:`CubeColourDialog` window style flags.

:see: :meth:`~CubeColourDialog.SetAGWWindowStyleFlag` for a list of possible flags.

Returns a 4-elements tuple of hue, saturation, brightness, alpha components. 

Returns a 4-elements tuple of red, green, blue, alpha components. 

Handles the Add Custom ``wx.EVT_BUTTON`` event for :class:`CubeColourDialog`.

Handles the ``wx.EVT_SPINCTRL`` event for the alpha channel.

:param `event`: a :class:`SpinEvent` event to be processed.

Handles the Cancel ``wx.EVT_BUTTON`` event for :class:`CubeColourDialog`.

Handles the ``wx.EVT_CLOSE`` event for :class:`CubeColourDialog`.

Handles the ``wx.EVT_CHAR_HOOK`` event for :class:`CubeColourDialog`.

Handles the Ok ``wx.EVT_BUTTON`` event for :class:`CubeColourDialog`.

Shows/hides the alpha channel control in :class:`CubeColourDialog`.

Handles the ``wx.EVT_SPINCTRL`` event for RGB and HSB colours.

Sets the :class:`CubeColourDialog` window style flags.

:param `agwStyle`: can only be ``CCD_SHOW_ALPHA`` or ``None``.

Sets some initial properties for :class:`CubeColourDialog` (sizes, values). 

Shows :class:`CubeColourDialog` as a modal dialog. Program flow does
not return until the dialog has been dismissed with `EndModal`.

:note: Overridden from :class:`Dialog`.

This panel displays a series of custom colours (chosen by the user) just like
the standard :class:`wx.ColourDialog`.

:param `colourData`: an instance of :class:`wx.ColourData`.

Adds a user-chosen colour to the list of custom colours.

Handles the ``wx.EVT_ERASE_BACKGROUND`` for :class:`CustomPanel`.

Handles the ``wx.EVT_LEFT_DOWN`` for :class:`CustomPanel`.

Handles the ``wx.EVT_PAINT`` for :class:`CustomPanel`.

Handles the ``wx.EVT_SIZE`` for :class:`CustomPanel`.

Paints a newly added custom colour subpanel.

:param `selX`: the x coordinate of the custom colour subpanel;
:param `selY`: the y coordinate of the custom colour subpanel.

Draws all the 16 subpanels with their custom colours.

Highlight the current custom colour selection (if any).

:param `draw`: whether to draw a thin black border around the selected custom
 colour or not.

Implements the drawing, mouse handling and sizing routines for the HSV
colour wheel.

Returns whether a point is inside the HSV wheel or not.

Handles the ``wx.EVT_LEFT_DOWN`` for :class:`HSVWheel`.

Handles the ``wx.EVT_LEFT_UP`` for :class:`HSVWheel`.

Handles the ``wx.EVT_MOTION`` for :class:`HSVWheel`.

Track a mouse event inside the HSV colour wheel.

Simple class to store description and constants for a line in 2D space. 

:param `x`: the x coordinate of the first point;
:param `y`: the y coordinate of the first point;
:param `slope`: the line's slope;
:param `c`: a floating point constant.

Implements the drawing, mouse handling and sizing routines for the RGB
cube colour.

Handles the ``wx.EVT_LEFT_DOWN`` for :class:`RGBCube`.

Handles the ``wx.EVT_LEFT_UP`` for :class:`RGBCube`.

Handles the ``wx.EVT_MOTION`` for :class:`RGBCube`.

Returns the angle between the x-axis and the line connecting the center and
the point `pt`.

:param `pt`: an instance of :class:`wx.Point`;
:param `center`: a float value representing the center.

Transforms degrees into radians.

:param `x`: a float representing an angle in degrees.

Returns the distance between 2 points.

:param `pt1`: an instance of :class:`wx.Point`;
:param `pt2`: another instance of :class:`wx.Point`.

Draws a checkerboard on a :class:`wx.DC`.

:param `rect`: the client rectangle on which to draw the checkerboard;
:param `checkColour`: the colour used for the dark checkerboards;
:param `box`: the checkerboards box sizes.

:note: Used for the Alpha channel control and the colour panels.

Calculates the intersection point between 2 lines.

:param `line1`: an instance of :class:`LineDescription`;
:param `line2`: another instance of :class:`LineDescription`.

Given the angle with respect to the x-axis, returns the point based on
the saturation value.

:param `angle`: a float representing an angle;
:param `sat`: a float representing the colour saturation value;

Transforms radians into degrees.

:param `x`: a float representing an angle in radians.

Restores the old settings for a :class:`wx.DC`.

:param `oldPen`: an instance of :class:`wx.Pen`;
:param `oldBrush`: an instance of :class:`wx.Brush`;
:param `oldMode`: the :class:`wx.DC` drawing mode bit.

Transforms a RGB triplet into an html hex string.

:param `colour`: a tuple of red, green, blue integers.

Normalize a value as a function of the radius.

:param `x`: a float value to normalize

Calculates the slope of the line connecting 2 points.

dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
    (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
    d = {}
    for k, v in iterable:
        d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
    in the keyword argument list.  For example:  dict(one=1, two=2)

{'#B0171F': ['Indian red', '2037680', ''], '#DC143C': ['Crimson', '3937500', '#CC0033'], '#FFB6C1': ['Lightpink', '12695295', '#FFCCCC'], '#FFAEB9': ['Lightpink 1', '12168959', ''], '#EEA2AD': ['Lightpink 2', '11379438', ''], '#CD8C95': ['Lightpink 3', '9800909', ''], '#8B5F65': ['Lightpink 4', '6643595', ''], '#FFC0CB': ['Pink', '13353215', '#FFCCCC'], '#FFB5C5': ['Pink 1', '12957183', ''], '#EEA9B8': ['Pink 2', '12102126', ''], '#CD919E': ['Pink 3', '10392013', ''], '#8B636C': ['Pink 4', '7103371', ''], '#DB7093': ['Palevioletred', '9662683', '#CC6699'], '#FF82AB': ['Palevioletred 1', '11240191', ''], '#EE799F': ['Palevioletred 2', '10451438', ''], '#CD6889': ['Palevioletred 3', '9005261', ''], '#8B475D': ['Palevioletred 4', '6113163', ''], '#FFF0F5': ['Lavenderblush 1 (lavenderblush)', '16118015', '#FFFFFF'], '#EEE0E5': ['Lavenderblush 2', '15065326', ''], '#CDC1C5': ['Lavenderblush 3', '12960205', ''], '#8B8386': ['Lavenderblush 4', '8815499', ''], '#FF3E96': ['Violetred 1', '9846527', ''], '#EE3A8C': ['Violetred 2', '9190126', ''], '#CD3278': ['Violetred 3', '7877325', ''], '#8B2252': ['Violetred 4', '5382795', ''], '#FF69B4': ['Hotpink', '11823615', '#FF66CC'], '#FF6EB4': ['Hotpink 1', '11824895', ''], '#EE6AA7': ['Hotpink 2', '10971886', ''], '#CD6090': ['Hotpink 3', '9461965', ''], '#8B3A62': ['Hotpink 4', '6437515', ''], '#872657': ['Raspberry', '5711495', ''], '#FF1493': ['Deeppink 1 (deeppink)', '9639167', '#FF0099'], '#EE1289': ['Deeppink 2', '8983278', ''], '#CD1076': ['Deeppink 3', '7737549', ''], '#8B0A50': ['Deeppink 4', '5245579', ''], '#FF34B3': ['Maroon 1', '11744511', ''], '#EE30A7': ['Maroon 2', '10957038', ''], '#CD2990': ['Maroon 3', '9447885', ''], '#8B1C62': ['Maroon 4', '6429835', ''], '#C71585': ['Mediumvioletred', '8721863', '#CC0066'], '#D02090': ['Violetred', '9445584', ''], '#DA70D6': ['Orchid', '14053594', '#CC66CC'], '#FF83FA': ['Orchid 1', '16417791', ''], '#EE7AE9': ['Orchid 2', '15301358', ''], '#CD69C9': ['Orchid 3', '13199821', ''], '#8B4789': ['Orchid 4', '8996747', ''], '#D8BFD8': ['Thistle', '14204888', '#CCCCCC'], '#FFE1FF': ['Thistle 1', '16769535', ''], '#EED2EE': ['Thistle 2', '15651566', ''], '#CDB5CD': ['Thistle 3', '13481421', ''], '#8B7B8B': ['Thistle 4', '9141131', ''], '#FFBBFF': ['Plum 1', '16759807', ''], '#EEAEEE': ['Plum 2', '15642350', ''], '#CD96CD': ['Plum 3', '13473485', ''], '#8B668B': ['Plum 4', '9135755', ''], '#DDA0DD': ['Plum', '14524637', '#CC99CC'], '#EE82EE': ['Violet', '15631086', '#FF99FF'], '#FF00FF': ['Magenta (fuchsia)', '16711935', '#FF00FF'], '#EE00EE': ['Magenta 2', '15597806', ''], '#CD00CD': ['Magenta 3', '13435085', ''], '#8B008B': ['Magenta 4 (darkmagenta)', '9109643', '#990099'], '#800080': ['Purple', '8388736', '#990099'], '#BA55D3': ['Mediumorchid', '13850042', '#CC66CC'], '#E066FF': ['Mediumorchid 1', '16738016', ''], '#D15FEE': ['Mediumorchid 2', '15622097', ''], '#B452CD': ['Mediumorchid 3', '13456052', ''], '#7A378B': ['Mediumorchid 4', '9123706', ''], '#9400D3': ['Darkviolet', '13828244', '#9900CC'], '#9932CC': ['Darkorchid', '13382297', '#9933CC'], '#BF3EFF': ['Darkorchid 1', '16727743', ''], '#B23AEE': ['Darkorchid 2', '15612594', ''], '#9A32CD': ['Darkorchid 3', '13447834', ''], '#68228B': ['Darkorchid 4', '9118312', ''], '#4B0082': ['Indigo', '8519755', '#330099'], '#8A2BE2': ['Blueviolet', '14822282', '#9933FF'], '#9B30FF': ['Purple 1', '16724123', ''], '#912CEE': ['Purple 2', '15608977', ''], '#7D26CD': ['Purple 3', '13444733', ''], '#551A8B': ['Purple 4', '9116245', ''], '#9370DB': ['Mediumpurple', '14381203', '#9966CC'], '#AB82FF': ['Mediumpurple 1', '16745131', ''], '#9F79EE': ['Mediumpurple 2', '15628703', ''], '#8968CD': ['Mediumpurple 3', '13461641', ''], '#5D478B': ['Mediumpurple 4', '9127773', ''], '#483D8B': ['Darkslateblue', '9125192', '#333399'], '#8470FF': ['Lightslateblue', '16740484', ''], '#7B68EE': ['Mediumslateblue', '15624315', '#6666FF'], '#6A5ACD': ['Slateblue', '13458026', '#6666CC'], '#836FFF': ['Slateblue 1', '16740227', ''], '#7A67EE': ['Slateblue 2', '15624058', ''], '#6959CD': ['Slateblue 3', '13457769', ''], '#473C8B': ['Slateblue 4', '9124935', ''], '#F8F8FF': ['Ghostwhite', '16775416', '#FFFFFF'], '#E6E6FA': ['Lavender', '16443110', '#FFFFFF'], '#0000FF': ['Blue', '16711680', '#0000FF'], '#0000EE': ['Blue 2', '15597568', ''], '#0000CD': ['Blue 3 (mediumblue)', '13434880', '#0000CC'], '#00008B': ['Blue 4 (darkblue)', '9109504', '#000099'], '#000080': ['Navy', '8388608', '#000099'], '#191970': ['Midnightblue', '7346457', '#000066'], '#3D59AB': ['Cobalt', '11229501', ''], '#4169E1': ['Royalblue', '14772545', '#3366CC'], '#4876FF': ['Royalblue 1', '16741960', ''], '#436EEE': ['Royalblue 2', '15625795', ''], '#3A5FCD': ['Royalblue 3', '13459258', ''], '#27408B': ['Royalblue 4', '9125927', ''], '#6495ED': ['Cornflowerblue', '15570276', '#6699FF'], '#B0C4DE': ['Lightsteelblue', '14599344', '#99CCCC'], '#CAE1FF': ['Lightsteelblue 1', '16769482', ''], '#BCD2EE': ['Lightsteelblue 2', '15651516', ''], '#A2B5CD': ['Lightsteelblue 3', '13481378', ''], '#6E7B8B': ['Lightsteelblue 4', '9141102', ''], '#778899': ['Lightslategray', '10061943', '#669999'], '#708090': ['Slategray', '9470064', '#669999'], '#C6E2FF': ['Slategray 1', '16769734', ''], '#B9D3EE': ['Slategray 2', '15651769', ''], '#9FB6CD': ['Slategray 3', '13481631', ''], '#6C7B8B': ['Slategray 4', '9141100', ''], '#1E90FF': ['Dodgerblue 1 (dodgerblue)', '16748574', '#3399FF'], '#1C86EE': ['Dodgerblue 2', '15631900', ''], '#1874CD': ['Dodgerblue 3', '13464600', ''], '#104E8B': ['Dodgerblue 4', '9129488', ''], '#F0F8FF': ['Aliceblue', '16775408', '#FFFFFF'], '#4682B4': ['Steelblue', '11829830', '#3399CC'], '#63B8FF': ['Steelblue 1', '16758883', ''], '#5CACEE': ['Steelblue 2', '15641692', ''], '#4F94CD': ['Steelblue 3', '13472847', ''], '#36648B': ['Steelblue 4', '9135158', ''], '#87CEFA': ['Lightskyblue', '16436871', '#99CCFF'], '#B0E2FF': ['Lightskyblue 1', '16769712', ''], '#A4D3EE': ['Lightskyblue 2', '15651748', ''], '#8DB6CD': ['Lightskyblue 3', '13481613', ''], '#607B8B': ['Lightskyblue 4', '9141088', ''], '#87CEFF': ['Skyblue 1', '16764551', ''], '#7EC0EE': ['Skyblue 2', '15646846', ''], '#6CA6CD': ['Skyblue 3', '13477484', ''], '#4A708B': ['Skyblue 4', '9138250', ''], '#87CEEB': ['Skyblue', '15453831', '#99CCFF'], '#00BFFF': ['Deepskyblue 1 (deepskyblue)', '16760576', '#00CCFF'], '#00B2EE': ['Deepskyblue 2', '15643136', ''], '#009ACD': ['Deepskyblue 3', '13474304', ''], '#00688B': ['Deepskyblue 4', '9136128', ''], '#33A1C9': ['Peacock', '13214003', ''], '#ADD8E6': ['Lightblue', '15128749', '#99CCFF'], '#BFEFFF': ['Lightblue 1', '16773055', ''], '#B2DFEE': ['Lightblue 2', '15654834', ''], '#9AC0CD': ['Lightblue 3', '13484186', ''], '#68838B': ['Lightblue 4', '9143144', ''], '#B0E0E6': ['Powderblue', '15130800', '#CCCCFF'], '#98F5FF': ['Cadetblue 1', '16774552', ''], '#8EE5EE': ['Cadetblue 2', '15656334', ''], '#7AC5CD': ['Cadetblue 3', '13485434', ''], '#53868B': ['Cadetblue 4', '9143891', ''], '#00F5FF': ['Turquoise 1', '16774400', ''], '#00E5EE': ['Turquoise 2', '15656192', ''], '#00C5CD': ['Turquoise 3', '13485312', ''], '#00868B': ['Turquoise 4', '9143808', ''], '#5F9EA0': ['Cadetblue', '10526303', '#669999'], '#00CED1': ['Darkturquoise', '13749760', '#00CCCC'], '#F0FFFF': ['Azure 1 (azure)', '16777200', '#FFFFFF'], '#E0EEEE': ['Azure 2', '15658720', ''], '#C1CDCD': ['Azure 3', '13487553', ''], '#838B8B': ['Azure 4', '9145219', ''], '#E0FFFF': ['Lightcyan 1 (lightcyan)', '16777184', '#CCFFFF'], '#D1EEEE': ['Lightcyan 2', '15658705', ''], '#B4CDCD': ['Lightcyan 3', '13487540', ''], '#7A8B8B': ['Lightcyan 4', '9145210', ''], '#BBFFFF': ['Paleturquoise 1', '16777147', ''], '#AEEEEE': ['Paleturquoise 2 (paleturquoise)', '15658670', ''], '#96CDCD': ['Paleturquoise 3', '13487510', ''], '#668B8B': ['Paleturquoise 4', '9145190', ''], '#2F4F4F': ['Darkslategray', '5197615', '#336666'], '#97FFFF': ['Darkslategray 1', '16777111', ''], '#8DEEEE': ['Darkslategray 2', '15658637', ''], '#79CDCD': ['Darkslategray 3', '13487481', ''], '#528B8B': ['Darkslategray 4', '9145170', ''], '#00FFFF': ['Cyan / aqua', '16776960', '#00FFFF'], '#00EEEE': ['Cyan 2', '15658496', ''], '#00CDCD': ['Cyan 3', '13487360', ''], '#008B8B': ['Cyan 4 (darkcyan)', '9145088', '#009999'], '#008080': ['Teal', '8421376', '#009999'], '#48D1CC': ['Mediumturquoise', '13422920', '#33CCCC'], '#20B2AA': ['Lightseagreen', '11186720', '#339999'], '#03A89E': ['Manganeseblue', '10397699', ''], '#40E0D0': ['Turquoise', '13688896', '#33CCCC'], '#808A87': ['Coldgrey', '8882816', ''], '#00C78C': ['Turquoiseblue', '9225984', ''], '#7FFFD4': ['Aquamarine 1 (aquamarine)', '13959039', '#66FFCC'], '#76EEC6': ['Aquamarine 2', '13037174', ''], '#66CDAA': ['Aquamarine 3 (mediumaquamarine)', '11193702', '#66CC99'], '#458B74': ['Aquamarine 4', '7637829', ''], '#00FA9A': ['Mediumspringgreen', '10156544', '#00FF99'], '#F5FFFA': ['Mintcream', '16449525', '#FFFFFF'], '#00FF7F': ['Springgreen', '8388352', '#00FF66'], '#00EE76': ['Springgreen 1', '7794176', ''], '#00CD66': ['Springgreen 2', '6737152', ''], '#008B45': ['Springgreen 3', '4557568', ''], '#3CB371': ['Mediumseagreen', '7451452', '#33CC66'], '#54FF9F': ['Seagreen 1', '10485588', ''], '#4EEE94': ['Seagreen 2', '9760334', ''], '#43CD80': ['Seagreen 3', '8441155', ''], '#2E8B57': ['Seagreen 4 (seagreen)', '5737262', '#339966'], '#00C957': ['Emeraldgreen', '5753088', ''], '#BDFCC9': ['Mint', '13237437', ''], '#3D9140': ['Cobaltgreen', '4231485', ''], '#F0FFF0': ['Honeydew 1 (honeydew)', '15794160', '#FFFFFF'], '#E0EEE0': ['Honeydew 2', '14741216', ''], '#C1CDC1': ['Honeydew 3', '12701121', ''], '#838B83': ['Honeydew 4', '8620931', ''], '#8FBC8F': ['Darkseagreen', '9419919', '#99CC99'], '#C1FFC1': ['Darkseagreen 1', '12713921', ''], '#B4EEB4': ['Darkseagreen 2', '11857588', ''], '#9BCD9B': ['Darkseagreen 3', '10210715', ''], '#698B69': ['Darkseagreen 4', '6916969', ''], '#98FB98': ['Palegreen', '10025880', '#99FF99'], '#9AFF9A': ['Palegreen 1', '10157978', ''], '#90EE90': ['Palegreen 2 (lightgreen)', '9498256', '#99FF99'], '#7CCD7C': ['Palegreen 3', '8179068', ''], '#548B54': ['Palegreen 4', '5540692', ''], '#32CD32': ['Limegreen', '3329330', '#33CC33'], '#228B22': ['Forestgreen', '2263842', '#339933'], '#00FF00': ['Green 1 (lime)', '65280', '#00FF00'], '#00EE00': ['Green 2', '60928', ''], '#00CD00': ['Green 3', '52480', ''], '#008B00': ['Green 4', '35584', ''], '#008000': ['Green', '32768', '#009900'], '#006400': ['Darkgreen', '25600', '#006600'], '#308014': ['Sapgreen', '1343536', ''], '#7CFC00': ['Lawngreen', '64636', '#66FF00'], '#7FFF00': ['Chartreuse 1 (chartreuse)', '65407', '#66FF00'], '#76EE00': ['Chartreuse 2', '61046', ''], '#66CD00': ['Chartreuse 3', '52582', ''], '#458B00': ['Chartreuse 4', '35653', ''], '#ADFF2F': ['Greenyellow', '3145645', '#99FF33'], '#CAFF70': ['Darkolivegreen 1', '7405514', ''], '#BCEE68': ['Darkolivegreen 2', '6876860', ''], '#A2CD5A': ['Darkolivegreen 3', '5950882', ''], '#6E8B3D': ['Darkolivegreen 4', '4033390', ''], '#556B2F': ['Darkolivegreen', '3107669', '#666633'], '#6B8E23': ['Olivedrab', '2330219', '#669933'], '#C0FF3E': ['Olivedrab 1', '4128704', ''], '#B3EE3A': ['Olivedrab 2', '3862195', ''], '#9ACD32': ['Olivedrab 3 (yellowgreen)', '3329434', '#99CC33'], '#698B22': ['Olivedrab 4', '2263913', ''], '#FFFFF0': ['Ivory 1 (ivory)', '15794175', '#FFFFFF'], '#EEEEE0': ['Ivory 2', '14741230', ''], '#CDCDC1': ['Ivory 3', '12701133', ''], '#8B8B83': ['Ivory 4', '8620939', ''], '#F5F5DC': ['Beige', '14480885', '#FFFFCC'], '#FFFFE0': ['Lightyellow 1 (lightyellow)', '14745599', '#FFFFFF'], '#EEEED1': ['Lightyellow 2', '13758190', ''], '#CDCDB4': ['Lightyellow 3', '11849165', ''], '#8B8B7A': ['Lightyellow 4', '8031115', ''], '#FAFAD2': ['Lightgoldenrodyellow', '13826810', '#FFFFCC'], '#FFFF00': ['Yellow 1 (yellow)', '65535', '#FFFF00'], '#EEEE00': ['Yellow 2', '61166', ''], '#CDCD00': ['Yellow 3', '52685', ''], '#8B8B00': ['Yellow 4', '35723', ''], '#808069': ['Warmgrey', '6914176', ''], '#808000': ['Olive', '32896', '#999900'], '#BDB76B': ['Darkkhaki', '7059389', '#CCCC66'], '#FFF68F': ['Khaki 1', '9434879', ''], '#EEE685': ['Khaki 2', '8775406', ''], '#CDC673': ['Khaki 3', '7587533', ''], '#8B864E': ['Khaki 4', '5146251', ''], '#F0E68C': ['Khaki', '9234160', ''], '#EEE8AA': ['Palegoldenrod', '11200750', '#FFFF99'], '#FFFACD': ['Lemonchiffon 1 (lemonchiffon)', '13499135', '#FFFFCC'], '#EEE9BF': ['Lemonchiffon 2', '12577262', ''], '#CDC9A5': ['Lemonchiffon 3', '10865101', ''], '#8B8970': ['Lemonchiffon 4', '7375243', ''], '#FFEC8B': ['Lightgoldenrod 1', '9170175', ''], '#EEDC82': ['Lightgoldenrod 2', '8576238', ''], '#CDBE70': ['Lightgoldenrod 3', '7388877', ''], '#8B814C': ['Lightgoldenrod 4', '5013899', ''], '#E3CF57': ['Banana', '5754851', ''], '#FFD700': ['Gold 1 (gold)', '55295', '#FFCC00'], '#EEC900': ['Gold 2', '51694', ''], '#CDAD00': ['Gold 3', '44493', ''], '#8B7500': ['Gold 4', '30091', ''], '#FFF8DC': ['Cornsilk 1 (cornsilk)', '14481663', '#FFFFCC'], '#EEE8CD': ['Cornsilk 2', '13494510', ''], '#CDC8B1': ['Cornsilk 3', '11651277', ''], '#8B8878': ['Cornsilk 4', '7899275', ''], '#DAA520': ['Goldenrod', '2139610', '#CC9933'], '#FFC125': ['Goldenrod 1', '2474495', ''], '#EEB422': ['Goldenrod 2', '2274542', ''], '#CD9B1D': ['Goldenrod 3', '1940429', ''], '#8B6914': ['Goldenrod 4', '1337739', ''], '#B8860B': ['Darkgoldenrod', '755384', '#CC9900'], '#FFB90F': ['Darkgoldenrod 1', '1030655', ''], '#EEAD0E': ['Darkgoldenrod 2', '962030', ''], '#CD950C': ['Darkgoldenrod 3', '824781', ''], '#8B6508': ['Darkgoldenrod 4', '550283', ''], '#FFA500': ['Orange 1 (orange)', '42495', '#FF9900'], '#EE9A00': ['Orange 2', '39662', ''], '#CD8500': ['Orange 3', '34253', ''], '#8B5A00': ['Orange 4', '23179', ''], '#FFFAF0': ['Floralwhite', '15792895', '#FFFFFF'], '#FDF5E6': ['Oldlace', '15136253', '#FFFFFF'], '#F5DEB3': ['Wheat', '11788021', '#FFCCCC'], '#FFE7BA': ['Wheat 1', '12249087', ''], '#EED8AE': ['Wheat 2', '11458798', ''], '#CDBA96': ['Wheat 3', '9878221', ''], '#8B7E66': ['Wheat 4', '6717067', ''], '#FFE4B5': ['Moccasin', '11920639', '#FFCCCC'], '#FFEFD5': ['Papayawhip', '14020607', '#FFFFCC'], '#FFEBCD': ['Blanchedalmond', '13495295', '#FFFFCC'], '#FFDEAD': ['Navajowhite 1 (navajowhite)', '11394815', '#FFCC99'], '#EECFA1': ['Navajowhite 2', '10604526', ''], '#CDB38B': ['Navajowhite 3', '9155533', ''], '#8B795E': ['Navajowhite 4', '6191499', ''], '#FCE6C9': ['Eggshell', '13231868', ''], '#D2B48C': ['Tan', '9221330', '#CCCC99'], '#9C661F': ['Brick', '2057884', ''], '#FF9912': ['Cadmiumyellow', '1219071', ''], '#FAEBD7': ['Antiquewhite', '14150650', '#FFFFCC'], '#FFEFDB': ['Antiquewhite 1', '14413823', ''], '#EEDFCC': ['Antiquewhite 2', '13426670', ''], '#CDC0B0': ['Antiquewhite 3', '11583693', ''], '#8B8378': ['Antiquewhite 4', '7897995', ''], '#DEB887': ['Burlywood', '8894686', '#CCCC99'], '#FFD39B': ['Burlywood 1', '10212351', ''], '#EEC591': ['Burlywood 2', '9553390', ''], '#CDAA7D': ['Burlywood 3', '8235725', ''], '#8B7355': ['Burlywood 4', '5600139', ''], '#FFE4C4': ['Bisque 1 (bisque)', '12903679', '#FFFFCC'], '#EED5B7': ['Bisque 2', '12047854', ''], '#CDB79E': ['Bisque 3', '10401741', ''], '#8B7D6B': ['Bisque 4', '7044491', ''], '#E3A869': ['Melon', '6924515', ''], '#ED9121': ['Carrot', '2200045', ''], '#FF8C00': ['Darkorange', '36095', '#FF9900'], '#FF7F00': ['Darkorange 1', '32767', ''], '#EE7600': ['Darkorange 2', '30446', ''], '#CD6600': ['Darkorange 3', '26317', ''], '#8B4500': ['Darkorange 4', '17803', ''], '#FF8000': ['Orange', '33023', ''], '#FFA54F': ['Tan 1', '5219839', ''], '#EE9A49': ['Tan 2', '4823790', ''], '#CD853F': ['Tan 3 (peru)', '4163021', '#CC9933'], '#8B5A2B': ['Tan 4', '2841227', ''], '#FAF0E6': ['Linen', '15134970', '#FFFFFF'], '#FFDAB9': ['Peachpuff 1 (peachpuff)', '12180223', '#FFCCCC'], '#EECBAD': ['Peachpuff 2', '11389934', ''], '#CDAF95': ['Peachpuff 3', '9809869', ''], '#8B7765': ['Peachpuff 4', '6649739', ''], '#FFF5EE': ['Seashell 1 (seashell)', '15660543', '#FFFFFF'], '#EEE5DE': ['Seashell 2', '14607854', ''], '#CDC5BF': ['Seashell 3', '12568013', ''], '#8B8682': ['Seashell 4', '8554123', ''], '#F4A460': ['Sandybrown', '6333684', '#FF9966'], '#C76114': ['Rawsienna', '1335751', ''], '#D2691E': ['Chocolate', '1993170', '#CC6633'], '#FF7F24': ['Chocolate 1', '2392063', ''], '#EE7621': ['Chocolate 2', '2193134', ''], '#CD661D': ['Chocolate 3', '1926861', ''], '#8B4513': ['Chocolate 4 (saddlebrown)', '1262987', '#993300'], '#292421': ['Ivoryblack', '2171945', ''], '#FF7D40': ['Flesh', '4226559', ''], '#FF6103': ['Cadmiumorange', '221695', ''], '#8A360F': ['Burntsienna', '997002', ''], '#A0522D': ['Sienna', '2970272', '#996633'], '#FF8247': ['Sienna 1', '4686591', ''], '#EE7942': ['Sienna 2', '4356590', ''], '#CD6839': ['Sienna 3', '3762381', ''], '#8B4726': ['Sienna 4', '2508683', ''], '#FFA07A': ['Lightsalmon 1 (lightsalmon)', '8036607', '#FF9966'], '#EE9572': ['Lightsalmon 2', '7509486', ''], '#CD8162': ['Lightsalmon 3', '6455757', ''], '#8B5742': ['Lightsalmon 4', '4347787', ''], '#FF7F50': ['Coral', '5275647', '#FF6666'], '#FF4500': ['Orangered 1 (orangered)', '17919', '#FF3300'], '#EE4000': ['Orangered 2', '16622', ''], '#CD3700': ['Orangered 3', '14285', ''], '#8B2500': ['Orangered 4', '9611', ''], '#5E2612': ['Sepia', '1189470', ''], '#E9967A': ['Darksalmon', '8034025', '#FF9966'], '#FF8C69': ['Salmon 1', '6917375', ''], '#EE8262': ['Salmon 2', '6456046', ''], '#CD7054': ['Salmon 3', '5533901', ''], '#8B4C39': ['Salmon 4', '3755147', ''], '#FF7256': ['Coral 1', '5665535', ''], '#EE6A50': ['Coral 2', '5270254', ''], '#CD5B45': ['Coral 3', '4545485', ''], '#8B3E2F': ['Coral 4', '3096203', ''], '#8A3324': ['Burntumber', '2372490', ''], '#FF6347': ['Tomato 1 (tomato)', '4678655', '#FF6633'], '#EE5C42': ['Tomato 2', '4349166', ''], '#CD4F39': ['Tomato 3', '3755981', ''], '#8B3626': ['Tomato 4', '2504331', ''], '#FA8072': ['Salmon', '7504122', '#FF9966'], '#FFE4E1': ['Mistyrose 1 (mistyrose)', '14804223', '#FFCCFF'], '#EED5D2': ['Mistyrose 2', '13817326', ''], '#CDB7B5': ['Mistyrose 3', '11909069', ''], '#8B7D7B': ['Mistyrose 4', '8093067', ''], '#FFFAFA': ['Snow 1 (snow)', '16448255', '#FFFFFF'], '#EEE9E9': ['Snow 2', '15329774', ''], '#CDC9C9': ['Snow 3', '13224397', ''], '#8B8989': ['Snow 4', '9013643', ''], '#BC8F8F': ['Rosybrown', '9408444', '#CC9999'], '#FFC1C1': ['Rosybrown 1', '12698111', ''], '#EEB4B4': ['Rosybrown 2', '11842798', ''], '#CD9B9B': ['Rosybrown 3', '10197965', ''], '#8B6969': ['Rosybrown 4', '6908299', ''], '#F08080': ['Lightcoral', '8421616', '#FF9999'], '#CD5C5C': ['Indianred', '6053069', '#CC6666'], '#FF6A6A': ['Indianred 1', '6974207', ''], '#EE6363': ['Indianred 2', '6513646', ''], '#8B3A3A': ['Indianred 4', '3816075', ''], '#CD5555': ['Indianred 3', '5592525', ''], '#A52A2A': ['Brown', '2763429', '#993333'], '#FF4040': ['Brown 1', '4210943', ''], '#EE3B3B': ['Brown 2', '3881966', ''], '#CD3333': ['Brown 3', '3355597', ''], '#8B2323': ['Brown 4', '2302859', ''], '#B22222': ['Firebrick', '2237106', '#993333'], '#FF3030': ['Firebrick 1', '3158271', ''], '#EE2C2C': ['Firebrick 2', '2895086', ''], '#CD2626': ['Firebrick 3', '2500301', ''], '#8B1A1A': ['Firebrick 4', '1710731', ''], '#FF0000': ['Red 1 (red)', '255', '#FF0000'], '#EE0000': ['Red 2', '238', ''], '#CD0000': ['Red 3', '205', ''], '#8B0000': ['Red 4 (darkred)', '139', '#990000'], '#800000': ['Maroon', '128', '#990000'], '#8E388E': ['Sgi beet', '9320590', ''], '#7171C6': ['Sgi slateblue', '13005169', ''], '#7D9EC0': ['Sgi lightblue', '12623485', ''], '#388E8E': ['Sgi teal', '9342520', ''], '#71C671': ['Sgi chartreuse', '7456369', ''], '#8E8E38': ['Sgi olivedrab', '3706510', ''], '#C5C1AA': ['Sgi brightgray', '11190725', ''], '#C67171': ['Sgi salmon', '7434694', ''], '#555555': ['Sgi darkgray', '5592405', ''], '#1E1E1E': ['Sgi gray 12', '1973790', ''], '#282828': ['Sgi gray 16', '2631720', ''], '#515151': ['Sgi gray 32', '5329233', ''], '#5B5B5B': ['Sgi gray 36', '5987163', ''], '#848484': ['Sgi gray 52', '8684676', ''], '#8E8E8E': ['Sgi gray 56', '9342606', ''], '#AAAAAA': ['Sgi lightgray', '11184810', ''], '#B7B7B7': ['Sgi gray 72', '12040119', ''], '#C1C1C1': ['Sgi gray 76', '12698049', ''], '#EAEAEA': ['Sgi gray 92', '15395562', ''], '#F4F4F4': ['Sgi gray 96', '16053492', ''], '#FFFFFF': ['White', '16777215', '#FFFFFF'], '#F5F5F5': ['White smoke (gray)', '16119285', '#FFFFFF'], '#DCDCDC': ['Gainsboro', '14474460', '#CCCCCC'], '#D3D3D3': ['Lightgrey', '13882323', '#CCCCCC'], '#C0C0C0': ['Silver', '12632256', '#CCCCCC'], '#A9A9A9': ['Darkgray', '11119017', '#999999'], '#808080': ['Gray', '8421504', ''], '#696969': ['Dimgray (gray 42)', '6908265', '#666666'], '#000000': ['Black', '0', '#000000'], '#FCFCFC': ['Gray 99', '16579836', ''], '#FAFAFA': ['Gray 98', '16448250', ''], '#F7F7F7': ['Gray 97', '16250871', ''], '#F2F2F2': ['Gray 95', '15921906', ''], '#F0F0F0': ['Gray 94', '15790320', ''], '#EDEDED': ['Gray 93', '15592941', ''], '#EBEBEB': ['Gray 92', '15461355', ''], '#E8E8E8': ['Gray 91', '15263976', ''], '#E5E5E5': ['Gray 90', '15066597', ''], '#E3E3E3': ['Gray 89', '14935011', ''], '#E0E0E0': ['Gray 88', '14737632', ''], '#DEDEDE': ['Gray 87', '14606046', ''], '#DBDBDB': ['Gray 86', '14408667', ''], '#D9D9D9': ['Gray 85', '14277081', ''], '#D6D6D6': ['Gray 84', '14079702', ''], '#D4D4D4': ['Gray 83', '13948116', ''], '#D1D1D1': ['Gray 82', '13750737', ''], '#CFCFCF': ['Gray 81', '13619151', ''], '#CCCCCC': ['Gray 80', '13421772', ''], '#C9C9C9': ['Gray 79', '13224393', ''], '#C7C7C7': ['Gray 78', '13092807', ''], '#C4C4C4': ['Gray 77', '12895428', ''], '#C2C2C2': ['Gray 76', '12763842', ''], '#BFBFBF': ['Gray 75', '12566463', ''], '#BDBDBD': ['Gray 74', '12434877', ''], '#BABABA': ['Gray 73', '12237498', ''], '#B8B8B8': ['Gray 72', '12105912', ''], '#B5B5B5': ['Gray 71', '11908533', ''], '#B3B3B3': ['Gray 70', '11776947', ''], '#B0B0B0': ['Gray 69', '11579568', ''], '#ADADAD': ['Gray 68', '11382189', ''], '#ABABAB': ['Gray 67', '11250603', ''], '#A8A8A8': ['Gray 66', '11053224', ''], '#A6A6A6': ['Gray 65', '10921638', ''], '#A3A3A3': ['Gray 64', '10724259', ''], '#A1A1A1': ['Gray 63', '10592673', ''], '#9E9E9E': ['Gray 62', '10395294', ''], '#9C9C9C': ['Gray 61', '10263708', ''], '#999999': ['Gray 60', '10066329', ''], '#969696': ['Gray 59', '9868950', ''], '#949494': ['Gray 58', '9737364', ''], '#919191': ['Gray 57', '9539985', ''], '#8F8F8F': ['Gray 56', '9408399', ''], '#8C8C8C': ['Gray 55', '9211020', ''], '#8A8A8A': ['Gray 54', '9079434', ''], '#878787': ['Gray 53', '8882055', ''], '#858585': ['Gray 52', '8750469', ''], '#828282': ['Gray 51', '8553090', ''], '#7F7F7F': ['Gray 50', '8355711', ''], '#7D7D7D': ['Gray 49', '8224125', ''], '#7A7A7A': ['Gray 48', '8026746', ''], '#787878': ['Gray 47', '7895160', ''], '#757575': ['Gray 46', '7697781', ''], '#737373': ['Gray 45', '7566195', ''], '#707070': ['Gray 44', '7368816', ''], '#6E6E6E': ['Gray 43', '7237230', ''], '#6B6B6B': ['Gray 42', '7039851', ''], '#666666': ['Gray 40', '6710886', ''], '#636363': ['Gray 39', '6513507', ''], '#616161': ['Gray 38', '6381921', ''], '#5E5E5E': ['Gray 37', '6184542', ''], '#5C5C5C': ['Gray 36', '6052956', ''], '#595959': ['Gray 35', '5855577', ''], '#575757': ['Gray 34', '5723991', ''], '#545454': ['Gray 33', '5526612', ''], '#525252': ['Gray 32', '5395026', ''], '#4F4F4F': ['Gray 31', '5197647', ''], '#4D4D4D': ['Gray 30', '5066061', ''], '#4A4A4A': ['Gray 29', '4868682', ''], '#474747': ['Gray 28', '4671303', ''], '#454545': ['Gray 27', '4539717', ''], '#424242': ['Gray 26', '4342338', ''], '#404040': ['Gray 25', '4210752', ''], '#3D3D3D': ['Gray 24', '4013373', ''], '#3B3B3B': ['Gray 23', '3881787', ''], '#383838': ['Gray 22', '3684408', ''], '#363636': ['Gray 21', '3552822', ''], '#333333': ['Gray 20', '3355443', ''], '#303030': ['Gray 19', '3158064', ''], '#2E2E2E': ['Gray 18', '3026478', ''], '#2B2B2B': ['Gray 17', '2829099', ''], '#292929': ['Gray 16', '2697513', ''], '#262626': ['Gray 15', '2500134', ''], '#242424': ['Gray 14', '2368548', ''], '#212121': ['Gray 13', '2171169', ''], '#1F1F1F': ['Gray 12', '2039583', ''], '#1C1C1C': ['Gray 11', '1842204', ''], '#1A1A1A': ['Gray 10', '1710618', ''], '#171717': ['Gray 9', '1513239', ''], '#141414': ['Gray 8', '1315860', ''], '#121212': ['Gray 7', '1184274', ''], '#0F0F0F': ['Gray 6', '986895', ''], '#0D0D0D': ['Gray 5', '855309', ''], '#0A0A0A': ['Gray 4', '657930', ''], '#080808': ['Gray 3', '526344', ''], '#050505': ['Gray 2', '328965', ''], '#030303': ['Gray 1', '197379', '']}

Point()
Point(x, y)
Point(pt)

A wxPoint is a useful data structure for graphics operations.

The ``customtreectrl`` module contains the :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` class
which mimics the behaviour of :class:`TreeCtrl`, with some more enhancements.

:class:`CustomTreeCtrl` is a class that mimics the behaviour of :class:`TreeCtrl`, with almost the
same base functionalities plus some more enhancements. This class does not rely on
the native control, as it is a full owner-drawn tree control.
Apart of the base functionalities of :class:`CustomTreeCtrl` (described below), in addition
to the standard :class:`TreeCtrl` behaviour this class supports:

* CheckBox-type items: checkboxes are easy to handle, just selected or unselected
  state with no particular issues in handling the item's children;
* Added support for 3-state value checkbox items;
* RadioButton-type items: since I elected to put radiobuttons in :class:`CustomTreeCtrl`, I
  needed some way to handle them, that made sense. So, I used the following approach:

  - All peer-nodes that are radiobuttons will be mutually exclusive. In other words,
    only one of a set of radiobuttons that share a common parent can be checked at
    once. If a radiobutton node becomes checked, then all of its peer radiobuttons
    must be unchecked.
  - If a radiobutton node becomes unchecked, then all of its child nodes will become
    inactive.

* Hyperlink-type items: they look like an hyperlink, with the proper mouse cursor on
  hovering;
* Multiline text items (**note**: to add a newline character in a multiline item, press
  ``Shift`` + ``Enter`` as the ``Enter`` key alone is consumed by :class:`CustomTreeCtrl` to finish
  the editing and ``Ctrl`` + ``Enter`` is consumed by the platform for tab navigation);
* Enabling/disabling items (together with their plain or grayed out icons);
* Whatever non-toplevel widget can be attached next to an item;
* Possibility to horizontally align the widgets attached to tree items on the
  same tree level.
* Possibility to align the widgets attached to tree items to the rightmost edge of :class:`CustomTreeCtrl`;
* Default selection style, gradient (horizontal/vertical) selection style and Windows
  Vista selection style;
* Customized drag and drop images built on the fly;
* Setting the :class:`CustomTreeCtrl` item buttons to a personalized imagelist;
* Setting the :class:`CustomTreeCtrl` check/radio item icons to a personalized imagelist;
* Changing the style of the lines that connect the items (in terms of :class:`wx.Pen` styles);
* Using an image as a :class:`CustomTreeCtrl` background (currently only in "tile" mode);
* Adding images to any item in the leftmost area of the :class:`CustomTreeCtrl` client window.
* Separator-type items which are simply visual indicators that are meant to set apart
  or divide tree items, with the following caveats:

  - Separator items should not have children, labels, data or an associated window;
  - You can change the color of individual separators by using :meth:`~CustomTreeCtrl.SetItemTextColour`, or you can use
    :meth:`~CustomTreeCtrl.SetSeparatorColour` to change the color of all separators. The default separator colour
    is that returned by `SystemSettings.GetColour(wx.SYS_COLOUR_GRAYTEXT)`;
  - Separators can be selected just like any other tree item;
  - Separators cannot have text;
  - Separators cannot have children;
  - Separators cannot be edited via the ``EVT_TREE_BEGIN_LABEL_EDIT`` event.

* Ellipsization of long items when the horizontal space is low, via the ``TR_ELLIPSIZE_LONG_ITEMS``
  style (`New in version 0.9.3`);
* Tooltips on long items when the horizontal space is low, via the ``TR_TOOLTIP_ON_LONG_ITEMS``
  style (`New in version 0.9.3`).
* Hiding items

:class:`CustomTreeCtrl` supports all the :class:`TreeCtrl` styles, except:

- ``TR_EXTENDED``: supports for this style is on the todo list (am I sure of this?).

Plus it has 3 more styles to handle checkbox-type items:

- ``TR_AUTO_CHECK_CHILD``: automatically checks/unchecks the item children;
- ``TR_AUTO_CHECK_PARENT``: automatically checks/unchecks the item parent;
- ``TR_AUTO_TOGGLE_CHILD``: automatically toggles the item children.

And two styles you can use to force the horizontal alignment of all the widgets
attached to the tree items:

- ``TR_ALIGN_WINDOWS``: aligns horizontally the windows belonging to the item on the
- ``TR_ALIGN_WINDOWS_RIGHT``: aligns to the rightmost position the windows belonging
  to the item on the same tree level.

And two styles related to long items (with a lot of text in them), which can be
ellipsized and/or highlighted with a tooltip:

- ``TR_ELLIPSIZE_LONG_ITEMS``: ellipsizes long items when the horizontal space for
  :class:`CustomTreeCtrl` is low (`New in version 0.9.3`);
- ``TR_TOOLTIP_ON_LONG_ITEMS``: shows tooltips on long items when the horizontal space
  for :class:`CustomTreeCtrl` is low (`New in version 0.9.3`);.

All the methods available in :class:`TreeCtrl` are also available in :class:`CustomTreeCtrl`.

Usage
=====

    import wx
    import wx.lib.agw.customtreectrl as CT

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

            # Create a CustomTreeCtrl instance
            custom_tree = CT.CustomTreeCtrl(self, agwStyle=wx.TR_DEFAULT_STYLE)

            # Add a root node to it
            root = custom_tree.AddRoot("The Root Item")

            # Create an image list to add icons next to an item
            il = wx.ImageList(16, 16)
            fldridx     = il.Add(wx.ArtProvider.GetBitmap(wx.ART_FOLDER,      wx.ART_OTHER, (16, 16)))
            fldropenidx = il.Add(wx.ArtProvider.GetBitmap(wx.ART_FILE_OPEN,   wx.ART_OTHER, (16, 16)))
            fileidx     = il.Add(wx.ArtProvider.GetBitmap(wx.ART_NORMAL_FILE, wx.ART_OTHER, (16, 16)))

            custom_tree.SetImageList(il)

            custom_tree.SetItemImage(root, fldridx, wx.TreeItemIcon_Normal)
            custom_tree.SetItemImage(root, fldropenidx, wx.TreeItemIcon_Expanded)

            for x in range(15):
                child = custom_tree.AppendItem(root, "Item %d" % x)
                custom_tree.SetItemImage(child, fldridx, wx.TreeItemIcon_Normal)
                custom_tree.SetItemImage(child, fldropenidx, wx.TreeItemIcon_Expanded)

                for y in range(5):
                    last = custom_tree.AppendItem(child, "item %d-%s" % (x, chr(ord("a")+y)))
                    custom_tree.SetItemImage(last, fldridx, wx.TreeItemIcon_Normal)
                    custom_tree.SetItemImage(last, fldropenidx, wx.TreeItemIcon_Expanded)

                    for z in range(5):
                        item = custom_tree.AppendItem(last,  "item %d-%s-%d" % (x, chr(ord("a")+y), z))
                        custom_tree.SetItemImage(item, fileidx, wx.TreeItemIcon_Normal)

            custom_tree.Expand(root)

Events
======

All the events supported by :class:`TreeCtrl` are also available in :class:`CustomTreeCtrl`, with
a few exceptions:

- ``EVT_TREE_GET_INFO`` (don't know what this means);
- ``EVT_TREE_SET_INFO`` (don't know what this means);
- ``EVT_TREE_ITEM_MIDDLE_CLICK`` (not implemented, but easy to add);
- ``EVT_TREE_STATE_IMAGE_CLICK`` (no need for that, look at the checking events below).

Plus, :class:`CustomTreeCtrl` supports the events related to the checkbutton-type items:

- ``EVT_TREE_ITEM_CHECKING``: an item is being checked;
- ``EVT_TREE_ITEM_CHECKED``: an item has been checked.

And to hyperlink-type items:

- ``EVT_TREE_ITEM_HYPERLINK``: an hyperlink item has been clicked (this event is sent
  after the ``EVT_TREE_SEL_CHANGED`` event).

Drag and Drop

A simplified drag and drop is available and can be initiated by calling
``event.Allow`` on the ``EVT_TREE_BEGIN_DRAG`` or ``EVT_TREE_BEGIN_RDRAG``
events. When the event handler returns, a ``wx.DragImage`` of the item will be
generated and the user can drag it to other items within the tree. When the
user releases the drag button a ``EVT_TREE_END_DRAG`` event will be sent and
``event.GetItem`` can be called to find out which item the drag ended at.
This simplified method is best when only a single item at a time needs to
be dragged (i.e. ``TR_MULTIPLE`` not set) and only for dragging items within
the tree control.

Alternately, the normal wxPython drag/drop can be invoked in the ``EVT_TREE_BEGIN_DRAG``
handler in which a :class:`wx.DropSource` must be generated, followed by a call
to :meth:`~wx.DropSource.DoDragDrop` which will block until the drag is finished.
This is much more flexible but more complicated to implement.

:note: The class value _DRAG_TIMER_TICKS controls how long the mouse must
 linger before the drag can start. It defaults to 250 milliseconds which can
 be far too long for today's quick 'swiping' generation. It can be lowered for
 a more responsive drag.

:class:`CustomTreeCtrl` has been tested on the following platforms:
  * GTK (Thanks to Michele Petrazzo);
  * Mac OS (Thanks to John Jackson).

This class takes in a regular wxPython ``style`` and an extended ``agwStyle``.
The ``style`` can be used with normal wxPython styles such as ``wx.WANTS_CHARS``
while the ``agwStyle`` specifies the behavior of the tree itself.
It supports the following ``agwStyle`` flags:

================================= =========== ==================================================
Window agwStyle Flags             Hex Value   Description
**wx.TR_DEFAULT_STYLE**              *varies* The set of flags that are closest to the defaults for the native control for a particular toolkit.  Should always be used.
``wx.TR_NO_BUTTONS``                      0x0 For convenience to document that no buttons are to be drawn.
``wx.TR_SINGLE``                          0x0 For convenience to document that only one item may be selected at a time. Selecting another item causes the current selection, if any, to be deselected. This is the default.
``wx.TR_HAS_BUTTONS``                     0x1 Use this style to show + and - buttons to the left of parent items.
``wx.TR_NO_LINES``                        0x4 Use this style to hide vertical level connectors.
``wx.TR_LINES_AT_ROOT``                   0x8 Use this style to show lines between root nodes. Only applicable if ``TR_HIDE_ROOT`` is set and ``TR_NO_LINES`` is not set.
``wx.TR_TWIST_BUTTONS``                  0x10 Use old Mac-twist style buttons.
``wx.TR_MULTIPLE``                       0x20 Use this style to allow a range of items to be selected. If a second range is selected, the current range, if any, is deselected.
``wx.TR_HAS_VARIABLE_ROW_HEIGHT``        0x80 Use this style to cause row heights to be just big enough to fit the content. If not set, all rows use the largest row height. The default is that this flag is unset.
``wx.TR_EDIT_LABELS``                   0x200 Use this style if you wish the user to be able to edit labels in the tree control.
``wx.TR_ROW_LINES``                     0x400 Use this style to draw a contrasting border between displayed rows.
``wx.TR_HIDE_ROOT``                     0x800 Use this style to suppress the display of the root node, effectively causing the first-level nodes to appear as a series of root nodes.
``wx.TR_FULL_ROW_HIGHLIGHT``           0x2000 Use this style to have the background colour and the selection highlight extend  over the entire horizontal row of the tree control window.
**Styles from customtreectrl:**
``TR_EXTENDED``                          0x40 Use this style to allow disjoint items to be selected. (Only partially implemented; may not work in all cases).
``TR_AUTO_CHECK_CHILD``                0x4000 Only meaningful for checkbox-type items: when a parent item is checked/unchecked its children are checked/unchecked as well.
``TR_AUTO_TOGGLE_CHILD``               0x8000 Only meaningful for checkbox-type items: when a parent item is checked/unchecked its children are toggled accordingly.
``TR_AUTO_CHECK_PARENT``              0x10000 Only meaningful for checkbox-type items: when a child item is checked/unchecked its parent item is checked/unchecked as well.
``TR_ALIGN_WINDOWS``                  0x20000 Flag used to align windows (in items with windows) at the same horizontal position.
``TR_ALIGN_WINDOWS_RIGHT``            0x40000 Flag used to align windows (in items with windows) to the rightmost edge of :class:`CustomTreeCtrl`.
``TR_ELLIPSIZE_LONG_ITEMS``           0x80000 Flag used to ellipsize long items when the horizontal space for :class:`CustomTreeCtrl` is low.
``TR_TOOLTIP_ON_LONG_ITEMS``         0x100000 Flag used to show tooltips on long items when the horizontal space for :class:`CustomTreeCtrl` is low.

The ``wx.TR_HAS_VARIABLE_LINE_HEIGHT`` style should be set if item rows might
not all be the same height. This can happen if certain rows have a larger font
size, multi-line text, or windows added to them. This style will automatically
adjust each item's height to be just big enough to show its contents.

When the ``wx.TR_HAS_VARIABLE_LINE_HEIGHT`` is not set, adding a new item with
multi-line text or with a window specified will throw an exception. However the
tree won't prevent you from adding multiline text with :meth:`~TreeListMainWindow.SetItemText`
or assigning a window with :meth:`~TreeListMainWindow.SetItemWindow` to an
existing item. It's generally a bad idea to do either of these without this
style as it will result in an ugly tree. By default the ``wx.TR_HAS_VARIABLE_LINE_HEIGHT``
is not set. This means that all item rows will use the same height. This is the
height of the largest item in the tree. If an item with a larger height is
added or revealed, ALL row heights will increase to this larger size. The
larger row height remains persistent even if the large items are hidden or
deleted. You must call :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CalculateLineHeight`
to reset the row height. This somewhat bizarre behavior is why the ``wx.TR_HAS_VARIABLE_LINE_HEIGHT``
style is almost always used.

============================== ==================================================
Event Name                     Description
``EVT_TREE_BEGIN_DRAG``        Begin dragging with the left mouse button.
``EVT_TREE_BEGIN_LABEL_EDIT``  Begin editing a label. This can be prevented by calling :meth:`~TreeEvent.Veto`.
``EVT_TREE_BEGIN_RDRAG``       Begin dragging with the right mouse button.
``EVT_TREE_DELETE_ITEM``       Delete an item.
``EVT_TREE_END_DRAG``          End dragging with the left or right mouse button.
``EVT_TREE_END_LABEL_EDIT``    End editing a label. This can be prevented by calling :meth:`~TreeEvent.Veto`.
``EVT_TREE_GET_INFO``          Request information from the application (not implemented in :class:`CustomTreeCtrl`).
``EVT_TREE_ITEM_ACTIVATED``    The item has been activated, i.e. chosen by double clicking it with mouse or from keyboard.
``EVT_TREE_ITEM_CHECKED``      A checkbox or radiobox type item has been checked.
``EVT_TREE_ITEM_CHECKING``     A checkbox or radiobox type item is being checked.
``EVT_TREE_ITEM_COLLAPSED``    The item has been collapsed.
``EVT_TREE_ITEM_COLLAPSING``   The item is being collapsed. This can be prevented by calling :meth:`~TreeEvent.Veto`.
``EVT_TREE_ITEM_EXPANDED``     The item has been expanded.
``EVT_TREE_ITEM_EXPANDING``    The item is being expanded. This can be prevented by calling :meth:`~TreeEvent.Veto`.
``EVT_TREE_ITEM_GETTOOLTIP``   The opportunity to set the item tooltip is being given to the application (call `TreeEvent.SetToolTip`).
``EVT_TREE_ITEM_HYPERLINK``    An hyperlink type item has been clicked.
``EVT_TREE_ITEM_MENU``         The context menu for the selected item has been requested, either by a right click or by using the menu key.
``EVT_TREE_ITEM_MIDDLE_CLICK`` The user has clicked the item with the middle mouse button (not implemented in :class:`CustomTreeCtrl`).
``EVT_TREE_ITEM_RIGHT_CLICK``  The user has clicked the item with the right mouse button.
``EVT_TREE_KEY_DOWN``          A key has been pressed.
``EVT_TREE_SEL_CHANGED``       Selection has changed.
``EVT_TREE_SEL_CHANGING``      Selection is changing. This can be prevented by calling :meth:`~TreeEvent.Veto`.
``EVT_TREE_SET_INFO``          Information is being supplied to the application (not implemented in :class:`CustomTreeCtrl`).
``EVT_TREE_STATE_IMAGE_CLICK`` The state image has been clicked (not implemented in :class:`CustomTreeCtrl`).

:class:`CustomTreeCtrl` is distributed under the wxPython license.

Latest Revision: Helio Guilherme @ 09 Aug 2018, 21.35 GMT

Version 2.7

# CUSTOMTREECTRL wxPython IMPLEMENTATION
# Inspired By And Heavily Based On wxGenericTreeCtrl.
#
# Andrea Gavana, @ 17 May 2006
# Latest Revision: 02 Jul 2018, 00.10 GMT
# Modified by Helio Guilherme, @ 26 Apr 2018
#
# TODO List
#
# Almost All The Features Of wx.TreeCtrl Are Available, And There Is Practically
# No Limit In What Could Be Added To This Class. The First Things That Comes
# To My Mind Are:
#
# 1. Try To Implement A More Flicker-Free Background Image In Cases Like
#    Centered Or Stretched Image (Now CustomTreeCtrl Supports Only Tiled
#    Background Images).
#
# 2. Try To Mimic Windows wx.TreeCtrl Expanding/Collapsing behaviour: CustomTreeCtrl
#    Suddenly Expands/Collapses The Nodes On Mouse Click While The Native Control
#    Has Some Kind Of "Smooth" Expanding/Collapsing, Like A Wave. I Don't Even
#    Know Where To Start To Do That.
#
# 3. Speed Up General OnPaint Things? I Have No Idea, Here CustomTreeCtrl Is Quite
#    Fast, But We Should See On Slower Machines.
#
#
#
#
#
#

:class:`CommandTreeEvent` is a special subclassing of :class:`CommandEvent`.

:note: Not all the accessors make sense for all the events, see the event description for every method in this class.

:param integer `evtType`: the event type;
:param integer `evtId`: the event identifier;
:param `item`: an instance of :class:`GenericTreeItem`;
:param integer `evtKey`: a character ordinal;
:param `point`: an instance of :class:`wx.Point`;
:param string `label`: a :class:`GenericTreeItem` text label.

__init__(self, evtType, evtId, item=None, evtKey=None, point=None, label=None, \*\*kwargs)

Gets the item on which the operation was performed or the newly selected
item for ``EVT_TREE_SEL_CHANGED`` and ``EVT_TREE_SEL_CHANGING`` events.

:return: An instance of :class:`GenericTreeItem`.

Returns the virtual key code. ASCII events return normal ASCII values, while
non-ASCII events return values such as ``wx.WXK_LEFT`` for the left cursor key.

This method is for ``EVT_TREE_KEY_DOWN`` events only.

:return: An integer representing the virtual key code.

:note: In Unicode build, the returned value is meaningful only if the user entered
 a character that can be represented in current locale's default charset. You can
 obtain the corresponding Unicode character using `GetUnicodeKey`.

Returns the keyboard data (for ``EVT_TREE_KEY_DOWN`` event only).

:return: An instance of :class:`KeyEvent`.

Returns the item text (for ``EVT_TREE_BEGIN_LABEL_EDIT`` and
``EVT_TREE_END_LABEL_EDIT`` events only).

:return: A string containing the item text.

Returns the previously selected item for ``EVT_TREE_SEL_CHANGED`` and
``EVT_TREE_SEL_CHANGING`` events.

Returns the point where the mouse was when the drag operation started
(for ``EVT_TREE_BEGIN_DRAG`` and ``EVT_TREE_BEGIN_RDRAG`` events only)
or the click position.

:return: An instance of :class:`wx.Point`.

Returns the tooltip for the item (for ``EVT_TREE_ITEM_GETTOOLTIP`` events).

:return: A string containing the item tooltip.

Returns the edit cancel flag (for ``EVT_TREE_BEGIN_LABEL_EDIT`` and

:return: ``True`` is the item editing has been cancelled, ``False`` otherwise.

Sets the edit cancel flag (for ``EVT_TREE_BEGIN_LABEL_EDIT`` and

:param bool `editCancelled`: ``True`` to cancel the editing, ``False`` otherwise.

Sets the item on which the operation was performed or the newly selected

:param `item`: an instance of :class:`GenericTreeItem`.

Sets the keyboard data (for ``EVT_TREE_KEY_DOWN`` event only).

:param `event`: a :class:`CommandTreeEvent` event to be processed.

Sets the item text (for ``EVT_TREE_BEGIN_LABEL_EDIT`` and

:param string `label`: a string containing the new item text.

Sets the point where the mouse was when the drag operation started

Sets the tooltip for the item (for ``EVT_TREE_ITEM_GETTOOLTIP`` events).

:param string `tooltip`: a string representing the item tooltip.

:param integer `style`: the underlying :class:`ScrolledWindow` style;
:param integer `agwStyle`: can be a combination of various bits. See
 :mod:`~wx.lib.agw.customtreectrl` for a full list of flags.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=TR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="CustomTreeCtrl")

:note: This method always returns ``True`` as we always accept focus from

:note: Overridden from :class:`ScrolledWindow`.

Adds a root item to the :class:`CustomTreeCtrl`.

:param string `text`: the item text label;
:param integer `ct_type`: the item type (see :meth:`~CustomTreeCtrl.SetItemType` for a list of valid
 item types);
:param `wnd`: if not ``None``, a non-toplevel window to show next to the item,
 any subclass of :class:`wx.Window` except top-level windows;
:param integer `image`: an index within the normal image list specifying the image to
 use for the item in unselected state;
:param  integer `selImage`: an index within the normal image list specifying the image to
 use for the item in selected state; if `image` > -1 and `selImage` is -1, the
 same image is used for both selected and unselected items;
:param object `data`: associate the given Python object `data` with the item.
:param bool `on_the_right`: ``True`` positions the window on the right of text, ``False``
 on the left of text and overlapping the image.

:return: An instance of :class:`GenericTreeItem` upon successful insertion.

 - There already is a root item in the tree;
 - The item window is not ``None`` but the ``TR_HAS_VARIABLE_ROW_HEIGHT`` flag has not been
   set for :class:`CustomTreeCtrl`;
 - The item has multiline text (with line-breaks in it) but the ``TR_HAS_VARIABLE_ROW_HEIGHT``
   flag has not been set for :class:`CustomTreeCtrl`;
 - The `ct_type` attribute is less than ``0`` or greater than ``2``.

   Only one root is allowed to exist in any given instance of :class:`CustomTreeCtrl`.

AddRoot(self, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, on_the_right=True)

Internal method used to adjust the :class:`ScrolledWindow` scrollbars. 

Appends an item as a last child of its parent.

:param `parentId`: an instance of :class:`GenericTreeItem` representing the
 item's parent;
 any subclass of :class:`wx.Window`;
:param integer `selImage`: an index within the normal image list specifying the image to

:see: :meth:`~CustomTreeCtrl.DoInsertItem` for possible exceptions generated by this method.

AppendItem(self, parentId, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, on_the_right=True)

Appends an horizontal line separator as a last child of its parent.

 separator's parent.

Assigns the button image list.

Assigns the normal image list.

Assigns the image list for :class:`CustomTreeCtrl` filled with images to be used on
the leftmost part of the client area. Any item can have a leftmost image associated
with it.

Assigns the state image list.

Transverses the tree and checks/unchecks the items.

:param bool `checked`: ``True`` to check an item, ``False`` to uncheck it.

:note: This method is meaningful only for checkbox-like and radiobutton-like items.

Traverses up the tree and checks/unchecks parent items.

Transverses the tree and toggles the items.

Calculates the level of an item inside the tree hierarchy.

:param integer `level`: the item level in the tree hierarchy;
:param integer `y`: the current vertical position inside the :class:`ScrolledWindow`;
:param integer `align`: an integer specifying the alignment type:

 =============== =========================================
 `align` Value   Description
        0        No horizontal alignment of windows (in items with windows).
        1        Windows (in items with windows) are aligned at the same horizontal position.
        2        Windows (in items with windows) are aligned at the rightmost edge of :class:`CustomTreeCtrl`.

:return: The new `y` vertical position inside the :class:`ScrolledWindow`.

Calculates the base height for all lines in the tree.

Only used if the TR_HAS_VARIABLE_ROW_HEIGHT style is not used.
This base line height gets adjusted to the max line height
of all items as they are displayed. All rows use this largest
height until this method is called to reset it.

Calculates overall position and size of an item.

Programmatically check/uncheck item children.

:note: This method does not generate ``EVT_TREE_ITEM_CHECKING`` and
 ``EVT_TREE_ITEM_CHECKED`` events.

Actually checks/uncheks an item, sending (eventually) the two
events ``EVT_TREE_ITEM_CHECKING`` and ``EVT_TREE_ITEM_CHECKED``.

:param bool `checked`: for a radiobutton-type item, ``True`` to check it, ``False``
 to uncheck it. For a checkbox-type item, it can be one of ``wx.CHK_UNCHECKED``
 when the checkbox is unchecked, ``wx.CHK_CHECKED`` when it is checked and
 ``wx.CHK_UNDETERMINED`` when it's in the undetermined state.

Used internally to avoid ``EVT_TREE_ITEM_CHECKED`` events.

:param bool `checked`: ``True`` to check an item, ``False`` to uncheck it;
:param bool `torefresh`: whether to redraw the item or not.

Uncheck radio items which are on the same level of the checked one.

:note: This method is meaningful only for radiobutton-like items.

We are about to destroy the item children.

Collapse an item, sending a ``EVT_TREE_ITEM_COLLAPSING`` and
``EVT_TREE_ITEM_COLLAPSED`` events.

:raise: `Exception` if you try to collapse a hidden root (i.e., when the ``TR_HIDE_ROOT``
 style is set for :class:`CustomTreeCtrl`).

Collapse the given item and deletes its children.

Deletes an item.

:note: This method sends the ``EVT_TREE_DELETE_ITEM`` event.

Delete all the item's children.

Deletes the window associated to an item (if any).

Actually inserts an item in the tree.

:param integer `previous`: the index at which we should insert the item;
:param `wnd`: if not ``None``, a non-toplevel window to show next to the item, any
 subclass of :class:`wx.Window` except top-level windows;
:param object `data`: associate the given Python object `data` with the item;
:param bool `separator`: ``True`` if the item is a separator, ``False`` otherwise.

 - The `ct_type` attribute is less than ``0`` or greater than ``2``;
 - The parent item is a separator;
 - The item is a separator but it has text or an associated window.

:note: Separator items should not have children, text labels or an associated window.

DoInsertItem(self, parentId, previous, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

Actually selects/unselects an item, sending ``EVT_TREE_SEL_CHANGING`` and
``EVT_TREE_SEL_CHANGED`` events.

:param bool `unselect_others`: if ``True``, all the other selected items are
 unselected.
:param bool `extended_select`: ``True`` if the :class:`CustomTreeCtrl` is using the
 ``TR_EXTENDED`` style;
:param bool `from_key`: ``True`` to indicate that the selection was made via a keyboard
 key, ``False`` if it was a mouse selection.

DoSelectItem(self, item, unselect_others=True, extended_select=False, from_key=False)

Gradient fill from colour 1 to colour 2 from left to right.

:param wx.Rect `rect`: the rectangle to be filled with the gradient shading;
:param bool `hasfocus`: ``True`` if the main :class:`CustomTreeCtrl` has focus, ``False``
 otherwise.

Gradient fill from colour 1 to colour 2 from top to bottom.

Draws the selected item(s) with the Windows Vista style.

Internal function. Starts the editing of an item label, sending a
``EVT_TREE_BEGIN_LABEL_EDIT`` event.

.. warning:: Separator-type items can not be edited.

Starts editing an item label.

Enables/disables the item children.

:param bool `enable`: ``True`` to enable the children, ``False`` to disable them.

:note: This method is used internally.

Enables/disables an item.

:param bool `enable`: ``True`` to enable the item, ``False`` to disable it;

Globally enables/disables drawing of gradient selections.

:param bool `enable`: ``True`` to enable gradient-style selections, ``False``
 to disable it.

:note: Calling this method disables any Vista-style selection previously
 enabled.

Globally enables/disables drawing of Windows Vista selections.

:param bool `enable`: ``True`` to enable Vista-style selections, ``False`` to
 disable it.

:note: Calling this method disables any gradient-style selection previously
 enabled.

Scrolls and/or expands items to ensure that the given item is visible.

Expands an item, sending a ``EVT_TREE_ITEM_EXPANDING`` and
``EVT_TREE_ITEM_EXPANDED`` events.

:raise: `Exception` if you try to expand a hidden root (i.e., when the ``TR_HIDE_ROOT``

Expands all :class:`CustomTreeCtrl` items.

:note: This method suppresses the ``EVT_TREE_ITEM_EXPANDING`` and
 ``EVT_TREE_ITEM_EXPANDED`` events because expanding many items int the
 control would be too slow then.

Expands all the items children of the input item.

Internal function. Used to populate an array of selected items when
the style ``TR_MULTIPLE`` is used.

:param list `array`: a Python list containing the selected items.

:return: A Python list containing the selected items.

Finds the first item starting with the given prefix after the given parent.

:param integer `idParent`: an instance of :class:`GenericTreeItem`;
:param string `prefixOrig`: a string containing the item text prefix.

:return: An instance of :class:`GenericTreeItem` or ``None`` if no item has been found.

Freeze :class:`CustomTreeCtrl`.

Freezes the window or, in other words, prevents any updates from taking place
on screen, the window is not redrawn at all. :meth:`~Thaw` must be called to re-enable
window redrawing. Calls to these two functions may be nested.

:note: This method is useful for visual appearance optimization (for example,
 it is a good idea to use it before doing many large text insertions in a row
 into a :class:`TextCtrl` under wxGTK) but is not implemented on all platforms nor
 for all controls so it is mostly just a hint to wxWidgets and not a mandatory
 directive.

Returns the :class:`CustomTreeCtrl` style.

:see: The :meth:`~CustomTreeCtrl.__init__` method for a list of possible style flags.

Returns the :class:`CustomTreeCtrl` background image (if any).

:return: An instance of :class:`wx.Bitmap` if a background image is present, ``None`` otherwise.

:note: At present, the background image can only be used in "tile" mode.

.. todo:: Support background images also in stretch and centered modes.

Returns the pen used to draw the selected item border.

:return: An instance of :class:`wx.Pen`.

:note: The border pen is not used if the Windows Vista selection style is applied.

Retrieves the rectangle bounding the item.

:param bool `textOnly`: if ``True``, only the rectangle around the item's label will
 be returned, otherwise the item's image is also taken into account.

:note: The rectangle coordinates are logical, not physical ones. So, for example,
 the `x` coordinate may be negative if the tree has a horizontal scrollbar and its
 position is not ``0``.

.. warning:: The ``textOnly`` flag is currently ignored and this method
 always returns the rectangle including the item's image, checkbox,
 and window (if they exist) along with the item's text. A separator's
 bounding box stretches the width of the entire client area. The height
 may be 0 for newly added items until :meth:`CustomTreeCtrl.CalculateSize`
 is called while the tree is not frozen.

Returns the buttons image list associated with :class:`CustomTreeCtrl` (from
which application-defined button images are taken).

:return: An instance of :class:`wx.ImageList`.

Returns the item children count.

:param bool `recursively`: if ``True``, returns the total number of descendants,
 otherwise only one level of children is counted.

Returns the pen used to draw the connecting lines between items.

Returns a native looking checkbox or radio button bitmap.

:param bool `checkbox`: ``True`` to get a checkbox image, ``False`` for a radiobutton one;
:param bool `checked`: ``True`` if the control is marked, ``False`` if it is not;
:param bool `enabled`: ``True`` if the control is enabled, ``False`` if it is not;
:param integer `x`: the width of the bitmap;
:param integer `y`: the height of the bitmap.

:return: An instance of :class:`wx.Bitmap`, representing a native looking checkbox or radiobutton.

GetControlBmp(self, checkbox=True, checked=False, enabled=True, x=16, y=16)

Returns the colour for items in a disabled state.

Returns whether built-in drag/drop will be full screen or not.

:return: ``True`` if the drag/drop operation will be full screen, or
 ``False`` if only within the tree.

Returns a reference to the edit :class:`TreeTextCtrl` if the item is being edited or
``None`` otherwise (it is assumed that no more than one item may be edited
simultaneously).

Returns the item's first child and an integer value 'cookie'.
Call :meth:`~CustomTreeCtrl.GetNextChild` for the next child using this very 'cookie' return
value as an input.

:return: A tuple with the first value being an instance of :class:`GenericTreeItem` or ``None`` if there are no
 further children, and as second value an integer parameter 'cookie'.

:note: This method returns ``None`` if there are no further children.

Returns the first gradient colour for gradient-style selections.

Returns the first visible item.

:return: An instance of :class:`GenericTreeItem` or ``None`` if there are no
 visible items.

Returns the gradient style for gradient-style selections.

:return: ``0`` for horizontal gradient-style selections, ``1`` for vertical
 gradient-style selections.

Returns the colour used to highlight focused selected items.

:note: This is used only if gradient and Windows Vista selection
 styles are disabled.

Returns the colour used to highlight unfocused selected items.

Returns the font used to render hypertext items.

:note: This method is meaningful only for hypertext-like items.

Returns the colour used to render a non-visited hypertext item.

Returns the colour used to render a visited hypertext item.

Returns the normal image list associated with :class:`CustomTreeCtrl`.

Returns the image list used to build the check/radio buttons in :class:`CustomTreeCtrl`.

Gets the state of a 3-state checkbox item.

:return: ``wx.CHK_UNCHECKED`` when the checkbox is unchecked, ``wx.CHK_CHECKED``
 when it is checked and ``wx.CHK_UNDETERMINED`` when it's in the undetermined
 state.

:note: This method raises an exception when the function is used with a 2-state
 checkbox item.

:note: This method is meaningful only for checkbox-like items.

Returns the item background colour.

Returns the item font.

Returns the item image.

:param integer `which`: can be one of the following bits:

 ================================= ========================
 Item State                        Description
 ``TreeItemIcon_Normal``           To get the normal item image
 ``TreeItemIcon_Selected``         To get the selected item image (i.e. the image which is shown when the item is currently selected)
 ``TreeItemIcon_Expanded``         To get the expanded image (this only makes sense for items which have children - then this image is shown when the item is expanded and the normal image is shown when it is collapsed)
 ``TreeItemIcon_SelectedExpanded`` To get the selected expanded image (which is shown when an expanded item is currently selected)

:return: An integer index that can be used to retrieve the item image inside
 a :class:`wx.ImageList`.

Returns the item leftmost image, i.e. the image associated to the item on the leftmost
part of the :class:`CustomTreeCtrl` client area.

:return: An integer index that can be used to retrieve the item leftmost image inside

Returns the item parent (can be ``None`` for root items).

:return: An instance of :class:`GenericTreeItem` or ``None`` for root items.

Returns the horizontal space available in :class:`CustomTreeCtrl`, in pixels, to draw this item.

.. versionadded:: 0.9.3

Returns the item text.

Returns the item text colour or separator horizontal line colour.

Returns the item type.

:return: An integer representing the item type.

:see: :meth:`~CustomTreeCtrl.SetItemType` for a description of valid item types.

Returns whether an hypertext item was visited.

:return: ``True`` if the hypertext item has been visited, ``False`` otherwise.

Returns the window associated to the item (if any).

:return: An instance of :class:`wx.Window` if the item has an associated window, ``None`` otherwise.

Returns whether the window associated to the item is enabled.

:return: ``True`` if the item has an associated window and this window is
 enabled, ``False`` in all other cases.

Returns the item last child.

 further children.

Returns the image list for :class:`CustomTreeCtrl` filled with images to be used on
with it.

Returns the line height for the given item.

:return: the item height, in pixels.

Returns the maximum width of the :class:`CustomTreeCtrl`.

:param bool `respect_expansion_state`: if ``True``, only the expanded items (and their
 children) will be measured. Otherwise all the items are expanded and
 their width measured.

:return: the maximum width of :class:`CustomTreeCtrl`, in pixels.

Returns the next item. Only for internal use right now.

 further items.

Returns the next active item. Used Internally at present.

:param bool `down`: ``True`` to search downwards in the hierarchy for an active item,
 ``False`` to search upwards.

:return: An instance of :class:`GenericTreeItem` if an active item has been found or
 ``None`` if none has been found.

Returns the item's next child.

:param `cookie`: a parameter which is opaque for the application but is necessary
 for the library to make these functions reentrant (i.e. allow more than one
 enumeration on one and the same object simultaneously).

Returns the next expanded item after the input one.

:param `item`: an instance of :class:`TreeListItem`.

Returns the next displayed item in the tree. This is either the first
child of the item (if it is expanded and has children) or its next
sibling. If there is no next sibling the tree is walked backwards
until a next sibling for one of its parents is found.

:return: An instance of :class:`GenericTreeItem` or ``None`` if no item follows this one.

Returns the next sibling of an item.

 further siblings.

:note: This method returns ``None`` if there are no further siblings.

Returns the next visible item.

 next visible items.

Returns the previous item. Only for internal use right now.

:return: An instance of :class:`GenericTreeItem`

Returns the previous expanded item before the input one.

Returns the previous displayed item in the tree. This is either the
last displayed child of its previous sibling, or its parent item.

:return: An instance of :class:`GenericTreeItem` or ``None`` if no previous item found (root).

Returns the previous sibling of an item.

Returns the previous visible item.

 previous visible items.

Returns the data associated to an item.

:return: A Python object representing the item data, or ``None`` if no data
 has been assigned to this item.

Returns the root item, an instance of :class:`GenericTreeItem`. 

Returns the second gradient colour for gradient-style selections.

Returns the current selected item (i.e. focused item).

:note: Similar to GetFocusedItem of wx.TreeCtrl. Use
 :meth:`~CustomTreeCtrl.GetSelections` for obtaining all items
 selected in multiple-selection trees (i.e. TR_MULTIPLE flag set).

Returns a list of selected items.

:note: This method can be used only if :class:`CustomTreeCtrl` has the ``TR_MULTIPLE`` or ``TR_EXTENDED``
 style set.

:return: A Python list containing the selected items, all instances of :class:`GenericTreeItem`.

Returns the pen colour for separator-type items.

:return: An instance of :class:`wx.Colour` representing the separator pen colour.

Returns the state image list associated with :class:`CustomTreeCtrl` (from which
application-defined state images are taken).

Handles the hyperlink items, sending the ``EVT_TREE_ITEM_HYPERLINK`` event.

Returns ``True`` if :class:`CustomTreeCtrl` has the `flag` bit set.

:param integer `flag`: any possible window style for :class:`CustomTreeCtrl`.

:see: The :meth:`~CustomTreeCtrl.__init__` method for the `flag` parameter description.

Returns whether :class:`CustomTreeCtrl` has the ``TR_HAS_BUTTONS`` flag set.

:return: ``True`` if :class:`CustomTreeCtrl` has the ``TR_HAS_BUTTONS`` flag set,

Returns whether an item has children or not.

Hides/shows an item.

:param `hide`: ``True`` to hide the item, ``False`` to show it.

:note: A hidden item always reports that it is collapsed and disabled.

Calculates which (if any) item is under the given point, returning the tree item
at this point plus extra information flags.

:param `point`: an instance of :class:`wx.Point`, a point to test for hits;
:param integer `flags`: a bitlist of the following values:

 ================================== =============== =================================
 HitTest Flags                      Hex Value       Description
 ``TREE_HITTEST_ABOVE``                         0x1 Above the client area
 ``TREE_HITTEST_BELOW``                         0x2 Below the client area
 ``TREE_HITTEST_NOWHERE``                       0x4 No item has been hit
 ``TREE_HITTEST_ONITEMBUTTON``                  0x8 On the button associated to an item
 ``TREE_HITTEST_ONITEMICON``                   0x10 On the icon associated to an item
 ``TREE_HITTEST_ONITEMINDENT``                 0x20 On the indent associated to an item
 ``TREE_HITTEST_ONITEMLABEL``                  0x40 On the label (string) associated to an item
 ``TREE_HITTEST_ONITEM``                       0x50 Anywhere on the item
 ``TREE_HITTEST_ONITEMRIGHT``                  0x80 On the right of the label associated to an item
 ``TREE_HITTEST_TOLEFT``                      0x200 On the left of the client area
 ``TREE_HITTEST_TORIGHT``                     0x400 On the right of the client area
 ``TREE_HITTEST_ONITEMUPPERPART``             0x800 On the upper part (first half) of the item
 ``TREE_HITTEST_ONITEMLOWERPART``            0x1000 On the lower part (second half) of the item
 ``TREE_HITTEST_ONITEMCHECKICON``            0x2000 On the check/radio icon, if present

:return: A tuple with the first value being an instance of :class:`GenericTreeItem` or ``None`` if
 no item has been hit-tested, and as second value an integer parameter `flag`.

:note: both the item (if any, ``None`` otherwise) and the `flags` are always returned as a tuple.

Inserts an item after the given previous.

:see: :meth:`~CustomTreeCtrl.InsertItemByIndex` and :meth:`~CustomTreeCtrl.InsertItemByItem` for an explanation of
 the input parameters.

InsertItem(self, parentId, input, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

:param `idPrevious`: the index at which we should insert the new item;

InsertItemByIndex(self, parentId, idPrevious, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

:param `idPrevious`: an instance of :class:`GenericTreeItem` representing the
 previous item;

:raise: `Exception` if the previous item is not a sibling.

:see: :meth:`~CustomTreeCtrl.DoInsertItem` for other possible exceptions generated by this method.

InsertItemByItem(self, parentId, idPrevious, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

Inserts a separator item after the given previous.

Returns whether the item font is bold or not.

:return: ``True`` if the item has bold text, ``False`` otherwise.

Checks if the given item is under another one in the tree hierarchy.

:param `parent`: an instance of :class:`GenericTreeItem`, representing the possible
 parent of `item`;
:param `item`: another instance of :class:`GenericTreeItem`.

:return: ``True`` if `item` is a descendant of `parent`, ``False`` otherwise.

Returns whether the item is expanded or not.

:return: ``True`` if the item is expanded, ``False`` if it is collapsed.

Returns whether the item font is italic or not.

:return: ``True`` if the item has italic text, ``False`` otherwise.

Returns whether or not the checkbox item is a 3-state checkbox.

:return: ``True`` if this checkbox is a 3-state checkbox, ``False`` if it's a
 2-state checkbox item.

Returns whether an item is checked or not.

:return: ``True`` if the item is in a 'checked' state, ``False`` otherwise.

Returns whether an item is enabled or disabled.

Returns whether an item is hypertext or not.

:return: ``True`` if the item is hypertext-like, ``False`` otherwise.

Returns whether an item is of separator type or not.

Returns whether the item is selected or not.

:return: ``True`` if the item is selected, ``False`` otherwise.

Returns whether the item is visible or not (i.e., its hierarchy is expanded
enough to show the item, and it has not been hidden).

:return: ``True`` if the item is visible, ``False`` if it is hidden.

Returns whether the item has children or not.

:return: ``True`` if the item has children, ``False`` otherwise.

Called by :class:`TreeTextCtrl`, to accept the changes and to send the
``EVT_TREE_END_LABEL_EDIT`` event.

:param string `value`: the new value of the item label.

:return: ``True`` if the editing has not been vetoed, ``False`` otherwise.

Called by :class:`TreeTextCtrl`, to cancel the changes and to send the

Returns whether 2 items have the same text.

Override this function in the derived class to change the sort order of the items
in the :class:`CustomTreeCtrl`. The function should return a negative, zero or positive
value if the first item is less than, equal to or greater than the second one.

:param `item1`: an instance of :class:`GenericTreeItem`;
:param `item2`: another instance of :class:`GenericTreeItem`.

:return: The return value is negative if `item1` < `item2`, zero if `item1` == `item2`
 and strictly positive if `item1` < `item2`.

:note: The base class version compares items alphabetically.

Handles the ``wx.EVT_WINDOW_DESTROY`` event for :class:`CustomTreeCtrl`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`CustomTreeCtrl`.

Process the tooltip event, to speed up event processing. Does not actually
get a tooltip.

This method is normally only used internally, but sometimes an application
may need it to implement functionality that should not be disabled by an
application defining an `OnIdle` handler in a derived class.

This method may be used to do delayed painting, for example, and most
implementations call :meth:`wx.Window.UpdateWindowUI` in order to send update events
to the window in idle time.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`CustomTreeCtrl`, sending a
``EVT_TREE_KEY_DOWN`` event.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`CustomTreeCtrl`.

Handles a bunch of ``wx.EVT_MOUSE_EVENTS`` events for :class:`CustomTreeCtrl`.

Handles the ``wx.EVT_PAINT`` event for :class:`CustomTreeCtrl`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`CustomTreeCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`CustomTreeCtrl`.

Actually draws an item.

Paint a level in the hierarchy of :class:`CustomTreeCtrl`.

:param integer `y`: the current vertical position in the :class:`ScrolledWindow`;

Prepends an item as a first child of parent.

:param `parent`: an instance of :class:`GenericTreeItem` representing the

PrependItem(self, parent, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

Prepends a separator item as a first child of parent.

 item's parent.

Recurses over all the children of the spcified items, calculating their
maximum width.

:param integer `maxwidth`: the current maximum width for :class:`CustomTreeCtrl`, in pixels;

:return: A tuple containing the maximum width and item height, in pixels.

RecurseOnChildren(self, item, maxwidth, respect_expansion_state)

Refreshes the items with which a window is associated.

:param `item`: an instance of :class:`GenericTreeItem`. If `item` is ``None``, then the
 recursive refresh starts from the root node.

:note: This method is called only if the style ``TR_ALIGN_WINDOWS_RIGHT`` is used.

Refreshes a damaged item line.

Refreshes the selected items under the given item.

Refreshes a damaged subtree of an item.

Called by :class:`TreeTextCtrl` when it marks itself for deletion. 

Scrolls the specified item into view.

Selects all the item in the tree.

:raise: `Exception` if used without the ``TR_EXTENDED`` or ``TR_MULTIPLE`` style set.

 style set.

Selects all the children of the given item.

 style set.

Selects/deselects an item.

:param bool `select`: ``True`` to select an item, ``False`` to deselect it.

:note: If TR_MULTIPLE is set, this actually toggles selection when select=True.

Selects all the items between `item1` and `item2`.

:param `item1`: an instance of :class:`GenericTreeItem`, representing the first
 item in the range to select;
:param `item2`: an instance of :class:`GenericTreeItem`, representing the last
 item in the range to select.

 style set.

Actually sends the ``EVT_TREE_DELETE_ITEM`` event.

Sets the :class:`CustomTreeCtrl` window style.

:param integer `agwStyle`: the new :class:`CustomTreeCtrl` window style.

:see: The :meth:`~CustomTreeCtrl.__init__` method for the `agwStyle` parameter description.

Changes the background colour of :class:`CustomTreeCtrl`.

:param `colour`: the colour to be used as the background colour, pass
 :class:`NullColour` to reset to the default colour.

:return: ``False`` if the underlying :class:`ScrolledWindow` does not accept
 the new colour, ``True`` otherwise.

:note: The background colour is usually painted by the default :class:`EraseEvent`
 event handler function under Windows and automatically under GTK.

:note: Setting the background colour does not cause an immediate refresh, so
 you may wish to call :meth:`wx.Window.ClearBackground` or :meth:`wx.Window.Refresh` after
 calling this function.

Sets the :class:`CustomTreeCtrl` background image.

:param `image`: if not ``None``, an instance of :class:`wx.Bitmap`.

Sets the pen used to draw the selected item border.

:param `pen`: an instance of :class:`wx.Pen`.

Sets the buttons image list for :class:`CustomTreeCtrl` (from which application-defined
button images are taken).

Sets the pen used to draw the connecting lines between items.

Sets the colour for items in a disabled state.

Sets whether a drag operation will be performed full screen or not.

A full screen drag allows the user to drag outside of the tree to
other controls. When the drag is finished the destination will have
to be found manually in the ``EVT_TREE_END_DRAG`` handler with
something like:

example::

    wnd = wx.FindWindowAtPoint(self.ClientToScreen(event.GetPoint()))

:param bool `fullScreen`: False (default) to drag within tree only.

Sets the first gradient colour for gradient-style selections.

:param `colour`: if not ``None``, a valid :class:`wx.Colour` instance. Otherwise,
 the colour is taken from the system value ``wx.SYS_COLOUR_HIGHLIGHT``.

Sets the :class:`CustomTreeCtrl` font.

Changes the foreground colour of :class:`CustomTreeCtrl`.

:param `colour`: the colour to be used as the foreground colour, pass

Sets the gradient style for gradient-style selections.

:param integer `vertical`: ``0`` for horizontal gradient-style selections, ``1`` for vertical

Sets the colour used to highlight focused selected items.

:note: This is applied only if gradient and Windows Vista selection

Sets the colour used to highlight unfocused selected items.

Sets the font used to render hypertext items.

Sets the colour used to render a non-visited hypertext item.

Sets the colour used to render a visited hypertext item.

Sets the normal image list for :class:`CustomTreeCtrl`.

Sets the checkbox/radiobutton image list.

:param integer `sizex`: the width of the bitmaps in the `imglist`, in pixels;
:param integer `sizey`: the height of the bitmaps in the `imglist`, in pixels;
:param `imglist`: an instance of :class:`wx.ImageList`.

Sets the indentation for :class:`CustomTreeCtrl`.

:param integer `indent`: an integer representing the indentation for the items in the tree.

Sets whether the item has a 3-state value checkbox assigned to it or not.

:param bool `allow`: ``True`` to set an item as a 3-state checkbox, ``False`` to set it
 to a 2-state checkbox.

:return: ``True`` if the change was successful, ``False`` otherwise.

Sets the checkbox item to the given `state`.

:param integer `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
 (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).

:note: This method raises an exception when the checkbox item is a 2-state checkbox
 and setting the state to ``wx.CHK_UNDETERMINED``.

Sets the item background colour.

Sets the item font as bold/unbold.

:param bool `bold`: ``True`` to set the item font as bold, ``False`` otherwise.

Gives the item the visual feedback for drag and drop operations.
This is useful when something is dragged from outside the :class:`CustomTreeCtrl`.

:param bool `highlight`: ``True`` to highlight the dragged items, ``False`` otherwise.

Sets the item font.

Forces the appearance/disappearance of the button next to the item.

:param bool `has`: ``True`` to have a button next to an item, ``False`` otherwise.

Sets whether the item is hypertext or not.

:param bool `hyper`: ``True`` to have an item with hypertext behaviour, ``False`` otherwise.

Sets the item image, depending on the item state.

 use for the item in the state specified by the `which` parameter;
:param integer `which`: the item state.

:see: :meth:`~CustomTreeCtrl.GetItemImage` for an explanation of the `which` parameter.

Sets the item font as italic/non-italic.

:param bool `italic`: ``True`` to set the item font as italic, ``False`` otherwise.

Sets the item leftmost image, i.e. the image associated to the item on the leftmost

:param integer `image`: an index within the left image list specifying the image to
 use for the item in the leftmost part of the client area.

Sets the item text.

:param string `text`: the new item label.

:raise: `Exception` if the input `item` is a separator.

Sets the item text colour or separator horizontal line colour.

Sets the item type.

:param integer `ct_type`: may be one of the following integers:

 `ct_type` Value Description
        0        A normal item
        1        A checkbox-like item
        2        A radiobutton-type item

:note: Regarding radiobutton-type items (with `ct_type` = 2), the following
 approach is used:

 - All peer-nodes that are radiobuttons will be mutually exclusive. In other words,
   only one of a set of radiobuttons that share a common parent can be checked at
   once. If a radiobutton node becomes checked, then all of its peer radiobuttons
   must be unchecked.
 - If a radiobutton node becomes unchecked, then all of its child nodes will become
   inactive.

Sets whether an hypertext item was visited.

:param bool `visited`: ``True`` to mark an hypertext item as visited, ``False`` otherwise.

Sets the window for the given item.

:param `wnd`: if not ``None``, a non-toplevel window to be displayed next to
 the item.
 on the left of text and overlapping the image. New in wxPython 4.0.4.

:raise: `Exception` if the input `item` is a separator and `wnd` is not ``None``.

Enables/disables the window associated to the item.

:param bool `enable`: ``True`` to enable the associated window, ``False`` to

Sets the image list for :class:`CustomTreeCtrl` filled with images to be used on
with it.

Sets the data associated to an item.

:param object `data`: can be any Python object.

Sets the second gradient colour for gradient-style selections.

 the colour generated is a slightly darker version of the :class:`CustomTreeCtrl`
 background colour.

Sets the pen colour for separator-type items.

:param `colour`: a valid instance of :class:`wx.Colour`.

Sets the spacing between items in :class:`CustomTreeCtrl`.

:param integer `spacing`: an integer representing the spacing between items in the tree.

Sets the state image list for :class:`CustomTreeCtrl` (from which application-defined
state images are taken).

Return ``True`` from here to allow the colours of this window to be
changed by `InheritAttributes`, returning ``False`` forbids inheriting them
from the parent window.

The base class version returns ``False``, but this method is overridden in
:class:`wx.Control` where it returns ``True``.

:class:`CustomTreeCtrl` does not inherit colours from anyone.

Sorts the children of the given item using the :meth:`~CustomTreeCtrl.OnCompareItems` method of
:class:`CustomTreeCtrl`.

:note: You should override the :meth:`~CustomTreeCtrl.OnCompareItems` method in your derived class to change
 the sort order (the default is ascending case-sensitive alphabetical order).

Thaw :class:`CustomTreeCtrl`.

Reenables window updating after a previous call to :meth:`~Freeze`. To really thaw the
control, it must be called exactly the same number of times as :meth:`~Freeze`.

:raise: `Exception` if :meth:`~Thaw` has been called without an un-matching :meth:`~Freeze`.

Tiles the background image to fill all the available area.

Toggles the item state (collapsed/expanded).

Toggles the item selection.

Used internally to handle radio node parent correctly.

Unselects all the children of the given item.

This class handles the creation of a custom image in case of item drag
and drop.

:param `treeCtrl`: the parent :class:`CustomTreeCtrl`;
:param `item`: one of the tree control item (an instance of :class:`GenericTreeItem`).

Actually creates the drag and drop bitmap for :class:`DragImage`.

:return: An instance of :class:`DragImage`, a close representation of the item's
 appearance (i.e., a screenshot of the item).

This class holds all the information and methods for every single item in
:class:`CustomTreeCtrl`. This is a generic implementation of :class:`TreeItem`.

:param `parent`: the tree item parent, an instance of :class:`GenericTreeItem` (may
 be ``None`` for root items);
:param string `text`: the tree item text;
:param integer `ct_type`: the tree item kind. May be one of the following integers:

 the item, an instance of :class:`wx.Window`;

   inactive.

:note: Separator items should not have children, labels, data or an associated window.
 Other issues/features associated to separator items:

 - You can change the color of individual separators by using :meth:`CustomTreeCtrl.SetItemTextColour() <customtreectrl.CustomTreeCtrl.SetItemTextColour>`,
   or you can use :meth:`CustomTreeCtrl.SetSeparatorColour() <customtreectrl.CustomTreeCtrl.SetSeparatorColour>` to change the color of all
   separators. The default separator colour is that returned by `SystemSettings.GetColour(wx.SYS_COLOUR_GRAYTEXT)`;
 - Separators can be selected just like any other tree item;
 - Separators cannot have text;
 - Separators cannot have children;
 - Separators cannot be edited via the ``EVT_TREE_BEGIN_LABEL_EDIT`` event.

__init__(self, parent, text="", ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

Assigns the item attributes (font, colours, etc...) for this item.

:param `attr`: an instance of :class:`TreeItemAttr`.

Creates a new attribute (font, colours, etc...) for this item.

:return: An instance of :class:`TreeItemAttr`.

Checks/unchecks an item. Internal use only.

:note: This is meaningful only for checkbox-like and radiobutton-like items.

:note: Always use :meth:`CustomTreeCtrl.CheckItem` instead to update the tree properly and send events.

Collapses the item. Internal use only.

:note: Always use :meth:`CustomTreeCtrl.Collapse` instead to update the tree properly and send events.

Deletes the item children. Internal use only.

:param `tree`: the main :class:`CustomTreeCtrl` instance.

:note: Always use :meth:`CustomTreeCtrl.DeleteChildren` instead to update the tree properly.

Deletes the window associated to the item (if any). Internal use only.

:note: Always use :meth:`CustomTreeCtrl.DeleteItemWindow` instead to update the tree properly.

Enables/disables the item.

:param bool `enable`: ``True`` to enable the item, ``False`` to disable it.

:note: Call :meth:`CustomTreeCtrl.EnableItem` instead to update the tree properly.

Expands the item. Internal use only.

:note: Always use :meth:`CustomTreeCtrl.Expand` instead to update the tree properly and send events.

 state.

:raise: `Exception` when the item is not a 3-state checkbox item.

Returns the item attributes (font, colours, etc...).

Returns the item check image.

 ``TreeItemIcon_Checked``          To get the checkbox checked item image
 ``TreeItemIcon_NotChecked``       To get the checkbox unchecked item image
 ``TreeItemIcon_Undetermined``     To get the checkbox undetermined state item image
 ``TreeItemIcon_Flagged``          To get the radiobutton checked image
 ``TreeItemIcon_NotFlagged``       To get the radiobutton unchecked image

:return: An integer index that can be used to retrieve the item check image inside

:note: This method is meaningful only for radio & check items.

Returns the item's children.

:return: A Python list containing instances of :class:`GenericTreeItem`, representing
 this item's children.
 
:note: The returned value is a reference to the list of children
 used internally by the tree. It is advised not to change this list
 and to make a copy before calling other tree methods as they could
 change the contents of the list.

Gets the number of children of this item.

Returns the current item check image.

Returns the current item image.

Returns the data associated to this item.

Returns the height of the item, in pixels.

This will be 0 when the item is first created and always 0 for hidden
items. It is updated when the item is calculated.

Returns the item image for a particular item state.

Returns the leftmost image associated to this item, i.e. the image on the
leftmost part of the client area of :class:`CustomTreeCtrl`.

Gets the item parent (another instance of :class:`GenericTreeItem` or ``None`` for
root items.

Returns the item size.

:param integer `x`: the current item's x position;
:param integer `y`: the current item's y position;
:param `theButton`: an instance of the main :class:`CustomTreeCtrl`.

:return: A tuple of (`x`, `y`) dimensions, in pixels, representing the
 item's width and height.

:see: :meth:`~GenericTreeItem.SetType` and :meth:`~GenericTreeItem.__init__` for a description of valid item types.

Returns whether the item is checked or not.

Returns the width of the item's contents, in pixels.

This is the width of the item's text plus the widths of the item's
image, checkbox, and window (if they exist).
A separator's width is the width of the entire client area.

:return: An instance of any :class:`wx.Window` derived class, excluding top-level windows.

Returns whether the associated window is enabled or not.

:return: ``True`` if the associated window is enabled, ``False`` if it is disabled.

:raise: `Exception` when the item has no associated window.

Returns whether the item has the plus button or not.

:return: ``True`` if the item has a 'plus' mark, ``False`` otherwise.

Hides/shows the item. Internal use only.

:note: Always use :meth:`CustomTreeCtrl.HideItem` instead to update the tree properly.

:meth:`~GenericTreeItem.HitTest` method for an item. Called from the main window :meth:`CustomTreeCtrl.HitTest() <customtreectrl.CustomTreeCtrl.HitTest>`.

:param `point`: the point to test for the hit (an instance of :class:`wx.Point`);
:param `theCtrl`: the main :class:`CustomTreeCtrl` tree;
:param integer `flags`: a bitlist of hit locations;
:param integer `level`: the item's level inside the tree hierarchy.

:see: :meth:`CustomTreeCtrl.HitTest() <customtreectrl.CustomTreeCtrl.HitTest>` method for the flags explanation.

:return: A 2-tuple of (item, flags). The item may be ``None``.        

Inserts an item in the item children list for this item.

:param `child`: an instance of :class:`GenericTreeItem`;
:param integer `index`: the index at which we should insert the new child.

This is just a maybe more readable synonym for :meth:`~GenericTreeItem.GetValue`.

Returns whether the item is enabled or not. Hidden items always return False.

:return: ``True`` if the item is enabled, ``False`` if it is disabled.

Returns whether the item is expanded or not. Hidden items always return False.

Returns whether the item is ok or not.

:note: This method always returns ``True``, it has been added for
 backward compatibility with the wxWidgets C++ implementation.

Returns whether the item is meant to be an horizontal line separator or not.

:return: ``True`` if this item is a separator, ``False`` otherwise.

Handles the ``wx.EVT_SET_FOCUS`` event for the window associated with the item.

Handles the ``wx.EVT_TREE_ITEM_COLLAPSING`` event for the window associated with the item.

:param `event`: a :class:`GenericTreeItem` to be processed.

Sets the item attributes (font, colours, etc...).

Sets the item font bold.

:parameter bool `bold`: ``True`` to have a bold font item, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SetItemBold` instead to refresh the tree properly.

Sets the data associated to this item.

Sets whether an item has the 'plus' button.

:param bool `has`: ``True`` to set the 'plus' button on the item, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SetItemHasChildren` instead to refresh the tree properly.

Sets the item's height. Used internally.

:param integer `h`: an integer specifying the item's height, in pixels.

Sets the item focus/unfocus.

:param bool `set`: ``True`` to set the focus to the item, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SelectItem` instead to update the tree properly and send events.

:param bool `hyper`: ``True`` to set hypertext behaviour, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SetItemHyperText` instead to refresh the tree properly.

Sets the item image.

:param integer `image`: an index within the normal image list specifying the image to use;
:param integer `which`: the image kind.

:see: :meth:`~GenericTreeItem.GetImage` for a description of the `which` parameter.

:note: Call :meth:`CustomTreeCtrl.SetItemImage` instead to refresh the tree properly.

Sets the item font italic.

:parameter bool `italic`: ``True`` to have an italic font item, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SetItemItalic` instead to refresh the tree properly.

:note: Call :meth:`CustomTreeCtrl.SetItemLeftImage` instead to refresh the tree properly.

:raise: `Exception` if the item is a separator.

:note: Call :meth:`CustomTreeCtrl.SetItemText` to refresh the tree properly.

   inactive.
   
:note: Call :meth:`CustomTreeCtrl.SetItemType` instead to refresh the tree properly.

Sets whether an hypertext item was visited or not.

:param bool `visited`: ``True`` to set a hypertext item as visited, ``False`` otherwise.

:note: Call :meth:`CustomTreeCtrl.SetItemVisited` instead to refresh the tree properly.

Sets the item's width. Used internally.

:param integer `w`: an integer specifying the item's width, in pixels.

Sets the window associated to the item. Internal use only.

:param `wnd`: a non-toplevel window to be displayed next to the item, any
 subclass of :class:`wx.Window`.

:note: Always use :meth:`CustomTreeCtrl.SetItemWindow` instead to update the tree properly.

Sets whether the associated window is enabled or not.

:param bool `enable`: ``True`` to enable the associated window, ``False`` to disable it.

Sets the `x` position on an item, in logical coordinates.

:param integer `x`: an integer specifying the x position of the item.

Sets the `y` position on an item, in logical coordinates.

:param integer `y`: an integer specifying the y position of the item.

:param `owner`: the :class:`Timer` owner (an instance of :class:`CustomTreeCtrl`).

:class:`CommandTreeEvent` is a special class for all events associated with tree controls.

:note: Not all accessors make sense for all events, see the event descriptions below.

This is the opposite of :meth:`~TreeEvent.Veto`: it explicitly allows the event to be processed.

Returns the actual :class:`NotifyEvent`.

:return: An instance of :class:`NotifyEvent`.

Returns ``True`` if the change is allowed (:meth:`~TreeEvent.Veto` hasn't been called) or

Timer used to clear the :class:`CustomTreeCtrl` `_findPrefix` attribute if no
key was pressed for a sufficiently long time.

The timer has expired, clear the `_findPrefix` attribute in :class:`CustomTreeCtrl`. 

Creates the item attributes (text colour, background colour and font).

:note: This class is inspired by the wxWidgets generic implementation of :class:`TreeItemAttr`.

:param `colText`: the text colour, an instance of :class:`wx.Colour`;
:param `colBack`: the tree item background colour, an instance of :class:`wx.Colour`;
:param `colBorder`: the tree item border colour, an instance of :class:`wx.Colour`;
:param `font`: the tree item font, an instance of :class:`wx.Font`.

__init__(self, colText=wx.NullColour, colBack=wx.NullColour, colBorder=wx.NullColour,font=wx.NullFont)

Returns the attribute background colour.

Returns the attribute border colour.

.. versionadded:: 0.9.6

Returns the attribute font.

Returns the attribute text colour.

Returns whether the attribute has background colour.

:return: ``True`` if the background colour attribute has been set, ``False`` otherwise.

Returns whether the attribute has border colour.

:return: ``True`` if the border colour attribute has been set, ``False`` otherwise.

Returns whether the attribute has font.

:return: ``True`` if the font attribute has been set, ``False`` otherwise.

Returns whether the attribute has text colour.

:return: ``True`` if the text colour attribute has been set, ``False`` otherwise.

Sets the item background colour attribute.

:param `colBack`: an instance of :class:`wx.Colour`.

Sets the item border colour attribute.

Sets the item font attribute.

Sets the text colour attribute.

:param `colText`: an instance of :class:`wx.Colour`.

Control used for in-place edit.

This is a subclass of :class:`lib.expando.ExpandoTextCtrl` as :class:`CustomTreeCtrl` supports multiline
text items.

:note: To add a newline character in a multiline item, press ``Shift`` + ``Enter`` as the ``Enter``
 key alone is consumed by :class:`CustomTreeCtrl` to finish the editing and ``Ctrl`` + ``Enter`` is
 consumed by the platform for tab navigation.

:param `owner`: the control parent (an instance of :class:`CustomTreeCtrl`);

:raise: `Exception` when the item has an associated image but the parent
 :class:`CustomTreeCtrl` does not have a :class:`wx.ImageList` assigned.

Accepts/rejects the changes made by the user.

:return: ``True`` if the changes to the item text have been accepted, ``False``
 if they have been rejected (i.e., vetoed by the user).

Returns the item currently edited.

Handles the ``wx.EVT_CHAR`` event for :class:`TreeTextCtrl`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`TreeTextCtrl`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`TreeTextCtrl`.

:param `text`: the text to chop;
:param `max_size`: the maximum size in which the text should fit.

:note: This method is used exclusively when :class:`CustomTreeCtrl` has the ``TR_ELLIPSIZE_LONG_ITEMS``
 style set.

Draw the expanded/collapsed icon for a tree control item.

:param `win`: an instance of :class:`wx.Window`;
:param wx.Rect `rect`: the client rectangle where to draw the tree item button;
:param integer `flags`: contains ``wx.CONTROL_EXPANDED`` bit for expanded tree items.

:note: This is a simple replacement of :meth:`RendererNative.DrawTreeItemButton`.

:note: This method is never used in wxPython versions newer than 2.6.2.1.

Translate the key or mouse event flag to the type of selection we
are dealing with.

:param integer `style`: the main :class:`CustomTreeCtrl` window style flag;
:param bool `shiftDown`: ``True`` if the ``Shift`` key is pressed, ``False`` otherwise;
:param bool `ctrlDown`: ``True`` if the ``Ctrl`` key is pressed, ``False`` otherwise;

:return: A 3-elements tuple, with the following elements:

 - `is_multiple`: ``True`` if :class:`CustomTreeCtrl` has the ``TR_MULTIPLE`` flag set, ``False`` otherwise;
 - `extended_select`: ``True`` if the ``Shift`` key is pressend and if :class:`CustomTreeCtrl` has the
   ``TR_MULTIPLE`` flag set, ``False`` otherwise;
 - `unselect_others`: ``True`` if the ``Ctrl`` key is pressend and if :class:`CustomTreeCtrl` has the
   ``TR_MULTIPLE`` flag set, ``False`` otherwise.

:return: An instance of :class:`wx.Bitmap`, containing a disabled-looking
 representation of the original item image.

:class:`~wx.lib.agw.flatmenu.FlatMenu` is a generic menu implementation.

:class:`FlatMenu`, like the name implies, it is a generic menu implementation.
I tried to provide a full functionality for menus, menubar and toolbar.

:class:`FlatMenu` supports the following features:

- Fires all the events (UI & Cmd);
- Check items;
- Separators;
- Enabled / Disabled menu items;
- Images on items;
- Toolbar support, with images and separators;
- Controls in toolbar (work in progress);
- Toolbar tools tooltips (done: thanks to Peter Kort);
- Accelerators for menus;
- Accelerators for menubar;
- Radio items in menus;
- Integration with AUI;
- Scrolling when menu is too big to fit the screen;
- Menu navigation with keyboard;
- Drop down arrow button to the right of the menu, it always contains the
  "Customize" option, which will popup an options dialog. The dialog has the
  following abilities:

  (a) Ability to add/remove menus;
  (b) Select different colour schemes for the menu bar / toolbar;
  (c) Control various options, such as: colour for highlight menu item, draw
      border around menus (classic look only);
  (d) Toolbar floating appearance.

- Allows user to specify grey bitmap for disabled menus/toolbar tools;
- If no grey bitmap is provided, it generates one from the existing bitmap;
- Hidden toolbar items / menu bar items - will appear in a small popmenu
  to the right if they are hidden;
- 4 different colour schemes for the menu bar (more can easily added);
- Scrolling is available if the menu height is greater than the screen height;
- Context menus for menu items;
- Show/hide the drop down arrow which allows the customization of :class:`FlatMenu`;
- Multiple columns menu window;
- Tooltips for menus and toolbar items on a :class:`StatusBar` (if present);
- Transparency (alpha channel) for menu windows (for platforms supporting it);
- FileHistory support through a pure-Python :class:`FileHistory` implementation;
- Possibility to set a background bitmap for a :class:`FlatMenu`;
- First attempt in adding controls to FlatToolbar;
- Added a MiniBar (thanks to Vladiuz);
- Added :class:`ToolBar` methods AddCheckTool/AddRadioTool (thanks to Vladiuz).

Usage
=====

    import wx
    import wx.lib.agw.flatmenu as FM

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

            self.CreateMenu()

            panel = wx.Panel(self, -1)
            btn = wx.Button(panel, -1, "Hello", (15, 12), (100, 120))

            main_sizer = wx.BoxSizer(wx.VERTICAL)
            main_sizer.Add(self.menubar, 0, wx.EXPAND)
            main_sizer.Add(panel, 1, wx.EXPAND)

            self.SetSizer(main_sizer)
            main_sizer.Layout()

        def CreateMenu(self):

            self.menubar = FM.FlatMenuBar(self, -1)

            f_menu = FM.FlatMenu()
            e_menu = FM.FlatMenu()
            v_menu = FM.FlatMenu()
            t_menu = FM.FlatMenu()
            w_menu = FM.FlatMenu()

            # Append the menu items to the menus
            f_menu.Append(-1, "Simple   Ctrl+N", "Text", None)
            e_menu.Append(-1, "FlatMenu", "Text", None)
            v_menu.Append(-1, "Example", "Text", None)
            t_menu.Append(-1, "Hello", "Text", None)
            w_menu.Append(-1, "World", "Text", None)

            # Append menus to the menubar
            self.menubar.Append(f_menu, "&File")
            self.menubar.Append(e_menu, "&Edit")
            self.menubar.Append(v_menu, "&View")
            self.menubar.Append(t_menu, "&Options")
            self.menubar.Append(w_menu, "&Help")

:class:`FlatMenu` has been tested on the following platforms:
  * Windows (Windows XP, Vista);
  * Linux Ubuntu (Dapper 6.06)

========================= =========== ==================================================
Window Styles             Hex Value   Description
``FM_OPT_IS_LCD``                 0x1 Use this style if your computer uses a LCD screen.
``FM_OPT_MINIBAR``                0x2 Use this if you plan to use the toolbar only.
``FM_OPT_SHOW_CUSTOMIZE``         0x4 Show "customize link" in the `More` menu, you will need to write your own handler. See demo.
``FM_OPT_SHOW_TOOLBAR``           0x8 Set this option is you are planning to use the toolbar.

================================= ==================================================
``EVT_FLAT_MENU_DISMISSED``       Used internally.
``EVT_FLAT_MENU_ITEM_MOUSE_OUT``  Fires an event when the mouse leaves a :class:`FlatMenuItem`.
``EVT_FLAT_MENU_ITEM_MOUSE_OVER`` Fires an event when the mouse enters a :class:`FlatMenuItem`.
``EVT_FLAT_MENU_SELECTED``        Fires the :class:`EVT_MENU` event for :class:`FlatMenu`.

:class:`FlatMenu` is distributed under the wxPython license.

Version 1.0

# FLATMENU wxPython IMPLEMENTATION
#
#
# TODO List
#
# 1. Work is still in progress, so other functionalities may be added in the future;
# 2. No shadows under MAC, but it may be possible to create them using Carbon.
#
#
#
#
#
#
# Tags:     phoenix-port, py3-port, unittest, documented

AuiPaneInfo()
AuiPaneInfo(c)

wxAuiPaneInfo is part of the wxAUI class framework.

The :class:`FileHistory` encapsulates a user interface convenience, the list of most
recently visited files as shown on a menu (usually the File menu).

:class:`FileHistory` can manage one or more file menus. More than one menu may be
required in an MDI application, where the file history should appear on each MDI
child menu as well as the MDI parent frame.

:param integer `maxFiles`: the maximum number of files that should be stored and displayed;
:param integer `idBase`: defaults to ``wx.ID_FILE1`` and represents the id given to the first
 history menu item.

:note: Since menu items can't share the same ID you should change `idBase` to one of
 your own defined IDs when using more than one :class:`FileHistory` in your application.

Appends the files in the history list, to all menus managed by the file history object
if `menu` is ``None``. Otherwise it calls the auxiliary method :meth:`~FileHistory.AddFilesToMenu2`.

:param `menu`: if not ``None``, an instance of :class:`FlatMenu`.

Appends the files in the history list, to the given menu only.

:param `menu`: an instance of :class:`FlatMenu`.

Adds a file to the file history list, if the object has a pointer to an
appropriate file menu.

:param string `fnNew`: the file name to add to the history list.

Returns the base identifier for the range used for appending items. 

Returns the number of files currently stored in the file history. 

Returns the file at this index (zero-based).

:param integer `index`: the index at which the file is stored in the file list (zero-based).

Returns the list of menus that are managed by this file history object.

:see: :meth:`~FileHistory.UseMenu`.

Loads the file history from the given `config` object.

:param `config`: an instance of :class:`Config <ConfigBase>`.

:note: This function should be called explicitly by the application.

:see: :meth:`~FileHistory.Save`.

Removes the specified file from the history.

:param integer `index`: the zero-based index indicating the file name position in
 the file list.

Removes this menu from the list of those managed by this object.

Saves the file history to the given `config` object.

:see: :meth:`~FileHistory.Load`.

Sets the base identifier for the range used for appending items.

:param integer `baseId`: the base identifier for the range used for appending items.

Adds this menu to the list of those menus that are managed by this file history
object.

:see: :meth:`~FileHistory.AddFilesToMenu` for initializing the menu with filenames that are already
 in the history when this function is called, as this is not done automatically.

:param `parent`: the :class:`FlatMenu` parent window (used to initialize the
 underlying :class:`ShadowPopupWindow`).

Internal function to add the item to this menu. The item must
already be in the `self._itemsArr` attribute.

:param `menuItem`: an instance of :class:`FlatMenuItem`.

Advance forward or backward the current selection.

:param bool `down`: ``True`` to advance the selection forward, ``False`` otherwise.

Appends an item to this menu.

:param integer `id`: the menu item identifier;
:param string `item`: the string to appear on the menu item;
:param string `helpString`: an optional help string associated with the item. By default,
 the handler for the ``EVT_FLAT_MENU_ITEM_MOUSE_OVER`` event displays this string
 in the status line;
:param integer `kind`: may be ``wx.ITEM_NORMAL`` for a normal button (default),
 ``wx.ITEM_CHECK`` for a checkable tool (such tool stays pressed after it had been
 toggled) or ``wx.ITEM_RADIO`` for a checkable tool which makes part of a radio
 group of tools each of which is automatically unchecked whenever another button
 in the group is checked;

Adds a checkable item to the end of the menu.

:see: :meth:`~FlatMenu.Append` for the explanation of the input parameters.

Adds a pull-right submenu to the end of the menu.

:param `subMenu`: an instance of :class:`FlatMenu`, the submenu to append;
 in the status line.

Adds a radio item to the end of the menu.

All consequent radio items form a group and when an item in the group is
checked, all the others are automatically unchecked.

This function is added to duplicate the API of :class:`wx.Menu`.

:see: :meth:`~FlatMenu.AppendMenu` for an explanation of the input parameters.

Closes a child sub-menu.

:param integer `itemIdx`: the index of the item for which we want to close the submenu;
:param bool `alwaysClose`: if ``True``, always close the submenu irrespectively of
 other conditions.

Deletes the menu item from the menu. If the item is a submenu, it will be
deleted. Use :meth:`~FlatMenu.Remove` if you want to keep the submenu (for example, to reuse
it later).

:param `item`: can be either a menu item identifier or a plain :class:`FlatMenuItem`.

Dismisses the popup window.

:param bool `dismissParent`: whether to dismiss the parent menu or not;
:param bool `resetOwner`: ``True`` to delete the link between this menu and the
 owner menu, ``False`` otherwise.

Performs an action based on user selection.

:param integer `itemIdx`: the index of the item for which we want to perform the action.

Redraws the menu.

:param integer `oldSelection`: if non-negative, the index representing the previous selected
 menu item.

Finds the menu item object associated with the given menu item identifier and,
optionally, the (sub)menu it belongs to.

:param integer `itemId`: menu item identifier;
:param `menu`: if not ``None``, it will be filled with the item's parent menu
 (if the item was found).

:return: The found menu item object, or ``None`` if one was not found.

Finds an item and its position inside the menu based on its id.

:param `item`: an instance of :class:`FlatMenuItem`.

:return: An integer specifying the index found menu item object, or
 ``wx.NOT_FOUND`` if one was not found.

Returns a list filled with the accelerator entries for the menu. 

Returns the menu accelerator table, an instance of :class:`AcceleratorTable`. 

Internal function to help recurse through all the menu items.

:param `menu`: the menu from which we start accumulating items;
:param list `items`: the array which is recursively filled with menu items.

:return: a list of :class:`FlatMenuItem`.

Returns the background bitmap for this particular :class:`FlatMenu`, if any. 

Returns this :class:`FlatMenuItem` font.

:param integer `itemId`: the menu item identifier.

Returns this :class:`FlatMenuItem` foreground text colour.

Returns the label of a :class:`FlatMenuItem`.

:see: :meth:`~FlatMenu.SetLabel`.

Returns the width of a particular item.

HitTest method for :class:`FlatMenu`.

:param `pos`: an instance of :class:`wx.Point`, a point to test for hits.

:return: A tuple representing one of the following combinations:

 ========================= ==================================================
 Return Tuple              Description
 (0, -1)                   The :meth:`~FlatMenu.HitTest` method didn't find any item with the specified input point `pt` (``MENU_HT_NONE`` = 0)
 (1, `integer`)            A menu item has been hit (``MENU_HT_ITEM`` = 1)
 (2, -1)                   The `Scroll Up` button has been hit (``MENU_HT_SCROLL_UP`` = 2)
 (3, -1)                   The `Scroll Down` button has been hit (``MENU_HT_SCROLL_DOWN`` = 3)

Inserts the given `item` before the position `pos`.

:param integer `pos`: the position at which to insert the new menu item;

Inserts an item into the menu.

Inserts a separator at the given position.

:param integer `pos`: the index at which we want to insert the separator.

Handles key events for :class:`FlatMenu`.

:param `key`: the keyboard key integer code.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`FlatMenu`.

:note: This method is intentionally empty to avoid flicker.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_MOTION`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_PAINT`` event for :class:`FlatMenu`.

Handles the ``wx.EVT_TIMER`` event for :class:`FlatMenu`.

Open an item's context menu (if any).

:param integer `itemIdx`: the index of the item for which we want to open the context menu.

Pops up the menu.

:param `pt`: the point at which the menu should be popped up (an instance
 of :class:`wx.Point`);
:param `owner`: the owner of the menu. The owner does not necessarly mean the
 menu parent, it can also be the window that popped up it;
:param `parent`: the menu parent window.

Prepends an item to this menu.

Processes mouse left clicks.

:param `pos`: the position at which the mouse left button was pressed,
 an instance of :class:`wx.Point`.

Processes mouse movements.

:param `pos`: the position at which the mouse was moved, an instance of :class:`wx.Point`.

Processes mouse right clicks.

:param `pos`: the position at which the mouse right button was pressed,

In some cases, we need to perform a recursive refresh for all opened submenu
from this.

Removes the menu item from the menu but doesn't delete the associated menu
object. This allows to reuse the same item later by adding it back to the
menu (especially useful with submenus).

Actually sends menu command events.

:param integer `itemIdx`: the menu item index for which we want to send a command event.

Sends the ``EVT_FLAT_MENU_ITEM_MOUSE_OVER`` and ``EVT_FLAT_MENU_ITEM_MOUSE_OUT``
events.

:param integer `itemIdx`: the menu item index for which we want to send an event;
:param bool `over`: ``True`` to send a ``EVT_FLAT_MENU_ITEM_MOUSE_OVER`` event, ``False`` to
 send a ``EVT_FLAT_MENU_ITEM_MOUSE_OUT`` event.

Actually sends menu UI events.

:param integer `itemIdx`: the menu item index for which we want to send a UI event.

Sets a background bitmap for this particular :class:`FlatMenu`.

:param `bitmap`: an instance of :class:`wx.Bitmap`. Set `bitmap` to ``None`` if you
 wish to remove the background bitmap altogether.

:note: the bitmap is rescaled to fit the menu width and height.

Sets the :class:`FlatMenuItem` font.

:param integer `itemId`: the menu item identifier;
:param `font`: an instance of a valid :class:`wx.Font`.

Sets the :class:`FlatMenuItem` foreground text colour.

:param `colour`: an instance of a valid :class:`wx.Colour`.

Sets the label of a :class:`FlatMenuItem`.

:param string `label`: the menu item label to set.

:see: :meth:`~FlatMenu.GetLabel`.

Attaches this menu to a menubar.

:param `mb`: an instance of :class:`FlatMenuBar`.

Sets the number of columns for a menu window.

:param integer `numCols`: the number of columns for this :class:`FlatMenu` window.

If `itemIdx` is an item with submenu, open it.

:param integer `itemIdx`: the index of the item for which we want to open the submenu;
:param bool `selectFirst`: if ``True``, the first item of the submenu will be shown
 as selected.

Updates an item.

Updates a group of radio items.

Implements the generic owner-drawn menu bar for :class:`FlatMenu`.

:param `parent`: the menu bar parent, must not be ``None``;
:param integer `id`: the window identifier. If ``wx.ID_ANY``, will automatically create an identifier;
:param integer `iconSize`: size of the icons in the toolbar. This can be one of the
 following values (in pixels):

 ==================== ======= =============================
 `iconSize` Bit        Value  Description
 ``LargeIcons``            32 Use large 32x32 icons
 ``SmallIcons``            16 Use standard 16x16 icons

:param integer `spacer`: the space between the menu bar text and the menu bar border;
:param integer `options`: a combination of the following bits:

 ========================= ========= =============================
 `options` Bit             Hex Value  Description
 ``FM_OPT_IS_LCD``               0x1 Use this style if your computer uses a LCD screen
 ``FM_OPT_MINIBAR``              0x2 Use this if you plan to use toolbar only
 ``FM_OPT_SHOW_CUSTOMIZE``       0x4 Show "customize link" in more menus, you will need to write your own handler. See demo.
 ``FM_OPT_SHOW_TOOLBAR``         0x8 Set this option is you are planing to use the toolbar

__init__(self, parent, id=wx.ID_ANY, iconSize=SmallIcons, spacer=SPACER, options=FM_OPT_SHOW_CUSTOMIZE|FM_OPT_IS_LCD)

Activates a menu.

:param `menuInfo`: an instance of :class:`wx.MenuEntryInfo`.

Activates previous menu and make sure all others are non-active. 

Adds a new check (or toggle) tool to the toolbar.

:see: :meth:`~FlatMenuBar.AddTool` for parameter descriptions.

AddCheckTool(self, toolId, label="", bitmap1=wx.NullBitmap, bitmap2=wx.NullBitmap, shortHelp="", longHelp="")

Adds any control to the toolbar, typically e.g. a combobox.

:param `control`: the control to be added, a subclass of :class:`wx.Window` (but no :class:`TopLevelWindow`).

Consecutive radio tools form a radio group such that exactly one button in the
group is pressed at any moment, in other words whenever a button in the group is
pressed the previously pressed button is automatically released.

You should avoid having the radio groups of only one element as it would be
impossible for the user to use such button.

By default, the first button in the radio group is initially pressed, the others are not.

AddRadioTool(self, toolId, label= "", bitmap1=wx.NullBitmap, bitmap2=wx.NullBitmap, shortHelp="", longHelp="")

Adds a tool to the toolbar.

:param integer `toolId`: an integer by which the tool may be identified in subsequent
 operations;
:param string `label`: the tool label string;
:param `bitmap1`: the primary tool bitmap, an instance of :class:`wx.Bitmap`;
:param `bitmap2`: the bitmap used when the tool is disabled. If it is equal to
 :class:`NullBitmap`, the disabled bitmap is automatically generated by greing out
 the normal one;
:param string `shortHelp`: a string used for the tools tooltip;
:param string `longHelp`: this string is shown in the :class:`StatusBar` (if any) of the
 parent frame when the mouse pointer is inside the tool.

AddTool(self, toolId, label="", bitmap1=wx.NullBitmap, bitmap2=wx.NullBitmap, kind=wx.ITEM_NORMAL, shortHelp="", longHelp="")

Adds the item to the end of the menu bar.

:param `menu`: the menu to which we are appending a new item, an instance of :class:`FlatMenu`;
:param string `title`: the menu item label, must not be empty.

:see: :meth:`~FlatMenuBar.Insert`.

Appends a tool to the :class:`FlatMenuBar`.

.. deprecated:: 0.9.5
   This method is now deprecated.

:see: :meth:`~FlatMenuBar.AddTool`

Restores a :class:`NullBitmap` for all the items in the menu.

:param integer `start`: the index at which to start resetting the bitmaps.

Gives tooltips and help in :class:`StatusBar`.

:param `hit`: the toolbar tool currently hovered by the mouse.

Handles mouse move event.

:param bool `leftIsDown`: ``True`` is the left mouse button is down, ``False`` otherwise.

Performs a toolbar button pressed action.

:param integer `idx`: the tool index in the toolbar.

Draws 'more' button to the right side of the menu bar.

:param integer `state`: the 'more' button state.

:see: :meth:`wx.MenuEntryInfo.SetState() <MenuEntryInfo.SetState>` for a list of valid menu states.

Draws the toolbar (if present).

:param `rect`: the toolbar client rectangle, an instance of :class:`wx.Rect`.

:param integer `idx`: the tool index in the toolbar;
:param integer `state`: the button state.

Returns the index of the menu with the given title or ``wx.NOT_FOUND`` if
no such menu exists in this menubar.

:param string `title`: may specify either the menu title (with accelerator characters,
 i.e. "&File") or just the menu label ("File") indifferently.

Finds the menu item object associated with the given menu item identifier.

:param integer `id`: the identifier for the sought :class:`FlatMenuItem`.

Returns the number of invisible menu items.

:note: Valid only after the :class:`PaintEvent` has been processed after a resize.

Returns the number of invisible toolbar items.

Returns the menu at the specified index `menuIdx` (zero-based).

:param integer `menuIdx`: the index of the sought menu.

Returns a rectangle region, as an instance of :class:`wx.Rect`, surrounding the menu button. 

Returns the :class:`FlatMenuBar` options, whether to show a toolbar, to use LCD screen settings etc...

:see: :meth:`~FlatMenuBar.SetOptions` for a list of valid options.

HitTest method for :class:`FlatMenuBar`.

:param `pt`: an instance of :class:`wx.Point`, specifying the hit test position.

 (-1, 0)                   The :meth:`~FlatMenuBar.HitTest` method didn't find any item with the specified input point `pt` (``NoWhere`` = 0)
 (`integer`, 1)            A menu item has been hit, its position specified by the tuple item `integer` (``MenuItem`` = 1)
 (`integer`, 2)            A toolbar item has ben hit, its position specified by the tuple item `integer` (``ToolbarItem`` = 2)
 (-1, 3)                   The drop-down area button has been hit (``DropDownArrowButton`` = 3)

Inserts the menu at the given position into the menu bar.

:param integer `pos`: the position of the new menu in the menu bar;
:param `menu`: the menu to add, an instance of :class:`FlatMenu`. :class:`FlatMenuBar` owns the menu and will free it;
:param string `title`: the title of the menu.

:note: Inserting menu at position 0 will insert it in the very beginning of it,
 inserting at position :meth:`~FlatMenuBar.GetMenuCount` is the same as calling :meth:`~FlatMenuBar.Append`.

Single function to handle any accelerator key used inside the menubar.

:param `event`: a :class:`FlatMenuEvent` event to be processed.

Handles the customize dialog here.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`FlatMenuBar`.

:note: This method is intentionally empty to reduce flicker.

Handles the ``wx.EVT_IDLE`` event for :class:`FlatMenuBar`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`FlatMenuBar`.

:note: This method is for MSW only.

:note: This method is for GTK only.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`FlatMenuBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`FlatMenuBar`.

Handles the ``EVT_FLAT_MENU_DISMISSED`` event for :class:`FlatMenuBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`FlatMenuBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`FlatMenuBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`FlatMenuBar`.

Handles the timer expiring to delete the `longHelp` string in the :class:`StatusBar`. 

Positions the control inside a wxAUI / PyAUI frame manager.

:param `mgr`: an instance of :class:`~wx.lib.agw.aui.framemanager.AuiManager` or :class:`framemanager`;
:param bool `fixToolbar`: ``True`` if :class:`FlatMenuBar` can not be floated.

This function is called from child menus, this allow a child menu to
pass the mouse movement event to the menu bar.

Removes the menu from the menu bar and returns the menu object - the
caller is responsible for deleting it.

:param integer `pos`: the position of the menu in the menu bar.

:note: This function may be used together with :meth:`~FlatMenuBar.Insert` to change the menubar
 dynamically.

Sets the menu bar background colour.

:param `colour`: a valid :class:`wx.Colour`.

Recalculates the :class:`FlatMenuBar` height when its settings change. 

Sets whether the PC monitor is an LCD or not.

:param bool `lcd`: ``True`` to use the settings appropriate for a LCD monitor,

Sets the margin above and below the menu bar text.

:param integer `margin`: height in pixels of the margin.

Sets the :class:`FlatMenuBar` options, whether to show a toolbar, to use LCD screen settings etc...

Sets the spacing between the menubar items.

:param integer `spacer`: number of pixels between each menu item.

Sets the margin around the toolbar.

:param integer `margin`: width in pixels of the margin around the tools in the toolbar.

Sets the spacing between the toolbar tools.

:param integer `spacer`: number of pixels between each tool in the toolbar.

Sets the UpdateUI interval for toolbar items. All UpdateUI events are
sent from within :meth:`~FlatMenuBar.OnIdle` handler, the default is 20 milliseconds.

:param integer `interval`: the updateUI interval in milliseconds.

Shows/hides the drop-down arrow which allows customization of :class:`FlatMenu`.

:param bool `show`: ``True`` to show the customize menu, ``False`` to hide it.

An item was modified. This function is called by :class:`FlatMenu` in case
an item was modified directly and not via a :class:`UpdateUIEvent` event.

:param `item`: an instance of :class:`FlatMenu`.

Base class for generic flat menu derived from :class:`PopupWindow`.

:param `parent`: the :class:`ShadowPopupWindow` parent window.

Adjusts position so the menu will be fully visible on screen.

:param `pos`: an instance of :class:`wx.Point` specifying the menu position.

Returns the menu logical owner, the owner does not necessarly mean the
menu parent, it can also be the window that popped up it.

Fires an event ``EVT_FLAT_MENU_DISMISSED`` and handle menu dismiss. 

Popups menu at the specified point.

:param `pt`: an instance of :class:`wx.Point`, assumed to be in screen coordinates. However,
 if `parent` is not ``None``, `pt` is translated into the screen coordinates using
 `parent.ClientToScreen()`;
:param `parent`: if not ``None``, an instance of :class:`wx.Window`.

Scroll one unit down.
By default this function is empty, let derived class do something.

Scroll one unit up.

Sets the menu owner height, this will be used to position the menu below
or above the owner.

:param integer `height`: an integer representing the menu owner height.

A nice small class that functions like :class:`wx.BitmapButton`, the reason I did
not used :class:`wx.BitmapButton` is that on Linux, it has some extra margins that
I can't seem to be able to remove.

:param `menu`: the parent menu associated with this button, an instance of :class:`FlatMenu`;
:param bool `up`: ``True`` for up arrow or ``False`` for down arrow;
:param `normalBmp`: normal state bitmap, an instance of :class:`wx.Bitmap`;
:param `disabledBmp`: disabled state bitmap, an instance of :class:`wx.Bitmap`.

__init__(self, menu, up, normalBmp, disabledBmp=wx.NullBitmap, scrollOnHover=False)

Draws self at rect using dc.

Moves :class:`FlatMenuButton` to the specified position.

:param `input1`: if it is an instance of :class:`wx.Point`, it represents the :class:`FlatMenuButton`
 position and the `input2` parameter is not used. Otherwise it is an integer representing
 the button `x` position;
:param `input2`: if not ``None``, it is an integer representing the button `y` position.

Handles left down mouse events.

:param `pt`: an instance of :class:`wx.Point` where the left mouse button was pressed.

Handles left up mouse events.

:param `pt`: an instance of :class:`wx.Point` where the left mouse button was released.

Handles mouse motion events. This is called any time the mouse moves in the parent menu,
so we must check to see if the mouse is over the button.

:param `pt`: an instance of :class:`wx.Point` where the mouse pointer was moved.

Sets the size for :class:`FlatMenuButton`.

:param `input1`: if it is an instance of :class:`wx.Size`, it represents the :class:`FlatMenuButton`
 size and the `input2` parameter is not used. Otherwise it is an integer representing
 the button width;
:param `input2`: if not ``None``, it is an integer representing the button height.

Event class that supports the :class:`FlatMenu`-compatible event called
``EVT_FLAT_MENU_SELECTED``.

:param `parent`: menu that the menu item belongs to, an instance of :class:`FlatMenu`;
:param string `label`: text for the menu item, as shown on the menu. An accelerator
 key can be specified using the ampersand '&' character. In order to embed
 an ampersand character in the menu item text, the ampersand must be doubled;
:param string `helpString`: optional help string that will be shown on the status bar;
:param integer `kind`: may be ``wx.ITEM_SEPARATOR``, ``wx.ITEM_NORMAL``, ``wx.ITEM_CHECK``
 or ``wx.ITEM_RADIO``;
:param `subMenu`: if not ``None``, the sub menu this item belongs to (an instance of :class:`FlatMenu`);
:param `normalBmp`: normal bitmap to draw to the side of the text, this bitmap
 is used when the menu is enabled (an instance of :class:`wx.Bitmap`);
:param `disabledBmp`: 'greyed' bitmap to draw to the side of the text, this
 bitmap is used when the menu is disabled, if none supplied normal is used (an instance of :class:`wx.Bitmap`);
:param `hotBmp`: hot bitmap to draw to the side of the text, this bitmap is
 used when the menu is hovered, if non supplied, normal is used (an instance of :class:`wx.Bitmap`).

__init__(self, parent, id=wx.ID_SEPARATOR, label="", helpString="", kind=wx.ITEM_NORMAL, subMenu=None, normalBmp=wx.NullBitmap, disabledBmp=wx.NullBitmap, hotBmp=wx.NullBitmap)

Checks or unchecks the menu item.

:param bool `check`: ``True`` to check the menu item, ``False`` to uncheck it.

:note: This method is meaningful only for menu items of ``wx.ITEM_CHECK``
 or ``wx.ITEM_RADIO`` kind.

Enables or disables a menu item.

:param bool `enable`: ``True`` to enable the menu item, ``False`` to disable it.

Returns the normal bitmap associated to the menu item or :class:`NullBitmap` if
none has been supplied.

Returns the disabled bitmap associated to the menu item or :class:`NullBitmap`
if none has been supplied.

Returns the hot bitmap associated to the menu item or :class:`NullBitmap` if

Returns the menu item kind, can be one of ``wx.ITEM_SEPARATOR``, ``wx.ITEM_NORMAL``,
``wx.ITEM_CHECK`` or ``wx.ITEM_RADIO``.

Returns the menu item label (without the accelerator if it is part of the string). 

Returns the item long help string (displayed in the parent frame :class:`StatusBar`). 

Returns the item short help string (displayed in the tool's tooltip). 

Gets the bitmap that should be used based on the item state.

:param bool `selected`: ``True`` if this menu item is currently hovered by the mouse,

Returns the text associated with the menu item including the accelerator. 

Returns ``True`` if this item is of type ``wx.ITEM_CHECK``, ``False`` otherwise. 

:note: This method is meaningful only for items of kind ``wx.ITEM_CHECK`` or
 ``wx.ITEM_RADIO``.

Returns ``True`` if this item is of type ``wx.ITEM_RADIO``, ``False`` otherwise. 

Returns ``True`` if this item is of type ``wx.ITEM_SEPARATOR``, ``False`` otherwise. 

Assigns a context menu to this item.

:param `context_menu`: an instance of :class:`FlatMenu`.

Sets the menu item disabled bitmap.

:param `bmp`: an instance of :class:`wx.Bitmap`.

Sets the menu item help string.

:param string `helpString`: the new menu item help string.

Sets the menu item hot bitmap.

Sets the label text for this item from the text (excluding the accelerator).

:param string `text`: the new item label (excluding the accelerator).

Sets the item long help string (displayed in the parent frame :class:`StatusBar`).

:param string `help`: the new item long help string.

Sets the menu item parent menu.

Links the current menu item with the main :class:`FlatMenuBar`. 

Sets the menu item normal bitmap.

Sets the menu item client rectangle.

:param `rect`: the menu item client rectangle, an instance of :class:`wx.Rect`.

Sets the menu item sub-menu.

Sets the text for this menu item (including accelerators).

:param string `text`: the new item label (including the accelerator).

Sets the :class:`FlatMenuItem` foreground colour for the menu label.

Actually shows/hides the menu item.

:param bool `show`: ``True`` to show the menu item, ``False`` to hide it.

Adds a new item to the group.

Checks if an item is in the group.

Removes a particular item.

Selects a particular item.

:param `controlType`: can be ``None`` for a toolbar separator, an instance
 of :class:`wx.Window` for a control or an instance of :class:`wx.Bitmap` for a standard
 toolbar tool;
:param integer `id`: the toolbar tool id. If set to ``wx.ID_ANY``, a new id is
 automatically assigned;
:param `disabledBmp`: the bitmap used when the tool is disabled. If the tool
 is a standard one (i.e., not a control or a separator), and `disabledBmp`
 is equal to :class:`NullBitmap`, the disabled bitmap is automatically generated
 by greing the normal one;
:param string `shortHelp`: a string used for the tool's tooltip;

__init__(self, controlType=None, id=wx.ID_ANY, label="", disabledBmp=wx.NullBitmap, kind=wx.ITEM_NORMAL, shortHelp="", longHelp="")

:param bool `enable`: ``True`` to enable the tool, ``False`` to disable it.

Returns the tool long help string (displayed in the parent frame :class:`StatusBar`). 

Returns the tool short help string (displayed in the tool's tooltip). 

Same as :meth:`~FlatToolbarItem.IsSelected`. More intuitive for check items though. 

Selects or checks a radio or check item.

:param bool `select`: ``True`` to select or check a tool, ``False`` to unselect
 or uncheck it.

Sets the tool bitmap.

:param `bmp`: the new tool bitmap, a valid :class:`wx.Bitmap` object.

Sets the tool disabled bitmap.

:param `bmp`: the new tool disabled bitmap, a valid :class:`wx.Bitmap` object.

Sets group id for a radio item, for other items does nothing.

:param `group`: an instance of :class:`FlatMenuItemGroup`.

Sets the tool label.

:param string `label`: the new tool string.

Sets the tool long help string (displayed in the parent frame :class:`StatusBar`).

:param string `help`: the new tool long help string.

Sets the tool short help string (displayed in the tool's tooltip).

:param string `help`: the new tool short help string.

Class used to customize the appearance of :class:`~wx.lib.agw.flatmenu.FlatMenu`
and :class:`~wx.lib.agw.flatmenu.FlatMenuBar`.

:param `parent`: the :class:`FMCustomizeDlg` parent window.

Creates the :class:`~wx.lib.agw.labelbook.LabelBook` pages with :class:`~wx.lib.agw.flatmenu.FlatMenu` information. 

Creates the :class:`~wx.lib.agw.labelbook.LabelBook` option page which holds the
:class:`~wx.lib.agw.flatmenu.FlatMenu` styles.

Creates the :class:`~wx.lib.agw.labelbook.LabelBook` shortcuts page. 

Initializes the :class:`~wx.lib.agw.labelbook.LabelBook` pages. 

Handles the ``wx.EVT_CHECKBOX`` event for :class:`FMCustomizeDlg`.

:note: This method handles the :class:`~wx.lib.agw.flatmenu.FlatMenu` styles.

:note: This method handles the :class:`~wx.lib.agw.flatmenu.FlatMenu` menus visibility.

Base class for the :class:`FlatMenu` renderers. This class implements the common
methods of all the renderers.

:param `rect`: an instance of :class:`wx.Rect`, representing the bitmap client rectangle;

Draws a button.

:param `rect`: an instance of :class:`wx.Rect`, representing the button client rectangle;
:param `colour`: if not ``None``, an instance of :class:`wx.Colour` to be used to draw
 the :class:`FlatMenuItem` background.

Draws the menu left margin.

:param `item`: an instance of :class:`FlatMenuItem`;
:param `menuRect`: an instance of :class:`wx.Rect`, representing the menu client rectangle.

Draws the menu.

:param `flatmenu`: the :class:`FlatMenu` instance we need to paint;

Draws everything for :class:`FlatMenuBar`.

:param `menubar`: an instance of :class:`FlatMenuBar`.

Draws the menu bar background colour according to the menubar.GetBackgroundColour

:param `rect`: an instance of :class:`wx.Rect`, representing the menubar client rectangle.

Draws the highlight on a :class:`FlatMenuBar`.

Draws the highlight on a FlatMenu

Draws the menu item.

:param `item`: a :class:`FlatMenuItem` instance;
:param integer `xCoord`: the current x position where to draw the menu;
:param integer `yCoord`: the current y position where to draw the menu;
:param integer `imageMarginX`: the spacing between the image and the menu border;
:param integer `markerMarginX`: the spacing between the checkbox/radio marker and
 the menu border;
:param integer `textX`: the menu item label x position;
:param integer `rightMarginX`: the right margin between the text and the menu border;
:param `backgroundImage`: if not ``None``, an instance of :class:`wx.Bitmap` which will
 become the background image for this :class:`FlatMenu`.

DrawMenuItem(self, item, dc, xCoord, yCoord, imageMarginX, markerMarginX, textX, rightMarginX, selected=False, backgroundImage=None)

Draws the scroll button

Draws a separator inside a :class:`FlatMenu`.

:param integer `xCoord`: the current x position where to draw the separator;
:param integer `yCoord`: the current y position where to draw the separator;
:param integer `sepWidth`: the width of the separator, in pixels.

Draws the toolbar background

:param `rect`: an instance of :class:`wx.Rect`, representing the toolbar client rectangle.

Draws a separator inside the toolbar in :class:`FlatMenuBar`.

:param `rect`: an instance of :class:`wx.Rect`, representing the bitmap client rectangle.

Set the colour to highlight focus on the menu bar.

Set the colour to highlight focus on the menu.

This class represents a manager that handles all the renderers defined.
Every instance of this class will share the same state, so everyone can
instantiate their own and a call to :meth:`FMRendererMgr.SetTheme() <FMRendererMgr.SetTheme>` anywhere will affect everyone.

Adds a user defined custom renderer.

:param `renderer`: a class derived from :class:`FMRenderer`.

Sets the current theme.

:param `theme`: an integer specifying the theme to use.

Draws a button using the Office 2007 theme.

:param `item`: the :class:`FlatMenuItem` to paint;

Draws the highlight on a :class:`FlatMenu`.

Draws a button using the Vista theme.

:param `rect`: the an instance of :class:`wx.Rect`, representing the button client rectangle;

:param `menu`: an instance of :class:`FlatMenu` for which we want to redirect
 focus inputs.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`FocusHandler`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`FocusHandler`.

Sets the listener menu.

Since Max OS does not support :class:`PopupWindow`, this is an alternative. 

:param `parent`: the :class:`mcPopupWindow` parent window.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`mcPopupWindow`.

:param `titleOrMenu`: if it is a string, it represents the new menu label,
 otherwise it is another instance of :class:`wx.MenuEntryInfo` from which the attributes
 are copied;
:param `menu`: the associated :class:`FlatMenu` object;
:param integer `state`: the menu item state. This can be one of the following:

:param integer `cmd`: the menu accelerator identifier.

__init__(self, titleOrMenu="", menu=None, state=ControlNormal, cmd=wx.ID_ANY)

Returns the associated menu state.

:see: :meth:`~MenuEntryInfo.SetState` for a list of valid menu states.

Sets the associated menu client rectangle.

:param `rect`: an instance of :class:`wx.Rect`, representing the menu client rectangle.

Sets the associated selected menu bitmap.

:param `bmp`: a valid :class:`wx.Bitmap` object.

Sets the associated menu state.

Sets the associated menu bitmap.

 keyboard inputs;
:param `oldHandler`: a previous (if any) :class:`EvtHandler` associated with
 the menu.

Processes the inout event.

:param `event`: any kind of keyboard-generated events.

Base class for generic :class:`FlatMenu` derived from :class:`PopupWindow`. 

:param `parent`: the :class:`ShadowPopupWindow` parent (typically your main frame).

ShadowPopupWindow(wx.PopupWindow if havePopupWindow else mcPopupWindow)

Timer used for deleting :class:`StatusBar` long help after ``_DELAY`` seconds. 

:param `owner`: the :class:`Timer` owner (:class:`FlatMenuBar`).

:param `tbItem`: an instance of :class:`FlatToolbarItem`;
:param `rect`: the client rectangle for the toolbar item, an instance of :class:`wx.Rect`;
:param integer `state`: the toolbar item state.

:see: :meth:`wx.MenuEntryInfo.SetState() <MenuEntryInfo.SetState>` for a list of valid item states.

Converts a bitmap to monochrome colour.

:param string `label`: a string possibly containing an ampersand.

Returns the string used for the MRU list items in the menu.

:param integer `n`: the index of the file name in the MRU list;
:param string `path`: the full path of the file name.

:note: The index `n` is 0-based, as usual, but the strings start from 1.

:class:`~wx.lib.agw.flatnotebook.FlatNotebook` is a full, generic and owner-drawn implementation of :class:`Notebook`.

:class:`FlatNotebook` is a full implementation of the :class:`Notebook`, and designed to be
a drop-in replacement for :class:`Notebook`. The API functions are similar so one can
expect the function to behave in the same way.

- The buttons are highlighted a la Firefox style;
- The scrolling is done for bulks of tabs (so, the scrolling is faster and better);
- The buttons area is never overdrawn by tabs (unlike many other implementations I saw);
- It is a generic control;
- Currently there are 6 different styles - VC8, VC 71, Standard, Fancy, Firefox 2 and Ribbon;
- Mouse middle click can be used to close tabs;
- A function to add right click menu for tabs (simple as :meth:`~FlatNotebook.SetRightClickMenu`);
- All styles has bottom style as well (they can be drawn in the bottom of screen);
- An option to hide 'X' button or navigation buttons (separately);
- Gradient colouring of the selected tabs and border;
- Support for drag 'n' drop of tabs, both in the same notebook or to another notebook;
- Possibility to have closing button on the active tab directly;
- Support for disabled tabs;
- Colours for active/inactive tabs, and captions;
- Background of tab area can be painted in gradient (VC8 style only);
- Colourful tabs - a random gentle colour is generated for each new tab (very cool, VC8 style only);
- Support for showing pages in "column/row mode", which means that all the pages will be
  shown in "tile" mode while the tabs are hidden;
- Possibility to add a custom panel to show a logo or HTML documentation or
  whatever you like when there are no pages left in :class:`FlatNotebook`;
- Try setting the tab area colour for the Ribbon Style.

Usage
=====

    import wx
    import wx.lib.agw.flatnotebook as fnb

            wx.Frame.__init(self, parent, -1, "FlatNotebook Demo")

            notebook = fnb.FlatNotebook(panel, -1)

            for i in range(3):
                caption = "Page %d"%(i+1)
                notebook.AddPage(self.CreatePage(notebook, caption), caption)

            sizer = wx.BoxSizer(wx.VERTICAL)
            sizer.Add(notebook, 1, wx.ALL | wx.EXPAND, 5)
            panel.SetSizer(sizer)

        def CreatePage(self, notebook, caption):
            '''
            Creates a simple :class:`Panel` containing a :class:`TextCtrl`.

            :param `notebook`: an instance of `FlatNotebook`;
            :param `caption`: a simple label.
            '''

            p = wx.Panel(notebook)
            wx.StaticText(p, -1, caption, (20,20))
            wx.TextCtrl(p, -1, "", (20,40), (150,-1))
            return p

================================ =========== ==================================================
Window Styles                    Hex Value   Description
``FNB_VC71``                             0x1 Use Visual Studio 2003 (VC7.1) style for tabs.
``FNB_FANCY_TABS``                       0x2 Use fancy style - square tabs filled with gradient colouring.
``FNB_TABS_BORDER_SIMPLE``               0x4 Draw thin border around the page.
``FNB_NO_X_BUTTON``                      0x8 Do not display the 'X' button.
``FNB_NO_NAV_BUTTONS``                  0x10 Do not display the right/left arrows.
``FNB_MOUSE_MIDDLE_CLOSES_TABS``        0x20 Use the mouse middle button for cloing tabs.
``FNB_BOTTOM``                          0x40 Place tabs at bottom - the default is to place them at top.
``FNB_NODRAG``                          0x80 Disable dragging of tabs.
``FNB_VC8``                            0x100 Use Visual Studio 2005 (VC8) style for tabs.
``FNB_X_ON_TAB``                       0x200 Place 'X' close button on the active tab.
``FNB_BACKGROUND_GRADIENT``            0x400 Use gradients to paint the tabs background.
``FNB_COLOURFUL_TABS``                 0x800 Use colourful tabs (VC8 style only).
``FNB_DCLICK_CLOSES_TABS``            0x1000 Style to close tab using double click.
``FNB_SMART_TABS``                    0x2000 Use `Smart Tabbing`, like ``Alt`` + ``Tab`` on Windows.
``FNB_DROPDOWN_TABS_LIST``            0x4000 Use a dropdown menu on the left in place of the arrows.
``FNB_ALLOW_FOREIGN_DND``             0x8000 Allows drag 'n' drop operations between different :class:`FlatNotebook`.
``FNB_HIDE_ON_SINGLE_TAB``           0x10000 Hides the Page Container when there is one or fewer tabs.
``FNB_DEFAULT_STYLE``                0x10020 :class:`FlatNotebook` default style.
``FNB_FF2``                          0x20000 Use Firefox 2 style for tabs.
``FNB_NO_TAB_FOCUS``                 0x40000 Does not allow tabs to have focus.
``FNB_RIBBON_TABS``                  0x80000 Use the Ribbon Tabs style
``FNB_HIDE_TABS``                   0x100000 Hides the Page Container allowing only keyboard navigation
``FNB_NAV_BUTTONS_WHEN_NEEDED``     0x200000 Hides the navigation left/right arrows if all tabs fit

========================================= ==================================================
Event Name                                Description
``EVT_FLATNOTEBOOK_PAGE_CHANGED``         Notify client objects when the active page in :class:`FlatNotebook` has changed.
``EVT_FLATNOTEBOOK_PAGE_CHANGING``        Notify client objects when the active page in :class:`FlatNotebook` is about to change.
``EVT_FLATNOTEBOOK_PAGE_CLOSED``          Notify client objects when a page in :class:`FlatNotebook` has been closed.
``EVT_FLATNOTEBOOK_PAGE_CLOSING``         Notify client objects when a page in :class:`FlatNotebook` is closing.
``EVT_FLATNOTEBOOK_PAGE_CONTEXT_MENU``    Notify client objects when a pop-up menu should appear next to a tab.
``EVT_FLATNOTEBOOK_PAGE_DROPPED``         Notify client objects when a tab has been dropped and re-arranged (on the *same* notebook)
``EVT_FLATNOTEBOOK_PAGE_DROPPED_FOREIGN`` Notify client objects when a tab has been dropped and re-arranged (from a foreign notebook)

:class:`FlatNotebook` is distributed under the wxPython license.

Version 3.2

# FLATNOTEBOOK Widget wxPython IMPLEMENTATION
#
#
# http://wxforum.shadonet.com/viewtopic.php?t=5761&start=0
#
#
#
#
#
#
#
#
#
#

The :class:`FlatNotebook` is a full implementation of the :class:`Notebook`, and designed to be

:param `parent`: the :class:`FlatNotebook` parent;
:param `id`: an identifier for the control: a value of -1 is taken to mean a default;
:param `style`: the underlying :class:`Panel` window style;

 ================================ =========== ==================================================
 Window Styles                    Hex Value   Description
 ``FNB_VC71``                             0x1 Use Visual Studio 2003 (VC7.1) style for tabs.
 ``FNB_FANCY_TABS``                       0x2 Use fancy style - square tabs filled with gradient colouring.
 ``FNB_TABS_BORDER_SIMPLE``               0x4 Draw thin border around the page.
 ``FNB_NO_X_BUTTON``                      0x8 Do not display the 'X' button.
 ``FNB_NO_NAV_BUTTONS``                  0x10 Do not display the right/left arrows.
 ``FNB_MOUSE_MIDDLE_CLOSES_TABS``        0x20 Use the mouse middle button for cloing tabs.
 ``FNB_BOTTOM``                          0x40 Place tabs at bottom - the default is to place them at top.
 ``FNB_NODRAG``                          0x80 Disable dragging of tabs.
 ``FNB_VC8``                            0x100 Use Visual Studio 2005 (VC8) style for tabs.
 ``FNB_X_ON_TAB``                       0x200 Place 'X' close button on the active tab.
 ``FNB_BACKGROUND_GRADIENT``            0x400 Use gradients to paint the tabs background.
 ``FNB_COLOURFUL_TABS``                 0x800 Use colourful tabs (VC8 style only).
 ``FNB_DCLICK_CLOSES_TABS``            0x1000 Style to close tab using double click.
 ``FNB_SMART_TABS``                    0x2000 Use `Smart Tabbing`, like ``Alt`` + ``Tab`` on Windows.
 ``FNB_DROPDOWN_TABS_LIST``            0x4000 Use a dropdown menu on the left in place of the arrows.
 ``FNB_ALLOW_FOREIGN_DND``             0x8000 Allows drag 'n' drop operations between different :class:`FlatNotebook`.
 ``FNB_HIDE_ON_SINGLE_TAB``           0x10000 Hides the Page Container when there is one or fewer tabs.
 ``FNB_DEFAULT_STYLE``                0x10020 :class:`FlatNotebook` default style.
 ``FNB_FF2``                          0x20000 Use Firefox 2 style for tabs.
 ``FNB_NO_TAB_FOCUS``                 0x40000 Does not allow tabs to have focus.
 ``FNB_RIBBON_TABS``                  0x80000 Use the Ribbon Tabs style.
 ``FNB_HIDE_TABS``                   0x100000 Hides the Page Container allowing only keyboard navigation
 ``FNB_NAV_BUTTONS_WHEN_NEEDED``     0x200000 Hides the navigation left/right arrows if all tabs fit

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="FlatNotebook")

Adds a page to the :class:`FlatNotebook`.

:param `page`: specifies the new page;
:param `text`: specifies the text for the new page;
:param `select`: specifies whether the page should be selected;
:param `imageId`: specifies the optional image index for the new page.

:return: ``True`` if successful, ``False`` otherwise.

:param `forward`: if ``True``, the selection is advanced in ascending order
 (to the right), otherwise the selection is advanced in descending order.

Assigns the image list for the page control.

Deletes the specified page, and the associated window.

:param `page`: an integer specifying the new selected page.

Enables or disables a tab.

:param `page`: an integer specifying the page index;
:param `enabled`: ``True`` to enable a tab, ``False`` to disable it.

Ensures that a tab is visible.

:param `page`: an integer specifying the page index.

Returns the :class:`FlatNotebook` window style.

:see: :meth:`~FlatNotebook.SetAGWWindowStyleFlag` for a list of valid window styles.

Returns the currently selected notebook page or ``None`` if none is selected. 

Returns a custom panel to show when there are no pages left in :class:`FlatNotebook`. 

Returns the amount of space around each page's icon and label, in pixels. 

Returns the number of pages in the :class:`FlatNotebook` control. 

Returns the index at which the window is found.

:param `win`: an instance of :class:`wx.Window`.

Returns the angle associated to a tab.

:param `page_index`: the index of the tab for which we wish to get the shape angle.

Returns the string for the given page.

Returns the tab text colour if it has been set previously, or ``None`` otherwise.

Returns the orientation when on tiling mode. This method can return
``wx.VERTICAL`` when the panels are vertically stacked, ``wx.HORIZONTAL``
when they are horizontally stacked panels or ``None`` when there is no
stacking and :class:`FlatNotebook` behaves like a normal notebook.

Returns whether a flag is present in the :class:`FlatNotebook` style.

:param `flag`: one of the possible :class:`FlatNotebook` window styles.

:see: :meth:`~FlatNotebook.SetAGWWindowStyleFlag` for a list of possible window style flags.

Inserts a new page at the specified position.

:param `indx`: specifies the position of the new page;

Handles the drop action from a drag and drop operation.

:param `x`: the x position of the drop action;
:param `y`: the y position of the drop action;
:param `nTabPage`: the index of the tab being dropped;
:param `wnd_oldContainer`: the :class:`FlatNotebook` to which the dropped tab previously
 belonged to.

Handles the ``wx.EVT_NAVIGATION_KEY`` event for :class:`FlatNotebook`.

Deletes the specified page, without deleting the associated window.

Sets the active tab colour.

:param `colour`: a valid :class:`wx.Colour` object or any typemap supported by wxWidgets/wxPython
 to generate a colour (i.e., a hex string, a colour name, a 3 or 4 integer tuple).

Sets the text colour for the active tab.

:param `textColour`: a valid :class:`wx.Colour` object or any typemap supported by wxWidgets/wxPython

Sets the :class:`FlatNotebook` window style flags.

Sets the angle associated to all the tab.

:param `angle`: the new shape angle for the tab (must be less than 15 degrees).

Sets a custom panel to show when there are no pages left in :class:`FlatNotebook`.

:param `panel`: any subclass of :class:`wx.Window` will do, as long as it is suitable
 to be used as a notebook page. Examples include :class:`Panel`, :class:`ScrolledWindow`,
 and so on.

Sets the tab border colour.

:param `border`: the border colour, an instance of :class:`wx.Colour`.

Sets the starting colour for the gradient.

:param `fr`: the first gradient colour, an instance of :class:`wx.Colour`.

Sets the gradient colours for the tab.

:param `fr`: the first gradient colour, an instance of :class:`wx.Colour`;
:param `to`: the second gradient colour, an instance of :class:`wx.Colour`;

Sets the ending colour for the gradient.

Sets the image list for the page control.

Set the icon used by the :class:`TabNavigatorWindow`.

Sets the non active tabs text colour.

Sets the amount of space around each page's icon and label, in pixels.

:param `padding`: the amount of space around each page's icon and label,
 in pixels.

:note: Only the horizontal padding is considered.

:param `image`: an index into the image list which was set with :meth:`~FlatNotebook.SetImageList`.

Sets the angle associated to a tab.

:param `page_index`: the index of the tab for which we wish to get the shape angle;

Sets the text for the given page.

:param `text`: the new tab label.

Sets the tab text colour individually.

 to generate a colour (i.e., a hex string, a colour name, a 3 or 4 integer tuple). You can
 pass ``None`` or :class:`NullColour` to return to the default page text colour.

Sets the popup menu associated to a right click on a tab.

Sets the selection for the given page.

:note: The call to this function **does not** generate the page changing events.

Sets the area behind the tabs colour.

Hides the custom panel which is shown when there are no pages left in :class:`FlatNotebook`. 

Shows pages in column/row mode (one panel after the other in columns/rows).

:param `orient`: this parameter represents the orientation of the stacked
 panels. Pass ``wx.VERTICAL`` to get vertically stacked panels, ``wx.HORIZONTAL``
 to get horizontally stacked panels or ``None`` to return to the default
 :class:`FlatNotebook` behaviour with tabs.

This class is more compatible with the :class:`Notebook` API, especially regarding
page changing events. Use the :meth:`FlatNotebookCompatible.SetSelection() <FlatNotebookCompatible.SetSelection>` method if you wish to send page
changing events, or :meth:`FlatNotebookCompatible.ChangeSelection() <FlatNotebookCompatible.ChangeSelection>` otherwise.

:note: The call to this function **generates** the page changing events.

This event will be sent when a ``EVT_FLATNOTEBOOK_PAGE_DRAGGED_FOREIGN`` is
mapped in the parent.

:param `eventType`: the event type;
:param `eventId`: the event identifier;
:param `nSel`: the current selection;
:param `nOldSel`: the old selection.

Sets the new notebook.

:param `notebook`: an instance of :class:`FlatNotebook`.

Sets the old notebook.

This events will be sent when a ``EVT_FLATNOTEBOOK_PAGE_CHANGED``,
``EVT_FLATNOTEBOOK_PAGE_CHANGING``, ``EVT_FLATNOTEBOOK_PAGE_CLOSING``,
``EVT_FLATNOTEBOOK_PAGE_CLOSED`` and ``EVT_FLATNOTEBOOK_PAGE_CONTEXT_MENU`` is

This is the opposite of :meth:`~FlatNotebookEvent.Veto`: it explicitly allows the event to be processed.

Returns the page that was selected before the change, -1 if none was selected. 

Returns ``True`` if the change is allowed (:meth:`~FlatNotebookEvent.Veto` hasn't been called) or

:param `nOldSel`: an integer specifying the old selection.

Sets the event selection.

:param `nSel`: an integer specifying the new selection.

Stores all the information to allow drag and drop between different
:class:`FlatNotebook` instances.

:param `container`: the drag and drop container, a page in :class:`FlatNotebook`;
:param `pageindex`: the index of the tab that is actually being dragged.

Give some custom UI feedback during the drag and drop operation in this
function. It is called on each mouse move, so your implementation must
not be too slow.

:param `win`: the source window for which we wish to provide UI feedback
 during drag and drop operations.

You may give some custom UI feedback during the drag and drop operation
in this function. It is called on each mouse move, so your implementation
must not be too slow.

:param `effect`: the effect to implement. One of ``wx.DragCopy``, ``wx.DragMove``,
 ``wx.DragLink`` and ``wx.DragNone``.

:return: Return ``False`` if you want default feedback, or ``True`` if you
 implement your own feedback. The return values is ignored under GTK.

:note: To show your own custom drag and drop UI feedback, you must override
 this method.

Class used to handle the :meth:`FlatNotebook.OnDropTarget() <FlatNotebook.OnDropTarget>` method when dragging and
dropping between different :class:`FlatNotebook` instances.

:param `parent`: the window handling the drag and drop, an instance of
 :class:`FlatNotebook`.

Called after `OnDrop` returns ``True``.

By default this will usually call `GetData` and will return the suggested default value `dragres`.

:param `x`: the current x position of the mouse while dragging and dropping;
:param `y`: the current y position of the mouse while dragging and dropping;
:param `dragres`: an optional default return value.

Parent class for the 6 renderers defined: `Standard`, `VC71`, `Fancy`, `Firefox 2`,
`VC8` and `Ribbon`. This class implements the common methods of all 6 renderers.

Calculates the height of the input tab.

:param `pageContainer`: an instance of :class:`FlatNotebook`.

Calculates the width of the input tab.

:param `pageContainer`: an instance of :class:`FlatNotebook`;
:param `tabIdx`: the index of the input tab;
:param `tabHeight`: the height of the tab.

Draws the left and right scrolling arrows.

:param `pc`: an instance of :class:`FlatNotebook`;
:param `rect`: the client rectangle containing the scrolling arrows.

Draws tab drag hint, the default implementation is to do nothing.
You can override this function to provide a nice feedback to user.

:param `tabIdx`: the index of the tab we are dragging.

 this method in your derived class.

Draws the drop-down arrow in the navigation area.

Draws a focus rectangle like the native :class:`Notebook`.

:param `page`: an instance of :class:`PageInfo`, representing a page in the notebook.

Draws the left navigation arrow.

Draws the right navigation arrow.

Actually draws the tabs in :class:`FlatNotebook`.

Draws a line over the tabs.

:param `selTabX1`: first x coordinate of the tab line;
:param `selTabX2`: second x coordinate of the tab line.

Draws the 'X' in the selected tab.

:param `rect`: the current tab client rectangle;
:param `tabIdx`: the index of the current tab;
:param `btnStatus`: the status of the 'X' button in the current tab.

Draw the 'X' navigation button in the navigation area.

Returns the navigation area width.

Returns the drop down button position in the navigation area.

Returns the left button position in the navigation area.

Returns the right button position in the navigation area.

Returns the 'X' button position in the navigation area.

Calculates the number of tabs that can fit on the available space on screen.

:param `fr`: the current first visible tab.

This class handles the drawing of tabs using the standard renderer.

Draws a tab using the `Standard` style.

:param `posx`: the x position of the tab;
:param `tabIdx`: the index of the tab;
:param `tabWidth`: the tab's width;
:param `tabHeight`: the tab's height;
:param `btnStatus`: the status of the 'X' button inside this tab.

DrawTab(self, pageContainer, dc, posx, tabIdx, tabWidth, tabHeight, btnStatus)

This class handles the drawing of tabs using the `Fancy` renderer.

Draws a tab using the `Fancy` style, similar to the `VC71` one but with gradients.

This class handles the drawing of tabs using the `Firefox 2` renderer.

#------------------------------------------
# Firefox2 renderer

Draws a tab using the `Firefox 2` style.

This class represents a manager that handles all the 6 renderers defined
and calls the appropriate one when drawing is needed.

Returns the current renderer based on the style selected.

:param `style`: represents one of the 6 implemented styles for :class:`FlatNotebook`,
 namely one of these bits:

 ===================== ========= ======================
 Tabs style            Hex Value Description
 ``FNB_VC71``                0x1 Use Visual Studio 2003 (VC7.1) style for tabs
 ``FNB_FANCY_TABS``          0x2 Use fancy style - square tabs filled with gradient colouring
 ``FNB_VC8``               0x100 Use Visual Studio 2005 (VC8) style for tabs
 ``FNB_FF2``             0x20000 Use Firefox 2 style for tabs
 ``FNB_RIBBON_TABS``     0x80000 Use the Ribbon Tabs style to render the tabs

This class handles the drawing of tabs using the `Ribbon Tabs` renderer.

#------------------------------------------------------------------
# Ribbon Tabs style

Draws a tab using the `Ribbon Tabs` style.

This class handles the drawing of tabs using the `VC71` renderer.

Draws a tab using the `VC71` style.

This class handles the drawing of tabs using the `VC8` renderer.

# Visual studio 2005 (VS8)

Draws a tab using the `VC8` style.

Draws all the tabs using `VC8` style.

Fills a tab with a gradient shading.

:param `tabPoints`: a Python list of :class:`wx.Point` representing the tab outline;
:param `bSelectedTab`: ``True`` if the tab is selected, ``False`` otherwise;

FillVC8GradientColour(self, pageContainer, dc, tabPoints, bSelectedTab, tabIdx)

Returns the `x` end position of a tab.

:param `y`: the y end position of the tab;
:param `style`: can be ``FNB_BOTTOM`` or the default (tabs at top).

Returns the `x` start position of a tab.

:param `y`: the y start position of the tab;

This class acts as a container for the pages you add to :class:`FlatNotebook`.

:param `parent`: the :class:`PageContainer` parent;
:param `style`: the window style.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0)

Adds a page to the :class:`PageContainer`.

Assigns the image list for the :class:`PageContainer`.

Returns whether a tab can fit in the left space in the screen or not.

Deletes a flag from the :class:`FlatNotebook` style.

:see: :meth:`FlatNotebook.SetAGWWindowStyleFlag() <FlatNotebook.SetAGWWindowStyleFlag>` for a list of possible window
 style flags.

Delete the specified page from :class:`PageContainer`.

Does the actual page deletion.

Does the actual selection of a page.

Fires the ``EVT_FLATNOTEBOOK_PAGE_CHANGING`` and ``EVT_FLATNOTEBOOK_PAGE_CHANGED``
events called from other methods (from menu selection or `Smart Tabbing`).

This is an utility function.

:param `selection`: the new selection inside :class:`FlatNotebook`.

:see: The :meth:`FlatNotebook.__init__() <FlatNotebook.__init__>` method for the `agwStyle` parameter description.

Returns the number of tabs in the :class:`FlatNotebook` control. 

Returns the image index associated to a page.

Returns the tab caption of the page.

HitTest method for :class:`PageContainer`.

:param `pt`: an instance of :class:`wx.Point`, to test for hits.

:return: The hit test flag (if any) and the hit page index (if any). The return
 value can be one of the following bits:

 ========================= ======= =================================
 HitTest Flag               Value  Description
 ``FNB_NOWHERE``                 0 Indicates mouse coordinates not on any tab of the notebook
 ``FNB_TAB``                     1 Indicates mouse coordinates inside a tab
 ``FNB_X``                       2 Indicates mouse coordinates inside the 'X' button region
 ``FNB_TAB_X``                   3 Indicates mouse coordinates inside the 'X' region in a tab
 ``FNB_LEFT_ARROW``              4 Indicates mouse coordinates inside the left arrow region
 ``FNB_RIGHT_ARROW``             5 Indicates mouse coordinates inside the right arrow region
 ``FNB_DROP_DOWN_ARROW``         6 Indicates mouse coordinates inside the drop down arrow region

Returns whether or not the mouse is hovering over this page's tab

Moves a tab inside the same :class:`FlatNotebook`.

:param `nMove`: the start index of the moved tab;
:param `nMoveTo`: the destination index of the moved tab.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`PageContainer`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`PageContainer`.

:note: When the :class:`PageContainer` has the focus tabs can be changed with
 the left/right arrow keys.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`PageContainer`.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`PageContainer`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`PageContainer`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`PageContainer`.

Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`PageContainer`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`PageContainer`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`PageContainer`.

Handles the ``wx.EVT_MOTION`` event for :class:`PageContainer`.

Handles the ``wx.EVT_MOUSEWHEEL`` event for :class:`PageContainer`.

Handles the ``wx.EVT_PAINT`` event for :class:`PageContainer`.

Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`PageContainer`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`PageContainer`.

Handles the ``wx.EVT_SIZE`` event for :class:`PageContainer`.

Handles the ``wx.EVT_MENU`` event for :class:`PageContainer`.

:param `event`: a :class:`wx.MenuEvent` event to be processed.

Pops up the menu activated with the drop down arrow in the navigation area. 

Sets the :class:`FlatNotebook` window style.

:param `agwStyle`: the new :class:`FlatNotebook` window style.

Sets/Unsets the focus on the appropriate page.

:param `pageIndex`: an integer specifying the page index. If `pageIndex`
 is defaulted to -1, we have lost focus and no focus indicator is drawn.

Sets the image list for the :class:`PageContainer`.

:param `image`: an index into the image list which was set with :meth:`~PageContainer.SetImageList`.

Sets the tab caption of the page.

Sets the selected page.

Shows a tab tooltip.

:param `tabIdx`: an integer specifying the page index.

Returns whether a tab has an associated image index or not.

This class holds all the information (caption, image, etc...) belonging to a
single tab in :class:`FlatNotebook`.

Default Class Constructor.

:param `caption`: the tab caption;
:param `imageindex`: the tab image index based on the assigned (set)
 :class:`wx.ImageList` (if any);
:param `tabangle`: the tab angle (only on standard tabs, from 0 to 15
 degrees);
:param `enabled`: sets the tab as enabled or disabled.

__init__(self, caption="", imageindex=-1, tabangle=0, enabled=True)

Sets the tab enabled or disabled.

Returns the tab text colour if it has been set previously, or ``None``
otherwise.

Sets the tab caption.

:param `value`: the new tab caption string.

Sets the tab colour.

Sets the tab image index.

:param `value`: an index within the :class:`FlatNotebook` image list specifying
 the image to use for this tab.

Sets the tab text colour for this tab.

:param `colour`: an instance of :class:`wx.Colour`. You can pass ``None`` or
 :class:`NullColour` to return to the default page text colour.

Sets the tab position.

:param `value`: an instance of :class:`wx.Point`.

Sets the tab region.

:param `points`: a Python list of :class:`wx.Point`

Sets the tab size.

:param `value`: an instance of :class:`wx.Size`.

Sets the tab header angle.

:param `value`: the tab header angle (0 <= value <= 15 degrees).

Sets the button 'X' area rect.

:param `xrect`: an instance of :class:`wx.Rect`, specifying the client rectangle
 of the 'X' button.

This class is used to create a modal dialog that enables `Smart Tabbing`,

:param `parent`: the :class:`TabNavigatorWindow` parent window;
:param `icon`: a valid :class:`wx.Bitmap` object representing the icon to be displayed
 in the :class:`TabNavigatorWindow`.

Closes the :class:`TabNavigatorWindow` dialog, setting the new selection in
:class:`FlatNotebook`.

Handles the ``wx.EVT_LISTBOX_DCLICK`` for the :class:`TabNavigatorWindow`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` for the :class:`TabNavigatorWindow` top panel.

Handles the ``wx.EVT_PAINT`` for the :class:`TabNavigatorWindow` top panel.

:param `book`: an instance of :class:`FlatNotebook` containing the tabs to be
 displayed in the listbox.

Brighten/darken input colour by `percent` and adjust `alpha` channel if needed.

:param `colour`: colour object to adjust, an instance of :class:`wx.Colour`;
:param `percent`: percent to adjust ``+`` (brighten) or ``-`` (darken);
:param `alpha`: amount to adjust the alpha channel.

:return: The modified colour.

Draws a :class:`FlatNotebook` tab.

:param `rect`: the tab's client rectangle;
:param `focus`: ``True`` if the tab has focus, ``False`` otherwise;
:param `upperTabs`: ``True`` if the tabs are at the top, ``False`` if they are
 at the bottom.

Convert the input `colour` into a valid :class:`wx.Colour` instance, using whatever typemap
accepted by wxWidgets/wxPython.

:param `colour`: can be an instance of :class:`wx.Colour`, a 3 or 4 integer tuple, a hex
 string, a string representing the colour name or ``None``.

:returns: a valid instance of :class:`wx.Colour` or ``None`` if the input `colour` was ``None``
 in the first place.

Brighten the input colour by a percentage.

:param `percent`: the percentage by which the input colour should be brightened.

Draws a gradient coloured box from `startColour` to `endColour`.

:param `rect`: the rectangle to fill with the gradient shading;
:param `startColour`: the first colour in the gradient shading;
:param `endColour`: the last colour in the gradient shading;
:param `vertical`: ``True`` if the gradient shading is north to south, ``False``
 if it is east to west.

PaintStraightGradientBox(dc, rect, startColour, endColour, vertical=True)

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #c9dafb', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'``.............`', b'``.###########.`', b'``.###########.`', b'``.###########.`', b'``.#aaaaaaaaa#.`', b'``.##aaaaaaa##.`', b'``.###aaaaa###.`', b'``.####aaa####.`', b'``.#####a#####.`', b'``.###########.`', b'``.###########.`', b'``.###########.`', b'``.............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #9e9ede', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'``.............`', b'``.###########.`', b'``.###########.`', b'``.###########.`', b'``.###########.`', b'``.###########.`', b'``.#aaaaaaaaa#.`', b'``.##aaaaaaa##.`', b'``.###aaaaa###.`', b'``.####aaa####.`', b'``.#####a#####.`', b'``.###########.`', b'``.............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #000000', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````.........```', b'`````.......````', b'``````.....`````', b'```````...``````', b'````````.```````', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

DataFormat(format=DF_INVALID)
DataFormat(format)

A wxDataFormat is an encapsulation of a platform-specific format
handle which is used by the system for the clipboard and drag and drop
operations.

[b'    16    16        8            1', b'` c #008080', b'. c #555555', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'````````.```````', b'```````..```````', b'``````.`.```````', b'`````.``.```````', b'````.```.```````', b'`````.``.```````', b'``````.`.```````', b'```````..```````', b'````````.```````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #c9dafb', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.######a#####.`', b'`.#####aa#####.`', b'`.####aaa#####.`', b'`.###aaaa#####.`', b'`.##aaaaa#####.`', b'`.###aaaa#####.`', b'`.####aaa#####.`', b'`.#####aa#####.`', b'`.######a#####.`', b'`.############.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #9e9ede', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.############.`', b'`.#######a####.`', b'`.######aa####.`', b'`.#####aaa####.`', b'`.####aaaa####.`', b'`.###aaaaa####.`', b'`.####aaaa####.`', b'`.#####aaa####.`', b'`.######aa####.`', b'`.#######a####.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #555555', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'````````.```````', b'```````..```````', b'``````...```````', b'`````....```````', b'````.....```````', b'`````....```````', b'``````...```````', b'```````..```````', b'````````.```````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #555555', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'```````.````````', b'```````..```````', b'```````.`.``````', b'```````.``.`````', b'```````.```.````', b'```````.``.`````', b'```````.`.``````', b'```````..```````', b'```````.````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #c9dafb', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.####a#######.`', b'`.####aa######.`', b'`.####aaa#####.`', b'`.####aaaa####.`', b'`.####aaaaa###.`', b'`.####aaaa####.`', b'`.####aaa#####.`', b'`.####aa######.`', b'`.####a#######.`', b'`.############.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #9e9ede', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.############.`', b'`.#####a######.`', b'`.#####aa#####.`', b'`.#####aaa####.`', b'`.#####aaaa###.`', b'`.#####aaaaa##.`', b'`.#####aaaa###.`', b'`.#####aaa####.`', b'`.#####aa#####.`', b'`.#####a######.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #555555', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'```````.````````', b'```````..```````', b'```````...``````', b'```````....`````', b'```````.....````', b'```````....`````', b'```````...``````', b'```````..```````', b'```````.````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #c9dafb', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.############.`', b'`.##aa####aa##.`', b'`.###aa##aa###.`', b'`.####aaaa####.`', b'`.#####aa#####.`', b'`.####aaaa####.`', b'`.###aa##aa###.`', b'`.##aa####aa##.`', b'`.############.`', b'`.############.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #4766e0', b'# c #9e9ede', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'`..............`', b'`.############.`', b'`.############.`', b'`.############.`', b'`.###aa####aa#.`', b'`.####aa##aa##.`', b'`.#####aaaa###.`', b'`.######aa####.`', b'`.#####aaaa###.`', b'`.####aa##aa##.`', b'`.###aa####aa#.`', b'`.############.`', b'`..............`', b'````````````````', b'````````````````']

[b'    16    16        8            1', b'` c #008080', b'. c #555555', b'# c #000000', b'a c #000000', b'b c #000000', b'c c #000000', b'd c #000000', b'e c #000000', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````..````..````', b'`````..``..`````', b'``````....``````', b'```````..```````', b'``````....``````', b'`````..``..`````', b'````..````..````', b'````````````````', b'````````````````', b'````````````````', b'````````````````', b'````````````````']

:class:`~wx.lib.agw.floatspin.FloatSpin` implements a floating point :class:`SpinCtrl`.

:class:`FloatSpin` implements a floating point :class:`SpinCtrl`. It is built using a custom
:class:`wx.Control`, composed by a :class:`TextCtrl` and a :class:`SpinButton`. In order to
correctly handle floating points numbers without rounding errors or non-exact
floating point representations, :class:`FloatSpin` uses the great :class:`FixedPoint` class
from Tim Peters.

What you can do:

- Set the number of representative digits for your floating point numbers;
- Set the floating point format (``%f``, ``%F``, ``%e``, ``%E``, ``%g``, ``%G``);
- Set the increment of every ``EVT_FLOATSPIN`` event;
- Set minimum, maximum values for :class:`FloatSpin` as well as its range;
- Change font and colour for the underline :class:`TextCtrl`.

Usage
=====

    import wx
    import wx.lib.agw.floatspin as FS

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

            floatspin = FS.FloatSpin(panel, -1, pos=(50, 50), min_val=0, max_val=1,
                                     increment=0.01, value=0.1, agwStyle=FS.FS_LEFT)
            floatspin.SetFormat("%f")
            floatspin.SetDigits(2)

Events
======

:class:`FloatSpin` catches 3 different types of events:

1) Spin events: events generated by spinning up/down the spinbutton;
2) Char events: playing with up/down arrows of the keyboard increase/decrease
   the value of :class:`FloatSpin`;
3) Mouse wheel event: using the wheel will change the value of :class:`FloatSpin`.

In addition, there are some other functionalities:

- It remembers the initial value as a default value, call :meth:`~FloatSpin.SetToDefaultValue`, or
  press ``Esc`` to return to it;
- ``Shift`` + arrow = 2 * increment        (or ``Shift`` + mouse wheel);
- ``Ctrl``  + arrow = 10 * increment       (or ``Ctrl`` + mouse wheel);
- ``Alt``   + arrow = 100 * increment      (or ``Alt`` + mouse wheel);
- Combinations of ``Shift``, ``Ctrl``, ``Alt`` increment the :class:`FloatSpin` value by the
  product of the factors;
- ``PgUp`` & ``PgDn`` = 10 * increment * the product of the ``Shift``, ``Ctrl``, ``Alt``
  factors;
- ``Space`` sets the control's value to it's last valid state.

=============== =========== ==================================================
Window Styles   Hex Value   Description
``FS_READONLY``         0x1 Sets :class:`FloatSpin` as read-only control.
``FS_LEFT``             0x2 Horizontally align the underlying :class:`TextCtrl` on the left.
``FS_CENTRE``           0x4 Horizontally align the underlying :class:`TextCtrl` on center.
``FS_RIGHT``            0x8 Horizontally align the underlying :class:`TextCtrl` on the right.

``EVT_FLOATSPIN`` Emitted when the user changes the value of :class:`FloatSpin`, either with the mouse or with the keyboard.

:class:`FloatSpin` control is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 03 Jan 2014, 23.00 GMT

Backward Incompatibilities

Modifications to allow `min_val` or `max_val` to be ``None`` done by:

James Bigler,
SCI Institute, University of Utah,
March 14, 2007

:note: Note that the changes I made will break backward compatibility,
 because I changed the contructor's parameters from `min` / `max` to
 `min_val` / `max_val` to be consistent with the other functions and to
 eliminate any potential confusion with the built in `min` and `max`
 functions.

You specify open ranges like this (you can equally do this in the
constructor)::

    SetRange(min_val=1, max_val=None)     # [1,  ]
    SetRange(min_val=None, max_val=0)     # [ , 0]

or no range::

    SetRange(min_val=None, max_val=None)  # [ , ]

# FLOATSPIN Control wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 16 Nov 2005
# Latest Revision: 03 Jan 2014, 23.00 GMT
#
#
#
# 1. Ay Idea?
#
#
#
#
#

FixedPoint objects support decimal arithmetic with a fixed number of
digits (called the object's precision) after the decimal point.  The
number of digits before the decimal point is variable & unbounded.

The precision is user-settable on a per-object basis when a FixedPoint
is constructed, and may vary across FixedPoint objects.  The precision
may also be changed after construction via `FixedPoint.set_precision(p)`.
Note that if the precision of a FixedPoint is reduced via :meth:`FixedPoint.set_precision() <FixedPoint.set_precision>`,
information may be lost to rounding.

Example::

    >>> x = FixedPoint("5.55")  # precision defaults to 2
    >>> print(x)
    5.55
    >>> x.set_precision(1)      # round to one fraction digit
    5.6
    >>> print(FixedPoint("5.55", 1))  # same thing setting to 1 in constructor
    5.6
    >>> repr(x) #  returns constructor string that reproduces object exactly
    "FixedPoint('5.6', 1)"
    >>>

When :class:`FixedPoint` objects of different precision are combined via + - * /,
the result is computed to the larger of the inputs' precisions, which also
becomes the precision of the resulting :class:`FixedPoint` object. Example::

    >>> print FixedPoint("3.42") + FixedPoint("100.005", 3)
    103.425
    >>>

When a :class:`FixedPoint` is combined with other numeric types (ints, floats,
strings representing a number) via + - * /, then similarly the computation
is carried out using -- and the result inherits -- the :class:`FixedPoint`'s
precision. Example::

    >>> print(FixedPoint(1) / 7)
    0.14
    >>> print(FixedPoint(1, 30) / 7)
    0.142857142857142857142857142857
    >>>

The string produced by `str(x)` (implicitly invoked by `print`) always
contains at least one digit before the decimal point, followed by a
decimal point, followed by exactly `x.get_precision()` digits.  If `x` is
negative, `str(x)[0] == "-"`.

The :class:`FixedPoint` constructor can be passed an int, long, string, float,
:class:`FixedPoint`, or any object convertible to a float via `float()` or to an
integer via `int()`. Passing a precision is optional; if specified, the
precision must be a non-negative int. There is no inherent limit on
the size of the precision, but if very very large you'll probably run
out of memory.

Note that conversion of floats to :class:`FixedPoint` can be surprising, and
should be avoided whenever possible. Conversion from string is exact
(up to final rounding to the requested precision), so is greatly
preferred. Example::

    >>> print(FixedPoint(1.1e30))
    1099999999999999993725589651456.00
    >>> print(FixedPoint("1.1e30"))
    1100000000000000000000000000000.00
    >>>

:param `value`: the initial value;
:param `precision`: must be an int >= 0, and defaults to ``DEFAULT_PRECISION``.

Returns fractional portion as a :class:`FixedPoint`.

:note: In :class:`FixedPoint`,

 this equality holds true::

        x = x.frac() + int(x)

Return the precision of this :class:`FixedPoint`.

:note: The precision is the number of decimal digits carried after
 the decimal point, and is an int >= 0.

Change the precision carried by this :class:`FixedPoint` to `precision`.

:param `precision`: must be an int >= 0, and defaults to
 ``DEFAULT_PRECISION``.

:note: If `precision` is less than this :class:`FixedPoint`'s current precision,
 information may be lost to rounding.

:param `parent`: the :class:`FloatSpin` parent;
:param `style`: the window style;
:param `value`: is the current value for :class:`FloatSpin`;
:param `min_val`: the minimum value, ignored if ``None``;
:param `max_val`: the maximum value, ignored if ``None``;
:param `increment`: the increment for every :class:`FloatSpinEvent` event;
:param `digits`: number of representative digits for your floating point numbers;
:param `agwStyle`: one of the following bits:

 =============== =========== ==================================================
 Window Styles   Hex Value   Description
 ``FS_READONLY``         0x1 Sets :class:`FloatSpin` as read-only control.
 ``FS_LEFT``             0x2 Horizontally align the underlying :class:`TextCtrl` on the left.
 ``FS_CENTRE``           0x4 Horizontally align the underlying :class:`TextCtrl` on center.
 ``FS_RIGHT``            0x8 Horizontally align the underlying :class:`TextCtrl` on the right.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, value=0.0, min_val=None, max_val=None, increment=1.0, digits=-1, agwStyle=FS_LEFT, name="FloatSpin")

Clamps `var` between `_min` and `_max` depending if the range has
been specified.

:param `var`: the value to be clamped.

:return: A clamped copy of `var`.

Returns the string format in use.

:see: :meth:`~FloatSpin.SetFormat` for a list of valid string formats.

Returns the maximum value for :class:`FloatSpin`. It can be a
number or ``None`` if no minimum is present.

Returns the minimum value for :class:`FloatSpin`. It can be a

Returns whether a value is inside :class:`FloatSpin` range.

:param `value`: the value to test.

Tries to determine if a value is finite or infinite/NaN.

Handles the ``wx.EVT_CHAR`` event for :class:`FloatSpin`.

:note: This method works on the underlying :class:`TextCtrl`.

Handles the ``wx.EVT_WINDOW_DESTROY`` event for :class:`FloatSpin`.

:note: This method tries to correctly handle the control destruction under MSW.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`FloatSpin`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`FloatSpin`.

Handles the ``wx.EVT_MOUSEWHEEL`` event for :class:`FloatSpin`.

Handles the ``wx.EVT_SIZE`` event for :class:`FloatSpin`.

:note: This method resizes the text control and reposition the spin button when
 resized.

Handles the ``wx.EVT_SPIN_DOWN`` event for :class:`FloatSpin`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`FloatSpin`.

:note: This method works on the underlying :class:`SpinButton`.

Handles the ``wx.EVT_SPIN_UP`` event for :class:`FloatSpin`.

Handles the ``wx.EVT_TEXT_ENTER`` event for :class:`FloatSpin`.

Replaces the (somewhat) python ugly `+e000` with `+e00`.

:param `strs`: a string (possibly) containing a `+e00` substring.

Sets the :class:`FloatSpin` default value.

:param `defaultvalue`: a floating point value representing the new default
 value for :class:`FloatSpin`.

Sets the number of digits to show.

:param `digits`: the number of digits to show. If `digits` < 0, :class:`FloatSpin`
 tries to calculate the best number of digits based on input values passed
 in the constructor.

Sets the underlying :class:`TextCtrl` font.

:param `font`: a valid instance of :class:`wx.Font`.

Set the string format to use.

:param `fmt`: the new string format to use. One of the following strings:

 ====== =================================
 Format Description
 'e'    Floating point exponential format (lowercase)
 'E'    Floating point exponential format (uppercase)
 'f'    Floating point decimal format
 'F'    Floating point decimal format
 'g'    Floating point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise
 'G'    Floating point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise

Sets the increment for every ``EVT_FLOATSPIN`` event.

:param `increment`: a floating point number specifying the :class:`FloatSpin` increment.

Sets the maximum value for :class:`FloatSpin`.

:param `max_val`: the maximum value for :class:`FloatSpin`. If it is ``None`` it is
 ignored.

:note: This method doesn't modify the current value.

Sets the minimum value for :class:`FloatSpin`.

:param `min_val`: the minimum value for :class:`FloatSpin`. If it is ``None`` it is
 ignored.

Sets the allowed range.

 ignored;
 ignored.

:note: You specify open ranges like this (you can equally do this in the
 constructor)::

     SetRange(min_val=1, max_val=None)
     SetRange(min_val=None, max_val=0)

 or no range::

     SetRange(min_val=None, max_val=None)

 ignored;
 ignored.

Force the value to always be divisible by the increment. Initially ``False``.

:param `forceticks`: ``True`` to force the snap to ticks option, ``False`` otherwise.

:note: This uses the default value as the basis, you will get strange results
 for very large differences between the current value and default value
 when the increment is very small.

Sets the :class:`FloatSpin` value.

:param `value`: the new value.

Synchronize the underlying :class:`TextCtrl` with :class:`SpinButton`.

:param `send_event`: ``True`` to send a ``EVT_FLOATSPIN`` event, ``False``
:param `force_valid`: ``True`` to force a valid value (i.e. inside the
 provided range), ``False`` otherwise.

This event will be sent when a ``EVT_FLOATSPIN`` event is mapped in the parent. 

Sets event position.

:param `pos`: an integer specyfing the event position.

A class which holds a :class:`TextCtrl`, one of the two building blocks
of :class:`FloatSpin`.

Used internally. Do not call directly this class in your code!

:param `parent`: the :class:`FloatTextCtrl` parent;
:param `value`: default text value;

__init__(self, parent, id=wx.ID_ANY, value="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.TE_NOHIDESEL | wx.TE_PROCESS_ENTER, validator=wx.DefaultValidator, name=wx.TextCtrlNameStr)

Handles the ``wx.EVT_CHAR`` event for :class:`FloatTextCtrl`.

Handles the ``wx.EVT_WINDOW_DESTROY`` event for :class:`FloatTextCtrl`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`FloatTextCtrl`.

:note: This method synchronizes the :class:`SpinButton` and the :class:`TextCtrl`
 when focus is lost.
 
Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

Return the integer represented by the given array of bytes.

bytes
  Holds the array of bytes to convert.  The argument must either
  support the buffer protocol or be an iterable object producing bytes.
  Bytes and bytearray are examples of built-in objects that support the
  buffer protocol.
byteorder
  The byte order used to represent the integer.  If byteorder is 'big',
  the most significant byte is at the beginning of the byte array.  If
  byteorder is 'little', the most significant byte is at the end of the
  byte array.  To request the native byte order of the host system, use
  `sys.byteorder' as the byte order value.
signed
  Indicates whether two's complement is used to represent the integer.

Return an array of bytes representing an integer.

length
  Length of bytes object to use.  An OverflowError is raised if the
  integer is not representable with the given number of bytes.
byteorder
signed
  Determines whether two's complement is used to represent the integer.
  If signed is False and a negative integer is given, an OverflowError
  is raised.

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple.
If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

This module contains a custom dialog class used to personalize the appearance of a
:class:`~wx.lib.agw.flatmenu.FlatMenu` on the fly, allowing also the user of your application to do the same.

# Name:         fmcustomizeddlg.py
# Purpose:
#
# Author:
#
# Created:
# Version:
# Date:
# Tags:         phoenix-port, py3-port

:param `parent`: the :class:`FMTitlePanel` parent;
:param `title`: the string to use as a dialog title.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`FMTitlePanel`.

Handles the ``wx.EVT_PAINT`` event for :class:`FMTitlePanel`.

An implementation of a notebook control - except that instead of having
tabs to show labels, it labels to the right or left (arranged horizontally).

:param `parent`: parent window. Must not be ``None``;
:param `id`: window identifier. A value of -1 indicates a default value;

 =========================== =========== ==================================================
 Window Styles               Hex Value   Description
 ``INB_BOTTOM``                      0x1 Place labels below the page area. Available only for :class:`FlatImageBook`.
 ``INB_LEFT``                        0x2 Place labels on the left side. Available only for :class:`FlatImageBook`.
 ``INB_RIGHT``                       0x4 Place labels on the right side.
 ``INB_TOP``                         0x8 Place labels above the page area.
 ``INB_BORDER``                     0x10 Draws a border around :class:`LabelBook` or :class:`FlatImageBook`.
 ``INB_SHOW_ONLY_TEXT``             0x20 Shows only text labels and no images. Available only for :class:`LabelBook`.
 ``INB_SHOW_ONLY_IMAGES``           0x40 Shows only tab images and no label texts. Available only for :class:`LabelBook`.
 ``INB_FIT_BUTTON``                 0x80 Displays a pin button to show/hide the book control.
 ``INB_DRAW_SHADOW``               0x100 Draw shadows below the book tabs. Available only for :class:`LabelBook`.
 ``INB_USE_PIN_BUTTON``            0x200 Displays a pin button to show/hide the book control.
 ``INB_GRADIENT_BACKGROUND``       0x400 Draws a gradient shading on the tabs background. Available only for :class:`LabelBook`.
 ``INB_WEB_HILITE``                0x800 On mouse hovering, tabs behave like html hyperlinks. Available only for :class:`LabelBook`.
 ``INB_NO_RESIZE``                0x1000 Don't allow resizing of the tab area.
 ``INB_FIT_LABELTEXT``            0x2000 Will fit the tab area to the longest text (or text+image if you have images) in all the tabs.
 ``INB_BOLD_TAB_SELECTION``       0x4000 Show the selected tab text using a bold font.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="LabelBook")

Creates the image container (LabelContainer) class for :class:`FlatImageBook`. 

Returns the colour for the specified parameter.

:param `which`: the colour key.

:see: :meth:`LabelContainer.SetColour() <LabelContainer.SetColour>` for a list of valid colour keys.

Handles the ``wx.EVT_SIZE`` event for :class:`LabelBook`.

Sets the colour for the specified parameter.

:param `which`: the colour key;

D.popitem() -> (k, v), remove and return some (key, value) pair
as a 2-tuple; but raise KeyError if D is empty.

D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D

D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
In either case, this is followed by: for k, v in F.items(): D[k] = v

:class:`~wx.lib.agw.foldpanelbar.FoldPanelBar` is a control that contains multiple panels, which can be expanded
or collapsed.

The :class:`FoldPanelBar` is a control that contains multiple panels (of type
:class:`FoldPanelItem`) that can be expanded or collapsed. The captionbar of
the :class:`FoldPanelBar` can be customized by setting it to a horizontal gradient
style, vertical gradient style, a single colour, a rectangle or filled
rectangle. The `FoldPanel` items can be collapsed in place or to the
bottom of the control. :class:`wx.Window` derived controls can be added
dynamically, and separated by separator lines.

How does it work
----------------

The internals of the :class:`FoldPanelBar` is a list of :class:`FoldPanelItem` objects. Through
the reference of `FoldPanel` these panels can be controlled by adding new controls
to a FoldPanel or adding new FoldPanels to the :class:`FoldPanelBar`.

The :class:`CaptionBar` fires events to the parent (container of all panel items) when a
sub-panel needs resizing (either folding or expanding). The fold or expand process
is simply a resize of the panel so it looks like all controls on it are gone. All
controls are still child of the `FoldPanel` they are located on. If they don't
handle the event (and they won't) then the owner of the :class:`FoldPanelBar` gets the
events.

This is what you need to handle the controls. There isn't much to it just
a lot of calculations to see what panel belongs where. There are no sizers
involved in the panels, everything is purely x-y positioning.

What can it do and what not?
----------------------------

a) What it can do:

   * Run-time addition of panels (no deletion just yet);
   * Run time addition of controls to the panel (it will be resized accordingly);
   * Creating panels in collapsed mode or expanded mode;
   * Various modes of caption behaviour and filling to make it more appealing;
   * Panels can be folded and collapsed (or all of them) to allow more space.

b) What it cannot do:

   * Selection of a panel like in a listctrl;
   * Dragging and dropping the panels;
   * Re-ordering the panels (not yet).

Usage
=====

    import wx
    import wx.lib.agw.foldpanelbar as fpb

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

            text_ctrl = wx.TextCtrl(self, -1, size=(400, 100), style=wx.TE_MULTILINE)

            panel_bar = fpb.FoldPanelBar(self, -1, agwStyle=fpb.FPB_VERTICAL)

            fold_panel = panel_bar.AddFoldPanel("Thing")
            thing = wx.TextCtrl(fold_panel, -1, size=(400, -1), style=wx.TE_MULTILINE)

            panel_bar.AddFoldPanelWindow(fold_panel, thing)

            main_sizer.Add(text_ctrl, 1, wx.EXPAND)
            main_sizer.Add(panel_bar, 1, wx.EXPAND)

:class:`FoldPanelBar` is supported on the following platforms:
  * Windows (Verified on Windows XP, 2000)
  * Linux/Unix (GTK2) (Thanks to Toni Brkic and Robin Dunn)
  * Mac OSX (Thanks to Robin Dunn for the :class:`CaptionBar` size patch)

========================== =========== ==================================================
Window Styles              Hex Value   Description
``FPB_SINGLE_FOLD``                0x1 Single fold forces other panels to close when they are open, and only opens the current panel. This will allow the open panel to gain the full size left in the client area.
``FPB_COLLAPSE_TO_BOTTOM``         0x2 All panels are stacked to the bottom. When they are expanded again they show up at the top.
``FPB_EXCLUSIVE_FOLD``             0x4 ``FPB_SINGLE_FOLD`` style plus the panels will be stacked at the bottom.
``FPB_HORIZONTAL``                 0x8 :class:`FoldPanelBar` will be horizontal.
``FPB_VERTICAL``                  0x10 :class:`FoldPanelBar` will be vertical.

================== ==================================================
Event Name         Description
``EVT_CAPTIONBAR`` The user has pressed the caption bar: :class:`FoldPanelBar` will either expand or collapse the underlying panel.

:class:`FoldPanelBar` is distributed under the wxPython license.

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

Version 0.6

# FOLDPANELBAR wxPython IMPLEMENTATION
# Ported From Jorgen Bodde & Julian Smart (Extended Demo) C++ Code By:
#
# Andrea Gavana, @ 23 Mar 2005
#
#
# TODO List
#
# All The C++ TODOs Are Still Alive. I Am Not Able to Read Jorges's Mind
# So I Don't Really Know What Will Be The New Features/Additions He Will
# Make On His Code. At The Moment They Are:
#
# 1. OnPaint Function In CaptionBar Class:
# TODO: Maybe First A Memory Dc Should Draw All, And Then Paint It On The
# Caption. This Way A Flickering Arrow During Resize Is Not Visible.
#
# 2. OnChar Function In CaptionBar Class:
# TODO: This Is Easy To Do But I Don't Have Any Useful Idea On Which Kind
# Of Features To Add. Does Anyone Have An Intelligent Idea?
#
# 3. AddFoldPanelWindow Function In FoldPanelBar Class:
# TODO: Take Old And New Heights, And If Difference, Reposition All The
# Lower Panels. This Is Because The User Can Add New wxWindow Controls
# Somewhere In Between When Other Panels Are Already Present.
# Don't Know What It Means. Probably Is My Poor English...
#
# 4. OnSizePanel Function In FoldPanelBar Class:
# TODO: A Smart Way To Check Whether The Old - New Width Of The
# Panel Changed, If So No Need To Resize The Fold Panel Items
#
#
# DONE List:
#
# 1. Implemented Styles Like FPB_SINGLE_FOLD and FPB_EXCLUSIVE_FOLD
# Thanks To E. A. Tacao For His Nice Suggestions.
#
# 2. Added Some Maquillage To FoldPanelBar: When The Mouse Enters The Icon
# Region, It Is Changed To wx.CURSOR_HAND.
#
#
# For The Original TODO List From Jorgen, Please Refer To:
# http://www.solidsteel.nl/jorg/components/foldpanel/wxFoldPanelBar.php#todo_list
#
#
#
#
#
#
#

This class is a graphical caption component that consists of a
caption and a clickable arrow.

The :class:`CaptionBar` fires an event ``EVT_CAPTIONBAR`` which is a
:class:`CaptionBarEvent`. This event can be caught and the parent window
can act upon the collapsed or expanded state of the bar (which is
actually just the icon which changed). The parent panel can
reduce size or expand again.

:param `parent`: the :class:`CaptionBar` parent window;
:param `caption`: the string to be displayed in :class:`CaptionBar`;
:param `foldIcons`: an instance of :class:`wx.ImageList` containing the icons to display
 next to the caption text;
:param `cbstyle`: the :class:`CaptionBar` window style. Must be an instance of
 :class:`CaptionBarStyle`;
:param `rightIndent`: number of pixels of the bmp to be aligned from the right filled
 with space;
:param `iconWidth`: the :class:`CaptionBar` icon width;
:param `iconHeight`: the :class:`CaptionBar` icon height;
:param `collapsed`: ``True`` if the :class:`CaptionBar` should start in the collapsed state,

__init__(self, parent, id, pos, size, caption="", foldIcons=None, cbstyle=None, rightIndent=FPB_BMP_RIGHTSPACE, iconWidth=16, iconHeight=16, collapsed=False)

Applies the style defined in `cbstyle` to the :class:`CaptionBar`.

:param `cbstyle`: an instance of :class:`CaptionBarStyle`;
:param `applyDefault`: if ``True``, the colours used in the :class:`CaptionBarStyle`
 will be reset to their default values.

This sets the internal state/representation to collapsed.

:note: This does not trigger a :class:`CaptionBarEvent` to be sent to the
 parent.

Returns the best size for this panel, based upon the font
assigned to this window, and the caption string.

:note: Overridden from :class:`wx.Window`.

:param `rect`: the :class:`CaptionBar` client rectangle.

Single colour fill for :class:`CaptionBar`.

Single rectangle for :class:`CaptionBar`.

This sets the internal state/representation to expanded.

 parent.

Fills the background of the caption with either a gradient or
a solid colour.

Returns the current style of the captionbar in a :class:`CaptionBarStyle` class.

:note: This can be used to change and set back the changes.

Returns whether the status of the bar is expanded or collapsed. 

Returns whether the :class:`CaptionBar` has a default orientation or not.
Default is vertical.

Handles the ``wx.EVT_CHAR`` event for :class:`CaptionBar`.

:note: This method currently does nothing.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`CaptionBar`.

:note: This method catches the mouse click-double click. If clicked on
 the arrow (single) or double on the caption we change state and an event
 must be fired to let this panel collapse or expand.

Handles the ``wx.EVT_PAINT`` event for :class:`CaptionBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`CaptionBar`.

Sets :class:`CaptionBar` styles with :class:`CaptionBarStyle` class.

:note: All styles that are actually set, are applied. If you set `applyDefault`
 to ``True``, all other (not defined) styles will be set to default. If it is
 ``False``, the styles which are not set in the :class:`CaptionBarStyle` will be ignored.

Sets the amount of pixels on the right from which the bitmap
is trailing.

:param `pixels`: the number of pixels on the right from which the bitmap
 is trailing. If this is 0, it will be drawn all the way to the right,
 default is equal to ``FPB_BMP_RIGHTSPACE``. Assign this before
 assigning an image list to prevent a redraw.

This event will be sent when a ``EVT_CAPTIONBAR`` is mapped in the parent.
It is to notify the parent that the bar is now in collapsed or expanded
state. The parent should re-arrange the associated windows accordingly

Returns whether the bar is expanded or collapsed. ``True`` means
expanded.

Sets the bar associated with this event.

:param `bar`: an instance of :class:`CaptionBar`.

:note: Should not be used by any other than the originator of the event.

Assigns a tag to the selected :class:`CaptionBar`.

:param `tag`: an instance of :class:`FoldPanelBar`.

This class encapsulates the styles you wish to set for the
:class:`CaptionBar` (this is the part of the `FoldPanel` where the caption
is displayed). It can either be applied at creation time be
reapplied when styles need to be changed.

At construction time, all styles are set to their default
transparency.  This means none of the styles will be applied to
the :class:`CaptionBar` in question, meaning it will be created using the
default internals. When setting i.e the colour, font or panel
style, these styles become active to be used.

Returns the caption colour for the caption bar.

:note: Please be warned this will result in an assertion failure
 when this property is not previously set.

:see: :meth:`~CaptionBarStyle.SetCaptionColour`, :meth:`~CaptionBarStyle.CaptionColourUsed`

Returns the font for the caption bar.

:note: Please be warned this will result in an assertion failure when
 this property is not previously set.

:see: :meth:`~CaptionBarStyle.SetCaptionFont`, :meth:`~CaptionBarStyle.CaptionFontUsed`

Returns the caption style for the caption bar.

:see: :meth:`~CaptionBarStyle.SetCaptionStyle`, :meth:`~CaptionBarStyle.CaptionStyleUsed`

Returns the first colour for the caption bar.

:see: :meth:`~CaptionBarStyle.SetFirstColour`, :meth:`~CaptionBarStyle.FirstColourUsed`

Returns the second colour for the caption bar.

:see: :meth:`~CaptionBarStyle.SetSecondColour`, :meth:`~CaptionBarStyle.SecondColourUsed`

Sets caption colour for the caption bar.

:note: If this is not set, the colour property is undefined and will not be used.
 Use :meth:`~CaptionBarStyle.CaptionColourUsed` to check if this style is used.

Sets font for the caption bar.

:param `font`: a valid :class:`wx.Font` object.

:note: If this is not set, the font property is undefined and will not be used.
 Use :meth:`~CaptionBarStyle.CaptionFontUsed` to check if this style is used.

Sets caption style for the caption bar.

:param `style`: can be one of the following bits:

 =============================== ======= =============================
 Caption Style                    Value  Description
 ``CAPTIONBAR_GRADIENT_V``             1 Draws a vertical gradient from top to bottom
 ``CAPTIONBAR_GRADIENT_H``             2 Draws a horizontal gradient from left to right
 ``CAPTIONBAR_SINGLE``                 3 Draws a single filled rectangle to draw the caption
 ``CAPTIONBAR_RECTANGLE``              4 Draws a single colour with a rectangle around the caption
 ``CAPTIONBAR_FILLED_RECTANGLE``       5 Draws a filled rectangle and a border around it

:note: If this is not set, the property is undefined and will not be used.
 Use :meth:`~CaptionBarStyle.CaptionStyleUsed` to check if this style is used.

Sets first colour for the caption bar.

 Use :meth:`~CaptionBarStyle.FirstColourUsed` to check if this style is used.

Sets second colour for the caption bar.

 Use :meth:`~CaptionBarStyle.SecondColourUsed` to check if this style is used.

The :class:`FoldPanelBar` is a class which can maintain a list of
collapsible panels. Once a panel is collapsed, only it's caption
bar is visible to the user. This will provide more space for the
other panels, or allow the user to close panels which are not used
often to get the most out of the work area.

This control is easy to use. Simply create it as a child for a
panel or sash window, and populate panels with
:meth:`FoldPanelBar.AddFoldPanel() <FoldPanelBar.AddFoldPanel>`. Then use the
:meth:`FoldPanelBar.AddFoldPanelWindow() <FoldPanelBar.AddFoldPanelWindow>` to add
:class:`wx.Window` derived controls to the current fold panel. Use
:meth:`FoldPanelBar.AddFoldPanelSeparator() <FoldPanelBar.AddFoldPanelSeparator>` to put separators between the groups of
controls that need a visual separator to group them
together. After all is constructed, the user can fold the panels
by double clicking on the bar or single click on the arrow, which
will indicate the collapsed or expanded state.

:param `parent`: the :class:`FoldPanelBar` parent window;
:param `agwStyle`: the AGW-specific :class:`FoldPanelBar` window style. It can be one of the

 ========================== =========== ==================================================
 Window Styles              Hex Value   Description
 ``FPB_SINGLE_FOLD``                0x1 Single fold forces other panels to close when they are open, and only opens the current panel. This will allow the open panel to gain the full size left in the client area.
 ``FPB_COLLAPSE_TO_BOTTOM``         0x2 All panels are stacked to the bottom. When they are expanded again they show up at the top.
 ``FPB_EXCLUSIVE_FOLD``             0x4 ``FPB_SINGLE_FOLD`` style plus the panels will be stacked at the bottom.
 ``FPB_HORIZONTAL``                 0x4 :class:`FoldPanelBar` will be horizontal.
 ``FPB_VERTICAL``                   0x8 :class:`FoldPanelBar` will be vertical.

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.TAB_TRAVERSAL|wx.NO_BORDER, agwStyle=0)

Adds a fold panel to the list of panels.

:param `caption`: the caption to be displayed in the associated :class:`CaptionBar`;
:param `collapsed`: if set to ``True``, the panel is collapsed initially;
:param `cbstyle`: an instance of :class:`CaptionBarStyle`.

:note: The FoldPanel item which is returned, can be used as a reference to perform
 actions upon the fold panel like collapsing it, expanding it, or deleting it
 from the list. Use this foldpanel to add windows to it.

:see: :meth:`~FoldPanelBar.AddFoldPanelWindow` and :meth:`~FoldPanelBar.AddFoldPanelSeparator` to see how to add
 items derived from :class:`wx.Window` to the panels.

AddFoldPanel(self, caption="", collapsed=False, foldIcons=None, cbstyle=None)

Adds a separator line to the current fold panel.

The separator is a simple line which is drawn and is no real
component. It can be used to separate groups of controls
which belong to each other.

:param `colour`: the separator colour, an instance of :class:`wx.Colour`;
:param `spacing`: the separator to be added can be slightly indented from
 left and right so it is more visibly placed in the fold panel. Use `spacing` > 0
 to give the control an y offset from the previous :class:`wx.Window` added;
:param `leftSpacing`: give the added separator a slight indent from the left;
:param `rightSpacing`: give the added separator a slight indent from the right.

AddFoldPanelSeparator(self, panel, colour=wx.BLACK, spacing=FPB_DEFAULT_SPACING, leftSpacing=FPB_DEFAULT_LEFTLINESPACING, rightSpacing=FPB_DEFAULT_RIGHTLINESPACING)

Adds a :class:`wx.Window` derived instance to the referenced fold panel.

:param `panel`: an instance of :class:`FoldPanelItem`;
:param `window`: the window we wish to add to the fold panel, an instance
 of :class:`wx.Window`;
:param `flags`: can be one of the following bits:

 ====================== ======= ====================================
 Align Flag              Value  Description
 ``FPB_ALIGN_WIDTH``          1 The :class:`wx.Window` to be added will be aligned to fit the width of the FoldPanel when it is resized. Very handy for sizer items, buttons and text boxes.
 ``FPB_ALIGN_LEFT``           0 Aligns left instead of fitting the width of the child window to be added. Use either this one or ``FPB_ALIGN_WIDTH``.

:param `spacing`: the :class:`wx.Window` to be added can be slightly indented from
:param `leftSpacing`: give the :class:`wx.Window` added a slight indent from the left;
:param `rightSpacing`: give the :class:`wx.Window` added a slight indent from the right;

:note: Make the window be a child of the fold panel!

 The following example adds a FoldPanel to the :class:`FoldPanelBar` and
 adds two :class:`wx.Window` derived controls to the FoldPanel::

       # Create the FoldPanelBar
       m_pnl = FoldPanelBar(self, wx.ID_ANY, wx.DefaultPosition, wx.DefaultSize, agwStyle=0x2)

       # Add a foldpanel to the control. "Test me" is the caption and it is
       # initially not collapsed.
       item = m_pnl.AddFoldPanel("Test me", False)

       # Now add a button to the fold panel. Mind that the button should be
       # made child of the FoldPanel and not of the main form.
       m_pnl.AddFoldPanelWindow(item, wx.Button(item, ID_COLLAPSEME, "Collapse Me"))

       # Add a separator between the two controls. This is purely a visual
       # line that can have a certain colour and also the indents and width
       # aligning like a control.
       m_pnl.AddFoldPanelSeparator(item)

       # Now add a text ctrl. Also very easy. Align this on width so that
       # when the control gets wider the text control also sizes along.
       m_pnl.AddFoldPanelWindow(item, wx.TextCtrl(item, wx.ID_ANY, "Comment"), FPB_ALIGN_WIDTH, FPB_DEFAULT_SPACING, 20)

AddFoldPanelWindow(self, panel, window, flags=FPB_ALIGN_WIDTH, spacing=FPB_DEFAULT_SPACING, leftSpacing=FPB_DEFAULT_LEFTLINESPACING, rightSpacing=FPB_DEFAULT_RIGHTLINESPACING)

Sets the style of the caption bar (:class:`CaptionBar`) of the fold panel.

:param `foldpanel`: an instance of :class:`FoldPanelItem`;

:note:

 The changes are applied immediately. All styles not set in the
 :class:`CaptionBarStyle` class are not applied. Use the :class:`CaptionBar` reference
 to indicate what captionbar you want to apply the style to. To apply one
 style to all :class:`CaptionBar` items, use :meth:`~FoldPanelBar.ApplyCaptionStyleAll`.

Sets the style of all the caption bars of the fold panel.
The changes are applied immediately.

Collapses the given fold panel reference, and updates the foldpanel bar.

:param `foldpanel`: an instance of :class:`FoldPanelItem`.

:note: With the ``FPB_COLLAPSE_TO_BOTTOM`` style set, all collapsed captions
 are put at the bottom of the control. In the normal mode, they stay where
 they are.

Expands the given fold panel reference, and updates the foldpanel bar.

:note: With the ``FPB_COLLAPSE_TO_BOTTOM`` style set, they will be removed
 from the bottom and the order where the panel originally was placed is
 restored.

Returns the currently used caption style for the fold panel.

It is returned as a :class:`CaptionBarStyle` class. After modifying it, it can
be set again.

Returns the panel associated with the index `item`.

:param `item`: an integer representing the :class:`FoldPanelItem` in the list of
 panels in this :class:`FoldPanelBar`.

Returns the length of the panels that are expanded and
collapsed.

:param `collapsed`: the current value of the collapsed panels;
:param `expanded`: the current value of the expanded panels.

:note: This is useful to determine quickly what size is used to display,
 and what is left at the bottom (right) to align the collapsed panels.

Returns whether the :class:`CaptionBar` has default orientation or not.

Handles the ``wx.EVT_CAPTIONBAR`` event for :class:`CaptionBar`.

:param `event`: a :class:`CaptionBarEvent` event to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`FoldPanelBar`.

Refreshes all the panels from given one down to last one.

:param `item`: the first :class:`FoldPanelItem` to be refreshed.

Repositions all the collapsed panels to the bottom.

When it is not possible to align them to the bottom, stick them behind
the visible panels.

This class is a child sibling of the :class:`FoldPanelBar` class. It will
contain a :class:`CaptionBar` class for receiving of events, and a the
rest of the area can be populated by a :class:`Panel` derived class.

:param `parent`: the :class:`FoldPanelItem` parent window;
 :class:`CaptionBarStyle`.

__init__(self, parent, id=wx.ID_ANY, caption="", foldIcons=None, collapsed=False, cbstyle=None)

Adds a separator item to the list of items on this panel.

AddSeparator(self, colour=wx.BLACK, spacing=FPB_DEFAULT_SPACING, leftSpacing=FPB_DEFAULT_LEFTSPACING, rightSpacing=FPB_DEFAULT_RIGHTSPACING)

Adds a window item to the list of items on this panel.

:param `spacing`: reserves a number of pixels before the window element;
:param `leftSpacing`: an indent, in pixels;
:param `rightSpacing`: a right spacing, only relevant when the style
 ``FPB_ALIGN_WIDTH`` is chosen.

AddWindow(self, window, flags=FPB_ALIGN_WIDTH, spacing=FPB_DEFAULT_SPACING, leftSpacing=FPB_DEFAULT_LEFTLINESPACING, rightSpacing=FPB_DEFAULT_RIGHTLINESPACING)

Internal method.

This should not be called by the user, because it doesn't trigger the
parent  to tell it that we are collapsed or expanded, it only changes
visual state.

parent to tell it that we are collapsed or expanded, it only changes

Returns height of caption only. This is for folding calculation purposes. 

This can be used to change and set back the changes.

Returns expanded or collapsed status.  If the panel is
expanded, ``True`` is returned.

Handles the ``wx.EVT_PAINT`` event for :class:`FoldPanelItem`.

Handles the ``wx.EVT_CAPTIONBAR`` event for :class:`FoldPanelItem`.

Repositions this :class:`FoldPanelItem` and reports the length occupied
for the next :class:`FoldPanelItem` in the list.

:param `pos`: the new item position.

This class is a child sibling of the :class:`FoldPanelItem` class. It
will contain :class:`wx.Window` that can be either a separator (a coloured
line simulated by a :class:`wx.Window`) or a wxPython controls (such as a
:class:`Button`, a :class:`ListCtrl` etc...).

Default class constructor

:param `parent`: the :class:`FoldWindowItem` parent;
:param `window`: the window contained in this item.

:keyword `Type`: can be "WINDOW" or "SEPARATOR";
:keyword `lineColour`: the separator colour (meaningful for separators only);
:keyword `y`: the separator y position (meaningful for separators only);
:keyword `flags`: the alignment flags;
:keyword `spacing`: reserves a number of pixels before the window/separator element;
:keyword `leftSpacing`: an indent, in pixels;
:keyword `rightSpacing`: a right spacing, only relevant when the style

:see: :meth:`FoldPanelBar.AddFoldPanelWindow() <FoldPanelBar.AddFoldPanelWindow>` for a list of valid alignment flags.

Returns space needed by the window if type is :class:`FoldWindowItem`
"WINDOW" and returns the total size plus the extra spacing.

:param `vertical`: ``True`` if the parent :class:`FoldPanelBar` is in vertical
 mode.

Resizes the element, whatever it is.

A separator or line will be always aligned by width or height
depending on orientation of the whole panel.

:param `size`: the maximum size available for the :class:`FoldWindowItem`;
 mode.

<wx.lib.agw.foldpanelbar.CaptionBarStyle object at 0x7fe26a8ecb10>

:class:`~wx.lib.agw.fourwaysplitter.FourWaySplitter` is a layout manager which manages 4 children like 4 panes in a
window.

The :class:`FourWaySplitter` is a layout manager which manages four children like four
panes in a window. You can use a four-way splitter for example in a CAD program
where you may want to maintain three orthographic views, and one oblique view of
a model.

The :class:`FourWaySplitter` allows interactive repartitioning of the panes by
means of moving the central splitter bars. When the :class:`FourWaySplitter` is itself
resized, each child is proportionally resized, maintaining the same split-percentage.

The main characteristics of :class:`FourWaySplitter` are:

- Handles horizontal, vertical or four way sizing via the sashes;
- Delayed or live update when resizing;
- Possibility to swap windows;
- Setting the vertical and horizontal split fractions;
- Possibility to expand a window by hiding the onther 3.

And a lot more. See the demo for a complete review of the functionalities.

Usage
=====

    import wx
    import wx.lib.agw.fourwaysplitter as fws

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

            splitter = fws.FourWaySplitter(self, -1, agwStyle=wx.SP_LIVE_UPDATE)

            # Put in some coloured panels...
            for colour in [wx.RED, wx.WHITE, wx.BLUE, wx.GREEN]:

                panel = wx.Panel(splitter)
                panel.SetBackgroundColour(colour)

                splitter.AppendWindow(panel)

:class:`FourWaySplitter` has been tested on the following platforms:

``SP_NOSASH``             0x10 No sash will be drawn on :class:`FourWaySplitter`.
``SP_LIVE_UPDATE``        0x80 Don't draw XOR line but resize the child windows immediately.
``SP_3DBORDER``          0x200 Draws a 3D effect border.

================================== ==================================================
Event Name                         Description
``EVT_SPLITTER_SASH_POS_CHANGED``  The sash position was changed. This event is generated after the user releases the mouse after dragging the splitter. Processes a ``wx.wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED`` event.
``EVT_SPLITTER_SASH_POS_CHANGING`` The sash position is in the process of being changed. You may prevent this change from happening by calling `Veto` or you may also modify the position of the tracking bar to properly reflect the position that would be set if the drag were to be completed at this point. Processes a ``wx.wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING`` event.

:class:`FourWaySplitter` is distributed under the wxPython license.

# FOURWAYSPLITTER wxPython IMPLEMENTATION
#
#
#
# TODO List
#
# 1. Any idea?
#
#
#
#
#

This class is very similar to :class:`SplitterWindow` except that it
allows for four windows and two sashes.  Many of the same styles,
constants, and methods behave the same as in :class:`SplitterWindow`.
However, in addition of the ability to drag the vertical and the
horizontal sash, by dragging at the intersection between the two
sashes, it is possible to resize the four windows at the same time.

:note: These things are not yet supported:

 * Minimum pane size (minimum of what? Width? Height?);
 * Using negative sash positions to indicate a position offset from the end;
 * User controlled unsplitting with double clicks on the sash (but supported via the
   :meth:`FourWaySplitter.SetExpanded() <FourWaySplitter.SetExpanded>` method);
 * Sash gravity.

:param `agwStyle`: the AGW-specific window style. It can be a combination of the

 ================== =========== ==================================================
 Window Styles      Hex Value   Description
 ``SP_NOSASH``             0x10 No sash will be drawn on :class:`FourWaySplitter`.
 ``SP_LIVE_UPDATE``        0x80 Don't draw XOR line but resize the child windows immediately.
 ``SP_3DBORDER``          0x200 Draws a 3D effect border.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="FourWaySplitter")

Adjust layout of :class:`FourWaySplitter`. Mainly used to recalculate the
correct values for split fractions.

Add a new window to the splitter at the right side or bottom
of the window stack.

Removes the window from the stack of windows managed by the splitter. The
window will still exist so you should `Hide` or `Destroy` it as needed.

Sends a ``EVT_SPLITTER_SASH_POS_CHANGING`` event.

:param `pt`: the point at which the splitter is being positioned.

Actually draws the sashes.

Draws a fake sash in case we don't have ``wx.SP_LIVE_UPDATE`` style.

:param `x`: the `x` position of the sash;
:param `y`: the `y` position of the sash.

:note: This method relies on :class:`ScreenDC` which is currently unavailable on wxMac.

Trade the positions in the splitter of the two windows.

:param `window1`: an instance of :class:`wx.Window`;
:param `window2`: another instance of :class:`wx.Window`.

Returns the :class:`FourWaySplitter` window style.

:see: :meth:`~FourWaySplitter.SetAGWWindowStyleFlag` for a list of possible window styles.

Determines the split mode for :class:`FourWaySplitter`.

:param `pt`: the point at which the mouse has been clicked, an instance of
 :class:`wx.Point`.

:return: One of the following 3 split modes:

 ================= ==============================
 Split Mode        Description
 ``wx.HORIZONTAL`` the user has clicked on the horizontal sash
 ``wx.VERTICAL``   The user has clicked on the vertical sash
 ``wx.BOTH``       The user has clicked at the intersection between the 2 sashes

Returns the window at the index `idx`.

:param `idx`: the index at which the window is located.

Insert a new window into the splitter at the position given in `idx`.

:param `idx`: the index at which the window will be inserted;
:param `sashPos`: the sash position after the window insertion.

Moves the split accordingly to user action.

:param `x`: the new splitter `x` coordinate;
:param `y`: the new splitter `y` coordinate.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_MOTION`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_PAINT`` event for :class:`FourWaySplitter`.

Handles the ``wx.EVT_SIZE`` event for :class:`FourWaySplitter`.

Replaces `oldWindow` (which is currently being managed by the
splitter) with `newWindow`.  The `oldWindow` window will still
exist so you should `Hide` or `Destroy` it as needed.

:param `oldWindow`: an instance of :class:`wx.Window`;
:param `newWindow`: another instance of :class:`wx.Window`.

Sets the :class:`FourWaySplitter` window style flags.

This method is used to expand one of the four window to fill the
whole client size (when `expanded` >= 0) or to return to the four-window
view (when `expanded` < 0).

:param `expanded`: an integer >= 0 to expand a window to fill the whole
 client size, or an integer < 0 to return to the four-window view.

Change horizontal split fraction.

:param `s`: the split fraction, which is an integer value between 0 and
 10000 (inclusive), indicating how much space to allocate to the leftmost
 panes. For example, to split the panes at 35 percent, use::

    fourSplitter.SetHSplit(3500)

Change vertical split fraction.

 10000 (inclusive), indicating how much space to allocate to the topmost

    fourSplitter.SetVSplit(3500)

This event class is almost the same as :class:`SplitterEvent` except
it adds an accessor for the sash index that is being changed.  The
same event type IDs and event binders are used as with
:class:`SplitterEvent`.

:param `evtType`: the event type;
:param `splitter`: the associated :class:`FourWaySplitter` window.

This is the opposite of :meth:`~FourWaySplitterEvent.Veto`: it explicitly allows the event to be processed.

Returns the new sash position.

:note: May only be called while processing ``EVT_SPLITTER_SASH_POS_CHANGING``
 and ``EVT_SPLITTER_SASH_POS_CHANGED`` events.

Returns ``True`` if the change is allowed (:meth:`~FourWaySplitterEvent.Veto` hasn't been called) or

Sets the index of the sash currently involved in the event.

:param `idx`: an integer between 0 and 3, representing the index of the
 sash involved in the event.

In the case of ``EVT_SPLITTER_SASH_POS_CHANGED`` events, sets the new sash
position. In the case of ``EVT_SPLITTER_SASH_POS_CHANGING`` events, sets
the new tracking bar position so visual feedback during dragging will represent
that change that will actually take place. Set to -1 from the event handler
code to prevent repositioning.

:param `pos`: the new sash position.

This class is a possible, fancy replacement for :class:`MessageDialog`.

This class represents a dialog that shows a single or multi-line message,
with a choice of ``OK``, ``Yes``, ``No``, ``Cancel`` and ``Help`` buttons. It is a possible
replacement for the standard :class:`MessageDialog`, with these extra functionalities:

* Possibility to modify the dialog position;
* Custom themed generic bitmap & text buttons;
* Support for normal and extended message (in different fonts);
* Custom labels for the ``OK``, ``Yes``, ``No``, ``Cancel`` and ``Help`` buttons;
* Custom icons for the ``OK``, ``Yes``, ``No``, ``Cancel`` and ``Help`` buttons;
* Possibility to set an icon to the dialog;
* More visibility to the button getting the focus;
* Support for Aqua buttons or Gradient buttons instead of themed ones (see :class:`~wx.lib.agw.aquabutton.AquaButton`
  and :class:`~wx.lib.agw.gradientbutton.GradientButton`);
* Possibility to automatically wrap long lines of text;
* Good old Python code :-D .

Usage
=====

    import wx
    import wx.lib.agw.genericmessagedialog as GMD

    main_message = "Hello world! I am the main message."

    dlg = GMD.GenericMessageDialog(None, main_message, "A Nice Message Box",
                                   agwStyle=wx.ICON_INFORMATION | wx.OK)

    dlg.ShowModal()

:class:`GenericMessageDialog` has been tested on the following platforms:
  * Windows (Windows XP).

=========================== =========== ==================================================
Window Styles               Hex Value   Description
``GMD_DEFAULT``                     0x0 Uses generic buttons.
``GMD_USE_AQUABUTTONS``            0x20 Uses :mod:`lib.agw.aquabutton` buttons instead of generic buttons.
``GMD_USE_GRADIENTBUTTONS``        0x40 Uses :mod:`lib.agw.gradientbutton` buttons instead of generic buttons.

The styles above are mutually exclusive. The style chosen above can be combined with a
bitlist containing flags chosen from the following:

``wx.OK``                           0x4 Shows an ``OK`` button.
``wx.CANCEL``                      0x10 Shows a ``Cancel`` button.
``wx.YES_NO``                       0xA Show ``Yes`` and ``No`` buttons.
``wx.YES_DEFAULT``                  0x0 Used with ``wx.YES_NO``, makes ``Yes`` button the default - which is the default behaviour.
``wx.NO_DEFAULT``                  0x80 Used with ``wx.YES_NO``, makes ``No`` button the default.
``wx.ICON_EXCLAMATION``           0x100 Shows an exclamation mark icon.
``wx.ICON_HAND``                  0x200 Shows an error icon.
``wx.ICON_ERROR``                 0x200 Shows an error icon - the same as ``wx.ICON_HAND``.
``wx.ICON_QUESTION``              0x400 Shows a question mark icon.
``wx.ICON_INFORMATION``           0x800 Shows an information icon.

:class:`GenericMessageDialog` is distributed under the wxPython license.

Version 0.8

# GENERICMESSAGEDIALOG wxPython IMPLEMENTATION
#
#
#
# TODO List
#
# 1) ?
#
#
#
#
#
#

Main class implementation, :class:`GenericMessageDialog` is a possible replacement
for the standard :class:`MessageDialog`.

Default class constructor. Use :meth:`~GenericMessageDialog.ShowModal` to show the dialog.

:param `parent`: the :class:`GenericMessageDialog` parent (if any);
:param `message`: the message in the main body of the dialog;
:param `caption`: the dialog title;
:param `agwStyle`: the AGW-specific dialog style; it can be one of the

 ``GMD_DEFAULT``                       0 Uses normal generic buttons
 ``GMD_USE_AQUABUTTONS``            0x20 Uses :class:`~wx.lib.agw.aquabutton.AquaButton` buttons instead of generic buttons.
 ``GMD_USE_GRADIENTBUTTONS``        0x40 Uses :class:`~wx.lib.agw.gradientbutton.GradientButton` buttons instead of generic buttons.

 The styles above are mutually exclusive. The style chosen above can be combined with a
 bitlist containing flags chosen from the following:

 ``wx.OK``                           0x4 Shows an ``OK`` button.
 ``wx.CANCEL``                      0x10 Shows a ``Cancel`` button.
 ``wx.YES_NO``                       0xA Show ``Yes`` and ``No`` buttons.
 ``wx.YES_DEFAULT``                  0x0 Used with ``wx.YES_NO``, makes ``Yes`` button the default - which is the default behaviour.
 ``wx.NO_DEFAULT``                  0x80 Used with ``wx.YES_NO``, makes ``No`` button the default.
 ``wx.ICON_EXCLAMATION``           0x100 Shows an exclamation mark icon.
 ``wx.ICON_HAND``                  0x200 Shows an error icon.
 ``wx.ICON_ERROR``                 0x200 Shows an error icon - the same as ``wx.ICON_HAND``.
 ``wx.ICON_QUESTION``              0x400 Shows a question mark icon.
 ``wx.ICON_INFORMATION``           0x800 Shows an information icon.

:param `pos`: the dialog position on screen;
:param `size`: the dialog size;
:param `style`: the underlying :class:`Dialog` style;
:param `wrap`: if set greater than zero, wraps the string in `message` so that
 every line is at most `wrap` pixels long.

:note: Notice that not all styles are compatible: only one of ``wx.OK`` and ``wx.YES_NO`` may be
 specified (and one of them must be specified) and at most one default button style can be used
 and it is only valid if the corresponding button is shown in the message box.

__init__(self, parent, message, caption, agwStyle, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE | wx.WANTS_CHARS, wrap=-1)

Creates a sizer with standard buttons.

:param `flags`: a bit list of the following flags:

 ================= ========= ==========================
 Flags             Hex Value Description
 ``wx.YES``              0x2 Show a ``Yes`` button
 ``wx.OK``               0x4 Show an ``OK`` button
 ``wx.NO``               0x8 Show a ``No`` button
 ``wx.CANCEL``          0x10 Show a ``Cancel`` button
 ``wx.NO_DEFAULT``      0x80 Used with ``wx.YES`` and ``wx.NO``, makes ``No`` button the default
 ``wx.HELP``          0x8000 Show a ``Help`` button

:note: The sizer lays out the buttons in a manner appropriate to the platform.

Actually creates the :class:`GenericMessageDialog`, just before showing it on screen. 

Creates a sizer with standard buttons using :meth:`~GenericMessageDialog.CreateButtonSizer` separated
from the rest of the dialog contents by a horizontal :class:`StaticLine`.

:param `flags`: the button sizer flags.

:see: :meth:`~GenericMessageDialog.CreateButtonSizer` for a list of valid flags.

Creates a :class:`StdDialogButtonSizer` with standard buttons.

Ends the :class:`GenericMessageDialog` life. This will be done differently depending on
the dialog modal/non-modal behaviour.

:param `rc`: one of the ``wx.ID_YES``, ``wx.ID_NO``, ``wx.ID_OK``, ``wx.ID_CANCEL`` constants.

:note: the `rc` parameter is unused if the dialog is not modal.

Returns the main caption (the title) for :class:`GenericMessageDialog`.

If a custom icon been used for the ``Cancel`` button, this method will return
it as an instance of :class:`wx.Bitmap`. Otherwise, the default one (as defined in
:meth:`~GenericMessageDialog.GetDefaultCancelBitmap`) is returned.

If a custom label has been used for the ``Cancel`` button, this method will return
it as a string. Otherwise, the default one (as defined in :meth:`~GenericMessageDialog.GetDefaultCancelLabel`)
is returned.

If a custom icon has been used for the ``Help`` button, this method will return
:meth:`~GenericMessageDialog.GetDefaultHelpBitmap`) is returned.

If a custom label has been used for the ``Help`` button, this method will return
it as a string. Otherwise, the default one (as defined in :meth:`~GenericMessageDialog.GetDefaultHelpLabel`)

If a custom icon has been used for the ``No`` button, this method will return
:meth:`~GenericMessageDialog.GetDefaultNoBitmap`) is returned.

If a custom label has been used for the ``No`` button, this method will return
it as a string. Otherwise, the default one (as defined in :meth:`~GenericMessageDialog.GetDefaultNoLabel`)

If a custom icon has been used for the ``OK`` button, this method will return
:meth:`~GenericMessageDialog.GetDefaultOKBitmap`) is returned.

If a custom label has been used for the ``OK`` button, this method will return
it as a string. Otherwise, the default one (as defined in :meth:`~GenericMessageDialog.GetDefaultOKLabel`)

If a custom icon has been used for the ``Yes`` button, this method will return
:meth:`~GenericMessageDialog.GetDefaultYesBitmap`) is returned.

If a custom label has been used for the ``Yes`` button, this method will return
it as a string. Otherwise, the default one (as defined in :meth:`~GenericMessageDialog.GetDefaultYesLabel`)

Returns the default icon for the ``Cancel`` button.

:note: this method may be overridden to provide different defaults for the
 default button icons.

Returns the default label for the ``Cancel`` button.

 default button labels.

Returns the default icon for the ``Help`` button.

Returns the default label for the ``Help`` button.

Returns the default icon for the ``No`` button.

Returns the default label for the ``No`` button.

Returns the default icon for the ``OK`` button.

Returns the default label for the ``OK`` button.

Returns the default icon for the ``Yes`` button.

Returns the default label for the ``Yes`` button.

Returns a string representing the extended :class:`GenericMessageDialog` message.

Returns a string representing the combination of the main :class:`GenericMessageDialog`
message and the extended message, separated by an empty line.

Returns a string representing the main :class:`GenericMessageDialog` message.

Returns the AGW-specific window style for :class:`GenericMessageDialog`.

Returns ``True`` if any of the buttons have a non-default icons.

Returns ``True`` if any of the buttons have a non-default label.

:class:`GenericMessageDialog` had received a ``wx.ID_CANCEL`` answer. 

:class:`GenericMessageDialog` had received a ``wx.ID_HELP`` answer. 

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`GenericMessageDialog`.

Handles the ``wx.EVT_NAVIGATION_KEY`` event for :class:`GenericMessageDialog`.

:class:`GenericMessageDialog` had received a ``wx.ID_NO`` answer. 

:class:`GenericMessageDialog` had received a ``wx.ID_OK`` answer. 

:class:`GenericMessageDialog` had received a ``wx.ID_YES`` answer. 

Sets the extended message for the dialog: this message is usually an extension of the
short message specified in the constructor or set with :meth:`~GenericMessageDialog.SetMessage`.

If it is set, the main message appears highlighted and this message appears beneath
it in normal font.

:param `extendedMessage`: a string representing the extended :class:`GenericMessageDialog` message.

Overrides the default icon of the ``Help`` button.

:param `helpBitmap`: the new icon for the ``Help`` button, an instance of :class:`wx.Bitmap`.

Overrides the default label of the ``Help`` button.

:param `help`: the new label for the ``Help`` button.

:see: The remarks in the :meth:`~GenericMessageDialog.SetYesNoLabels` documentation.

Sets the message shown by the dialog.

:param `message`: a string representing the main :class:`GenericMessageDialog` message.

Overrides the default icon of the ``OK`` button.

:param `yesBitmap`: the new icon for the ``OK`` button, an instance of :class:`wx.Bitmap`;

Overrides the default icons of the ``OK`` and ``Cancel`` buttons.

:param `okBitmap`: the new icon for the ``OK`` button, an instance of :class:`wx.Bitmap`;
:param `cancelBitmap`: the new icon for the ``Cancel`` button, an instance of :class:`wx.Bitmap`.

Overrides the default labels of the ``OK`` and ``Cancel`` buttons.

:param `ok`: the new label for the ``OK`` button;
:param `cancel`: the new label for the ``Cancel`` button.

Overrides the default label of the ``OK`` button.

:param `ok`: the new label for the ``OK`` button.

Overrides the default icons of the ``Yes`` and ``No`` buttons.

:param `yesBitmap`: the new icon for the ``Yes`` button, an instance of :class:`wx.Bitmap`;
:param `noBitmap`: the new icon for the ``No`` button, an instance of :class:`wx.Bitmap`.

:param `noBitmap`: the new icon for the ``No`` button, an instance of :class:`wx.Bitmap`;

Overrides the default labels of the ``Yes`` and ``No`` buttons.

:param `yes`: the new label for the ``Yes`` button;
:param `no`: the new label for the ``No`` button;

:param `no`: the new label for the ``No`` button.

Typically, if the function was used successfully, the main dialog message may need to be changed, e.g.::

    dlg = GenericMessageDialog(None, main_message, "A Nice Message Box",
                               agwStyle=wx.ICON_INFORMATION | wx.OK)

    if dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")):
        dlg.SetMessage(_("What do you want to do?"))

    else: # buttons have standard "Yes"/"No" values, so rephrase the question
        dlg.SetMessage(_("Do you really want to quit?"))

Shows the dialog, returning one of ``wx.ID_OK``, ``wx.ID_CANCEL``, ``wx.ID_YES``,
``wx.ID_NO`` or ``wx.ID_HELP``.

:note: Notice that this method returns the identifier of the button which was
 clicked unlike the :class:`MessageBox` () function.

:note: Reimplemented from :class:`Dialog`.

Wraps the input message to multi lines so that the resulting new message
is at most `wrap` pixels wide.

:param `message`: the original input message;
:param `wrap`: wraps the string in `message` so that every line is at most
 `wrap` pixels long;
:param `font`: if not ``None``, it should be an instance of :class:`wx.Font` to be
 used to measure and then wrap the input `message`.

:return: a new message wrapped at maximum `wrap` pixels wide.

:todo: Establish if wrapping all messages by default is a better idea than
 provide a keyword parameter to :class:`GenericMessageDialog`. A default maximum
 line width might be the wxMac one, at 360 pixels.

Add a button to the sizer.

:param `mybutton`: the button to add.

Sets the affirmative button.

:param `button`: the button to set as affirmative one.

Sets the cancel button.

:param `button`: the button to set as cancel one.

Sets the negative button.

:param `button`: the button to set as negative one.

:class:`~wx.lib.agw.gradientbutton.GradientButton` is another custom-drawn button class which mimics Windows CE mobile
gradient buttons.

:class:`GradientButton` is another custom-drawn button class which mimics Windows CE mobile
gradient buttons, using a tri-vertex blended gradient plus some ClearType bold
font (best effect with Tahoma Bold). :class:`GradientButton` supports:

* Triple blended gradient background, with customizable colours;
* Custom colours for the "pressed" state;
* Text-only or image+text buttons.

Usage
=====

    import wx
    import wx.lib.agw.gradientbutton as GB

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

            # One button without bitmap
            button_1 = GB.GradientButton(panel, -1, None, "Hello World", (100, 50))

            # One button with bitmap
            my_bitmap = wx.Bitmap("my_bitmap.png", wx.BITMAP_TYPE_PNG)
            button_2 = GB.GradientButton(panel, -1, my_bitmap, "GradientButton", (100, 150))

:class:`GradientButton` has been tested on the following platforms:

:class:`GradientButton` is distributed under the wxPython license.

# GRADIENTBUTTON wxPython IMPLEMENTATION
#
#
#
# TODO List
#
#
#
#
#
#
#

This is the main class implementation of :class:`GradientButton`. 

:param `parent`: the :class:`GradientButton` parent;
:param `bitmap`: the button bitmap (if any);
:param `label`: the button text label;
:param `style`: the button style (unused);
:param `align`: text/bitmap alignment. wx.CENTER or wx.LEFT;
:param `validator`: the validator associated to the button;
:param `name`: the button name.

__init__(self, parent, id=wx.ID_ANY, bitmap=None, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, align=wx.CENTER, validator=wx.DefaultValidator, name="gradientbutton")

:param `enable`: ``True`` to enable the button, ``False`` to disable it.

:param `rc`: a client rectangle;
:param `r`: the radious of the rounded part of the rectangle.

Returns the pressed bottom start colour for the gradient shading. 

:param `colour`: the input colour to be brightened;
:param `percent`: determines how light the colour will be. `percent` = 100
 returns white, `percent` = 0 returns `colour`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`GradientButton`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`GradientButton`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`GradientButton`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`GradientButton`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`GradientButton`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`GradientButton`.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`GradientButton`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`GradientButton`.

Handles the ``wx.EVT_PAINT`` event for :class:`GradientButton`.

Handles the ``wx.EVT_SIZE`` event for :class:`GradientButton`.

Sets the bottom, top, pressed and foreground colour

:param startcolour: based colour to be used for bottom, top and pressed
:param foregroundcolour: colour used for the text

SetBaseColours(self, startcolour=wx.BLACK, foregroundcolour=wx.WHITE)

Sets the bottom end colour for the gradient shading.

Sets the top bottom colour for the gradient shading.

Sets the :class:`GradientButton` foreground (text) colour.

:param `size`: an instance of :class:`wx.Size`.

Sets the pressed bottom start colour for the gradient shading.

Sets the pressed top start colour for the gradient shading.

Sets the top end colour for the gradient shading.

Sets the top start colour for the gradient shading.

Event sent from :class:`GradientButton` when the button is activated. 

:param `eventId`: the event identifier.

:param `btn`: the button object, an instance of :class:`GradientButton`.

:class:`~wx.lib.agw.hyperlink.HyperLinkCtrl` is a control for wxPython that acts like a hyper link
in a typical browser.

:class:`HyperLinkCtrl` is a control for wxPython that acts like a hyper link
in a typical browser. Latest features include the ability to capture
your own left, middle, and right click events to perform your own
custom event handling and ability to open link in a new or current
browser window.

Special thanks to Robin Dunn for the event binder for the 3 mouse buttons.

Usage
=====

    import wx
    import wx.lib.agw.hyperlink as hl

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

            # Default Web links:
            hyper1 = hl.HyperLinkCtrl(panel, -1, "wxPython Main Page", pos=(100, 100),
                                      URL="http://www.wxpython.org/")

            # Web link with underline rollovers, opens in same window
            hyper2 = hl.HyperLinkCtrl(panel, -1, "My Home Page", pos=(100, 150),
                                      URL="http://xoomer.virgilio.it/infinity77/")

            hyper2.AutoBrowse(False)
            hyper2.SetColours("BLUE", "BLUE", "BLUE")
            hyper2.EnableRollover(True)
            hyper2.SetUnderlines(False, False, True)
            hyper2.SetBold(True)
            hyper2.OpenInSameWindow(True)
            hyper2.SetToolTip(wx.ToolTip("Hello World!"))
            hyper2.UpdateLink()

======================== ==================================================
Event Name               Description
``EVT_HYPERLINK_LEFT``   Responds to a left mouse button event. Sent when the left mouse button is clicked, but only if `AutoBrowse` is set to ``False``.
``EVT_HYPERLINK_MIDDLE`` Responds to a middle mouse button event. Sent when the middle mouse button is clicked.
``EVT_HYPERLINK_RIGHT``  Handles a right mouse button event. Sent when the right mouse button is clicked, but only if `DoPopup` is set to ``False``.

:class:`HyperLinkCtrl` is distributed under the wxPython license.

Version 0.7

# HYPERLINKSCTRL wxPython IMPLEMENTATION
# Ported From Angelo Mandato C++ Code By:
#
# Andrea Gavana, @ 27 Mar 2005
#
#
# Original Web Site (For The C++ Code):
#
# http://www.spaceblue.com/codedetail.php?CodeID=7
#
#
# Thanks to E. A. Tacao for his nice suggestions and improvements of the code.
#
#
#
#
#

:class:`GenStaticText` is a generic implementation of :class:`wx.StaticText`.

:param integer `ID`: window identifier. A value of -1 indicates a default value;
:param string `label`: the static text label (i.e., its text label);

__init__(self, parent, ID=-1, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="genstattext")

.. note:: This is functionally equivalent of calling :meth:`~wx.Control.Enable`
   with a ``False`` flag.

Overridden base class virtual.  Determines the best size of
the control based on the label size and the current font.

Enable or disable the widget for user input.

:param bool `enable`: If ``True``, enables the window for input. If
  ``False``, disables the window.

:returns: ``True`` if the window has been enabled or disabled,
  ``False`` if nothing was done, i.e. if the window had already been
  in the specified state.

.. note:: Note that when a parent window is disabled, all of its
   children are disabled as well and they are re-enabled again when
   the parent is.

Overridden base class virtual.  By default we should use
the same font/colour attributes as the native :class:`wx.StaticText`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`GenStaticText`.

:param `event`: a :class:`wx.EraseEvent` event to be processed.

.. note:: This is intentionally empty to reduce flicker.

Handles the ``wx.EVT_PAINT`` for :class:`GenStaticText`.

Sets the static text font and updates the control's size to exactly
fit the label unless the control has ``wx.ST_NO_AUTORESIZE`` flag.

:param wx.Font `font`: a valid font instance, which will be the new font used
 to display the text.

Sets the static text label and updates the control's size to exactly

:param string `label`: the static text label (i.e., its text label).

Overridden base class virtual.  If the parent has non-default
colours then we want this control to inherit them.

:class:`HyperLinkCtrl` is a control for wxPython that acts like a hyper
link in a typical browser. Latest features include the ability to
capture your own left, middle, and right click events to perform
your own custom event handling and ability to open link in a new
or current browser window.

:param `parent`: the window parent. Must not be ``None``;
:param `label`: the control label;
:param `name`: the window name;
:param `URL`: a string specifying the url link to navigate to.

:note: Pass URL="" to use the label as the url link to navigate to.

__init__(self, parent, id=-1, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="staticText", URL="")

Automatically browse to URL when clicked.

:param `AutoBrowse`: ``True`` to automatically browse to an URL when clicked,

:note: Set `AutoBrowse` to ``False`` to receive ``EVT_HYPERLINK_LEFT`` events.

Displays an error message (according to the `ReportErrors` parameter) in a
:class:`MessageBox`.

:param `ErrorMessage`: a string representing the error to display;
:param `ReportErrors`: ``True`` to display error dialog if an error occurs
 navigating to the URL.

Sets whether to show popup menu on right click or not.

:param `DoPopup`: ``True`` to show a popup menu on right click, ``False`` otherwise.

Enable/disable rollover.

:param `EnableRollover`: ``True`` to enable text effects during rollover,
 ``False`` to disable them.

Returns whether the :class:`HyperLinkCtrl` has text in bold or not. 

Gets the colours for the link, the visited link and the mouse
rollover.

Returns if link is underlined, if the mouse rollover is
underlined and if the visited link is underlined.

Goto the specified URL.

:param `URL`: the url link we wish to navigate;
:param `ReportErrors`: Use ``True`` to display error dialog if an error
 occurs navigating to the URL;
:param `NotSameWinIfPossible`: Use ``True`` to attempt to open the URL
 in new browser window.

GotoURL(self, URL, ReportErrors=True, NotSameWinIfPossible=False)

Handles the ``wx.EVT_MOUSE_EVENTS`` events for :class:`HyperLinkCtrl`.

Handles the ``wx.EVT_MENU`` event for :class:`HyperLinkCtrl`.

:note: This method copies the data from the :class:`HyperLinkCtrl` to the clipboard.

Open multiple URL in the same window (if possible).

:param `NotSameWinIfPossible`: ``True`` to open an hyperlink in a new browser
 window, ``False`` to use an existing browser window.

Set whether to report browser errors or not.

Sets the :class:`HyperLinkCtrl` label in bold text.

:param `Bold`: ``True`` to set the :class:`HyperLinkCtrl` label as bold, ``False``

Sets the colours for the link, the visited link and the mouse rollover.

- Visited link: VIOLET
- Rollover: BLUE

:param `link`: a valid :class:`wx.Colour` to use as text foreground for new links
 (default=RED);
:param `visited`: a valid :class:`wx.Colour` to use as text foreground for visited
 links (default=VIOLET);
:param `rollover`: a valid :class:`wx.Colour` to use as text foreground for links
 rollovers (default=BLUE).

SetColours(self, link=wx.BLUE, visited=wx.Colour(79, 47, 79), rollover=wx.BLUE)

Sets link cursor properties.

:param `cur`: an integer representing a :ref:`Cursor` constant.

Sets whether the text should be underlined or not for new links, visited
links and rollovers.

:param `link`: ``True`` to set the text of new links as underlined, ``False``
:param `visited`: ``True`` to set the text of visited links as underlined,
:param `rollover`: ``True`` to set the text of rollovers as underlined,

Sets the :class:`HyperLinkCtrl` text to the specified URL.

:param `URL`: the new URL associated with :class:`HyperLinkCtrl`.

Sets a link as visited.

:param `Visited`: ``True`` to set a link as visited, ``False`` otherwise.

Updates the link, changing text properties if:

- User specific setting;
- Link visited;
- New link;

:param `OnRefresh`: ``True`` to refresh the control, ``False`` otherwise.

Event object sent in response to clicking on a :class:`HyperLinkCtrl`.

Sets the event position.

:param `pos`: an instance of :class:`wx.Point`.

The ``hypertreelist`` module contains the :class:`~wx.lib.agw.hypertreelist.HyperTreeList` class
that combines the multicolumn features of a :class:`wx.ListCtrl` in report mode
with the hierarchical features of a :class:`wx.TreeCtrl`. Although it looks
more like a :class:`wx.ListCtrl`, the API tends to follow the API of
:class:`wx.TreeCtrl`.

The :class:`~wx.lib.agw.hypertreelist.HyperTreeList` class actually consists of
two sub-windows:

* :class:`TreeListHeaderWindow` displays the column headers.
* :class:`TreeListMainWindow` is the main tree list based off :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`.

These widgets can be obtained by the :meth:`~HyperTreeList.GetHeaderWindow`
and :meth:`~HyperTreeList.GetMainWindow` methods respectively although this
shouldn't be needed in normal usage because most of the methods of the
sub-windows are monkey-patched and can be called directly from the
:class:`~wx.lib.agw.hypertreelist.HyperTreeList` itself.

:class:`HyperTreeList` was originally inspired from the
``wx.gizmos.TreeListCtrl`` class from Classic wxPython. Now in Phoenix the old
wrapped C++ ``wxTreeListCtrl`` class is gone and this class can be used in its
place. In addition to the features of the old ``wx.gizmos.TreeListCtrl`` this
class supports:

* RadioButton-type items: since I elected to put radiobuttons in
  :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`, I needed some way to handle
  them that made sense. So, I used the following approach:

    inactive.

  hovering;
* Multiline text items;
* Whatever non-toplevel widget can be attached next to a tree item;
* Whatever non-toplevel widget can be attached next to a list item;
* Column headers are fully customizable in terms of icons, colour, font, alignment etc...;
* Customized drag and drop images built on the fly (see :mod:`~wx.lib.agw.customtreectrl` for more info);
* Setting the :class:`HyperTreeList` item buttons to a personalized imagelist;
* Setting the :class:`HyperTreeList` check/radio item icons to a personalized imagelist;
* Using an image as a :class:`HyperTreeList` background (currently only in "tile" mode);

:class:`HyperTreeList` supports all the :mod:`~wx.lib.agw.customtreectrl` styles, except:

- ``TR_EXTENDED``: supports for this style is on the todo list (Am I sure of this?).

And a style useful to hide the TreeListCtrl header:

- ``TR_NO_HEADER``: hides the :class:`HyperTreeList` header.

And a style related to long items (with a lot of text in them), which can be
ellipsized:

  :class:`HyperTreeList` is low (`New in version 0.9.3`).

Please note that most TreeCtrl-like APIs are available in this class, although
they may not be visible to IDEs or other tools as they are automatically
delegated to the :class:`CustomTreeCtrl` or other helper classes.

Usage
=====

    import wx
    import wx.lib.agw.hypertreelist as HTL

        def __init__(self):
            wx.Frame.__init__(self, None, title="HyperTreeList Demo")

            tree = HTL.HyperTreeList(self, agwStyle=wx.TR_DEFAULT_STYLE |
                                     HTL.TR_ELLIPSIZE_LONG_ITEMS)
            tree.AddColumn("Tree Column", width=200)
            tree.AddColumn("Column 1", width=200, flag=wx.ALIGN_LEFT)
            root = tree.AddRoot("Root")

            parent = tree.AppendItem(root, "First child")
            tree.SetItemText(parent, "Child of root", column=1)
            
            child = tree.AppendItem(parent, "First Grandchild")
            tree.SetItemText(child, "Column1 Text", column=1)

            child2 = tree.AppendItem(root, "Second child")
            button = wx.Button(tree.GetMainWindow(), label="Button1")
            tree.SetItemWindow(child2, button, column=1)

    app = wx.App(redirect=False)
    locale = wx.Locale(wx.LANGUAGE_DEFAULT)
    frame = MyFrame()

Events
======

All the events supported by :mod:`~wx.lib.agw.customtreectrl` are also
available in :class:`HyperTreeList`, with a few exceptions:

Plus, :class:`HyperTreeList` supports the events related to the checkbutton-type items:

:class:`HyperTreeList` has been tested on the following platforms:
  * Windows
  * Linux
  * Mac

The :class:`HyperTreeList` class takes a regular wxPython ``style`` and an
extended ``agwStyle``. The ``style`` can be used with normal wxPython styles
such as ``wx.WANTS_CHARS`` while the ``agwStyle`` specifies the behavior of the
tree itself. It supports the following ``agwStyle`` flags:

**wx.TR_DEFAULT_STYLE**              *varies* The set of flags that are closest to the defaults for the native control for a particular toolkit. Should always be used.
**Styles from hypertreelist:**
``TR_COLUMN_LINES``                    0x1000 Use this style to draw a contrasting border between displayed columns.
``TR_ALIGN_WINDOWS``                  0x20000 Has no effect in HyperTreeList.
``TR_NO_HEADER``                      0x40000 Use this style to hide the columns header.
``TR_ELLIPSIZE_LONG_ITEMS``           0x80000 Flag used to ellipsize long items when the horizontal space for :class:`HyperTreeList` columns is low.
``TR_VIRTUAL``                       0x100000 :class:`HyperTreeList` will have virtual behaviour.

See :mod:`~wx.lib.agw.customtreectrl` for more information on styles.

This class processes the following events, Note that these are the same events as ``wx.ListCtrl`` and ``wx.TreeCtrl``:

``EVT_LIST_COL_BEGIN_DRAG``    The user started resizing a column - can be vetoed.
``EVT_LIST_COL_CLICK``         A column has been left-clicked.
``EVT_LIST_COL_DRAGGING``      The divider between columns is being dragged.
``EVT_LIST_COL_END_DRAG``      A column has been resized by the user.
``EVT_LIST_COL_RIGHT_CLICK``   A column has been right-clicked.
``EVT_TREE_BEGIN_DRAG``        Begin dragging with the left mouse button. See :mod:`wx.lib.agw.customtreectrl` Drag/Drop section for more information.
``EVT_TREE_BEGIN_LABEL_EDIT``  Begin editing a label. This can be prevented by calling :meth:`TreeEvent.Veto() <lib.agw.customtreectrl.TreeEvent.Veto>`.
``EVT_TREE_END_LABEL_EDIT``    End editing a label. This can be prevented by calling :meth:`TreeEvent.Veto() <lib.agw.customtreectrl.TreeEvent.Veto>`.
``EVT_TREE_GET_INFO``          Request information from the application (not implemented in :class:`HyperTreeList`).
``EVT_TREE_ITEM_COLLAPSING``   The item is being collapsed. This can be prevented by calling :meth:`TreeEvent.Veto() <lib.agw.customtreectrl.TreeEvent.Veto>`.
``EVT_TREE_ITEM_EXPANDED``     The item has been expanded.s
``EVT_TREE_ITEM_EXPANDING``    The item is being expanded. This can be prevented by calling :meth:`TreeEvent.Veto() <lib.agw.customtreectrl.TreeEvent.Veto>`.
``EVT_TREE_ITEM_GETTOOLTIP``   The opportunity to set the item tooltip is being given to the application (call :meth:`TreeEvent.SetToolTip() <lib.agw.customtreectrl.CommandTreeEvent.SetToolTip>`).
``EVT_TREE_ITEM_MIDDLE_CLICK`` The user has clicked the item with the middle mouse button (not implemented in :class:`HyperTreeList`).
``EVT_TREE_SEL_CHANGING``      Selection is changing. This can be prevented by calling :meth:`TreeEvent.Veto() <lib.agw.customtreectrl.TreeEvent.Veto>`.
``EVT_TREE_SET_INFO``          Information is being supplied to the application (not implemented in :class:`HyperTreeList`).
``EVT_TREE_STATE_IMAGE_CLICK`` The state image has been clicked (not implemented in :class:`HyperTreeList`).

:class:`HyperTreeList` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 30 Jul 2014, 21.00 GMT

Version 1.4

# HYPERTREELIST wxPython IMPLEMENTATION
# Inspired By And Heavily Based On wx.gizmos.TreeListCtrl in Classic.
#
# Andrea Gavana, @ 08 May 2006
# Latest Revision: 30 Jul 2014, 21.00 GMT
#
#
# TODO List
#
# Almost All The Features Of wx.gizmos.TreeListCtrl Are Available, And There Is
# Practically No Limit In What Could Be Added To This Class. The First Things
# That Comes To My Mind Are:
#
# 1. Add Support For 3-State CheckBoxes (Is That Really Useful?).
#
# 2. Try To Implement A More Flicker-Free Background Image In Cases Like
#    Centered Or Stretched Image (Now HyperTreeList Supports Only Tiled
#
# 3. Try To Mimic Windows wx.TreeCtrl Expanding/Collapsing behaviour: HyperTreeList
#
# 4. Speed Up General OnPaint Things? I Have No Idea, Here HyperTreeList Is Quite
#
#
#
#
#
#

:param `item`: an instance of :class:`TreeListItem`;
:param `column`: if not ``None``, an integer specifying the column index.
 If it is ``None``, the main column index is used;
:param `owner`: the window owner, in this case an instance of :class:`TreeListMainWindow`;
:param `value`: the initial value in the control;

__init__(self, parent, id=wx.ID_ANY, item=None, column=None, owner=None, value="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="editctrl", \*\*kwargs)

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`EditCtrl`

:param `value`: the initial value in the text control;

__init__(self, parent, id=wx.ID_ANY, item=None, column=None, owner=None, value="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="edittextctrl", \*\*kwargs)

Handles the ``wx.EVT_CHAR`` event for :class:`EditTextCtrl`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`EditTextCtrl`.

:class:`HyperTreeList` is a generic widget that combines the multicolumn
features of a :class:`wx.ListCtrl` with the hierarchical features of a
:class:`wx.TreeCtrl` This class does not rely on native native controls,
as it is a full owner-drawn tree-list control.

It manages two widgets internally:

shouldn't be needed in normal usage.

Please note that in addition to the defined methods of :class:`HyperTreeList`
many more methods are delegated to the internal :class:`TreeListMainWindow`
and its subclass :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`. These
methods can be called directly from the ``HyperTreeList`` class:

================================================================================ ==================================================================================
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.AddRoot`                     Adds a root item to the :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AppendItem`                     Appends an item as a last child of its parent.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AssignButtonsImageList`         Assigns the button image list.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AssignImageList`                Assigns the normal image list.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AssignStateImageList`           Assigns the state image list.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AutoCheckChild`                 Transverses the tree and checks/unchecks the items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AutoCheckParent`                Traverses up the tree and checks/unchecks parent items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.AutoToggleChild`                Transverses the tree and toggles the items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CheckChilds`                    Programmatically check/uncheck item children.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CheckItem`                      Actually checks/uncheks an item, sending the two related events.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CheckItem2`                     Used internally to avoid ``EVT_TREE_ITEM_CHECKED`` events.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CheckSameLevel`                 Uncheck radio items which are on the same level of the checked one.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.Collapse`                       Collapse an item, sending the two related events.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.CollapseAndReset`               Collapse the given item and deletes its children.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.Delete`                      Deletes an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.DeleteAllItems`              Delete all items in the :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.DeleteChildren`                 Delete all the item's children.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.DeleteItemWindow`            Deletes the window in the column associated to an item (if any).
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.DeleteRoot`                  Removes the tree root item (and subsequently all the items in the tree).
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.EditLabel`                   Starts editing an item label.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.EnableChildren`                 Enables/disables the item children.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.EnableItem`                  Enables/disables an item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.EnableSelectionGradient`        Globally enables/disables drawing of gradient selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.EnableSelectionVista`           Globally enables/disables drawing of Windows Vista selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.EnsureVisible`                  Scrolls and/or expands items to ensure that the given item is visible.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.Expand`                         Expands an item, sending the two related events.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.ExpandAll`                      Expands all :class:`TreeListMainWindow` items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.ExpandAllChildren`              Expands all the items children of the input item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.FindItem`                       Finds the first item starting with the given prefix after the given parent.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetBackgroundImage`             Returns the :class:`TreeListMainWindow` background image (if any).
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetBorderPen`                   Returns the pen used to draw the selected item border.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetBoundingRect`                Retrieves the rectangle bounding the item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetButtonsImageList`            Returns the buttons image list associated with :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetChildrenCount`               Returns the item children count.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetColumnCount`              Returns the total number of columns.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetConnectionPen`               Returns the pen used to draw the connecting lines between items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetCount`                       Returns the global number of items in the tree.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetCurrentItem`              Returns the current item. Simply calls :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSelection`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetDisabledColour`              Returns the colour for items in a disabled state.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetDragFullScreen`              Returns whether built-in drag/drop will be full screen or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetEditControl`                 Returns a reference to the edit :class:`~wx.lib.agw.customtreectrl.TreeTextCtrl` if the item is being edited.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetFirstChild`                  Returns the item's first child and an integer value 'cookie'.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetFirstExpandedItem`        Returns the first item which is in the expanded state.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetFirstGradientColour`         Returns the first gradient colour for gradient-style selections.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetFirstVisibleItem`         Returns the first visible item.
GetFocusedItem                                                                   Another name for :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSelection`   
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetGradientStyle`               Returns the gradient style for gradient-style selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetHilightFocusColour`          Returns the colour used to highlight focused selected items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetHilightNonFocusColour`       Returns the colour used to highlight unfocused selected items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetHyperTextFont`               Returns the font used to render hypertext items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetHyperTextNewColour`          Returns the colour used to render a non-visited hypertext item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetHyperTextVisitedColour`      Returns the colour used to render a visited hypertext item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetImageList`                   Returns the normal image list associated with :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetImageListCheck`              Returns the ``wx.ImageList`` used for the check/radio buttons in :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetIndent`                      Returns the item indentation, in pixels.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItem3StateValue`             Gets the state of a 3-state checkbox item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemBackgroundColour`        Returns the item background colour.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemFont`                    Returns the item font.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetItemImage`                Returns the item image.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemParent`                  Returns the item parent (can be ``None`` for root items).
GetItemPyData                                                                    Another name for :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetPyData`   
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetItemText`                 Returns the item text label.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemTextColour`              Returns the item text colour or separator horizontal line colour.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemType`                    Returns the item type.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetItemVisited`                 Returns whether an hypertext item was visited.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetItemWindow`               Returns the window associated with an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetItemWindowEnabled`        Returns whether the window associated with an item is enabled or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetLastChild`                   Returns the item last child.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetNext`                        Returns the next item. Only for internal use right now.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetNextChild`                   Returns the item's next child.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetNextExpanded`             Returns the next expanded item after the input one.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetNextShown`                   Returns the next displayed item in the tree, visible or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetNextSibling`                 Returns the next sibling of an item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetNextVisible`                 Returns the next item that is visible to the user.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetPrev`                        Returns the previous item. Only for internal use right now.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetPrevChild`                Returns the previous child of an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetPrevExpanded`             Returns the previous expanded item before the input one.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetPrevShown`                   Returns the previous displayed item in the tree, visible or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetPrevSibling`                 Returns the previous sibling of an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.GetPrevVisible`              Returns the previous item visible to the user.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetPyData`                      Returns the data associated to an item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetRootItem`                    Returns the root item, an instance of :class:`GenericTreeItem`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSecondGradientColour`        Returns the second gradient colour for gradient-style selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSelection`                   Returns the current selection.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSelections`                  Returns a list of selected items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSpacing`                     Returns the spacing between the start and the text, in pixels.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetStateImageList`              Returns the state image list associated with :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.HasChildren`                    Returns whether an item has children or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.HideItem`                       Hides/shows an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.HitTest`                     Finds which (if any) item is under the given point, returning the item plus flags.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.InsertItem`                     Inserts an item after the given previous.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsBold`                         Returns whether the item font is bold or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsDescendantOf`                 Checks if the given item is under another one in the tree hierarchy.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsExpanded`                     Returns whether the item is expanded or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsItem3State`                   Returns whether or not the checkbox item is a 3-state checkbox.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsItemChecked`                  Returns whether an item is checked or not.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.IsItemEnabled`               Returns whether an item is enabled or disabled.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsItemHyperText`                Returns whether an item is hypertext or not.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.IsItemVisible`               Returns whether the item is visible or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsSelected`                     Returns whether the item is selected or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.ItemHasChildren`                Returns whether the item has children or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.PrependItem`                    Prepends an item as a first child of parent.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.ScrollTo`                    Scrolls the specified item into view.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SelectAll`                      Selects all the item in the tree.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SelectAllChildren`              Selects all the children of the given item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SelectItem`                     Selects/deselects an item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetBackgroundImage`             Sets the :class:`TreeListMainWindow` background image.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetBorderPen`                   Sets the pen used to draw the selected item border.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetButtonsImageList`            Sets the buttons image list for :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetConnectionPen`               Sets the pen used to draw the connecting lines between items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetDisabledColour`              Sets the colour for items in a disabled state.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetDragFullScreen`              Sets whether a drag operation will be performed full screen or not.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetDragItem`                 Sets the specified item as member of a current drag and drop operation.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetFirstGradientColour`         Sets the first gradient colour for gradient-style selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetGradientStyle`               Sets the gradient style for gradient-style selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetHilightFocusColour`          Sets the colour used to highlight focused selected items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetHilightNonFocusColour`       Sets the colour used to highlight unfocused selected items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetHyperTextFont`               Sets the font used to render hypertext items.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetHyperTextNewColour`          Sets the colour used to render a non-visited hypertext item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetHyperTextVisitedColour`      Sets the colour used to render a visited hypertext item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetImageList`                   Sets the normal image list for :class:`TreeListMainWindow`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetImageListCheck`              Sets the checkbox/radiobutton image list.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetIndent`                      Currently has no effect on ``HyperTreeList``. The indent is auto-calculated.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItem3State`                  Sets whether the item has a 3-state value checkbox assigned to it or not.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItem3StateValue`             Sets the checkbox item to the given `state`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemBackgroundColour`        Sets the item background colour.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemBold`                    Sets the item font as bold/unbold.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemDropHighlight`           Gives the item the visual feedback for drag and drop operations.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemFont`                    Sets the item font.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemHasChildren`             Forces the appearance/disappearance of the button next to the item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemHyperText`               Sets whether the item is hypertext or not.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetItemImage`                Sets the item image for a particular item state.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemItalic`                  Sets the item font as italic/non-italic.
SetItemPyData                                                                    Another name for :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetPyData`   
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetItemText`                 Sets the item text label.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemTextColour`              Sets the item text colour or separator horizontal line colour.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemType`                    Sets the item type.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetItemVisited`                 Sets whether an hypertext item was visited.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetItemWindow`               Sets the window associated to an item.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetItemWindowEnabled`        Sets whether the window associated with an item is enabled or not.
:meth:`~wx.lib.agw.hypertreelist.TreeListMainWindow.SetMainColumn`               Sets the :class:`HyperTreeList` main column (i.e. the column of the tree).
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetPyData`                      Sets the data associated to an item.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetSecondGradientColour`        Sets the second gradient colour for gradient-style selections.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetSpacing`                     Currently has no effect on ``HyperTreeList``.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.SetStateImageList`              Sets the state image list for :class:`TreeListMainWindow`
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.ShouldInheritColours`           Return ``True`` to allow the window colours to be changed by `InheritAttributes`.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.Toggle`                         Toggles the item state (collapsed/expanded).
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.ToggleItemSelection`            Toggles the item selection.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.UnCheckRadioParent`             Used internally to handle radio node parent correctly.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.Unselect`                       Unselects the current selection.
:meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.UnselectAll`                    Unselect all the items.

:param `style`: the underlying :class:`wx.Control` style;
:param `agwStyle`: the AGW-specific :class:`HyperTreeList` window style.
 see :mod:`~wx.lib.agw.hypertreelist` for a full list of flags.
:param `validator`: window validator;
:param `name`: window name.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=wx.TR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="HyperTreeList")

Appends a column to the :class:`HyperTreeList`.

:param `text`: the column text label;
:param `width`: the column width in pixels;
:param `flag`: the column alignment flag, one of ``wx.ALIGN_LEFT``,
 ``wx.ALIGN_RIGHT``, ``wx.ALIGN_CENTER``;
:param `image`: an index within the normal image list assigned to
 :class:`HyperTreeList` specifying the image to use for the column;
:param `shown`: ``True`` to show the column, ``False`` to hide it;
:param `colour`: a valid :class:`wx.Colour`, representing the text foreground colour
 for the column;
:param `edit`: ``True`` to set the column as editable, ``False`` otherwise.

AddColumn(self, text, width=_DEFAULT_COL_WIDTH, flag=wx.ALIGN_LEFT, image=-1, shown=True, colour=None, edit=False)

:param `colInfo`: an instance of :class:`TreeListColumnInfo`.

Create an edit control for editing a label of an item. By default, this
returns a text control.

Override this function in the derived class to return a different type
of control.

:param `column`: an integer specifying the column index.

Freeze :class:`HyperTreeList` to allow rapid changes to the tree.

Freezes the HyperTreeList main (tree) and and header windows.
This prevents any re-calculation or updates from taking place
allowing mass updates to the tree very quickly. :meth:`~Thaw`
must be called to re-enable updates. Calls to these two
functions may be nested.

Returns the :class:`HyperTreeList` window style flag.

:see: :meth:`~HyperTreeList.SetAGWWindowStyleFlag` for a list of valid window styles.

Returns an instance of :class:`TreeListColumnInfo` containing column information.

Returns the column text alignment.

Returns the column text colour.

Returns the column text font.

Returns the image assigned to the specified column.

Returns the column text label.

Returns the column width, in pixels.

Returns the header window, an instance of :class:`TreeListHeaderWindow`. 

Returns the main window, an instance of :class:`TreeListMainWindow`. 

Return the alignment style to use for the text control that is used
to edit labels of items. The alignment style is derived from the
column alignment.

Return the style to use for the text control that is used to edit
labels of items.

Override this function in the derived class to support a different
style, e.g. ``wx.TE_MULTILINE``.

Returns whether a flag is present in the :class:`HyperTreeList` style.

:param `flag`: one of the possible :class:`HyperTreeList` window styles.

:see: :meth:`~HyperTreeList.SetAGWWindowStyleFlag` for a list of possible window style flags.

Inserts a column to the :class:`HyperTreeList` at the position specified
by `before`.

:param `before`: the index at which we wish to insert the new column;

InsertColumn(self, before, text, width=_DEFAULT_COL_WIDTH, flag=wx.ALIGN_LEFT, image=-1, shown=True, colour=None, edit=False)

Returns ``True`` if the column is editable, ``False`` otherwise.

Returns ``True`` if the column is shown, ``False`` otherwise.

Returns the comparison of two items. Used for sorting.

in the :class:`HyperTreeList`. The function should return a negative, zero or positive

:param `item1`: an instance of :class:`TreeListItem`;
:param `item2`: another instance of :class:`TreeListItem`.

If the ``TR_VIRTUAL`` style is set this function **must** be overloaded
in the derived class. It should return the string containing the text
of the given column for the specified item.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`HyperTreeList`.

Handles the ``wx.EVT_SIZE`` event for :class:`HyperTreeList`.

Causes this window, and all of its children recursively (except under wxGTK1
where this is not implemented), to be repainted.

:param `erase`: If ``True``, the background will be erased;
:param `rect`: If not ``None``, only the given rectangle will be treated as damaged.

:note: Note that repainting doesn't happen immediately but only during the next
 event loop iteration, if you need to update the window immediately you should
 use `Update` instead.

Removes a column from the :class:`HyperTreeList`.

Sets the window style for :class:`HyperTreeList`.

:param `agwStyle`: can be a combination of various bits. See
 :mod:`~wx.lib.agw.hypertreelist` for a full list of flags.

Changes the background colour of :class:`HyperTreeList`.

Sets/unsets the double buffering for the header and the main window.

:param `buffered`: ``True`` to use double-buffering, ``False`` otherwise.

:note: Currently we are using double-buffering only on Windows XP.

Sets a column using an instance of :class:`TreeListColumnInfo`.

:param `column`: an integer specifying the column index;
:param `info`: an instance of :class:`TreeListColumnInfo`.

Sets the column text alignment.

:param `flag`: the alignment flag, one of ``wx.ALIGN_LEFT``, ``wx.ALIGN_RIGHT``,
 ``wx.ALIGN_CENTER``.

Sets the column text colour.

Sets the column as editable or non-editable.

:param `edit`: ``True`` if the column should be editable, ``False`` otherwise.

Sets the column text font.

Sets an image on the specified column.

 :class:`HyperTreeList` specifying the image to use for the column.

Sets the column as shown or hidden.

:param `shown`: ``True`` if the column should be shown, ``False`` if it
 should be hidden.

Sets the sort icon to be displayed in the column header.

The sort icon will be displayed in the specified column number
and all other columns will have the sort icon cleared.

:param `sortIcon`: the sort icon to display, one of ``wx.HDR_SORT_ICON_NONE``,
 ``wx.HDR_SORT_ICON_UP``, ``wx.HDR_SORT_ICON_DOWN``.
:param `colour`: the colour of the sort icon as a wx.Colour. Optional.
 Set to ``None`` to restore native colour.

Sets the column text label.

:param `text`: the new column label.

Sets the column width, in pixels.

:param `width`: the new column width, in pixels.

Sets the default font for the header window and the main window.

Changes the foreground colour of :class:`HyperTreeList`.

Associate a custom renderer with the header - all columns will use it

:param `renderer`: a class able to correctly render header buttons

:note: the renderer class **must** implement the method `DrawHeaderButton`

Sets the default font for the header window..

Sorts the children of the given item using :meth:`~HyperTreeList.OnCompareItems` method of :class:`HyperTreeList`.
You should override that method to change the sort order (the default is ascending
case-sensitive alphabetical order).

Thaw :class:`HyperTreeList`.

Reenables updates to the main (tree) and header windows after a
previous call to :meth:`~Freeze`. To really thaw the control, it
must be called exactly the same number of times as :meth:`~Freeze`.
When fully thawed the tree will re-calculate and update itself.

Class used to store information (width, alignment flags, colours, etc...) about a
:class:`HyperTreeList` column header.

:param `input`: can be a string (representing the column header text) or
 another instance of :class:`TreeListColumnInfo`. In the latter case, all the
 other input parameters are not used;

__init__(self, input="", width=_DEFAULT_COL_WIDTH, flag=wx.ALIGN_LEFT, image=-1, shown=True, colour=None, edit=False)

Returns ``True`` if the column is editable, ``False`` otherwise. 

Returns ``True`` if the column is shown, ``False`` if it is hidden. 

Sets the column image index.

Sets the column image index in the selected state.

 :class:`HyperTreeList` specifying the image to use for the column when in
 selected state.

Sets the column sort icon displayed in the header.

Sets the column header label.

:param `text`: the new column header text.

Sets the column header width.

:param `width`: the column header width, in pixels.

__init__(self, parent, id=wx.ID_ANY, owner=None, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="wxtreelistctrlcolumntitles")

Appends a column to the :class:`TreeListHeaderWindow`.

Shifts the :class:`wx.DC` origin to match the position of the main window horizontal
scrollbar: this allows us to always use logical coordinates.

Returns a column item, an instance of :class:`TreeListItem`.

Inserts a column to the :class:`TreeListHeaderWindow` at the position specified

Returns ``True`` if the column is shown, ``False`` if it is hidden.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`TreeListHeaderWindow`.

Handles the ``wx.EVT_PAINT`` event for :class:`TreeListHeaderWindow`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`TreeListHeaderWindow`.

Redraws the column.

:param `col`: the index of the column to redraw.

Removes a column from the :class:`TreeListHeaderWindow`.

Sends a :class:`ListEvent` for the parent window.

Sets/unsets the double buffering for the header.

:note: Currently double-buffering is only enabled by default for Windows XP.

:param `flag`: the new text alignment flag.

:see: :meth:`TreeListColumnInfo.SetAlignment() <TreeListColumnInfo.SetAlignment>` for a list of valid alignment
 flags.

:param `width`: the new width for the column, in pixels.

Returns the column that corresponds to the logical input `x` coordinate.

:param `x`: the `x` position to evaluate.

:return: The column that corresponds to the logical input `x` coordinate,
 or ``wx.NOT_FOUND`` if there is no column at the `x` position.

:class:`HyperTreeList`.

:note: Subclassed from :class:`~wx.lib.agw.customtreectrl.GenericTreeItem`.

# ---------------------------------------------------------------------------
# TreeListItem

:param `mainWin`: the main :class:`HyperTreeList` window, in this case an instance
 of :class:`TreeListMainWindow`;
:param `parent`: the tree item parent (may be ``None`` for root items);
:param `text`: the tree item text;
:param `ct_type`: the tree item kind. May be one of the following integers:

 =============== ==========================

 the item;
:param `image`: an index within the normal image list specifying the image to
:param `selImage`: an index within the normal image list specifying the image to
:param `data`: associate the given Python object `data` with the item.

   inactive.

__init__(self, mainWin, parent, text="", ct_type=0, wnd=None, image=-1, selImage=-1, data=None)

Deletes the item children.

:param `tree`: the main :class:`TreeListMainWindow` instance.

Deletes the window associated to the item (if any).

 If it is ``None``, the main column index is used.

Returns the associated background colour

:param `column` an integer specifying the column index.

:param `which`: can be one of the following bits:

Returns the item text label.

Returns the window associated to the item.

Returns whether the window associated with an item is enabled or not.

Returns the associated window size.

HitTest method for an item. Called from the main window HitTest.

:param `theCtrl`: the main :class:`TreeListMainWindow` tree;
:param `flags`: a bitlist of hit locations;
:param `level`: the item's level inside the tree hierarchy.

:see: :meth:`TreeListMainWindow.HitTest() <TreeListMainWindow.HitTest>` method for the flags explanation.

:return: A 3-tuple of (item, flags, column). The item may be ``None``.

Returns whether the item is enabled or not.

:return: ``True`` if the item is enabled, ``False`` if it is disabled or hidden.

:return: ``True`` if the item is expanded, ``False`` if it is collapsed or hidden.

Handles the ``wx.EVT_SET_FOCUS`` event for a window associated to an item.

Sets the associated background colour

:param integer `column`

Sets the item image for a particular item state.

:param `image`: an index within the normal image list specifying the image to use;
:param `which`: the item state.

:see: :meth:`~TreeListItem.GetImage` for a list of valid item states.

:note: Call :meth:`~TreeListMainWindow.SetItemImage` instead to refresh the tree properly.

Sets the item text label.

:param `text`: a string specifying the new item label.

:note: Call :meth:`~TreeListMainWindow.SetItemText` instead to refresh the tree properly.

Sets the `x` position of the item text. Used internally to position
text according to column alignment.

:param `text_x`: the `x` position of the item text.

:param `wnd`: a non-toplevel window to be displayed next to the item;
 
:note: Always use :meth:`~TreeListMainWindow.SetItemWindow` instead to update the tree properly.

Sets whether the window associated with an item is enabled or not.

:param `enable`: ``True`` to enable the associated window, ``False`` to disable it;

This class represents the main window (and thus the main column) in :class:`HyperTreeList`.

:note: This is a subclass of :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`.

:param `style`: the underlying :class:`ScrolledWindow` style;

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=wx.TR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="wxtreelistmainwindow")

Adds a root item to the :class:`TreeListMainWindow`.

:param `text`: the item text label;
:param `ct_type`: the item type (see :meth:`CustomTreeCtrl.SetItemType() <lib.agw.customtreectrl.CustomTreeCtrl.SetItemType>`
 for a list of valid item types);
:param `wnd`: if not ``None``, a non-toplevel window to show next to the item;

   Only one root is allowed to exist in any given instance of :class:`TreeListMainWindow`.

AddRoot(self, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None)

:param `level`: the item level in the tree hierarchy;
:param `y`: the current vertical position inside the :class:`ScrolledWindow`;
:param `x_colstart`: the x coordinate at which the item's column starts.

We are about to destroy the item's children.

Deletes the window in the column associated to an item (if any).

Removes the tree root item (and subsequently all the items in
:class:`TreeListMainWindow`.

:param `parentId`: an instance of :class:`TreeListItem` representing the
:param `previous`: the index at which we should insert the item;
:param `ct_type`: the item type (see :meth:`CustomTreeCtrl.SetItemType() <lib.agw.customtreectrl.CustomTreeCtrl.SetItemType>` for a list of valid
:param `ignored_args`: unused at the moment, this parameter is present to comply with
 :meth:`CustomTreeCtrl.DoInsertItem() <lib.agw.customtreectrl.CustomTreeCtrl.DoInsertItem>` changed API.

DoInsertItem(self, parent, previous, text, ct_type=0, wnd=None, image=-1, selImage=-1, data=None, \*ignored_args)

:param `enable`: ``True`` to enable the item, ``False`` otherwise;
:param `torefresh`: whether to redraw the item or not.

Returns the best column's width based on the items width in this column.

:param `parent`: an instance of :class:`TreeListItem`.

Returns the current item.

This is the same as :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.GetSelection`.

Returns the column background colour of the item

:param `item`: an instance of :class:`TreeListItem`

GetItemImage(self, item, column=None, which=wx.TreeItemIcon_Normal)

Returns the item width.

Returns the window associated with an item.

Returns the :class:`HyperTreeList` main column (i.e. the position of the underlying
:class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`.

Returns the previous child of an item.

Returns the previous visible item before the input one.

Scans all item windows in the tree and hides those whose items
they belong to are not currently visible. Used internally. 

at this point plus extra information flags plus the item's column.

:param `flags`: a bitlist of the following values:

:return: the item (if any, ``None`` otherwise), the `flags` and the column are always
 returned as a tuple.

Returns whether the item is visible or not.

:note: This method is renamed from :meth:`~wx.lib.agw.customtreectrl.CustomTreeCtrl.IsVisible`

Returns ``True`` if :class:`TreeListMainWindow` has the ``TR_VIRTUAL`` flag set. 

Called by :class:`EditTextCtrl`, to accept the changes and to send the

:param `value`: the new value of the item label.

Called by :class:`EditCtrl`, to cancel the changes and to send the

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`TreeListMainWindow`.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`TreeListMainWindow`.

Handles the ``wx.EVT_PAINT`` event for :class:`TreeListMainWindow`.

Handles the ``wx.EVT_SCROLLWIN`` event for :class:`TreeListMainWindow`.

:param `event`: a :class:`ScrollEvent` event to be processed.

Paint a level in the hierarchy of :class:`TreeListMainWindow`.

:param `y`: the current vertical position in the :class:`ScrolledWindow`;
:param `x_maincol`: the horizontal position of the main column.

Sets/unsets the double buffering for the main window.

Sets the specified item as member of a current drag and drop operation.

Sets the column background colour of the item

:see: :meth:`~TreeListMainWindow.GetItemImage` for a list of valid item states.

SetItemImage(self, item, image, column=None, which=wx.TreeItemIcon_Normal)

:param `text`: a string specifying the new item label;

Sets the window associated to an item.

:note: The window being added should have its parent set to the :class:`TreeListMainWindow`
 which can be obtained with :meth:`~HyperTreeList.GetHeaderWindow`. If this is not the case
 the window will be re-parented which may cause some flicker.

Sets the :class:`HyperTreeList` main column (i.e. the position of the underlying

Creates a method that forwards calls to `self._main_win` (an instance of :class:`TreeListMainWindow`).

:param `method`: one method inside the :class:`TreeListMainWindow` local scope.

Utility function which checks if a platform handles correctly double
buffering for the header. Currently returns ``False`` for all platforms
except Windows XP.

['GetIndent', 'SetIndent', 'GetSpacing', 'SetSpacing', 'GetImageList', 'GetStateImageList', 'GetButtonsImageList', 'AssignImageList', 'AssignStateImageList', 'AssignButtonsImageList', 'SetImageList', 'SetButtonsImageList', 'SetStateImageList', 'GetItemText', 'GetItemImage', 'GetItemPyData', 'GetPyData', 'GetItemTextColour', 'GetItemBackgroundColour', 'GetItemFont', 'SetItemText', 'SetItemImage', 'SetItemPyData', 'SetPyData', 'SetItemHasChildren', 'SetItemBackgroundColour', 'SetItemFont', 'IsItemVisible', 'HasChildren', 'IsExpanded', 'IsSelected', 'IsBold', 'GetCount', 'GetChildrenCount', 'GetRootItem', 'GetSelection', 'GetSelections', 'GetItemParent', 'GetFirstChild', 'GetNextChild', 'GetPrevChild', 'GetLastChild', 'GetNextSibling', 'GetPrevSibling', 'GetNext', 'GetFirstExpandedItem', 'GetNextExpanded', 'GetPrevExpanded', 'GetFocusedItem', 'GetFirstVisibleItem', 'GetNextVisible', 'GetPrevVisible', 'AddRoot', 'PrependItem', 'InsertItem', 'AppendItem', 'Delete', 'DeleteChildren', 'DeleteRoot', 'Expand', 'ExpandAll', 'ExpandAllChildren', 'Collapse', 'CollapseAndReset', 'Toggle', 'Unselect', 'UnselectAll', 'SelectItem', 'SelectAll', 'EnsureVisible', 'ScrollTo', 'HitTest', 'GetBoundingRect', 'EditLabel', 'FindItem', 'SelectAllChildren', 'SetDragItem', 'GetColumnCount', 'SetMainColumn', 'GetHyperTextFont', 'SetHyperTextFont', 'SetHyperTextVisitedColour', 'GetHyperTextVisitedColour', 'SetHyperTextNewColour', 'GetHyperTextNewColour', 'SetItemVisited', 'GetItemVisited', 'SetHilightFocusColour', 'GetHilightFocusColour', 'SetHilightNonFocusColour', 'GetHilightNonFocusColour', 'SetFirstGradientColour', 'GetFirstGradientColour', 'SetSecondGradientColour', 'GetSecondGradientColour', 'EnableSelectionGradient', 'SetGradientStyle', 'GetGradientStyle', 'EnableSelectionVista', 'SetBorderPen', 'GetBorderPen', 'SetConnectionPen', 'GetConnectionPen', 'SetBackgroundImage', 'GetBackgroundImage', 'SetImageListCheck', 'GetImageListCheck', 'EnableChildren', 'EnableItem', 'IsItemEnabled', 'GetDisabledColour', 'SetDisabledColour', 'IsItemChecked', 'UnCheckRadioParent', 'CheckItem', 'CheckItem2', 'AutoToggleChild', 'AutoCheckChild', 'AutoCheckParent', 'CheckChilds', 'CheckSameLevel', 'GetItemWindowEnabled', 'SetItemWindowEnabled', 'GetItemType', 'IsDescendantOf', 'SetItemHyperText', 'IsItemHyperText', 'SetItemBold', 'SetItemDropHighlight', 'SetItemItalic', 'GetEditControl', 'ShouldInheritColours', 'GetItemWindow', 'SetItemWindow', 'DeleteItemWindow', 'SetItemTextColour', 'HideItem', 'DeleteAllItems', 'ItemHasChildren', 'ToggleItemSelection', 'SetItemType', 'GetDragFullScreen', 'SetDragFullScreen', 'GetCurrentItem', 'SetItem3State', 'SetItem3StateValue', 'GetItem3StateValue', 'IsItem3State', 'GetPrev', 'GetNextShown', 'GetPrevShown']

An info bar is a transient window shown at top or bottom of its parent window to display
non-critical information to the user.

:note:

    The Python implementation of :class:`InfoBar` is a direct translation of the generic C++
    implementation of :class:`InfoBar`.

This class provides another way to show messages to the user, intermediate between message
boxes and status bar messages. The message boxes are modal and thus interrupt the users work
flow and should be used sparingly for this reason. However status bar messages are often
too easy not to notice at all. An info bar provides a way to present the messages which has
a much higher chance to be noticed by the user but without being annoying.

Info bar may show an icon (on the left), text message and, optionally, buttons allowing the
user to react to the information presented. It always has a close button at the right allowing
the user to dismiss it so it isn't necessary to provide a button just to close it.

:class:`InfoBar` calls its parent `Layout()` method (if its parent is **not** managed by :class:`~aui.framemanager`
or :class:`~wx.lib.agw.aui.framemanager.AuiManager`) and assumes that it will change the parent layout appropriately depending
on whether the info bar itself is shown or hidden. Usually this is achieved by simply using a
sizer for the parent window layout and adding wxInfoBar to this sizer as one of the items.
Considering the usual placement of the info bars, normally this sizer should be a vertical
:class:`BoxSizer` and the bar its first or last element.

:class:`InfoBar` supports all the :class:`InfoBar` generic implementation functionalities, and in addition
it using :meth:`~InfoBar.AddButton` it is possible to add a button with a bitmap (and not only a plain :class:`Button`).

For example::

    info = InfoBar(parent)
    bitmap = wx.Bitmap('nice_bitmap.png', wx.BITMAP_TYPE_PNG)

    info.AddButton(wx.ID_ANY, 'New Button', bitmap)

Usage
=====

The simplest possible example of using this class would be::

    import wx
    import wx.lib.agw.infobar as IB

            wx.Frame.__init__(self, parent, -1, 'InfoBar Demo')

            self._infoBar = IB.InfoBar(self)

            sizer.Add(self._infoBar, wx.SizerFlags().Expand())

            sizer.Add(panel, 1, wx.EXPAND)

            # ... Add other frame controls to the sizer ...
            self.SetSizer(sizer)

            wx.CallLater(2000, self.SomeMethod)

        def SomeMethod(self):

            self._infoBar.ShowMessage("Something happened", wx.ICON_INFORMATION)

:class:`InfoBar` has been tested on the following platforms:
  * Windows (Vista/7).

``wx.EVT_BUTTON`` Process a `wx.wxEVT_COMMAND_BUTTON_CLICKED` event, when the button is clicked.

:class:`InfoBar` control is distributed under the wxPython license.

# INFOBAR Control wxPython IMPLEMENTATION
# Inspired By And Heavily Based On wxInfoBar.
#
#
# Andrea Gavana, @ 12 March 2012
#
#
#
# 1. ?
#
#
#
#
#
#

A simple class derived from :mod:`lib.stattext` that implements auto-wrapping
behaviour depending on the parent size.

Defsult class constructor.

:param wx.Window parent: a subclass of :class:`wx.Window`, must not be ``None``;
:param string `label`: the :class:`AutoWrapStaticText` text label.

Handles the ``wx.EVT_SIZE`` event for :class:`AutoWrapStaticText`.

Sets the :class:`AutoWrapStaticText` label.

All "&" characters in the label are special and indicate that the following character is
a mnemonic for this control and can be used to activate it from the keyboard (typically
by using ``Alt`` key in combination with it). To insert a literal ampersand character, you
need to double it, i.e. use "&&". If this behaviour is undesirable, use :meth:`~Control.SetLabelText` instead.

:param string `label`: the new :class:`AutoWrapStaticText` text label;
:param bool `wrapped`: ``True`` if this method was called by the developer using :meth:`~AutoWrapStaticText.SetLabel`,
 ``False`` if it comes from the :meth:`~AutoWrapStaticText.OnSize` event handler.

:note: Reimplemented from :class:`wx.Control`.

This functions wraps the controls label so that each of its lines becomes at
most `width` pixels wide if possible (the lines are broken at words boundaries
so it might not be the case if words are too long).

If `width` is negative, no wrapping is done.

:param integer `width`: the maximum available width for the text, in pixels.

:note: Note that this `width` is not necessarily the total width of the control,
 since a few pixels for the border (depending on the controls border style) may be added.

This is the main class implementation, plainly translated from C++.

:param integer `style`: the :class:`InfoBar` style (unused at present);
:param string `name`: the control name.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name='InfoBar')

Adds a button to be shown in the info bar.

The button added by this method will be shown to the right of the text (in LTR layout),
with each successive button being added to the right of the previous one. If any buttons
are added to the info bar using this method, the default `Close` button is not shown
as it is assumed that the extra buttons already allow the user to close it.

Clicking the button will generate a normal ``wx.wxEVT_COMMAND_BUTTON_CLICKED`` event which
can be handled as usual. The default handler in :class:`InfoBar` itself closes the window
whenever a button in it is clicked so if you wish the info bar to be hidden when the button
is clicked, simply call `event.Skip()` in the button handler to let the base class handler
do it (calling :meth:`~InfoBar.Dismiss` explicitly works too, of course). On the other hand, if you don't
skip the event, the info bar will remain opened so make sure to do it for at least some
buttons to allow the user to close it.

:param integer `btnid`: id of the button. It will be used in the button message clicking
 this button will generate;
:param string `label`: the label of the button. It may only be empty if `btnid` is one of
 the stock ids in which case the corresponding stock label will be used;
:param `bitmap`: if not equal to :class:`NullBitmap`, a valid :class:`wx.Bitmap` image to show beside
 the button text.

:note:

     Notice that the generic :class:`InfoBar` implementation handles the button events itself
     and so they are not propagated to the info bar parent and you need to either inherit from
     :class:`InfoBar` and handle them in your derived class or use `self.Bind(...)` to handle the
     button events in the parent frame.

Hides the :class:`InfoBar` window.

This method hides the window and lays out the parent window to account for
its disappearance (unlike a simple `Hide()`), but only if this :class:`InfoBar`
parent is **not** managed by :class:`framemanager` or :class:`~wx.lib.agw.aui.framemanager.AuiManager`.

Hides this :class:`InfoBar` with whatever hiding effect has been chosen. 

Shows this :class:`InfoBar` with whatever showing effect has been chosen. 

Determines the placement of the bar from its position in the containing
sizer.

:return: One of these integer bits:

 Placement Flag             Hex Value   Description
 ``BarPlacement_Unknown``           0x0 Unknown placement of :class:`InfoBar` (not good).
 ``BarPlacement_Top``               0x1 :class:`InfoBar` is placed at the top of its parent.
 ``BarPlacement_Bottom``            0x2 :class:`InfoBar` is placed at the bottom of its parent.

Return the effect animation duration currently used, in milliseconds. 

Return the effect currently used for hiding the bar.

:return: One of the following integer bits:

 ================================== =========== ==================================================
 `ShowEffect` Flag                  Hex Value   Description
 ``wx.SHOW_EFFECT_NONE``                    0x0 No effect, equivalent to normal `Show()` or `Hide()` call.
 ``wx.SHOW_EFFECT_SLIDE_TO_TOP``            0x7 Slide the :class:`InfoBar` window to the top.
 ``wx.SHOW_EFFECT_SLIDE_TO_BOTTOM``         0x8 Slide the :class:`InfoBar` window to the bottom.

Return the effect currently used for showing the bar.

Default event handler for the `Close` button in :class:`InfoBar`.

:param `event`: a :class:`CommandEvent` to be processed.

:note:

Remove a button previously added by :meth:`~InfoBar.AddButton`.

:param integer `btnid`: id of the button to remove. If more than one button with the
 same id is used in the :class:`InfoBar` (which is in any case not recommended), the last,
 i.e. most recently added, button with this `id` is removed.

Sets the duration of the animation used when showing or hiding the bar.

By default, 500ms duration is used.

:param integer `duration`: duration of the animation, in milliseconds.

Overridden base class methods changes the font of the text message.

:class:`InfoBar` overrides this method to use the font passed to it for its text
message part. By default a larger and bold version of the standard font is used.

Set the effects to use when showing and hiding the bar.

Either or both of the parameters can be set to ``wx.SHOW_EFFECT_NONE`` to disable using
effects entirely.

By default, the info bar uses ``wx.SHOW_EFFECT_SLIDE_TO_BOTTOM`` effect for showing itself
and ``wx.SHOW_EFFECT_SLIDE_TO_TOP`` for hiding if it is the first element of the containing
sizer and reverse effects if it's the last one. If it is neither the first nor the last element,
no effect is used to avoid the use of an inappropriate one and this function must be called
if an effect is desired.

:param integer `showEffect`: the effect to use when showing the bar;
:param integer `hideEffect`: the effect to use when hiding the bar.

The `showEffect` and `hideEffect` parameters can take one of the following bit:

==================================== ===========================================================
`ShowEffect` Flag                    Description
``SHOW_EFFECT_NONE``                 No effect, equivalent to normal `Show()` or `Hide()` call.
``SHOW_EFFECT_ROLL_TO_LEFT``         Roll window to the left.
``SHOW_EFFECT_ROLL_TO_RIGHT``        Roll window to the right.
``SHOW_EFFECT_ROLL_TO_TOP``          Roll window to the top.
``SHOW_EFFECT_ROLL_TO_BOTTOM``       Roll window to the bottom.
``SHOW_EFFECT_SLIDE_TO_LEFT``        Slide window to the left.
``SHOW_EFFECT_SLIDE_TO_RIGHT``       Slide window to the right.
``SHOW_EFFECT_SLIDE_TO_TOP``         Slide window to the top.
``SHOW_EFFECT_SLIDE_TO_BOTTOM``      Slide window to the bottom.
``SHOW_EFFECT_BLEND``                Fade in or out effect.
``SHOW_EFFECT_EXPAND``               Expanding or collapsing effect.

Show a message in the bar.

If the bar is currently hidden, it will be shown. Otherwise its message will be updated in place.

:param string `msg`: the text of the message;
:param integer `flags`: one of ``wx.ICON_NONE``, ``wx.ICON_INFORMATION`` (default), ``wx.ICON_QUESTION``,
 ``wx.ICON_WARNING`` or ``wx.ICON_ERROR`` values.

 :note: These flags have the same meaning as in :class:`MessageDialog` for the generic version, i.e.
  show (or not, in case of ``wx.ICON_NONE``) the corresponding icon in the bar but can be interpreted
  by the native versions. For example, the GTK+ native implementation doesn't show icons at all but
  uses this parameter to select the appropriate background colour for the notification.

Updates the parent layout appearance, but only if this :class:`InfoBar` parent is **not** managed
by :class:`framemanager` or :class:`~wx.lib.agw.aui.framemanager.AuiManager`.

For platforms supporting it (namely wxMSW and wxMAC), this method uses :class:`RendererNative`
to draw a natively-looking close button on the :class:`InfoBar` itself.

:param `win`: the window in which we wish to draw the close button (an instance of
 :class:`InfoBar`);
:param tuple `size`: the close button size, a tuple of `(width, height)` dimensions in pixels;
:param `colBg`: the background colour of the parent window, an instance of :class:`wx.Colour`;
:param integer `flags`: may have the ``wx.CONTROL_PRESSED``, ``wx.CONTROL_CURRENT`` or
 ``wx.CONTROL_ISDEFAULT`` bit set.

Returns a copy of text with newline characters inserted where long
lines should be broken such that they will fit within the given
width, with the given margin left and right, on the given `wx.DC`
using its current font settings.  By default words that are wider
than the margin-adjusted width will be broken at the nearest
character boundary, but this can be disabled by passing ``False``
for the ``breakLongWords`` parameter.

{262144: b'wxART_MISSING_IMAGE', 2048: b'wxART_INFORMATION', 1024: b'wxART_QUESTION', 256: b'wxART_WARNING', 512: b'wxART_ERROR'}

:class:`~wx.lib.agw.knobctrl.KnobCtrl` lets the user select a numerical value by rotating it.

:class:`KnobCtrl` lets the user select a numerical value by rotating it. It works like a
scrollbar: just set the ticks range property and read the value property in the
associated ``EVT_KC_ANGLE_CHANGING``/``EVT_KC_ANGLE_CHANGED`` events. Simple but
effective.

It can be easily used if you want to simulate the volume knob of a music player
or similar functionalities.

Usage
=====

    import wx
    import wx.lib.agw.knobctrl as KC

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

            knob1 = KC.KnobCtrl(panel, -1, size=(100, 100))
            knob2 = KC.KnobCtrl(panel, -1, size=(100, 100))

            knob1.SetTags(range(0, 151, 10))
            knob1.SetAngularRange(-45, 225)
            knob1.SetValue(45)

            knob2.SetTags(range(0, 151, 10))
            knob2.SetAngularRange(0, 270)
            knob2.SetValue(100)

            main_sizer.Add(knob1, 0, wx.EXPAND | wx.ALL, 20)
            main_sizer.Add(knob2, 0, wx.EXPAND | wx.ALL, 20)

            panel.SetSizer(main_sizer)

Events
======

:class:`KnobCtrl` implements two events that can be intercepted by the user:

- ``EVT_KC_ANGLE_CHANGING``;
- ``EVT_KC_ANGLE_CHANGED``.

The first one can be "vetoed" by eliminating the `event.Skip()` at the end of the
event handler.

:class:`KnobCtrl` has been tested on the following platforms:

``KC_BUFFERED_DC``         0x1 Flag to use double buffering (recommendeded = 1).

========================= ==================================================
Event Name                Description
``EVT_KC_ANGLE_CHANGED``  Notify the client that the knob has changed its value.
``EVT_KC_ANGLE_CHANGING`` Notify the client that the knob is changing its value.

:class:`KnobCtrl` is distributed under the wxPython license.

# KNOBCTRL wxPython IMPLEMENTATION
#
#
#
# TODO List
#
#
#
#
#
#

A Buffered window class.

To use it, subclass it and define a `Draw(dc)` method that takes a `dc`
to draw to. In that method, put the code needed to draw the picture
you want. The window will automatically be double buffered, and the
screen will be automatically updated when a Paint event is received.

When the drawing needs to change, you app needs to call the
:meth:`BufferedWindow.UpdateDrawing() <BufferedWindow.UpdateDrawing>` method. Since the drawing is stored in a bitmap, you
can also save the drawing to file by calling the
`SaveToFile(self, file_name, file_type)` method.

:param `agwStyle`: if set to ``KC_BUFFERED_DC``, double-buffering will
 be used.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_FULL_REPAINT_ON_RESIZE, agwStyle=KC_BUFFERED_DC)

This method should be overridden when sub-classed.

Handles the ``wx.EVT_PAINT`` event for :class:`BufferedWindow`.

Handles the ``wx.EVT_SIZE`` event for :class:`BufferedWindow`.

This would get called if the drawing needed to change, for whatever reason.

The idea here is that the drawing is based on some data generated
elsewhere in the system. If that data changes, the drawing needs to
be updated.

This class can be used to simulate a knob volume control often found in
PC music players.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=KC_BUFFERED_DC)

Converts the input values into logical `x` and `y` coordinates.

:param `radius`: the :class:`KnobCtrl` radius;
:param `angle`: the angular position of the mouse;
:param `centerX`: the `x` position of the :class:`KnobCtrl` center;
:param `centerX`: the `y` position of the :class:`KnobCtrl` center.

Draws everything on the empty bitmap.
Here all the chosen styles are applied.

Draws the :class:`KnobCtrl` bounding circle.

:param `size`: the control size.

Draw a shading of diagonal gradient to :class:`KnobCtrl`.

Draws the small knob.

:param `pencolour`: the colour to use for drawing the inset circle.

Draws the tags.

Returns the angular position based on the input logical coordinates.

:param `cx`: the `x` logical position;
:param `cy`: the `y` logical position.

Returns the angular range for :class:`KnobCtrl` as a tuple. The `start` and `end`
angles in the returned tuple are given in degrees, clockwise.

Changes the input colour by the `offset` value. Used internally.

:param `colour`: a valid :class:`wx.Colour` object;
:param `offset`: an integer value for offsetting the input colour.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`KnobCtrl`.

Sets the angular range for :class:`KnobCtrl`.

:param `start`: the starting angle, in degrees, clockwise;
:param `start`: the ending angle, in degrees, clockwise.

Sets the bounding circle colour.

Sets the first gradient colour for shading.

Sets the knob radius.

:param `radius`: the knob radius, in pixels.

Sets the second gradient colour for shading.

Sets the tags for :class:`KnobCtrl`.

:param `tags`: a list of integers ranging from `minvalue` to `maxvalue`.

Sets the tags colour.

Sets programmatically the value of :class:`KnobCtrl`.

:param `val`: an integer specifying the new :class:`KnobCtrl` value.

:note: This method does not send a :class:`KnobCtrlEvent`.

Represent details of the events that the :class:`KnobCtrl` object sends.

Sets the old :class:`KnobCtrl` value for this event.

:param `oldValue`: an integer representing the old value.

Sets the new :class:`KnobCtrl` value for this event.

:param `value`: an integer representing the new value.

:class:`~wx.lib.agw.labelbook.LabelBook` and :class:`~wx.lib.agw.labelbook.FlatImageBook` are a quasi-full generic and owner-drawn
implementations of :class:`Notebook`.

:class:`LabelBook` and :class:`FlatImageBook` are quasi-full implementations of the :class:`Notebook`,
and designed to be a drop-in replacement for :class:`Notebook`. The API functions are
similar so one can expect the function to behave in the same way.
:class:`LabelBook` anf :class:`FlatImageBook` share their appearance with :class:`Toolbook` and
:class:`Listbook`, while having more options for custom drawings, label positioning,
mouse pointing and so on. Moreover, they retain also some visual characteristics
of the Outlook address book.

- They are generic controls;
- Supports for left, right, top (:class:`FlatImageBook` only), bottom (:class:`FlatImageBook`
  only) book styles;
- Possibility to draw images only, text only or both (:class:`FlatImageBook` only);
- Support for a "pin-button", that allows the user to shrink/expand the book
  tab area;
- Shadows behind tabs (:class:`LabelBook` only);
- Gradient shading of the tab area (:class:`LabelBook` only);
- Web-like mouse pointing on tabs style (:class:`LabelBook` only);
- Many customizable colours (tab area, active tab text, tab borders, active
  tab, highlight) - :class:`LabelBook` only.

And much more. See the demo for a quasi-complete review of all the functionalities
of :class:`LabelBook` and :class:`FlatImageBook`.

Usage
=====

    import wx
    import wx.lib.agw.labelbook as LB

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

            # Possible values for Tab placement are INB_TOP, INB_BOTTOM, INB_RIGHT, INB_LEFT

            notebook = LB.LabelBook(self, -1, agwStyle=LB.INB_FIT_LABELTEXT|LB.INB_LEFT|LB.INB_DRAW_SHADOW|LB.INB_GRADIENT_BACKGROUND)

            pane1 = wx.Panel(notebook)
            pane2 = wx.Panel(notebook)

            imagelist = wx.ImageList(32, 32)
            imagelist.Add(wx.Bitmap("my_bitmap.png", wx.BITMAP_TYPE_PNG))
            notebook.AssignImageList(imagelist)

            notebook.AddPage(pane_1, "Tab1", 1, 0)
            notebook.AddPage(pane_2, "Tab2", 0, 0)

:class:`LabelBook` and :class:`FlatImageBook` have been tested on the following platforms:

``INB_BOTTOM``                      0x1 Place labels below the page area. Available only for :class:`FlatImageBook`.
``INB_LEFT``                        0x2 Place labels on the left side. Available only for :class:`FlatImageBook`.
``INB_RIGHT``                       0x4 Place labels on the right side.
``INB_TOP``                         0x8 Place labels above the page area.
``INB_BORDER``                     0x10 Draws a border around :class:`LabelBook` or :class:`FlatImageBook`.
``INB_SHOW_ONLY_TEXT``             0x20 Shows only text labels and no images. Available only for :class:`LabelBook`.
``INB_SHOW_ONLY_IMAGES``           0x40 Shows only tab images and no label texts. Available only for :class:`LabelBook`.
``INB_FIT_BUTTON``                 0x80 Displays a pin button to show/hide the book control.
``INB_DRAW_SHADOW``               0x100 Draw shadows below the book tabs. Available only for :class:`LabelBook`.
``INB_USE_PIN_BUTTON``            0x200 Displays a pin button to show/hide the book control.
``INB_GRADIENT_BACKGROUND``       0x400 Draws a gradient shading on the tabs background. Available only for :class:`LabelBook`.
``INB_WEB_HILITE``                0x800 On mouse hovering, tabs behave like html hyperlinks. Available only for :class:`LabelBook`.
``INB_NO_RESIZE``                0x1000 Don't allow resizing of the tab area.
``INB_FIT_LABELTEXT``            0x2000 Will fit the tab area to the longest text (or text+image if you have images) in all the tabs.
``INB_BOLD_TAB_SELECTION``       0x4000 Show the selected tab text using a bold font.

=================================== ==================================================
``EVT_IMAGENOTEBOOK_PAGE_CHANGED``  Notify client objects when the active page in :class:`FlatImageBook` or :class:`LabelBook` has changed.
``EVT_IMAGENOTEBOOK_PAGE_CHANGING`` Notify client objects when the active page in :class:`FlatImageBook` or :class:`LabelBook` is about to change.
``EVT_IMAGENOTEBOOK_PAGE_CLOSED``   Notify client objects when a page in :class:`FlatImageBook` or :class:`LabelBook` has been closed.
``EVT_IMAGENOTEBOOK_PAGE_CLOSING``  Notify client objects when a page in :class:`FlatImageBook` or :class:`LabelBook` is closing.

TODOs
=====

- :class:`LabelBook`: support ``IMB_SHOW_ONLY_IMAGES``;
- :class:`LabelBook`: an option to only draw the border between the controls and the pages so the background
  colour can flow into the window background.

:class:`LabelBook` and :class:`FlatImageBook` are distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 22 Jan 2013, 21.00 GMT

Version 0.6.

# LABELBOOK And FLATIMAGEBOOK Widgets wxPython IMPLEMENTATION
#
# Original C++ Code From Eran, embedded in the FlatMenu source code
#
#
#
#
#
# Latest Revision: 22 Jan 2013, 21.00 GMT
#
#
#
#
#
# TODO:
# LabelBook - Support IMB_SHOW_ONLY_IMAGES
# LabelBook - An option to only draw the border
#             between the controls and the pages so the background
#             colour can flow into the window background
#
#
#

Base class for the containing window for :class:`LabelBook` and :class:`FlatImageBook`. 

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="FlatBookBase")

Adds a page to the book.

Assigns an image list to the control.

Changes the selection for the given page, returning the previous selection.

:param `page`: an integer specifying the page to be selected.

:note: The call to this function does not generate the page changing events.

:param `page`: an integer specifying the page to be deleted.

Select the window by the provided pointer.

Returns the :class:`FlatBookBase` window style.

:see: :meth:`~FlatBookBase.SetAGWWindowStyleFlag` for a list of possible window style flags.

Returns the window at the given page position.

:param `page`: an integer specifying the page to be returned.

Returns the text for the given page.

Returns whether a flag is present in the :class:`FlatBookBase` style.

:param `flag`: one of the possible :class:`FlatBookBase` window styles.

Inserts a page into the book at the specified position.

:param `page_idx`: specifies the position for the new page;

InsertPage(self, page_idx, page, text, select=False, imageId=-1)

Handles the ``wx.EVT_NAVIGATION_KEY`` event for :class:`FlatBookBase`.

:param `page`: an integer specifying the page to be removed.

Resizes the tab area if the control has the ``INB_FIT_LABELTEXT`` style set. 

Sets the window style.

:param `agwStyle`: can be a combination of the following bits:

Sets whether the page captions are bold or not.

:param `bold`: ``True`` or ``False``.

Sets the font size multiple for the page captions.

:param `multiple`: The multiple to be applied to the system font to get the our font size.

:param `image`: an index into the image list.

Changes the selection from currently visible/selected page to the page
given by page.

Default implementation of the image book, it is like a :class:`Notebook`, except that
images are used to control the different pages. This container is usually used
for configuration dialogs etc.

:note: Currently, this control works properly for images of size 32x32 and bigger.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="FlatImageBook")

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="ImageContainer")

Allows the parent to examine the children type. Some implementation
(such as :class:`LabelBook`), does not support top/bottom images, only left/right.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_MOTION`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_PAINT`` event for :class:`wx.ImageContainer`.

Handles the ``wx.EVT_SIZE`` event for :class:`wx.ImageContainer`.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="ImageContainerBase")

Adds a page to the container.

:param `caption`: specifies the text for the new tab;
:param `selected`: specifies whether the page should be selected;
:param `imgIdx`: specifies the optional image index for the new tab.

Assigns an image list to the :class:`wx.ImageContainerBase`.

Removes flag from the style.

:param `flag`: a window style flag.

:see: :meth:`~ImageContainerBase.HasAGWFlag` for a list of possible window style flags.

:param `page`: the index of the tab.

Draw a pin button, that allows collapsing of the image panel.

:param `rect`: the pin button client rectangle;
:param `downPin`: ``True`` if the pin button is facing downwards, ``False``
 if it is facing leftwards.

Fixes the text, to fit `maxWidth` value. If the text length exceeds
`maxWidth` value this function truncates it and appends two dots at
the end. ("Long Long Long Text" might become "Long Long...").

:param `text`: the text to fix/truncate;
:param `maxWidth`: the maximum allowed width for the text, in pixels.

Returns the image size inside the :class:`wx.ImageContainerBase` image list. 

Returns the tab caption for the given page.

Tests for existence of flag in the style.

:param `flag`: a window style. This can be a combination of the following bits:

Returns the index of the tab at the specified position or ``wx.NOT_FOUND``
if ``None``, plus the flag style of :meth:`~ImageContainerBase.HitTest`.

:return: The index of the tab at the specified position plus the hit test
 flag, which can be one of the following bits:

 ====================== ======= ================================
 HitTest Flags           Value  Description
 ``IMG_OVER_IMG``             0 The mouse is over the tab icon
 ``IMG_OVER_PIN``             1 The mouse is over the pin button
 ``IMG_OVER_EW_BORDER``       2 The mouse is over the east-west book border
 ``IMG_NONE``                 3 Nowhere

Inserts a page into the container at the specified position.

:param `page_idx`: specifies the position for the new tab;

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`wx.ImageContainerBase`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`wx.ImageContainerBase`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`wx.ImageContainerBase`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`wx.ImageContainerBase`.

Handles the ``wx.EVT_MOTION`` event for :class:`wx.ImageContainerBase`.

Handles the ``wx.EVT_SIZE`` event for :class:`wx.ImageContainerBase`.

Tests whether pt is located on the sash.

Sets the image for the given page.

:param `page`: the index of the tab;
:param `imgIdx`: specifies the optional image index for the tab.

Sets the tab caption for the given page.

:param `text`: the new tab caption.

single tab in :class:`LabelBook`.

:param `strCaption`: the tab caption;
:param `imageIndex`: the tab image index based on the assigned (set)

:param `value`: an index into the image list..

:param `value`: the new tab position, an instance of :class:`wx.Point`.

:param `value`:  the new tab size, an instance of :class:`wx.Size`.

Sets the client rectangle available for the tab text.

:param `rect`: the tab text client rectangle, an instance of :class:`wx.Rect`.

This events will be sent when a ``EVT_IMAGENOTEBOOK_PAGE_CHANGED``,
``EVT_IMAGENOTEBOOK_PAGE_CHANGING``, ``EVT_IMAGENOTEBOOK_PAGE_CLOSING``,
``EVT_IMAGENOTEBOOK_PAGE_CLOSED`` is mapped in the parent.

:param `sel`: the current selection;
:param `oldsel`: the old selection.

This is the opposite of :meth:`~ImageNotebookEvent.Veto`: it explicitly allows the event to be processed.

Returns ``True`` if the change is allowed (:meth:`~ImageNotebookEvent.Veto` hasn't been called) or

Sets the event old selection.

:param `s`: an integer specifying the old selection.

:param `s`: an integer specifying the new selection.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="LabelContainer")

Draws a bitmap as the background of the control.

Draws a label using the specified dc.

:param `rect`: the text client rectangle;
:param `text`: the actual text string;
:param `bmp`: a bitmap to be drawn next to the text;
:param `imgInfo`: an instance of :class:`wx.ImageInfo`;
:param `orientationLeft`: ``True`` if the book has the ``INB_RIGHT`` or ``INB_LEFT``
 style set;
:param `imgIdx`: the tab image index;
:param `selected`: ``True`` if the tab is selected, ``False`` otherwise;
:param `hover`: ``True`` if the tab is being hovered with the mouse, ``False`` otherwise.

DrawLabel(self, dc, rect, text, bmp, imgInfo, orientationLeft, imgIdx, selected, hover)

Draws a rounded rectangle around the current tab.

:param `rect`: the current tab client rectangle.

Draws a web style hover effect (cursor set to hand & text is underlined).

:param `caption`: the tab caption text;
:param `xCoord`: the x position of the tab caption;
:param `yCoord`: the y position of the tab caption;
:param `selected`: ``True`` if the tab is selected, ``False`` otherwise.

Returns a colour for a parameter.

:see: :meth:`~LabelContainer.SetColour` for a list of valid colour keys.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_MOTION`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_PAINT`` event for :class:`LabelContainer`.

Handles the ``wx.EVT_SIZE`` event for :class:`LabelContainer`.

Actually resizes the tab area.

:param `event`: an instance of :class:`wx.SizeEvent`.

Sets the background bitmap for the control.

Sets a colour for a parameter.

:param `which`: can be one of the following parameters:

 ================================== ======= ==================================
 Colour Key                          Value  Description
 ``INB_TAB_AREA_BACKGROUND_COLOUR``     100 The tab area background colour
 ``INB_ACTIVE_TAB_COLOUR``              101 The active tab background colour
 ``INB_TABS_BORDER_COLOUR``             102 The tabs border colour
 ``INB_TEXT_COLOUR``                    103 The tab caption text colour
 ``INB_ACTIVE_TEXT_COLOUR``             104 The active tab caption text colour
 ``INB_HILITE_TAB_COLOUR``              105 The tab caption highlight text colour

Sets the width of the tab area.

:param `width`: the width of the tab area, in pixels.

This class represents a possible replacement for :class:`DirDialog`, with the additional
ability of selecting multiple folders at once.

ability of selecting multiple folders at once. It may be useful when you wish to
present to the user a directory browser which allows multiple folder selections.
:class:`MultiDirDialog` sports the following features:

* Ability to select a single or multiple folders, depending on the style passed;
* More colourful and eye-catching buttons;

Usage
=====

    import os
    import wx

    import wx.lib.agw.multidirdialog as MDD

    dlg = MDD.MultiDirDialog(None, title="Custom MultiDirDialog", defaultPath=os.getcwd(),
                             agwStyle=MDD.DD_MULTIPLE|MDD.DD_DIR_MUST_EXIST)

    if dlg.ShowModal() != wx.ID_OK:
        print("You Cancelled The Dialog!")
        dlg.Destroy()
        return

    paths = dlg.GetPaths()
    for indx, path in enumerate(paths):
        print("Path %d: %s"%(indx+1, path))

:class:`MultiDirDialog` has been tested on the following platforms:

===================== =========== ==================================================
Window Styles         Hex Value   Description
``DD_NEW_DIR_BUTTON``       0x080 Enable/disable the "Make new folder" button
``DD_DIR_MUST_EXIST``       0x200 The dialog will allow the user to choose only an existing folder. When this style is not given, a "Create new directory" button is added to the dialog (on Windows) or some other way is provided to the user to type the name of a new folder.
``DD_MULTIPLE``             0x400 Allows the selection of multiple folders.

:class:`MultiDirDialog` is distributed under the wxPython license.

# MULTIDIRDIALOG wxPython IMPLEMENTATION
#
#
#
# TODO List
#
# 1) Implement an meaningful action for the "Make New Folder" button, but this
#    requires a strong integration with Explorer, at least on Windows;
#
# 2) Be more user-friendly with special folders as the Desktop, My Documents etc...
#
#
#
#
#
#

A different implementation of :class:`DirDialog` which allows multiple
folders to be selected at once.

:param `parent`: the dialog parent widget;
:param `message`: the message to show on the dialog;
:param `title`: the dialog title;
:param `defaultPath`: the default path, or the empty string;
:param `style`: the underlying :class:`Dialog` window style;
:param `agwStyle`: the AGW-specific dialog style; this can be a combination of the

 ===================== =========== ==================================================
 Window Styles         Hex Value   Description
 ``DD_NEW_DIR_BUTTON``       0x080 Enable/disable the "Make new folder" button
 ``DD_DIR_MUST_EXIST``       0x200 The dialog will allow the user to choose only an existing folder. When this style is not given, a "Create new directory" button is added to the dialog (on Windows) or some other way is provided to the user to type the name of a new folder.
 ``DD_MULTIPLE``             0x400 Allows the selection of multiple folders.

:param `pos`: the dialog position;
:param `name`: the dialog name.

__init__(self, parent, message=_("Choose one or more folders:"), title=_("Browse For Folders"), defaultPath="", style=wx.DD_DEFAULT_STYLE, agwStyle=DD_MULTIPLE, pos=wx.DefaultPosition, size=wx.DefaultSize, name="multidirdialog")

Creates the ``OK``, ``Cancel`` and ``Make New Folder`` bitmap buttons. 

Handles the ``wx.EVT_BUTTON`` event for the dialog.

:note: This method handles the ``Cancel`` button press.

Handles the ``wx.EVT_CLOSE`` event for the dialog.

Handles the ``wx.EVT_CHAR_HOOK`` event for the dialog.

:note: This method handles the ``OK`` button press.

Handles the ``wx.EVT_TREE_SEL_CHANGED`` event for the tree control associated
with :class:`MultiDirDialog`.

:param `event`: a :class:`TreeEvent` event to be processed.

Sets few properties for the dialog.

:param `title`: the dialog title.

Setup the internal :class:`GenericDirCtrl` (icons, labels, etc...).

:param `defaultPath`: the default path for :class:`MultiDirDialog`, can be an
 empty string.

:class:`~wx.lib.agw.peakmeter.PeakMeterCtrl` mimics the behaviour of equalizers that are usually found in stereos
and MP3 players.

:class:`PeakMeterCtrl` mimics the behaviour of equalizers that are usually found in stereos
and MP3 players. This widgets supports:

* Vertical and horizontal led bands;
* Settings number of bands and leds per band;
* Possibility to change the colour for low/medium/high band frequencies;
* Falloff effects;
* Showing a background grid for the bands.

Usage
=====

    import wx
    import random

    import wx.lib.agw.peakmeter as PM

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

            # Initialize Peak Meter control 1
            self.vertPeak = PM.PeakMeterCtrl(panel, -1, style=wx.SIMPLE_BORDER, agwStyle=PM.PM_VERTICAL)
            # Initialize Peak Meter control 2
            self.horzPeak = PM.PeakMeterCtrl(panel, -1, style=wx.SUNKEN_BORDER, agwStyle=PM.PM_HORIZONTAL)

            self.vertPeak.SetMeterBands(10, 15)
            self.horzPeak.SetMeterBands(10, 15)

            # Layout the two PeakMeterCtrl
            mainSizer = wx.BoxSizer(wx.HORIZONTAL)
            mainSizer.Add(self.vertPeak, 0, wx.EXPAND | wx.ALL, 15)
            mainSizer.Add(self.horzPeak, 0, wx.EXPAND | wx.ALL, 15)

            panel.SetSizer(mainSizer)
            mainSizer.Layout()

            self.timer = wx.Timer(self)
            self.Bind(wx.EVT_TIMER, self.OnTimer)

            wx.CallLater(500, self.Start)

        def Start(self):
            ''' Starts the PeakMeterCtrl. '''

            self.timer.Start(1000//2)            # 2 fps

            self.vertPeak.Start(1000//18)        # 18 fps
            self.horzPeak.Start(1000//20)        # 20 fps

        def OnTimer(self, event):
            '''
            Handles the ``wx.EVT_TIMER`` event for :class:`PeakMeterCtrl`.

            :param `event`: a :class:`TimerEvent` event to be processed.
            '''

            # Generate 15 random number and set them as data for the meter
            nElements = 15
            arrayData = []

            for i in xrange(nElements):
                nRandom = random.randint(0, 100)
                arrayData.append(nRandom)

            self.vertPeak.SetData(arrayData, 0, nElements)
            self.horzPeak.SetData(arrayData, 0, nElements)

:class:`PeakMeterCtrl` has been tested on the following platforms:

======================== =========== ========================================================
Window Styles            Hex Value   Description
``PM_HORIZONTAL``        0x0         Shows horizontal bands in :class:`PeakMeterCtrl`.
``PM_VERTICAL``          0x1         Shows vertical bands in :class:`PeakMeterCtrl`.
``PM_VERTICAL_INVERTED`` 0x2         Shows inverted vertical bands in :class:`PeakMeterCtrl`.

:class:`PeakMeterCtrl` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 31 Jul 2014, 21.00 GMT

# PEAKMETERCTRL wxPython IMPLEMENTATION
#
# Latest Revision: 31 Jul 2014, 21.00 GMT
#
#
# TODO List
#
# 1) Possibly some nicer drawing of bands and leds (using GraphicsContext).
#
#
#
#
#
#

:param parent: the :class:`PeakMeterCtrl` parent. Must not be ``None``
:param `style`: the underlying :class:`wx.Control` window style;
:param `agwStyle`: the AGW-specific window style, which can be one of the following bits:

 ======================== =========== ========================================================
 Window Styles            Hex Value   Description
 ``PM_HORIZONTAL``        0x0         Shows horizontal bands in :class:`PeakMeterCtrl`.
 ``PM_VERTICAL``          0x1         Shows vertical bands in :class:`PeakMeterCtrl`.
 ``PM_VERTICAL_INVERTED`` 0x2         Shows inverted vertical bands in :class:`PeakMeterCtrl`.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=PM_VERTICAL)

:class:`PeakMeterCtrl` animation, does the ``wx.EVT_TIMER`` processing. 

Draws horizontal bands.

:param `rect`: the horizontal bands client rectangle.

.. todo:: Implement falloff effect for horizontal bands.

Draws vertical bands.

:param `rect`: the vertical bands client rectangle.

Draws vertical bands inverted.

Returns the :class:`PeakMeterCtrl` window style.

:see: :meth:`PeakMeterCtrl.SetAGWWindowStyleFlag` for a list of possible window style flags.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`PeakMeterCtrl`.

Handles the ``wx.EVT_PAINT`` event for :class:`PeakMeterCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`PeakMeterCtrl`.

Handles the ``wx.EVT_TIMER`` event for :class:`PeakMeterCtrl`.

Sets the :class:`PeakMeterCtrl` window style flags.

Changes the background colour of :class:`PeakMeterCtrl`.

:param `colourBgnd`: the colour to be used as the background colour, pass

Set bands colour for :class:`PeakMeterCtrl`.

:param `colourNormal`: the colour for normal (low) bands, a valid :class:`wx.Colour`
 object;
:param `colourMedium`: the colour for medium bands, a valid :class:`wx.Colour`
 object;
:param `colourHigh`: the colour for high bands, a valid :class:`wx.Colour`
 object.

Change data value. Use this function to change only
a set of values. All bands can be changed or only 1 band,
depending on the application.

:param `arrayValue`: a Python list containing the :class:`PeakMeterData` values;
:param `offset`: the (optional) offset where to start applying the new data;
:param `size`: the size of the input data.

Set peak value speed before falling off.

:param `speed`: the speed at which the falloff happens.

Set falloff effect flag.

:param `falloffEffect`: ``True`` to enable the falloff effect, ``False``

Set number of vertical or horizontal bands to display.

:param `numBands`: number of bands to display (either vertical or horizontal);
:param `ledBands`: the number of leds per band.

:note: You can obtain a smooth effect by setting `nHorz` or `nVert` to "1", these
 cannot be 0.

Sets the ranges for low, medium and high bands.

:param `minVal`: the value for low bands;
:param `medVal`: the value for medium bands;
:param `maxVal`: the value for high bands.

:note: The conditions to be satisfied are:

 Min: [0 - nMin[,  Med: [nMin - nMed[,  Max: [nMed - nMax]

Request to have gridlines visible or not.

:param `showGrid`: ``True`` to show grid lines, ``False`` otherwise.

Start the timer and animation effect.

:param `delay`: the animation effect delay, in milliseconds.

A simple class which holds data for our :class:`PeakMeterCtrl`. 

:param `value`: the current :class:`PeakMeterCtrl` value;
:param `falloff`: the falloff effect. ``True`` to enable it, ``False`` to
 disable it;
:param `peak`: the peak value.

Returns whether 2 instances of :class:`PeakMeterData` are the same.

:param `pm`: another instance of :class:`PeakMeterData`.

Returns whether one :class:`PeakMeterData` is greater than another.

Returns whether one :class:`PeakMeterData` is smaller than another.

Darkens a colour.

:param `crColour`: a valid :class:`wx.Colour` object;
:param `byReduceVal`: an integer specifying the amount for which the input
 colour should be darkened.

Returns whether the value `val` is between `valMin` and `valMax`.

:param `val`: the value to test;
:param `valMin`: the minimum range value;
:param `valMax`: the maximum range value.

Lightens a colour.

:param `byIncreaseVal`: an integer specifying the amount for which the input
 colour should be brightened.

:class:`~wx.lib.agw.piectrl.PieCtrl` and :class:`~wx.lib.agw.piectrl.ProgressPie` are simple classes that reproduce the behavior of a pie
chart.

:class:`PieCtrl` and :class:`ProgressPie` are simple classes that reproduce the behavior of a pie
chart. They use only pure wxPython classes/methods, without external dependencies.
:class:`PieCtrl` is somewhat a "static" control, that you may create in order to display
a simple pie chart on a :class:`Panel` or similar. :class:`ProgressPie` tries to emulate the
behavior of :class:`ProgressDialog`, but using a pie chart instead of a gauge.

Usage
=====

    import wx
    import wx.lib.agw.piectrl as PC

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

            # create a simple PieCtrl with 3 sectors
            mypie = PC.PieCtrl(panel, -1, wx.DefaultPosition, wx.Size(180,270))

            part = PC.PiePart()

            part.SetLabel("Label 1")
            part.SetValue(300)
            part.SetColour(wx.Colour(200, 50, 50))
            mypie._series.append(part)

            part.SetLabel("Label 2")
            part.SetValue(200)
            part.SetColour(wx.Colour(50, 200, 50))

            part.SetLabel("helloworld label 3")
            part.SetValue(50)
            part.SetColour(wx.Colour(50, 50, 200))

            # create a ProgressPie
            progress_pie = PC.ProgressPie(panel, 100, 50, -1, wx.DefaultPosition,
                                          wx.Size(180, 200), wx.SIMPLE_BORDER)

            progress_pie.SetBackColour(wx.Colour(150, 200, 255))
            progress_pie.SetFilledColour(wx.RED)
            progress_pie.SetUnfilledColour(wx.WHITE)
            progress_pie.SetHeight(20)

            main_sizer = wx.BoxSizer(wx.HORIZONTAL)

            main_sizer.Add(mypie, 1, wx.EXPAND | wx.ALL, 5)
            main_sizer.Add(progress_pie, 1, wx.EXPAND | wx.ALL, 5)

With :class:`PieCtrl` you can:

- Create a :class:`PieCtrl` with different sectors;
- Set the sector values, colours and labels;
- Assign a legend to the :class:`PieCtrl`;
- Use an image as the :class:`PieCtrl` background;
- Change the vertical rotation (perspective) of the :class:`PieCtrl`;
- Show/hide the segment edges.

:class:`PieCtrl` is distributed under the wxPython license.

# PIECTRL Control wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 31 Oct 2005
#
#
#
# 1. Maybe Integrate The Very Nice PyOpenGL Implementation Of A PieChart Coded
#    By Will McGugan?
#
# 2. Not Tested On Other Platforms, Only On Windows 2000/XP, With Python 2.4.1
#    And wxPython 2.6.1.0
#
#
#
#
#

a simple pie chart on a :class:`Panel` or similar.

:param `parent`: the :class:`PieCtrl` parent. Must not be ``None``;
:param `style`: the window style (unused);

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="PieCtrl")

Draws all the sectors of :class:`PieCtrl`.

Draws the :class:`PieCtrl` external edges.

:param `cx`: the part `x` coordinate;
:param `cy`: the part `y` coordinate;
:param `w`: the control's width;
:param `h`: the control's height.

Returns the orientation angle for :class:`PieCtrl`, in radians. 

Returns the angle at which the first sector starts, in radians. 

Handles the ``wx.EVT_PAINT`` event for :class:`PieCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`PieCtrl`.

Sets the orientation angle for :class:`PieCtrl`.

:param `angle`: the orientation angle for :class:`PieCtrl`, in radians.

Sets the :class:`PieCtrl` background colour.

Sets the :class:`PieCtrl` background image.

Sets the height (in pixels) of the :class:`PieCtrl`.

:param `value`: the new height of the widget, in pixels.

Sets the angle at which the first sector starts.

:param `angle`: the first sector angle, in radians.

Sets whether the :class:`PieCtrl` edges are visible or not.

:param `value`: ``True`` to show the edges, ``False`` to hide them.

This class displays a legend window for the classic :class:`PieCtrl`.

:param `parent`: the :class:`PieCtrlLegend` parent;
:param `title`: the legend title;
:param `style`: the window style (unused).

__init__(self, parent, title, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0)

Handles the ``wx.EVT_PAINT`` event for :class:`PieCtrlLegend`.

Recreates the legend background.

:param `parentdc`: an instance of :class:`wx.DC`.

Sets the legend background colour.

Sets the legend's horizontal border.

:param `value`: the horizontal border thickness, in pixels.

Sets the legend label colour.

Sets the legend label font.

Toggles the legend transparency (visibility).

:param `value`: ``True`` to set the legend as transparent, ``False`` otherwise.

Sets the legend's vertical border.

This class handles the legend segments properties, such as value,
colour and label.

:param `value`: the pie part value;
:param `colour`: the pie part colour;
:param `label`: the pie part text label.

Sets the segment colour.

Sets the segment label.

Sets the segment absolute value.

:param `value`: a floating point number representing the :class:`PiePart` value.

:class:`ProgressPie` tries to emulate the behavior of :class:`ProgressDialog`, but
using a pie chart instead of a gauge.

__init__(self, parent, maxvalue, value, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0)

Returns the colour that progressively fills the :class:`ProgressPie`. 

Sets the colour that progressively fills the :class:`ProgressPie` .

Sets the :class:`ProgressPie` maximum value.

:param `value`: a floating point number representing the maximum value.

Sets the colour that is filled.

Sets the :class:`ProgressPie` value.

:param `value`: a floating point number representing the new value.

:class:`~wx.lib.agw.pybusyinfo.PyBusyInfo` constructs a busy info window and displays a message in it.

:class:`PyBusyInfo` constructs a busy info window and displays a message in it.

This class makes it easy to tell your user that the program is temporarily busy.
Just create a :class:`PyBusyInfo` object, and within the current scope, a message window
will be shown.

    busy = PyBusyInfo("Please wait, working...")

    for i in xrange(10000):
        DoACalculation()

    del busy

It works by creating a window in the constructor, and deleting it in the destructor.
You may also want to call :func:`Yield` () to refresh the window periodically (in case
it had been obscured by other windows, for example).

Usage
=====

    import wx
    import wx.lib.agw.pybusyinfo as PBI

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

            b = wx.Button(panel, -1, "Test PyBusyInfo ", (50,50))
            self.Bind(wx.EVT_BUTTON, self.OnButton, b)

            message = "Please wait 5 seconds, working..."
            busy = PBI.PyBusyInfo(message, parent=self, title="Really Busy")

            wx.Yield()

            for indx in xrange(5):
                wx.MilliSleep(1000)

            del busy

:class:`PyBusyInfo` has been tested on the following platforms:

:class:`PyBusyInfo` is distributed under the wxPython license.

# PYBUSYINFO Control wxPython IMPLEMENTATION
# Inspired By And Heavily Based On wxBusyInfo.
#
#
# Andrea Gavana, @ 10 December 2009
#
#
#
# 1. ?
#
#
#
#
#
#

Constructs a busy info window as child of parent and displays a message in it.

:param `parent`: the :class:`PyBusyInfo` parent;
:param `message`: the message to display in the :class:`PyBusyInfo`;
:param `title`: the main :class:`PyBusyInfo` title;
:param `icon`: an icon to draw as the frame icon, an instance of :class:`wx.Bitmap`.

:note: If `parent` is not ``None`` you must ensure that it is not closed
 while the busy info is shown.

__init__(self, message, parent=None, title=_("Busy"), icon=wx.NullBitmap)

Shows or hides the window.

You may need to call `Raise` for a top level window if you want to bring it to
top, although this is not needed if :meth:`PyBusyInfo.Show` is called immediately after the frame creation.

:param bool `show`: ``True`` to show the :class:`PyBusyInfo` frame, ``False`` to hide it.

:return: ``True`` if the window has been shown or hidden or ``False`` if nothing was done
 because it already was in the requested state.

.. note::

   Notice that the default state of newly created top level windows is hidden (to allow
   you to create their contents without flicker) unlike for all the other, not derived from
   :class:`TopLevelWindow`, windows that are by default created in the shown state.

Calling this method immediately repaints the invalidated area of the window and all of its
children recursively (this normally only happens when the flow of control returns to the
event loop).

:note: Notice that this function doesn't invalidate any area of the window so nothing happens
 if nothing has been invalidated (i.e. marked as requiring a redraw). Use `Refresh` first if
 you want to immediately redraw the window unconditionally.

:param `parent`: the frame parent;

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`PyInfoFrame`.

Handles the ``wx.EVT_PAINT`` event for :class:`PyInfoFrame`.

Sets :class:`PyInfoFrame` shape using the region created from the bitmap.

:class:`~wx.lib.agw.pycollapsiblepane.PyCollapsiblePane` is a container with an embedded button-like control which
can be used by the user to collapse or expand the pane's contents.

A collapsible pane is a container with an embedded button-like control which
Once constructed you should use the :meth:`~PyCollapsiblePane.GetPane` function to access the pane and
add your controls inside it (i.e. use the window returned from :meth:`~PyCollapsiblePane.GetPane` as the
parent for the controls which must go in the pane, **not** the :class:`PyCollapsiblePane`
itself!).

:note: Note that because of its nature of control which can dynamically (and drastically)
 change its size at run-time under user-input, when putting :class:`PyCollapsiblePane`
 inside a :class:`wx.Sizer` you should be careful to add it with a proportion value of zero;
 this is because otherwise all other windows with non-null proportion values would
 automatically get resized each time the user expands or collapse the pane window
 resulting usually in a weird, flickering effect.

Usage
=====

    import wx
    import wx.lib.agw.pycollapsiblepane as PCP

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

            title = wx.StaticText(panel, label="PyCollapsiblePane")
            title.SetFont(wx.Font(18, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD))
            title.SetForegroundColour("blue")

            self.cp = cp = PCP.PyCollapsiblePane(panel, label="Some Data",
                                                 style=wx.CP_DEFAULT_STYLE | wx.CP_NO_TLW_RESIZE)

            self.MakePaneContent(cp.GetPane())

            sizer.Add(title, 0, wx.ALL, 25)
            sizer.Add(cp, 0, wx.RIGHT | wx.LEFT | wx.EXPAND, 25)

            sizer.Layout()

        def MakePaneContent(self, pane):
            ''' Just makes a few controls to put on `PyCollapsiblePane`. '''

            nameLbl = wx.StaticText(pane, -1, "Name:")
            name = wx.TextCtrl(pane, -1, "");

            addrLbl = wx.StaticText(pane, -1, "Address:")
            addr1 = wx.TextCtrl(pane, -1, "");
            addr2 = wx.TextCtrl(pane, -1, "");

            cstLbl = wx.StaticText(pane, -1, "City, State, Zip:")
            city  = wx.TextCtrl(pane, -1, "", size=(150,-1));
            state = wx.TextCtrl(pane, -1, "", size=(50,-1));
            zip   = wx.TextCtrl(pane, -1, "", size=(70,-1));

            addrSizer = wx.FlexGridSizer(cols=2, hgap=5, vgap=5)
            addrSizer.AddGrowableCol(1)
            addrSizer.Add(nameLbl, 0,
                          wx.ALIGN_RIGHT | wx.ALIGN_CENTER_VERTICAL)
            addrSizer.Add(name, 0, wx.EXPAND)
            addrSizer.Add(addrLbl, 0,
            addrSizer.Add(addr1, 0, wx.EXPAND)
            addrSizer.Add((5,5))
            addrSizer.Add(addr2, 0, wx.EXPAND)

            addrSizer.Add(cstLbl, 0,

            cstSizer = wx.BoxSizer(wx.HORIZONTAL)
            cstSizer.Add(city, 1)
            cstSizer.Add(state, 0, wx.LEFT | wx.RIGHT, 5)
            cstSizer.Add(zip)
            addrSizer.Add(cstSizer, 0, wx.EXPAND)

            border = wx.BoxSizer()
            border.Add(addrSizer, 1, wx.EXPAND | wx.ALL, 5)
            pane.SetSizer(border)

``CP_NO_TLW_RESIZE``         0x2 By default :class:`PyCollapsiblePane` resizes the top level window containing it when its own size changes. This allows to easily implement dialogs containing an optionally shown part, for example, and so is the default behaviour but can be inconvenient in some specific cases -- use this flag to disable this automatic parent resizing then.
``CP_GTK_EXPANDER``          0x4 Uses a GTK expander instead of a button.
``CP_USE_STATICBOX``         0x8 Uses a :class:`StaticBox` around :class:`PyCollapsiblePane`.
``CP_LINE_ABOVE``           0x10 Draws a line above :class:`PyCollapsiblePane`.

=============================== ==================================================
Event Name                      Description
``EVT_COLLAPSIBLEPANE_CHANGED`` The user showed or hid the collapsible pane.

:class:`PyCollapsiblePane` is distributed under the wxPython license.

# PYCOLLAPSIBLEPANE wxPython IMPLEMENTATION
# Generic Implementation Based On wx.CollapsiblePane.
#
# Andrea Gavana, @ 09 Aug 2007
#
#
#
#
#
#

A :class:`GTKExpander` allows the user to hide or show its child by clicking on an expander
triangle.

:param `parent`: the :class:`GTKExpander` parent. Must not be ``None``;
:param `label`: the expander text label;
:param `style`: the expander style.

__init__(self, parent, id=wx.ID_ANY, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER)

Draws the :class:`GTKExpander` triangle.

Draws the :class:`GTKExpander` text label.

Handles the ``wx.EVT_SIZE`` event for :class:`GTKExpander`.

:class:`PyCollapsiblePane` is a container with an embedded button-like control which

:param `parent`: the :class:`PyCollapsiblePane` parent. Must not be ``None``;
:param `label`: The initial label shown in the button which allows the
 user to expand or collapse the pane window.
:param `agwStyle`: the AGW-specifi window style. This can be a combination of the

 ``CP_NO_TLW_RESIZE``         0x2 By default :class:`PyCollapsiblePane` resizes the top level window containing it when its own size changes. This allows to easily implement dialogs containing an optionally shown part, for example, and so is the default behaviour but can be inconvenient in some specific cases -- use this flag to disable this automatic parent resizing then.
 ``CP_GTK_EXPANDER``          0x4 Uses a GTK expander instead of a button.
 ``CP_USE_STATICBOX``         0x8 Uses a :class:`StaticBox` around :class:`PyCollapsiblePane`.
 ``CP_LINE_ABOVE``           0x10 Draws a line above :class:`PyCollapsiblePane`.

:param `validator`: the validator associated to the :class:`PyCollapsiblePane`;
:param `name`: the widget name.

__init__(self, parent, id=wx.ID_ANY, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=wx.CP_DEFAULT_STYLE, validator=wx.DefaultValidator, name="PyCollapsiblePane")

Collapses or expands the pane window.

:param `collapse`: ``True`` to collapse the pane window, ``False`` to expand it.

Returns the :class:`PyCollapsiblePane` window style.

:see: :meth:`~PyCollapsiblePane.SetAGWWindowStyleFlag` for a list of possible window style flags.

Returns the :class:`PyCollapsiblePane` border in pixels (platform dependent). 

Returns the expander dimensions, a tuple of integers representing the
width and height of the expander, in pixels.

Returns the button label.

Returns a reference to the pane window. Use the returned :class:`wx.Window` as
the parent of widgets to make them part of the collapsible area.

Returns whether a flag is present in the :class:`PyCollapsiblePane` style.

:param `flag`: one of the possible :class:`PyCollapsiblePane` window styles.

Handles the ``wx.EVT_BUTTON`` event for :class:`PyCollapsiblePane`.

Overridable method to draw the GTK-style expander.

Handles the ``wx.EVT_PAINT`` event for :class:`PyCollapsiblePane`.

:note: This is a drawing routine to paint the GTK-style expander.

Overridable method to draw the :class:`PyCollapsiblePane` text in the expander.

Handles the ``wx.EVT_SIZE`` event for :class:`PyCollapsiblePane`.

Handles the status changes (collapsing/expanding).

:param `sz`: an instance of :class:`wx.Size`.

Sets the :class:`PyCollapsiblePane` window style flags.

Assign a new button to :class:`PyCollapsiblePane`.

:param `button`: can be the standard :class:`Button` or any of the generic
 implementations which live in :mod:`lib.buttons`.

Sets the button font.

Sets the expander width and height.

:param `width`: an integer specifying the expander width in pixels;
:param `height`: an integer specifying the expander height in pixels.

Sets the button label.

:param `label`: the new button label.

:class:`~wx.lib.agw.pygauge.PyGauge` is a generic :class:`Gauge` implementation.

:class:`PyGauge` supports the determinate mode functions as :class:`Gauge` and adds an :meth:`~PyGauge.Update` function
which takes a value and a time parameter. The `value` is added to the current value over
a period of `time` milliseconds.

Usage
=====

    import wx
    import wx.lib.agw.pygauge as PG

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

            gauge1 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL)
            gauge1.SetValue(80)
            gauge1.SetBackgroundColour(wx.WHITE)
            gauge1.SetBorderColor(wx.BLACK)

            gauge2 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL)
            gauge2.SetValue([20, 80])
            gauge2.SetBarColor([wx.Colour(162, 255, 178), wx.Colour(159, 176, 255)])
            gauge2.SetBackgroundColour(wx.WHITE)
            gauge2.SetBorderColor(wx.BLACK)
            gauge2.SetBorderPadding(2)
            gauge2.Update([30, 0], 2000)

            gauge3 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL)
            gauge3.SetValue(50)
            gauge3.SetBarColor(wx.GREEN)
            gauge3.SetBackgroundColour(wx.WHITE)
            gauge3.SetBorderColor(wx.BLACK)

            sizer.Add(gauge1, 0, wx.ALIGN_CENTER_VERTICAL | wx.ALL, 20)
            sizer.Add(gauge2, 0, wx.ALIGN_CENTER_VERTICAL | wx.ALL, 20)
            sizer.Add(gauge3, 0, wx.ALIGN_CENTER_VERTICAL | wx.ALL, 20)

:class:`PyGauge` has been tested on the following platforms:
  * Windows (Windows XP, Windows 7);

:class:`PyGauge` is distributed under the wxPython license.

:class:`PyGauge` has been kindly contributed to the AGW library by Mark Reed.

Version 0.1

# PYGAUGE wxPython IMPLEMENTATION
#
# Mark Reed, @ 28 Jul 2010
#
# TODO List
#
# 1. Indeterminate mode (see wx.Gauge)
# 2. Vertical bar
# 3. Bitmap support (bar, background)
# 4. UpdateFunction - Pass a function to PyGauge which will be called every X
#    milliseconds and the value will be updated to the returned value.
# 5. Currently the full gradient is drawn from 0 to value. Perhaps the gradient
#    should be drawn from 0 to range and clipped at 0 to value.
# 6. Add a label?
#
# Write To The:
#
# wxPython Mailing List!!!
#
#

This class provides a visual alternative for :class:`Gauge`. It currently
only support determinate mode (see :meth:`PyGauge.SetValue() <PyGauge.SetValue>` and
:meth:`PyGauge.SetRange() <PyGauge.SetRange>`).

:param `style`: the underlying :class:`wx.Window` window style.

__init__(self, parent, id=wx.ID_ANY, range=100, pos=wx.DefaultPosition, size=(-1,30), style=0)

Gets the size which best suits :class:`PyGauge`: for a control, it would be

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`PyGauge`.

Handles the ``wx.EVT_PAINT`` event for :class:`PyGauge`.

Handles the ``wx.EVT_TIMER`` event for :class:`PyGauge`.

Sets the :class:`PyGauge` main bar colour.

Sets the bar gradient.

:param `gradient`: a tuple containing the gradient start and end colours.

:note: This overrides the bar colour previously set with :meth:`PyGauge.SetBarColour`.

Sets the :class:`PyGauge` border colour.

Sets the border padding.

:param `padding`: pixels between the border and the progress bar.

Sets whether percentage or current value should be drawn on the gauge for precise indication.

:param bool `draw`: a boolean value, which if ``True`` tells to start drawing value or percentage.
 If set to ``False`` nothing will be drawn and other parameters will be ignored;
:param bool `drawPercent`: a boolean value which indicates that a percent should be drawn instead
 of value passed in :meth:`SetValue`;
:param wx.Font `font`: a font with which indication should be drawn, if ``None``, then ``wx.NORMAL_FONT``
 will be used. Usually text would be displayed centered in the control, but if the text font is too large
 to be displayed (either in width or height) the corresponding coordinate will be set to zero;
:param wx.Colour `colour`: the colour with which indication should be drawn, if ``None`` then ``wx.BLACK`` will be used;
:param string `formatString`: a string specifying format of the indication (should have one and only one
 number placeholder). If set to ``None``, will use ``{:.0f}`` format string for values and ``{:.0f}%``
 format string for percentages. As described in http://docs.python.org/library/string.html#format-specification-mini-language.

.. note:: `formatString` will override addition of percent sign (after value) even if `drawPercent` is ``True``.

SetDrawValue(self, draw=True, drawPercent=True, font=None, colour=wx.BLACK, formatString=None)

Sets the range of the gauge. The gauge length is its
value as a proportion of the range.

:param `range`: The maximum value of the gauge.

Sets the current position of the gauge.

:param `value`: an integer specifying the current position of the gauge.

Internal method which sorts things so we draw the longest bar first. 

Update the gauge by adding `value` to it over `time` milliseconds. The `time` parameter
**must** be a multiple of 50 milliseconds.

:param `value`: The value to be added to the gauge;
:param `time`: The length of time in milliseconds that it will take to move the gauge.

:class:`~wx.lib.agw.pyprogress.PyProgress` is similar to :class:`ProgressDialog` in indeterminated mode, but with a
different gauge appearance and a different spinning behavior.

:class:`PyProgress` is similar to :class:`ProgressDialog` in indeterminated mode, but with a
different gauge appearance and a different spinning behavior. The moving gauge
can be drawn with a single solid colour or with a shading gradient foreground.
The gauge background colour is user customizable.

The bar does not move always from the beginning to the end as in :class:`ProgressDialog`
in indeterminated mode, but spins cyclically forward and backward.

Other options include:

- Possibility to change the proportion between the spinning bar and the
  entire gauge, so that the bar can be longer or shorter (the default is 20%);
- Modifying the number of steps the spinning bar performs before a forward
  (or backward) loop reverses.

:class:`PyProgress` can optionally display a ``Cancel`` button, and a :class:`StaticText` which
outputs the elapsed time from the starting of the process.

Usage
=====

    import wx
    import wx.lib.agw.pyprogress as PP

    dlg = PP.PyProgress(None, -1, "PyProgress Example",
                        "An Informative Message",
                        agwStyle=wx.PD_APP_MODAL | wx.PD_ELAPSED_TIME)

    dlg.SetGaugeProportion(0.2)
    dlg.SetGaugeSteps(50)
    dlg.SetGaugeBackground(wx.WHITE)
    dlg.SetFirstGradientColour(wx.WHITE)
    dlg.SetSecondGradientColour(wx.BLUE)

    max = 400
    keepGoing = 1
    count = 0

    while keepGoing and count < max:
        count += 1
        wx.MilliSleep(30)

        if count >= max // 2:
            keepGoing = dlg.UpdatePulse("Half-time!")
        else:
            keepGoing = dlg.UpdatePulse()

:class:`PyProgress` has been tested on the following platforms:

=================== =========== ==================================================
Window Styles       Hex Value   Description
``PD_CAN_ABORT``            0x1 This flag tells the dialog that it should have a ``Cancel`` button which the user may press. If this happens, the next call to `Update` will return ``False``.
``PD_APP_MODAL``            0x2 Make the progress dialog modal. If this flag is not given, it is only 'locally' modal - that is the input to the parent window is disabled, but not to the other ones.
``PD_AUTO_HIDE``            0x4 Causes the progress dialog to disappear from screen as soon as the maximum value of the progress meter has been reached.
``PD_ELAPSED_TIME``         0x8 This flag tells the dialog that it should show elapsed time (since creating the dialog).

:class:`PyProgress` is distributed under the wxPython license.

# PYPROGRESS wxPython IMPLEMENTATION
#
#
#
# TODO List
#
# 1. Do we support all the styles of wx.ProgressDialog in indeterminated mode?
#
# 2. Other ideas?
#
#
#
#
#
#

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=(-1,30))

Actually draws the sliding bar.

:param `xsize`: the width of the whole progress bar;
:param `ysize`: the height of the whole progress bar;
:param `increment`: a positive value if we are spinning from left to right,
 a negative one if we are spinning from right to left.

Returns the relative proportion between the sliding bar and the
whole gauge.

Returns the number of steps the gauge performs before switching from
forward to backward (or vice-versa) movement.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`ProgressGauge`.

Handles the ``wx.EVT_PAINT`` event for :class:`ProgressGauge`.

Sets the first gradient colour.

Sets the gauge background colour.

Sets the relative proportion between the sliding bar and the

:param `proportion`: a floating point number representing the relative
 proportion between the sliding bar and the whole gauge.

Sets the number of steps the gauge performs before switching from

:param `steps`: the number of steps the gauge performs before switching from
 forward to backward (or vice-versa) movement.

Sets the second gradient colour.

:param `title`: dialog title to show in titlebar;
:param `message`: message displayed above the progress bar;
:param `style`: the dialog style. This can be a combination of the following bits:

 =================== =========== ==================================================
 Window Styles       Hex Value   Description
 ``PD_CAN_ABORT``            0x1 This flag tells the dialog that it should have a ``Cancel`` button which the user may press. If this happens, the next call to `UpdatePulse` will return ``False``.
 ``PD_APP_MODAL``            0x2 Make the progress dialog modal. If this flag is not given, it is only 'locally' modal - that is the input to the parent window is disabled, but not to the other ones.
 ``PD_AUTO_HIDE``            0x4 Causes the progress dialog to disappear from screen as soon as the maximum value of the progress meter has been reached.
 ``PD_ELAPSED_TIME``         0x8 This flag tells the dialog that it should show elapsed time (since creating the dialog).

__init__(self, parent=None, id=-1, title="", message="", agwStyle=wx.PD_APP_MODAL|wx.PD_AUTO_HIDE)

Creates the :class:`StaticText` that holds the elapsed time label.

:param `text`: the dialog message to be displayed above the gauge;
:param `sizer`: the main :class:`BoxSizer` for :class:`PyProgress`.

Enables or disables the ``Cancel`` button.

:param `enable`: ``True`` to enable the ``Cancel`` button, ``False`` to disable it.

Enables or disables the ``Close`` button.

:param `enable`: ``True`` to enable the ``Close`` button, ``False`` to disable it.

Returns the :class:`PyProgress` style.

:see: The :meth:`~PyProgress.__init__` method for a list of possible style flags.

Handles the ``wx.EVT_CLOSE`` event for :class:`PyProgress`.

Handles the ``wx.EVT_WINDOW_DESTROY`` event for :class:`PyProgress`.

Re-enables the other windows if using :class:`wx.WindowDisabler`. 

Sets the gauge first gradient colour.

Sets the gauge second gradient colour.

Sets the elapsed time label.

:param `val`: the elapsed time since the dialog was shown, in seconds;
:param `label`: the new message to display in the elapsed time text.

Show the dialog.

:param `show`: ``True`` to show the dialog and re-enable all the other windows,

Updates the dialog, setting the progress bar to the new value and, if given
changes the message above it. Returns ``True`` unless the ``Cancel`` button
has been pressed.

If ``False`` is returned, the application can either immediately destroy the
dialog or ask the user for the confirmation.

:param `newmsg`: The new messages for the progress dialog text, if it is
 empty (which is the default) the message is not changed.

:class:`~wx.lib.agw.rulerctrl.RulerCtrl` implements a ruler window that can be placed on top, bottom, left or right
to any wxPython widget.

:class:`RulerCtrl` implements a ruler window that can be placed on top, bottom, left or right
to any wxPython widget. It is somewhat similar to the rulers you can find in text
editors software, though not so powerful.

:class:`RulerCtrl` has the following characteristics:

- Can be horizontal or vertical;
- 4 built-in formats: integer, real, time and linearDB formats;
- Units (as ``cm``, ``dB``, ``inches``) can be displayed together with the label values;
- Possibility to add a number of "paragraph indicators", small arrows that point at
  the current indicator position;
- Customizable background colour, tick colour, label colour;
- Possibility to flip the ruler (i.e. changing the tick alignment);
- Changing individually the indicator colour (requires PIL at the moment);
- Different window borders are supported (``wx.STATIC_BORDER``, ``wx.SUNKEN_BORDER``,
  ``wx.DOUBLE_BORDER``, ``wx.NO_BORDER``, ``wx.RAISED_BORDER``, ``wx.SIMPLE_BORDER``);
- Logarithmic scale available;
- Possibility to draw a thin line over a selected window when moving an indicator,
  which emulates the text editors software.

And a lot more. See the demo for a review of the functionalities.

Usage
=====

    import wx
    import wx.lib.agw.rulerctrl as RC

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

            text = wx.TextCtrl(panel, -1, "Hello World! wxPython rules", style=wx.TE_MULTILINE)

            ruler1 = RC.RulerCtrl(panel, -1, orient=wx.HORIZONTAL, style=wx.SUNKEN_BORDER)
            ruler2 = RC.RulerCtrl(panel, -1, orient=wx.VERTICAL, style=wx.SUNKEN_BORDER)

            mainsizer = wx.BoxSizer(wx.HORIZONTAL)
            leftsizer = wx.BoxSizer(wx.VERTICAL)
            bottomleftsizer = wx.BoxSizer(wx.HORIZONTAL)
            topsizer = wx.BoxSizer(wx.HORIZONTAL)

            leftsizer.Add((20, 20), 0, wx.ADJUST_MINSIZE, 0)
            topsizer.Add((39, 0), 0, wx.ADJUST_MINSIZE, 0)
            topsizer.Add(ruler1, 1, wx.EXPAND, 0)
            leftsizer.Add(topsizer, 0, wx.EXPAND, 0)

            bottomleftsizer.Add((10, 0))
            bottomleftsizer.Add(ruler2, 0, wx.EXPAND, 0)
            bottomleftsizer.Add(text, 1, wx.EXPAND, 0)
            leftsizer.Add(bottomleftsizer, 1, wx.EXPAND, 0)
            mainsizer.Add(leftsizer, 3, wx.EXPAND, 0)

            panel.SetSizer(mainsizer)

Events
======

:class:`RulerCtrl` implements the following events related to indicators:

- ``EVT_INDICATOR_CHANGING``: the user is about to change the position of one indicator;
- ``EVT_INDICATOR_CHANGED``: the user has changed the position of one indicator.

:class:`RulerCtrl` has been tested on the following platforms:

========================== ==================================================
Event Name                 Description
``EVT_INDICATOR_CHANGED``  The user has changed the indicator value.
``EVT_INDICATOR_CHANGING`` The user is about to change the indicator value.

:class:`RulerCtrl` is distributed under the wxPython license.

# RULERCTRL wxPython IMPLEMENTATION
#
#
#
# TODO List
#
#
#
#
#
#

This class holds all the information about a single indicator inside :class:`RulerCtrl`.

You should not call this class directly. Use::

    ruler.AddIndicator(id, value)

to add an indicator to your :class:`RulerCtrl`.

:param `parent`: the parent window, an instance of :class:`RulerCtrl`;
:param `id`: the indicator identifier;
:param `value`: the initial value of the indicator.

Actually draws the indicator.

Returns the position at which we should draw the indicator bitmap. 

Rotates the default indicator bitmap.

:param `img`: if not ``None``, the indicator image.

Sets the indicator colour.

:param `colour`: the new indicator colour, an instance of :class:`wx.Colour`.

:note: Requires PIL (Python Imaging Library), which can be downloaded from
 http://www.pythonware.com/products/pil/

Sets the indicator value.

:param `value`: the new indicator value.

Auxiliary class. Just holds information about a label in :class:`RulerCtrl`.

:param `pos`: the indicator position;
:param `lx`: the indicator `x` coordinate;
:param `ly`: the indicator `y` coordinate;
:param `text`: the label text.

:param `orient`: sets the orientation of the :class:`RulerCtrl`, and can be either
 ``wx.HORIZONTAL`` of ``wx.VERTICAL``.

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.STATIC_BORDER, orient=wx.HORIZONTAL)

Adds an indicator to :class:`RulerCtrl`. You should pass a unique `id` and a starting
`value` for the indicator.

:param `value`: the indicator initial value.

Adjust the :class:`RulerCtrl` style accordingly to borders, units, etc...

Actually draws the whole :class:`RulerCtrl`.

Actually draws the thin line over the drawing parent window.

:param `indicator`: the current indicator, an instance of :class:`Indicator`.

:note: This method is currently not available on wxMac as it uses :class:`ScreenDC`.

Returns the window to which :class:`RulerCtrl` draws a thin line over. 

Returns the format used to display values in :class:`RulerCtrl`.

:see: :meth:`RulerCtrl.SetFormat` for a list of possible formats.

Returns the indicator located at the mouse position `mousePos` (if any).

:param `mousePos`: the mouse position, an instance of :class:`wx.Point`.

Sets whether the major ticks should be labeled or not.

:param `label`: ``True`` to label major ticks, ``False`` otherwise.

Sets whether the minor ticks should be labeled or not.

:param `label`: ``True`` to label minor ticks, ``False`` otherwise.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RulerCtrl`.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`RulerCtrl`.

Handles the ``wx.EVT_PAINT`` event for :class:`RulerCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`RulerCtrl`.

Sets the :class:`RulerCtrl` background colour.

Sets the bounds for :class:`RulerCtrl` (its client rectangle).

:param `left`: the left corner of the client rectangle;
:param `top`: the top corner of the client rectangle;
:param `right`: the right corner of the client rectangle;
:param `bottom`: the bottom corner of the client rectangle.

Sets the window to which :class:`RulerCtrl` draws a thin line over.

:param `dparent`: an instance of :class:`wx.Window`, representing the window to
 which :class:`RulerCtrl` draws a thin line over.

Sets whether the orientation of the tick marks should be reversed.

:param `flip`: ``True`` to reverse the orientation of the tick marks, ``False``

Sets the fonts for minor and major tick labels.

:param `minorFont`: the font used to draw minor ticks, a valid :class:`wx.Font` object;
:param `majorFont`: the font used to draw major ticks, a valid :class:`wx.Font` object.

Sets the format for :class:`RulerCtrl`.

:param `format`: the format used to display values in :class:`RulerCtrl`. This can be
 one of the following bits:

 ====================== ======= ==============================
 Format                  Value  Description
 ``IntFormat``                1 Integer format
 ``RealFormat``               2 Real format
 ``TimeFormat``               3 Time format
 ``LinearDBFormat``           4 Linear DB format
 ``HHMMSS_Format``            5 HHMMSS format
 
:note: This method requires PIL to change the image palette.

:param `sendEvent`: ``True`` to send a :class:`RulerCtrlEvent`, ``False`` otherwise.

Sets the labels colour.

Sets whether the edge values should always be displayed or not.

:param `labelEdges`: ``True`` to always display edge labels, ``False`` otherwise/

Sets whether :class:`RulerCtrl` should have a logarithmic scale or not.

:param `log`: ``True`` to use a logarithmic scale, ``False`` to use a
 linear one.

Sets the :class:`RulerCtrl` orientation.

:param `orient`: can be ``wx.HORIZONTAL`` or ``wx.VERTICAL``.

Sets the :class:`RulerCtrl` range.

:param `minVal`: the minimum value of :class:`RulerCtrl`;
:param `maxVal`: the maximum value of :class:`RulerCtrl`.

Sets the :class:`RulerCtrl` spacing between labels.

:param `spacing`: the spacing between labels, in pixels.

Sets the pen colour to draw the ticks.

Sets the time format.

:param `format`: the format used to display time values.

Sets the units that should be displayed beside the labels.

:param `units`: the units that should be displayed beside the labels.

Ticks a particular position.

:param `pos`: the label position;
:param `d`: the current label value;
:param `major`: ``True`` if it is a major ticks, ``False`` if it is a minor one.

Sets whether the major ticks should be ticked or not.

:param `tick`: ``True`` to show major ticks, ``False`` otherwise.

Sets whether the minor ticks should be ticked or not.

:param `tick`: ``True`` to show minor ticks, ``False`` otherwise.

Updates all the ticks calculations.

Represent details of the events that the :class:`RulerCtrl` object sends.

Sets the event old value.

:param `value`: the old indicator position.

Sets the event value.

:param `value`: the new indicator position.

Converts a PIL image into a :class:`wx.Image`.

:param `pil`: a PIL image;
:param `alpha`: ``True`` if the image contains alpha transparency, ``False``

Converts a :class:`wx.Image` into a PIL image.

:param `bmp`: an instance of :class:`wx.Image`.

Returns the image indicator as a decompressed stream of characters. 

Creates a palette to be applied on an image based on input colour.

:param `tr`: the red intensity of the input colour;
:param `tg`: the green intensity of the input colour;
:param `tb`: the blue intensity of the input colour.

:class:`ScrolledThumbnail` is a widget that can be used to display a series of
thumbnails for files in a scrollable window.

:class:`ScrolledThumbnail` is a widget derived from :class:`wx.ScrolledWindow`
which will display the thumbnail image for a file in a scrollable, resizable
window.  It supports selecting one or more thumbnails, rotating the thumbnails,
displaying information for each thumbnail, and popups for both the window and
for individual thumbnails.

The class uses two support classes: :class:`Thumb` and :class:`ImageHandler`.

:class:`Thumb` contains all of the information for a particular thumbnail,
including filename, bitmaped thumbnail image, caption, and other data.  This
class also has methods to perform thumbnail operations such as rotation,
highlighting, setting a file name.

:class:`ImageHandler` provides file/image handling functions, including loading
a file and creating an image from it, rotating an image, or highlighting an image.

The implementations of these two classes included in this file support generating
thumbnails from supported image files, such as JPEG, GIF, PNG, etc., using either
WxPythons native support or the PIL image library.  Additional file types can be
supported by extending these classes, for example, to provide a thumbnail image
for an MP4 file, perhaps the cover photo, an MPEG by providing the image of a
title frame, or a PDF by providing an image of the cover page.  The images for
these files may be generated on the fly by a suitably extended :class:`ImageHandler`,
or may be provided with the instance of :class:`Thumb`.  The list of `Thumb`
instances passed to `ScrolledThumbnail` may contain different derived classes,
as long as each contains the required functions.

NB:  Use of :class:`ScrolledThumbnail` has not been tested with extended classes.

:class:`ScrolledThumbnail`, :class:`Thumb`, and :class:`ImageHandler`, implemented
here are derived from the similarly named classes included in :class:`agw.ThumbnailCtrl`,
written by Andrea Gavana.  That implementation was tightly integrated as a image
file browser application.  The current implementation removes dependencies between
the several classes and narrows the scope of `ScrolledThumbnail` to the placement
and management of thumbnails within a window.

An updated :class:`ThumbnailCtrl` which uses this implementation of
:class:`ScrolledThumbnail`, :class:`Thumb`, and :class:`ImageHandler` provides
all of the previous functionality, which described as a widget that can be used
to display a series of images in a "thumbnail" format; it mimics, for example,
the windows explorer behavior when you select the "view thumbnails" option.
Basically, by specifying a folder that contains some image files, the files
in the folder are displayed as miniature versions of the actual images in
a :class:`ScrolledWindow`.

The code in the previous implementation is partly based on `wxVillaLib`, a
wxWidgets implementation of the :class:`ThumbnailCtrl` control.  Andrea Gavana
notes that :class:`ThumbnailCtrl` wouldn't have been so fast and complete
without the suggestions and hints from Peter Damoc.

Usage:
=====

    import os
    import wx
    from scrolledthumbnail import ScrolledThumbnail, Thumb, NativeImageHandler

            wx.Frame.__init__(self, parent, -1, "ScrolledThumb Demo", size=(400,300))

            self.scroll = ScrolledThumbnail(self, -1, size=(400,300))

        def ShowDir(self, dir):
            dir = os.getcwd()
            files = os.listdir(dir)
            thumbs = []
            for f in files:
                if os.path.splitext(f)[1] in [".jpg", ".gif", ".png"]:
                    thumbs.append(Thumb(dir, f, caption=f, imagehandler=NativeImageHandler))
            self.scroll.ShowThumbs(thumbs)

    app = wx.App(False)
    frame.ShowDir(os.getcwd())
    frame.Show(True)

With :class:`ScrolledThumbnail` you can:

- Create different thumbnail outlines (none, images only, full, etc...);
- Highlight thumbnails on mouse hovering;
- Show/hide file names below thumbnails;
- Change thumbnail caption font;
- Zoom in/out thumbnails (done via ``Ctrl`` key + mouse wheel or with ``+`` and ``-`` chars,
  with zoom factor value customizable);
- Rotate thumbnails with these specifications:

  a) ``d`` key rotates 90 degrees clockwise;
  b) ``s`` key rotates 90 degrees counter-clockwise;
  c) ``a`` key rotates 180 degrees.

- Drag and drop thumbnails from :class:`ScrolledThumbnail` to whatever application you want;
- Use local (when at least one thumbnail is selected) or global (no need for
  thumbnail selection) popup menus;
- possibility to show tooltips on thumbnails, which display file information
  (like file name, size, last modification date and thumbnail size).

:note: Using highlight thumbnails on mouse hovering may be slow on slower
 computers.

``EVT_THUMBNAILS_CAPTION_CHANGED`` The thumbnail caption has been changed. Not used at present.
``EVT_THUMBNAILS_DCLICK``          The user has double-clicked on a thumbnail.
``EVT_THUMBNAILS_POINTED``         The mouse cursor is hovering over a thumbnail.
``EVT_THUMBNAILS_SEL_CHANGED``     The user has changed the selected thumbnail.
``EVT_THUMBNAILS_THUMB_CHANGED``   The thumbnail of an image has changed. Used internally.
``EVT_THUMBNAILS_CHAR``            A character has been typed

:class:`ScrolledThumbnail` is distributed under the wxPython license.

Latest revision: Michael Eager @ 2 Oct 2020

# SCROLLEDTHUMBNAIL Control wxPython IMPLEMENTATION
#
# Michael Eager (eager@eagercon.com), 26 Sep 2020
#
# Based on thumnailctrl.py by
# Andrea Gavana And Peter Damoc, @ 12 Dec 2005, revised 27 Dec 2012
#
# Tags:         phoenix-port, documented, unittest, py3-port
#

This image handler loads and manipulates the thumbnails with the help of
wxPython's own image related functions.

Adjust overall image brightness to highlight.

:param `img`: an instance of :class:`wx.Image`;
:param `factor`: a floating point number representing the highlight factor.

Rotate image by angle degrees.

:param img: an instance of :class:wx.Image;
:param angle:  angle in degrees
:return: rotated image

This image handler loads and manipulates the thumbnails with the help
of PIL (the Python Imaging Library).

:note: If PIL is not installed, this will raise an exception. PIL
 can be downloaded from http://www.pythonware.com/products/pil/ .

:param `factor`: unused in :class:`PILImageHandler`.

This is the main class implementation of :class:`ThumbnailCtrl`. 

:param `thumboutline`: outline style for :class:`ScrolledThumbnail`, which may be:

 =========================== ======= ==================================
 Outline Flag                 Value  Description
 ``THUMB_OUTLINE_NONE``            0 No outline is drawn on selection
 ``THUMB_OUTLINE_FULL``            1 Full outline (image+caption) is drawn on selection
 ``THUMB_OUTLINE_RECT``            2 Only thumbnail bounding rectangle is drawn on selection (default)
 ``THUMB_OUTLINE_IMAGE``           4 Only image bounding rectangle is drawn.

:param `imagehandler`: can be :class:`PILImageHandler` if PIL is installed (faster), or
 :class:`NativeImageHandler` which only uses wxPython image methods.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, thumboutline=THUMB_OUTLINE_IMAGE, imagehandler=None)

Calculates the best caption string to show based on the actual zoom factor.

:param `caption`: the original caption string;
:param `sw`: the maximum width allowed for the caption string, in pixels;
:param `width`: the caption string width, in pixels.

Draws a visible thumbnail.

:param `bmp`: the thumbnail version of the original image;
:param `thumb`: an instance of :class:`Thumb`;
:param `index`: the index of the thumbnail to draw.

Enables/disables thumbnails drag and drop.

:param `enable`: ``True`` to enable drag and drop, ``False`` to disable it.

Globally enables/disables thumbnail file information.

:param `enable`: ``True`` to enable thumbnail file information, ``False`` to disable it.

Returns the height for the file name caption.

:param `begRow`: the caption line at which we start measuring the height;
:param `count`: the number of lines to measure.

Returns the global thumbnailss popup menu (no need of thumbnail selection). 

Returns whether the thumbnail pointed should be highlighted or not.

:note: Please be aware that this functionality may be slow on slower computers.

Return thumbnail at specified position.

:param pos: the index of the thumbnail
:return:  the Thumb

Returns the thumbnail index at position (x, y).

:param `x`: the mouse `x` position;
:param `y`: the mouse `y` position.

Returns the paint bounding rect for the :meth:`~ScrolledThumbnail.OnPaint` method. 

Returns the thumbnails popup menu when at least one thumbnail is selected. 

Returns the selected thumbnail.

:param `index`: the thumbnail index (i.e., the selection).

:param `selIndex`: if not equal to -1, the index of the selected thumbnail.

Returns the thumbnail information.

:param `thumb`: the index of the thumbnail for which we are collecting information.

Returns the thumbnail outline style on selection.

:see: :meth:`~ScrolledThumbnail.SetThumbOutline` for a list of possible return values.

Inserts a thumbnail in the specified position.

:param `pos`: the index at which we wish to insert the new thumbnail.

Returns whether a thumbnail is selected or not.

:param `indx`: the index of the thumbnail to check for selection.

Threaded method to load images. Used internally.

:param `newfile`: a file name containing an image to thumbnail;
:param `imagecount`: the number of images loaded until now.

Handles the ``wx.EVT_CHAR`` event for :class:`ThumbnailCtrl`.

:note: You have these choices:

 (1) ``d`` key rotates 90 degrees clockwise the selected thumbnails;
 (2) ``s`` key rotates 90 degrees counter-clockwise the selected thumbnails;
 (3) ``a`` key rotates 180 degrees the selected thumbnails;
 (4) ``+`` key zooms in;
 (5) ``-`` key zooms out.
 All other keys cause an EVT_THUMBNAILS_CHAR event to be thrown.

Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_LEFT_DOWN`` and ``wx.EVT_RIGHT_DOWN`` events for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_MOTION`` event for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_LEFT_UP`` and ``wx.EVT_RIGHT_UP`` events for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_MOUSEWHEEL`` event for :class:`ThumbnailCtrl`.

:note: If you hold down the ``Ctrl`` key, you can zoom in/out with the mouse wheel.

Handles the ``wx.EVT_PAINT`` event for :class:`ThumbnailCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`ThumbnailCtrl`.

Handles the ``EVT_THUMBNAILS_THUMB_CHANGED`` event for :class:`ThumbnailCtrl`.

:param `event`: a :class:`ThumbnailEvent` event to be processed.

Removes a thumbnail at the specified position.

:param `pos`: the index at which we wish to remove the thumbnail.

Rotates the selected thumbnails by the angle specified by `angle`.

:param `angle`: the rotation angle for the thumbnail, in degrees.

Sets the font for all the thumbnail captions.

:param `font`: a valid :class:`wx.Font` object. If defaulted to ``None``, a standard
 font will be generated.

Sets whether to drop a shadow behind thumbnails or not.

:param `drop`: ``True`` to drop a shadow behind each thumbnail, ``False`` otheriwise.

Sets the global thumbnails popup menu (no need of thumbnail selection).

:param `gpmenu`: an instance of :class:`wx.Menu`.

Sets whether the thumbnail pointed should be highlighted or not.

:param `highlight`: ``True`` to enable highlight-on-point with the mouse,

Sets the thumbnails popup menu when at least one thumbnail is selected.

Sets thumbnail selection.

:param `value`: the thumbnail index to select.

Sets the colour used to indicate a selected thumbnail.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, it
 will be taken from the system settings.

Sets the thumbnail outline style on selection.

:param `outline`: the outline to use on selection. This can be one of the following
 bits:

Sets the thumbnail size as width, height and border.

:param `width`: the desired thumbnail width;
:param `height`: the desired thumbnail height;
:param `border`: the spacing between thumbnails.

Sets the zoom factor.

:param `zoom`: a floating point number representing the zoom factor. Must be
 greater than or equal to 1.0.

Sets whether the user wants to show file names under the thumbnails or not.

:param `show`: ``True`` to show file names under the thumbnails, ``False`` otherwise.

Shows all the thumbnails.

:param `thumbs`: should be a sequence with instances of :class:`Thumb`;

:param `filenames`: a Python list of file names containing images.

Updates :class:`ThumbnailCtrl` and its visible thumbnails.

:param `checkSize`: ``True`` to update the items visibility if the window
 size has changed.

This is an auxiliary class, to handle single thumbnail information for every thumb.

:param `folder`: the directory containing the images;
:param `filename`: a file containing an image;
:param `caption`: the thumbnail caption string;
:param `size`: the file size;
:param `lastmod`: the file last modification time.

__init__(self, folder, filename, caption="", size=0, lastmod=0, imagehandler=None)

Breaks the caption in several lines of text (if needed).

:param `width`: the maximum width, in pixels, available for the caption text.

Returns the bitmap of the thumbnail

:param `width`: the associated bitmap width;
:param `height`: the associated bitmap height.

Returns the caption associated to a thumbnail.

:param `line`: the caption line we wish to retrieve (useful for multilines
 caption strings).

Returns the number of lines for the caption.

Returns the file last modification date associated to a thumbnail. 

Returns a tuple containing the original image width and height, in pixels. 

Returns the wx.Image of the thumbnail

Sets the thumbnail caption.

:param `caption`: the thumbnail caption string.

Sets the file name associated with this thumbnail.

:param `filename`: the file containing the image.

Sets the thumbnail identifier.

:param `id`: an integer specifying the thumbnail identifier.

Sets the thumbnail image.

:param `image`: a :class:`wx.Image` object.

This class is used to send events when a thumbnail is hovered, selected,
double-clicked or when its caption has been changed.

:param `evtId`: the event identifier.

Return the second part of the shadow dropped behind thumbnails. 

Convert paths to the platform-specific separator.

:param `path`: the path to convert.

:class:`~wx.lib.agw.shapedbutton.SButton` tries to fill the lack of "custom shaped" controls in wxPython
and it can be used to build round or elliptic-shaped buttons.

`ShapedButton` tries to fill the lack of "custom shaped" controls in wxPython
(that depends on the same lack in wxWidgets). It can be used to build round
buttons or elliptic buttons.

I have stolen some code from :mod:`lib.buttons` in order to recreate the same
classes (`GenButton`, `GenBitmapButton`, `GenBitmapTextButton`, `GenToggleButton`,
`GenBitmapToggleButton`, `GenBitmapTextToggleButton`). Here you have the same
classes (with "Gen" replaced by "S"), with the same event handling, but they
are rounded/elliptical buttons.

`ShapedButton` is based on a :class:`wx.Window`, in which 2 images are drawn depending
on the button state (pressed or not pressed). The 2 images have been stolen
from Audacity (written with wxWidgets) and rearranged/reshaped/restyled
using adobe PhotoShop.
Changing the button colour in runtime was more difficult, but using some
intelligent instruction from the PIL library it can be done.

`ShapedButton` reacts on mouse events *only* if the mouse event occurred inside
the circle/ellipse, even if `ShapedButton` is built on a rectangular window.
This behavior is a lot different with respect to Audacity round buttons.

Usage
=====

    import wx
    import wx.lib.agw.shapedbutton as SB

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

            # Create 2 bitmaps for the button
            upbmp = wx.Bitmap("play.png", wx.BITMAP_TYPE_PNG)
            disbmp = wx.Bitmap("playdisabled.png", wx.BITMAP_TYPE_PNG)

            play = SB.SBitmapToggleButton(panel, -1, upbmp, (100, 50))
            play.SetUseFocusIndicator(False)
            play.SetBitmapDisabled(disbmp)

The `ShapedButton` construction and usage is quite similar to the :mod:`lib.buttons`
implementation.

With `ShapedButton` you can:

- Create rounded/elliptical buttons/togglebuttons;
- Set images for the enabled/disabled/focused/selected state of the button;
- Draw the focus indicator (or disable it);
- Set label colour and font;
- Apply a rotation to the `ShapedButton` label;
- Change `ShapedButton` shape and text orientation in runtime.

:note: `ShapedButton` **requires** PIL (Python Imaging Library) library to be installed,
 which can be downloaded from http://www.pythonware.com/products/pil/ .

`ShapedButton` is distributed under the wxPython license.

# SHAPEDBUTTON Control wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 18 Oct 2005
#
#
#
# 1. Elliptic Buttons May Be Handled Better, In My Opinion. They Look Nice
#    But They Are Somewhat More Difficult To Handle When Using Sizers.
#    This Is Probably Due To Some Lack In My Implementation;
#
# 2. I Am Unable To Translate The 2 Files "UpButton.png" And "DownButton.png"
#    Using "img2py" (Under wx.tools) Or With PIL In Order To Embed Them In
#    A Python File. Every Translation I Made, Did Not Preserve The Alpha
#    Channel So I Ended Up With Round Buttons Inside Black Squares. Does
#    Anyone Have A Suggestion Here?
#
# 3. Creating *A Lot* Of ShapedButtons May Require Some Time. In The Demo,
#    I Create 23 Buttons In About 0.4 Seconds On Windows XP, 3 GHz 1 GB RAM.
#
# 4. Creating Buttons With Size Greater Than wx.Size(200, 200) May Display
#    Buttons With Clearly Evident Pixel Edges. This Is Due To The Size Of The
#    Image Files I Load During Initialization. If This Is Not Satisfactory,
#    Please Let Me Know And I Will Upload Bigger Files.
#
#
#
#
#

A mixin that allows to transform any of :class:`SButton`, :class:`SBitmapButton` and
:class:`SBitmapTextButton` in the corresponding toggle buttons.

Handles the ``wx.EVT_KEY_DOWN`` event for the button.

Handles the ``wx.EVT_KEY_UP`` event for the button.

Handles the ``wx.EVT_LEFT_DOWN`` event for the button.

Handles the ``wx.EVT_LEFT_UP`` event for the button.

Handles the ``wx.EVT_MOTION`` event for the button.

:param `flag`: ``True`` to set the button as toggled, ``False`` otherwise.

Subclass of :class:`SButton` which displays a bitmap, acting like a
:class:`wx.BitmapButton`.

:param `parent`: the :class:`SBitmapButton` parent. Must not be ``None``;

__init__(self, parent, id, bitmap, pos=wx.DefaultPosition, size=wx.DefaultSize)

Draws the bitmap in the middle of the button.

:param `width`: the button width;
:param `height`: the button height;
:param `dw`: width differential, to show a 3D effect;
:param `dh`: height differential, to show a 3D effect.

Returns the bitmap associated with the button in the normal state. 

Returns the bitmap displayed when the button is selected (pressed). 

Sets the bitmap to display when the button is disabled.

:param `bitmap`: a valid :class:`wx.Bitmap` object.

Sets the bitmap to display when the button has the focus.

Sets the bitmap to display normally. This is the only one that is
required.

:param `bitmap`: a valid :class:`wx.Bitmap` object;
:param `createothers`: if set to ``True``, then the other bitmaps will be
 generated on the fly. Currently, only the disabled bitmap is generated.

Sets the bitmap to display when the button is selected (pressed).

Subclass of :class:`SButton` which displays a bitmap and a label.

:param `parent`: the :class:`SBitmapTextButton` parent. Must not be ``None``;

__init__(self, parent, id, bitmap, label, pos=wx.DefaultPosition, size=wx.DefaultSize)

Draws the bitmap and the text label.

:param `parent`: the :class:`SButton` parent. Must not be ``None``;

__init__(self, parent, id=wx.ID_ANY, label="", pos=wx.DefaultPosition, size=wx.DefaultSize)

Overridden base class virtual. Determines the best size of the button
based on the label size.

Draws the focus indicator. This is a circle/ellipse inside the button
drawn with a dotted-style pen, to let the user know which button has
the focus.

:param `height`: the button height.

Draws the label on the button.

Draws the main button, in whichever state it is.

Calculates a new set of focus indicator colour and indicator pen
based on button colour and label colour.

Checks if a mouse events occurred inside the circle/ellipse or not.

:param `x`: the mouse x position;
:param `y`: the mouse y position.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`SButton`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`SButton`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`SButton`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`SButton`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`SButton`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`SButton`.

Handles the ``wx.EVT_MOTION`` event for :class:`SButton`.

Handles the ``wx.EVT_PAINT`` event for :class:`SButton`.

Handles the ``wx.EVT_SIZE`` event for :class:`SButton`.

Sets angle of button label rotation.

:param `angle`: the label rotation, in degrees.

Given the current font settings, calculate and set a good size.

:param `size`: if not ``None``, an instance of :class:`wx.Size` to pass to
 `SetInitialSize`.

Sets the button colour, for all button states.

:note: The original button images are greyscale with a lot of pixels with
 different colours. Changing smoothly the button colour in order to
 give the same 3D effect can be efficiently done only with PIL.

Sets the ellipse axis. What it is important is not their absolute values
but their ratio.

:param `main`: a floating point number representing the absolute dimension
 of the main ellipse axis;
:param `secondary`: a floating point number representing the absolute dimension
 of the secondary ellipse axis.

Sets the button label colour.

:param `flag`: ``True`` to use the focus indicator, ``False`` otherwise.

Overridden base class virtual. Buttons usually do not inherit
parent's colours.

Event sent from the generic buttons when the button is activated. 

:param `btn`: the button object.

Sets the button event as pressed.

:param `isDown`: ``True`` to set the event as "pressed", ``False`` otherwise.

:class:`~wx.lib.agw.shortcuteditor.ShortcutEditor` is a widget that allows the user to customize and change keyboard
shortcuts via a dialog. It can be used to edit :class:`wx.MenuItem` shortcuts or accelerators
defined in a :class:`AcceleratorTable`.

.. note::

    :class:`ShortcutEditor` **requires** the minimum AGW version 0.9.3 or the current
    SVN, for the various enhancements made to the :class:`~wx.lib.agw.hypertreelist.HyperTreeList`
    and :class:`~wx.lib.agw.genericmessagedialog.GenericMessageDialog`
    widgets.

:class:`ShortcutEditor` is a widget that allows the user to customize and change keyboard

The interface itself is very much inpired by the GIMP shortcut editor:

http://graphicssoft.about.com/od/gimptutorials/tp/keyboard-shortcut-editor.htm

There are very few minor UI differences between :class:`ShortcutEditor` and the GIMP one,
although the behaviour should be pretty much equivalent.

Various features:

* Shortcuts are listed in a tree-like structure, pretty much reflecting a menu
  hierarchy (as most of the time :class:`ShortcutEditor` is used to edit :class:`wx.MenuItem`
  shortcuts);
* Accelerators defined via :class:`AcceleratorTable` are handled in a similar way;
* Support for I18N;
* Ability to restore default shortcuts/accelerators via a UI button;
* Possibility to send back the new/updated shortcuts to the original :class:`wx.MenuBar` or
  the original :class:`AcceleratorTable`;
* Filters on the shortcuts label (case-insensitive);
* Basic help window with instructions (customizable via :meth:`~ShortcutEditor.SetHTMLHelpFile`), via
  the ``Help`` button.

UI Interactions
===============

1. In the :class:`ShortcutEditor` dialog you can open sub-sections by clicking the small box
   with a + sign in it next to each section name. In the screen grab, you can see I've
   opened the *Options* sub-section as I'm going to add a keyboard shortcut to the
   *OptionsItem 1* item.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_1_thumb.png
      :alt: Open Subsections
      :figclass: floatcenter
      :target: _static/images/sphinxdocs/ShortcutEditor_1.png

      **Figure 1**

2. Now you need to scroll to the tool or command that you want to edit and click on it
   to select it. When selected, the text for that tool in the *Shortcut* column changes
   to read 'New accelerator...' and you can press the key or combination of keys you
   want to assign as a shortcut.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_2_thumb.png
      :alt: Assign Shortcut
      :target: _static/images/sphinxdocs/ShortcutEditor_2.png

      **Figure 2**

3. I've changed the *OptionsItem 1*'s keyboard shortcut to ``Shift+Ctrl+F`` by pressing
   the ``Shift``, ``Ctrl`` and ``F`` keys simultaneously. If you want to remove a keyboard
   shortcut from any tool or command, just click on it to select it and then when the
   'New accelerator...' text displays, press the backspace key and the text will change
   to 'Disabled'.

   Once you're happy that your keyboard shortcuts are set up as you wish, simply click
   the ``OK`` button.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_3_thumb.png
      :alt: Remove/Save Shortcuts
      :target: _static/images/sphinxdocs/ShortcutEditor_3.png

      **Figure 3**

4. If you thought my choice of ``Shift+Ctrl+F`` was an odd selection, I chose it because
   it was a keyboard combination that hadn't already been assigned to any tool or command.
   If you try to assign a keyboard shortcut that is already in use, an alert will open
   telling you what the shortcut is currently being used for. If you want to keep the
   original shortcut, just click the ``Cancel`` button, otherwise click ``Reassign shortcut``
   to make the shortcut apply to your new selection.

   .. figure:: _static/images/sphinxdocs/ShortcutEditor_4_thumb.png
      :alt: Reassigning Shortcuts
      :target: _static/images/sphinxdocs/ShortcutEditor_4.png

      **Figure 4**

There are basically three ways to populate the :class:`ShortcutEditor` dialog, depending on
your needs. These approaches can be combined if needed.

1) Use the :meth:`~ShortcutEditor.FromMenuBar` method: if you need to give your user the ability to edit
   the various :class:`wx.MenuItem` shortcuts in your application, you can create :class:`ShortcutEditor`
   in this way::

        # Build your wx.MenuBar first!!!
        # "self" is an instance of wx.TopLevelWindow

        dlg = ShortcutEditor(self)
        dlg.FromMenuBar(self)

        # Here the user will make all the various modifications
        # to the shortcuts

        if dlg.ShowModal() == wx.ID_OK:
            # Changes accepted, send back the new shortcuts to
            # the TLW wx.MenuBar
            dlg.ToMenuBar(self)

2) Use the :meth:`~ShortcutEditor.FromAcceleratorTable` method: if you need to give your user the ability to edit
   the various accelerators you set via :class:`AcceleratorTable` in your application, you can
   create :class:`ShortcutEditor` in this way::

        # Build your wx.AcceleratorTable first!!!
        # "accelTable" is a list of tuples (4 elements per tuple)

        accelTable = []

        # Every tuple is defined in this way:

        for label, flags, keyCode, cmdID in my_accelerators:
            # label:   the string used to show the accelerator into the ShortcutEditor dialog
            # flags:   a bitmask of wx.ACCEL_ALT, wx.ACCEL_SHIFT, wx.ACCEL_CTRL, wx.ACCEL_CMD,
            #          or wx.ACCEL_NORMAL used to specify which modifier keys are held down
            # keyCode: the keycode to be detected (i.e., ord('b'), wx.WXK_F10, etc...)
            # cmdID:   the menu or control command ID to use for the accelerator event.

            accel_tuple = (label, flags, keyCode, cmdID)
            accelTable.append(accel_tuple)

        dlg.FromAcceleratorTable(accelTable)

            # the window with the wx.AcceleratorTable:
            dlg.ToAcceleratorTable(self)

3) Build your own hierarchy of shortcuts using :meth:`~ShortcutEditor.GetShortcutManager`::

        manager = dlg.GetShortcutManager()

        for label, accelerator, bitmap, help, cmdID in my_list:
            shortcut = Shortcut(label, accelerator, bitmap, help, accelId=cmdID)
            manager.AppendItem(shortcut)

        dlg.ShowModal()

Usage
=====

    import wx
    import wx.lib.agw.shortcuteditor as SE

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

            bar = wx.MenuBar()
            menu = wx.Menu()

            menu.Append(101, "&Mercury", "This the text in the Statusbar")
            menu.Append(102, "&Venus", "")
            menu.Append(103, "&Earth", "You may select Earth too")
            menu.AppendSeparator()
            menu.Append(104, "&Close", "Close this frame")

            bar.Append(menu, 'File')
            self.SetMenuBar(bar)

            dlg = SE.ShortcutEditor(self)
            dlg.FromMenuBar(self)

            if dlg.ShowModal() == wx.ID_OK:
                # Changes accepted, send back the new shortcuts to the TLW wx.MenuBar
                dlg.ToMenuBar(self)

            dlg.Destroy()

``EVT_SHORTCUT_CHANGING`` Event emitted when the user is about to change a shortcut.
``EVT_SHORTCUT_CHANGED``  Event emitted when the user has changed a shortcut.

:class:`ShortcutEditor` has been tested on the following platforms:
  * Windows (Windows Vista/7);

:class:`ShortcutEditor` is distributed under the wxPython license.

# SHORTCUTEDITOR wxPython IMPLEMENTATION
# Inspired By the GIMP Shortcut Editor.
#
# Andrea Gavana, @ 05 March 2012
#
#
# TODO List
#
# 1. Check the various IDs in the KEYMAP dictionary to try and understand if all
#    the possible shortcut combinations can be handled.
#
# 2. Verify that the current shortcut handling is working as advertised.
#
#
#
#
#
#

:class:`ConflictDialog` is a subclass of :class:`GenericMessageDialog`, customized to look
like the GIMP conflict dialog. This class is used to resolve shortcut
conflicts when the user assigns a shortcut that is already taken by another
entry in the shortcut list.

:param `parent`: an instance of :class:`ShortcutEditor`;
:param `conflict`: an instance of :class:`Shortcut`, representing the conflicting
 shortcut.

A simple :class:`wx.Frame` container for the basic help provided to :class:`ShortcutEditor`.
The help page is actually straightly derived from:

:param string `htmlFile`: a valid HTML file containing either the default help
 or your particular definition of help.

Creates a toolbar for :class:`HTMLHelpWindow` containing the standard browsing
buttons like `Back`, `Forward`, `Home`, `Refresh` and `Print`.

:param `toolbar`: an instance of :class:`ToolBar`.

Handles the ``wx.EVT_CLOSE`` event for :class:`HTMLHelpWindow`.

:param `event`: an instance of :class:`CloseEvent`.

Handles all the ``wx.EVT_TOOL`` events for :class:`HTMLHelpWindow`.

:param `event`: an instance of :class:`CommandEvent`.

Handles all the ``wx.EVT_UPDATE_UI`` events for :class:`HTMLHelpWindow`.

:param `event`: an instance of :class:`UpdateUIEvent`.

:class:`ListShortcut` is a subclass of :class:`~wx.lib.agw.hypertreelist.HyperTreeList`,
customized to look like the GIMP main shortcut list. This class is used to display the
shortcut label (with an optional bitmap next to it), its accelerator and
the help string associated with it (if present).

This information is displayed in 3 columns inside :class:`ListShortcut`.

:param `parent`: an instance of :class:`ShortcutEditor`.

Returns ``True`` if the input `accelerator` is a valid shortcut, ``False`` otherwise.

:param `shortcut`: an instance of :class:`Shortcut`;
:param string `accelerator`: the new accelerator to check.

:note: Conflicting shortcuts are handled inside this method by presenting the user with
 a conflict dialog. At this point the user can decide to reassign an existing shortcut
 or to back away, in which case this method will return ``False``.

Recursively builds the :class:`ListShortcut` image list based on the bitmaps in the
:class:`Shortcut` hierarchy.

:param `shortcut`: an instance of :class:`Shortcut`. If ``None``, it is defaulted to
 `self.manager` to make this function reentrant (i.e. allow more than one
 enumeration on one and the same object simultaneously);
:param integer `index`: the current image index inside the :class:`ListShortcut` own :class:`wx.ImageList`.

Calculates an offset (in pixels) so that the :class:`Shortcut` items without
a bitmap look parallel to the ones with a bitmap.

If the user decides to reassign a shortcut to another item, this method will disable
the conflicting shortcut (by putting a "Disabled" string as its accelerator).

:param `conflict`: an instance of :class:`Shortcut` to reset;
:param `item`: an instance of :class:`~wx.lib.agw.customtreectrl.GenericTreeItem`. If defaulted to ``None``, it is set
 to the :class:`ListShortcut` root item and used only to make this function reentrant
 (i.e. allow more than one enumeration on one and the same object simultaneously).

Fires the ``EVT_SHORTCUT_CHANGED`` event for :class:`ListShortcut`.

:param `shortcut`: an instance of :class:`Shortcut` that has been renamed;
:param string `newAccel`: the new accelerator just entered by the user.

Fires the ``EVT_SHORTCUT_CHANGING`` event for :class:`ListShortcut`.

The event propagation (and thus the shortcut renaming by the user) can be
interrupted by *not* calling `event.Skip()` in your handler for this event.

:param `shortcut`: an instance of :class:`Shortcut` that is about to be renamed;

Return a hashable object that represents the identity of a :class:`ListShortcut` item.

In this implementation this returns the item label.

:param `item`: an instance of :class:`~wx.lib.agw.customtreectrl.GenericTreeItem`.

Overridden from :class:`wx.Window` as a workaround on the conflicts between `treemixin` and
:class:`~wx.lib.agw.hypertreelist.HyperTreeList` with the ``wx.TR_HIDE_ROOT`` `agwStyle` set.

:param integer `flag`: an integer bit flag specifying the `agwStyle` style.

:return: ``True`` if the :class:`ListShortcut` has the input `flag` set, ``False`` otherwise.

Builds the :class:`ListShortcut` image list based on the bitmaps in the :class:`Shortcut` hierarchy. 

Handles the ``wx.EVT_TREE_ITEM_COLLAPSED`` / ``wx.EVT_TREE_ITEM_EXPANDED`` events for :class:`ListShortcut`.

:param `event`: an instance of :class:`TreeEvent`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`ListShortcut`.

:param `event`: an instance of :class:`FocusEvent`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`ListShortcut`.

Handles the ``wx.EVT_TREE_SEL_CHANGED`` event for :class:`ListShortcut`.

Handles the ``wx.EVT_CHAR_HOOK`` event for :class:`ShortcutEditor`, implemented in :class:`ListShortcut`
as it is easier to deal with in this class.

:param `event`: an instance of :class:`KeyEvent`.

Recursively populates the :class:`ListShortcut` with information from the :class:`Shortcut` tree.

:param `item`: an instance of :class:`~wx.lib.agw.customtreectrl.GenericTreeItem`. If ``None``, it is defaulted to
 the :class:`ListShortcut` root item to make this function reentrant (i.e. allow more than one

Sets the `filter` string against all the shortcuts in the :class:`ListShortcut` are matched.

:param string `filter`: a string to match.

Shows/Hides a :class:`TextCtrl` used to display the combination of keystrokes the user
has entered. This :class:`TextCtrl` remains visible only for a short amount of time
and only when some keys are down.

:param bool `show`: ``True`` to show the :class:`TextCtrl`, ``False`` to hide it.

:class:`Shortcut` is a class containing the details for a shortcut, whether from
a menu item, an accelerator or a user-defined shortcut. It behaves like
a tree, with children and parents.

:param string `label`: the shortcut label string;
:param string `accelerator`: the shortcut accelerator string;
:param `bitmap`: an instance of :class:`wx.Bitmap`, to display along the shortcut `label`
 in the interface tree;
:param string `help`: the help string for this shortcut, to display in the interface tree;
:param `menuItem`: if this :class:`Shortcut` is derived from a :class:`wx.MenuItem`, the :class:`wx.MenuItem`
 to which it should be associated;
:param integer `accelId`: if this :class:`Shortcut` is derived from an accelerator in a :class:`AcceleratorTable`
 or from a custom, developer-defined shortcut, it represents the ID it is associated with.

__init__(self, label='', accelerator='', bitmap=wx.NullBitmap, help='', menuItem=None, accelId=None)

Appends a :class:`Shortcut` item as a last child of its parent.

:param `item`: an instance of :class:`Shortcut`.

Checks if a shortcut string entered by the user has already been taken by another entry
in the :class:`Shortcut` hierarchy.

:param `item`: an instance of :class:`Shortcut`;
:param `shortcut`: another instance of :class:`Shortcut`, to compare with the previous `item`;
:param string `accelerator`: the user-edited accelerator string to check.

:return: An instance of :class:`Shortcut` if the shortcut string entered by the user conflicts
 with an existing one, ``None`` otherwise.

Constructs this :class:`Shortcut` starting from a :class:`wx.Menu` or :class:`wx.MenuItem`.

The attributes needed to properly construct a :class:`Shortcut` are the label,
the accelerator string, the help string (optional) and the bitmap associated
with it (optional).

Returns an instance of :class:`Shortcut` whose label matches the input `label` string.

:param string `label`: the string label to compare against this :class:`Shortcut` label;
:param `item`: an instance of :class:`Shortcut`, used only to make this function reentrant

:return: An instance of :class:`Shortcut` or ``None`` if no match was found.

Returns the bitmap associated with this :class:`Shortcut`.

:note: You should always check if the returned bitmap is a valid one or not::

    bitmap = shortcut.GetBitmap()
    if bitmap.IsOk():
        DoSomething()

 as the default bitmap associated with a :class:`Shortcut` is :class:`NullBitmap`.

Returns an instance of :class:`Shortcut` whose ID matches the input `id`.

:param integer `id`: an integer ID to compare against this :class:`Shortcut` id;

Returns this :class:`Shortcut`'s first child and an integer value 'cookie'.
Call :meth:`~Shortcut.GetNextChild` for the next child using this very 'cookie' return

:return: A tuple with the first value being an instance of :class:`Shortcut` or ``None`` if there are no

Returns an integer index to be used in the :class:`ListShortcut` own :class:`wx.ImageList`. 

Returns this :class:`Shortcut`'s next child.

:param integer `cookie`: a parameter which is opaque for the application but is necessary
 for the library to make this function reentrant (i.e. allow more than one

Returns ``True`` if the current accelerator associated with this :class:`Shortcut` is
different from the original one, ``False`` otherwise.

Returns ``True`` if this :class:`Shortcut` is associated with a top-level :class:`wx.Menu`,
(i.e., in the top :class:`wx.MenuBar` level), ``False`` otherwise.

Matches this :class:`Shortcut` label string against the `filter` input variable.

:param string `filter`: a string to match;
:param `item`: an instance of :class:`Shortcut`: its label string is compared with
 the `filter` string to look for a match.

:return: An instance of :class:`Shortcut` if the `filter` string is contained in
 the `item` label, ``None`` otherwise.

:note: The string-matching is case-insensitive.

Set the status of this :class:`Shortcut` and its parent as `hidden` in the
:class:`ListShortcut` tree hierarchy.

Restore the original shortcut string for this :class:`Shortcut`.

Sets the string accelerator associated with this shortcut.

:param string `accelerator`: a string representing the shortcut string (accelerator).

Sets the bitmap associated with this :class:`Shortcut`.

:param `bitmap`: an instance of :class:`wx.Bitmap` (can be invalid, i.e., :class:`NullBitmap`).

Set the status of this :class:`Shortcut` ans its parent as `shown` in the

Dumps this :class:`Shortcut` into a tuple of 3 elements:

* **flags**: a bitmask of ``wx.ACCEL_ALT``, ``wx.ACCEL_SHIFT``, ``wx.ACCEL_CTRL``, ``wx.ACCEL_CMD``
  or ``wx.ACCEL_NORMAL`` used to specify which modifier keys are held down;
* **keyCode**: the keycode to be detected (i.e., ord('b'), wx.WXK_F10, etc...);
* **cmdID**: the menu or control command ID to use for the accelerator event.

:param `table`: a list of tuples, with the above specifications.

Dumps this :class:`Shortcut` into a :class:`wx.Menu` or :class:`wx.MenuItem`.

The attributes needed to properly dump a :class:`Shortcut` into a :class:`wx.Menu` or :class:`wx.MenuBar`
are the label and the accelerator string.

:param `menuBar`: an instance of :class:`wx.MenuBar`.

:param `parent`: an instance of :class:`wx.Window`, it can also be ``None``.

Binds a few events we will need to process:

* ``wx.EVT_TEXT`` for the label filtering;
* ``wx.EVT_BUTTON`` for clearing the filtering, for the HTML help window and
  to reset all the shortcuts to their defaults.

Creates all the widgets needed to populate the interface, such as buttons,
texts and, most importantly, :class:`ListShortcut`.

Lays out the widgets using sizers in a platform-independent way. 

Builds the entire shortcut hierarchy starting from a modified version of a :class:`AcceleratorTable`.

:param `accelTable`: a modified version of :class:`AcceleratorTable`, is a list of tuples (4 elements per tuple),
 populated like this::

    accelTable = []

    # Every tuple is defined in this way:

    for label, flags, keyCode, cmdID in my_accelerators:
        # label:   the string used to show the accelerator into the ShortcutEditor dialog
        # flags:   a bitmask of wx.ACCEL_ALT, wx.ACCEL_SHIFT, wx.ACCEL_CTRL, wx.ACCEL_CMD,
        #          or wx.ACCEL_NORMAL used to specify which modifier keys are held down
        # keyCode: the keycode to be detected (i.e., ord('b'), wx.WXK_F10, etc...)
        # cmdID:   the menu or control command ID to use for the accelerator event.

        accel_tuple = (label, flags, keyCode, cmdID)
        accelTable.append(accel_tuple)

Builds the entire shortcut hierarchy starting from a :class:`wx.MenuBar`.

:param `topWindow`: an instance of :class:`TopLevelWindow`, containing the :class:`wx.MenuBar`
 we wish to scan.

Returns the root :class:`Shortcut` containing the whole shortcut hierarchy. 

Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user clears the
label filter at the top of the user interface.

Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user presses the ``Help``
button.

.. note::

   By default, this method launches a :class:`html.HtmlWindow` containing the default
   HTML help file. If you wish to load another help file, you should call :meth:`~ShortcutEditor.SetHTMLHelpFile`
   with another input HTML file.

Handles the ``wx.EVT_BUTTON`` event for :class:`ShortcutEditor` when the user restores the
original shortcuts.

Handles the ``wx.EVT_TEXT`` event for :class:`ShortcutEditor`.

:param `event`: if not ``None``, an instance of :class:`KeyEvent`.

Does some more common initialization before showing :class:`ShortcutEditor`. 

Sets the :class:`ListShortcut` columns widths to acceptable and eye-pleasing
numbers (in pixels).

Sets a new HTML help file (a valid html file) to be loaded when the user seeks
for an explanation on how the UI works.

:param string `htmlFile`: a valid HTML file.

Hides or shows the :class:`ShortcutEditor` dialog.

The preferred way of dismissing a modal dialog is to use `EndModal`.

:param bool `show`: if ``True``, the dialog box is shown and brought to the front,
 otherwise the box is hidden. If ``False`` and the dialog is modal, control is
 returned to the calling program.

Shows the :class:`ShortcutEditor` dialog in an application-modal way.

Program flow does not return until the dialog has been dismissed with `EndModal`.

:return: The value set with :meth:`~Dialog.SetReturnCode`.

.. note::

   Notice that it is possible to call :meth:`~ShortcutEditor.ShowModal` for a dialog which had been
   previously shown with :meth:`~ShortcutEditor.Show`, this allows to make an existing modeless dialog
   modal. However :meth:`~ShortcutEditor.ShowModal` can't be called twice without intervening `EndModal` calls.

.. note::

   Note that this function creates a temporary event loop which takes precedence
   over the application's main event loop (see :class:`EventLoopBase`) and which is
   destroyed when the dialog is dismissed. This also results in a call to
   :meth:`AppConsole.ProcessPendingEvents` ().

Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`AcceleratorTable`), into
a :class:`AcceleratorTable`. This method **does** rebuild the :class:`AcceleratorTable` and sets it back
to the input `window`.

:param `window`: an instance of :class:`wx.Window`, to which the new :class:`AcceleratorTable` should be set.

Dumps the entire shortcut hierarchy (for shortcuts associated with a :class:`wx.MenuItem`), into
a :class:`wx.MenuBar`, changing only the :class:`wx.Menu` / :class:`wx.MenuItem` labels (it does **not** rebuild
the :class:`wx.MenuBar`).

 we wish to repopulate.

:class:`ShortcutEvent` is a special subclassing of :class:`PyCommandEvent`.

This event gets emitted when the user is about to change a shortcut (via ``EVT_SHORTCUT_CHANGING``)
and when the user has changed a shortcut (via ``EVT_SHORTCUT_CHANGED``).

:param integer `evtId`: the event identifier.

Gets the shortcut string for which the operation was performed for ``EVT_SHORTCUT_CHANGED``
and ``EVT_SHORTCUT_CHANGING`` events.

:return: A string representing the new shortcut string (accelerator).

Returns the previous shortcut string for ``EVT_SHORTCUT_CHANGED`` and
``EVT_SHORTCUT_CHANGING`` events.

:return: A string representing the old shortcut string (accelerator).

Returns the shortcut class used for ``EVT_SHORTCUT_CHANGED`` and

:return: An instance of :class:`Shortcut`.

Sets the shortcut string for which the operation was performed for ``EVT_SHORTCUT_CHANGED``

:param string `accelerator`: a string representing the new shortcut string (accelerator).

Sets the previous shortcut string for ``EVT_SHORTCUT_CHANGED`` and

:param string `accelerator`: a string representing the old shortcut string (accelerator).

Sets the shortcut class used for ``EVT_SHORTCUT_CHANGED`` and

:param `shortcut`: an instance of :class:`Shortcut`.

Creates a copy of the input `font`.

{8: 'Back', 9: 'Tab', 13: 'Enter', 27: 'Esc', 32: 'Space', 127: 'Delete', 300: 'Start', 303: 'Cancel', 305: 'Clear', 309: 'Menu', 310: 'Pause', 311: 'Capital', 312: 'End', 313: 'Home', 314: 'Left', 315: 'Up', 316: 'Right', 317: 'Down', 318: 'Select', 319: 'Print', 320: 'Execute', 321: 'Snapshot', 322: 'Insert', 323: 'Help', 334: '*', 335: '+', 337: '-', 338: '.', 339: '/', 340: 'F1', 341: 'F2', 342: 'F3', 343: 'F4', 344: 'F5', 345: 'F6', 346: 'F7', 347: 'F8', 348: 'F9', 349: 'F10', 350: 'F11', 351: 'F12', 352: 'F13', 353: 'F14', 354: 'F15', 355: 'F16', 356: 'F17', 357: 'F18', 358: 'F19', 359: 'F20', 360: 'F21', 361: 'F22', 362: 'F23', 363: 'F24', 364: 'NumLock', 365: 'Scroll', 366: 'PgUp', 367: 'PgDn'}

:class:`~wx.lib.agw.speedmeter.SpeedMeter` tries to reproduce the behavior of some car controls (but not only),
by creating an "angular" control (actually, circular).

:class:`SpeedMeter` tries to reproduce the behavior of some car controls (but not only),
by creating an "angular" control (actually, circular). I remember to have seen
it somewhere, and i decided to implement it in wxPython.

:class:`SpeedMeter` starts its construction from an empty bitmap, and it uses some
functions of the :class:`wx.DC` class to create the rounded effects. everything is
processed in the `Draw()` method of :class:`SpeedMeter` class.

This implementation allows you to use either directly the :class:`PaintDC`, or the
better (for me) double buffered style with :class:`BufferedPaintDC`. the double
buffered implementation has been adapted from the wxPython wiki example:

http://wiki.wxpython.org/index.cgi/doublebuffereddrawing

Usage
=====

    import wx
    import wx.lib.agw.speedmeter as SM

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

            speed = SM.SpeedMeter(self, agwStyle=SM.SM_DRAW_HAND|SM.SM_DRAW_SECTORS|SM.SM_DRAW_MIDDLE_TEXT|SM.SM_DRAW_SECONDARY_TICKS)

            # Set The Region Of Existence Of SpeedMeter (Always In Radians!!!!)
            speed.SetAngleRange(-pi/6, 7*pi/6)

            # Create The Intervals That Will Divide Our SpeedMeter In Sectors
            intervals = range(0, 201, 20)
            speed.SetIntervals(intervals)

            # Assign The Same Colours To All Sectors (We Simulate A Car Control For Speed)
            # Usually This Is Black
            colours = [wx.BLACK]*10
            speed.SetIntervalColours(colours)

            # Assign The Ticks: Here They Are Simply The String Equivalent Of The Intervals
            ticks = [str(interval) for interval in intervals]
            speed.SetTicks(ticks)
            # Set The Ticks/Tick Markers Colour
            speed.SetTicksColour(wx.WHITE)
            # We Want To Draw 5 Secondary Ticks Between The Principal Ticks
            speed.SetNumberOfSecondaryTicks(5)

            # Set The Font For The Ticks Markers
            speed.SetTicksFont(wx.Font(7, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_NORMAL))

            # Set The Text In The Center Of SpeedMeter
            speed.SetMiddleText("Km/h")
            # Assign The Colour To The Center Text
            speed.SetMiddleTextColour(wx.WHITE)
            # Assign A Font To The Center Text
            speed.SetMiddleTextFont(wx.Font(8, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD))

            # Set The Colour For The Hand Indicator
            speed.SetHandColour(wx.Colour(255, 50, 0))

            # Do Not Draw The External (Container) Arc. Drawing The External Arc May
            # Sometimes Create Uglier Controls. Try To Comment This Line And See It
            # For Yourself!
            speed.DrawExternalArc(False)

            # Set The Current Value For The SpeedMeter
            speed.SetSpeedValue(44)

:class:`SpeedMeter` is highly customizable, and in particular you can set:

- The start and end angle of existence for :class:`SpeedMeter`;
- The intervals in which you divide the :class:`SpeedMeter` (numerical values);
- The corresponding thicks for the intervals;
- The interval colours (different intervals may have different filling colours);
- The ticks font and colour;
- The background colour (outsize the :class:`SpeedMeter` region);
- The external arc colour;
- The hand (arrow) colour;
- The hand's shadow colour;
- The hand's style ("arrow" or "hand");
- The partial filler colour;
- The number of secondary (intermediate) ticks;
- The direction of increasing speed ("advance" or "reverse");
- The text to be drawn in the middle and its font;
- The icon to be drawn in the middle;
- The first and second gradient colours (that fills the :class:`SpeedMeter` control);
- The current value.

``SM_ROTATE_TEXT``                  0x1 Draws the ticks rotated: the ticks are rotated accordingly to the tick marks positions.
``SM_DRAW_SECTORS``                 0x2 Different intervals are painted in different colours (every sector of the circle has its own colour).
``SM_DRAW_PARTIAL_SECTORS``         0x4 Every interval has its own colour, but only a circle corona is painted near the ticks.
``SM_DRAW_HAND``                    0x8 The hand (arrow indicator) is drawn.
``SM_DRAW_SHADOW``                 0x10 A shadow for the hand is drawn.
``SM_DRAW_PARTIAL_FILLER``         0x20 A circle corona that follows the hand position is drawn near the ticks.
``SM_DRAW_SECONDARY_TICKS``        0x40 Intermediate (smaller) ticks are drawn between principal ticks.
``SM_DRAW_MIDDLE_TEXT``            0x80 Some text is printed in the middle of the control near the center.
``SM_DRAW_MIDDLE_ICON``           0x100 An icon is drawn in the middle of the control near the center.
``SM_DRAW_GRADIENT``              0x200 A gradient of colours will fill the control.
``SM_DRAW_FANCY_TICKS``           0x400 With this style you can use xml tags to create some custom text and draw it at the ticks position. See :mod:`lib.fancytext` for the tags.

:class:`SpeedMeter` is distributed under the wxPython license.

# SPEEDMETER Control wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 25 Sep 2005
#
#
#
# 1. Combination Of The Two Styles:
#
#    SM_DRAW_PARTIAL_FILLER
#    SM_DRAW_SECTORS
#
#    Does Not Work Very Well. It Works Well Only In Case When The Sector Colours
#    Are The Same For All Intervals.
#
#
# Thanks To Gerard Grazzini That Has Tried The Demo On MacOS, I Corrected A
# Bug On Line 246
#
#
#
#
#
#

A buffered window class.

:param `bufferedstyle`: if set to ``SM_BUFFERED_DC``, double-buffering will
 be used.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_FULL_REPAINT_ON_RESIZE, bufferedstyle=SM_BUFFERED_DC)

elsewhere in the system. if that data changes, the drawing needs to

:param `agwStyle`: this value specifies the :class:`SpeedMeter` styles, and can be a
 combination of the following bits:

 ``SM_ROTATE_TEXT``                  0x1 Draws the ticks rotated: the ticks are rotated accordingly to the tick marks positions.
 ``SM_DRAW_SECTORS``                 0x2 Different intervals are painted in different colours (every sector of the circle has its own colour).
 ``SM_DRAW_PARTIAL_SECTORS``         0x4 Every interval has its own colour, but only a circle corona is painted near the ticks.
 ``SM_DRAW_HAND``                    0x8 The hand (arrow indicator) is drawn.
 ``SM_DRAW_SHADOW``                 0x10 A shadow for the hand is drawn.
 ``SM_DRAW_PARTIAL_FILLER``         0x20 A circle corona that follows the hand position is drawn near the ticks.
 ``SM_DRAW_SECONDARY_TICKS``        0x40 Intermediate (smaller) ticks are drawn between principal ticks.
 ``SM_DRAW_MIDDLE_TEXT``            0x80 Some text is printed in the middle of the control near the center.
 ``SM_DRAW_MIDDLE_ICON``           0x100 An icon is drawn in the middle of the control near the center.
 ``SM_DRAW_GRADIENT``              0x200 A gradient of colours will fill the control.
 ``SM_DRAW_FANCY_TICKS``           0x400 With this style you can use xml tags to create some custom text and draw it at the ticks position. See :mod:`lib.fancytext` for the tags.

:param `bufferedstyle`: this value allows you to use the normal :class:`PaintDC` or the
 double buffered drawing options:

 Buffered Styles             Hex Value   Description
 ``SM_NORMAL_DC``                    0x0 Uses the normal :class:`PaintDC`
 ``SM_BUFFERED_DC``                  0x1 Uses the double buffered drawing style

:param `mousestyle`: this value allows you to use the mouse to change the :class:`SpeedMeter`
 value interactively with left click/drag events. If set to ``SM_MOUSE_TRACK``, the mouse
 left click/drag allow you to change the :class:`SpeedMeter` value interactively.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=SM_DRAW_HAND, bufferedstyle=SM_BUFFERED_DC, mousestyle=0)

Converts the input values into logical x, y coordinates.

:param `radius`: the :class:`SpeedMeter` radius;
:param `centerX`: the `x` position of the :class:`SpeedMeter` center;
:param `centerX`: the `y` position of the :class:`SpeedMeter` center.

Specify whether or not you wish to draw the external (thicker) arc.

:param `draw`: ``True`` to draw the external arc, ``False`` otherwise.

Returns the range of existence for :class:`SpeedMeter`.
The returned values are in radians.

Returns the intervals for :class:`SpeedMeter`, a Python list of main ticks displayed. 

Returns the icon to be drawn near the center of :class:`SpeedMeter`. 

Returns the text to be drawn near the center of :class:`SpeedMeter`. 

Returns the background colour outside the :class:`SpeedMeter` control.

Returns a list of strings and a list of integers containing the styles. 

Returns the ticks for :class:`SpeedMeter` intervals (main ticks string values).

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`SpeedMeter`.

:note: Here only left clicks/drags are involved. Should :class:`SpeedMeter`
 have something more?

Sets the range of existence for :class:`SpeedMeter`.

:param `start`: the starting angle, in radians;
:param `end`: the ending angle, in radians.

Sets the external arc colour (thicker line).

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, the arc
 colour will be black.

Sets the direction of advancing :class:`SpeedMeter` value.

:param `direction`: specifying "advance" will move the hand in clock-wise direction
 (like normal car speed control), while using "reverse" will move it counterclock-wise
 direction. If defaulted to ``None``, then "advance" will be used.

Sets the partial filler colour.

A circle corona near the ticks will be filled with this colour, from
the starting value to the current value of :class:`SpeedMeter`.

Sets the first gradient colour (near the ticks).

Sets the hand (arrow indicator) colour.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, the arrow
 indicator will be red.

Sets the style for the hand (arrow indicator).

:param `style`: by specifying "Hand", :class:`SpeedMeter` will draw a polygon
 that simulates the car speed control indicator. Using "Arrow" will force
 :class:`SpeedMeter` to draw a simple arrow. If defaulted to ``None``, "Hand" will
 be used.
 
Sets the colours for the intervals.

:param `colours`: a Python list of colours. The length of this list should be
 the same as the number of circle sectors in :class:`SpeedMeter`. If defaulted to ``None``,
 all the intervals will have a white colour.

:note: Every interval (circle sector) should have a colour.

Sets the intervals for :class:`SpeedMeter` (main ticks numeric values).

:param `intervals`: a Python list of main ticks to be displayed. If defaulted
 to ``None``, the list `[0, 50, 100]` is used.

Sets the icon to be drawn near the center of :class:`SpeedMeter`.

:param `icon`: a valid :class:`wx.Bitmap` object.

Sets the text to be drawn near the center of :class:`SpeedMeter`.

:param `text`: the text to be drawn near the center of :class:`SpeedMeter`. If
 defaulted to ``None``, an empty string will be used.

Sets the colour for the text in the middle.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, the text
 in the middle will be painted in blue.

Sets the font for the text in the middle.

:param `font`: a valid :class:`wx.Font` object. If defaulted to ``None``, some
 standard font will be generated.

Sets the number of secondary (intermediate) ticks.

:param `ticknum`: the number of intermediate ticks. If defaulted to ``None``,
 3 ticks are used.

Sets the second gradient colour (near the center).

Sets the hand's shadow colour.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, the shadow
 colour will be light grey.

Sets the background colour outside the :class:`SpeedMeter` control.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, the
 :class:`SpeedMeter` background will be taken from the system default.

Sets the current value for :class:`SpeedMeter`.

:param `value`: a floating point number representing the current value. If defaulted
 to ``None``, the :class:`SpeedMeter` value will be the middle point of the control range.

Sets the ticks for :class:`SpeedMeter` intervals (main ticks string values).

:param `ticks`: a Python list of strings, representing the ticks values.
 If defaulted to ``None``, the ticks will be taken from the interval values.

Sets the ticks colour.

 ticks colour will be set as blue.

Sets the ticks font.

:param `font`: a valid :class:`wx.Font` object. If defaulted to ``None``, some standard
 font will be chosen automatically.

['default', 'decorative', 'roman', 'script', 'swiss', 'modern', 'teletype', 'unknown']

['invalid', 'thin', 'extra-light', 'normal', 'medium', 'semi-bold', 'bold', 'extra-bold', 'heavy', 'extra-heavy']

:class:`~wx.lib.agw.supertooltip.SuperToolTip` is a class that mimics the behaviour of :class:`TipWindow` and generic tooltip
windows, although it is a custom-drawn widget.

:class:`SuperToolTip` is a class that mimics the behaviour of :class:`TipWindow` and generic tooltip

This class supports:

* Blended triple-gradient for the tooltip background;
* Header text and header image, with possibility to set the header font independently;
* Footer text and footer image, with possibility to set the footer font independently;
* Multiline text message in the tooltip body, plus an optional image as "body image";
* Bold lines and hyperlink lines in the tooltip body;
* A wide set of predefined drawing styles for the tooltip background;
* Drawing of separator lines after the header and/or before the footer;
* Rounded corners and shadows below the tooltip window (Windows XP only);
* Fade in/fade out effects (Windows XP only);
* User-settable delays for the delay after which the tooltip appears and the delay
  after which the tooltip is destroyed.

Usage
=====

    import wx
    import wx.lib.agw.supertooltip as STT

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

            button = wx.Button(panel, -1, "I am the SuperToolTip target", pos=(100, 50))

            tip = STT.SuperToolTip("A nice tooltip message")

            tip.SetHeader("Hello World")
            tip.SetTarget(button)
            tip.SetDrawHeaderLine(True)

            tip.ApplyStyle("Office 2007 Blue")

            tip.SetDropShadow(True)

:class:`SuperToolTip` has been tested on the following platforms:

:class:`SuperToolTip` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 04 Feb 2013, 21.00 GMT

# SUPERTOOLTIP wxPython IMPLEMENTATION
#
# Latest Revision: 04 Feb 2013, 21.00 GMT
#
#
# TODO List
#
# 1) Maybe add some more customization like multiline text
#    in the header and footer;
# 2) Check whether it's possible to use rounded corners and
#    shadows on the Mac
# 3) Split OnPaint() into smaller pieces to improve readability and
#    ability to redefine behaviour in subclasses
# 4) Extend text formatting capabilities
# 5) Make better use of links (right now it's difficult to click them without hiding tooltip)
#
#
#
#
#

The main class for :class:`SuperToolTip`, which holds all the methods
and setters/getters available to the user.

:param `message`: the main message in :class:`SuperToolTip` body;
:param `bodyImage`: the image in the :class:`SuperToolTip` body;
:param `header`: the header text;
:param `headerBmp`: the header bitmap;
:param `footer`: the footer text;
:param `footerBmp`: the footer bitmap.

__init__(self, message, bodyImage=wx.NullBitmap, header="", headerBmp=wx.NullBitmap, footer="", footerBmp=wx.NullBitmap)

Applies none of the predefined styles.

:param `style`: one of the predefined styles available at the
 beginning of the module.

Dismiss the :class:`SuperToolTip` window immediately.

Globally (application-wide) enables/disables :class:`SuperToolTip`.

:param `enable`: ``True`` to enable :class:`SuperToolTip` globally, ``False`` otherwise.

Returns whether the separator line before the footer is drawn or not. 

Returns whether the separator line after the header is drawn or not. 

Returns whether a shadow below :class:`SuperToolTip` is drawn or not.

:note: This method is available only on Windows and requires Mark Hammond's
 pywin32 package.

Returns the delay time (in seconds) after which the :class:`SuperToolTip` is destroyed.

Returns the tim delay (in seconds) after which the :class:`SuperToolTip` is created.

Returns whether a fade in/fade out effect is used or not.

Returns ``True`` when :class:`SuperToolTip` is globally enabled, ``False`` otherwise.

The show time for :class:`SuperToolTip` has expired, destroy the :class:`SuperToolTip`. 

The creation time has expired, create the :class:`SuperToolTip`. 

Starts the :class:`SuperToolTip` timer for creation, handles the ``wx.EVT_ENTER_WINDOW`` event.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for the target widgets.

Sets the main body bitmap for :class:`SuperToolTip`.

:param `bmp`: the body bitmap, a valid :class:`wx.Bitmap` object.

Sets the bottom gradient colour for :class:`SuperToolTip`.

:param `colour`: the colour to use as bottom colour, a valid :class:`wx.Colour` object.

Sets whether to draw a separator line before the footer or not.

:param `draw`: ``True`` to draw a separator line before the footer, ``False``

Sets whether to draw a separator line after the header or not.

:param `draw`: ``True`` to draw a separator line after the header, ``False``

Whether to draw a shadow below :class:`SuperToolTip` or not.

:param `drop`: ``True`` to drop a shadow below the control, ``False`` otherwise.

Sets the delay time (in seconds) after which the :class:`SuperToolTip` is destroyed.

:param `delay`: the delay in seconds.

Sets the footer text.

:param `footer`: the footer text to display.

Sets the footer bitmap for :class:`SuperToolTip`.

:param `bmp`: the footer bitmap, a valid :class:`wx.Bitmap` object.

Sets the font for the footer text.

:param `font`: the font to use for the footer text, a valid :class:`wx.Font`
 object.

Sets the header text.

:param `header`: the header text to display.

Sets the header bitmap for :class:`SuperToolTip`.

:param `bmp`: the header bitmap, a valid :class:`wx.Bitmap` object.

Sets the font for the header text.

:param `font`: the font to use for the header text, a valid :class:`wx.Font`
 object.

Sets the font for the hyperlink text.

:param `font`: the font to use for the hyperlink text, a valid :class:`wx.Font`
 object.

Sets the main body message for :class:`SuperToolTip`.

:param `message`: the message to display in the body.

Sets the font for the main body message.

:param `font`: the font to use for the main body message, a valid :class:`wx.Font`
 object.

Sets the middle gradient colour for :class:`SuperToolTip`.

:param `colour`: the colour to use as middle colour, a valid :class:`wx.Colour` object.

Sets the time delay (in seconds) after which the :class:`SuperToolTip` is created.

Sets the target window for :class:`SuperToolTip`.

:param `widget`: the widget to which :class:`SuperToolTip` is associated.

Sets the text colour for :class:`SuperToolTip`.

:param `colour`: the colour to use as text colour, a valid :class:`wx.Colour` object.

Sets the top gradient colour for :class:`SuperToolTip`.

:param `colour`: the colour to use as top colour, a valid :class:`wx.Colour` object.

Whether to use a fade in/fade out effect or not.

:param `fade`: ``True`` to use a fade in/fade out effect, ``False`` otherwise.

top, although this is not needed if :meth:`~SuperToolTip.Show` is called immediately after the frame creation.

:param bool `show`: ``True`` to show the :class:`SuperToolTip` window, ``False`` to hide it.

.. note::

A simple :class:`PopupWindow` that holds fancy tooltips.
Not available on Mac as :class:`PopupWindow` is not implemented there.

:param `parent`: the :class:`SuperToolTip` parent widget;
:param `classParent`: the :class:`SuperToolTip` class object.

Handles the ``wx.EVT_TIMER`` event for :class:`SuperToolTip`.

Adds a shadow under the window.

:param `drop`: whether to drop a shadow or not.

Makes the :class:`SuperToolTip` window transparent.

:param `amount`: the alpha channel value.

Handles the ``wx.EVT_LEFT_DOWN``, ``wx.EVT_LEFT_DCLICK`` and ``wx.EVT_KILL_FOCUS``
events for :class:`SuperToolTip`. All these events destroy the :class:`SuperToolTip`,
unless the user clicked on one hyperlink.

:param `event`: a :class:`MouseEvent` or a :class:`FocusEvent` event to be processed.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`SuperToolTip`.

Handles the ``wx.EVT_MOTION`` event for :class:`SuperToolTip`.

Handles the ``wx.EVT_PAINT`` event for :class:`SuperToolTip`.

If the `event` parameter is ``None``, calculates best size and returns it.

:param `event`: a :class:`PaintEvent` event to be processed or ``None``.

Handles the ``wx.EVT_SIZE`` event for :class:`SuperToolTip`.

Sets the :class:`SuperToolTip` font globally.

:param `font`: the font to set.

Start the timer which set the alpha channel for :class:`SuperToolTip`.

:param `isShow`: whether :class:`SuperToolTip` is being shown or deleted.

Extract the link from an hyperlink line.

:param `line`: the line of text to be processed.

Makes a font bold. Utility method.

:param `font`: the font to be made bold.

{'Beige': (wx.Colour(-1, -1, -1, 255), wx.Colour(242, 242, 223, 255), wx.Colour(198, 195, 160, 255), wx.Colour(-1, -1, -1, 255)), 'Blue': (wx.Colour(-1, -1, -1, 255), wx.Colour(202, 220, 246, 255), wx.Colour(150, 180, 222, 255), wx.Colour(-1, -1, -1, 255)), 'Blue 2': (wx.Colour(-1, -1, -1, 255), wx.Colour(228, 236, 248, 255), wx.Colour(198, 214, 235, 255), wx.Colour(-1, -1, -1, 255)), 'Blue 3': (wx.Colour(-1, -1, -1, 255), wx.Colour(213, 233, 243, 255), wx.Colour(151, 195, 216, 255), wx.Colour(-1, -1, -1, 255)), 'Blue 4': (wx.Colour(-1, -1, -1, 255), wx.Colour(227, 235, 255, 255), wx.Colour(102, 153, 255, 255), wx.Colour(-1, -1, -1, 255)), 'Blue Glass': (wx.Colour(182, 226, 253, 255), wx.Colour(137, 185, 232, 255), wx.Colour(188, 244, 253, 255), wx.Colour(-1, -1, -1, 255)), 'Blue Glass 2': (wx.Colour(192, 236, 255, 255), wx.Colour(147, 195, 242, 255), wx.Colour(198, 254, 255, 255), wx.Colour(-1, -1, -1, 255)), 'Blue Glass 3': (wx.Colour(212, 255, 255, 255), wx.Colour(167, 215, 255, 255), wx.Colour(218, 255, 255, 255), wx.Colour(-1, -1, -1, 255)), 'Blue Inverted': (wx.Colour(117, 160, 222, 255), wx.Colour(167, 210, 240, 255), wx.Colour(233, 243, 255, 255), wx.Colour(-1, -1, -1, 255)), 'Blue Shift': (wx.Colour(124, 178, 190, 255), wx.Colour(13, 122, 153, 255), wx.Colour(0, 89, 116, 255), wx.Colour(-1, -1, -1, 255)), 'CodeProject': (wx.Colour(255, 250, 172, 255), wx.Colour(255, 207, 157, 255), wx.Colour(255, 153, 0, 255), wx.Colour(-1, -1, -1, 255)), 'Dark Gray': (wx.Colour(195, 195, 195, 255), wx.Colour(168, 168, 168, 255), wx.Colour(134, 134, 134, 255), wx.Colour(-1, -1, -1, 255)), 'Deep Purple': (wx.Colour(131, 128, 164, 255), wx.Colour(112, 110, 143, 255), wx.Colour(90, 88, 117, 255), wx.Colour(-1, -1, -1, 255)), 'Electric Blue': (wx.Colour(224, 233, 255, 255), wx.Colour(135, 146, 251, 255), wx.Colour(99, 109, 233, 255), wx.Colour(-1, -1, -1, 255)), 'Firefox': (wx.Colour(255, 254, 207, 255), wx.Colour(254, 248, 125, 255), wx.Colour(225, 119, 24, 255), wx.Colour(-1, -1, -1, 255)), 'Gold': (wx.Colour(255, 202, 0, 255), wx.Colour(255, 202, 0, 255), wx.Colour(255, 202, 0, 255), wx.Colour(-1, -1, -1, 255)), 'Gold Shift': (wx.Colour(178, 170, 107, 255), wx.Colour(202, 180, 32, 255), wx.Colour(162, 139, 1, 255), wx.Colour(-1, -1, -1, 255)), 'Gray': (wx.Colour(-1, -1, -1, 255), wx.Colour(228, 228, 228, 255), wx.Colour(194, 194, 194, 255), wx.Colour(-1, -1, -1, 255)), 'Green': (wx.Colour(234, 241, 223, 255), wx.Colour(211, 224, 180, 255), wx.Colour(182, 200, 150, 255), wx.Colour(-1, -1, -1, 255)), 'Green Shift': (wx.Colour(129, 184, 129, 255), wx.Colour(13, 185, 15, 255), wx.Colour(1, 125, 1, 255), wx.Colour(-1, -1, -1, 255)), 'Light Green': (wx.Colour(174, 251, 171, 255), wx.Colour(145, 221, 146, 255), wx.Colour(90, 176, 89, 255), wx.Colour(-1, -1, -1, 255)), 'NASA Blue': (wx.Colour(0, 91, 134, 255), wx.Colour(0, 100, 150, 255), wx.Colour(0, 105, 160, 255), wx.Colour(-1, -1, -1, 255)), 'Office 2007 Blue': (wx.Colour(-1, -1, -1, 255), wx.Colour(242, 246, 251, 255), wx.Colour(202, 218, 239, 255), wx.Colour(76, 76, 76, 255)), 'Orange Shift': (wx.Colour(179, 120, 80, 255), wx.Colour(183, 92, 19, 255), wx.Colour(157, 73, 1, 255), wx.Colour(-1, -1, -1, 255)), 'Outlook Green': (wx.Colour(236, 242, 208, 255), wx.Colour(219, 230, 187, 255), wx.Colour(195, 210, 155, 255), wx.Colour(-1, -1, -1, 255)), 'Pale Green': (wx.Colour(249, 255, 248, 255), wx.Colour(206, 246, 209, 255), wx.Colour(148, 225, 155, 255), wx.Colour(-1, -1, -1, 255)), 'Pink Blush': (wx.Colour(255, 254, 255, 255), wx.Colour(255, 231, 242, 255), wx.Colour(255, 213, 233, 255), wx.Colour(-1, -1, -1, 255)), 'Pink Shift': (wx.Colour(202, 135, 188, 255), wx.Colour(186, 8, 158, 255), wx.Colour(146, 2, 116, 255), wx.Colour(-1, -1, -1, 255)), 'Pretty Pink': (wx.Colour(255, 240, 249, 255), wx.Colour(253, 205, 217, 255), wx.Colour(255, 150, 177, 255), wx.Colour(-1, -1, -1, 255)), 'Red': (wx.Colour(255, 183, 176, 255), wx.Colour(253, 157, 143, 255), wx.Colour(206, 88, 78, 255), wx.Colour(-1, -1, -1, 255)), 'Red Shift': (wx.Colour(186, 102, 102, 255), wx.Colour(229, 23, 9, 255), wx.Colour(182, 11, 1, 255), wx.Colour(-1, -1, -1, 255)), 'Silver': (wx.Colour(-1, -1, -1, 255), wx.Colour(242, 242, 246, 255), wx.Colour(212, 212, 224, 255), wx.Colour(-1, -1, -1, 255)), 'Silver 2': (wx.Colour(-1, -1, -1, 255), wx.Colour(242, 242, 248, 255), wx.Colour(222, 222, 228, 255), wx.Colour(-1, -1, -1, 255)), 'Silver Glass': (wx.Colour(158, 158, 158, 255), wx.Colour(-1, -1, -1, 255), wx.Colour(105, 105, 105, 255), wx.Colour(-1, -1, -1, 255)), 'Silver Inverted': (wx.Colour(161, 160, 186, 255), wx.Colour(199, 201, 213, 255), wx.Colour(-1, -1, -1, 255), wx.Colour(-1, -1, -1, 255)), 'Silver Inverted 2': (wx.Colour(181, 180, 206, 255), wx.Colour(219, 221, 233, 255), wx.Colour(-1, -1, -1, 255), wx.Colour(-1, -1, -1, 255)), 'Soylent Green': (wx.Colour(134, 211, 131, 255), wx.Colour(105, 181, 106, 255), wx.Colour(50, 136, 49, 255), wx.Colour(-1, -1, -1, 255)), 'Spring Green': (wx.Colour(154, 231, 151, 255), wx.Colour(125, 201, 126, 255), wx.Colour(70, 156, 69, 255), wx.Colour(-1, -1, -1, 255)), 'Too Blue': (wx.Colour(-1, -1, -1, 255), wx.Colour(225, 235, 244, 255), wx.Colour(188, 209, 226, 255), wx.Colour(-1, -1, -1, 255)), 'Totally Green': (wx.Colour(190, 230, 160, 255), wx.Colour(190, 230, 160, 255), wx.Colour(190, 230, 160, 255), wx.Colour(-1, -1, -1, 255)), 'XP Blue': (wx.Colour(119, 185, 236, 255), wx.Colour(81, 144, 223, 255), wx.Colour(36, 76, 171, 255), wx.Colour(-1, -1, -1, 255)), 'Yellow': (wx.Colour(255, 255, 220, 255), wx.Colour(255, 231, 161, 255), wx.Colour(254, 218, 108, 255), wx.Colour(-1, -1, -1, 255))}

:class:`~wx.lib.agw.thumbnailctrl.ThumbnailCtrl` is a widget that can be used to display a series of images in
a "thumbnail" format.

:class:`ThumbnailCtrl` is a widget that can be used to display a series of images in
a "thumbnail" format; it mimics, for example, the windows explorer behavior
when you select the "view thumbnails" option.

The code is partly based on `wxVillaLib`, a wxWidgets implementation of this
control. However, :class:`ThumbnailCtrl` wouldn't have been so fast and complete
without the suggestions and hints from Peter Damoc. So, if he accepts the
mention, this control is his as much as mine.

:class:`ThumbnailCtrl` is more of a demo application than a widget.
The :class:`ScrolledThumbnail` is a freestanding widget, accepting a list of
:class:`Thumb` objects which represent files and which returns a thumbnail
on request.  :class:`Thumb` can be extended by the user to provide thumbnails
for other data types, such as text, audio, video, or PDF files.

Usage
=====

    import os

    import wx
    import wx.lib.agw.thumbnailctrl as TC

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

            thumbnail = TC.ThumbnailCtrl(panel, imagehandler=TC.NativeImageHandler)
            sizer.Add(thumbnail, 1, wx.EXPAND | wx.ALL, 10)

            thumbnail.ShowDir(os.getcwd())

With :class:`ThumbnailCtrl` you can:

- Delete files/thumbnails (via the ``del`` key);
- Drag and drop thumbnails from :class:`ThumbnailCtrl` to whatever application you want;
- Show/hide a :class:`ComboBox` at the top of :class:`ThumbnailCtrl`: this combobox contains
  working directory information and it has history entries;

``EVT_THUMBNAILS_CHAR``            A key was typed in the widget

:class:`ThumbnailCtrl` is distributed under the wxPython license.

Latest revision: Michael Eager @ 26 Sep 2020

# THUMBNAILCTRL Control wxPython IMPLEMENTATION
#
# Andrea Gavana And Peter Damoc, @ 12 Dec 2005
#
# Refactored and reorganized:  Michael Eager (eager@eagercon.com), 26 Sep 2020
#
#

:class:`ScrolledTextDialog` is a dialog widget which displays a scrolled
text box and OK/CANCEL buttons.

:param `thumboutline`: outline style for :class:`ThumbnailCtrl`, which may be:

:param `thumbfilter`: filter for image/video/audio files.  Ignored.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, thumboutline=THUMB_OUTLINE_IMAGE, thumbfilter=None, imagehandler=PILImageHandler)

Deletes the selected thumbnails and their associated files.
.. warning:: This method deletes the original files too.

:param `thumbs`:  List of indexes to thumbnails.

Returns list of file info objects for files of particular extensions.

:param `directory`: the folder containing the images to thumbnail;
:param `fileExtList`: a Python list of file extensions to consider.

Handles the ``wx.EVT_COMBOBOX`` for the folder combobox.

Recreates the folder combobox every time a new directory is explored.

:param `newdir`: the new folder to be explored.

Set the background color of the widget.

:param `colour`: the color to which the background is set.

Shows/Hide the top folder :class:`ComboBox`.

:param `show`: ``True`` to show the combobox, ``False`` otherwise.

Shows thumbnails for a particular folder.

:param `folder`: a directory containing the images to thumbnail;

['.jpeg', '.jpg', '.bmp', '.png', '.ico', '.tiff', '.ani', '.cur', '.gif', '.iff', '.icon', '.pcx', '.tif', '.xpm', '.xbm', '.mpeg', '.mpg', '.mov']

:class:`~wx.lib.agw.toasterbox.ToasterBox` is a cross-platform widget to make the creation of MSN style "toaster"
popups easier.

ToasterBox is a cross-platform widget to make the creation of MSN style "toaster"
popups easier. The syntax is really easy especially if you are familiar with the
syntax of wxPython.

It has 2 main styles:

- ``TB_SIMPLE``: using this style, you will be able to specify a background image for
  ToasterBox, text properties as text colour, font and label;

- ``TB_COMPLEX``: this style will allow you to put almost any control inside a
  ToasterBox. You can add a panel in which you can put all the controls you like.

Both styles support the setting of ToasterBox position (on screen coordinates),
size, the time after which the ToasterBox is destroyed (linger), and the scroll
speed of ToasterBox.

Usage
=====

    import wx
    import wx.lib.agw.toasterbox as TB

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

            toaster = TB.ToasterBox(self, tbstyle=TB.TB_COMPLEX)
            toaster.SetPopupPauseTime(3000)

            tbpanel = toaster.GetToasterBoxWindow()
            panel = wx.Panel(tbpanel, -1)

            button = wx.Button(panel, wx.ID_ANY, "Simple button")
            sizer.Add(button, 0, wx.EXPAND)

            toaster.AddPanel(panel)

            wx.CallLater(1000, toaster.Play)

ToasterBox has been tested on the following platforms:

- Windows (verified on Windows XP, 2000)
- Linux
- Mac

``TB_SIMPLE``                0x1 A simple `ToasterBox`, with background image and text customization can be created.
``TB_ONTIME``                0x1 `ToasterBox` will close after a specified amount of time.
``TB_COMPLEX``               0x2 ToasterBoxes with different degree of complexity can be created. You can add as  many controls as you want, provided that you call the :meth:`~ToasterBox.AddPanel` method and pass  to it a dummy frame and a :class:`Panel`. See the demo for details.
``TB_ONCLICK``               0x2 `ToasterBox` can be closed by clicking anywhere on the `ToasterBox` frame.
``TB_DEFAULT_STYLE``   0x2008002 Default window style for `ToasterBox`, with no caption nor close box.
``TB_CAPTION``        0x22009806 `ToasterBox` will have a caption, with the possibility to set a title for the `ToasterBox` frame, and a close box.

ToasterBox is distributed under the wxPython license.

# TOASTERBOX wxPython IMPLEMENTATION
# Ported And Enhanced From wxWidgets Contribution (Aj Bommarito) By:
#
# Andrea Gavana, @ 16 September 2005
#
#
# TODO/Caveats List
#
# 1. Any Idea?
#
#
#
#
#
#

:param `parent`: the window parent;
:param `tbstyle`: the :class:`ToasterBox` main style. Can be one of the following
 bits:

 `ToasterBox` Style      Value  Description
 ``TB_SIMPLE``              0x1 A simple :class:`ToasterBox`, with background image and text customization can be created
 ``TB_COMPLEX``             0x2 `ToasterBoxes` with different degree of complexity can be created. You can add as many controls as you want, provided that you call the :meth:`~ToasterBox.AddPanel` method and pass to it a dummy frame and a :class:`Panel`.

:param `windowstyle`: this parameter influences the visual appearance of
 :class:`ToasterBox`, and can be one of the following styles:

 ====================== ========== ================================
 Window Style           Hex Value  Description
 ``TB_DEFAULT_STYLE``   0x2008002  Default window style for :class:`ToasterBox`, with no caption nor close box.
 ``TB_CAPTION``         0x22009806 :class:`ToasterBox` will have a caption, with the possibility to set a title for the :class:`ToasterBox` frame, and a close box.

:param `closingstyle`: the closing style for :class:`ToasterBox`. Can be one of the

 Closing Styles       Hex Value   Description
 ``TB_ONTIME``                0x1 :class:`ToasterBox` will close after a specified amount of time.
 ``TB_ONCLICK``               0x2 :class:`ToasterBox` can be closed by clicking anywhere on the :class:`ToasterBox` frame.

:param `scrollType`: the scrolling direction for :class:`ToasterBox`. Can be one of the

 Scroll Styles        Hex Value   Description
 ``TB_SCR_TYPE_UD``           0x1 :class:`ToasterBox` will scroll from up to down
 ``TB_SCR_TYPE_DU``           0x2 :class:`ToasterBox` will scroll from down to up
 ``TB_SCR_TYPE_FADE``         0x4 :class:`ToasterBox` will fade in/out (without scrolling).

__init__(self, parent, tbstyle=TB_SIMPLE, windowstyle=TB_DEFAULT_STYLE, closingstyle=TB_ONTIME, scrollType=TB_SCR_TYPE_DU)

Adds a panel to the :class:`ToasterBox`.

:param `panel`: an instance of :class:`wx.Window`.

:note: Use this method only for a :class:`ToasterBox` created with the ``TB_COMPLEX`` style.

Centres the window on its parent (if any). If the :class:`ToasterBox` parent is ``None``,
it calls :meth:`~ToasterBox.CenterOnScreen`.

:param `direction`: specifies the direction for the centering. May be ``wx.HORIZONTAL``,
 ``wx.VERTICAL`` or ``wx.BOTH``.

:note: This methods provides for a way to center :class:`ToasterBox` over their parents instead of the
 entire screen. If there is no parent, then behaviour is the same as :meth:`~ToasterBox.CenterOnScreen`.

:see: :meth:`~ToasterBox.CenterOnScreen`.

Centres the :class:`ToasterBox` on screen.

:see: :meth:`~ToasterBox.CenterOnParent`.

Cleans the window list, erasing the stack of :class:`ToasterBox` objects. 

Returns whether :class:`ToasterBox` will steal the focus from the parent application. 

If a :class:`ToasterBox` already exists, move the new one above the existing one.

:param `tb`: another instance of :class:`ToasterBox`.

Handles the ``wx.EVT_TIMER`` event for :class:`ToasterBox`, moving the new window
on top of the last one created.

Sets the :class:`ToasterBox` background colour.

:param `colour`: a valid :class:`wx.Colour` object. If defaulted to ``None``, then
 the background colour will be white.

:note: Use this method only for a :class:`ToasterBox` created with the ``TB_SIMPLE`` style.

Sets the :class:`ToasterBox` background image.

:param `bitmap`: a valid :class:`wx.Bitmap` object or filename. If defaulted
 to ``None``, then no background bitmap is used.

Sets the time after which the :class:`ToasterBox` is destroyed (linger).

:param `pausetime`: the delay after which the control is destroyed, in seconds.

Sets the :class:`ToasterBox` position on screen.

:param `pos`: the widget position, an instance of :class:`wx.Point`.

Sets the :class:`ToasterBox` position on screen, at one of the screen corners.

:param `pos`: an integer specifying the screen corner, namely:

 ============= ========================================
 Corner Number Position
       0       Top left screen corner
       1       Top right screen corner
       2       Bottom left screen corner
       3       Bottom right screen corner

Sets the :class:`ToasterBox` scroll speed.

:param `speed`: it is the pause time (in milliseconds) for every step in the
 `ScrollUp` method.

Sets the :class:`ToasterBox` size.

:param `size`: the new control size, an instance of :class:`wx.Size`.

Sets the :class:`ToasterBox` text label.

:param `text`: the widget label.

Sets the :class:`ToasterBox` foreground colour.

 the background colour will be black.

Sets the :class:`ToasterBox` text font.

 a simple generic font will be generated.

Sets the :class:`ToasterBox` title if it was created with ``TB_CAPTION`` window style.

:param `title`: the :class:`ToasterBox` caption title.

If `focus` is ``True``, Instructs :class:`ToasterBox` to steal the focus from the
parent application, otherwise it returns the focus to the original owner.

:param `focus`: ``True`` to set the focus on :class:`ToasterBox`, ``False`` to
 return it to the original owner.

This class does all the job, by handling background images, text properties
and panel adding. Depending on the style you choose, :class:`ToasterBoxWindow` will
behave differently in order to handle widgets inside it.

:param `parent2`: the :class:`ToasterBox` calling this window;
:param `tbstyle`: the :class:`ToasterBoxWindow` main style. Can be one of the following
 bits:

 ``TB_COMPLEX``             0x2 `ToasterBoxes` with different degree of complexity can be created. You can add as many controls as you want, provided that you call the :meth:`~ToasterBoxWindow.AddPanel` method and pass to it a dummy frame and a :class:`Panel`.

 :class:`ToasterBoxWindow`, and can be one of the following styles:

:param `closingstyle`: the closing style for :class:`ToasterBoxWindow`. Can be one of the

:param `scrollType`: the scrolling direction for :class:`ToasterBoxWindow`. Can be one of the

__init__(self, parent, parent2, tbstyle, windowstyle, closingstyle, scrollType=TB_SCR_TYPE_DU)

Handles the ``wx.EVT_TIMER`` event for :class:`ToasterBoxWindow`.

Draws the text label for a :class:`ToasterBox` with ``TB_SIMPLE`` style set.

:param `dc`: an instance of :class:`wx.DC`. If defaulted to ``None``, a :class:`ClientDC`
 will be created on the fly.

Returns the :class:`ToasterBox` text.

Makes the :class:`ToasterBoxWindow` window transparent.

Handles the ``wx.EVT_CLOSE`` event for :class:`ToasterBoxWindow`.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`ToasterBoxWindow`.

Handles the ``wx.EVT_PAINT`` event for :class:`ToasterBoxWindow`.

:note: This event is handled and processed only if the style ``TB_SIMPLE`` is
 given to :class:`ToasterBox`.

Handles the ``wx.EVT_TIMER`` event for :class:`ToasterBoxWindow` scrolling up/down.

Scrolls the :class:`ToasterBox` down, which means gradually hiding it. 

Scrolls the :class:`ToasterBox` up, which means gradually showing it. 

:param `bitmap`: a valid :class:`wx.Bitmap` object. If defaulted to ``None``, then
 no background bitmap is used.

 :meth:`~ToasterBoxWindow.ScrollUp` method.

Sets up the position, size and scrolling step for :class:`ToasterBoxWindow`. 

If `focus` is ``True``, Instructs :class:`ToasterBoxWindow` to steal the focus from the

:param `focus`: ``True`` to set the focus on :class:`ToasterBoxWindow`, ``False`` to
 return it to the original owner;
:param `originalfocus`: an instance of :class:`wx.Window`, representing a pointer to
 the window which originally had the focus

UltimateListCtrl is a class that mimics the behaviour of :class:`ListCtrl`, with almost
the same base functionalities plus some more enhancements. This class does
not rely on the native control, as it is a full owner-drawn list control.

In addition to the standard :class:`ListCtrl` behaviour this class supports:

Appearance

* Multiple images for items/subitems;
* Images can be of any size and not limited to a single specific pair of `width`, `height`
  as it is the case of :class:`wx.ImageList`. Simply use :class:`PyImageList` instead of :class:`wx.ImageList`
  to add your images.
* Font, colour, background, custom renderers and formatting for items and subitems;
* Ability to add persistent data to an item using :meth:`~UltimateListCtrl.SetItemPyData` and :meth:`~UltimateListCtrl.GetItemPyData`:
  the data can be any Python object and not necessarily an integer as in :class:`ListCtrl`;
* CheckBox-type items and subitems;
* RadioButton-type items and subitems;
* Overflowing items/subitems, a la :class:`grid.Grid`, i.e. an item/subitem may overwrite neighboring
  items/subitems if its text would not normally fit in the space allotted to it;
* Hyperlink-type items and subitems: they look like an hyperlink, with the proper mouse
  cursor on hovering;
* Multiline text items and subitems;
* Variable row heights depending on the item/subitem kind/text/window;
* User defined item/subitem renderers: these renderer classes **must** implement the methods
  `DrawSubItem`, `GetLineHeight` and `GetSubItemWidth` (see the demo);
* Whatever non-toplevel widget can be attached next to an item/subitem;
* Column headers can have their own checkbox/radiobutton;
* Column footers are fully customizable in terms of icons, colour, font, alignment etc...;
* Column footers can have their own checkbox/radiobutton;
* Ability to hide/show columns;
  Vista selection style.

Usage
=====

    import sys

    import wx
    import wx.lib.agw.ultimatelistctrl as ULC

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

            list = ULC.UltimateListCtrl(self, wx.ID_ANY, agwStyle=ULC.ULC_REPORT | ULC.ULC_VRULES | ULC.ULC_HRULES | ULC.ULC_SINGLE_SEL | ULC.ULC_HAS_VARIABLE_ROW_HEIGHT)

            list.InsertColumn(0, "Column 1")
            list.InsertColumn(1, "Column 2")

            index = list.InsertStringItem(sys.maxsize, "Item 1")
            list.SetStringItem(index, 1, "Sub-item 1")

            index = list.InsertStringItem(sys.maxsize, "Item 2")
            list.SetStringItem(index, 1, "Sub-item 2")

            choice = wx.Choice(list, -1, choices=["one", "two"])
            index = list.InsertStringItem(sys.maxsize, "A widget")

            list.SetItemWindow(index, 1, choice, expand=True)

            sizer.Add(list, 1, wx.EXPAND)

# our normal wxApp-derived class, as usual

    if __name__ == "__main__":
        app = wx.App(0)

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

        app.MainLoop()

===============================  =========== ====================================================================================================
``ULC_VRULES``                           0x1 Draws light vertical rules between rows in report mode.
``ULC_HRULES``                           0x2 Draws light horizontal rules between rows in report mode.
``ULC_ICON``                             0x4 Large icon view, with optional labels.
``ULC_SMALL_ICON``                       0x8 Small icon view, with optional labels.
``ULC_LIST``                            0x10 Multicolumn list view, with optional small icons. Columns are computed automatically, i.e. you don't set columns as in ``ULC_REPORT``. In other words, the list wraps, unlike a :class:`ListBox`.
``ULC_REPORT``                          0x20 Single or multicolumn report view, with optional header.
``ULC_ALIGN_TOP``                       0x40 Icons align to the top. Win32 default, Win32 only.
``ULC_ALIGN_LEFT``                      0x80 Icons align to the left.
``ULC_AUTOARRANGE``                    0x100 Icons arrange themselves. Win32 only.
``ULC_VIRTUAL``                        0x200 The application provides items text on demand. May only be used with ``ULC_REPORT``.
``ULC_EDIT_LABELS``                    0x400 Labels are editable: the application will be notified when editing starts.
``ULC_NO_HEADER``                      0x800 No header in report mode.
``ULC_NO_SORT_HEADER``                0x1000 No Docs.
``ULC_SINGLE_SEL``                    0x2000 Single selection (default is multiple).
``ULC_SORT_ASCENDING``                0x4000 Sort in ascending order. (You must still supply a comparison callback in :meth:`ListCtrl.SortItems`.)
``ULC_SORT_DESCENDING``               0x8000 Sort in descending order. (You must still supply a comparison callback in :meth:`ListCtrl.SortItems`.)
``ULC_TILE``                         0x10000 Each item appears as a full-sized icon with a label of one or more lines beside it (partially implemented).
``ULC_NO_HIGHLIGHT``                 0x20000 No highlight when an item is selected.
``ULC_STICKY_HIGHLIGHT``             0x40000 Items are selected by simply hovering on them, with no need to click on them.
``ULC_STICKY_NOSELEVENT``            0x80000 Don't send a selection event when using ``ULC_STICKY_HIGHLIGHT`` style.
``ULC_SEND_LEFTCLICK``              0x100000 Send a left click event when an item is selected.
``ULC_HAS_VARIABLE_ROW_HEIGHT``     0x200000 The list has variable row heights.
``ULC_AUTO_CHECK_CHILD``            0x400000 When a column header has a checkbox associated, auto-check all the subitems in that column.
``ULC_AUTO_TOGGLE_CHILD``           0x800000 When a column header has a checkbox associated, toggle all the subitems in that column.
``ULC_AUTO_CHECK_PARENT``          0x1000000 Only meaningful foe checkbox-type items: when an item is checked/unchecked its column header item is checked/unchecked as well.
``ULC_SHOW_TOOLTIPS``              0x2000000 Show tooltips for ellipsized items/subitems (text too long to be shown in the available space) containing the full item/subitem text.
``ULC_HOT_TRACKING``               0x4000000 Enable hot tracking of items on mouse motion.
``ULC_BORDER_SELECT``              0x8000000 Changes border colour when an item is selected, instead of highlighting the item.
``ULC_TRACK_SELECT``              0x10000000 Enables hot-track selection in a list control. Hot track selection means that an item is automatically selected when the cursor remains over the item for a certain period of time. The delay is retrieved on Windows using the `win32api` call `win32gui.SystemParametersInfo(win32con.SPI_GETMOUSEHOVERTIME)`, and is defaulted to 400ms on other platforms. This style applies to all views of `UltimateListCtrl`.
``ULC_HEADER_IN_ALL_VIEWS``       0x20000000 Show column headers in all view modes.
``ULC_NO_FULL_ROW_SELECT``        0x40000000 When an item is selected, the only the item in the first column is highlighted.
``ULC_FOOTER``                    0x80000000 Show a footer too (only when header is present).
``ULC_USER_ROW_HEIGHT``          0x100000000 Allows to set a custom row height (one value for all the items, only in report mode).
``ULC_NO_ITEM_DRAG``             0x200000000 Disable item dragging

======================================== ====================================================================================================
``EVT_LIST_BEGIN_DRAG``                  Begin dragging with the left mouse button.
``EVT_LIST_BEGIN_RDRAG``                 Begin dragging with the right mouse button.
``EVT_LIST_BEGIN_LABEL_EDIT``            Begin editing a label. This can be prevented by calling `Veto()`.
``EVT_LIST_END_LABEL_EDIT``              Finish editing a label. This can be prevented by calling `Veto()`.
``EVT_LIST_DELETE_ITEM``                 An item was deleted.
``EVT_LIST_DELETE_ALL_ITEMS``            All items were deleted.
``EVT_LIST_KEY_DOWN``                    A key has been pressed.
``EVT_LIST_INSERT_ITEM``                 An item has been inserted.
``EVT_LIST_COL_CLICK``                   A column (`m_col`) has been left-clicked.
``EVT_LIST_COL_RIGHT_CLICK``             A column (`m_col`) has been right-clicked.
``EVT_LIST_COL_BEGIN_DRAG``              The user started resizing a column - can be vetoed.
``EVT_LIST_COL_END_DRAG``                The user finished resizing a column.
``EVT_LIST_COL_DRAGGING``                The divider between columns is being dragged.
``EVT_LIST_ITEM_SELECTED``               The item has been selected.
``EVT_LIST_ITEM_DESELECTED``             The item has been deselected.
``EVT_LIST_ITEM_RIGHT_CLICK``            The right mouse button has been clicked on an item.
``EVT_LIST_ITEM_MIDDLE_CLICK``           The middle mouse button has been clicked on an item.
``EVT_LIST_ITEM_ACTIVATED``              The item has been activated (``ENTER`` or double click).
``EVT_LIST_ITEM_FOCUSED``                The currently focused item has changed.
``EVT_LIST_CACHE_HINT``                  Prepare cache for a virtual list control.
``EVT_LIST_ITEM_CHECKING``               An item/subitem is being checked.
``EVT_LIST_ITEM_CHECKED``                An item/subitem has been checked.
``EVT_LIST_COL_CHECKING``                A column header is being checked.
``EVT_LIST_COL_CHECKED``                 A column header has being checked.
``EVT_LIST_FOOTER_CHECKING``             A column footer is being checked.
``EVT_LIST_FOOTER_CHECKED``              A column footer has being checked.
``EVT_LIST_ITEM_HYPERLINK``              An hyperlink item has been clicked.
``EVT_LIST_FOOTER_CLICK``                The user left-clicked on a column footer.
``EVT_LIST_FOOTER_RIGHT_CLICK``          The user right-clicked on a column footer.
``EVT_LIST_ITEM_LEFT_CLICK``             Send a left-click event after an item is selected.
``EVT_LIST_END_DRAG``                    Notify an end-drag operation.

UltimateListCtrl has been tested on the following platforms:

UltimateListCtrl is distributed under the wxPython license.

# ULTIMATELISTCTRL wxPython IMPLEMENTATION
# Inspired by and heavily based on the wxWidgets C++ generic version of wxListCtrl.
#
# Andrea Gavana, @ 08 May 2009
#
#
# TODO List
#
# 1)  Subitem selection;
# 2)  Watermark? (almost, does not work very well :-( );
# 3)  Groups? (Maybe, check ObjectListView);
# 4)  Scrolling items as headers and footers;
# 5)  Alpha channel for text/background of items;
# 6)  Custom renderers for headers/footers (done);
# 7)  Fading in and out on mouse motion (a la Windows Vista Aero);
# 8)  Sub-text for headers/footers (grey text below the header/footer text);
# 9)  Fixing the columns to the left or right side of the control layout;
# 10) Skins for header and scrollbars (implemented for headers/footers).
#
#
#
#
#
#

A simple class which holds information about :class:`UltimateListCtrl` columns. 

:param `w`: the initial width of the column;
:param `needsUpdate`: ``True`` if the column needs refreshing, ``False``

A list event holds information about events associated with :class:`UltimateListCtrl`
objects.

:param `commandTypeOrEvent`: the event type or another instance of
 :class:`PyCommandEvent`;
:param `winid`: the event identifier.

Returns the first item which the list control advises us to cache.

:note: This method is meaningful for ``EVT_LIST_CACHE_HINT`` event only.

Returns the last item (inclusive) which the list control advises us to cache.

Returns the column position: it is only used with ``COL`` events.

For the column dragging events, it is the column to the left of the divider
being dragged, for the column click events it may be -1 if the user clicked
in the list control header outside any column.

Returns the (new) item label for ``EVT_LIST_END_LABEL_EDIT`` event. 

Returns the position of the mouse pointer if the event is a drag event. 

Returns ``True`` if it the label editing has been cancelled by the user
(:meth:`~CommandListEvent.GetLabel` returns an empty string in this case but it doesn't allow
the application to distinguish between really cancelling the edit and
the admittedly rare case when the user wants to rename it to an empty
string).

:note: This method only makes sense for ``EVT_LIST_END_LABEL_EDIT`` messages.

Sets the item editing as cancelled/not cancelled.

:param `editCancelled`: ``True`` to set the item editing as cancelled, ``False``

A simple class which holds items geometries for :class:`UltimateListCtrl` not in
report mode.

Extends all our rectangles to be centered inside the one of given width.

:param `w`: the given width.

A :class:`PyImageList` contains a list of images. Images can have masks for
transparent drawing, and can be made from a variety of sources including
bitmaps and icons.

:class:`PyImageList` is used in conjunction with :class:`UltimateListCtrl`.

:note: The main improvements that :class:`PyImageList` introduces is the removal
 of the limitation of same-size images inside the image list. If you use
 the style ``IL_VARIABLE_SIZE`` then each image can have any size (in terms
 of width and height).

:param `width`: the width of the images in the image list, in pixels (unused
 if you specify the ``IL_VARIABLE_SIZE`` style;
:param `height`: the height of the images in the image list, in pixels (unused
:param `mask`: ``True`` if masks should be created for all images (unused in
 :class:`PyImageList`);
:param `initialCount`: the initial size of the list (unused in :class:`PyImageList`);

 ==================== ===== =================================
 Style Flag           Value Description
 ``IL_FIXED_SIZE``        0 All the images in :class:`PyImageList` have the same size (width, height)
 ``IL_VARIABLE_SIZE``     1 Each image can have any size (in terms of width and height)

__init__(self, width, height, mask=True, initialCount=1, style=IL_VARIABLE_SIZE)

Adds a new image or images using a bitmap.

:return: The new zero-based image index.

:note: If the bitmap is wider than the images in the list and you are not using
 the ``IL_VARIABLE_SIZE`` style, then the bitmap will automatically be split
 into smaller images, each matching the dimensions of the image list.

Adds a new image using an icon.

:param `icon`: a valid :class:`Icon` object.

:note: If the icon is wider than the images in the list and you are not using
 the ``IL_VARIABLE_SIZE`` style, then the icon will automatically be split

Adds a new image or images using a bitmap and a colour mask.

:param `colour`: an instance of :class:`wx.Colour`, a colour indicating which parts
 of the image are transparent.

Draws a specified image onto a device context.

:param `index`: the image index, starting from zero;
:param `x`: x position on the device context;
:param `y`: y position on the device context;
:param `flags`: how to draw the image. A bitlist of a selection of the following:

 ================================= =======================================
 Flag Paarameter                   Description
 ``wx.IMAGELIST_DRAW_NORMAL``      Draw the image normally
 ``wx.IMAGELIST_DRAW_TRANSPARENT`` Draw the image with transparency
 ``wx.IMAGELIST_DRAW_SELECTED``    Draw the image in selected state
 ``wx.IMAGELIST_DRAW_FOCUSED``     Draw the image in a focused state

:param `solidBackground`: currently unused.

Returns the bitmap corresponding to the given `index`, or :class:`NullBitmap`
if the index is invalid.

:param `index`: the bitmap index.

Returns the icon corresponding to the given `index`, or :class:`NullIcon`

:param `index`: the icon index.

Retrieves the size of an image in the list.

:param `index`: the zero-based index of the image.

:return: a tuple of `(width, height)` properties of the chosen bitmap.

Removes the image at the given position.

:param `index`: the zero-based index of the image to be removed.

Replaces the existing image with the new bitmap.

:param `index`: the index at which the image should be replaced;
:param `bitmap`: the new bitmap to add to the image list, an instance of
 :class:`wx.Bitmap`.

Replaces the existing image with the new icon.

:param `icon`: the new icon to add to the image list, an instance of
 :class:`Icon`.

SelectionStore is used to store the selected items in the virtual
controls, i.e. it is well suited for storing even when the control contains
a huge (practically infinite) number of items.

Of course, internally it still has to store the selected items somehow (as
an array currently) but the advantage is that it can handle the selection
of all items (common operation) efficiently and that it could be made even
smarter in the future (e.g. store the selections as an array of ranges +
individual items) without changing its API.

Returns ``True`` if the given item is selected.

:param `item`: the item to check for selection state.

Must be called when an item is deleted.

:param `item`: the item that is being deleted.

Selects the given item.

:param `item`: the item to select;
:param `select`: ``True`` to select the item, ``False`` otherwise.

:return: ``True`` if the items selection really changed.

Selects a range of items.

:param `itemFrom`: the first index of the selection range;
:param `itemTo`: the last index of the selection range;
:param `select`: ``True`` to select the items, ``False`` otherwise.

:return: ``True`` and fill the `itemsChanged` array with the indices of items
 which have changed state if "few" of them did, otherwise return ``False``
 (meaning that too many items changed state to bother counting them individually).

Sets the total number of items we handle.

:param `count`: the total number of items we handle.

:param `agwStyle`: the AGW-specific window style; can be almost any combination of the following
 bits:

 ===============================  =========== ====================================================================================================
 ``ULC_VRULES``                           0x1 Draws light vertical rules between rows in report mode.
 ``ULC_HRULES``                           0x2 Draws light horizontal rules between rows in report mode.
 ``ULC_ICON``                             0x4 Large icon view, with optional labels.
 ``ULC_SMALL_ICON``                       0x8 Small icon view, with optional labels.
 ``ULC_LIST``                            0x10 Multicolumn list view, with optional small icons. Columns are computed automatically, i.e. you don't set columns as in ``ULC_REPORT``. In other words, the list wraps, unlike a :class:`ListBox`.
 ``ULC_REPORT``                          0x20 Single or multicolumn report view, with optional header.
 ``ULC_ALIGN_TOP``                       0x40 Icons align to the top. Win32 default, Win32 only.
 ``ULC_ALIGN_LEFT``                      0x80 Icons align to the left.
 ``ULC_AUTOARRANGE``                    0x100 Icons arrange themselves. Win32 only.
 ``ULC_VIRTUAL``                        0x200 The application provides items text on demand. May only be used with ``ULC_REPORT``.
 ``ULC_EDIT_LABELS``                    0x400 Labels are editable: the application will be notified when editing starts.
 ``ULC_NO_HEADER``                      0x800 No header in report mode.
 ``ULC_NO_SORT_HEADER``                0x1000 No Docs.
 ``ULC_SINGLE_SEL``                    0x2000 Single selection (default is multiple).
 ``ULC_SORT_ASCENDING``                0x4000 Sort in ascending order. (You must still supply a comparison callback in :meth:`ListCtrl.SortItems`.)
 ``ULC_SORT_DESCENDING``               0x8000 Sort in descending order. (You must still supply a comparison callback in :meth:`ListCtrl.SortItems`.)
 ``ULC_TILE``                         0x10000 Each item appears as a full-sized icon with a label of one or more lines beside it (partially implemented).
 ``ULC_NO_HIGHLIGHT``                 0x20000 No highlight when an item is selected.
 ``ULC_STICKY_HIGHLIGHT``             0x40000 Items are selected by simply hovering on them, with no need to click on them.
 ``ULC_STICKY_NOSELEVENT``            0x80000 Don't send a selection event when using ``ULC_STICKY_HIGHLIGHT`` style.
 ``ULC_SEND_LEFTCLICK``              0x100000 Send a left click event when an item is selected.
 ``ULC_HAS_VARIABLE_ROW_HEIGHT``     0x200000 The list has variable row heights.
 ``ULC_AUTO_CHECK_CHILD``            0x400000 When a column header has a checkbox associated, auto-check all the subitems in that column.
 ``ULC_AUTO_TOGGLE_CHILD``           0x800000 When a column header has a checkbox associated, toggle all the subitems in that column.
 ``ULC_AUTO_CHECK_PARENT``          0x1000000 Only meaningful foe checkbox-type items: when an item is checked/unchecked its column header item is checked/unchecked as well.
 ``ULC_SHOW_TOOLTIPS``              0x2000000 Show tooltips for ellipsized items/subitems (text too long to be shown in the available space) containing the full item/subitem text.
 ``ULC_HOT_TRACKING``               0x4000000 Enable hot tracking of items on mouse motion.
 ``ULC_BORDER_SELECT``              0x8000000 Changes border colour when an item is selected, instead of highlighting the item.
 ``ULC_TRACK_SELECT``              0x10000000 Enables hot-track selection in a list control. Hot track selection means that an item is automatically selected when the cursor remains over the item for a certain period of time. The delay is retrieved on Windows using the `win32api` call `win32gui.SystemParametersInfo(win32con.SPI_GETMOUSEHOVERTIME)`, and is defaulted to 400ms on other platforms. This style applies to all views of `UltimateListCtrl`.
 ``ULC_HEADER_IN_ALL_VIEWS``       0x20000000 Show column headers in all view modes.
 ``ULC_NO_FULL_ROW_SELECT``        0x40000000 When an item is selected, the only the item in the first column is highlighted.
 ``ULC_FOOTER``                    0x80000000 Show a footer too (only when header is present).
 ``ULC_USER_ROW_HEIGHT``          0x100000000 Allows to set a custom row height (one value for all the items, only in report mode).

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, validator=wx.DefaultValidator, name="UltimateListCtrl")

Append an item to the :class:`UltimateListCtrl`.

:param `entry`: should be a sequence with an item for each column.

Arranges the items in icon or small icon view.

:param `flag`: one of the following bits:

 ========================== ========= ===============================
 Alignment Flag             Hex Value Description
 ``ULC_ALIGN_DEFAULT``            0x0 Default alignment
 ``ULC_ALIGN_SNAP_TO_GRID``       0x3 Snap to grid

:note: This method is currently unimplemented and does nothing.

Assigns the image list associated with the control.

:param `imageList`: an instance of :class:`wx.ImageList` or an instance of :class:`PyImageList`;
:param `which`: one of ``wx.IMAGE_LIST_NORMAL``, ``wx.IMAGE_LIST_SMALL``,
 ``wx.IMAGE_LIST_STATE`` (the last is unimplemented).

:note: Using :class:`PyImageList` enables you to have images of different size inside the
 image list. In your derived class, instead of doing this::

     imageList = wx.ImageList(16, 16)
     imageList.Add(someBitmap)
     self.SetImageList(imageList, wx.IMAGE_LIST_SMALL)

 You should do this::

     imageList = PyImageList(16, 16)

Clears all the images in the specified column.

:param `col`: the column index;

Converts to screen coordinates from coordinates relative to this window.

:param `pointOrTuple`: an instance of :class:`wx.Point` or a tuple representing the
 `x`, `y` coordinates for this point.

:return: the coordinates relative to the screen.

:param `x`: an integer specifying the `x` client coordinate;
:param `y`: an integer specifying the `y` client coordinate.

Creates or destroys the footer window depending on the window style flags. 

Creates or destroys the header window depending on the window style flags. 

Deletes all items in the :class:`UltimateListCtrl`.

:note: This function does not send the ``EVT_LIST_DELETE_ITEM`` event because
 deleting many items from the control would be too slow then (unlike :meth:`~UltimateListCtrl.DeleteItem`).

Deletes the specified column.

:param `col`: the index of the column to delete.

Deletes the specified item.

:param `item`: the index of the item to delete.

:note: This function sends the ``EVT_LIST_DELETE_ITEM`` event for the item
 being deleted.

:param `itemOrId`: an instance of :class:`UltimateListItem` or the item index;
:param `col`: the column index to which the input item belongs to.

Layouts the header, main and footer windows. This is an auxiliary method to avoid code
duplication.

:param `item`: the index of the item to edit.

:param `col`: the column index to which the input item belongs to;
:param `enable`: ``True`` to enable the item, ``False`` otherwise.

:param `enable`: ``True`` to enable gradient-style selections, ``False``

 enabled.

:param `enable`: ``True`` to enable Vista-style selections, ``False`` to

 enabled.

Ensures this item is visible.

:param `index`: the index of the item to scroll into view.

Find an item whose label matches this string.

:param `start`: the starting point of the input `string` or the beginning
 if `start` is -1;
:param `string`: the string to look for matches;
:param `partial`: if ``True`` then this method will look for items which
 begin with `string`.

:note: The string comparison is case insensitive.

Find an item nearest this position.

Find an item whose data matches this data.

:param `start`: the starting point of the input `data` or the beginning
:param `data`: the data to look for matches.

Focus and show the given item.

:param `idx`: the index of the item to be focused.

Returns the :class:`UltimateListCtrl` AGW-specific style flag.

:see: :meth:`~UltimateListCtrl.SetAGWWindowStyleFlag` for a list of possible style flags.

Returns the background colour of the window.

Returns the :class:`UltimateListCtrl` background image (if any).

Returns the number of checked items in the given column.

:param 'col': an integer specifying the column index.
:returns: the number of checked items.

Returns the default font and colours which are used by the control. This is
useful if you want to use the same font or colour in your own control as in
a standard control -- which is a much better idea than hard coding specific
colours or fonts which might look completely out of place on the users system,
especially if it uses themes.

This static method is "overridden'' in many derived classes and so calling,
for example, :meth:`Button.GetClassDefaultAttributes` () will typically return the
values appropriate for a button which will be normally different from those
returned by, say, :meth:`ListCtrl.GetClassDefaultAttributes` ().

:note: The :class:`VisualAttributes` structure has at least the fields `font`,
 `colFg` and `colBg`. All of them may be invalid if it was not possible to
 determine the default control appearance or, especially for the background
 colour, if the field doesn't make sense as is the case for `colBg` for the
 controls with themed background.

Returns information about this column.

:param `col`: an integer specifying the column index.

Returns the total number of columns in the :class:`UltimateListCtrl`. 

Returns the column width for the input column.

Returns the number of items that can fit vertically in the visible area
of the :class:`UltimateListCtrl` (list or report view) or the total number of
items in the list control (icon or small icon view).

Returns the associated drop target, which may be ``None``.

Returns a pointer to the edit :class:`UltimateListTextCtrl` if the item is being edited or

Returns the first gradient colour for gradient-style selections. 

Returns the :class:`UltimateListHeaderWindow` height, in pixels. 

Returns the foreground colour of the window.

:return: 0 for horizontal gradient-style selections, 1 for vertical

Returns the colour used to render a non-visited hypertext item. 

Returns the image list associated with the control.

:note:

 As :class:`UltimateListCtrl` allows you to use a standard :class:`wx.ImageList` or
 :class:`PyImageList`, the returned object depends on which kind of image list you
 chose.

Returns the information about the input item.

:param `itemOrId`: an instance of :class:`UltimateListItem` or an integer specifying
 the item index;
:param `col`: the column to which the item belongs to.

:param `item`: the index of the item.

Returns the custom renderer used to draw the input item (if any).

Gets the application-defined data associated with this item.

:param `item`: an integer specifying the item index.

Returns the item kind.

:see: :meth:`~UltimateListCtrl.SetItemKind` for a list of valid item kinds.

Returns if the item is in the overflow state.

An item/subitem may overwrite neighboring items/subitems if its text would
not normally fit in the space allotted to it.

Returns the position of the item, in icon or small icon view.

:param `item`: the row in which the item lives.

Returns the data for the item, which can be any Python object.

:note: Please note that Python data is associated with the item and not
 with subitems.

Returns the rectangle representing the item's size and position, in physical
coordinates.

:param `item`: the row in which the item lives;
:param `code`: one of ``ULC_RECT_BOUNDS``, ``ULC_RECT_ICON``, ``ULC_RECT_LABEL``.

Returns the spacing between item texts and icons, in pixels.

:param `isSmall`: ``True`` if using a ``wx.IMAGE_LIST_SMALL`` image list,
 ``False`` if using a ``wx.IMAGE_LIST_NORMAL`` image list.

Returns the item state flags for the input item.

:param `item`: the index of the item;
:param `stateMask`: the bitmask for the state flag.

:see: :meth:`~UltimateListCtrl.SetItemState` for a list of valid state flags.

:param `item`: an instance of :class:`UltimateListItem` or an integer specifying
 the item index.

Returns the item text colour.

Searches for an item with the given `geometry` or `state`, starting from `item`
but excluding the `item` itself.

:param `item`: the item at which starting the search. If set to -1, the first
 item that matches the specified flags will be returned.
:param `geometry`: can be one of:

 =================== ========= =================================
 Geometry Flag       Hex Value Description
 ``ULC_NEXT_ABOVE``        0x0 Searches for an item above the specified item
 ``ULC_NEXT_ALL``          0x1 Searches for subsequent item by index
 ``ULC_NEXT_BELOW``        0x2 Searches for an item below the specified item
 ``ULC_NEXT_LEFT``         0x3 Searches for an item to the left of the specified item
 ``ULC_NEXT_RIGHT``        0x4 Searches for an item to the right of the specified item

:param `state`: any combination of the following bits:

 ============================ ========= ==============================
 State Bits                   Hex Value Description
 ``ULC_STATE_DONTCARE``             0x0 Don't care what the state is
 ``ULC_STATE_DROPHILITED``          0x1 The item is highlighted to receive a drop event
 ``ULC_STATE_FOCUSED``              0x2 The item has the focus
 ``ULC_STATE_SELECTED``             0x4 The item is selected
 ``ULC_STATE_CUT``                  0x8 The item is in the cut state
 ``ULC_STATE_DISABLED``            0x10 The item is disabled
 ``ULC_STATE_FILTERED``            0x20 The item has been filtered
 ``ULC_STATE_INUSE``               0x40 The item is in use
 ``ULC_STATE_PICKED``              0x80 The item has been picked
 ``ULC_STATE_SOURCE``             0x100 The item is a drag and drop source

:return: The first item with given `state` following `item` or -1 if no such item found.

:note: This function may be used to find all selected items in the
 control like this::

     item = -1

     while 1:
         item = listctrl.GetNextItem(item, ULC_NEXT_ALL, ULC_STATE_SELECTED)

         if item == -1:
             break

         # This item is selected - do whatever is needed with it

         wx.LogMessage("Item %ld is selected."%item)

GetNextItem(self, item, geometry=ULC_NEXT_ALL, state=ULC_STATE_DONTCARE)

Returns subsequent selected items, or -1 when no more are selected.

Returns the scrollbar position.

:note: This method is forwarded to :class:`UltimateListMainWindow`.

:param `orientation`: May be wx.HORIZONTAL or wx.VERTICAL.

Returns the scrollbar range in pixels.

Returns the scrollbar size in pixels.

Returns the second gradient colour for gradient-style selections. 

Returns the number of selected items in :class:`UltimateListCtrl`. 

Returns the rectangle representing the size and position, in physical coordinates,
of the given subitem, i.e. the part of the row `item` in the column `subItem`.

:param `subItem`: the column in which the item lives. If set equal to the special
 value ``ULC_GETSUBITEMRECT_WHOLEITEM`` the return value is the same as for
 :meth:`~UltimateListCtrl.GetItemRect`;

:note: This method is only meaningful when the :class:`UltimateListCtrl` is in the
 report mode.

Gets the index of the topmost visible item when in list or report view. 

Returns the custom value for the :class:`UltimateListCtrl` item height, if previously set with
:meth:`~UltimateListCtrl.SetUserLineHeight`.

:note: This method can be used only with ``ULC_REPORT`` and ``ULC_USER_ROW_HEIGHT`` styles set.

Returns the rectangle taken by all items in the control. In other words,
if the controls client size were equal to the size of this rectangle, no
scrollbars would be needed and no free space would be left.

:note: This function only works in the icon and small icon views, not in
 list or report views.

Returns the :class:`UltimateListCtrl` watermark image (if any), displayed in the
bottom right part of the window.

.. todo:: Better support for this is needed.

Returns ``True`` if the window has the given flag bit set.

:param `flag`: the window style to check.

:see: :meth:`~UltimateListCtrl.SetAGWWindowStyleFlag` for a list of valid window styles.

Returns ``True`` if :class:`UltimateListCtrl` has a footer window. 

Returns ``True`` if :class:`UltimateListCtrl` has a header window. 

HitTest method for a :class:`UltimateListCtrl`.

:param `pointOrTuple`: an instance of :class:`wx.Point` or a tuple representing
 the mouse `x`, `y` position.

:see: :meth:`UltimateListMainWindow.HitTestLine() <UltimateListMainWindow.HitTestLine>` for a list of return flags.

Inserts a column into :class:`UltimateListCtrl`.

:param `col`: the column index at which we wish to insert a column;
:param `heading`: the header text;
:param `format`: the column alignment flag. This can be one of the following
 bits:

 Alignment Bits               Hex Value Description
 ``ULC_FORMAT_LEFT``                0x0 The item is left-aligned
 ``ULC_FORMAT_RIGHT``               0x1 The item is right-aligned
 ``ULC_FORMAT_CENTRE``              0x2 The item is centre-aligned
 ``ULC_FORMAT_CENTER``              0x2 The item is center-aligned

:param `width`: can be a width in pixels or ``wx.LIST_AUTOSIZE`` (-1) or
 ``wx.LIST_AUTOSIZE_USEHEADER`` (-2) or ``LIST_AUTOSIZE_FILL`` (-3).
 ``wx.LIST_AUTOSIZE`` will resize the column to the length of its longest
 item. ``wx.LIST_AUTOSIZE_USEHEADER`` will resize the column to the
 length of the header (Win32) or 80 pixels (other platforms).
 ``LIST_AUTOSIZE_FILL`` will resize the column fill the remaining width
 of the window.

:return: the index at which the column has been inserted.

InsertColumn(self, col, heading, format=ULC_FORMAT_LEFT, width=-1)

:param `item`: an instance of :class:`UltimateListItem`.

Inserts an image item at the given location.

:param `index`: the index at which we wish to insert the item;
:param `imageIds`: a Python list containing the image indexes for the
 images associated to this item;
:param `it_kind`: the item kind.

:see: :meth:`~UltimateListCtrl.SetStringItem` for a list of valid item kinds.

Inserts an image+string item at the given location.

:param `label`: the item text;

Inserts an item into :class:`UltimateListCtrl`.

:param `info`: an instance of :class:`UltimateListItem`.

Inserts a string item at the given location.

Returns ``True`` if the input column is shown, ``False`` if it is hidden.

Returns whether an item is enabled or not.

Returns ``True`` if the item is selected.

:param `idx`: the index of the item to check for selection.

Returns ``True`` if the :class:`UltimateListCtrl` has the ``ULC_VIRTUAL`` style set. 

This function may be overloaded in the derived class for a control with
``ULC_VIRTUAL`` style. It should return the attribute for the specified
item or ``None`` to use the default appearance parameters.

:note:

 :class:`UltimateListCtrl` will not delete the pointer or keep a reference of it.
 You can return the same :class:`UltimateListItemAttr` pointer for every
 :meth:`~UltimateListCtrl.OnGetItemAttr` call.

:note: The base class version always returns ``None``.

``ULC_VIRTUAL`` style. It should return whether a checkbox-like item or
a radiobutton-like item is checked or unchecked.

:note: The base class version always returns an empty list.

This function **must** be overloaded in the derived class for a control with
``ULC_VIRTUAL`` and ``ULC_REPORT`` style. It should return whether a
checkbox-like item or a radiobutton-like item in the column header is checked
or unchecked.

:note: The base class version always returns an empty Python list.

``ULC_VIRTUAL`` and ``ULC_REPORT`` style. It should return a Python list of
indexes representing the images associated to the input item or an empty list
for no images.

``ULC_VIRTUAL`` style. It should return the item kind for the input item in
the header window.

:param `item`: an integer specifying the item index;
:param `column`: the column index.

:note: The base class version always returns 0 (a standard item).

``ULC_VIRTUAL`` style having an image list (if the control doesn't have an
image list, it is not necessary to overload it). It should return a Python
list of indexes representing the images associated to the input item or an
empty list for no images.

:note: In a control with ``ULC_REPORT`` style, :meth:`~UltimateListCtrl.OnGetItemImage` only gets called
 for the first column of each line.

``ULC_VIRTUAL`` style. It should return the item kind for the input item.

``ULC_VIRTUAL`` style. It should return the string containing the text of
the given column for the specified item.

:param `col`: the column index to which the item belongs to.

``ULC_VIRTUAL`` style. It should return a :class:`wx.Colour` object or ``None`` for
the default color.

the tooltip for the specified item.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`UltimateListCtrl`.

Handles the ``wx.EVT_SIZE`` event for :class:`UltimateListCtrl`.

Pops up the given `menu` at the specified coordinates, relative to this window,
and returns control when the user has dismissed the menu. If a menu item is
selected, the corresponding menu event is generated and will be processed as
usual. If the coordinates are not specified, the current mouse cursor position
is used.

:param `menu`: an instance of :class:`wx.Menu` to pop up;
:param `pos`: the position where the menu will appear.

:param `eraseBackground`: If ``True``, the background will be erased;

 use :meth:`~UltimateListCtrl.Update` instead.

Redraws the given item.

:note: This is only useful for the virtual list controls as without calling
 this function the displayed value of the item doesn't change even when the
 underlying data does change.

Redraws the items between `itemFrom` and `itemTo`.
The starting item must be less than or equal to the ending one.

Just as :meth:`~UltimateListCtrl.RefreshItem` this is only useful for virtual list controls

:param `itemFrom`: the first index of the refresh range;
:param `itemTo`: the last index of the refresh range.

Converts from screen to client window coordinates.

:return: the coordinates relative to this window.

:param `x`: an integer specifying the `x` screen coordinate;
:param `y`: an integer specifying the `y` screen coordinate.

Scrolls the :class:`UltimateListCtrl`.

:param `dx`: if in icon, small icon or report view mode, specifies the number
 of pixels to scroll. If in list view mode, `dx` specifies the number of
 columns to scroll.
:param `dy`: always specifies the number of pixels to scroll vertically.

:param `idx`: the index of the item to select;
:param `on`: ``True`` to select the item, ``False`` to deselect it.

Sets the :class:`UltimateListCtrl` AGW-specific style flag.

:param `style`: the AGW-specific window style; can be almost any combination of the following
 bits:

Changes the background colour of :class:`UltimateListCtrl`.

Sets the :class:`UltimateListCtrl` background image.

Sets information about this column.

:param `col`: an integer specifying the column index;

Associate a custom renderer to this column's header.

:param `col`: the column index.
:param `renderer`: a class able to correctly render the input item.

:note: the renderer class **must** implement the methods `DrawHeaderButton`
 and `GetForegroundColor`.

Sets one or more images to the specified column.

:param `image`: a Python list containing the image indexes for the
 images associated to this column item.

Sets the specified column as shown or hidden.

:param `shown`: ``True`` to show the column, ``False`` to hide it.

Sets the tooltip for the column header

:param `tip`: the tooltip text

Sets the column width.

:note: In small or normal icon view, col must be -1, and the column width
 is set for all columns.

Sets the window's cursor.

:param `cursor`: specifies the cursor that the window should normally display.
 The `cursor` may be :class:`NullCursor` in which case the window cursor will be
 reset back to default.

:note: The window cursor also sets it for the children of the window implicitly.

Sets the items disabled colour.

Associates a drop target with this window.
If the window already has a drop target, it is deleted.

:param `dropTarget`: an instance of :class:`DropTarget`.

Sets the :class:`UltimateListCtrl` font.

Associate a custom renderer with the footer - all columns will use it.

Sets the :class:`UltimateListHeaderWindow` height, in pixels. This overrides the default
footer window size derived from :class:`RendererNative`. If `height` is ``None``, the
default behaviour is restored.

:param `height`: the footer window height, in pixels (if it is ``None``, the default
 height obtained using :class:`RendererNative` is used).

Changes the foreground colour of :class:`UltimateListCtrl`.

:param `vertical`: 0 for horizontal gradient-style selections, 1 for vertical

Associate a custom renderer with the header - all columns will use it.

header window size derived from :class:`RendererNative`. If `height` is ``None``, the

:param `height`: the header window height, in pixels (if it is ``None``, the default

Sets the image list associated with the control.

Sets the information about the input item.

:param `col`: a valid :class:`wx.Colour` object.

Sets a Python list of image indexes associated with the item in the input
column.

:param `column`: the column to which the item belongs to;
:param `image`: a Python list of indexes into the image list associated
 with the :class:`UltimateListCtrl`.

Associate a custom renderer to this item.

:note: the renderer class **must** implement the methods `DrawSubItem`,
 `GetLineHeight` and `GetSubItemWidth`.

Sets the application-defined data associated with this item.

:param `data`: the data to be associated with the input item.

:note: This function cannot be used to associate pointers with
 the control items, use :meth:`~UltimateListCtrl.SetItemPyData` instead.

:param `f`: a valid :class:`wx.Font` object.

:param `hyper`: ``True`` to have an item with hypertext behaviour, ``False`` otherwise.

Sets a Python list of image indexes associated with the item.

 with the :class:`UltimateListCtrl`. In report view, this only sets the images
 for the first column;
:param `selImage`: not used at present.

Sets the item kind.

:param `kind`: may be one of the following integers:

 Item Kind       Description

Sets the item in the overflow/non overflow state.

:param `over`: ``True`` to set the item in a overflow state, ``False`` otherwise.

Sets the position of the item, in icon or small icon view.

:param `pos`: the item position.

Sets the data for the item, which can be any Python object.

:param `pyData`: any Python object.

Sets the spacing between item texts and icons.

:param `spacing`: the spacing between item texts and icons, in pixels;

Sets the item state flags for the input item.

:param `item`: the index of the item; if defaulted to -1, the state flag
 will be set for all the items;

:param `text`: the new item text.

Sets the item text colour.

:param `visited`: ``True`` to mark an hypertext item as visited, ``False`` otherwise.

:param `expand`: ``True`` to expand the column where the item/subitem lives,
 so that the window will be fully visible.

:param `enable`: ``True`` to enable the associated window, ``False`` to disable it.

Sets the scrollbar position.

:param `orientation`: determines the scrollbar whose position is to be set.
 May be ``wx.HORIZONTAL`` or ``wx.VERTICAL``;
:param `pos`: the scrollbar position in scroll units;
:param `refresh`: ``True`` to redraw the scrollbar, ``False`` otherwise.

 the colour generated is a slightly darker version of the :class:`UltimateListCtrl`

Adds or removes a single window style.

:param `add`: ``True`` to add the window style, ``False`` to remove it.

:note: The style ``ULC_VIRTUAL`` can not be set/unset after construction.

Sets a string or image at the given location.

:param `index`: the item index;
:param `col`: the column to which the item belongs to;
:param `it_kind`: the item kind. May be one of the following integers:

Sets the :class:`UltimateListCtrl` foreground colour.

Sets a custom value for the :class:`UltimateListCtrl` item height.

:param `height`: the custom height for all the items, in pixels.

Sets the :class:`UltimateListCtrl` watermark image to be displayed in the bottom
right part of the window.

:param `watermark`: if not ``None``, an instance of :class:`wx.Bitmap`.

Call this function to sort the items in the :class:`UltimateListCtrl`. Sorting is done
using the specified function `func`. This function must have the
following prototype::

    def OnCompareItems(self, line1, line2):

        DoSomething(line1, line2)
        # function code

It is called each time when the two items must be compared and should return 0
if the items are equal, negative value if the first item is less than the second
one and positive value if the first one is greater than the second one.

:param `func`: the method to use to sort the items. The default is to use the
 :meth:`UltimateListMainWindow.OnCompareItems() <UltimateListMainWindow.OnCompareItems>` method.

:note: This function doesn't invalidate any area of the window so nothing
 happens if nothing has been invalidated (i.e. marked as requiring a redraw).
 Use :meth:`~UltimateListCtrl.Refresh` first if you want to immediately redraw the window unconditionally.

This is the opposite of :meth:`~UltimateListEvent.Veto`: it explicitly allows the event to be processed.

Returns ``True`` if the change is allowed (:meth:`~UltimateListEvent.Veto` hasn't been called) or

A simple class which holds information about :class:`UltimateListItem` visual
attributes for the header/footer items (client rectangles, positions, etc...).

:param `item`: another instance of :class:`UltimateListHeaderData`.

Checks/unchecks a header item.

:param `checked`: ``True`` to check an item, ``False`` to uncheck it.

:note: This method is meaningful only for check and radio header items.

Checks/unchecks a footer item.

:note: This method is meaningful only for check and radio footer items.

Returns the custom renderer associated with this item (if any). 

Returns a Python list with the zero-based indexes of the images associated
with the footer item into the image list.

Returns the footer item kind.

:see: :meth:`~UltimateListHeaderData.SetKind` for a list of valid item kinds.

with the header item into the image list.

Returns information about the item.

:param `item`: an instance of :class:`UltimateListHeaderData`.

Returns the header item kind.

Returns a bit field representing the state of the item.

:see: :meth:`~UltimateListHeaderData.SetState` for a list of valid item states.

Returns ``True`` if the footer item has at least one image associated
with it.

Returns ``True`` if the header item has at least one image associated
with it.

Returns ``True`` if the input position is inside the item client rectangle.

:param `x`: the `x` mouse position;
:param `y`: the `y` mouse position.

:param `renderer`: a class able to correctly render the item.

Sets a new font for the header item.

Sets a new font for the footer item.

Sets the footer item format.

:param `format`: the footer item format.

Sets the footer item kind.

:param `kind`: the footer item kind.

Sets the header item format.

:param `format`: the header item format.

Sets the header/footer item height, in pixels.

:param `h`: an integer value representing the header/footer height.

Sets information about the header/footer item.

:param `info`: an instance of :class:`UltimateListHeaderData`.

Sets the header item kind.

Sets the header/footer item position.

:param `x`: the item `x` position;
:param `y`: the item `y` position.

Sets the item state flags.

Sets the header/footer item text.

:param `text`: the new header/footer text.

Sets the header/footer item tooltip.

:param `tip`: the new header/footer tooltip.

Sets the header/footer item width, in pixels.

:param `w`: an integer value representing the header/footer width.

This class holds the header window for :class:`UltimateListCtrl`.

:param `owner`: an instance of :class:`UltimateListCtrl`;
:param `isFooter`: ``True`` if the :class:`UltimateListHeaderWindow` is in a footer
 position, ``False`` otherwise.

__init__(self, win, id, owner, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name="UltimateListCtrlcolumntitles", isFooter=False)

Draws the item text, correctly formatted.

:param `text`: the item text;
:param `rect`: the item client rectangle.

Returns the header window owner, an instance of :class:`UltimateListCtrl`. 

Handles the case in which a column contains a checkbox-like item.

:param `column`: the column index;
:param `pos`: the mouse position.

HitTest method for column headers.

:return: The column index if any column client rectangle contains the mouse
 position, ``wx.NOT_FOUND`` otherwise.

Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`UltimateListHeaderWindow`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`UltimateListHeaderWindow`.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`UltimateListHeaderWindow`.

Handles the ``wx.EVT_PAINT`` event for :class:`UltimateListHeaderWindow`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`UltimateListHeaderWindow`.

Sends a :class:`UltimateListEvent` for the parent window.

  and `GetForegroundColor`.

This class stores information about a :class:`UltimateListCtrl` item or column. 

:param `item`: if not ``None``, another instance of :class:`UltimateListItem`.

Returns the associated attributes if they exist, or create a new :class:`UltimateListItemAttr`
structure and associate it with this item.

Checks/unchecks an item.

:note: This method is meaningful only for check and radio items.

Enables or disables the item.

:param `enable`: ``True`` to enable the item, ``False`` to disable it.

Returns the alignment for the item.

:see: :meth:`~UltimateListItem.SetAlign` for a list of valid alignment bits.

Returns the associated :class:`UltimateListItemAttr` attributes. 

Returns the zero-based column.

:note: This method is meaningful only in report mode.

Returns client data associated with the control.

:note: Please note that client data is associated with the item and not

Returns the alignment for the footer item.

:see: :meth:`~UltimateListItem.SetAlign` for a list of valid alignment flags.

Returns the zero-based index of the image associated with the footer item into
the image list.

:see: :meth:`~UltimateListItem.SetKind` for a list of valid items kind.

with the item into the image list.

:see: :meth:`~UltimateListItem.SetKind` for a valid list of item's kind.

Returns a bit mask indicating which fields of the structure are valid.

:see: :meth:`~UltimateListItem.SetMask` for a list of valid bit masks.

Returns data for the item, which can be any Python object.

:see: :meth:`~UltimateListItem.SetState` for a list of valid item states.

Returns the column width.

:note: This method is meaningful only for column headers in report mode.

Returns ``True`` if the item has attributes associated with it. 

Returns ``True`` if the item is shown, or ``False`` if it is hidden. 

Handles the ``wx.EVT_SET_FOCUS`` event for the window associated to an item.

Sets the alignment for the item.

:param `align`: one of the following bits:

Sets the background colour for the item.

:param `colBack`: a valid :class:`wx.Colour` object.

Sets the zero-based column.

:param `col`: the zero-based column.

:note: This method is neaningful only in report mode.

Sets client data for the item.

:param `data`: the client data associated to the item.

Sets the font for the item.

Sets the alignment for the footer item.

Sets the background colour for the footer item.

Sets the font for the footer item.

Sets the zero-based index of the image associated with the footer item into the
image list.

:param `image`: the zero-based index of the image associated with the footer item
 into the image list.

Sets the text label for the footer item.

:param `text`: the text label for the footer item.

Sets the text colour for the footer item.

:param `colText`: a valid :class:`wx.Colour` object.

:param `hyper`: ``True`` to set hypertext behaviour, ``False`` otherwise.

Sets the zero-based item position.

:param `id`: the zero-based item position.

Sets the zero-based indexes of the images associated with the item into the

:param `image`: a Python list with the zero-based indexes of the images
 associated with the item into the image list.

Sets the mask of valid fields.

:param `mask`: any combination of the following bits:

 Mask Bits                    Hex Value Description
 ``ULC_MASK_STATE``                 0x1 :meth:`~UltimateListItem.GetState` is valid
 ``ULC_MASK_TEXT``                  0x2 :meth:`~UltimateListItem.GetText` is valid
 ``ULC_MASK_IMAGE``                 0x4 :meth:`~UltimateListItem.GetImage` is valid
 ``ULC_MASK_DATA``                  0x8 :meth:`~UltimateListItem.GetData` is valid
 ``ULC_MASK_WIDTH``                0x20 :meth:`~UltimateListItem.GetWidth` is valid
 ``ULC_MASK_FORMAT``               0x40 :meth:`~UltimateListItem.GetFormat` is valid
 ``ULC_MASK_FONTCOLOUR``           0x80 :meth:`~UltimateListItem.GetTextColour` is valid
 ``ULC_MASK_FONT``                0x100 :meth:`~UltimateListItem.GetFont` is valid
 ``ULC_MASK_BACKCOLOUR``          0x200 :meth:`~UltimateListItem.GetBackgroundColour` is valid
 ``ULC_MASK_KIND``                0x400 :meth:`~UltimateListItem.GetKind` is valid
 ``ULC_MASK_ENABLE``              0x800 :meth:`~UltimateListItem.IsEnabled` is valid
 ``ULC_MASK_CHECK``              0x1000 :meth:`~UltimateListItem.IsChecked` is valid
 ``ULC_MASK_HYPERTEXT``          0x2000 :meth:`~UltimateListItem.IsHyperText` is valid
 ``ULC_MASK_WINDOW``             0x4000 :meth:`~UltimateListItem.GetWindow` is valid
 ``ULC_MASK_PYDATA``             0x8000 :meth:`~UltimateListItem.GetPyData` is valid
 ``ULC_MASK_SHOWN``             0x10000 :meth:`~UltimateListItem.IsShown` is valid
 ``ULC_MASK_RENDERER``          0x20000 :meth:`~UltimateListItem.GetCustomRenderer` is valid
 ``ULC_MASK_OVERFLOW``          0x40000 :meth:`~UltimateListItem.GetOverFlow` is valid
 ``ULC_MASK_FOOTER_TEXT``       0x80000 :meth:`~UltimateListItem.GetFooterText` is valid
 ``ULC_MASK_FOOTER_IMAGE``     0x100000 :meth:`~UltimateListItem.GetFooterImage` is valid
 ``ULC_MASK_FOOTER_FORMAT``    0x200000 :meth:`~UltimateListItem.GetFooterFormat` is valid
 ``ULC_MASK_FOOTER_FONT``      0x400000 :meth:`~UltimateListItem.GetFooterFont` is valid
 ``ULC_MASK_FOOTER_CHECK``     0x800000 :meth:`~UltimateListItem.IsFooterChecked` is valid
 ``ULC_MASK_FOOTER_KIND``     0x1000000 :meth:`~UltimateListItem.GetFooterKind` is valid

Sets data for the item, which can be any Python object.

:param `data`: any Python object associated to the item.

Sets an item as shown/hidden.

:param `shown`: ``True`` to show the item, ``False`` to hide it.

:note: The valid state flags are influenced by the value of the state mask.

:see: :meth:`~UltimateListItem.SetStateMask`

Sets the bitmask that is used to determine which of the state flags are
to be set.

:param `stateMask`: the state bitmask.

:see: :meth:`~UltimateListItem.SetState` for a list of valid state bits.

Sets the text label for the item.

:param `text`: the text label for the item.

Sets the text colour for the item.

Sets the tooltip text for the item.

:param `text`: the tooltip text for the item.

:param `visited`: ``True`` to set a hypertext item as visited, ``False`` otherwise.

:param `width`: the column width.

Sets the window associated to the item.

Represents the attributes (colour, font, ...) of a :class:`UltimateListCtrl`
:class:`UltimateListItem`.

:param `colText`: the item text colour;
:param `colBack`: the item background colour;
:param `font`: the item font;
:param `enabled`: ``True`` if the item should be enabled, ``False`` if it is disabled;
:param `footerColText`: for footer items, the item text colour;
:param `footerColBack`: for footer items, the item background colour;
:param `footerFont`: for footer items, the item font.

__init__(self, colText=wx.NullColour, colBack=wx.NullColour, font=wx.NullFont, enabled=True, footerColText=wx.NullColour, footerColBack=wx.NullColour, footerFont=wx.NullFont)

Returns ``True`` if the currently set background colour is valid. 

Returns ``True`` if the currently set background colour for the footer item
is valid.

Returns ``True`` if the currently set font for the footer item
is valid.

Returns ``True`` if the currently set text colour for the footer item
is valid.

Sets a new background colour.

Sets a new font for the item.

Sets a new footer item background colour.

Sets a new footer item text colour.

Sets a new text colour.

attributes (client rectangles, positions, etc...).

:param `owner`: an instance of :class:`UltimateListCtrl`.

:param `info`: an instance of :class:`UltimateListItemData`.

:see: :meth:`~UltimateListItemData.SetKind` for a list of valid item kinds.

Returns the item text or a simple string if the item text is the
empty string.

Returns ``True`` if the item has at least one image associated with it. 

Returns ``True`` if the item is enabled, ``False`` if it is disabled. 

Sets the item attributes.

:param `attr`: an instance of :class:`UltimateListItemAttr`.

Sets the text font for the item.

Sets information about the item.

Sets the item position.

Sets the item size.

:param `width`: the item width, in pixels;
:param `height`: the item height, in pixels.

Sets the tooltip for the item

:param `tooltip`: the tooltip text

A simple class which holds line geometries for :class:`UltimateListCtrl`. 

Calculates the line size and item positions.

:param `spacing`: the spacing between the items, in pixels.

:param `index`: the index of the item;

Draws the line on the specified device context.

:param `line`: an instance of :class:`UltimateListLineData`;

:param `rect`: the rectangle to be filled with the gradient shading;
:param `hasfocus`: ``True`` if the main :class:`UltimateListCtrl` has focus, ``False``

Draws the line on the specified device context when the parent :class:`UltimateListCtrl`
is in report mode.

:param `rect`: the item client rectangle;
:param `rectHL`: the item client rectangle when the item is highlighted;
:param `highlighted`: ``True`` if the item is highlighted, ``False`` otherwise;
:param `current`: ``True`` if the item is the current item;
:param `enabled`: ``True`` if the item is enabled, ``False`` otherwise;
:param `oldPN`: an instance of :class:`wx.Pen`, to save and restore at the end of
 the drawing;
:param `oldBR`: an instance of :class:`wx.Brush`, to save and restore at the end of
 the drawing.

DrawInReportMode(self, dc, line, rect, rectHL, highlighted, current, enabled, oldPN, oldBR)

:param `row`: the line number to which this item belongs to;
:param `col`: the column number to which this item belongs to;
:param `itemRect`: the item client rectangle;
:param `overflow`: ``True`` if the item should overflow into neighboring columns,

Returns an instance of :class:`UltimateListItemAttr` associated with the first item
in the line.

:param `index`: the index of the item.

:see: :meth:`~UltimateListLineData.SetKind` for a list of valid item kinds.

Returns the item text at the position `index`.

Returns the item tooltip at the position `index`.

Returns ``True`` if the first item in the line has at least one image
associated with it.

Returns ``True`` if the parent :class:`UltimateListCtrl` has the window
style specified by `mode`.

:param `mode`: the window style to check.

Returns ``True`` if the text of first item in the line is not the empty
string.

If the input item has a window associated with it, hide it.

Sets the current line as highlighted or not highlighted.

:param `on`: ``True`` to set the current line as highlighted, ``False``

Initializes the list of items.

:param `num`: the initial number of items to store.

Returns ``True`` if the parent :class:`UltimateListCtrl` is in report view. 

Returns ``True`` if the parent :class:`UltimateListCtrl` has the ``ULC_VIRTUAL`` style set. 

Reverses the line highlighting, switching it off if it was on and vice-versa.

Sets an instance of :class:`UltimateListItemAttr` to the first item in the line.

Sets various attributes to the input device context.

:param `attr`: an instance of :class:`UltimateListItemAttr`;
:param `highlighted`: ``True`` if the item is highlighted, ``False`` otherwise.

:param `c`: an instance of :class:`wx.Colour`.

Sets the line position.

:param `x`: the current `x` coordinate;
:param `y`: the current `y` coordinate;
:param `spacing`: the spacing between items, in pixels.

Sets whether :class:`UltimateListLineData` is in report view or not.

:param `inReportView`: ``True`` to set :class:`UltimateListLineData` in report view, ``False``

Sets the item text at the position `index`.

:param `s`: the new item text.

Sets the item tooltip at the position `index`.

:param `s`: the new item tooltip.

Sets the line `x` position.

:param `x`: the new line `x` position.

Sets the line `y` position.

:param `y`: the new line `y` position.

This is the main widget implementation of :class:`UltimateListCtrl`.

:param `style`: the underlying :class:`ScrolledWindow` window style;
 bits:

 ``ULC_NO_ITEM_DRAG``             0x200000000 Disable item dragging

__init__(self, parent, id, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="listctrlmainwindow")

Checks/unchecks all the items.

:param `isChecked`: ``True`` to check the items, ``False`` to uncheck them;
:param `column`: the column to which the items belongs to.

Toggles all the items.

Saves the current line attributes.

:param `line`: an instance of :class:`UltimateListLineData`.

:note: This method is used only if the :class:`UltimateListCtrl` has the ``ULC_VIRTUAL``
 style set.

Changes the current line to the specified one.

:param `current`: an integer specifying the index of the current line.

events ``EVT_LIST_ITEM_CHECKING`` / ``EVT_LIST_ITEM_CHECKED``.

:param `item`: an instance of :class:`UltimateListItem`;
:param `checked`: ``True`` to check an item, ``False`` to uncheck it;
:param `sendEvent`: ``True`` to send a {UltimateListEvent}, ``False`` otherwise.

 deleting many items from the control would be too slow then (unlike :meth:`~UltimateListMainWindow.DeleteItem`).

Deletes all items in the :class:`UltimateListCtrl`, resetting column widths to zero. 

:param `lindex`: the index of the item to delete.

A drag and drop operation has just finished.

Draws the item checkbox/radiobutton image.

:param `x`: the x position where to draw the image;
:param `y`: the y position where to draw the image;

  =============== ==========================
  Item Kind       Description
         0        A normal item
         1        A checkbox-like item
         2        A radiobutton-type item

:param `checked`: ``True`` if the item is checked, ``False`` otherwise;
:param `enabled`: ``True`` if the item is enabled, ``False`` if it is disabled.

Draws one of the item images.

:param `index`: the index of the image inside the image list;

:param col: an integer specifying the column index.

Returns the custom renderer used to draw the column header

:param `checkbox`: ``True`` to get a checkbox image, ``False`` for a radiobutton
 one;
:param `checked`: ``True`` if the control is marked, ``False`` if it is not;
:param `enabled`: ``True`` if the control is enabled, ``False`` if it is not;
:param `x`: the width of the bitmap, in pixels;
:param `y`: the height of the bitmap, in pixels.

Returns a dummy line.

 style set.

Returns the image size for the item.

:param `index`: the image index.

:see: :meth:`~UltimateListMainWindow.SetItemKind` for a list of valid item kinds.

:see: :meth:`~UltimateListMainWindow.SetItemStateAll` for a list of valid state flags.

Returns the item width, in pixels, considering only the item text.

Returns the item width, in pixels, considering the item text and its images.

Returns the line data for the given index.

:param `n`: the line index.

Returns the line client rectangle for the item checkbox image only.

Returns the line height for a specific item.

:param `item`: if not ``None``, an instance of :class:`UltimateListItem`.

Returns the line client rectangle when the line is highlighted.

Returns the line client rectangle for the item image only.

Returns the line client rectangle for the item text only.
Note this is the full column width unless an image or
checkbox exists. It is not the width of the text itself

Returns the line client rectangle.

Returns the size of the total line client rectangle.

Returns the line `y` position.

Returns the parent widget, an instance of :class:`UltimateListCtrl`. 

:param `down`: ``True`` to search downwards for an active item, ``False``
 to search upwards.

Returns the colour to be used for drawing the horizontal and vertical rules. 

 :meth:`~UltimateListMainWindow.GetItemRect`.

Returns the text width for the input string.

:param `s`: the string to measure.

Returns the total width of the columns in :class:`UltimateListCtrl`. 

Returns the custom value for the :class:`UltimateListMainWindow` item height, if previously set with
:meth:`~UltimateListMainWindow.SetUserLineHeight`.

Returns the range of visible items on screen.

:note: This method can be used only if :class:`UltimateListCtrl` has the ``ULC_REPORT``
 style set.

Handles the hyperlink items, sending the ``EVT_LIST_ITEM_HYPERLINK`` event.

Returns ``True`` if the window has the given `flag` bit set.

:param `flag`: the bit to check.

:see: :meth:`UltimateListCtrl.SetSingleStyle() <UltimateListCtrl.SetSingleStyle>` for a list of valid flags.

Returns ``True`` if the current item has been set, either programmatically
or by user intervention.

Highlights/unhighlights all the lines in :class:`UltimateListCtrl`.

:param `on`: ``True`` to highlight all the lines, ``False`` to unhighlight them.

Highlights a line in :class:`UltimateListCtrl`.

:param `highlight`: ``True`` to highlight the line, ``False`` otherwise.

Highlights a range of lines in :class:`UltimateListCtrl`.

:param `lineFrom`: an integer representing the first line to highlight;
:param `lineTo`: an integer representing the last line to highlight;
:param `highlight`: ``True`` to highlight the lines, ``False`` otherwise.

:see: :meth:`~UltimateListMainWindow.HitTestLine` for a list of return flags.

HitTest method for a :class:`UltimateListCtrl` line.

:return: a tuple of values, representing the item hit and a hit flag. The
 hit flag can be one of the following bits:

 =============================== ========= ================================
 HitTest Flag                    Hex Value Description
 ``ULC_HITTEST_ABOVE``                 0x1 Above the client area
 ``ULC_HITTEST_BELOW``                 0x2 Below the client area
 ``ULC_HITTEST_NOWHERE``               0x4 In the client area but below the last item
 ``ULC_HITTEST_ONITEM``              0x2a0 Anywhere on the item (text, icon, checkbox image)
 ``ULC_HITTEST_ONITEMICON``           0x20 On the bitmap associated with an item
 ``ULC_HITTEST_ONITEMLABEL``          0x80 On the label (string) associated with an item
 ``ULC_HITTEST_ONITEMSTATEICON``     0x200 On the state icon for a list view item that is in a user-defined state
 ``ULC_HITTEST_TOLEFT``              0x400 To the left of the client area
 ``ULC_HITTEST_TORIGHT``             0x800 To the right of the client area
 ``ULC_HITTEST_ONITEMCHECK``        0x1000 On the item checkbox (if any)

:param `col`: the column index at which we wish to insert a new column;

:note: This method is meaningful only if :class:`UltimateListCtrl` has the ``ULC_REPORT``
 or the ``ULC_TILE`` styles set.

Returns ``True`` if the window is in tile mode (partially implemented).

.. todo:: Fully implement tile view for :class:`UltimateListCtrl`.

Returns ``True`` if the input line is highlighted.

Returns ``True`` if we are in single selection mode, ``False`` if multi selection. 

Returns ``True`` if the window has the ``ULC_VIRTUAL`` style set. 

Scrolls the input item into view.

Handles the keyboard arrows key events.

:param `newCurrent`: an integer specifying the new current item;

Handles the ``wx.EVT_CHAR`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_CHILD_FOCUS`` event for :class:`UltimateListMainWindow`.

.. note::

   This method is intentionally empty to prevent the default handler in
   :class:`ScrolledWindow` from needlessly scrolling the window when the edit
   control is dismissed.

Returns whether 2 lines have the same index.

in the :class:`UltimateListCtrl`. The function should return a negative, zero or positive
value if the first line is less than, equal to or greater than the second one.

:param `line1`: an instance of :class:`UltimateListItem`;
:param `line2`: another instance of :class:`UltimateListItem`.

:note: The base class version compares lines by their index.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_TIMER`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_PAINT`` event for :class:`UltimateListMainWindow`.

Called by :class:`UltimateListTextCtrl`, to accept the changes and to send the
``EVT_LIST_END_LABEL_EDIT`` event.

:param `itemEdit`: an instance of :class:`UltimateListItem`;

Called by :class:`UltimateListTextCtrl`, to cancel the changes and to send the

Handles the ``wx.EVT_SCROLLWIN`` event for :class:`UltimateListMainWindow`.

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`UltimateListMainWindow`.

Draws a watermark at the bottom right of :class:`UltimateListCtrl`.

Recalculates all the items positions, and sets the scrollbars positions
too.

:param `noRefresh`: ``True`` to avoid calling `Refresh`, ``False`` otherwise.

Redraws all the lines after the input one.

:param `lineFrom`: an integer representing the first line to refresh.

Redraws the input line.

Redraws a range of lines in :class:`UltimateListCtrl`.

:param `lineFrom`: an integer representing the first line to refresh;
:param `lineTo`: an integer representing the last line to refresh.

Resets the line dimensions, so that client rectangles and positions are
recalculated.

:param `force`: ``True`` to reset all line dimensions.

Called by :class:`UltimateListTextCtrl` when it marks itself for deletion.

Forces us to recalculate the range of visible lines.

:param `reset`: ``True`` to reset all line dimensions, which will then be
 recalculated.

If ``ULC_AUTOSIZE_FILL`` was passed to :meth:`UltimateListCtrl.SetColumnWidth() <UltimateListCtrl.SetColumnWidth>` then
that column's width will be expanded to fill the window on a resize event.

Called by :meth:`UltimateListCtrl.OnSize() <UltimateListCtrl.OnSize>` when the window is resized.

Toggles the line state and refreshes it.

Actually sends a :class:`UltimateListEvent`.

:param `command`: the event type to send;
:param `point`: an instance of :class:`wx.Point`.

SendNotify(self, line, command, point=wx.DefaultPosition, col=0)

Associate a custom renderer to this column's header

 ``wx.LIST_AUTOSIZE_USEHEADER`` (-2) or ``ULC_AUTOSIZE_FILL`` (-3).
 ``ULC_AUTOSIZE_FILL`` will resize the column fill the remaining width

Overridden base class virtual to reset the line height when the font changes.

:param `sizex`: the width of the bitmaps in the `imglist`;
:param `sizey`: the height of the bitmaps in the `imglist`;

:param `item`: an instance of :class:`UltimateListItemData`.

This method can only be used with virtual :class:`UltimateListCtrl`. It is used to
indicate to the control the number of items it contains. After calling it,
the main program should be ready to handle calls to various item callbacks
(such as :meth:`UltimateListCtrl.OnGetItemText() <UltimateListCtrl.OnGetItemText>`) for all items in the range from 0 to `count`.

:param `count`: the total number of items in :class:`UltimateListCtrl`.

:param `litem`: the index of the item; if defaulted to -1, the state flag
:param `state`: the item state flag;

Sets the item state flags for all the items.

:param `value`: the new item text.

 the item;

:param `enable`: ``True`` to enable the associated window, ``False`` to

Sets whether :class:`UltimateListCtrl` is in report view or not.

:param `inReportView`: ``True`` to set :class:`UltimateListCtrl` in report view, ``False``

Sets a custom value for the :class:`UltimateListMainWindow` item height.

 :meth:`~UltimateListMainWindow.OnCompareItems` method.

This is a subclass of :class:`~wx.lib.expando.ExpandoTextCtrl` as :class:`UltimateListCtrl`
supports multiline text items.

:note: To add a newline character in a multiline item, press ``Shift`` + ``Enter``
 as the ``Enter`` key alone is consumed by :class:`UltimateListCtrl` to finish
 the editing and ``Ctrl`` + ``Enter`` is consumed by the platform for tab navigation.

:param `owner`: the control parent (an instance of :class:`UltimateListCtrl` );
:param `itemEdit`: an instance of :class:`UltimateListItem`.

Handles the ``wx.EVT_CHAR`` event for :class:`UltimateListTextCtrl`.

Handles the ``wx.EVT_KEY_UP`` event for :class:`UltimateListTextCtrl`.

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`UltimateListTextCtrl`.

Checks whether a `text` contains multiline strings and if the `listCtrl` window
style is compatible with multiline strings.

:param `listCtrl`: an instance of :class:`UltimateListCtrl`;
:param `text`: the text to analyze.

Creates a new instance of :class:`UltimateListItem`.

:param `itemOrId`: can be an instance of :class:`UltimateListItem` or an integer;
:param `col`: the item column.

Returns the drag and drop cursor image as a :class:`wx.Bitmap`. 

Returns the drag and drop cursor image as a decompressed stream of characters. 

Converts the input data into a Python list.

:param `input`: can be an integer or a Python list (in which case nothing will
 be done to `input`.

:class:`~wx.lib.agw.xlsgrid.XLSGrid` is a class based on :class:`grid.Grid` that can be used to faithfully
reproduce the appearance of a Microsoft Excel spreadsheet (one worksheet per
every instance of :class:`XLSGrid`).

:class:`XLSGrid` is a class based on :class:`grid.Grid` that can be used to faithfully

:class:`XLSGrid` is a completely owner-drawn control, and it relies on the power of
:class:`grid.PyGridTableBase` and :class:`grid.PyGridCellRenderer` to draw the cell
content. For this reasons (and for some others, see the TODOs section), it will
work efficiently only for relatively small Excel files.

:note:

 :class:`XLSGrid` **requires** the `xlrd` package from:

 http://pypi.python.org/pypi/xlrd

 Minimum version requirement for `xlrd` is 0.7.1. If you wish to have
 support for hyperlinks inside cells and rich text content, you need the
 SVN version of `xlrd`.

:note:

 On Windows, it is **strongly** recommended to install Mark Hammonds'
 `pywin32` package:

 http://sourceforge.net/projects/pywin32/

 This will allow you to perfectly reproduce the appearance of the Excel
 worksheet in your instance of :class:`XLSGrid`.

   If Mark Hammonds' `pywin32` package is not available, the formatting
   capabilities of :class:`XLSGrid` are severely limited; for instance, you won't
   probably get the exact WYSIWYG between the Excel spreadsheet and :class:`XLSGrid`.

   :class:`XLSGrid` can only read Excel `.xls` files, not the newer versions
   `.xlsx` generated by Office 2007/2010. If you have a `.xlsx` file, you will
   need to save it in 1997-2003 Office compatibility mode.

Currently this class provides a read-only subclass of :class:`grid.Grid`, with
the following formatting features already implemented:

* Cell background: support for any cell background colour and fill pattern
  (hatching) in the Excel default set. There currently is no support for
  gradient shading inside a cell as `xlrd` doesn't report this information.

* Cell borders: support for all the border types and colours exposed by Excel
  (left, top, bottom, right and diagonal borders, thin, double, thick, etc...
  line styles).

* Cell text: support for all kind of fonts (except strikethrough, but this is
  a bug in wxWidgets), and font colours. As a subset of text/font capabilities,
  :class:`XLSGrid` supports the following features found in Excel:

  - Horizontal alignment: left, right, centered, left-indented;
  - Vertical alignment: left, right, centered;
  - Text direction: left-to-right or right-to-left;
  - Text-wrapping: wrapping long texts inside a grid cell;
  - Shrink-to-fit: text font is reduced until the text can fit in a one-line
    inside the grid cell;
  - Text rotation: text can be rotated from +90 to -90 degrees.

* Cell rich text (new in version 0.2): support for strings containing partial
  bold, italic and underlined text, change of font inside a string etc...
  Cells with rich text content can not be multi-line and they will not honour
  the `shrink-to-fit` and `wrapping` settings.

* Cell text appearance: if you are using Mark Hammonds' `pywin32` package, the
  text displayed in the :class:`XLSGrid` cells has exactly the same appearance as in
  the Excel spreadsheet.

* Cell comments (notes): if you are using Mark Hammonds' `pywin32` package,
  cell comments (notes) are extracted and you will see a small red triangle at
  the top-right corner of any cell containing a comment. Hovering with the
  mouse on that cell will pop-up a "comment-window" displaying the comment
  text (the comment window is based on :mod:`lib.agw.supertooltip`).

* Cell hyperlinks: starting from version 0.7.2 (SVN), `xlrd` is capable of
  extracting hyperlinks from Excel cells. This will be appropriately displayed
  in :class:`XLSGrid` with a cursor changing and a tooltip on that cell.

* Cell merging: merged cells in the Excel spreadsheet will be correctly handled
  by :class:`XLSGrid`.

* Columns and rows sizes: :class:`XLSGrid` calculates the correct rows and columns
  sizes based on the Excel reported values in characters. The calculations are
  based on the default width of the text in 1/256 of the width of the zero
  character, using default Excel font (first FONT record in the Excel file).

Usage
=====

    import wx
    import xlrd
    import os

    import xlsgrid as XG

            wx.Frame.__init__(self, parent, -1, "XLSGrid Demo", size=(1000, 800))

            filename = os.path.join(os.getcwd(), "Excel", "Example_1.xls")
            sheetname = "Example_1"

            book = xlrd.open_workbook(filename, formatting_info=1)

            sheet = book.sheet_by_name(sheetname)
            rows, cols = sheet.nrows, sheet.ncols

            comments, texts = XG.ReadExcelCOM(filename, sheetname, rows, cols)

            xls_grid = XG.XLSGrid(self)
            xls_grid.PopulateGrid(book, sheet, texts, comments)

:note: Please note that you **have to** pass the keyword `formatting_info` to
 the method `xlrd.open_workbook` to obtain the cell formatting.

TODOs
=====

1. :class:`XLSGrid` is sufficiently efficient and fast for reasonably small Excel files.
   There might be some improvement to be made in the code to make it work with
   bigger files and in a faster way;
2. :class:`grid.Grid` seems to completely redraw itself at every resize event, even
   if the cell content has not changed and it has not been damaged (this seems
   to be fixed in wxPython 2.9.2.1);
3. There is currently no support for strikethrough fonts, although `xlrd` correctly
   reports this format. The issue is a bug in wxWidgets itself which doesn't
   allow the creation of strikethrough fonts (http://trac.wxwidgets.org/ticket/9907).

:class:`XLSGrid` has been tested on the following platforms:
  * Windows (Windows Vista and 7);

:class:`XLSGrid` is distributed under the wxPython license.

# XLSGRID wxPython IMPLEMENTATION
#
# Andrea Gavana @ 08 Aug 2011
#
#
# TODO List
#
# Current todo list:
#
# 1. There is currently no support for rich text, i.e. strings containing partial
#    bold, italic and underlined text, change of font inside a string, etc... xlrd
#    supports those (from version 0.7.2 in SVN) but there is no easy way to handle
#    changing fonts/colours/formatting in the same string in wxPython;
#
# 2. XLSGrid is sufficiently efficient and fast for reasonably small Excel files.
#    There might be some improvement to be made in the code to make it work with
#    bigger files and in a faster way;
#
# 3. There is currently no support for strikethrough fonts, although xlrd correctly
#    reports this format. The issue is a bug in wxWidgets itself which doesn't
#    allow the creation of strikethrough fonts (http://trac.wxwidgets.org/ticket/9907).
#
# For all kind of problems, requests of enhancements and bug reports, please write
# to me at:
#
#
#
#
# End of comments

attrgetter(attr, ...) --> attrgetter object

Return a callable object that fetches the given attribute(s) from its operand.
After f = attrgetter('name'), the call f(r) returns r.name.
After g = attrgetter('name', 'date'), the call g(r) returns (r.name, r.date).
After h = attrgetter('name.first', 'name.last'), the call h(r) returns
(r.name.first, r.name.last).

A simple class that holds a COM interface to Excel.

By using the `win32com` module from Mark Hammonds' `pywin32` package, we
can manipulate various workbook/worksheet methods inside this class.

:param `filename`: a valid Excel `.xls` filename;
:param `sheetname`: the worksheet name inside the Excel file (i.e., the label
 on the workbook tab at the bottom of the workbook).

Closes the Excel workbook, interrupting the COM interface.

:param `save`: ``True`` to save the changes you made to the workbook,

Returns a range of cells containing comments, using the VBA API.

Returns the WYSIWYG text contained in a cell.

:param `row`: the row in which the cell lives;
:param `col`: the column in which the cell lives.

:note: The `row` and `col` parameters are not real Python index, as they
 use the Excel indexing mode (i.e., first index is 1 and not 0).

This is a subclass of :class:`SuperToolTip` and it is used to display a
"comment-window" on the cells containing a comment (a note).

:note: If Mark Hammonds' `pywin32` package is not available, this class is
 never invoked.

:param `grid_window`: the actual window representing the grid;
:param `comment`: an instance of :class:`XLSComment`, containing the
 text for this comment;
:param `position`: the position at which we pop up the comment
 window (currently unused).

This is a class which holds information about the cell background, in terms
of background colour and background pattern (hatching).

:param `book`: an instance of the `xlrd.Book` class;
:param `xf_index`: an index into `xlrd.Book.xf_list`, which holds a
 reference to the `xlrd.sheet.Cell` class (the actual cell for `xlrd`).

Combines the input attribute `attr` with the features of the :class:`XLSBackground` class.

:param `attr`: an instance of :class:`grid.GridCellAttr`.

Creates a suitable wxPython colour for the cell background starting from
a `xlrd` tuple representing this colour.

:param `background_colour`: a tuple representing the RGB components of the
 cell background colour. If `background_colour` is ``None``, use the
 default ``wx.SYS_COLOUR_WINDOW``;
:param `pattern_colour`: a tuple representing the RGB components of the
 cell pattern colour;
:param `fill_pattern`: the pattern to use to draw hatches on top of the
 background.

CreateBackgroundColour(self, background_colour, pattern_colour, fill_pattern)

Actually draws the cell background and pattern hatching on a grid cell.

:param `rect`: an instance of :class:`wx.Rect`, representing the cell rectangle.

This is a class which holds information about a single cell border, in terms
of its location (top, left, bottom, right, diagonal), its colour, width and
shape.

:param `location`: the actual border location (top, left, bottom, right,
 diagonal);
:param `line_style`: the line style used by Excel to draw this border;
:param `border_colour`: the colour used by Excel to draw this border;
:param `default_colour`: the "magic" colour used by Excel to draw non-custom
 border lines;
:param `diagonals`: a tuple containing whether or not to draw the up and down
 diagonal borders.

__init__(self, location, line_style, border_colour, default_colour, diagonals)

Actually draws the cell border.

Actually draws the cell border (one of left, right, bottom, top).

Actually draws the cell diagonal border.

This is a factory class which holds information about all the borders in a
cell. Its implementation and use is merely to simplify the handling of the
different cell borders (left, top, bottom, right, diagonal).

:param `border`: an instance of `xlrd.formatting.XFBorder` class;
 border lines.

Actually draws all the cell borders based on their drawing priority.

:note: The drawing priority is assigned depending on if the border is a
 custom one or not. Customized borders are drawn last.

This is a class which holds information about a single cell in :class:`XLSGrid`.
It stores (via auxiliary classes), all details about cell background, text,
font, colours and borders.

:param `cell`: an instance of `xlrd.sheet.Cell` class;
 reference to the `xlrd.sheet.Cell` class (the actual cell for `xlrd`);
:param `xls_text`: the actual WYSIWYG cell text, if available;
:param `xls_comment`: the cell comment (note), if any;
:param `hyperlink`: an instance of `xlrd.sheet.hyperlink`;
:param `rich_text`: if this cell contains text in rich text format, :class:`XLSGrid`
 will do its best to render the text as rich text;
:param `default_width`: this is the default width of the text in 1/256
 of the width of the zero character, using default Excel font (first FONT
 record in the Excel file);

:note: If you are using version 0.7.1 or lower for `xlrd`, the *hyperlink*
 parameter will always be ``None`` as this feature is available only in
 `xlrd` 0.7.2 (SVN).

:note: If you are using version 0.7.1 or lower for `xlrd`, the `rich_text`

:note: if Mark Hammonds' `pywin32` package is not available, the `xls_text`
 parameter will almost surely not be the WYSIWYG representation of the cell
 text.

:note: If Mark Hammonds' `pywin32` package is not available, the `xls_comment`
 parameter will always be ``None``.

__init__(self, book, cell, xf_index, xls_text, xls_comment, hyperlink, rich_text, default_width, default_colour)

Returns the attribute to use for this specific cell.

:returns: an instance of :class:`grid.GridCellAttr`.

Returns the cell comment, if any.

:returns: an instance of :class:`XLSComment`.

:note: If Mark Hammonds' `pywin32` package is not available, this method
 always returns ``None``.

Sets the size of the cell.

Specifying a value of more than 1 in `rows` or `cols` will make the cell
at (`row`, `col`) span the block of the specified size, covering the other
cells which would be normally shown in it. Passing 1 for both arguments
resets the cell to normal appearance.

:param `rows`: number of rows to be occupied by this cell, must be >= 1;
:param `cols`: number of columns to be occupied by this cell, must be >= 1.

Actually sets up the :class:`XLSCell` class. This is an auxiliary method to
avoid cluttering the :meth:`~xlsgrid.XLSCell.__init__` method.

 text.

SetupCell(self, book, cell, xf_index, xls_text, xls_comment, hyperlink, rich_text, default_width, default_colour)

Sets the actual WYSIWYG representation of the cell value.

:param `value`: the current text value to insert in the cell.

:note: This method is currently unused as everything is handled inside the :class:`XLSText` class.

:see: :meth:`~xlsgrid.XLSCell.GetValue`

This is a class which holds information about the content of the "comment
window" (aka note) in Excel.

:note: If Mark Hammonds' `pywin32` package is not available, this class can
 not be used.

:param `comment`: the actual text contained in the Excel cell comment (note).

Actually draws a small red triangle in the top-right corder of the cell
to indicate that a comment is present.

:param `parent`: the grid parent window. Must not be ``None``.

If a comment window or a tooltip over a hyperlink have been created, this
method destroys them.

Processes the creation of a single cell (an instance of :class:`XLSCell`).

:param `sheet`: an instance of the `xlrd.sheet` class;
:param `row`: the row in which this cell lives;
:param `col`: the column in which this cell lives;
:param `display_texts`: if Mark Hammonds' `pywin32` package is available,
 this is the WYSIWYG cell content for all the cells in the Excel worksheet;
:param `comments`: if Mark Hammonds' `pywin32` package is available,
 this is a nested list of cell comments (notes) for all the cells in the
 Excel worksheet;
:param `hyperlink`: if this cell contains a hyperlink, it will be displayed
 accordingly;

:note: If Mark Hammonds' `pywin32` package is not available, the `display_texts`
 and `comments` parameter will be two empty nested lists.

FormatCell(self, book, sheet, row, col, display_texts, comments, hyperlink, rich_text, default_width, default_colour)

Returns suitable width and height (in pixels) starting from Excel's own
measurements (in characters, whatever that means).

:param `book`: an instance of the `xlrd.Book` class.

:returns: a `default_width` and `default_height` in pixels, based on the
 default width of the text in 1/256 of the width of the zero character,
 using default Excel font (first FONT record in the Excel file).

Auxiliary method used to bind a ``wx.EVT_MOTION`` event to :class:`XLSGrid`.

This is the main method of this class, and it is used to actually create
the cells, size the columns and rows, merging cells, etc...

 Excel worksheet.

This class is responsible for actually drawing the cell in the grid.

:param `cell`: an instance of :class:`XLSCell`.

Draw the given cell on the provided `dc` inside the given rectangle using
default or selected state corresponding to the `isSelected` value.

:param `grid`: an instance of :class:`grid.Grid`;
:param `attr`: an instance of :class:`grid.GridCellAttr`;
:param `rect`: an instance of :class:`wx.Rect`, representing the cell rectangle;
:param `isSelected`: ``True`` if the cell is selected, ``False`` otherwise.

This is a class which holds information about the cell content, in terms
of actual cell value, font, text colour, alignment and formatting. In addition
to what :class:`XLSText` does, this class attempts to handle cells with rich text
content.

:param `display_text`: if Mark Hammonds' `pywin32` package is available,
 this is the WYSIWYG cell content;
 record in the Excel file).

:note: If you are using version 0.7.1 or lower for `xlrd`, this class will
 note be used by :class:`XLSGrid`.

   This class currently supports only single-line non-rotated text,
   and it discards properties like `shrink-to-fit` and `wrapping`.

__init__(self, book, cell, xf_index, display_text=None, hyperlink=None, rich_text=None, default_width=10)

Splits the cell content accordingly to their rich text format index.

 will do its best to render the text as rich text.

Actually draws all the chunks of text on a grid cell, one by one.

Convenience method to measure the maximum height and total width of all
the chunks of text composing our rich text string.

The almost abstract base class for grid tables.

A grid table is responsible for storing the grid data and, indirectly, grid
cell attributes. The data can be stored in the way most convenient for the
application but has to be provided in string form to :class:`grid.Grid`.

:param `cells`: a Python dictionary. For every key `(row, col)`, the
 corresponding value is an instance of :class:`XLSCell`;
:param `rows`: the number of rows in the table;
:param `cols`: the number of columns in the table.

Return the attribute for the given cell.

:param `kind`: the kind of the attribute to return.

Returns the "raw" value for the cell content.

:param `col`: the column in which this cell lives.

Returns the cell content for the specified row and column.

sets the cell content for the specified row and column.

:param `value`: the new value to assign to the specified cell.

of actual cell value, font, text colour, alignment and formatting.

__init__(self, book, cell, xf_index, display_text=None, hyperlink=None, default_width=10)

Combines the input attribute `attr` with the features of the :class:`XLSText` class.

Creates a suitable wxPython alignment flag for the text starting from a
`xlrd` class representing this alignment.

:param `alignment`: an instance of `xlrd.formatting.XFAlignment` class;

Creates a suitable wxPython font starting from an Excel font.

:param `font`: an instance of `xlrd.formatting.Font` class.

:note: There is currently no support for strikethrough fonts, although
 `xlrd` correctly reports this format. The issue is a bug in wxWidgets
 itself which doesn't allow the creation of strikethrough fonts. See
 (http://trac.wxwidgets.org/ticket/9907).

This method tries to guess the best format to apply to the current text
value.

:param `format`: an instance of `xlrd.formatting.Format` class;
:param `datemode`: the datemode associated with this Excel workbook.

:note: This method is used only if Mark Hammonds' `pywin32` package is
 not available to try and format the cell text in an intelligent way.

   The formatting applied by this method is severely limited; for
   instance, you won't probably get the exact WYSIWYG between the Excel
   spreadsheet and :class:`XLSGrid`.

Creates a suitable wxPython colour for the text starting from a `xlrd`
tuple representing this colour.

:param `text_colour`: a tuple representing the RGB components of the
 colour. If `text_colour` is ``None``, use the default ``wx.SYS_COLOUR_WINDOWTEXT``.

Actually draws the text value on a grid cell.

value.

:param `value`: the actual raw cell text value;
:param `isDate`: ``True`` if this value represents a `xlrd` date object,
:param `format_str`: the actual formatting string as extracted from Excel.

Returns whether the cell text is representing a hyperlink.

:returns: ``True`` if the cell text represents a hyperlink, ``False``

Sets up the cell text value in case it represents a hyperlink.

:param `hyperlink`: an instance of `xlrd.sheet.hyperlink`.

Reads and Excel spreadsheet (a single worksheet) using Mark Hammonds' `pywin32`
package. If this package is not available, it returns two empty nested lists.

 on the workbook tab at the bottom of the workbook);
:param `rows`: the number of significant rows in the worksheet, as returned
 by `xlrd`;
:param `cols`: the number of significant columns in the worksheet, as returned
 by `xlrd`.

:returns: two nested lists representing the comments (notes) on every cell and
 the WYSIWYG representation of the cell content.

 returns two empty nested lists.

Splits a general float on thousands. GIGO on general input.

:param `s`: can be a float or a string, representing a number;
:param `tSep`: the character to be used as thousands separator;
:param `dSep`: the character to be used as decimal separator.

:returns: a string properly formatted with thousands and decimal
 separators in it.

 not available to try and format a number in an intelligent way.

:note: This code has been obtained from the public domain:

 http://code.activestate.com/recipes/498181-add-thousands-separator-commas-to-formatted-number/#c14

{'bottom': 128, 'left': 16, 'right': 32, 'top': 64, 'diag': 256}

{0: (0, None), 1: (1, 100), 2: (2, 100), 3: (1, 103), 4: (1, 101), 5: (3, 100), 6: (1, 100), 7: (1, 101), 8: (2, 102), 9: (1, 104), 10: (2, 104), 11: (1, 104), 12: (2, 104), 13: (2, 104)}

:class:`~wx.lib.agw.zoombar.ZoomBar` is a class that *appoximatively* mimics the behaviour of the Mac Dock,
inside a :class:`Panel`.

:class:`ZoomBar` is a class that *appoximatively* mimics the behaviour of the Mac Dock,

Once you hover mouse over the :class:`ZoomBar` correct button will bubble up, grow to
predefined size, so you can easily see the button you are about to click and
have larger area to click. Difference this makes is amazing.

The buttons are able to be zoomed from the bottom up (bottom fixed) as well
as to zoom from a central point. Also the container is able to move the
remaining buttons around the zoomed button.

Usage
=====

    import os
    import glob

    import wx
    import wx.lib.agw.zoombar as ZB

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

            bar = ZB.ZoomBar(panel, -1)

            standard = glob.glob(bitmapDir + "/*96.png")
            reflections = glob.glob(bitmapDir + "/*96Flip40.png")

            separatorImage = bitmapDir + "/separator.gif"
            separatorReflection = bitmapDir + "/separatorFlip.png"
            count = 0

            for std, ref in zip(standard, reflections):
                if random.randint(0, 1) == 1 and count > 0:
                    sep1 = wx.Bitmap(separatorImage, wx.BITMAP_TYPE_GIF)
                    sep2 = wx.Bitmap(separatorReflection, wx.BITMAP_TYPE_PNG)
                    bar.AddSeparator(sep1, sep2)

                bname = os.path.split(std)[1][0:-6]
                bar.AddButton(wx.Bitmap(std, wx.BITMAP_TYPE_PNG), wx.Bitmap(ref, wx.BITMAP_TYPE_PNG), bname)
                count += 1

            bar.ResetSize()

            sizer = wx.BoxSizer(wx.HORIZONTAL)
            sizer.Add(bar, 0, wx.ALIGN_CENTER_HORIZONTAL | wx.ALIGN_CENTER_VERTICAL | wx.ALL, 15)

:class:`ZoomBar` has been tested on the following platforms:

``EVT_ZOOMBAR``                Process a ``wxEVT_ZOOMBAR`` event, when a :class:`ZoomBar` button is clicked.

:class:`ZoomBar` is distributed under the wxPython license.

# ZoomBar wxPython IMPLEMENTATION
#
# Andrea Gavana @ 19 Dec 2012, 21.00 GMT
#
#
# to me at:
#
#
#
#

This class holds the background button bar on which the buttons float. 

:param `bitmap`: if not ``None``, the bitmap to use as a background button
 bar on which the buttons float. It should be an instance of :class:`wx.Image`.

Returns the position of :class:`wx.ImageBar`, as a :class:`wx.Point`. 

Returns the size of :class:`wx.ImageBar`, as a :class:`wx.Size`. 

Sets the background button bar colour.

:param `colour`: an instance of :class:`wx.Colour`;
:param `xSize`: if not ``None``, the new :class:`wx.ImageBar` width;
:param `ySize`: if not ``None``, the new :class:`wx.ImageBar` height.

Sets the position of :class:`wx.ImageBar`.

:param `xpos`: the `x` position of the bar;
:param `ypos`: the `y` position of the bar.

Sets the size of :class:`wx.ImageBar`.

:param `xSize`: the width of the bar, in pixels;
:param `ySize`: the height of the bar, in pixels.

:param `parent`: the :class:`ZoomBar` parent. Must not be ``None``;

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, name="ZoomBar")

Adds a button to :class:`ZoomBar`.

:param `normalBmp`: the button main bitmap, an instance of :class:`wx.Bitmap`;
:param `reflectionBmp`: a bitmap representing a reflection of the main bitmap,
 an instance of :class:`wx.Bitmap`;
:param `label`: the button label;
:param `disabledBmp`: the button main bitmap when the button is in a disabled
 state, an instance of :class:`wx.Bitmap`;
:param `disabledReflectionBmp`: a bitmap representing a reflection of the main bitmap,
 when the button is in a disabled state, an instance of :class:`wx.Bitmap`.

AddButton(self, normalBmp, reflectionBmp=wx.NullBitmap, label="", disabledBmp=wx.NullBitmap, disabledReflectionBmp=wx.NullBitmap)

Adds a separator to :class:`ZoomBar`.

:param `normalBmp`: the separator main bitmap, an instance of :class:`wx.Bitmap`;
 an instance of :class:`wx.Bitmap`.

Draws all the main button bitmaps on the :class:`ZoomBar` client window.

Draws all the button labels on the :class:`ZoomBar` client window.

Draws all the reflection button bitmaps on the :class:`ZoomBar` client window.

Enables/disables the button at position `index`.

:param `index`: the index of the button to enable/disable;

HitTest method for :class:`ZoomBar`.

:param `pos`: the current mouse position.

:return: an index representing the button on which the mouse is hovering,
 or ``wx.NOT_FOUND`` if no button has been hit.

Returns ``True`` if the button at position `index` is enabled, ``False``

:param `index`: the index of the button to check.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`ZoomBar`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`ZoomBar`.

Handles the ``wx.EVT_LEFT_DOWN`` and ``wx.EVT_LEFT_DCLICK`` events for :class:`ZoomBar`.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`ZoomBar`.

Handles the ``wx.EVT_MOTION`` event for :class:`ZoomBar`.

Handles the ``wx.EVT_PAINT`` event for :class:`ZoomBar`.

Handles the ``wx.EVT_SIZE`` event for :class:`ZoomBar`.

Repositions all the buttons inside the :class:`ZoomBar`.

:param `toButton`: the button currently hovered by the mouse (and hence zoomed).

Resets all the button sizes and positions, recalculating the optimal :class:`ZoomBar`
size.

Sets the original button size.

:param `size`: the new (not-zoomed) button size, in pixels.

Sets to zoom from the center.

:param `center`: if ``True`` button zooms upwards.

Sets whether to show button labels or not.

:param `show`: ``True`` to show button labels, ``False`` otherwise.

Sets whether to show reflections or not.

:param `show`: ``True`` to show reflections, ``False`` otherwise.

Sets the zoom factor for all the buttons. Larger number gives a greater zoom
effect.

:param `zoom`: a floating point number, greater than or equal to 1.0.

Snaps the background button bar bitmap and all the buttons to the bottom
of :class:`ZoomBar`.

:param `size`: the current :class:`ZoomBar` size.

Event sent from the :class:`ZoomBar` when a button is activated. 

Sets the text label of the selected button.

:param `label`: the text label of the selected button.

Sets the index of the selected button.

:param `selection`: an integer indicating the current selected button.

This simple class holds information about a :class:`ZoomBar` button, such as normal
bitmaps, disabled bitmap, button label, etc...

:param `parent`: the main :class:`ZoomBar` window;
:param `bitmap`: the button bitmap, an instance of :class:`wx.Bitmap`;
:param `disabledBmp`: the button bitmap when the button is in a disabled
 state;
:param `label`: the button label.

__init__(self, parent, bitmap, disabledBmp=wx.NullBitmap, label="")

Enables/disables a button.

:param `enable`: ``True`` to enable a button, ``False`` to disable it.

Returns the button bitmap, which may be a scaled up version of the original
bitmap is the button is being zoomed.

Returns ``True`` if the button is enabled, ``False`` otherwise. 

Caches the bitmaps at various zoom levels to avoid calling every time
`image.Scale` on the button bitmap.

:param `size`: the original button size, in pixels.

:param `label`: a string specifying the button label. May be an empty string
 for no label.

Sets the button size.

Set up the button position and size.

:param `buttonSize`: the button original size (not zoomed), in pixels.

Sets the zoom factor for the button. Larger number gives a greater zoom
effect.

Zooms the button bitmap depending on the mouse x position.

:param `nxcoord`: the mouse x position relative to the button center.

AnalogClock - an analog clock.

This control creates an analog clock window. Its features include shadowing,
the ability to render numbers as well as any arbitrary polygon as tick marks,
resize marks and hands proportionally as the widget itself is resized, rotate
marks in a way the get aligned to the watch. It also has a dialog, accessed
via a context menu item, allowing one to change on the fly all of its settings.

Usage:

       AnalogClock(parent, id=-1, pos=wx.DefaultPosition,
                   size=wx.DefaultSize, style=wx.NO_BORDER, name="AnalogClock",
                   clockStyle=DEFAULT_CLOCK_STYLE,
                   minutesStyle=TICKS_CIRCLE, hoursStyle=TICKS_POLY)

- parent, id, pos, size, style and name are used as in a wx.Window. Please
  refer to the wx.Window docs for more details.

- clockStyle defines the clock style, according to the options below:

    ====================  ================================
    SHOW_QUARTERS_TICKS   Show marks for hours 3, 6, 9, 12
    SHOW_HOURS_TICKS      Show marks for all hours
    SHOW_MINUTES_TICKS    Show marks for minutes

    SHOW_HOURS_HAND       Show hours hand
    SHOW_MINUTES_HAND     Show minutes hand
    SHOW_SECONDS_HAND     Show seconds hand

    SHOW_SHADOWS          Show hands and marks shadows

    ROTATE_TICKS          Align tick marks to watch
    OVERLAP_TICKS         Draw tick marks for minutes even
                          when they match the hours marks.

    DEFAULT_CLOCK_STYLE   The same as SHOW_HOURS_TICKS|
                          SHOW_MINUTES_TICKS|
                          SHOW_HOURS_HAND|
                          SHOW_MINUTES_HAND|
                          SHOW_SECONDS_HAND|
                          SHOW_SHADOWS|ROTATE_TICKS

- minutesStyle and hoursStyle define the the tick styles, according to the
  options below:

    =================   ======================================
    TICKS_NONE          Don't show tick marks.
    TICKS_SQUARE        Use squares as tick marks.
    TICKS_CIRCLE        Use circles as tick marks.
    TICKS_POLY          Use a polygon as tick marks. A
                        polygon can be passed using
                        SetTickPolygon, otherwise the default
                        polygon will be used.
    TICKS_DECIMAL       Use decimal numbers as tick marks.
    TICKS_ROMAN         Use Roman numbers as tick marks.
    TICKS_BINARY        Use binary numbers as tick marks.
    TICKS_HEX           Use hexadecimal numbers as tick marks.

Notes:

The 'target' keyword that's present in various of the AnalogClock methods may
accept one (or more, combined using '|') of the following values:

    =========  ===========================================
    HOUR       The values passed/retrieved are related to
               the hours hand/ticks

    MINUTE     The values passed/retrieved are related to
               the minutes hand/ticks

    SECOND     The values passed/retrieved are related to
               the seconds hand/ticks

    ALL        The same as HOUR|MINUTE|SECOND, i. e., the
               values passed/retrieved are related to all
               of the hours hands/ticks. This is the
               default value in all methods.

It is legal to pass target=ALL to methods that don't handle seconds (tick
mark related methods). In such cases, ALL will be equivalent to HOUR|MINUTE.

All of the 'Get' AnalogClock methods that allow the 'target' keyword
will always return a tuple, e. g.:

    =================================  ========================================
    GetHandSize(target=HOUR)           Returns a 1 element tuple, containing
                                       the size of the hours hand.

    GetHandSize(target=HOUR|MINUTE)    Returns a 2 element tuple, containing
                                       the sizes of the hours and the minutes
                                       hands, respectively.

    GetHandSize(target=ALL)            Returns a 3 element tuple, containing
         or                            the sizes of the hours, minutes and
    GetHandSize()                      seconds hands, respectively.

About:

Most of the ideas and part of the code of AnalogClock were based on the
original wxPython's AnalogClock module, which was created by several folks on
the wxPython-users list.

AnalogClock is distributed under the wxWidgets license.

This code should meet the wxPython Coding Guidelines
<http://www.wxpython.org/codeguidelines.php> and the wxPython Style Guide
<http://wiki.wxpython.org/index.cgi/wxPython_20Style_20Guide>.

For all kind of problems, requests, enhancements, bug reports, etc,
please drop me an e-mail.

For updates please visit <http://j.domaindlx.com/elements28/wxpython/>.

ButtonTreeCtrlPanel is a widget where one can place check buttons, tri-state
check buttons, radio buttons, both, and the ability to display them
hierarchically.

About:

ButtonTreeCtrlPanel is distributed under the wxWidgets license.

# Name:         buttontreectrlpanel.py
# Purpose:
#
# Author:       E. A. Tacao <e.a.tacao |at| estadao.com.br>
#
# Created:
# Version:      0.03
# Date:         12 Fev 2006, 22:00 GMT-03:00
# Licence:
# Tags:         phoenix-port

PyEvent(id=0, eventType=wxEVT_NULL)

:class:`PyEvent` can be used as a base class for implementing custom
event types in Python. You should derive from this class instead
of :class:`Event` because this class is Python-aware and is able to
transport its Python bits safely through the wxWidgets event
system and have them still be there when the event handler is
invoked. Note that since :class:`PyEvent` is taking care of preserving
the extra attributes that have been set then you do not need to
override the Clone method in your derived classes.

:see: :class:`PyCommandEvent`

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.WANTS_CHARS)

AddItem(self, label, bmp=None, parent=None, style=None, value=False)

Generates a new `(event, binder)` tuple.

::

    MooEvent, EVT_MOO = NewEvent()

# AnalogClock's font selector for setup dialog
#   E. A. Tacao <e.a.tacao |at| estadao.com.br>
#   http://j.domaindlx.com/elements28/wxpython/
#   15 Fev 2006, 22:00 GMT-03:00
# Distributed under the wxWidgets license.
# Tags:     phoenix-port

# AnalogClock's main class
#
# For more info please see the __init__.py file.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, name="AnalogClock", clockStyle=DEFAULT_CLOCK_STYLE, minutesStyle=TICKS_CIRCLE, hoursStyle=TICKS_POLY)

DoGetBestSize() -> Size

Implementation of GetBestSize() that can be overridden.

Gets fonts for tick marks when using TICKS_DECIMAL or
TICKS_ROMAN style.

Gets lists of points to be used as polygon shapes
when using the TICKS_POLY style.

Forces an immediate recalculation and redraw of all clock
elements.

Set the clock style, according to the options below.

Overridden base wx.Window method. This method sets a colour for
all hands and ticks at once.

Sets fonts for tick marks when using text-based tick styles
such as TICKS_DECIMAL or TICKS_ROMAN.

Sets lists of points to be used as polygon shapes

Set the tick style, according to the options below.

A simple derived class that provides some backwards compatibility
with the old analogclock module.

self.border (wx.Colour)  border colour
self.width  (int)        border width
self.fill   (wx.Colour)  fill colour
self.shadow (wx.Colour)  shadow colour

# AnalogClock's base classes

__init__(self, idx=0, pos=None, size=None, offset=0, clocksize=None, scale=1, rotate=False, kind="")

{64: <class 'wx.lib.analogclock.helpers.TickBinary'>, 4: <class 'wx.lib.analogclock.helpers.TickCircle'>, 16: <class 'wx.lib.analogclock.helpers.TickDecimal'>, 128: <class 'wx.lib.analogclock.helpers.TickHex'>, 1: <class 'wx.lib.analogclock.helpers.TickNone'>, 8: <class 'wx.lib.analogclock.helpers.TickPoly'>, 32: <class 'wx.lib.analogclock.helpers.TickRoman'>, 2: <class 'wx.lib.analogclock.helpers.TickSquare'>}

# AnalogClock setup dialog

['wx.SIMPLE_BORDER', 'wx.DOUBLE_BORDER', 'wx.SUNKEN_BORDER', 'wx.RAISED_BORDER', 'wx.STATIC_BORDER', 'wx.NO_BORDER']

# AnalogClock constants

Currently provides some flag icons based on:
http://www.famfamfam.com/lab/icons/flags

See: http://www.famfamfam.com/lab/icons/flags

FamFamFam Flag icons are available free for any purpose
Copyright Mark James (mjames@gmail.com)

This module is (c) 2006 Riaan Booysen and licensed under the Python license.

{'AE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26858e110>, 'AF': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e090>, 'AL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e110>, 'AM': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e190>, 'AR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e250>, 'AT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e290>, 'AU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e310>, 'AZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e390>, 'BE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e210>, 'BG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e3d0>, 'BH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e410>, 'BI': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e490>, 'BLANK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e510>, 'BN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e590>, 'BO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e610>, 'BR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e690>, 'BT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e710>, 'BW': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e790>, 'BY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e810>, 'BZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e890>, 'CA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e910>, 'CB': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828e990>, 'CD': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ea10>, 'CF': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ea90>, 'CH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828eb10>, 'CL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828eb90>, 'CN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ebd0>, 'CO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ec10>, 'CR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ec90>, 'CZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ed10>, 'DE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ed90>, 'DK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ee10>, 'DO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ee50>, 'DZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ee90>, 'EC': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ef10>, 'EE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ef90>, 'EG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f050>, 'ES': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f0d0>, 'ESPERANTO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f110>, 'ET': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f150>, 'FI': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f190>, 'FJ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f1d0>, 'FO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f250>, 'FR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f290>, 'GB': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f2d0>, 'GE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f350>, 'GH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f3d0>, 'GL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f450>, 'GR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f4d0>, 'GT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f550>, 'HK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f5d0>, 'HN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f650>, 'HR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f6d0>, 'HU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f750>, 'ID': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f7d0>, 'IE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f850>, 'IL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f8d0>, 'IN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f950>, 'IQ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f990>, 'IR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828f9d0>, 'IS': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fa50>, 'IT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fa90>, 'JM': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fad0>, 'JO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fb10>, 'JP': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fb50>, 'KE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fbd0>, 'KG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fc10>, 'KH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fc50>, 'KR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fcd0>, 'KW': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fd50>, 'KZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fdd0>, 'LA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fe50>, 'LB': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828fed0>, 'LI': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ff50>, 'LT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe26828ffd0>, 'LU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291090>, 'LV': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291110>, 'LY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291190>, 'MA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291210>, 'MC': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291290>, 'MD': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291310>, 'MG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291390>, 'MK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291410>, 'MM': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291450>, 'MN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291490>, 'MO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe2682914d0>, 'MT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291510>, 'MX': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291590>, 'MY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291610>, 'MZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291690>, 'NG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291710>, 'NI': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291750>, 'NL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291790>, 'NO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe2682917d0>, 'NP': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291810>, 'NR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291890>, 'NZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291910>, 'OM': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291990>, 'PA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291a10>, 'PE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291a90>, 'PH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291b10>, 'PK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291b90>, 'PL': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291c10>, 'PR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291c90>, 'PT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291d10>, 'PY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291d90>, 'QA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291e10>, 'RO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291e50>, 'RS': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291e90>, 'RU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291f10>, 'RW': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291f50>, 'SA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268291f90>, 'SB': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe2686819d0>, 'SD': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681950>, 'SE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681990>, 'SG': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681ad0>, 'SI': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681b10>, 'SK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681b50>, 'SN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681b90>, 'SV': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681bd0>, 'SY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681c10>, 'SZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681c50>, 'TH': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681c90>, 'TJ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681cd0>, 'TM': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681d10>, 'TN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681d50>, 'TO': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681d90>, 'TR': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681dd0>, 'TT': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681e10>, 'TW': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681e50>, 'UA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681e90>, 'US': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681ed0>, 'UY': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681f10>, 'UZ': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681f50>, 'VA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681f90>, 'VE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268681fd0>, 'VN': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516590>, 'VOLAPUK': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516650>, 'VU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe2685166d0>, 'WS': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516710>, 'YE': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516750>, 'YU': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516790>, 'ZA': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe2685167d0>, 'ZW': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe268516810>}

['AE', 'AF', 'AL', 'AM', 'AR', 'AT', 'AU', 'AZ', 'BE', 'BG', 'BH', 'BI', 'BLANK', 'BN', 'BO', 'BR', 'BT', 'BW', 'BY', 'BZ', 'CA', 'CB', 'CD', 'CF', 'CH', 'CL', 'CN', 'CO', 'CR', 'CZ', 'DE', 'DK', 'DO', 'DZ', 'EC', 'EE', 'EG', 'ES', 'ESPERANTO', 'ET', 'FI', 'FJ', 'FO', 'FR', 'GB', 'GE', 'GH', 'GL', 'GR', 'GT', 'HK', 'HN', 'HR', 'HU', 'ID', 'IE', 'IL', 'IN', 'IQ', 'IR', 'IS', 'IT', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KR', 'KW', 'KZ', 'LA', 'LB', 'LI', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'MG', 'MK', 'MM', 'MN', 'MO', 'MT', 'MX', 'MY', 'MZ', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NZ', 'OM', 'PA', 'PE', 'PH', 'PK', 'PL', 'PR', 'PT', 'PY', 'QA', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SD', 'SE', 'SG', 'SI', 'SK', 'SN', 'SV', 'SY', 'SZ', 'TH', 'TJ', 'TM', 'TN', 'TO', 'TR', 'TT', 'TW', 'UA', 'US', 'UY', 'UZ', 'VA', 'VE', 'VN', 'VOLAPUK', 'VU', 'WS', 'YE', 'YU', 'ZA', 'ZW']

ArtProvider class that publishes images from modules generated by img2py.

Image modules must be generated with the -u and -n <name> parameters.

Typical usage::
    >>> import wx, wx.lib.art.img2pyartprov, myimagemodule
    >>> wx.ArtProvider.PushProvider(wx.lib.art.img2pyartprov.Img2PyArtProvider(myimagemodule))

If myimagemodule.catalog['MYIMAGE'] is defined, it can be accessed as::
    >>> wx.ArtProvider.GetBitmap('wxART_MYIMAGE')

#-----------------------------------------------------------------------------
# Name:        img2pyartprov.py
# Purpose:
#
# Author:      Riaan Booysen
#
# Copyright:   (c) 2006
# Licence:     wxPython

wxArtProvider class is used to customize the look of wxWidgets
application.

CreateBitmap(id, client, size) -> Bitmap

Derived art provider classes may override this method to create
requested art resource.

Bitmap()
Bitmap(bitmap)
Bitmap(bits, width, height, depth=1)
Bitmap(width, height, depth=BITMAP_SCREEN_DEPTH)
Bitmap(sz, depth=BITMAP_SCREEN_DEPTH)
Bitmap(width, height, dc)
Bitmap(name, type=BITMAP_TYPE_ANY)
Bitmap(img, depth=BITMAP_SCREEN_DEPTH)
Bitmap(img, dc)
Bitmap(listOfBytes)

This class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour or colour with alpha channel support.

PyColourChooser
Copyright (C) 2002 Michael Gilfix <mgilfix@eecs.tufts.edu>

This file is part of PyColourChooser.

This version of PyColourChooser is open source; you can redistribute it
and/or modify it under the licensed terms.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

A screen buffer class.

This class implements a screen output buffer. Data is meant to
be drawn in the buffer class and then blitted directly to the
output device, or on-screen window.

A canvas class for arbitrary drawing.

The Canvas class implements a window that allows for drawing
arbitrary graphics. It implements a double buffer scheme and
blits the off-screen buffer to the window during paint calls
by the windowing system for speed.

Some other methods for determining the canvas colour and size
are also provided.

Creates a canvas instance and initializes the off-screen
buffer. Also sets the handler for rendering the canvas
automatically via size and paint calls from the windowing
system.

__init__(self, parent, id, pos=wx.DefaultPosition, style=wx.SIMPLE_BORDER, forceClientSize=None)

Actual drawing function for drawing into the off-screen
buffer. To be overrideen in the implementing class. Do nothing
by default.

Returns a tuple that contains the coordinates of the
top-left and bottom-right corners of the canvas.

Perform actual redraw to off-screen buffer only when the
size of the canvas has changed. This saves a lot of computation
since the same image can be re-used, provided the canvas size
hasn't changed.

A Colour Selection Box

The Colour selection box implements button like behavior but contains
a solid-filled, coloured sub-box. Placing the colour in a sub-box allows
for filling in the main panel's background for a high-lighting effect.

Creates a new colour box instance and initializes the colour
content.

Returns a reference to the internal box object containing the
color. This function is useful for setting up event handlers for
the box.

Update()

Calling this method immediately repaints the invalidated area of the
window and all of its children recursively (this normally only happens
when the flow of control returns to the event loop).

Adds GetColour()/GetValue() for compatibility with ColourPickerCtrl and colourselect

A Pure-Python implementation of the colour chooser dialog.

The PyColourChooser is a pure python implementation of the colour
chooser dialog. It's useful for embedding the colour choosing functionality
inside other widgets, when the pop-up dialog is undesirable. It can also
be used as a drop-in replacement on the GTK platform, as the native
dialog is kind of ugly.

Creates an instance of the colour chooser. Note that it is best to
accept the given size of the colour chooser as it is currently not
resizeable.

Updates the colour values based on the mouse location
over the palette.

Calculate current colour from HS box position and V slider.
return - wx.Colour

Adds a custom colour to the custom colour box set. Boxes are
chosen in a round-robin fashion, eventually overwriting previously
added colours.

Highlights the selected colour box and updates the solid colour
display and colour slider to reflect the choice.

Highlights the selected custom colour box and updates the solid
colour display and colour slider to reflect the choice.

Stores state that the mouse has been pressed and updates
the selected colour values.

Updates the colour values during mouse motion while the
mouse button is depressed.

Sets the custom colour at the given index. true_colour is wxColour
object containing the actual rgb value of the custom colour.
base_colour (wxColour) and slidepos (int) are used to configure the
colour slider and set everything to its original position.

setCustomColour (self, index, true_colour, base_colour, slidepos)

Set a new HSV value for the v slider. Does not update displayed colour.

Update the displayed color box (solid) and send the EVT_COLOUR_CHANGED

['ORANGE', 'GOLDENROD', 'WHEAT', 'SPRING GREEN', 'SKY BLUE', 'SLATE BLUE', 'MEDIUM VIOLET RED', 'PURPLE', 'RED', 'YELLOW', 'MEDIUM SPRING GREEN', 'PALE GREEN', 'CYAN', 'LIGHT STEEL BLUE', 'ORCHID', 'LIGHT MAGENTA', 'BROWN', 'YELLOW', 'GREEN', 'CADET BLUE', 'MEDIUM BLUE', 'MAGENTA', 'MAROON', 'ORANGE RED', 'FIREBRICK', 'CORAL', 'FOREST GREEN', 'AQUAMARINE', 'BLUE', 'NAVY', 'THISTLE', 'MEDIUM VIOLET RED', 'INDIAN RED', 'GOLD', 'MEDIUM SEA GREEN', 'MEDIUM BLUE', 'MIDNIGHT BLUE', 'GREY', 'PURPLE', 'KHAKI', 'BLACK', 'MEDIUM FOREST GREEN', 'KHAKI', 'DARK GREY', 'SEA GREEN', 'LIGHT GREY', 'MEDIUM SLATE BLUE', 'WHITE']

[(wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0), (wx.Colour(-1, -1, -1, 255), 86.0)]

WindowIDRef()
WindowIDRef(id)
WindowIDRef(idref)

A wxWindowIDRef object wraps an ID value and marks it as being in-use
until all references to that ID are gone.

Copyright (C) 2002 Michael Gilfix

You should have received a file COPYING containing license terms
along with this program; if not, write to Michael Gilfix
(mgilfix@eecs.tufts.edu) for a copy.

This version of PyColourChooser is open source; you can redistribute it and/or
modify it under the terms listed in the file COPYING.

A Pure-Python Colour Slider

The colour slider displays transitions from value 0 to value 1 in
HSV, allowing the user to select a colour within the transition
spectrum.

This class is best accompanying by a wxSlider that allows the user
to select a particular colour shade.

Creates a blank slider instance. A colour must be set before the
slider will be filled in.

Actual implementation of the widget's drawing. We simply draw
from value 0.0 to value 1.0 in HSV.

Return the current colour used as a colour base for filling out
the slider.

Returns the HSV value "V" based on the location of a mouse click at y offset "pos"

Sets the base, or target colour, to use as the central colour
when calculating colour transitions.

The Pure-Python Palette

The PyPalette is a pure python implementation of a colour palette. The
palette implementation here imitates the palette layout used by MS
Windows and Adobe Photoshop.

The actual palette image has been embedded as an XPM for speed. The
actual reverse-engineered drawing algorithm is provided in the
GeneratePaletteBMP() method. The algorithm is tweakable by supplying
the granularity factor to improve speed at the cost of display
beauty. Since the generator isn't used in real time, no one will
likely care :) But if you need it for some sort of unforeseen realtime
application, it's there.

Overridden to create a client window that exactly fits our bitmap

The actual palette drawing algorithm.

This used to be 100% reverse engineered by looking at the
values on the MS map, but has since been redone Correctly(tm)
according to the HSV (hue, saturation, value) colour model by
Charl P. Botha <http://cpbotha.net/>.

Speed is tweakable by changing the granularity factor, but
that affects how nice the output looks (makes the vertical
blocks bigger. This method was used to generate the embedded
XPM data.

Returns a colour value at a specific x, y coordinate pair. This
is useful for determining the colour found a specific mouse click
in an external event handler.

Highlights an area of the palette with a little circle around
the coordinate point

#----------------------------------------------------------------------
# Name:        wx.lib.editor
# Purpose:     A package containing a colourizable text editor
#
# Author:      Robin Dunn
#
# Created:     30-Dec-1999
# Copyright:   (c) 1999-2020 by Total Control Software
# Licence:     wxWindows license
# 12/14/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o 2.5 compatibility update.
#
# 12/21/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o wxEditor -> Editor
#

# Name:        wx.lib.editor.Editor
# Purpose:     An intelligent text editor with colorization capabilities.
#
# Original
# Authors:      Dirk Holtwic, Robin Dunn
#
# New
# Authors:      Adam Feuer, Steve Howell
#
# History:
#   This code used to support a fairly complex subclass that did
#   syntax coloring and outliner collapse mode.  Adam and Steve
#   inherited the code, and added a lot of basic editor
#   functionality that had not been there before, such as cut-and-paste.
#
#
# Created:     15-Dec-1999
# Copyright:   (c) 1999-2016 by Dirk Holtwick, 1999
#
#
#
#

ScrolledWindow()
ScrolledWindow(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=ScrolledWindowStyle, name=PanelNameStr)

Scrolled window derived from wxPanel.

__init__(self, parent, id, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0)

CanScroll(orient) -> bool

Returns true if this window can have a scroll bar in this orientation.

Move(x, y, flags=SIZE_USE_EXISTING)
Move(pt, flags=SIZE_USE_EXISTING)

Moves the window to the given position.

#
#

This is the floatcanvas package, the main classes are
:class:`~lib.floatcanvas.FloatCanvas` and
:class:`~lib.floatcanvas.NavCanvas`, in each class documentation there
is at least one sample on how to use them and many more samples are provided
in `wxPhoenix/samples` folder.

FloatCanvas.py contains the main :class:`~lib.floatcanvas.FloatCanvas`
class, and its supporting classes.  NavCanvas.py contains the
:class:`~lib.floatcanvas.NavCanvas` wrapper for the FloatCanvas that
provides the canvas and a toolbar with tools that allow you to navigate
the canvas (zooming, panning, etc.)  Resources.py is a module that
contains a few resources required by the FloatCanvas (icons, etc)

The FloatCanvas is a high level window for drawing maps and anything
else in an arbitrary coordinate system.

The goal is to provide a convenient way to draw stuff on the screen
without having to deal with handling OnPaint events, converting to pixel
coordinates, knowing about wxWindows brushes, pens, and colors, etc. It
also provides virtually unlimited zooming and scrolling

I am using it for two things:

1) general purpose drawing in floating point coordinates
2) displaying map data in Lat-long coordinates

If the projection is set to None, it will draw in general purpose
floating point coordinates. If the projection is set to 'FlatEarth', it
will draw a FlatEarth projection, centered on the part of the map that
you are viewing. You can also pass in your own projection function.

It is double buffered, so re-draws after the window is uncovered by
something else are very quick.

It relies on `NumPy <http://www.numpy.org/>`_, which is needed for speed
(maybe, I haven't profiled properly) and convenience.

Bugs and Limitations: Lots: patches, fixes welcome

For Map drawing: It ignores the fact that the world is, in fact, a
sphere, so it will do strange things if you are looking at stuff near
the poles or the date line. so far I don't have a need to do that, so I
haven't bothered to add any checks for that yet.

Zooming: I have set no zoom limits. What this means is that if you zoom
in really far, you can get integer overflows, and get weird results. It
doesn't seem to actually cause any problems other than weird output, at
least when I have run it.

Speed: I have done a couple of things to improve speed in this app. The
one thing I have done is used `NumPy <http://www.numpy.org/>`_ Arrays to
store the coordinates of the points of the objects. This allowed me to use
array oriented functions when doing transformations, and should provide some
speed improvement for objects with a lot of points (big polygons, polylines,
pointsets).

The real slowdown comes when you have to draw a lot of objects, because
you have to call the wx.DC.DrawSomething call each time. This is plenty
fast for tens of objects, OK for hundreds of objects, but pretty darn
slow for thousands of objects.

If you are zoomed in, it checks the Bounding box of an object before
drawing it. This makes it a great deal faster when there are a lot of
objects and you are zoomed in so that only a few are shown.

Mouse Events:

There are a full set of custom mouse events. They are just like the
regular mouse events, but include an extra attribute: Event.GetCoords(),
that returns the (x,y) position in world coordinates, as a length-2
`NumPy <http://www.numpy.org/>`_ vector of Floats.

There are also a full set of bindings to mouse events on objects, so
that you can specify a given function be called when an object is
clicked, mouse-over'd, etc.

See the Demo for what it can do, and how to use it.

Copyright: Christopher Barker

TRAC site for some docs and updates:

http://trac.paulmcnett.com/floatcanvas

http://mail.paulmcnett.com/cgi-bin/mailman/listinfo/floatcanvas

The latest code is in the main wx SVN:

For classic:

http://svn.wxwidgets.org/viewvc/wx/wxPython/3rdParty/FloatCanvas/

For Phoenix:

http://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk/wx/lib/floatcanvas

Check for updates or answers to questions, send me an email.
Please let me know if you're using this!!!

Contact me at:

Chris.Barker@noaa.gov

# Name:         __init__.py
# Purpose:      The FloatCanvas package
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

A Bounding Box object and assorted utilities , subclassed from a numpy array

# Name:         BBox.py
# Purpose:
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

A Bounding Box object:

Takes Data as an array. Data is any python sequence that can be turned into a
2x2 numpy array of floats::

    [
    [MinX, MinY ],
    [MaxX, MaxY ]
    ]

It is a subclass of numpy.ndarray, so for the most part it can be used as
an array, and arrays that fit the above description can be used in its place.

Usually created by the factory functions:

    asBBox

    and

    fromPoints

Inside(BB):

Tests if the given Bounding Box is entirely inside this one.

Returns True if it is entirely inside, or touching the
border.

Returns False otherwise

Joins this bounding box with the one passed in, maybe making this one bigger

Overlap(BB):

Tests if the given Bounding Box overlaps with this one.
Returns True is the Bounding boxes overlap, False otherwise
If they are just touching, returns True

Tests if the given Point is entirely inside this one.

border.

Point is any length-2 sequence (tuple, list, array) or two numbers

subclass of a BBox that can be used for a rotated Rectangle

contributed by MArco Oster (marco.oster@bioquant.uni-heidelberg.de)

assume edgepoints are ordered such you can walk along all edges with left rotation sense
This may be:
left-top
left-bottom
right-bottom
right-top

or any rotation.

returns a BBox object.

If object is a BBox, it is returned unaltered

If object is a numpy array, a BBox object is returned that shares a
view of the data with that array. The numpy array should be of the correct
format: a 2x2 numpy array of floats::

    [
    ]

Builds a BBox object from an array of Bounding Boxes.
The resulting Bounding Box encompases all the included BBs.

The BBarray is in the shape: (Nx2x2) where BBarray[n] is a 2x2 array that represents a BBox

fromPoints (Points).

reruns the bounding box of the set of points in Points. Points can
be any python object that can be turned into a numpy NX2 array of Floats.

If a single point is passed in, a zero-size Bounding Box is returned.

Returns a BBox object with all NaN entries.

This represents a Null BB box;

BB merged with it will return BB.

Nothing is inside it.

Colors.py

Assorted stuff for Colors support. At the moment, only a few color sets.

Many of these are from:
http://geography.uoregon.edu/datagraphics/color_scales.htm

They may have been modified some

CategoricalColor1: A list of colors that are distict.
BlueToRed11: 11 colors from blue to red

# Name:         Colors.py
# Purpose:      Contains color lists used in FloatCanvas
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

Part of the floatcanvas.Utilities package.

This module contains assorted GUI-related utilities that can be used
with FloatCanvas

So far, they are:

RubberBandBox: used to draw a RubberBand Box on the screen

# Name:         GUI.py
# Purpose:      Contains GUI related utilities for FloatCanvas
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

Class to provide a GUI Mode that makes a rubber band box that can be drawn on a Window

:param `CallBack`: is the method you want called when the mouse is
          released. That method will be called, passing in a rect
          parameter, where rect is: (Point, WH) of the rect in
          world coords.
:param `Tol`: The tolerance for the smallest rectangle allowed. defaults
          to 5. In pixels

# Name:         FCEvents.py
# Purpose:      A convenient place to put all event types and binders for
#               FloatCanvas, and to help avoid circular imports.
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

# Name:         FCObjects.py
# Purpose:      Contains all the drawing objects FloatCanvas supports
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

Draws an arc of a circle, centered on point ``CenterXY``, from
the first point ``StartXY`` to the second ``EndXY``.

The arc is drawn in an anticlockwise direction from the start point to
the end point.

:param `StartXY`: start point, takes a 2-tuple, or a (2,)
 `NumPy <http://www.numpy.org/>`_ array of point coordinates
:param `EndXY`: end point, takes a 2-tuple, or a (2,)
:param `CenterXY`: center point, takes a 2-tuple, or a (2,)
:param `LineColor`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetColor`
:param `LineStyle`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetLineStyle`
:param `LineWidth`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetLineWidth`
:param `FillColor`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetColor`
:param `FillStyle`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetFillStyle`
:param boolean `InForeground`: should object be in foreground

__init__(self, StartXY, EndXY, CenterXY, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, FillColor    = None, FillStyle    = "Solid", InForeground = False)

Move the object by delta

:param `Delta`: delta is a (dx, dy) pair. Ideally a `NumPy <http://www.numpy.org/>`_
 array of shape (2,)

Draws an arrow

It will draw an arrow , starting at the point ``XY`` points at an angle
defined by ``Direction``.

:param `XY`: the (x, y) coordinate of the starting point, or a 2-tuple,
 or a (2,) `NumPy <http://www.numpy.org/>`_ array
:param integer `Length`: length of arrow in pixels
:param integer `Direction`: angle of arrow in degrees, zero is straight
  up `+` angle is to the right
:param `ArrowHeadSize`: size of arrow head in pixels
:param `ArrowHeadAngle`: angle of arrow head in degrees

__init__(self, XY, Length, Direction, LineColor = "Black", LineStyle = "Solid", LineWidth    = 2, ArrowHeadSize = 8, ArrowHeadAngle = 30, InForeground = False)

Set the direction

Set the length

Set the length and direction

Draws an arrow line.

It will draw a set of arrows from point to point.

It takes a list of 2-tuples, or a NX2 NumPy Float array of point coordinates.

:param `Points`: takes a 2-tuple, or a (2,)

__init__(self, Points, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, ArrowHeadSize = 8, ArrowHeadAngle = 30, InForeground = False)

Draws a bitmap

The size is fixed, and does not scale with the drawing.

:param wx.Bitmap `Bitmap`: the bitmap to be drawn
:param `XY`: the (x, y) coordinate of the corner of the bitmap, or a 2-tuple,
:param string `Position`: a two character string indicating where in relation to the coordinates
 the bitmap should be oriented

 ============== ==========================
 1st character  Meaning
 ``t``          top
 ``c``          center
 ``b``          bottom

 2nd character  Meaning
 ``l``          left
 ``r``          right

:param `XY`: the (x, y) coordinate of the center of the circle, or a 2-tuple,
:param integer `Diameter`: the diameter for the object

__init__(self, XY, Diameter, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, FillColor    = None, FillStyle    = "Solid", InForeground = False)

Set the diameter of the object

Mixin class for objects that have just one color, rather than a fill
color and line color

Set the Color

:param `Color`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetColor`
 for valid values

An example of a Grid Object -- it is set on the FloatCanvas with one of::

    FloatCanvas.GridUnder = Grid
    FloatCanvas.GridOver = Grid

It will be drawn every time, regardless of the viewport.

In its _Draw method, it computes what to draw, given the ViewPortBB
of the Canvas it's being drawn on.

__init__(self, Spacing, Size = 2, Color = "Black", Cross=False, CrossThickness = 1)

This is the base class for all the objects that can be drawn.

One must subclass from this (and an assortment of Mixins) to create
a new DrawObject, see for example :class:`~lib.floatcanvas.FloatCanvas.Circle`.

:param boolean `InForeground`: Define if object should be in foreground
 or not
:param boolean `IsVisible`: Define if object should be visible

Bind an event to the DrawObject

:param `Event`: see below for supported event types

 - EVT_FC_LEFT_DOWN
 - EVT_FC_LEFT_UP
 - EVT_FC_LEFT_DCLICK
 - EVT_FC_MIDDLE_DOWN
 - EVT_FC_MIDDLE_UP
 - EVT_FC_MIDDLE_DCLICK
 - EVT_FC_RIGHT_DOWN
 - EVT_FC_RIGHT_UP
 - EVT_FC_RIGHT_DCLICK
 - EVT_FC_ENTER_OBJECT
 - EVT_FC_LEAVE_OBJECT

:param `CallBackFun`: the call back function for the event

Set the brush for this DrawObject

 for valid entries

Set the Color - this method is overridden in the subclasses

:param `Color`: use one of the following values any valid entry from
 :class:`wx.ColourDatabase`

 - ``Green``
 - ``White``
 - ``Black``
 - ``Grey``
 - ``MediumGrey``
 - ``LightGrey``
 - ``Cyan``
 - ``Red``

Set the FillColor - this method is overridden in the subclasses

Set the FillStyle - this method is overridden in the subclasses

:param string `FillStyle`: following is a list of valid values:

  ===================== =========================================
  Style                 Description
  ``Transparent``       Transparent fill
  ``Solid``             Solid fill
  ``BiDiagonalHatch``   Bi Diagonal hatch fill
  ``CrossDiagHatch``    Cross Diagonal hatch fill
  ``FDiagonal_Hatch``   F Diagonal hatch fill
  ``CrossHatch``        Cross hatch fill
  ``HorizontalHatch``   Horizontal hatch fill
  ``VerticalHatch``     Vertical hatch fill

Set the brush used for hit test, do not call directly.

:param `HitColor`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetColor`

Set the pen used for hit test, do not call directly.

:param integer `LineWidth`: the line width in pixels

Set the LineColor - this method is overridden in the subclasses

Set the LineStyle - this method is overridden in the subclasses

:param `LineStyle`: Use one of the following values or ``None`` :

  ===================== =============================
  ``Solid``             Solid line
  ``Transparent``       A transparent line
  ``Dot``               Dotted line
  ``LongDash``          Dashed line (long)
  ``ShortDash``         Dashed line (short)
  ``DotDash``           Dash-dot-dash line

Set the LineWidth

:param integer `LineWidth`: sets the line width in pixel

Set the Pen for this DrawObject

:param integer `LineWidth`: the width in pixels

Unbind all events

.. note:: Currently only removes one from each list

{(None, 'Transparent'): <wx._core.Brush object at 0x7fe27a65d370>, ('Blue', 'Solid'): <wx._core.Brush object at 0x7fe27a658e10>, ('Green', 'Solid'): <wx._core.Brush object at 0x7fe27a658eb0>, ('White', 'Solid'): <wx._core.Brush object at 0x7fe27a65d050>, ('Black', 'Solid'): <wx._core.Brush object at 0x7fe27a65d0f0>, ('Grey', 'Solid'): <wx._core.Brush object at 0x7fe27a65d190>, ('MediumGrey', 'Solid'): <wx._core.Brush object at 0x7fe27a65d230>, ('LightGrey', 'Solid'): <wx._core.Brush object at 0x7fe27a65d2d0>, ('Cyan', 'Solid'): <wx._core.Brush object at 0x7fe27a65d410>, ('Red', 'Solid'): <wx._core.Brush object at 0x7fe27a65d4b0>}

{'Transparent': 106, 'Solid': 100, 'BiDiagonalHatch': 111, 'CrossDiagHatch': 112, 'FDiagonal_Hatch': 113, 'CrossHatch': 114, 'HorizontalHatch': 115, 'VerticalHatch': 116}

{'Solid': 100, 'Transparent': 106, 'Dot': 101, 'LongDash': 102, 'ShortDash': 103, 'DotDash': 104}

{(None, 'Transparent', 1): <wx._core.Pen object at 0x7fe27a658af0>, ('Green', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658730>, ('White', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658a50>, ('Black', 'Solid', 1): <wx._core.Pen object at 0x7fe27a6589b0>, ('Grey', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658c30>, ('MediumGrey', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658cd0>, ('LightGrey', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658d70>, ('Cyan', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658690>, ('Red', 'Solid', 1): <wx._core.Pen object at 0x7fe27a658550>}

Draws an ellipse see :class:`~lib.floatcanvas.FloatCanvas.RectEllipse`

A group of other FloatCanvas Objects

Not all DrawObject methods may apply here.

Note that if an object is in more than one group, it will get drawn more than once.

:param list `ObjectList`: a list of :class:`DrawObject` to be grouped
:param boolean `InForeground`: keep in foreground
:param boolean `IsVisible`: keep it visible

__init__(self, ObjectList=[], InForeground=False, IsVisible=True)

Add an object to the group.

:param DrawObject `obj`: object to add

Add objects to the group.

:param list `Objects`: a list of :class:`DrawObject` to be grouped

Bind an event to the Group object

Moves the object by delta, where delta is a (dx, dy) pair.

:param `Delta`: is a (dx, dy) pair ideally a `NumPy <http://www.numpy.org/>`_
 array of shape (2, )

Set the FillColor

Set the FillStyle

Set the LineColor

Set the LineStyle

:param integer `LineWidth`: line width in pixels

Draws a line

It will draw a straight line if there are two points, and a polyline
if there are more than two.

__init__(self, Points, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, InForeground = False)

Mixin class for objects that have both a line and a fill color and
style.

Setup for draw

:param `dc`: the dc to draw ???
:param `WorldToPixel`: ???
:param `ScaleWorldToPixel`: ???
:param `HTdc`: ???

Mixin class for objects that have just a line, rather than a fill

This is DrawObject for a pie chart

You can pass in a bunch of values, and it will draw a pie chart for
you, and it will make the chart, scaling the size of each "slice" to
match your values.

:param `XY`: The (x,y) coords of the center of the chart
:param `Diameter`: The diamter of the chart in world coords, unless you
         set "Scaled" to False, in which case it's in pixel coords.
:param `Values`: sequence of values you want to make the chart of.
:param `FillColors`: sequence of colors you want the slices. If
         None, it will choose (no guarantee you'll like them!)
:param `FillStyles`: Fill style you want ("Solid", "Hash", etc)
:param `LineColor`: Color of lines separating the slices
:param `LineStyle`: style of lines separating the slices
:param `LineWidth`: With of lines separating the slices
:param `Scaled`: Do you want the pie to scale when zooming?
         or stay the same size in pixels?
:param `InForeground`: Should it be on the foreground?

__init__(self, XY, Diameter, Values, FillColors=None, FillStyles=None, LineColor = None, LineStyle = "Solid", LineWidth    = 1, Scaled = True, InForeground = False)

Set the FillColors and update the Brushes.

:param `FillColors`: sequence of colors

Set te FillStyles and update the Brushes.

Set the values and calculate the points.

:param `Values`: sequence of values you want to use for the chart

A point DrawObject

.. note::

   The Bounding box is just the point, and doesn't include the Diameter.

   The HitLineWidth is used as diameter for the Hit Test.

:param `XY`: the (x, y) coordinate of the center of the point, or a
 2-tuple, or a (2,) `NumPy <http://www.numpy.org/>`_ array
:param integer `Diameter`: in screen points
:param `InForeground`: define if object is in foreground

__init__(self, XY, Color="Black", Diameter=1, InForeground=False)

Set the diameter of the object.

Draws a set of points

If Points is a sequence of tuples: Points[N][0] is the x-coordinate of
point N and Points[N][1] is the y-coordinate.

If Points is a NumPy array: Points[N,0] is the x-coordinate of point
N and Points[N,1] is the y-coordinate for arrays.

Each point will be drawn the same color and Diameter. The Diameter
is in screen pixels, not world coordinates.

The hit-test code does not distinguish between the points, you will
only know that one of the points got hit, not which one. You can use
PointSet.FindClosestPoint(WorldPoint) to find out which one

In the case of points, the HitLineWidth is used as diameter.

:param integer `Diameter`: the points diameter

__init__(self, Points, Color="Black", Diameter=1, InForeground=False)

Returns the index of the closest point to the point, XY, given
in World coordinates. It's essentially random which you get if
there are more than one that are the same.

This can be used to figure out which point got hit in a mouse
binding callback, for instance. It's a lot faster that using a
lot of separate points.

:param `XY`: the (x,y) coordinates of the point to look for, it takes a
 2-tuple or (2,) numpy array in World coordinates

Sets the diameter

A mixin class that provides some methods suitable for use
with objects that have a set of (x, y) coordinate pairs.

Sets the coordinates of the points of the object to Points (NX2 array).

:param boolean `copy`: By default, a copy is made, if copy is set to
 ``False``, a reference is used, if Points is a NumPy array of Floats.
 This allows you to change some or all of the points without making
 any copies.

    Points = Object.Points
    # shifts the points 5 in the x dir, and 10 in the y dir.
    Points += (5, 10)
    # Sets the points to the same array as it was
    Object.SetPoints(Points, False)

Draws a polygon

Points is a list of 2-tuples, or a NX2 NumPy array of
point coordinates.  so that Points[N][0] is the x-coordinate of
point N and Points[N][1] is the y-coordinate or Points[N,0] is the
x-coordinate of point N and Points[N,1] is the y-coordinate for
arrays.

:param `Points`: start point, takes a 2-tuple, or a (2,)

__init__(self, Points, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, FillColor    = None, FillStyle    = "Solid", InForeground = False)

Draws a rectangle see :class:`~lib.floatcanvas.FloatCanvas.RectEllipse`

:param `XY`: the (x, y) coordinate of the corner of RectEllipse, or a 2-tuple,
:param `WH`: a tuple with the Width and Height for the object
:param `InForeground`: put object in foreground

__init__(self, XY, WH, LineColor = "Black", LineStyle = "Solid", LineWidth    = 1, FillColor    = None, FillStyle    = "Solid", InForeground = False)

Set the shape of the object.

:param `XY`: takes a 2-tuple, or a (2,) `NumPy <http://www.numpy.org/>`_
 array of point coordinates

:param `XY`: the (x, y) coordinate of the corner of the scaled bitmap,
 or a 2-tuple, or a (2,) `NumPy <http://www.numpy.org/>`_ array
:param `Height`: height to be used, width is calculated from the aspect ratio of the bitmap

 ``t``          top

 ``l``          left

__init__(self, Bitmap, XY, Height, Position = 'tl', InForeground = False)

Draws a scaled bitmap

An alternative scaled bitmap that only scaled the required amount of
the main bitmap when zoomed in: EXPERIMENTAL!

:param `Height`: height to be used
:param `Width`: width to be used, if ``None`` width is calculated from the aspect ratio of the bitmap

 ``t``          top

 ``l``          left

__init__(self, Bitmap, XY, Height, Width=None, Position = 'tl', InForeground = False)

##fixme: this can be deprecated and just use ScaledTextBox with different defaults.

This class creates a text object that is scaled when zoomed.  It is
placed at the coordinates, x,y. the "Position" argument is a two
character string, indicating where in relation to the coordinates
the string should be oriented.

The first letter is: t, c, or b, for top, center and bottom The
second letter is: l, c, or r, for left, center and right The
position refers to the position relative to the text itself. It
defaults to "tl" (top left).

Size is the size of the font in world coordinates.

* Family: Font family, a generic way of referring to fonts without
  specifying actual facename. One of:

        * wx.FONTFAMILY_DEFAULT:  Chooses a default font.
        * wx.FONTFAMILY_DECORATIVE: A decorative font.
        * wx.FONTFAMILY_ROMAN: A formal, serif font.
        * wx.FONTFAMILY_SCRIPT: A handwriting font.
        * wx.FONTFAMILY_SWISS: A sans-serif font.
        * wx.FONTFAMILY_MODERN: A fixed pitch font.

  .. note:: these are only as good as the wxWindows defaults, which aren't so good.

* Style: One of wx.FONTSTYLE_NORMAL, wx.FONTSTYLE_SLANT and wx.FONTSTYLE_ITALIC.
* Weight: One of wx.FONTWEIGHT_NORMAL, wx.FONTWEIGHT_LIGHT and wx.FONTWEIGHT_BOLD.
* Underlined: The value can be True or False. At present this may have an an
  effect on Windows only.

Alternatively, you can set the kw arg: Font, to a wx.Font, and the
above will be ignored. The size of the font you specify will be
ignored, but the rest of its attributes will be preserved.

The size will scale as the drawing is zoomed.

Bugs/Limitations:

As fonts are scaled, the do end up a little different, so you don't
get exactly the same picture as you scale up and done, but it's
pretty darn close.

On wxGTK1 on my Linux system, at least, using a font of over about
3000 pts. brings the system to a halt. It's the Font Server using
huge amounts of memory. My work around is to max the font size to
3000 points, so it won't scale past there. GTK2 uses smarter font
drawing, so that may not be an issue in future versions, so feel
free to test. Another smarter way to do it would be to set a global
zoom limit at that point.

The hit-test is done on the entire text extent. This could be made
optional, but I haven't gotten around to it.

__init__(self, String, XY, Size, Color = "Black", BackgroundColor = None, Family = wx.FONTFAMILY_MODERN, Style = wx.FONTSTYLE_NORMAL, Weight = wx.FONTWEIGHT_NORMAL, Underlined = False, Position = 'tl', Font = None, InForeground = False)

A dummy method to re-do the layout of the text.

A derived object needs to override this if required.

Draws a text object

The object is scaled when zoomed.

The hit-test is done on the entire text extent

As fonts are scaled, they do end up a little different, so you don't
get exactly the same picture as you scale up and down, but it's

1000 pts. brings the system to a halt. It's the Font Server using
1000 points, so it won't scale past there. GTK2 uses smarter font

:param `Point`: takes a 2-tuple, or a (2,) `NumPy <http://www.numpy.org/>`_
:param integer `Size`: size in World units
:param `BackgroundColor`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetColor`
:param `Width`: width in pixels or ``None``, text will be wrapped to
 the given width.
:param `PadSize`: padding in world units or ``None``, if specified it
 will creating a space (margin) around the text
:param wx.FontFamily `Family`: a valid :ref:`wx.FontFamily`
:param wx.FontStyle `Style`: a valid :ref:`wx.FontStyle`
:param wx.FontWeight `Weight`: a valid :ref:`wx.FontWeight`
:param boolean `Underlined`: underline the text
:param string `Position`: a two character string indicating where in
 relation to the coordinates the box should be oriented

 ``t``          top

 ``l``          left

:param `Alignment`: see :meth:`~lib.floatcanvas.FloatCanvas.DrawObject.SetLineWidth`
:param wx.Font `Font`: alternatively a valid :class:`wx.Font` can be defined
 in which case the above will be ignored
:param float `LineSpacing`: the line space to be used

__init__(self, String, Point, Size, Color = "Black", BackgroundColor = None, LineColor = 'Black', LineStyle = 'Solid', LineWidth = 1, Width = None, PadSize = None, Family = wx.FONTFAMILY_MODERN, Style = wx.FONTSTYLE_NORMAL, Weight = wx.FONTWEIGHT_NORMAL, Underlined = False, Position = 'tl', Alignment = "left", Font = None, LineSpacing = 1.0, InForeground = False)

Calculates the positions of the words of text.

This isn't exact, as fonts don't scale exactly.
To help this, the position of each individual word
is stored separately, so that the general layout stays
the same in world coordinates, as the fonts scale.

see :class:`~lib.floatcanvas.FloatCanvas.Line`

Draws a square point

The Size is in screen points, not world coordinates, so the
Bounding box is just the point, and doesn't include the Size.

The HitLineWidth is used as diameter for the  Hit Test.

:param `Point`: takes a 2-tuple, or a (2,)
:param integer `Size`: the size of the square point

__init__(self, Point, Color="Black", Size=4, InForeground=False)

Sets the size

:param string `string`: the text to draw
:param `XY`: the (x, y) coordinate of the corner of the text, or a 2-tuple,
:param `Size`: the font size
:param wx.Font `Font`: alternatively you can define :ref:`wx.Font` and the
 above will be ignored.

 ``t``          top

 ``l``          left

:param wx.Font `Font`: a valid :class:`wx.Font`

__init__(self, String, xy, Size =  14, Color = "Black", BackgroundColor = None, Family = wx.FONTFAMILY_MODERN, Style = wx.FONTSTYLE_NORMAL, Weight = wx.FONTWEIGHT_NORMAL, Underlined = False, Position = 'tl', InForeground = False, Font = None)

A mix in class that holds attributes and methods that are needed by
the Text objects

SetFont(self, Size, Family, Style, Weight, Underlined, FaceName)

Re-sets the text displayed by the object

In the case of the ScaledTextBox, it will re-do the layout as appropriate

Note: only tested with the ScaledTextBox

{'tl': <function TextObjectMixin.<lambda> at 0x7fe27a503e60>, 'tc': <function TextObjectMixin.<lambda> at 0x7fe27a503ef0>, 'tr': <function TextObjectMixin.<lambda> at 0x7fe27a503f80>, 'cl': <function TextObjectMixin.<lambda> at 0x7fe27a446050>, 'cc': <function TextObjectMixin.<lambda> at 0x7fe27a4460e0>, 'cr': <function TextObjectMixin.<lambda> at 0x7fe27a446170>, 'bl': <function TextObjectMixin.<lambda> at 0x7fe27a446200>, 'bc': <function TextObjectMixin.<lambda> at 0x7fe27a446290>, 'br': <function TextObjectMixin.<lambda> at 0x7fe27a446320>}

This is a mixin class that provides some methods suitable for use
with objects that have a single (x,y) coordinate pair.

Compute the font scale.

A global variable to hold the scaling from pixel size to point size.

This is the main module of the floatcanvas package, it contains the :class:`~lib.floatcanvas.FloatCanvas.FloatCanvas`
and all the all the different objects which are sub-classed from :class:`~lib.floatcanvas.FloatCanvas.DrawObject`.

In the following very simple sample ``self`` is a frame, but it could be another
container type control::

    from wx.lib.floatcanvas import FloatCanvas

    self.Canvas = FloatCanvas.FloatCanvas(self, -1,
                                 size=(500, 500),
                                 ProjectionFun=None,
                                 Debug=0,
                                 BackgroundColor="White",
                                 )

    # add a circle
    cir = FloatCanvas.Circle((10, 10), 100)
    self.Canvas.AddObject(cir)

    # add a rectangle
    rect = FloatCanvas.Rectangle((110, 10), (100, 100), FillColor='Red')
    self.Canvas.AddObject(rect)

    self.Canvas.Draw()

Many samples are available in the `wxPhoenix/samples/floatcanvas` folder.

# Name:         FloatCanvas.py
# Purpose:
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

This event class takes a regular wxWindows mouse event as a parameter,
and wraps it so that there is access to all the original methods. This
is similar to subclassing, but you can't subclass a wxWindows event

The goal is to be able to it just like a regular mouse event.

It adds the method:

GetCoords() , which returns an (x,y) tuple in world coordinates.

Another difference is that it is a CommandEvent, which propagates up
the window hierarchy until it is handled.

The main class of the floatcanvas package :class:`~lib.floatcanvas.FloatCanvas`.

:param `size`: a tuple or :class:`wx.Size`
:param `ProjectionFun`: This allows you to change the transform from
 world to pixel coordinates. We can point to :meth:`~lib.floatcanvas.FloatCanvas.FloatCanvas.FlatEarthProjection`
 for an example -- though that should really be a class method, or even
 better, simply a function in the module. There is a tiny bit on info
 in the error message in FloatCanvas.SetProjectionFun()

 (Note: this really should get re-factored to allow more generic
 projections...)
:param string `BackgroundColor`: any value accepted by :class:`wx.Brush`
:param `Debug`: activate debug, currently it prints some debugging
 information, could be improved.

__init__(self, parent, id = -1, size = wx.DefaultSize, ProjectionFun = None, BackgroundColor = "WHITE", Debug = False, \*\*kwargs)

Add an object to the canvas

:param DrawObject `obj`: the object to add

:return: DrawObject

Add objects to the canvas

:param list `Objects`: a list of :class:`DrawObject`

Creates Circle and adds its reference to the canvas.
Argument protocol same as Circle class, whose docstring is:
Draws a circle

ClearAll(ResetBB=True)

Removes all DrawObjects from the Canvas

If ResetBB is set to False, the original bounding box will remain

Canvas.Draw(Force=False)

Re-draws the canvas.

Note that the buffer will not be re-drawn unless something has
changed. If you change a DrawObject directly, then the canvas
will not know anything has changed. In this case, you can force
a re-draw by passing int True for the Force flag:

Canvas.Draw(Force=True)

There is a main buffer set up to double buffer the screen, so
you can get quick re-draws when the window gets uncovered.

If there are any objects in self._ForeDrawList, then the
background gets drawn to a new buffer, and the foreground
objects get drawn on top of it. The final result if blitted to
the screen, and stored for future Paint events.  This is done so
that you can have a complicated background, but have something
changing on the foreground, without having to wait for the
background to get re-drawn. This can be used to support simple
animation, for instance.

Compute the scaling array for the flat-earth projection

:param `CenterPoint`: center point of viewport (lon, lat) -- the
 longitude is scaled to the latitude of this point. a 2-tuple, or a
 (2,) `NumPy <http://www.numpy.org/>`_ array of point coordinates

 :returns : a (2,) numpy array that scales world coordinates. This
  scaling is applied when converting to-from world to pixel coordinates.

Get the hit test colour

:param `xy`: the position to get the hit test colour for

Sets everything in the Canvas to default state.

It can be used to reset the Canvas

Move the image in the window.

:param tuple `shift`: is an (x, y) tuple defining amount to shift in
 each direction
:param string `CoordType`: defines what coordinates to use, valid entries
 are:

 ============== ======================================================
 Coordtype      Description
 `Panel`        shift the image by some fraction of the size of the
                displayed image
 `Pixel`        shift the image by some number of pixels
 `World`        shift the image by an amount of floating point world
                coordinates

Converts coordinates from Pixel coordinates to world coordinates.

Points is a tuple of (x,y) coordinates, or a list of such tuples,
or a NX2 Numpy array of x,y coordinates.

"
Remove object from canvas

:param DrawObject `Object`: a :class:`DrawObjects` to remove
:param boolean `ResetBB`: reset the bounding box

"
Remove objects from canvas

:param list `Objects`: a list of :class:`DrawObjects` to remove

Saves the current image as an image file.

:param string `filename`: the name of the image file
:param `ImageType`: format to use, see :ref:`wx.BitmapType` and the note in
 :meth:`wx.Bitmap.SaveFile`

This function computes a pair of x.y lengths,
to change then from pixel to world coordinates.

Lengths should be a NX2 array of (x,y) coordinates, or
a 2-tuple, or sequence of 2-tuples.

This function will get passed to the drawing functions of the objects,
to Change a length from world to pixel coordinates.

Set the GUImode to any of the available mode.

:param `Mode`: a valid GUI Mode, out of the box valid modes
 are subclassed from :class:`~lib.floatcanvas.GUIMode.GUIBase` or a mode
 can also be user defined.

Set a custom projection function

:param `ProjectionFun`: valid entries are ``FlatEarth``, ``None``
  or a callable object that takes the ``ViewPortCenter`` and returns
  ``MapProjectionVector``

Set to the new scale

:param boolean `DrawFlag`: draw the canvas

to transform from world to pixel coordinates.
Coordinates should be a NX2 array of (x,y) coordinates, or

Zoom(factor, center) changes the amount of zoom of the image by factor.
If factor is greater than one, the image gets larger.
If factor is less than one, the image gets smaller.
:param factor: amount to zoom in or out If factor is greater than one,
               the image gets larger. If factor is less than one, the
               image gets smaller.
:param center: a tuple of (x,y) coordinates of the center of the viewport,
               after zooming. If center is not given, the center will stay the same.

:param centerCoords: flag indicating whether the center given is in pixel or world
                     coords. Options are: "World" or "Pixel"
:param keepPointInPlace: boolean flag. If False, the center point is what's given.
                         If True, the image is shifted so that the given center point
                         is kept in the same pixel space. This facilitates keeping the
                         same point under the mouse when zooming with the scroll wheel.

Zoom(self, factor, center = None, centerCoords="World", keepPointInPlace=False)

Zooms the image to the bounding box given, or to the bounding
box of all the objects on the canvas, if none is given.

Module that holds the GUI modes used by FloatCanvas

Note that this can only be imported after a wx.App() has been created.

This approach was inspired by Christian Blouin, who also wrote the initial
version of the code.

# Name:         GUIMode.py
# Purpose:
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

Basic Mouse mode and baseclass for other GUImode.

This one does nothing with any event

:param `Canvas`: the canvas the GUI mode is attached too

this method gets called by FloatCanvas when a new mode is being set
on the Canvas

Update gets called if the screen has been repainted in the middle of a zoom in
so the Rubber Band Box can get updated. Other GUIModes may require something similar

Cursor()
Cursor(cursorName, type=BITMAP_TYPE_ANY, hotSpotX=0, hotSpotY=0)
Cursor(cursorId)
Cursor(image)
Cursor(cursor)

A cursor is a small bitmap usually used for denoting where the mouse
pointer is, with a picture that might indicate the interpretation of a
mouse click.

Mouse mode checks for a hit test, and if nothing is hit,
raises a FloatCanvas mouse event for each event.

Mode that moves the image (pans).
It doesn't change any coordinates, it only changes what the viewport is

so the Rubber Band Box can get updated

Combines :class:`~lib.floatcanvas.FloatCanvas.FloatCanvas` with Navigation
controls onto a :class:`Panel`

    from wx.lib.floatcanvas import NavCanvas, FloatCanvas

    #Add the Canvas
    self.Canvas = NavCanvas.NavCanvas(self, -1,
                                 Debug=0,
                                 ).Canvas

# Name:         NavCanvas.py
# Purpose:      Combines FloatCanvas with Navigation controls
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:

:class:`~lib.floatcanvas.NavCanvas.NavCanvas` encloses a
:class:`~lib.floatcanvas.FloatCanvas.FloatCanvas` in a :class:`Panel` and
adds a Navigation toolbar.

:param `**kwargs`: will be passed on to :class:`~lib.floatcanvas.FloatCanvas.FloatCanvas`

__init__(self, parent, id = wx.ID_ANY, size = wx.DefaultSize, \*\*kwargs)

Add the mode buttons to the tool bar.

:param ToolBar `tb`: the toolbar instance
:param list `Modes`: a list of modes to add, out of the box valid modes
 are subclassed from :class:`~lib.floatcanvas.GUIMode.GUIBase` or modes

Add the zoom button to the tool bar.

Build the default tool bar, can be over-ridden in a subclass to add
extra tools etc.

Hack to hide and show button on toolbar to get around OS-X bug on
wxPython2.8 on OS-X

# This file was generated by /usr/local/bin/img2py
#

GetDIPSize() -> Size

Returns the size of bitmap in DPI-independent units.

GetHandle() -> long

MSW-only method to fetch the windows handle for the bitmap.

GetHeight() -> int

Returns the height of the bitmap in physical pixels.

GetLogicalHeight() -> double

Returns the height of the bitmap in logical pixels.

GetLogicalSize() -> Size

Returns the size of the bitmap in logical pixels.

GetLogicalWidth() -> double

Returns the width of the bitmap in logical pixels.

GetMask() -> Mask

Gets the associated mask (if any) which may have been loaded from a
file or set for the bitmap.

GetPalette() -> Palette

Gets the associated palette (if any) which may have been loaded from a

GetScaledHeight() -> double

GetScaledSize() -> Size

GetScaledWidth() -> double

GetScaleFactor() -> double

Returns the scale factor of this bitmap.

GetSize() -> Size

Returns the size of the bitmap in physical pixels.

GetWidth() -> int

Returns the width of the bitmap in physical pixels.

Image()
Image(width, height, clear=True)
Image(sz, clear=True)
Image(name, type=BITMAP_TYPE_ANY, index=-1)
Image(name, mimetype, index=-1)
Image(stream, type=BITMAP_TYPE_ANY, index=-1)
Image(stream, mimetype, index=-1)
Image(width, height, data)
Image(width, height, data, alpha)
Image(size, data)
Image(size, data, alpha)

This class encapsulates a platform-independent image.

HSVValue(h=0.0, s=0.0, v=0.0)

A simple class which stores hue, saturation and value as doubles in
the range 0.0-1.0.

RGBValue(r=0, g=0, b=0)

A simple class which stores red, green and blue values as 8 bit
unsigned integers in the range of 0-255.

GetMaskBlue() -> unsignedchar

Gets the blue value of the mask colour.

GetMaskGreen() -> unsignedchar

Gets the green value of the mask colour.

GetMaskRed() -> unsignedchar

Gets the red value of the mask colour.

GetType() -> BitmapType

Gets the type of image found by LoadFile() or specified with
SaveFile().

# Name:        wx.lib.gizmos
# Purpose:     Python ports of some of the wrapped C++ classes in the
#              wx.gizmos module in Classic wxPython
#
#
# Created:     26-Oct-2017
# Copyright:   (c) 2017-2020 by Total Control Software
# Tags:

A window which can be dynamically split to an arbitrary depth and later
reunified through the user interface.

# Name:        wx.lib.gizmos.dynamicsash
# Purpose:     A Python port of the C++ wxDynamicSashWindow from the
#              old wxCode library.
#
#
# Created:     30-Oct-2017
# Tags:

EvtHandler()

A class that can handle events from the windowing system.

DynamicSashSplitEvents are sent to your view by DynamicSashWindow whenever
your view is being split by the user.  It is your responsibility to handle
this event by creating a new view window as a child of the
DynamicSashWindow.  DynamicSashWindow will automatically reparent it to
the proper place in its window hierarchy.

DynamicSashUnifyEvents are sent to your view by DynamicSashWindow whenever
the sash which splits your view and its sibling is being reunified such
that your view is expanding to replace its sibling. You needn't do
anything with this event if you are allowing DynamicSashWindow to manage
your view's scrollbars, but it is useful if you are managing the
scrollbars yourself so that you can keep the scrollbars' event handlers
connected to your view's event handler class.

A DynamicSashWindow widget manages the way other widgets are viewed. When
a DynamicSashWindow is first shown, it will contain one child view, a
viewport for that child, and a pair of scrollbars to allow the user to
navigate the child view area.  Next to each scrollbar is a small tab.  By
clicking on either tab and dragging to the appropriate spot, a user can
split the view area into two smaller views separated by a draggable sash.
Later, when the user wishes to reunify the two subviews, the user simply
drags the sash to the side of the window. DynamicSashWindow will
automatically reparent the appropriate child view back up the window
hierarchy, and the DynamicSashWindow will have only one child view once
again.

As an application developer, you will simply create a DynamicSashWindow
using either the Create() function or the more complex constructor
provided below, and then create a view window whose parent is the
DynamicSashWindow.  The child should respond to DynamicSashSplitEvents --
perhaps with an OnSplit() event handler -- by constructing a new view
window whose parent is also the DynamicSashWindow.  That's it!  Now your
users can dynamically split and reunify the view you provided.

If you wish to handle the scrollbar events for your view, rather than
allowing DynamicSashWindow to do it for you, things are a bit more
complex.  (You might want to handle scrollbar events yourself, if, for
instance, you wish to scroll a subwindow of the view you add to your
DynamicSashWindow object, rather than scrolling the whole view.) In this
case, you will need to construct your DynamicSashWindow without the
wxDS_MANAGE_SCROLLBARS style and  you will need to use the GetHScrollBar()
and GetVScrollBar() methods to retrieve the scrollbar controls and call
SetEventHandler() on them to redirect the scrolling events whenever your
window is reparented by wxDyanmicSashWindow. You will need to set the
scrollbars' event handler at three times:

    *  When your view is created When your view receives a
    *  DynamicSashSplitEvent When your view receives a
    *  DynamicSashUnifyEvent

See the dynsash_switch sample application for an example which does this.

Create a new DynamicSashWindow.

Both the normal constructor style with all parameters, or wxWidgets
2-phase style default constructor is supported. If the default
constructor is used then the Create method will need to be called
later before the widget can actually be used.

Create(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, name=PanelNameStr) -> bool

Construct the actual window object after creating the C++ object.

Create(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=DS_DEFAULT, name='dynamicSashWindow')

Widget to display a series of digits, spaces, dashes or colons in a segmented style.

# Name:        wx.lib.gizmos.ledctrl
# Purpose:
#
#
# Tags:

The LEDNumberCtrl can be used to display a series of digits, (plus spaces,
colons or dashes,) using a style reminiscent of old-timey segmented
digital displays.

Create a new LEDNumberCtrl.

Create(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr) -> bool

Create(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=LED_ALIGN_LEFT|LED_DRAW_FADED, name='ledctrl')

Set how the digits will be aligned within the widget.

Supported values are ``LED_ALIGN_LEFT``, ``LED_ALIGN_RIGHT``,
and ``LED_ALIGN_CENTER``.

Set whether unlit segments will still be draw with a faded version of
the foreground colour.

A generic widget that combines the multicolumn features of a :class:`wx.ListCtrl`
with the hierarchical features of a :class:`wx.TreeCtrl`.

This implementation is based on :class:`~wx.lib.agw.hypertreelist.HyperTreeList`

See documentation for :class:`~wx.lib.agw.hypertreelist.HyperTreeList` and
:class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`. This class is just a
simple derivation of the former in order to provide a mostly compatible
class to replace the C++ TreeListCtrl class in Classic, and most
CustomTreeCtrl methods are available here as well via monkey-patched
delegates.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=wx.TR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="treelistctrl")

package providing "masked edit" controls, allowing characters within a data entry control to remain fixed, and providing fine-grain control over allowed user input.

# Name:        wx.lib.masked
# Purpose:     A package containing the masked edit controls
#
# Author:      Will Sadkin, Jeff Childers
#
# Created:     6-Mar-2004
# Copyright:   (c) 2004
# License:     wxWidgets license
# Tags:        phoenix-port, py3-port

Provides masked edit capabilities within a ComboBox format, as well as
a base class from which you can derive masked comboboxes tailored to a specific
function.  See maskededit module overview for how to configure the control.

# Name:         masked.combobox.py
# Authors:      Will Sadkin
# Email:        wsadkin@nameconnector.com
# Created:      02/11/2003
# Copyright:    (c) 2003 by Will Sadkin, 2003
# License:      wxWidgets license
#
# Tags:         py3-port, phoenix-port, unittest, documented
#
#
# This masked edit class allows for the semantics of masked controls
# to be applied to combo boxes.
#

Base class for generic masked edit comboboxes; allows auto-complete of values.
It is not meant to be instantiated directly, but rather serves as a base class
for any subsequent refinements.

:param wx.Window `parent`: the window parent. Must not be ``None``;
:param string `value`: value to be shown;
:param list `choices`: a list of valid choices;
:param wx.Validator `validator`: this is mainly provided for data-transfer, as control does
  its own validation;
:param string `name`: the window name;
:param boolean `setupEventHandling`: setup event handling by default.

__init__( self, parent, id=-1, value = '', pos = wx.DefaultPosition, size = wx.DefaultSize, choices = [], style = wx.CB_DROPDOWN, validator = wx.DefaultValidator, name = "maskedComboBox", setupEventHandling = True, \*\*kwargs)

This base control function override is necessary so the control can keep
track of any additions to the list of choices, because :class:`ComboBox`
doesn't have an accessor for the choice list.  The code here is the same
as in the SetParameters() mixin function, but is done for the individual
value as appended, so the list can be built incrementally without speed
penalty.

:meth:`~lib.masked.combobox.ComboBox.AppendItems` is handled in terms
of :meth:`lib.masked.combobox.ComboBox.Append`, to avoid code replication.

This base control function override is necessary so the derived control
can keep track of any additions to the list of choices, because
:class:`ComboBox`  doesn't have an accessor for the choice list.

This function redefines the externally accessible :meth:`ComboBox.Cut`
to be a smart "erase" of the text in question, so as not to corrupt the
masked control.

.. note::

  This must be done in the class derived from the base wx control.

GetTextSelection() -> (from, to)

Gets the current selection span.

IsEmpty() -> bool

Returns true if the control is empty or false if it has some items.

This function redefines the externally accessible :meth:`ComboBox.Paste`
to be a smart "paste" of the text in question, so as not to corrupt the

.. note::

This function redefines the externally accessible :meth:`ComboBox.Refresh`
to validate the contents of the masked control as it refreshes.

.. note::

Set the font, then recalculate control size, if appropriate.

see :meth:`ComboBox.SetFont` for valid arguments

Necessary override for bookkeeping on choice selection, to keep current
value current.

:param integer `index`: index to choice item to be set

This function redefines the externally accessible :meth:`ComboBox.SetValue`

.. note::

This function defines the undo operation for the control.
(The default undo is 1-deep.)

This is the primary derivation from MaskedEditMixin.  It provides
a general masked text control that can be configured with different
masks.

However, this is done with an extra level of inheritance, so that
"general" classes like masked.TextCtrl can have all possible attributes,
while derived classes, like masked.TimeCtrl and masked.NumCtrl
can prevent exposure of those optional attributes of their base
class that do not make sense for their derivation.  Therefore,
we define::

    BaseMaskedTextCtrl(TextCtrl, MaskedEditMixin)

and::

    masked.TextCtrl(BaseMaskedTextCtrl, MaskedEditAccessorsMixin).

This allows us to then derive::

    masked.NumCtrl( BaseMaskedTextCtrl )

and not have to expose all the same accessor functions for the
derived control when they don't all make sense for it.

In practice, BaseMaskedTextCtrl should never be instantiated directly,
but should only be used in derived classes.

__init__( self, parent, id=-1, value = '', pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TE_PROCESS_TAB, validator=wx.DefaultValidator, name = 'maskedTextCtrl', setupEventHandling = True, \*\*kwargs)

Provided to accommodate similar functionality added to base
control in wxPython 2.7.1.1.

:param string `value`: new value for control, this will not fire an event

Blanks the current control value by replacing it with the default value.

This function redefines the externally accessible :meth:`TextCtrl.Cut`

.. note::

Returns true if the control is currently empty.

This function overrides the raw :meth:`TextCtrl.IsModified` method,
because the  masked edit mixin uses SetValue to change the value, which
doesn't modify the state of this attribute.  So, the derived control
keeps track on each keystroke to see if the value changes, and if so,
it's been modified.

This factored function of common code does the bulk of the work for
SetValue and ChangeValue.

:param string `value`: new value for control
:param boolean `use_change_value`: if True uses :meth:`~lib.masked.textctrl.TextCtrl.ChangeValue`

This function redefines the externally accessible :meth:`TextCtrl.Paste`

.. note::

This function redefines the externally accessible :meth:`TextCtrl.Refresh`

.. note::

see :meth:`TextCtrl.SetFont` for valid arguments

This function redefines the externally accessible :meth:`TextCtrl.SetValue`

.. note::

The "user-visible" masked combobox control, this class is
identical to the BaseMaskedComboBox class it's derived from.
(This extra level of inheritance allows us to add the generic
set of masked edit parameters only to this class while allowing
other classes to derive from the "base" masked combobox control,
and provide a smaller set of valid accessor functions.)
See BaseMaskedComboBox for available methods.

This class manages the individual fields in a masked edit control.
Each field has a zero-based index, indicating its position in the
control, an extent, an associated mask, and a plethora of optional
parameters.  Fields can be instantiated and then associated with
parent masked controls, in order to provide field-specific configuration.
Alternatively, fields will be implicitly created by the parent control
if not provided at construction, at which point, the fields can then
manipulated by the controls .SetFieldParameters() method.

This is the "constructor" for setting up parameters for fields.
a field_index of -1 is used to indicate "the entire control."

Indicates whether the specified slice is considered empty for the
field.

Indicates whether the specified slice is considered a valid value for the
field.

('fillChar', 'groupChar', 'decimalChar', 'useParensForNegatives', 'compareNoCase', 'emptyInvalid', 'validRequired', 'raiseOnInvalidPaste', 'stopFieldChangeIfInvalid')

{'index': None, 'mask': '', 'extent': (), 'formatcodes': '', 'fillChar': ' ', 'groupChar': ',', 'decimalChar': '.', 'shiftDecimalChar': '>', 'useParensForNegatives': False, 'defaultValue': '', 'excludeChars': '', 'includeChars': '', 'validRegex': '', 'validRange': (), 'choices': [], 'choiceRequired': False, 'compareNoCase': False, 'autoSelect': False, 'validFunc': None, 'validRequired': False, 'emptyInvalid': False, 'description': '', 'raiseOnInvalidPaste': False, 'stopFieldChangeIfInvalid': False}

This function provides a useful framework for generating
optional debugging output that can be displayed at an
arbitrary level of indentation.

This handler ensures that the derived control can react to events
from the base control before any external handlers run, to ensure
proper behavior.

Because calling SetSelection programmatically does not fire EVT_COMBOBOX
events, the derived control has to do it itself when it auto-completes.

## ---------- ---------- ---------- ---------- ---------- ---------- ----------
## Because calling SetSelection programmatically does not fire EVT_COMBOBOX
## events, we have to do it ourselves when we auto-complete.

Retrieve the value of the control at the time
this event was generated.

To avoid a ton of boiler-plate, and to automate the getter/setter generation
for each valid control parameter so we never forget to add the functions when
adding parameters, this class programmatically adds the masked edit mixin
parameters to itself.
(This makes it easier for Designers like Boa to deal with masked controls.)

To further complicate matters, this is done with an extra level of inheritance,
so that "general" classes like masked.TextCtrl can have all possible attributes,
while derived classes, like masked.TimeCtrl and masked.NumCtrl can prevent
exposure of those optional attributes of their base class that do not make
sense for their derivation.

Therefore, we define:
and

This allows us to then derive:

['mask', 'autoformat', 'fields', 'datestyle', 'autoCompleteKeycodes', 'useFixedWidthFont', 'defaultEncoding', 'retainFieldValidation', 'emptyBackgroundColour', 'validBackgroundColour', 'invalidBackgroundColour', 'signedForegroundColour', 'demo', 'mask', 'formatcodes', 'fillChar', 'groupChar', 'decimalChar', 'shiftDecimalChar', 'useParensForNegatives', 'defaultValue', 'excludeChars', 'includeChars', 'validRegex', 'validRange', 'choices', 'choiceRequired', 'compareNoCase', 'autoSelect', 'validFunc', 'validRequired', 'emptyInvalid', 'description', 'raiseOnInvalidPaste', 'stopFieldChangeIfInvalid']

This class allows us to abstract the masked edit functionality that could
be associated with any text entry control. (eg. wx.TextCtrl, wx.ComboBox, etc.)
It forms the basis for all of the lib.masked controls.

This is the "constructor" for setting up the mixin variable parameters for the composite class.

Using ChangeValue, so not to fire a change event

Routine provided for getting a parameter of an individual field.

Returns control's value stripped of the template text.
plainvalue = MaskedEditMixin.GetPlainValue()

Returns True if the value specified (or the value of the control if not specified)
is equal to the default value.

Returns True if control is equal to an empty value.
(Empty means all editable positions in the template == fillChar.)

Indicates whether the value specified (or the current value of the control
if not specified) is considered valid.

This public function can be used to set individual or multiple masked edit
parameters after construction.  (See maskededit module overview for the list
of valid parameters.)

Routine provided to modify the parameters of a given field.
Because changes to fields can affect the overall control,
direct access to the fields is prevented, and the control
is always "reconfigured" after setting a field parameter.
(See maskededit module overview for the list of valid field-level
parameters.)

{'mask': 'XXXXXXXXXXXXX', 'autoformat': '', 'fields': {}, 'datestyle': 'MDY', 'autoCompleteKeycodes': [], 'useFixedWidthFont': True, 'defaultEncoding': 'latin1', 'retainFieldValidation': False, 'emptyBackgroundColour': 'White', 'validBackgroundColour': 'White', 'invalidBackgroundColour': 'Yellow', 'foregroundColour': 'Black', 'signedForegroundColour': 'Red', 'demo': False}

PreMaskedComboBox( BaseMaskedComboBox, MaskedEditAccessorsMixin )

PreMaskedTextCtrl( BaseMaskedTextCtrl, MaskedEditAccessorsMixin )

The "user-visible" masked text control; it is identical to the
BaseMaskedTextCtrl class it's derived from.
other classes to derive from the "base" masked text control,
See BaseMaskedTextCtrl for available methods.

[('24HRTIMEHHMM', '24Hr HH:MM\n(see TimeCtrl)'), ('24HRTIMEHHMMSS', '24Hr HH:MM:SS\n(see TimeCtrl)'), ('AGE', 'Age'), ('CREDITCARD', 'Credit Card'), ('EMAIL', 'Email address'), ('EUDATE24HRTIMEDDMMYYYY.HHMM', 'DD.MM.YYYY 24Hr Time\n(w/o seconds)'), ('EUDATE24HRTIMEDDMMYYYY.HHMMSS', 'DD.MM.YYYY 24Hr Time'), ('EUDATE24HRTIMEDDMMYYYY/HHMM', 'DD/MM/YYYY 24Hr Time\n(w/o seconds)'), ('EUDATE24HRTIMEDDMMYYYY/HHMMSS', 'DD/MM/YYYY 24Hr Time'), ('EUDATE24HRTIMEYYYYMMDD.HHMM', 'YYYY.MM.DD 24Hr Time\n(w/o seconds)'), ('EUDATE24HRTIMEYYYYMMDD.HHMMSS', 'YYYY.MM.DD 24Hr Time'), ('EUDATE24HRTIMEYYYYMMDD/HHMM', 'YYYY/MM/DD 24Hr Time\n(w/o seconds)'), ('EUDATE24HRTIMEYYYYMMDD/HHMMSS', 'YYYY/MM/DD 24Hr Time'), ('EUDATEDDMMMYYYY.', 'DD.Month.YYYY'), ('EUDATEDDMMMYYYY/', 'DD/Month/YYYY'), ('EUDATEDDMMYYYY.', 'DD.MM.YYYY'), ('EUDATEDDMMYYYY/', 'DD/MM/YYYY'), ('EUDATETIMEDDMMYYYY.HHMM', 'DD.MM.YYYY HH:MM'), ('EUDATETIMEDDMMYYYY.HHMMSS', 'DD.MM.YYYY HH:MM:SS'), ('EUDATETIMEDDMMYYYY/HHMM', 'DD/MM/YYYY HH:MM'), ('EUDATETIMEDDMMYYYY/HHMMSS', 'DD/MM/YYYY HH:MM:SS'), ('EUDATETIMEYYYYMMDD.HHMM', 'YYYY.MM.DD HH:MM'), ('EUDATETIMEYYYYMMDD.HHMMSS', 'YYYY.MM.DD HH:MM:SS'), ('EUDATETIMEYYYYMMDD/HHMM', 'YYYY/MM/DD HH:MM'), ('EUDATETIMEYYYYMMDD/HHMMSS', 'YYYY/MM/DD HH:MM:SS'), ('EUDATEYYYYMMDD.', 'YYYY.MM.DD'), ('EUDATEYYYYMMDD/', 'YYYY/MM/DD'), ('EXPDATEMMYY', 'Expiration MM/YY'), ('IPADDR', 'IP Address\n(see IpAddrCtrl)'), ('PERCENT', 'Percentage'), ('TIMEHHMM', 'HH:MM (A|P)M\n(see TimeCtrl)'), ('TIMEHHMMSS', 'HH:MM:SS (A|P)M\n(see TimeCtrl)'), ('USDATE24HRTIMEMMDDYYYY-HHMM', 'US Date + 24Hr Time\n(w/hyphens and w/o seconds)'), ('USDATE24HRTIMEMMDDYYYY-HHMMSS', 'US Date + 24Hr Time\n(w/hyphens)'), ('USDATE24HRTIMEMMDDYYYY/HHMM', 'US Date + 24Hr Time\n(without seconds)'), ('USDATE24HRTIMEMMDDYYYY/HHMMSS', 'US Date + 24Hr (Military) Time'), ('USDATEMMDDYY/', 'US Date\n(MMDDYY)'), ('USDATEMMDDYYYY-', 'MM-DD-YYYY'), ('USDATEMMDDYYYY/', 'US Date\n(MMDDYYYY)'), ('USDATETIMEMMDDYYYY-HHMM', 'US Date + Time\n(w/hyphens and w/o secs)'), ('USDATETIMEMMDDYYYY-HHMMSS', 'US Date + Time\n(w/hyphens)'), ('USDATETIMEMMDDYYYY/HHMM', 'US Date + Time\n(without seconds)'), ('USDATETIMEMMDDYYYY/HHMMSS', 'US Date + Time'), ('USPHONEFULL', 'Phone Number only'), ('USPHONEFULLEXT', 'Phone Number w/opt. ext'), ('USPHONETIGHT', 'Phone Number\n(w/hyphens)'), ('USPHONETIGHTEXT', 'Phone Number\n (w/hyphens and opt. ext)'), ('USSOCIALSEC', 'Social Sec#'), ('USSTATE', 'US State Code'), ('USSTATENAME', 'US State Name'), ('USZIP', 'US 5-digit zip code'), ('USZIPPLUS4', 'US zip+4 code')]

{'jan': 1, 'feb': 2, 'mar': 3, 'apr': 4, 'may': 5, 'jun': 6, 'jul': 7, 'aug': 8, 'sep': 9, 'oct': 10, 'nov': 11, 'dec': 12}

{'USPHONEFULLEXT': {'mask': '(###) ###-#### x:###', 'formatcodes': 'F^->', 'validRegex': '^\\(\\d{3}\\) \\d{3}-\\d{4}', 'description': 'Phone Number w/opt. ext'}, 'USPHONETIGHTEXT': {'mask': '###-###-#### x:###', 'formatcodes': 'F^->', 'validRegex': '^\\d{3}-\\d{3}-\\d{4}', 'description': 'Phone Number\n (w/hyphens and opt. ext)'}, 'USPHONEFULL': {'mask': '(###) ###-####', 'formatcodes': 'F^->', 'validRegex': '^\\(\\d{3}\\) \\d{3}-\\d{4}', 'description': 'Phone Number only'}, 'USPHONETIGHT': {'mask': '###-###-####', 'formatcodes': 'F^->', 'validRegex': '^\\d{3}-\\d{3}-\\d{4}', 'description': 'Phone Number\n(w/hyphens)'}, 'USSTATE': {'mask': 'AA', 'formatcodes': 'F!V', 'validRegex': '([ACDFGHIKLMNOPRSTUVW] |AL|AK|AZ|AR|CA|CO|CT|DE|DC|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|MA|ME|MD|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|PR|RI|SC|SD|TN|TX|UT|VA|VT|VI|WA|WV|WI|WY)', 'choices': ['AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'DC', 'FL', 'GA', 'GU', 'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'MA', 'ME', 'MD', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA', 'PR', 'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VA', 'VT', 'VI', 'WA', 'WV', 'WI', 'WY'], 'choiceRequired': True, 'description': 'US State Code'}, 'USSTATENAME': {'mask': 'ACCCCCCCCCCCCCCCCCCC', 'formatcodes': 'F_', 'validRegex': '([ACDFGHIKLMNOPRSTUVW] |Alabama|Alaska|Arizona|Arkansas|California|Colorado|Connecticut|Delaware|District of Columbia|Florida|Georgia|Hawaii|Idaho|Illinois|Indiana|Iowa|Kansas|Kentucky|Louisiana|Maine|Maryland|Massachusetts|Michigan|Minnesota|Mississippi|Missouri|Montana|Nebraska|Nevada|New Hampshire|New Jersey|New Mexico|New York|North Carolina|North Dakokta|Ohio|Oklahoma|Oregon|Pennsylvania|Puerto Rico|Rhode Island|South Carolina|South Dakota|Tennessee|Texas|Utah|Vermont|Virginia|Washington|West Virginia|Wisconsin|Wyoming)', 'choices': ['Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California', 'Colorado', 'Connecticut', 'Delaware', 'District of Columbia', 'Florida', 'Georgia', 'Hawaii', 'Idaho', 'Illinois', 'Indiana', 'Iowa', 'Kansas', 'Kentucky', 'Louisiana', 'Maine', 'Maryland', 'Massachusetts', 'Michigan', 'Minnesota', 'Mississippi', 'Missouri', 'Montana', 'Nebraska', 'Nevada', 'New Hampshire', 'New Jersey', 'New Mexico', 'New York', 'North Carolina', 'North Dakokta', 'Ohio', 'Oklahoma', 'Oregon', 'Pennsylvania', 'Puerto Rico', 'Rhode Island', 'South Carolina', 'South Dakota', 'Tennessee', 'Texas', 'Utah', 'Vermont', 'Virginia', 'Washington', 'West Virginia', 'Wisconsin', 'Wyoming'], 'choiceRequired': True, 'description': 'US State Name'}, 'USDATETIMEMMDDYYYY/HHMMSS': {'mask': '##/##/#### ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'US Date + Time'}, 'USDATETIMEMMDDYYYY-HHMMSS': {'mask': '##-##-#### ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)-(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)-\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'US Date + Time\n(w/hyphens)'}, 'USDATE24HRTIMEMMDDYYYY/HHMMSS': {'mask': '##/##/#### ##:##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'US Date + 24Hr (Military) Time'}, 'USDATE24HRTIMEMMDDYYYY-HHMMSS': {'mask': '##-##-#### ##:##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)-(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)-\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'US Date + 24Hr Time\n(w/hyphens)'}, 'USDATETIMEMMDDYYYY/HHMM': {'mask': '##/##/#### ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'US Date + Time\n(without seconds)'}, 'USDATE24HRTIMEMMDDYYYY/HHMM': {'mask': '##/##/#### ##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'US Date + 24Hr Time\n(without seconds)'}, 'USDATETIMEMMDDYYYY-HHMM': {'mask': '##-##-#### ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)-(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)-\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'US Date + Time\n(w/hyphens and w/o secs)'}, 'USDATE24HRTIMEMMDDYYYY-HHMM': {'mask': '##-##-#### ##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)-(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)-\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'US Date + 24Hr Time\n(w/hyphens and w/o seconds)'}, 'USDATEMMDDYYYY/': {'mask': '##/##/####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d{4}', 'description': 'US Date\n(MMDDYYYY)'}, 'USDATEMMDDYY/': {'mask': '##/##/##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/\\d\\d', 'description': 'US Date\n(MMDDYY)'}, 'USDATEMMDDYYYY-': {'mask': '##-##-####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)-(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)-\\d{4}', 'description': 'MM-DD-YYYY'}, 'EUDATEYYYYMMDD/': {'mask': '####/##/##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}/(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)', 'description': 'YYYY/MM/DD'}, 'EUDATEYYYYMMDD.': {'mask': '####.##.##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}.(01|02|03|04|05|06|07|08|09|10|11|12).(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)', 'description': 'YYYY.MM.DD'}, 'EUDATEDDMMYYYY/': {'mask': '##/##/####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(01|02|03|04|05|06|07|08|09|10|11|12)/\\d{4}', 'description': 'DD/MM/YYYY'}, 'EUDATEDDMMYYYY.': {'mask': '##.##.####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(01|02|03|04|05|06|07|08|09|10|11|12).\\d{4}', 'description': 'DD.MM.YYYY'}, 'EUDATEDDMMMYYYY.': {'mask': '##.CCC.####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec).\\d{4}', 'description': 'DD.Month.YYYY'}, 'EUDATEDDMMMYYYY/': {'mask': '##/CCC/####', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)/\\d{4}', 'description': 'DD/Month/YYYY'}, 'EUDATETIMEYYYYMMDD/HHMMSS': {'mask': '####/##/## ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^\\d{4}/(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'YYYY/MM/DD HH:MM:SS'}, 'EUDATETIMEYYYYMMDD.HHMMSS': {'mask': '####.##.## ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^\\d{4}.(01|02|03|04|05|06|07|08|09|10|11|12).(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'YYYY.MM.DD HH:MM:SS'}, 'EUDATETIMEDDMMYYYY/HHMMSS': {'mask': '##/##/#### ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(01|02|03|04|05|06|07|08|09|10|11|12)/\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'DD/MM/YYYY HH:MM:SS'}, 'EUDATETIMEDDMMYYYY.HHMMSS': {'mask': '##.##.#### ##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(01|02|03|04|05|06|07|08|09|10|11|12).\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'DD.MM.YYYY HH:MM:SS'}, 'EUDATETIMEYYYYMMDD/HHMM': {'mask': '####/##/## ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^\\d{4}/(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'YYYY/MM/DD HH:MM'}, 'EUDATETIMEYYYYMMDD.HHMM': {'mask': '####.##.## ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^\\d{4}.(01|02|03|04|05|06|07|08|09|10|11|12).(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'YYYY.MM.DD HH:MM'}, 'EUDATETIMEDDMMYYYY/HHMM': {'mask': '##/##/#### ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(01|02|03|04|05|06|07|08|09|10|11|12)/\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'DD/MM/YYYY HH:MM'}, 'EUDATETIMEDDMMYYYY.HHMM': {'mask': '##.##.#### ##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'DF!', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(01|02|03|04|05|06|07|08|09|10|11|12).\\d{4} (0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'DD.MM.YYYY HH:MM'}, 'EUDATE24HRTIMEYYYYMMDD/HHMMSS': {'mask': '####/##/## ##:##:##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}/(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'YYYY/MM/DD 24Hr Time'}, 'EUDATE24HRTIMEYYYYMMDD.HHMMSS': {'mask': '####.##.## ##:##:##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}.(01|02|03|04|05|06|07|08|09|10|11|12).(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'YYYY.MM.DD 24Hr Time'}, 'EUDATE24HRTIMEDDMMYYYY/HHMMSS': {'mask': '##/##/#### ##:##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(01|02|03|04|05|06|07|08|09|10|11|12)/\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'DD/MM/YYYY 24Hr Time'}, 'EUDATE24HRTIMEDDMMYYYY.HHMMSS': {'mask': '##.##.#### ##:##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(01|02|03|04|05|06|07|08|09|10|11|12).\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'DD.MM.YYYY 24Hr Time'}, 'EUDATE24HRTIMEYYYYMMDD/HHMM': {'mask': '####/##/## ##:##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}/(01|02|03|04|05|06|07|08|09|10|11|12)/(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'YYYY/MM/DD 24Hr Time\n(w/o seconds)'}, 'EUDATE24HRTIMEYYYYMMDD.HHMM': {'mask': '####.##.## ##:##', 'formatcodes': 'DF', 'validRegex': '^\\d{4}.(01|02|03|04|05|06|07|08|09|10|11|12).(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31) (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'YYYY.MM.DD 24Hr Time\n(w/o seconds)'}, 'EUDATE24HRTIMEDDMMYYYY/HHMM': {'mask': '##/##/#### ##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31)/(01|02|03|04|05|06|07|08|09|10|11|12)/\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'DD/MM/YYYY 24Hr Time\n(w/o seconds)'}, 'EUDATE24HRTIMEDDMMYYYY.HHMM': {'mask': '##.##.#### ##:##', 'formatcodes': 'DF', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31).(01|02|03|04|05|06|07|08|09|10|11|12).\\d{4} (00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': 'DD.MM.YYYY 24Hr Time\n(w/o seconds)'}, 'TIMEHHMMSS': {'mask': '##:##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'TF!', 'validRegex': '^(0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'HH:MM:SS (A|P)M\n(see TimeCtrl)'}, 'TIMEHHMM': {'mask': '##:## AM', 'excludeChars': 'BCDEFGHIJKLMNOQRSTUVWXYZ\x8a\x8c\x8e\x9fÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ', 'formatcodes': 'TF!', 'validRegex': '^(0\\d| \\d|1[012]):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59) (A|P)M', 'description': 'HH:MM (A|P)M\n(see TimeCtrl)'}, '24HRTIMEHHMMSS': {'mask': '##:##:##', 'formatcodes': 'TF', 'validRegex': '^(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': '24Hr HH:MM:SS\n(see TimeCtrl)'}, '24HRTIMEHHMM': {'mask': '##:##', 'formatcodes': 'TF', 'validRegex': '^(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23):(00|01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59)', 'description': '24Hr HH:MM\n(see TimeCtrl)'}, 'USSOCIALSEC': {'mask': '###-##-####', 'formatcodes': 'F', 'validRegex': '\\d{3}-\\d{2}-\\d{4}', 'description': 'Social Sec#'}, 'CREDITCARD': {'mask': '####-####-####-####', 'formatcodes': 'F', 'validRegex': '\\d{4}-\\d{4}-\\d{4}-\\d{4}', 'description': 'Credit Card'}, 'EXPDATEMMYY': {'mask': '##/##', 'formatcodes': 'F', 'validRegex': '^(01|02|03|04|05|06|07|08|09|10|11|12)/\\d\\d', 'description': 'Expiration MM/YY'}, 'USZIP': {'mask': '#####', 'formatcodes': 'F', 'validRegex': '^\\d{5}', 'description': 'US 5-digit zip code'}, 'USZIPPLUS4': {'mask': '#####-####', 'formatcodes': 'F', 'validRegex': '\\d{5}-(\\s{4}|\\d{4})', 'description': 'US zip+4 code'}, 'PERCENT': {'mask': '0.##', 'formatcodes': 'F', 'validRegex': '^0.\\d\\d', 'description': 'Percentage'}, 'AGE': {'mask': '###', 'formatcodes': 'F', 'validRegex': '^[1-9]{1}  |[1-9][0-9] |1[0|1|2][0-9]', 'description': 'Age'}, 'EMAIL': {'mask': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', 'excludeChars': ' \\/*&%$#!+=\'"', 'formatcodes': 'F>', 'validRegex': '^\\w+([\\-\\.]\\w+)*@((([a-zA-Z0-9]+(\\-[a-zA-Z0-9]+)*\\.)+)[a-zA-Z]{2,4}|\\[(\\d|\\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))(\\.(\\d|\\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))){3}\\]) *$', 'description': 'Email address'}, 'IPADDR': {'mask': '###.###.###.###', 'formatcodes': 'F_Sr', 'validRegex': '(  \\d| \\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))(\\.(  \\d| \\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))){3}', 'description': 'IP Address\n(see IpAddrCtrl)'}}

['Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California', 'Colorado', 'Connecticut', 'Delaware', 'District of Columbia', 'Florida', 'Georgia', 'Hawaii', 'Idaho', 'Illinois', 'Indiana', 'Iowa', 'Kansas', 'Kentucky', 'Louisiana', 'Maine', 'Maryland', 'Massachusetts', 'Michigan', 'Minnesota', 'Mississippi', 'Missouri', 'Montana', 'Nebraska', 'Nevada', 'New Hampshire', 'New Jersey', 'New Mexico', 'New York', 'North Carolina', 'North Dakokta', 'Ohio', 'Oklahoma', 'Oregon', 'Pennsylvania', 'Puerto Rico', 'Rhode Island', 'South Carolina', 'South Dakota', 'Tennessee', 'Texas', 'Utah', 'Vermont', 'Virginia', 'Washington', 'West Virginia', 'Wisconsin', 'Wyoming']

['AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'DC', 'FL', 'GA', 'GU', 'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'MA', 'ME', 'MD', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA', 'PR', 'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VA', 'VT', 'VI', 'WA', 'WV', 'WI', 'WY']

{'mask': '###.###.###.###', 'formatcodes': 'F_Sr', 'validRegex': '(  \\d| \\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))(\\.(  \\d| \\d\\d|(1\\d\\d|2[0-4]\\d|25[0-5]))){3}', 'description': 'IP Address\n(see IpAddrCtrl)'}

*masked.Ctrl* is actually a factory function for several types of
masked edit controls:

    =================  =========================================================
    masked.TextCtrl     standard masked edit text box
    masked.ComboBox     adds combobox capabilities
    masked.IpAddrCtrl   adds logical input semantics for IP address entry
    masked.TimeCtrl     special subclass handling lots of time formats as values
    masked.NumCtrl      special subclass handling numeric values

masked.Ctrl works by looking for a special *controlType*
parameter in the variable arguments of the control, to determine
what kind of instance to return.
controlType can be one of::

    controlTypes.TEXT
    controlTypes.COMBO
    controlTypes.IPADDR
    controlTypes.TIME
    controlTypes.NUMBER

These constants are also available individually, ie, you can
use either of the following::

    from wx.lib.masked import Ctrl, COMBO, TEXT, NUMBER, TIME
    from wx.lib.masked import Ctrl, controlTypes

If not specified as a keyword argument, the default controlType is
controlTypes.TEXT.

Each of the above classes has its own unique arguments, but Masked.Ctrl
provides a single "unified" interface for masked controls.

# Name:         wx.lib.masked.ctrl.py
# Author:       Will Sadkin
# Created:      09/24/2003
# Copyright:   (c) 2003 by Will Sadkin
# License:     wxWindows license
# Tags:        py3-port
# 12/09/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Updated for wx namespace (minor)
#
# 12/20/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Removed wx prefix
#

This class is a particular type of MaskedTextCtrl that accepts
and understands the semantics of IP addresses, reformats input
as you move from field to field, and accepts '.' as a navigation
character, so that typing an IP address can be done naturally.

__init__( self, parent, id=-1, value = '', pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator, name = 'IpAddrCtrl', setupEventHandling = True, \*\*kwargs)

Defines what action to take when the '.' character is typed in the
control.  By default, the current field is right-justified, and the
cursor is placed in the next field.

Takes a string value, validates it for a valid IP address,
splits it into an array of 4 fields, justifies it
appropriately, and inserts it into the control.
Invalid values will raise a ValueError exception.

:param string `value`: the IP address in the form '000.000.000.000'

Masked edit control supporting "native" numeric values, ie. .SetValue(3), for
example, and supporting a variety of formatting options, including automatic
rounding specifiable precision, grouping and decimal place characters, etc.

:param integer `value`: value to be shown;

__init__ ( self, parent, id=-1, value = 0, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator, name = "masked.num", \*\*kwargs )

Sets the value of the control to the value specified.
The resulting actual value of the control may be altered to
conform with the bounds set on the control if limited,
or colored if not limited but the value is out-of-bounds.
A ValueError exception will be raised if an invalid value
is specified.

This method does not fire a change event.

:param integer `value`: new value

This function returns a two-tuple (min,max), indicating the
current bounds of the control.  Each value can be None if
that bound is not set.

Returns the fractional portion of the value as a float. If there is no
fractional portion, the value returned will be 0.0.

Gets the maximum value of the control.  It will return the current
maximum integer, or None if not specified.

Gets the lower bound value of the control.  It will return
None if not specified.

Returns True if no value is specified and the current value
of the control falls within the current bounds.  This function can
also be called with a value to see if that value would fall within
the current bounds of the given control.

:param `value`: value to check

Returns True if the control is currently limiting the
value to fall within the current bounds.

Handles an event indicating that the text control's value
has changed, and issue EVT_NUM event.

.. note::

  Using :meth:`TextCtrl.SetValue` to change the control's contents from
  within a EVT_CHAR handler can cause double text events. So we check
  for actual changes to the text before passing the events on.

Change the behavior of the validation code, allowing control
to have a value of None or not, as appropriate.  If the value
of the control is currently None, and allow_none is False, the
value of the control will be set to the minimum value of the
control, or 0 if no lower bound is set.

:param boolean `allow_none`: True if None is allowed

This function is a convenience function for setting the min and max
values at the same time.  The function only applies the maximum bound
if setting the minimum bound is successful, and returns True
only if both operations succeed.

.. note:: leaving out an argument will remove the corresponding bound.

:param `min`: Minimum value for the control
:type `min`: integer or None
:param `max`: Minimum value for the control
:type `max`: integer or None

Set the fraction width of the control

:param integer `value`: the width value

Set the integer width of the control

If called with a value of True, this function will cause the control
to limit the value to fall within the bounds currently specified.
If the control's value currently exceeds the bounds, it will then
be limited accordingly.

If called with a value of False, this function will disable value
limiting, but coloring of out-of-bounds values will still take
place if bounds have been set for the control.

:param boolean `limited`: define value limiting

to prevent navigation out of the current field if its value is out-of-bounds,
and limit the value to fall within the bounds currently specified if the
control loses focus.

:param boolean `limit`: define value limiting

Sets the maximum value of the control. If a value of None
is provided, then the control will have no explicit maximum value.
If the value specified is less than the current minimum value, then
the function returns False and the maximum will not change from its
current setting. On success, the function returns True.

If successful and the current value is greater than the new upper
bound, if the control is limited the value will be automatically
adjusted to this maximum value; if not limited, the value in the
control will be colored as invalid.

If max > the max value allowed by the width of the control,
the function will return False, and the max will not be set.

Sets the minimum value of the control.  If a value of None
is provided, then the control will have no explicit minimum value.
If the value specified is greater than the current maximum value,
then the function returns False and the minimum will not change from
its current setting.  On success, the function returns True.

If successful and the current value is lower than the new lower
bound, if the control is limited, the value will be automatically
adjusted to the new minimum value; if not limited, the value in the

If min > the max value allowed by the width of the control,
the function will return False, and the min will not be set.

This function is used to initialize and reconfigure the control.
See :class:`~lib.masked.timectrl.TimeCtrl` module overview for available
parameters.

{'integerWidth': 10, 'fractionWidth': 0, 'decimalChar': '.', 'allowNegative': True, 'useParensForNegatives': False, 'groupDigits': False, 'groupChar': ',', 'min': None, 'max': None, 'limited': False, 'limitOnFieldChange': False, 'allowNone': False, 'selectOnEntry': True, 'foregroundColour': 'Black', 'signedForegroundColour': 'Red', 'emptyBackgroundColour': 'White', 'validBackgroundColour': 'White', 'invalidBackgroundColour': 'Yellow', 'useFixedWidthFont': False, 'autoSize': True}

Masked control providing several time formats and manipulation of time values.

:param boolean `fmt24hr`: True to use 24 hour format (sometimes called military format;
:param SpinButton `spinButton`: an instance of :class:`SpinButton` or
  None;

__init__ ( self, parent, id=-1, value = '00:00:00', pos = wx.DefaultPosition, size = wx.DefaultSize, fmt24hr=False, spinButton = None, style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator, name = "time", \*\*kwargs )

This function binds an externally created spin button to the control,
so that up/down events from the button automatically change the control.

:param SpinButton `sb`: an instance of :class:`SpinButton`

Validating ChangeValue function for time values:
This function will do dynamic type checking on the value argument,
and convert :class:`DateTime`, mxDateTime, or 12/24 format time string
into the appropriate format string for the control.

No change event is fired by this method.

:param `value`: the time value

Gets the minimum value of the control.
If None, it will return None.  Otherwise it will return
the current minimum bound on the control, as a :class:`DateTime`
by default, or as a string if as_string argument is True.

Returns the value of the control as an mx.DateTime, with the date
portion set to January 1, 1970.

This function returns the value of the display as a string by default,
but supports return as a :class:`DateTime`, mx.DateTime, :class:`TimeSpan`,
or mx.DateTimeDelta, if requested.
(Evaluated in the order above-- first one wins!)

:param boolean `as_wxDateTime`: return value as :class:`DateTime`;
:param boolean `as_mxDateTime`: return value as mxDateTime;
:param boolean `as_wxTimeSpan`: return value as :class:`TimeSpan`;
:param boolean `as_mxDateTimeDelta`: return value as mxDateTimeDelta;

GetValue(self, as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan = False, as_mxDateTimeDelta = False)

This function is the conversion engine for TimeCtrl; it takes
one of the following types:

* time string
* :class:`DateTime`
* :class:`TimeSpan`
* mxDateTime
* mxDateTimeDelta

and converts it to a :class:`DateTime` that always has Jan 1, 1970 as
its date portion, so that range comparisons around values can work using
:class:`DateTime` built-in comparison function.  If a value is not
provided to convert, the string value of the control will be used.
If the value is not one of the accepted types, a ValueError will be
raised.

of the control falls within the current bounds.  As the clock
is a "circle", both minimum and maximum bounds must be set for
a value to ever be considered "out of bounds".  This function can

value to fall within any current bounds.  *Note:* can
be set even if there are no current bounds.

Can be used to determine if a given value would be a legal and
in-bounds value for the control.

.. note:: Leaving out an argument will remove the corresponding bound.

This override records the specified position and associated cell before
calling base class' function.  This is necessary to handle the optional
spin button, because the insertion point is lost when the focus shifts
to the spin button.

If called with a value of 0, this function will disable value

then the function returns 0 and the minimum will not change from
its current setting.  On success, the function returns 1.

Because SetValue can take an mx.DateTime, (if DateTime is importable),
this is now just an alias.

Function providing access to the parameters governing TimeCtrl display
and bounds.

SetSelection(from_, to_)

Selects the text starting at the first position up to (but not
including) the character at the last position.

Validating SetValue function for time values:

Because SetValue can take a :class:`DateTime`, this is now just an alias.

{'format': 'HHMMSS', 'displaySeconds': True, 'min': None, 'max': None, 'limited': False, 'useFixedWidthFont': True, 'oob_color': 'Yellow'}

Actually a factory function providing a unifying
interface for generating masked controls.

Provides a smart text input control that understands the structure and
limits of IP Addresses, and allows automatic field navigation as the
user hits '.' when typing.

# Name:         masked.ipaddrctrl.py
#
# Tags:        phoenix-port, py3-port, unittest, documented
#
# NOTE:
#   Masked.IpAddrCtrl is a minor modification to masked.TextCtrl, that is
#   specifically tailored for entering IP addresses.  It allows for
#   right-insert fields and provides an accessor to obtain the entered
#   address with extra whitespace removed.
#

Defines IpAddrCtrl's list of attributes having their own
Get/Set functions, exposing only those that make sense for
an IP address control.

('fields', 'retainFieldValidation', 'formatcodes', 'fillChar', 'defaultValue', 'description', 'useFixedWidthFont', 'signedForegroundColour', 'emptyBackgroundColour', 'validBackgroundColour', 'invalidBackgroundColour', 'emptyInvalid', 'validFunc', 'validRequired')

\
contains MaskedEditMixin class that drives all the other masked controls.

Masked Edit Overview

masked.TextCtrl:
    is a sublassed text control that can carefully control the user's input
    based on a mask string you provide.

    General usage example::

        control = masked.TextCtrl( win, -1, '', mask = '(###) ###-####')

    The example above will create a text control that allows only numbers to be
    entered and then only in the positions indicated in the mask by the # sign.

masked.ComboBox:
    is a similar subclass of wxComboBox that allows the same sort of masking,
    but also can do auto-complete of values, and can require the value typed
    to be in the list of choices to be colored appropriately.

masked.Ctrl:
    is actually a factory function for several types of masked edit controls:

    =================   ==================================================
    masked.IpAddrCtrl   adds special semantics for IP address entry
    masked.TimeCtrl     special subclass handling lots of types as values

    It works by looking for a *controlType* parameter in the keyword
    arguments of the control, to determine what kind of instance to return.
    If not specified as a keyword argument, the default control type returned
    will be masked.TextCtrl.

    Each of the above classes has its own set of arguments, but masked.Ctrl
    provides a single "unified" interface for masked controls.

What follows is a description of how to configure the generic masked.TextCtrl
and masked.ComboBox;  masked.NumCtrl and masked.TimeCtrl have their own demo
pages and interface descriptions.

=========================

Initialization Parameters
-------------------------
mask
    Allowed mask characters and function:

    =========  ==========================================================
    Character   Function
        #       Allow numeric only (0-9)
        N       Allow letters and numbers (0-9)
        A       Allow uppercase letters only
        a       Allow lowercase letters only
        C       Allow any letter, upper or lower
        X       Allow string.letters, string.punctuation, string.digits
        &       Allow string.punctuation only (doesn't include all unicode symbols)
        \*      Allow any visible character
        |       explicit field boundary (takes no space in the control; allows mix
                of adjacent mask characters to be treated as separate fields,
                eg: '&|###' means "field 0 = '&', field 1 = '###'", but there's
                no fixed characters in between.

    These controls define these sets of characters using string.letters,
    string.uppercase, etc.  These sets are affected by the system locale
    setting, so in order to have the masked controls accept characters
    that are specific to your users' language, your application should
    set the locale.
    For example, to allow international characters to be used in the
    above masks, you can place the following in your code as part of
    your application's initialization code::

      import locale
      locale.setlocale(locale.LC_ALL, '')

    The controls now also support (by popular demand) all "visible" characters,
    by use of the * mask character, including unicode characters above
    the standard ANSI keycode range.
    Note:  As string.punctuation doesn't typically include all unicode
    symbols, you will have to use includechars to get some of these into
    otherwise restricted positions in your control, such as those specified
    with &.

  Using these mask characters, a variety of template masks can be built. See
  the demo for some other common examples include date+time, social security
  number, etc.  If any of these characters are needed as template rather
  than mask characters, they can be escaped with \, ie. \N means "literal N".
  (use \\ for literal backslash, as in: r'CCC\\NNN'.)

  .. note::

      Masks containing only # characters and one optional decimal point
      character are handled specially, as "numeric" controls.  Such
      controls have special handling for typing the '-' key, handling
      the "decimal point" character as truncating the integer portion,
      optionally allowing grouping characters and so forth.
      There are several parameters and format codes that only make sense
      when combined with such masks, eg. groupChar, decimalChar, and so
      forth (see below).  These allow you to construct reasonable
      numeric entry controls.

  .. note::

      Changing the mask for a control deletes any previous field classes
      (and any associated validation or formatting constraints) for them.

useFixedWidthFont
  By default, masked edit controls use a fixed width font, so that
  the mask characters are fixed within the control, regardless of
  subsequent modifications to the value.  Set to False if having
  the control font be the same as other controls is required. (This is
  a control-level parameter.)

  .. versionchanged::  2.9.5
     The default is changed to False for numctrl only

defaultEncoding
  (Applies to unicode systems only) By default, the default unicode encoding
  used is latin1, or iso-8859-1.  If necessary, you can set this control-level
  parameter to govern the codec used to decode your keyboard inputs.
  (This is a control-level parameter.)

formatcodes
  These other properties can be passed to the class when instantiating it:
    Formatcodes are specified as a string of single character formatting
    codes that modify  behavior of the control::

            _  Allow spaces
            !  Force upper
            ^  Force lower
            R  Right-align field(s)
            r  Right-insert in field(s) (implies R)
            <  Stay in field until explicit navigation out of it

            >  Allow insert/delete within partially filled fields (as
               opposed to the default "overwrite" mode for fixed-width
               masked edit controls.)  This allows single-field controls
               or each field within a multi-field control to optionally
               behave more like standard text controls.
               (See EMAIL or phone number autoformat examples.)

               *Note: This also governs whether backspace/delete operations
               shift contents of field to right of cursor, or just blank the
               erased section.

               Also, when combined with 'r', this indicates that the field
               or control allows right insert anywhere within the current
               non-empty value in the field.  (Otherwise right-insert behavior
               is only performed to when the entire right-insertable field is
               selected or the cursor is at the right edge of the field.*

            ,  Allow grouping character in integer fields of numeric controls
               and auto-group/regroup digits (if the result fits) when leaving
               such a field.  (If specified, .SetValue() will attempt to
               auto-group as well.)
               ',' is also the default grouping character.  To change the
               grouping character and/or decimal character, use the groupChar
               and decimalChar parameters, respectively.
               Note: typing the "decimal point" character in such fields will
               clip the value to that left of the cursor for integer
               fields of controls with "integer" or "floating point" masks.
               If the ',' format code is specified, this will also cause the
               resulting digits to be regrouped properly, using the current
               grouping character.
            -  Prepend and reserve leading space for sign to mask and allow
               signed values (negative #s shown in red by default.) Can be
               used with argument useParensForNegatives (see below.)
            0  integer fields get leading zeros
            D  Date[/time] field
            T  Time field
            F  Auto-Fit: the control calculates its size from
               the length of the template mask
            V  validate entered chars against validRegex before allowing them
               to be entered vs. being allowed by basic mask and then having
               the resulting value just colored as invalid.
               (See USSTATE autoformat demo for how this can be used.)
            S  select entire field when navigating to new field

fillChar

defaultValue
  These controls have two options for the initial state of the control.
  If a blank control with just the non-editable characters showing
  is desired, simply leave the constructor variable fillChar as its
  default (' ').  If you want some other character there, simply
  change the fillChar to that value.  Note: changing the control's fillChar
  will implicitly reset all of the fields' fillChars to this value.

  If you need different default characters in each mask position,
  you can specify a defaultValue parameter in the constructor, or
  set them for each field individually.
  This value must satisfy the non-editable characters of the mask,
  but need not conform to the replaceable characters.

groupChar

decimalChar
  These parameters govern what character is used to group numbers
  and is used to indicate the decimal point for numeric format controls.
  The default groupChar is ',', the default decimalChar is '.'
  By changing these, you can customize the presentation of numbers
  for your location.

  Eg::

        formatcodes = ',', groupChar='\''                  allows  12'345.34
        formatcodes = ',', groupChar='.', decimalChar=','  allows  12.345,34

  (These are control-level parameters.)

shiftDecimalChar
  The default "shiftDecimalChar" (used for "backwards-tabbing" until
  shift-tab is fixed in wxPython) is '>' (for QUERTY keyboards.) for
  other keyboards, you may want to customize this, eg '?' for shift ',' on
  AZERTY keyboards, ':' or ';' for other European keyboards, etc.

useParensForNegatives=False
  This option can be used with signed numeric format controls to
  indicate signs via () rather than '-'.

autoSelect=False
  This option can be used to have a field or the control try to
  auto-complete on each keystroke if choices have been specified.

autoCompleteKeycodes=[]
  By default, DownArrow, PageUp and PageDown will auto-complete a
  partially entered field.  Shift-DownArrow, Shift-UpArrow, PageUp
  and PageDown will also auto-complete, but if the field already
  contains a matched value, these keys will cycle through the list
  of choices forward or backward as appropriate.  Shift-Up and
  Shift-Down also take you to the next/previous field after any
  auto-complete action.

  Additional auto-complete keys can be specified via this parameter.
  Any keys so specified will act like PageDown.

Validating User Input
=====================
There are a variety of initialization parameters that are used to validate
user input.  These parameters can apply to the control as a whole, and/or
to individual fields:

========================  ==================================================================
excludeChars              A string of characters to exclude even if otherwise allowed
includeChars              A string of characters to allow even if otherwise disallowed
validRegex                Use a regular expression to validate the contents of the text box
validRange                Pass a rangeas list (low,high) to limit numeric fields/values
choices                   A list of strings that are allowed choices for the control.
choiceRequired            value must be member of choices list
compareNoCase             Perform case-insensitive matching when validating against list. *Note: for masked.ComboBox, this defaults to True.*
emptyInvalid              Boolean indicating whether an empty value should be considered invalid
validFunc                 A function to call of the form: bool = func(candidate_value) which will return True if the candidate_value satisfies some external criteria for the control in addition to the the other validation, or False if not.  (This validation is applied last in the chain of validations.)
validRequired             Boolean indicating whether or not keys that are allowed by the mask, but result in an invalid value are allowed to be entered into the control.  Setting this to True implies that a valid default value is set for the control.
retainFieldValidation     False by default; if True, this allows individual fields to retain their own validation constraints independently of any subsequent changes to the control's overall parameters. (This is a control-level parameter.)
validator                 Validators are not normally needed for masked controls, because of the nature of the validation and control of input.  However, you can supply one to provide data transfer routines for the controls.
raiseOnInvalidPaste       False by default; normally a bad paste simply is ignored with a bell; if True, this will cause a ValueError exception to be thrown, with the .value attribute of the exception containing the bad value.
stopFieldChangeIfInvalid  False by default; tries to prevent navigation out of a field if its current value is invalid.  Can be used to create a hybrid of validation settings, allowing intermediate invalid values in a field without sacrificing ability to limit values as with validRequired. NOTE: It is possible to end up with an invalid value when using this option if focus is switched to some other control via mousing. To avoid this, consider deriving a class that defines _LostFocus() function that returns the control to a valid value when the focus shifts.  (AFAICT, The change in focus is unpreventable.)

Coloring Behavior

The following parameters have been provided to allow you to change the default
coloring behavior of the control.   These can be set at construction, or via
the .SetCtrlParameters() function.  Pass a color as string e.g. 'Yellow':

========================  =======================================================================
emptyBackgroundColour     Control Background color when identified as empty. Default=White
invalidBackgroundColour   Control Background color when identified as Not valid. Default=Yellow
validBackgroundColour     Control Background color when identified as Valid. Default=white

The following parameters control the default foreground color coloring behavior of the
control. Pass a color as string e.g. 'Yellow':

========================  ======================================================================
foregroundColour          Control foreground color when value is not negative.  Default=Black
signedForegroundColour    Control foreground color when value is negative. Default=Red

Fields
======

Each part of the mask that allows user input is considered a field.  The fields
are represented by their own class instances.  You can specify field-specific
constraints by constructing or accessing the field instances for the control
and then specifying those constraints via parameters.

fields
  This parameter allows you to specify Field instances containing
  constraints for the individual fields of a control, eg: local
  choice lists, validation rules, functions, regexps, etc.
  It can be either an ordered list or a dictionary.  If a list,
  the fields will be applied as fields 0, 1, 2, etc.
  If a dictionary, it should be keyed by field index.
  the values should be a instances of maskededit.Field.

  Any field not represented by the list or dictionary will be
  implicitly created by the control.

  Eg::

    fields = [ Field(formatcodes='_r'), Field('choices=['a', 'b', 'c']) ]

  Or::

    fields = {
               1: ( Field(formatcodes='_R', choices=['a', 'b', 'c']),
               3: ( Field(choices=['01', '02', '03'], choiceRequired=True)
             }

  The following parameters are available for individual fields, with the
  same semantics as for the whole control but applied to the field in question:

    ==============  =============================================================================
    fillChar        if set for a field, it will override the control's fillChar for that field
    groupChar       if set for a field, it will override the control's default
    defaultValue    sets field-specific default value; overrides any default from control
    compareNoCase   overrides control's settings
    emptyInvalid    determines whether field is required to be filled at all times
    validRequired   if set, requires field to contain valid value

  If any of the above parameters are subsequently specified for the control as a
  whole, that new value will be propagated to each field, unless the
  retainFieldValidation control-level parameter is set.

    ==============  ==============================
    formatcodes      Augments control's settings
    excludeChars         '       '        '
    includeChars         '       '        '
    validRegex           '       '        '
    validRange           '       '        '
    choices              '       '        '
    choiceRequired       '       '        '
    validFunc            '       '        '

Control Class Functions
=======================

.GetPlainValue(value=None)
                    Returns the value specified (or the control's text value
                    not specified) without the formatting text.
                    In the example above, might return phone no='3522640075',
                    whereas control.GetValue() would return '(352) 264-0075'
.ClearValue()
                    Returns the control's value to its default, and places the
                    cursor at the beginning of the control.
.SetValue()
                    Does "smart replacement" of passed value into the control, as does
                    the .Paste() method.  As with other text entry controls, the
                    .SetValue() text replacement begins at left-edge of the control,
                    with missing mask characters inserted as appropriate.
                    .SetValue will also adjust integer, float or date mask entry values,
                    adding commas, auto-completing years, etc. as appropriate.
                    For "right-aligned" numeric controls, it will also now automatically
                    right-adjust any value whose length is less than the width of the
                    control before attempting to set the value.
                    If a value does not follow the format of the control's mask, or will
                    not fit into the control, a ValueError exception will be raised.

                    Eg::

                      mask = '(###) ###-####'
                          .SetValue('1234567890')           => '(123) 456-7890'
                          .SetValue('(123)4567890')         => '(123) 456-7890'
                          .SetValue('(123)456-7890')        => '(123) 456-7890'
                          .SetValue('123/4567-890')         => illegal paste; ValueError

                      mask = '#{6}.#{2}', formatcodes = '_,-',
                          .SetValue('111')                  => ' 111   .  '
                          .SetValue(' %9.2f' % -111.12345 ) => '   -111.12'
                          .SetValue(' %9.2f' % 1234.00 )    => '  1,234.00'
                          .SetValue(' %9.2f' % -1234567.12345 ) => insufficient room; ValueError

                      mask = '#{6}.#{2}', formatcodes = '_,-R'  # will right-adjust value for right-aligned control
                          .SetValue('111')                  => padded value misalignment ValueError: "       111" will not fit
                          .SetValue('%.2f' % 111 )          => '    111.00'
                          .SetValue('%.2f' % -111.12345 )   => '   -111.12'

.IsValid(value=None)
                    Returns True if the value specified (or the value of the control
                    if not specified) passes validation tests
.IsEmpty(value=None)
                    if not specified) is equal to an "empty value," ie. all
                    editable characters == the fillChar for their respective fields.
.IsDefault(value=None)
                    if not specified) is equal to the initial value of the control.

.Refresh()
                    Recolors the control as appropriate to its current settings.

.SetCtrlParameters(\*\*kwargs)
                    This function allows you to set up and/or change the control parameters
                    after construction; it takes a list of key/value pairs as arguments,
                    where the keys can be any of the mask-specific parameters in the constructor.

                    Eg::

                        ctl = masked.TextCtrl( self, -1 )
                        ctl.SetCtrlParameters( mask='###-####',
                                               defaultValue='555-1212',
                                               formatcodes='F')

.GetCtrlParameter(parametername)
                    This function allows you to retrieve the current value of a parameter
                    from the control.

  *Note:* Each of the control parameters can also be set using its
      own Set and Get function.  These functions follow a regular form:
      All of the parameter names start with lower case; for their
      corresponding Set/Get function, the parameter name is capitalized.

    Eg::

          ctl.SetMask('###-####')
          ctl.SetDefaultValue('555-1212')
          ctl.GetChoiceRequired()
          ctl.GetFormatcodes()

  *Note:* After any change in parameters, the choices for the
      control are reevaluated to ensure that they are still legal.  If you
      have large choice lists, it is therefore more efficient to set parameters
      before setting the choices available.

.SetFieldParameters(field_index, \*\*kwargs)
                    This function allows you to specify change individual field
                    parameters after construction. (Indices are 0-based.)

.GetFieldParameter(field_index, parametername)
                    Allows the retrieval of field parameters after construction

The control detects certain common constructions. In order to use the signed feature
(negative numbers and coloring), the mask has to be all numbers with optionally one
decimal point. Without a decimal (e.g. '######', the control will treat it as an integer
value. With a decimal (e.g. '###.##'), the control will act as a floating point control
(i.e. press decimal to 'tab' to the decimal position). Pressing decimal in the
integer control truncates the value.  However, for a true numeric control,
masked.NumCtrl provides all this, and true numeric input/output support as well.

Check your controls by calling each control's .IsValid() function and the
.IsEmpty() function to determine which controls have been a) filled in and
b) filled in properly.

Regular expression validations can be used flexibly and creatively.
Take a look at the demo; the zip-code validation succeeds as long as the
first five numerals are entered. the last four are optional, but if
any are entered, there must be 4 to be valid.

masked.Ctrl Configuration

    from wx.lib.masked import MaskedCtrl, controlTypes
    from wx.lib.masked import MaskedCtrl, COMBO, TEXT, NUMBER, IPADDR

# Name:         maskededit.py
# Authors:      Will Sadkin, Jeff Childers
# Email:        wsadkin@parlancecorp.com, jchilders_98@yahoo.com
# Copyright:    (c) 2003 by Jeff Childers, Will Sadkin, 2003
# Portions:     (c) 2002 by Will Sadkin, 2002-2007
#
# NOTE:
#   MaskedEdit controls are based on a suggestion made on [wxPython-Users] by
#   Jason Hihn, and borrows liberally from Will Sadkin's original masked edit
#   control for time entry, TimeCtrl (which is now rewritten using this
#   control!).
#
#   MaskedEdit controls do not normally use validators, because they do
#   careful manipulation of the cursor in the text window on each keystroke,
#   and validation is cursor-position specific, so the control intercepts the
#   key codes before the validator would fire.  However, validators can be
#   provided to do data transfer to the controls.
#
#
# This file now contains the bulk of the logic behind all masked controls,
# the MaskedEditMixin class, the Field class, and the autoformat codes.
#
#
# 03/30/2004 - Will Sadkin (wsadkin@parlancecorp.com)
#
# o Split out TextCtrl, ComboBox and IpAddrCtrl into their own files,
# o Reorganized code into masked package
#
#
# o Updated for wx namespace. No guarantees. This is one huge file.
#
# 12/13/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Missed wx.DateTime stuff earlier.
#
#
# o MaskedEditMixin -> MaskedEditMixin
# o wxMaskedTextCtrl -> maskedTextCtrl
# o wxMaskedComboBoxSelectEvent -> MaskedComboBoxSelectEvent
# o wxMaskedComboBox -> MaskedComboBox
# o wxIpAddrCtrl -> IpAddrCtrl
# o wxTimeCtrl -> TimeCtrl
#
#

The ``wx.App`` class represents the application and is used to:

  * bootstrap the wxPython system and initialize the underlying
    gui toolkit
  * set and get application-wide properties
  * implement the native windowing system main message or event loop,
    and to dispatch events to window instances
  * etc.

Every wx application must have a single ``wx.App`` instance, and all
creation of UI objects should be delayed until after the ``wx.App`` object
has been created in order to ensure that the gui platform and wxWidgets
have been fully initialized.

Normally you would derive from this class and implement an ``OnInit``
method that creates a frame and then calls ``self.SetTopWindow(frame)``,
however ``wx.App`` is also usable on its own without derivation.

:note: In Python the wrapper for the C++ class ``wxApp`` has been renamed tp
    :class:`wx.PyApp`. This ``wx.App`` class derives from ``wx.PyApp``, and is
    responsible for handling the Python-specific needs for bootstrapping the
    wxWidgets library and other Python integration related requirements.

masked.NumCtrl:
  - allows you to get and set integer or floating point numbers as value,</LI>
  - provides bounds support and optional value limiting,</LI>
  - has the right-insert input style that MaskedTextCtrl supports,</LI>
  - provides optional automatic grouping, sign control and format, grouping and decimal
    character selection, etc. etc.</LI>

  Being derived from masked.TextCtrl, the control only allows
  fixed-point  notation.  That is, it has a fixed (though reconfigurable)
  maximum width for the integer portion and optional fixed width
  fractional portion.

  Here's the API::

        from wx.lib.masked import NumCtrl

        NumCtrl(
             parent, id = -1,
             value = 0,
             pos = wx.DefaultPosition,
             size = wx.DefaultSize,
             style = 0,
             validator = wx.DefaultValidator,
             name = "masked.number",
             integerWidth = 10,
             fractionWidth = 0,
             allowNone = False,
             allowNegative = True,
             useParensForNegatives = False,
             groupDigits = False,
             groupChar = ',',
             decimalChar = '.',
             min = None,
             max = None,
             limited = False,
             limitOnFieldChange = False,
             selectOnEntry = True,
             foregroundColour = "Black",
             signedForegroundColour = "Red",
             emptyBackgroundColour = "White",
             validBackgroundColour = "White",
             invalidBackgroundColour = "Yellow",
             autoSize = True
             )

  value
        If no initial value is set, the default will be zero, or
        the minimum value, if specified.  If an illegal string is specified,
        a ValueError will result. (You can always later set the initial
        value with SetValue() after instantiation of the control.)

  integerWidth
        Indicates how many places to the right of any decimal point
        should be allowed in the control.  This will, perforce, limit
        the size of the values that can be entered. This number need
        not include space for grouping characters or the sign, if either
        of these options are enabled, as the resulting underlying
        mask is automatically by the control.  The default of 10
        will allow any 32 bit integer value.  The minimum value
        for integerWidth is 1.

  fractionWidth
        Indicates how many decimal places to show for numeric value.
        If default (0), then the control will display and return only
        integer or long values.

  allowNone
        Boolean indicating whether or not the control is allowed to be
        empty, representing a value of None for the control.

  allowNegative
        Boolean indicating whether or not control is allowed to hold
        negative numbers.

  useParensForNegatives
        If true, this will cause negative numbers to be displayed with ()s
        rather than -, (although '-' will still trigger a negative number.)

  groupDigits
        Indicates whether or not grouping characters should be allowed and/or
        inserted when leaving the control or the decimal character is entered.

  groupChar
        What grouping character will be used if allowed. (By default ',')

  decimalChar
        If fractionWidth is > 0, what character will be used to represent
        the decimal point.  (By default '.')

  min
        The minimum value that the control should allow.  This can be also be
        adjusted with SetMin().  If the control is not limited, any value
        below this bound will result in a background colored with the current
        invalidBackgroundColour.  If the min specified will not fit into the
        control, the min setting will be ignored.

  max
        The maximum value that the control should allow.  This can be
        adjusted with SetMax().  If the control is not limited, any value
        above this bound will result in a background colored with the current
        invalidBackgroundColour.  If the max specified will not fit into the
        control, the max setting will be ignored.

  limited
        Boolean indicating whether the control prevents values from
        exceeding the currently set minimum and maximum values (bounds).
        If False and bounds are set, out-of-bounds values will
        result in a background colored with the current invalidBackgroundColour.

  limitOnFieldChange
        An alternative to limited, this boolean indicates whether or not a
        field change should be allowed if the value in the control
        is out of bounds.  If True, and control focus is lost, this will also
        cause the control to take on the nearest bound value.

  selectOnEntry
        Boolean indicating whether or not the value in each field of the
        control should be automatically selected (for replacement) when
        that field is entered, either by cursor movement or tabbing.
        This can be desirable when using these controls for rapid data entry.

  foregroundColour
        Color value used for positive values of the control.

  signedForegroundColour
        Color value used for negative values of the control.

  emptyBackgroundColour
        What background color to use when the control is considered
        "empty." (allow_none must be set to trigger this behavior.)

  validBackgroundColour
        What background color to use when the control value is
        considered valid.

  invalidBackgroundColour
        Color value used for illegal values or values out-of-bounds of the
        control when the bounds are set but the control is not limited.

  autoSize
        Boolean indicating whether or not the control should set its own
        width based on the integer and fraction widths.  True by default.
        <I>Note:</I> Setting this to False will produce seemingly odd
        behavior unless the control is large enough to hold the maximum
        specified value given the widths and the sign positions; if not,
        the control will appear to "jump around" as the contents scroll.
        (ie. autoSize is highly recommended.)

--------------------------

masked.EVT_NUM(win, id, func)
    Respond to a EVT_COMMAND_MASKED_NUMBER_UPDATED event, generated when
    the value changes. Notice that this event will always be sent when the
    control's contents changes - whether this is due to user input or
    comes from the program itself (for example, if SetValue() is called.)

SetValue(int|long|float|string)
    Sets the value of the control to the value specified, if
    possible.  The resulting actual value of the control may be
    altered to conform to the format of the control, changed
    to conform with the bounds set on the control if limited,
    or colored if not limited but the value is out-of-bounds.
    A ValueError exception will be raised if an invalid value
    is specified.

GetValue()
    Retrieves the numeric value from the control.  The value
    retrieved will be either be returned as a long if the
    fractionWidth is 0, or a float otherwise.

SetParameters(**kwargs)
    Allows simultaneous setting of various attributes
    of the control after construction.  Keyword arguments
    allowed are the same parameters as supported in the constructor.

SetIntegerWidth(value)
    Resets the width of the integer portion of the control.  The
    value must be >= 1, or an AttributeError exception will result.
    This value should account for any grouping characters that might
    be inserted (if grouping is enabled), but does not need to account
    for the sign, as that is handled separately by the control.
GetIntegerWidth()
    Returns the current width of the integer portion of the control,
    not including any reserved sign position.

SetFractionWidth(value)
    Resets the width of the fractional portion of the control.  The
    value must be >= 0, or an AttributeError exception will result.  If
    0, the current value of the control will be truncated to an integer
    value.
GetFractionWidth()
    Returns the current width of the fractional portion of the control.

SetMin(min=None)
    Resets the minimum value of the control.  If a value of <I>None</I>
    is provided, then the control will have no explicit minimum value.
    If the value specified is greater than the current maximum value,
    then the function returns False and the minimum will not change from
    its current setting.  On success, the function returns True.

    If successful and the current value is lower than the new lower
    bound, if the control is limited, the value will be automatically
    adjusted to the new minimum value; if not limited, the value in the
    control will be colored as invalid.

    If min > the max value allowed by the width of the control,
    the function will return False, and the min will not be set.

GetMin()
    Gets the current lower bound value for the control.
    It will return None if no lower bound is currently specified.

SetMax(max=None)
    Resets the maximum value of the control. If a value of <I>None</I>
    is provided, then the control will have no explicit maximum value.
    If the value specified is less than the current minimum value, then
    the function returns False and the maximum will not change from its
    current setting. On success, the function returns True.

    If successful and the current value is greater than the new upper
    bound, if the control is limited the value will be automatically
    adjusted to this maximum value; if not limited, the value in the

    If max > the max value allowed by the width of the control,
    the function will return False, and the max will not be set.

GetMax()
    Gets the current upper bound value for the control.
    It will return None if no upper bound is currently specified.

SetBounds(min=None,max=None)
    This function is a convenience function for setting the min and max
    values at the same time.  The function only applies the maximum bound
    if setting the minimum bound is successful, and returns True
    only if both operations succeed.  <B><I>Note:</I> leaving out an argument
    will remove the corresponding bound.
GetBounds()
    This function returns a two-tuple (min,max), indicating the
    current bounds of the control.  Each value can be None if
    that bound is not set.

IsInBounds(value=None)
    Returns <I>True</I> if no value is specified and the current value
    of the control falls within the current bounds.  This function can also
    be called with a value to see if that value would fall within the current
    bounds of the given control.

SetLimited(bool)
    If called with a value of True, this function will cause the control
    to limit the value to fall within the bounds currently specified.
    If the control's value currently exceeds the bounds, it will then
    be limited accordingly.
    If called with a value of False, this function will disable value
    limiting, but coloring of out-of-bounds values will still take
    place if bounds have been set for the control.

GetLimited()

IsLimited()
    Returns <I>True</I> if the control is currently limiting the
    value to fall within the current bounds.

SetLimitOnFieldChange()
    If called with a value of True, will cause the control to allow
    out-of-bounds values, but will prevent field change if attempted
    via navigation, and if the control loses focus, it will change
    the value to the nearest bound.

GetLimitOnFieldChange()

IsLimitedOnFieldChange()
    value on field change.

SetAllowNone(bool)
    to allow the value to be empty, representing a value of None.
    If called with a value of False, this function will prevent the value
    from being None.  If the value of the control is currently None,
    ie. the control is empty, then the value will be changed to that
    of the lower bound of the control, or 0 if no lower bound is set.

GetAllowNone()

IsNoneAllowed()
    Returns <I>True</I> if the control currently allows its
    value to be None.

SetAllowNegative(bool)
    If called with a value of True, this function will cause the
    control to allow the value to be negative (and reserve space for
    displaying the sign. If called with a value of False, and the
    value of the control is currently negative, the value of the
    control will be converted to the absolute value, and then
    limited appropriately based on the existing bounds of the control
    (if any).

GetAllowNegative()

IsNegativeAllowed()
    Returns <I>True</I> if the control currently permits values
    to be negative.

SetGroupDigits(bool)
    If called with a value of True, this will make the control
    automatically add and manage grouping characters to the presented
    value in integer portion of the control.

GetGroupDigits()

IsGroupingAllowed()
    Returns <I>True</I> if the control is currently set to group digits.

SetGroupChar()
    Sets the grouping character for the integer portion of the
    control.  (The default grouping character this is ','.
GetGroupChar()
    Returns the current grouping character for the control.

SetSelectOnEntry()
    If called with a value of <I>True</I>, this will make the control
    automatically select the contents of each field as it is entered
    within the control.  (The default is True.)
    GetSelectOnEntry()
    Returns <I>True</I> if the control currently auto selects
    the field values on entry.

SetAutoSize(bool)
    Resets the autoSize attribute of the control.
GetAutoSize()
    Returns the current state of the autoSize attribute for the control.

# Name:         wx.lib.masked.numctrl.py
# Created:      09/06/2003
# Copyright:   (c) 2003-2007 by Will Sadkin
#
# NOTE:
#   This was written to provide a numeric edit control for wxPython that
#   does things like right-insert (like a calculator), and does grouping, etc.
#   (ie. the features of masked.TextCtrl), but allows Get/Set of numeric
#   values, rather than text.
#
#   Masked.NumCtrl permits integer, and floating point values to be set
#   retrieved or set via .GetValue() and .SetValue() (type chosen based on
#   fraction width, and provides an masked.EVT_NUM() event function for trapping
#   changes to the control.
#
#   It supports negative numbers as well as the naturals, and has the option
#   of not permitting leading zeros or an empty control; if an empty value is
#   not allowed, attempting to delete the contents of the control will result
#   in a (selected) value of zero, thus preserving a legitimate numeric value.
#   Similarly, replacing the contents of the control with '-' will result in
#   a selected (absolute) value of -1.
#
#   masked.NumCtrl also supports range limits, with the option of either
#   enforcing them or simply coloring the text of the control if the limits
#   are exceeded.
#
#   masked.NumCtrl is intended to support fixed-point numeric entry, and
#   is derived from BaseMaskedTextCtrl.  As such, it supports a limited range
#   of values to comply with a fixed-width entry mask.
#
# o Updated for wx namespace
#
#
# o wxMaskedEditMixin -> MaskedEditMixin
# o wxMaskedTextCtrl -> masked.TextCtrl
# o wxMaskedNumNumberUpdatedEvent -> masked.NumberUpdatedEvent
# o wxMaskedNumCtrl -> masked.NumCtrl
#

Used to fire an EVT_NUM event whenever the value in a NumCtrl changes.

Defines masked.NumCtrl's list of attributes having their own
Get/Set functions, ignoring those that make no sense for
a numeric control.

('decimalChar', 'shiftDecimalChar', 'groupChar', 'useParensForNegatives', 'defaultValue', 'description', 'useFixedWidthFont', 'autoSize', 'signedForegroundColour', 'emptyBackgroundColour', 'validBackgroundColour', 'invalidBackgroundColour', 'emptyInvalid', 'validFunc', 'validRequired', 'stopFieldChangeIfInvalid')

Provides a generic, fully configurable masked edit text control, as well as
a base class from which you can derive masked controls tailored to a specific

# Name:         masked.textctrl.py
# Authors:      Jeff Childers, Will Sadkin
# Email:        jchilders_98@yahoo.com, wsadkin@nameconnector.com
# Portions:     (c) 2002 by Will Sadkin, 2002-2003
#
# This file contains the most typically used generic masked control,
# masked.TextCtrl.  It also defines the BaseMaskedTextCtrl, which can
# be used to derive other "semantics-specific" classes, like masked.NumCtrl,
# masked.TimeCtrl, and masked.IpAddrCtrl.
#
#

*TimeCtrl* provides a multi-cell control that allows manipulation of a time
value.  It supports 12 or 24 hour format, and you can use wxDateTime or mxDateTime
to get/set values from the control.

Left/right/tab keys to switch cells within a TimeCtrl, and the up/down arrows act
like a spin control.  TimeCtrl also allows for an actual spin button to be attached
to the control, so that it acts like the up/down arrow keys.

The ! or c key sets the value of the control to the current time.

  Here's the API for TimeCtrl::

    from wx.lib.masked import TimeCtrl

    TimeCtrl(
         parent, id = -1,
         value = '00:00:00',
         pos = wx.DefaultPosition,
         size = wx.DefaultSize,
         style = wxTE_PROCESS_TAB,
         validator = wx.DefaultValidator,
         name = "time",
         format = 'HHMMSS',
         fmt24hr = False,
         displaySeconds = True,
         spinButton = None,
         min = None,
         max = None,
         limited = None,
         oob_color = "Yellow"
        )

  value
    If no initial value is set, the default will be midnight; if an illegal string
    is specified, a ValueError will result.  (You can always later set the initial time
    with SetValue() after instantiation of the control.)

  size
    The size of the control will be automatically adjusted for 12/24 hour format
    if wx.DefaultSize is specified.  NOTE: due to a problem with wx.DateTime, if the
    locale does not use 'AM/PM' for its values, the default format will automatically
    change to 24 hour format, and an AttributeError will be thrown if a non-24 format

  style
    By default, TimeCtrl will process TAB events, by allowing tab to the
    different cells within the control.

  validator
    By default, TimeCtrl just uses the default (empty) validator, as all
    of its validation for entry control is handled internally.  However, a validator
    can be supplied to provide data transfer capability to the control.

  format
    This parameter can be used instead of the fmt24hr and displaySeconds
    parameters, respectively; it provides a shorthand way to specify the time
    format you want.  Accepted values are 'HHMMSS', 'HHMM', '24HHMMSS', and
    '24HHMM'.  If the format is specified, the other two arguments will be ignored.

  fmt24hr
    If True, control will display time in 24 hour time format; if False, it will
    use 12 hour AM/PM format.  SetValue() will adjust values accordingly for the
    control, based on the format specified.  (This value is ignored if the *format*
    parameter is specified.)

  displaySeconds
    If True, control will include a seconds field; if False, it will
    just show hours and minutes. (This value is ignored if the *format*

  spinButton
    If specified, this button's events will be bound to the behavior of the
    TimeCtrl, working like up/down cursor key events.  (See BindSpinButton.)

  min
    Defines the lower bound for "valid" selections in the control.
    By default, TimeCtrl doesn't have bounds.  You must set both upper and lower
    bounds to make the control pay attention to them, (as only one bound makes no sense
    with times.) "Valid" times will fall between the min and max "pie wedge" of the
    clock.
  max
    Defines the upper bound for "valid" selections in the control.
    "Valid" times will fall between the min and max "pie wedge" of the
    clock. (This can be a "big piece", ie. min = 11pm, max= 10pm
    means *all but the hour from 10:00pm to 11pm are valid times.*)
  limited
    If True, the control will not permit entry of values that fall outside the
    set bounds.

  oob_color
    Sets the background color used to indicate out-of-bounds values for the control
    when the control is not limited.  This is set to "Yellow" by default.

--------------------

EVT_TIMEUPDATE(win, id, func)
    func is fired whenever the value of the control changes.

SetValue(time_string | wxDateTime | wxTimeSpan | mx.DateTime | mx.DateTimeDelta)
    Sets the value of the control to a particular time, given a valid
    value; raises ValueError on invalid value.

*NOTE:* This will only allow mx.DateTime or mx.DateTimeDelta if mx.DateTime
    was successfully imported by the class module.

GetValue(as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan=False, as mxDateTimeDelta=False)
    Retrieves the value of the time from the control.  By default this is
    returned as a string, unless one of the other arguments is set; args are
    searched in the order listed; only one value will be returned.

GetWxDateTime(value=None)
    When called without arguments, retrieves the value of the control, and applies
    it to the wxDateTimeFromHMS() constructor, and returns the resulting value.
    The date portion will always be set to Jan 1, 1970. This form is the same
    as GetValue(as_wxDateTime=True).  GetWxDateTime can also be called with any of the
    other valid time formats settable with SetValue, to regularize it to a single
    wxDateTime form.  The function will raise ValueError on an unconvertable argument.

GetMxDateTime()
    Retrieves the value of the control and applies it to the DateTime.Time()
    constructor,and returns the resulting value.  (The date portion will always be
    set to Jan 1, 1970.) (Same as GetValue(as_wxDateTime=True); provided for backward
    compatibility with previous release.)

BindSpinButton(SpinBtton)
    Binds an externally created spin button to the control, so that up/down spin
    events change the active cell or selection in the control (in addition to the
    up/down cursor keys.)  (This is primarily to allow you to create a "standard"
    interface to time controls, as seen in Windows.)

    Sets the expected minimum value, or lower bound, of the control.
    (The lower bound will only be enforced if the control is
    configured to limit its values to the set bounds.)
    If a value of *None* is provided, then the control will have
    explicit lower bound.  If the value specified is greater than
    the current lower bound, then the function returns False and the
    lower bound will not change from its current setting.  On success,
    the function returns True.  Even if set, if there is no corresponding
    upper bound, the control will behave as if it is unbounded.

    If successful and the current value is outside the
    new bounds, if the control is limited the value will be
    automatically adjusted to the nearest bound; if not limited,
    the background of the control will be colored with the current
    out-of-bounds color.

GetMin(as_string=False)
    Gets the current lower bound value for the control, returning
    None, if not set, or a wxDateTime, unless the as_string parameter
    is set to True, at which point it will return the string
    representation of the lower bound.

    Sets the expected maximum value, or upper bound, of the control.
    (The upper bound will only be enforced if the control is
    If a value of *None* is provided, then the control will
    have no explicit upper bound.  If the value specified is less
    than the current lower bound, then the function returns False and
    the maximum will not change from its current setting. On success,
    lower bound, the control will behave as if it is unbounded.

GetMax(as_string = False)
    Gets the current upper bound value for the control, returning

    only if both operations succeed.  *Note: leaving out an argument
    will remove the corresponding bound, and result in the behavior of
    an unbounded control.*

GetBounds(as_string = False)
    that bound is not set.  The values will otherwise be wxDateTimes
    unless the as_string argument is set to True, at which point they
    will be returned as string representations of the bounds.

    Returns *True* if no value is specified and the current value
    bounds of the given control.  It will raise ValueError if the value
    specified is not a wxDateTime, mxDateTime (if available) or parsable string.

IsValid(value)
    Returns *True* if specified value is a legal time value and
    falls within the current bounds of the given control.

    (Provided both bounds have been set.)
    be set to the nearest bound.
    Returns *True* if the control is currently limiting the

# Name:         timectrl.py
# Created:      09/19/2002
# Copyright:    (c) 2002 by Will Sadkin, 2002
# License:      wxWindows license
#
#
# NOTE:
#   This was written way it is because of the lack of masked edit controls
#   in wxWindows/wxPython.  I would also have preferred to derive this
#   control from a wxSpinCtrl rather than wxTextCtrl, but the wxTextCtrl
#   component of that control is inaccessible through the interface exposed in
#   wxPython.
#
#   TimeCtrl does not use validators, because it does careful manipulation
#   of the cursor in the text window on each keystroke, and validation is
#   cursor-position specific, so the control intercepts the key codes before the
#   validator would fire.
#
#   TimeCtrl now also supports .SetValue() with either strings or wxDateTime
#   values, as well as range limits, with the option of either enforcing them
#   or simply coloring the text of the control if the limits are exceeded.
#
#   Note: this class now makes heavy use of wxDateTime for parsing and
#   regularization, but it always does so with ephemeral instances of
#   wxDateTime, as the C++/Python validity of these instances seems to not
#   persist.  Because "today" can be a day for which an hour can "not exist"
#   or be counted twice (1 day each per year, for DST adjustments), the date
#   portion of all wxDateTimes used/returned have their date portion set to
#   Jan 1, 1970 (the "epoch.")
#
# o Updated for V2.5 compatibility
# o wx.SpinCtl has some issues that cause the control to
#   lock up. Noted in other places using it too, it's not this module
#   that's at fault.
#
#
# o wxTimeCtrl -> masked.TimeCtrl
#
# 2/4/2018   - jensgoe (mail@jensgoepfert.de)
# o wx.Validator_IsSilent() -> wx.Validator.IsSilent()
#

Defines TimeCtrl's list of attributes having their own Get/Set functions,
ignoring those in the base class that make no sense for a time control.

('defaultValue', 'description', 'useFixedWidthFont', 'emptyBackgroundColour', 'validBackgroundColour', 'invalidBackgroundColour', 'validFunc', 'validRequired')

Used to fire an EVT_TIMEUPDATE event whenever the value in a TimeCtrl changes.

Retrieve the value of the time control at the time this event was generated

# Name:        wx.lib.mixins
# Purpose:     A package for helpful wxPython mix-in classes
#
#
# Created:     15-May-2001
# Copyright:   (c) 2001-2020 by Total Control Software
#
#

# Name:        wx.lib.mixins.grid
# Purpose:     Helpful mix-in classes for wx.Grid
#
#
# Created:     5-June-2001
#
# o Untested
#
#
# o wxGridAutoEditMixin -> GridAutoEditMixin
#

A mix-in class that automatically enables the grid edit control when
a cell is selected.

If your class hooks EVT_GRID_SELECT_CELL be sure to call event.Skip so
this handler will be called too.

A Grid mixin that enables renderers to be plugged in for drawing the
row and col labels, similar to how the cell renderers work.

# Name:        wx.lib.mixins.gridlabelrenderer
# Purpose:     A Grid mixin that enables renderers to be plugged in
#              for drawing the row and col labels, similar to how the
#              cell renderers work.
#
#
# Created:     20-Mar-2009
# Copyright:   (c) 2009-2020 by Total Control Software

Override this method in derived classes to do the actual
drawing of the label.

Draw a standard border around the label, to give a simple 3D
effect like the stock wx.grid.Grid labels do.

Draw the label's text in the rectangle, using the alignment
flags, and the grid's specified label font and color.

This class can be mixed with wx.grid.Grid to add the ability to plugin
label renderer objects for the row, column and corner labels, similar to
how the cell renderers work in the main Grid class.

Register a renderer to be used for drawing the label for the
given column.

Sets the renderer that should be used for drawing the area in
the upper left corner of the Grid, between the row labels and
the column labels.  Defaults to an instance of
`GridDefaultCornerLabelRenderer`

Set the column label renderer that should be used for any
column that does not have an explicitly set renderer.
Defaults to an instance of `GridDefaultColLabelRenderer`.

Set the row label renderer that should be used for any row
that does not have an explicitly set renderer.  Defaults to
an instance of `GridDefaultRowLabelRenderer`.

given row.

# Name:        wx.lib.mixins.imagelist
# Purpose:     Helpful mix-in classes for using a wxImageList
#
#
#
# o Untested.
#

Add an icon to the image list, or get the index if already there

Get icon indexes for a given node, or None if no associated icon

This module provides the :class:`~lib.mixins.inspection.InspectableApp` and
:class:`~lib.mixins.inspection.InspectionMixin` which make it easy to use the Widget
Inspection Tool (WIT).

The Widget Inspection Tool (WIT) is very useful debugging tool provided with
wxPython, especially useful to debug layout issues when using :class:`wx.Sizer`.

The :class:`InspectableApp` is a "pre-mixed" :class:`App` and the
:class:`InspectionMixin` allows you to mix it with your custom :class:`App`
class.

Usage
=====

The following samples assume the default key sequence (*ctrl-alt-i*) to start
the WIT, additional information can be found on the following wiki page.

http://wiki.wxpython.org/Widget_Inspection_Tool

InspectableApp usage::

    import wx
    import wx.lib.sized_controls as sc
    import wx.lib.mixins.inspection as wit

    app = wit.InspectableApp()

    frame = sc.SizedFrame(None, -1, "WIT InspectableApp")

    pane = frame.GetContentsPane()
    pane.SetSizerType("horizontal")

    b1 = wx.Button(pane, wx.ID_ANY)
    t1 = wx.TextCtrl(pane, -1)
    t1.SetSizerProps(expand=True)

InspectionMixin usage::

    import wx

    class MyApp(wx.App, wit.InspectionMixin):
        def OnInit(self):
            self.Init()  # initialize the inspection tool
            return True

    app = MyApp()

    frame = sc.SizedFrame(None, -1, "WIT InspectionMixin")

# Name:        wx.lib.mixins.inspection
# Purpose:     A mix-in class that can add PyCrust-based inspection of the
#              app's widgets and sizers.
#
#
# Created:     21-Nov-2006
# Copyright:   (c) 2006-2020 by Total Control Software
#
# Tags: phoenix-port, documented, unittest
#
# NOTE: This class was originally based on ideas sent to the
# wxPython-users mail list by Dan Eloff.

A simple mix of :class:`App` and :class:`InspectionMixin` that can be used
stand-alone.

This class is intended to be used as a mix-in with the :class:`App`.
When used it will add the ability to popup a
:class:`~lib.inspection.InspectionFrame` window
where the widget under the mouse cursor will be selected in the tree and
loaded into the shell's namespace as 'obj'.  The default key sequence to
activate the inspector is Ctrl-Alt-I (or Cmd-Alt-I on Mac) but this can be
changed via parameters to the `Init` method, or the application can call
:meth:`~lib.mixins.inspection.InspectionMixin.ShowInspectionTool` from other
event handlers if desired.

To use this class simply derive a class from :class:`App` and
:class:`InspectionMixin` and then call the
:meth:`InspectionMixin.Init` method from the app's
:meth:`AppConsole.OnInit` method.

Make the event binding that will activate the InspectionFrame window.

:param `config`: A :class:`Config` object to be used to store layout
    and other info to when the inspection frame is closed.
    This info will be restored the next time the inspection
    frame is used.
:param `locals`: A dictionary of names to be added to the PyCrust
    namespace.
:param boolean `alt`: use alt in the short cut sequence
:param boolean `cmd`: use ctrl/cmd in the short cut sequence
:param boolean `shift`: use shift in the short cut sequence
:param string `keyCode`: the key code for the short cut sequence

InitInspection(self, pos=wx.DefaultPosition, size=wx.Size(850,700), config=None, locals=None, alt=True, cmd=True, shift=False, keyCode=ord('I'))

Show the Inspection tool, creating it if necessary, setting it
to display the widget under the cursor.

The :class:`InspectionTool` is a singleton that manages creating and
showing an :class:`InspectionFrame`.

Init is used to set some parameters that will be used later
when the inspection tool is shown.  Suitable defaults will be
used for all of these parameters if they are not provided.

:param `pos`:   The default position to show the frame at
:param `size`:  The default size of the frame
:param `app`:  A reference to the :class:`App` object.

Init(self, pos=wx.DefaultPosition, size=wx.Size(850,700), config=None, locals=None, app=None)

Creates the inspection frame if it hasn't been already, and
raises it if necessary.

:param `selectObj`: Pass a widget or sizer to have that object be
             preselected in widget tree.
:param boolean `refreshTree`: rebuild the widget tree, default False

# Name:        wx.lib.mixins.listctrl
# Purpose:     Helpful mix-in classes for wxListCtrl
#
#
#
# o ListCtrlSelectionManagerMix untested.
#
#
# o wxColumnSorterMixin -> ColumnSorterMixin
# o wxListCtrlAutoWidthMixin -> ListCtrlAutoWidthMixin
# ...
# 13/10/2004 - Pim Van Heuven (pim@think-wize.com)
# o wxTextEditMixin: Support Horizontal scrolling when TAB is pressed on long
#       ListCtrls, support for WXK_DOWN, WXK_UP, performance improvements on
#       very long ListCtrls, Support for virtual ListCtrls
#
# 15-Oct-2004 - Robin Dunn
# o wxTextEditMixin: Added Shift-TAB support
#
# 2008-11-19 - raf <raf@raf.org>
# o ColumnSorterMixin: Added GetSortState()
#

This is a mixin for ListCtrl which add a checkbox in the first
column of each row. It is inspired by limodou's CheckList.py(which
can be got from his NewEdit) and improved:

    - You can just use InsertStringItem() to insert new items;

    - Once a checkbox is checked/unchecked, the corresponding item
      is not selected;

    - You can use SetItemData() and GetItemData();

    - Interfaces are changed to OnCheckItem(), IsChecked(),
      CheckItem().

You should not set a imagelist for the ListCtrl once this mixin is used.

WARNING: This class is obsolete as wx.ListCtrl now includes nearly the same
functionality.

__init__(self, check_image=None, uncheck_image=None, imgsz=(16,16))

A mixin class that handles sorting of a wx.ListCtrl in REPORT mode when
the column header is clicked on.

There are a few requirements needed in order for this to work genericly:

  1. The combined class must have a GetListCtrl method that
     returns the wx.ListCtrl to be sorted, and the list control
     must exist at the time the wx.ColumnSorterMixin.__init__
     method is called because it uses GetListCtrl.

  2. Items in the list control must have a unique data value set
     with list.SetItemData.

  3. The combined class must have an attribute named itemDataMap
     that is a dictionary mapping the data values to a sequence of
     objects representing the values in each column.  These values
     are compared in the column sorter to determine sort order.

Interesting methods to override are GetColumnSorter,
GetSecondarySortValues, and GetSortImages.  See below for details.

Returns a callable object to be used for comparing column values when sorting.

Returns a list of column widths.  Can be used to help restore the current
view later.

Returns a tuple of 2 values to use for secondary sort values when the
items in the selected column match equal.  The default just returns the
item data values.

Returns a tuple of image list indexesthe indexes in the image list for an image to be put on the column
header when sorting in descending order.

Return a tuple containing the index of the column that was last sorted
and the sort direction of that column.
Usage:
col, ascending = self.GetSortState()
# Make changes to list items... then resort
self.SortListItems(col, ascending)

Callback called after sort order has changed (whenever user
clicked column header).

Sort the list on demand.  Can also be used to set the sort column and order.

A mix-in class that automatically resizes the last column to take up
the remaining width of the wx.ListCtrl.

This causes the wx.ListCtrl to automatically take up the full width of
the list, without either a horizontal scroll bar (unless absolutely
necessary) or empty space to the right of the last column.

NOTE:    This only works for report-style lists.

WARNING: If you override the EVT_SIZE event in your wx.ListCtrl, make
         sure you call event.Skip() to ensure that the mixin's
         _OnResize method is called.

This mix-in class was written by Erik Westra <ewestra@wave.co.nz>

Resize the last column appropriately.

If the list's columns are too wide to fit within the window, we use
a horizontal scrollbar.  Otherwise, we expand the right-most column
to take up the remaining free space in the list.

This method is called automatically when the wx.ListCtrl is resized;
you can also call it yourself whenever you want the last column to
be resized appropriately (eg, when adding, removing or resizing
columns).

'minWidth' is the preferred minimum width for the last column.

Specify which column that should be autosized.  Pass either
'LAST' or the column number.  Default is 'LAST'.

Mixin that defines a platform independent selection policy

As selection single and multi-select list return the item index or a
list of item indexes respectively.

Editra Control Library: ListRowHighlighter
Mixin class that handles automatic background highlighting of alternate
rows in the a ListCtrl. The background of the rows are highlighted
automatically as items are added or inserted in the control based on the
mixins Mode and set Color. By default the Even rows will be highlighted with
the systems highlight color.

Initialize the highlighter mixin
@keyword color: Set a custom highlight color (default uses system color)
@keyword mode: HIGHLIGHT_EVEN (default) or HIGHLIGHT_ODD

Set the color used to highlight the rows. Call :meth:`RefreshRows` after
this if you wish to update all the rows highlight colors.
@param color: wx.Color or None to set default

Set the highlighting mode to either HIGHLIGHT_EVEN or to
HIGHLIGHT_ODD. Call :meth:`RefreshRows` afterwards to update the list
state.
@param mode: HIGHLIGHT_* mode value

A mixin class that enables any text in any column of a
multi-column listctrl to be edited by clicking on the given row
and column.  You close the text editor by hitting the ENTER key or
clicking somewhere else on the listctrl. You switch to the next
column by hiting TAB.

To use the mixin you have to include it in the class definition
and call the __init__ function::

    class TestListCtrl(wx.ListCtrl, TextEditMixin):
        def __init__(self, parent, ID, pos=wx.DefaultPosition,
                     size=wx.DefaultSize, style=0):
            wx.ListCtrl.__init__(self, parent, ID, pos, size, style)
            TextEditMixin.__init__(self)

Authors:     Steve Zatz, Pim Van Heuven (pim@think-wize.com)

Catch the TAB, Shift-TAB, cursor DOWN/UP key code
so we can open the editor at the next column (if any).

Examine the click and double
click events to see if a row has been click on twice. If so,
determine the current row and columnn and open the editor.

Returns list of item indexes of given state (selected by defaults) 

Ensures the item the mouse is pointing at is selected before a popup.

Works with both single-select and multi-select lists.

'The CheckListCtrlMixin class has been made redundant by new checkbox features in the wx.ListCtrl class. It is advised to switch your code to use that instead of this mixin.'

# Name:        wx.lib.mixins.rubberband
# Purpose:     A mixin class for doing "RubberBand"-ing on a window.
#
# Author:      Robb Shecter and members of wxPython-users
#
# Created:     11-September-2002
# Copyright:   (c) 2002 by db-X Corporation
# Tags:        phoenix-port
#
# o Tested, but there is an anomaly between first use and subsequent uses.
#   First use is odd, subsequent uses seem to be OK. Init error?
#   -- No, the first time it uses an aspect ratio, but after the reset it doesn't.
#

A stretchable border which is drawn on top of an
image to define an area.

Return (x0, y0, x1, y1) or None if
no drawing has yet been done.

Convert a box specification to an extent specification.
I put this into a separate function after I realized that
I had been implementing it wrong in several places.

Return a position number in the range 0 .. 7 to indicate
where on the box border the point is.  The layout is:

          0    1    2
          7         3
          6    5    4

Convert any negative measurements in the current
box to positive, and adjust the origin.

Return True if the point is on the outside edge
of the box.  The thickness defines how thick the
edge should be.  This is necessary for HCI reasons:
For example, it's normally very difficult for a user
to maneuver the mouse onto a one pixel border.

treemixin.py

This module provides three mixin classes that can be used with tree
controls:

- VirtualTree is a class that, when mixed in with a tree control,
  makes the tree control virtual, similar to a ListCtrl in virtual mode.
  A virtual tree control builds the tree itself by means of callbacks,
  so the programmer is freed from the burden of building the tree herself.

- DragAndDrop is a mixin class that helps with dragging and dropping of
  items. The graphical part of dragging and dropping tree items is done by
  this mixin class. You only need to implement the OnDrop method that is
  called when the drop happens.

- ExpansionState is a mixin that can be queried for the expansion state of
  all items in the tree to restore it later.

All mixin classes work with wx.TreeCtrl, wx.gizmos.TreeListCtrl,
and wx.lib.customtreectrl.CustomTreeCtrl. They can be used together or
separately.

The VirtualTree and DragAndDrop mixins force the wx.TR_HIDE_ROOT style.

.. moduleauthor:: Frank Niessink <frank@niessink.com>

License: wxWidgets license
Version: 1.1
Date: 24 September 2007

ExpansionState is based on code and ideas from Karsten Hilbert.
Andrea Gavana provided help with the CustomTreeCtrl integration.

# Name:        treemixin.py
# Purpose:     This module provides three mixin classes that can be used with tree
#              controls
#
# Author:
#
# Created:
# RCS-ID:
# Date:        24 September 2007
# Copyright:
# Version:     1.1
# Licence:     wxWidgets license

This is a mixin class that can be used to easily implement
dragging and dropping of tree items. It can be mixed in with
wx.TreeCtrl, wx.gizmos.TreeListCtrl, or wx.lib.customtree.CustomTreeCtrl.

To use it derive a new class from this class and one of the tree
controls, e.g.::

  class MyTree(DragAndDrop, wx.TreeCtrl):
      # Other code here

You *must* implement OnDrop. OnDrop is called when the user has
dropped an item on top of another item. It's up to you to decide how
to handle the drop. If you are using this mixin together with the
VirtualTree mixin, it makes sense to rearrange your underlying data
and then call RefreshItems to let the virtual tree refresh itself. 

This function must be overloaded in the derived class.
dragItem is the item being dragged by the user. dropItem is the
item dragItem is dropped upon. If the user doesn't drop dragItem
on another item, dropItem equals the (hidden) root item of the
tree control. 

This is a mixin class that can be used to save and restore
the expansion state (i.e. which items are expanded and which items
are collapsed) of a tree. It can be mixed in with wx.TreeCtrl,
wx.gizmos.TreeListCtrl, or wx.lib.customtree.CustomTreeCtrl.

  class MyTree(ExpansionState, wx.TreeCtrl):

By default, ExpansionState uses the position of tree items in the tree
to keep track of which items are expanded. This should be sufficient
for the simple scenario where you save the expansion state of the tree
when the user closes the application or file so that you can restore
the expansion state when the user start the application or loads that
file for the next session.

If you need to add or remove items between the moments of saving and
restoring the expansion state (e.g. in case of a multi-user application)
you must override GetItemIdentity so that saving and loading of the
expansion doesn't depend on the position of items in the tree, but
rather on some more stable characteristic of the underlying domain
object, e.g. a social security number in case of persons or an isbn
number in case of books. 

GetExpansionState() -> list of expanded items. Expanded items
are coded as determined by the result of GetItemIdentity(item). 

a database key. 

SetExpansionState(listOfExpandedItems). Expands all tree items
whose identity, as determined by GetItemIdentity(item), is present
in the list and collapses all other tree items. 

This class attempts to hide the differences in API between the
different tree controls that are part of wxPython. 

GetItemImage(self, item, which=wx.TreeItemIcon_Normal, column=-1)

HitTest returns a two-tuple (item, flags) for tree controls
without columns and a three-tuple (item, flags, column) for tree
controls with columns. Our caller can indicate this method to
always return a three-tuple no matter what tree control we're mixed
in with by specifying the optional argument 'alwaysReturnColumn'
to be True. 

SetItemImage(self, item, imageIndex, which=wx.TreeItemIcon_Normal, column=-1)

This class provides methods that are not part of the API of any
tree control, but are convenient to have available. 

This is a mixin class that can be used to allow for virtual tree
controls. It can be mixed in with wx.TreeCtrl, wx.gizmos.TreeListCtrl,
wx.lib.customtree.CustomTreeCtrl.

  class MyTree(VirtualTree, wx.TreeCtrl):

VirtualTree uses several callbacks (such as OnGetItemText) to
retrieve information needed to construct the tree and render the
items. To specify what item the callback needs information about,
the callback passes an item index. Whereas for list controls a simple
integer index can be used, for tree controls indicating a specific
item is a little bit more complicated. See below for a more detailed
explanation of the how index works.

Note that VirtualTree forces the wx.TR_HIDE_ROOT style.

In your subclass you *must* override OnGetItemText and
OnGetChildrenCount. These two methods are the minimum needed to
construct the tree and render the item labels. If you want to add
images, change fonts our colours, etc., you need to override the
appropriate OnGetXXX method as well.

About indices: your callbacks are passed a tuple of integers that
identifies the item the VirtualTree wants information about. An
empty tuple, i.e. (), represents the hidden root item.  A tuple with
one integer, e.g. (3,), represents a visible root item, in this case
the fourth one. A tuple with two integers, e.g. (3,0), represents a
child of a visible root item, in this case the first child of the
fourth root item.

This function *must* be overloaded in the derived class.
It should return the number of child items of the item with the
provided index. If index == () it should return the number of
root items. 

This function may be overloaded in the derived class. It
should return the wx.Colour to be used as background colour for
the specified item. 

This function may be overloaded in the derived class, but
that only makes sense when this class is mixed in with a tree
control that supports checkable items, i.e. CustomTreeCtrl.
This method should return whether the item is to be checked.
Note that OnGetItemType should return 1 (checkbox) or 2
(radiobutton) for this item. 

should return the wx.Font to be used for the specified item. 

should return the index of the image to be used. Don't forget
to associate an ImageList with the tree control. 

OnGetItemImage(self, index, which=wx.TreeItemIcon_Normal, column=0)

This function *must* be overloaded in the derived class. It
should return the string containing the text of the specified
item. 

should return the wx.Colour to be used as text colour for the
specified item. 

This method should return whether the item is to be normal (0,
the default), a checkbox (1) or a radiobutton (2).
Note that OnGetItemChecked needs to be implemented as well; it
should return whether the item is actually checked. 

Refresh the children of item, reusing as much of the
existing items in the tree as possible. 

The Object Graphics Library provides for simple drawing and manipulation
of 2D objects.

# Name:         basic.py
# Purpose:      The basic OGL shapes
#
# Author:       Pierre Hjälm (from C++ original by Julian Smart)
#
# Created:      2004-05-08
# Copyright:    (c) 2004 Pierre Hjälm - 1998 Julian Smart
# Tags:         phoenix-port, unittest, py3-port, documented

:param int `type`: the type

 ======================================== ==================================
 Arrow head type                          Description
 `ARROW_HOLLOW_CIRCLE`                    a hollow circle
 `ARROW_FILLED_CIRCLE`                    a filled circle
 `ARROW_ARROW`                            an arrow
 `ARROW_SINGLE_OBLIQUE`                   a single oblique
 `ARROW_DOUBLE_OBLIQUE`                   a double oblique
 `ARROW_METAFILE`                         custom, define in metafile

:param int `end`: end of arrow head ???
:param float `size`: size of arrow head
:param float `dist`: dist ???
:param string `name`: name of arrow head
:param `mf`: mf ???
:param `arrowId`: id of arrow head

__init__(self, type = 0, end = 0, size = 0.0, dist = 0.0, name = "", mf = None, arrowId = -1)

Set the arrow size.

:param `size`: size in points???

:note: if a custom arrow is used size is used to scale the arrow???

The :class:`CircleShape` class is an :class:`EllipseShape` whose width
and height are the same.

Get the perimeter point.

:param `x1`: ???
:param `y1`: ???
:param `x2`: ???
:param `y2`: ???
:returns: ???

The :class:`CompositeShape` is a shape with a list of child objects, and a
list of size and positioning constraints between the children.

Add a shape to the composite. If addAfter is not None, the shape
will be added after addAfter.

:param `child`: an instance of :class:`~lib.ogl.Shape`
:param `addAfter`: an instance of :class:`~lib.ogl.Shape`

Adds a constraint to the composite.

:param `constraint`: an instance of :class:`~lib.ogl.Shape`

Add a constraint of the given type to the composite.

:param `type`: see :class:`ConstraintType` for valid types
:param `constraining`: the constraining :class:`Shape`
:param `constrained`: the constrained :class:`Shape`

Calculates the size and position of the composite based on
child sizes and positions.

Constrain the children.

:returns: True if constrained otherwise False

Check if division is descendant.

:param `division`: division to check
:returns: `True` if division is a descendant of this container.

Fully disconnect this shape from parents, children, the
canvas, etc.

Deletes constraint from composite.

:param `constraint`: the constraint to delete

This function deletes constraints which mention the given child.

Used when deleting a child from the composite.

Finds the constraint with the given id.

:param `cId`: The constraint id to find.

:returns: None or a tuple of the constraint and the actual composite the
 constraint was in, in case that composite was a descendant of
 this composit.

Finds the image used to visualize a container. This is any child of
the composite that is not in the divisions list.

Makes this composite into a container by creating one child
DivisionShape.

The right click handler.

:note: If we get a ctrl-right click, this means send the message to
 the division, so we can invoke a user interface for dealing
 with regions.

Recomputes any constraints associated with the object. If `False` is
returned, the constraints could not be satisfied (there was an
inconsistency).

Removes the child from the composite and any constraint
relationships, but does not delete the child.

Removes the child from the constraints.

Set the size.

:param `w`: the width
:param `h`: the height
:param `recursive`: size the children recursively

The :class:`Constraint` class helps specify how child shapes are laid out
with respect to siblings and parents.

Return `True` if a and b are approximately equal (for the purposes
of evaluating the constraint).

:param `a`: ???
:param `b`: ???

Sets the horizontal and vertical spacing for the constraint.

:param `x`: the x position
:param `y`: the y position

:param `theType`: one of the following
 ====================================== ================================
 Constraint type                        Description
 `CONSTRAINT_CENTRED_VERTICALLY`        Centered vertically
 `CONSTRAINT_CENTRED_HORIZONTALLY`      Centered horizontally
 `CONSTRAINT_CENTRED_BOTH`              Centered in both directions
 `CONSTRAINT_LEFT_OF`                   Center left of
 `CONSTRAINT_RIGHT_OF`                  Center right of
 `CONSTRAINT_ABOVE`                     Center above
 `CONSTRAINT_BELOW`                     Center below
 `CONSTRAINT_ALIGNED_TOP`               Align top
 `CONSTRAINT_ALIGNED_BOTTOM`            Align bottom
 `CONSTRAINT_ALIGNED_LEFT`              Align left
 `CONSTRAINT_ALIGNED_RIGHT`             Align right
 `CONSTRAINT_MIDALIGNED_TOP`            Middle align top
 `CONSTRAINT_MIDALIGNED_BOTTOM`         Middle align bottom
 `CONSTRAINT_MIDALIGNED_LEFT`           Middle align left
 `CONSTRAINT_MIDALIGNED_RIGHT`          Middle align right

:param `theName`: the name for the constraint
:param `thePhrase`: the descriptive phrase

:param `theCanvas`: a :class:`~lib.ogl.Canvas`
:param `object`: the shape, instance of :class:`~lib.ogl.Shape`
:param float `size`: the size
:param float `the_xoffset`: the x position
:param float `the_yoffset`: the y position
:param int `the_type`: one of the following types ???

 Control point type                       Description
 `CONTROL_POINT_VERTICAL`                 Vertical
 `CONTROL_POINT_HORIZONTAL`               Horizontal
 `CONTROL_POINT_DIAGONAL`                 Diagonal

__init__(self, theCanvas, object, size, the_xoffset, the_yoffset, the_type)

Get the attachment position.

:param `attachment`: the attachment ???
:param `nth`: get nth attachment ???
:param `no_arcs`: ???
:param `line`: ???

GetAttachmentPosition(self, attachment, nth = 0, no_arcs = 1, line = None)

__init__(self, the_canvas, object, size, the_xoffset, the_yoffset, the_type)

A :class:`DivisionShape` class is a composite with special properties,
to be used for containment. It's a subdivision of a container.
A containing node image consists of a composite with a main child shape
such as rounded rectangle, plus a list of division objects.
It needs to be a composite because a division contains pieces
of diagram.

:note: A container has at least one wxDivisionShape for consistency.
 This can be subdivided, so it turns into two objects, then each of
 these can be subdivided, etc.

Adjust a side.

:param `left`: desired left position ???
:param `test`: if `True` just a test
:returns: `False` if it's not physically possible to adjust it to
 this point.

:param `right`: desired right position ???

:param `top`: desired top position ???

Divide this division into two further divisions.

:param `direction`: `wx.HORIZONTAL` for horizontal or `wx.VERTICAL` for
 vertical division.

Return the colour used for drawing the left side of the division.

Return the colour used for drawing the top side of the division.

Resize adjoining divisions at the given side.

:param `side`: can be one of

======================= =======================
Side option             Description
`DIVISION_SIDE_NONE`    no side
`DIVISION_SIDE_LEFT`    Left side
`DIVISION_SIDE_TOP`     Top side
`DIVISION_SIDE_RIGHT`   Right side
`DIVISION_SIDE_BOTTOM`  Bottom side

:param `newPos`: new position
:param `test`: if `True`, just see whether it's possible for each
 adjoining region, returning `False` if it's not.

Sets the side which the handle appears on.

:param `side`: Either DIVISION_SIDE_LEFT or DIVISION_SIDE_TOP.

:param `recursive`: `True` recurse all children

The :class:`EllipseShape` class behaves similarly to the
:class`RectangleShape` but is elliptical.

Get attachment position.

:param `x1`: the x1 position
:param `y1`: the y1 position
:param `x2`: the x2 position
:param `y2`: the y2 position

:param `x`: the width
:param `y`: the height
:recursive: not used

:param `parent`: the parent an instance of :class:`Line`
:param `region`: the shape region an instance of :class:`~lib.ogl.ShapeRegion`
:param `w`: width in points
:param `h`: height in points

:param `object`: not used ???
:param float `x`: the x position
:param float `y`: the y position
:param int `the_type`: one of the following types

__init__(self, theCanvas = None, object = None, size = 0.0, x = 0.0, y = 0.0, the_type = 0)

The LineShape class may be attached to two nodes, it may be segmented,
in which case a control point is drawn for each joint.

A :class:`LineShape` may have arrows at the beginning, end and centre.

Add an arrow (or annotation) to the line.

:param `type`: an arrow head type, one of the following

:param `end`: may be one of the following

 `ARROW_POSITION_END`                     arrow appears at the end
 `ARROW_POSITION_START`                   arrow appears at the start

:param `size`: specifies the length of the arrow
:param `xOffset`: specifies the offset from the end of the line
:param `name`: specifies a name
:param `mf`: mf can be a wxPseduoMetaFile, perhaps loaded from a simple Windows
  metafile.
:param `arrowId`: the id for the arrow

AddArrow(self, type, end = ARROW_POSITION_END, size = 10.0, xOffset = 0.0, name = "", mf = None, arrowId = -1)

Add an arrowhead in the position indicated by the reference list
of arrowheads, which contains all legal arrowheads for this line, in
the correct order. E.g.

Reference list:      a b c d e
Current line list:   a d

Add c, then line list is: a c d.

If no legal arrowhead position, return FALSE. Assume reference list
is for one end only, since it potentially defines the ordering for
any one of the 3 positions. So we don't check the reference list for
arrowhead position.

:param `arrow`: an instance of :class:`ArrowHead`
:param `referenceList`: ???
:param `end`: ???

Delete the arrow with the given name.

:param `name`: name of arrow to delete

Delete the arrows at the specified position, or at any position if position is -1.

:param `end`: position to clear arrow from

Delete arrowhead by position and name.

if position is -1, matches any position.

:param `position`: position of arrow to delete or -1

Delete arrowhead by id.

:param `arrowId`: id of arrow to delete

Line is not draggable.

:note: This is really to distinguish between lines and other images.
 For lines we want to pass drag to canvas, since lines tend to prevent
 dragging on a canvas (they get in the way.)

Draw the given arrowhead (or annotation).

:param `dc`: an instance of :class:`wx.MemoryDC`
:param `arrow`: an instannce of :class:`ArrowHead`
:param `XOffset`: the x offset ???
:param `proportionalOffset`: ???

Format one region at this position.

:param `dc`: an instance of :class:`~lib.ogl.ShapeRegion`

Erase one region at this position.

Find arrowhead by position and name.

:param `position`: position of arrow to find or -1
:param `name`: name of arrow to find

Finds the x, y points at the two ends of the line.

This function can be used by e.g. line-routing routines to
get the actual points on the two node images where the lines will be
drawn to / from.

Find which position we're talking about.

:param `x`: x position
:param `y`: y position

:returns: ARROW_POSITION_START or ARROW_POSITION_MIDDLE or ARROW_POSITION_END.

Find the horizontal width for drawing a line with arrows in
minimum space. Assume arrows at end only.

Find the position of the line on the given object.

Specify whether incoming or outgoing lines are being considered
with incoming.

:param `image`: a node image
:param `incoming`: True to get incoming lines ???

:returns: nth line, number of lines ???

Format a text string according to the region size, adding
strings with positions to region text list.

:param str `s`: the text string
:param int `i`: index to the region to be used???

Get the alignment orientation.

:param `isEnd`: if True get the type for the begin, else for the end ???

Get the alignment type.

Get the visible endpoints of the lines for drawing between two objects.

Get the reference point for a label.

:param `position`: 0 = middle, 1 = start, 2 = end, Region x and y are offsets from this.

Find the next control point in the line after the start / end point,
depending on whether the shape is at the start or end.

:param `shape`: an instance of :class:`~lib.ogl.Shape` ???

Insert a control point at an optional given position.

:param `point`: an optional point, otherwise will use _lineControlPoints

Make a given number of control points.

:param int `n`: number of control points, minimum of two

OnLabelMovePre(self, dc, labelShape, x, y, old_x, old_y, display)

The move link handler, called when a connected object has moved, to move the link to
correct position.

OnSizingDragLeft(self, pt, draw, x, y, keys = 0, attachment = 0)

Overridden select, to create / delete temporary label-moving objects.

Set the alignment orientation.

:param `isEnd`: True or False ???
:param `isHoriz`: True of False ???

Set the alignment type.

:param `isEnd`: if True set the type for the begin, else for the end ???
:param `alignType`: one of the following

 `LINE_ALIGNMENT_HORIZ`                   Align horizontally
 `LINE_ALIGNMENT_VERT`                    Align vertically
 `LINE_ALIGNMENT_TO_NEXT_HANDLE`          Align to next handle
 `LINE_ALIGNMENT_NONE`                    vertical by default

Specify which object attachment points should be used at each end of the line.

:param `from_attach`: the from points ???
:param `to_attach`: the to points ???

Set the end positions of the line.

:param: `x1`: x1 position
:param: `y1`: y1 position
:param: `x2`: x2 position
:param: `y2`: y2 position

Set whether to ignore offsets from the end of the line when drawing.

Specifies whether a spline is to be drawn through the control points.

:param boolean `spline`: True draw a spline through control points.

Straighten verticals and horizontals.

:param `dc`: an instance of :class:`wx.MemoryDC` or None

:param `vertext`: the vertex

__init__(self, theCanvas, object, size, vertex, the_xoffset, the_yoffset)

Calculate what new size would be, at end of resize.

:param `x`: x ???
:param `y`: y ???

The :class:`PolygonShape` class shape is defined by a number of points
passed to the object's constructor. It can be used to create new shapes
such as diamonds and triangles.

Does not follow above statement, should it? or is Create called
automagically?

Add a control point after the given point.

:param `pos`: position of point

Recalculates the centre of the polygon, and
readjusts the point offsets accordingly.
Necessary since the centre of the polygon
is expected to be the real centre of the bounding
box.

Takes a list of :class:`wx.Points` or tuples; each point is an offset
from the centre.

Delete the given control point.

Rotate about the given axis by the given amount in radians.

:param `theta`: the theta

Set the size

:param `new_width`: the width
:param `new_height`: the height
:param `recursive`: not used

If we've changed the shape, must make the original points match the
working points with this function.

Menu()
Menu(style)
Menu(title, style=0)

A menu is a popup (or pull down) list of items, one of which may be
selected before the menu goes away (clicking elsewhere dismisses the
menu).

The :class:`wx.RectangleShape` class has rounded or square corners.

:param float `w`: the width
:param float `h`: the height

Set the radius of the rectangle's rounded corners.

:param `rad`: If the radius is zero, a non-rounded rectangle will be
 drawn. If the radius is negative, the value is the proportion of the
 smaller dimension of the rectangle.

The :class:`Shape` is the base class for OGL shapes.

The :class:`Shape` is the top-level, abstract object that all other objects
are derived from. All common functionality is represented by :class:`Shape`
members, and overridden members that appear in derived classes and have
behaviour as documented for :class:`Shape`, are not documented separately.

:param `canvas`: an instance of :class:`~lib.ogl.Canvas`

Add a line between this shape and the given other shape, at the
specified attachment points.

:param `line`: the line an instance of :class:`~lib.ogl.LineShape`
:param `other`: the other shape, an instance of :class:`Shape`
:param `attachFrom`: the attachment from point ???
:param `attachTo`: the attachment to point ???
:param `positionFrom`: the from position
:param `positionTo`: the to position

:note: The position in the list of lines at each end can also be
 specified, so that the line will be drawn at a particular point on
 its attachment point.

AddLine(self, line, other, attachFrom = 0, attachTo = 0, positionFrom = -1, positionTo = -1)

Add the shape to the canvas's shape list.

:param `theCanvas`: an instance of :class:`~lib.ogl.Canvas`
:param `addAfter`: if non-NULL, will add the shape after this shape

Apply the line ordering in linesToSort to the shape, to reorder
the way lines are attached.

Set the shape's internal canvas pointer to point to the given canvas.

Return TRUE if pt1 is less than or equal to pt2, in the sense
that one point comes before another on an edge of the shape.

attachment is the attachment point (side) in question.

This function is used in Shape.MoveLineToNewAttachment to determine
the new line ordering.

Assuming the attachment lies along a vertical or horizontal line,
calculate the position on that point.

:param `pt1`: The first point of the line representing the edge of
 the shape
:param `pt2`: The second point of the line representing the edge of
 the shape
:param `nth`: The position on the edge (for example there may be 6
 lines at this attachment point, and this may be the 2nd line.
:param `noArcs`: The number of lines at this edge.
:param `line`: The line shape.

:note: This function expects the line to be either vertical or horizontal,
 and determines which.

Clear internal custom attachment point shapes (of class
:class:`~lib.ogl.AttachmentPoint`)

Clear the text from the specified text region.

:param `regionId`: the region identifier

Delete the control points (or handles) for the shape.

Does not redraw the shape.

Is shape draggable?

:returns: `True` if the shape may be dragged by the user.

Draw the whole shape and any lines attached to it.

Do not override this function: override OnDraw, which is called
by this function.

Draw the internal graphic of the shape (such as text).

Do not override this function: override OnDrawContents, which
is called by this function.

Draws any lines linked to this shape.

:param `dc`: the device context
:param `attachment`: ???
:param `recurse`: if `True` recurse through the children

Erase the shape.

Does not repair damage caused to other shapes.

Erase the shape contents, that is, the area within the shape's
minimum bounding box.

Erase links attached to this shape, but do not repair damage
caused to other shapes.

Find the actual image ('this' if non-composite) and region id
for the given region name.

:param str `name`: the region name

Get a list of all region names for this image (composite or simple).

Reformat the given text region; defaults to formatting the
default region.

:param `dc`: the device contexr
:param int `i`: the region identifier

Get the number of lines at this attachment position.

:returns: the count of lines at this position

Get the position at which the given attachment point should be drawn.

If attachment isn't found among the attachment points of the shape,
returns None.

Only get the attachment position at the _edge_ of the shape,
ignoring branching mode. This is used e.g. to indicate the edge of
interest, not the point on the attachment branch.

GetAttachmentPositionEdge(self, attachment, nth = 0, no_arcs = 1, line = None)

Get the maximum bounding box for the shape, taking into account
external features such as shadows.

Get the minimum bounding box for the shape, that defines the area
available for drawing the contents (such as text).

Must be overridden.

Get information about where branching connections go.

:returns: `False` if there are no lines at this attachment.

Get branching attachment point.

:param `n`: ???

Get the root point at the given attachment.

`True` if the shape is to be resized from the centre (the centre stands
still), or `False` if from the corner or side being dragged (the other
corner or side stands still)

`True` if the default region will not be shown, `False` otherwise.

Return flags indicating whether the shape is of fixed size in
either direction.

Get the font for the specified text region.

Get the format mode.

:param `regionId`: the region identifier, default=0

Get the zero-based position of line in the list of lines
for this shape.

:param `line`: line to find position for

Get the point at which the line from (x1, y1) to (x2, y2) hits
the shape.

:returns: `False` if the line doesn't hit the perimeter.

Get the region's identifier by name.

:param str `name`: the regions name

:note: This is not unique for within an entire composite, but is unique
 for the image.

Get the region's name.

:note: A region's name can be used to uniquely determine a region within
 an entire composite image hierarchy. See also
 :meth:`~lib.ogl.Shape.SetRegionName`.

Get the sensitivity filter, a bitlist of values.

See :meth:`Shape.SetSensitivityFilter`

Get whether lines should be spaced out evenly at the point they
touch the node (True), or whether they should join at a single point
(False).

Get the colour for the specified text region.

Return the top-most ancestor of this shape (the root of
the composite).

Is image a descendant of this composite.

:param `image`: the image, is this a shape???
:returns: `True` if it is a descendant

Given a point on a canvas, returns `True` if the point was on the
shape, and returns the nearest attachment point and distance from
the given point and target.

Insert the shape at the front of the shape list of canvas.

`True` if the shape is highlighted. Shape highlighting is unimplemented.

`True` if the shape is in a visible state, `False` otherwise.

:note: That this has nothing to do with whether the window is hidden
 or the shape has scrolled off the canvas; it refers to the internal
 visibility flag.

Rotate the standard attachment point from logical
to physical (0 is always North).

:param `logicalAttachment`: ???

Make a list of control points (draggable handles) appropriate to
the shape.

Make the mandatory control points.

For example, the control point on a dividing line should appear even
if the divided rectangle shape's handles should not appear (because
it is the child of a composite, and children are not resizable).

Move the shape to the given position.

:param `display`: if `True` redraw

Move the given line (which must already be attached to the shape)
to a different attachment point on the shape, or a different order
on the same attachment.

Calls Shape.AttachmentSortTest and then
ShapeEvtHandler.OnChangeAttachment.

Make unique names for all the regions in a shape or composite shape.

:param str `parentName`: a prefix for the region names

Rotate the standard attachment point from physical
(0 is always North) to logical (0 -> 1 if rotated by 90 degrees)

:param `physicalAttachment`: ???

Recentre (or other formatting) all the text regions for this shape.

Recomputes any constraints associated with the shape.

Normally applicable to CompositeShapes only, but harmless for
other classes of Shape.

Remove the shape from the canvas.

Remove the given line from the shape's list of attached lines.

:param `line`: an instance of :class:`~lib.ogl.LineShape`

Reset the positions of the control points (for instance when the
shape's shape has changed).

Select or deselect the given shape, drawing or erasing control points
(handles) as necessary.

:param `select`: `True` to select

Set the attachment mode.

:param `mode`: if `True` attachment points will be significant when
 drawing lines to and from this shape. If `False` lines will be drawn
 as if to the centre of the shape.

Set the canvas, identical to Shape.Attach.

Specify whether the shape is to be resized from the centre (the
centre stands still) or from the corner or side being dragged (the
other corner or side stands still).

Set the shape to be draggable or not draggable.

:param `drag`: if `True` make shape draggable
:param `recursive`: if `True` recurse through children

Set the drawHandles flag for this shape and all descendants.

:param `drawH`: if `True` (the default), any handles (control points)
 will be drawn. Otherwise, the handles will not be drawn.

Set the event handler for this shape.

:param `handler`: an instance of :class:`ShapeEvtHandler`

Set the shape to be fixed size.

Set the font for the specified text region.

:param `the_font`: an instance of :class:`wx.Font` ???

Set the format mode of the region.

:param `mode`: can be a bit list of the following

============================== ==============================
Format mode                    Description
`FORMAT_NONE`                  No formatting
`FORMAT_CENTRE_HORIZ`          Horizontal centring
`FORMAT_CENTRE_VERT`           Vertical centring

Set the highlight for a shape. Shape highlighting is unimplemented.

Set whether a shape that resizes should not change the aspect ratio
(width and height should be in the original proportion).

Set the name for this region.

:param str `name`: the name to set

:note: The name for a region is unique within the scope of the whole
 composite, whereas a region id is unique only for a single image.

Set the shape to be sensitive or insensitive to specific mouse

:param `sens`: is a bitlist of the following:

========================== ===================
Mouse operation            Description
`OP_CLICK_LEFT`            left clicked
`OP_CLICK_RIGHT`           right clicked
`OP_DRAG_LEFT`             left drag
`OP_DRAG_RIGHT`            right drag
`OP_ALL`                   all of the above

Set the shadow mode (whether a shadow is drawn or not).

:param `mode`: can be one of the following:

=============================== ===========================
Shadow mode                     Description
`SHADOW_NONE`                   No shadow (the default)
`SHADOW_LEFT`                   Shadow on the left side
`SHADOW_RIGHT`                  Shadow on the right side

Set the shape's size.

Indicate whether lines should be spaced out evenly at the point
they touch the node.

:param `sp`: if `True` space out evently, else they should join at a
 single point.

Set the colour for the specified text region.

:param str `the_colour`: a valid colour name,
 see :class:`wx.ColourDatabase`

Reorder the lines coming into the node image at this attachment
position, in the order in which they appear in linesToSort.

Any remaining lines not in the list will be added to the end.

:param `parent`: parent window
:param integer `id`: window identifier. A value of -1 indicates a default value
 chosen by either the windowing system or wxPython, depending on platform
:param integer `style`: the underlying :class:`wx.Window` style
:param str `name`: the window name

__init__(self, parent = None, id = -1, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.BORDER, name = "ShapeCanvas")

Add a shape to canvas.

:param `object`: the :class:`~lib.ogl.Shape` instance to add
:param `addAfter`: None or the :class:`~lib.ogl.Shape` after which
 above shape is to be added.

Update the buffer with the background and redraw the full diagram.

Find shape at given position.

:param `info`: ???
:param `notObject`: ???

Insert a shape to canvas.

:param `object`: the :class:`~lib.ogl.Shape` instance to insert

The paint handler, uses :class:`BufferedPaintDC` to draw the
buffer to the screen.

The size handler, it initializes the buffer to the size of the window.

Remove a shape from canvas.

:param `object`: the :class:`~lib.ogl.Shape` instance to be removed

Set the diagram associated with this canvas.

:param `diag`: an instance of :class:`~lib.ogl.Diagram`

:param `pref`: the previous event handler, an instance of
 :class:`ShapeEvtHandler` ???
:param `shape`: the shape, an instance of :class:`Shape`

Set previous event handler.

:param `handler`: the previous handler, an instance of

Set associated shape

:param `sh`:  the shape, an instance of :class:`Shape`

:param `region`: a parent region or None???

Get the actual colour object from the :class:`wx.ColourDatabase`.

Get actual pen.

:note: Returns NULL if the pen is invisible
 (different to pen being transparent; indicates that
 region boundary should not be drawn.)

Set the colour.

:param str `col`: a valid colour name,

Set the minimum size.

:param `w`: the minimum width
:Param `h`: the minimum height

Set the pen colour.

Set the pen style.

:param `style`: the style, see :class:`wx.Pen`

Set the position.

:param `xp`: the x position
:Param `yp`: the y position

Set the proportions.

:param `xp`: the x region proportion
:Param `yp`: the y region proportion

:param int `the_x`: the x position
:param int `the_y`: the y position
:param str `the_line`: the text

The :class:`TextShape` class like :class:`wx.RectangleShape` but only the
text is displayed.

:param `width`: the width
:param `height`: the height

Centre a text

:param `dc`: the :class:`wx.MemoryDC`
:param `text_list`: a list of texts
:param `xpos`: the x position
:param `ypos`: the y position
:param `width`: the width of the box???
:param `height`: the height of the box???
:param `formatMode`: one of the format modes, can be combined in a bit list

  Format mode name                         Description
  `FORMAT_NONE`                            Left justification
  `FORMAT_CENTRE_HORIZ`                    Centre horizontally
  `FORMAT_CENTRE_VERT`                     Centre vertically
  `FORMAT_SIZE_TO_CONTENTS`                Resize shape to contents

CentreText(dc, text_list, xpos, ypos, width, height, formatMode)

Check for line intersection

:param `x1`: x1 position
:param `y1`: y1 position
:param `x2`: x2 position
:param `y2`: y2 position
:param `x3`: x3 position
:param `y3`: y3 position
:param `x4`: x4 position
:param `y4`: y4 position

:returns: a length ratio and a k line???

Draw arc to ellipse

:param `width1`: width
:param `height1`: height

:returns: ellipse points ???

Draw formatted text

DrawFormattedText(dc, text_list, xpos, ypos, width, height, formatMode)

Find the end for a box

:param `width`: the width of the box
:param `height`: the height of the box

:returns: the end position

Find end for a circle

:param `radius`: radius

:returns: end position

Find the end for a polyline

:param `xvec`: x vector ???
:param `yvec`: y vector ???

Format a text

:param `text`: the text to format
:param `height`: the height of the box??? it is not used in the code!

:returns: a list of strings fitting in the box

Get point on arrow

:param `length`: length ???
:param `width`: width ???

:returns: point on line

Get the centred text extend

:param `text_list`: a list of text lines
:param `xpos`: unused
:param `ypos`: unused
:param `width`: unused
:param `height`: unused

:returns: maximum width and the height

GetCentredTextExtent(dc, text_list, xpos=0, ypos=0, width=0, height=0)

Get point on a line

Straighten a line in graphics

:param `point1`: a point list???
:param `point2`: a point list???

Initialize OGL.

:note: This creates some pens and brushes that the OGL library uses.
 It should be called after the app object has been created, but
 before OGL is used.

Hittest for a polyline

:returns: True or False

Check if values are roughly equal

:param `val1`: the first value to check
:param `val2`: the second value to check
:param `tol`: the tolerance, defaults to 0.00001

Helper function.

:param `contains`: the containing shape
:param `contained`: the contained shape
:returns: `True` if 'contains' wholly contains 'contained'

[[1, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a223050>], [2, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a2231d0>], [3, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a223250>], [4, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a226410>], [5, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a226490>], [6, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a226510>], [7, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a226590>], [8, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a2269d0>], [9, <wx.lib.ogl.composit.ConstraintType object at 0x7fe259dd80d0>], [10, <wx.lib.ogl.composit.ConstraintType object at 0x7fe259dd8150>], [11, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a16ad10>], [12, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a16ad50>], [13, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a16ad90>], [14, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a16ac90>], [15, <wx.lib.ogl.composit.ConstraintType object at 0x7fe25a16add0>]]

# Name:         bmpshape.py
# Purpose:      Bitmap shape
#
#

The :class:`wx.BitmapShape` class draws a bitmap (non-resizable).

Set the associated bitmap.

:param `bitmap`: a :class:`wx.Bitmap` instance

:note: You can delete the bitmap from the calling application, since
 reference counting will take care of holding on to the internal bitmap
 data.

# Name:         _canvas.py
# Purpose:      The canvas class
#
#

# Name:         composit.py
# Purpose:      Composite class
#
#

# Name:         diagram.py
# Purpose:      Diagram class
#
#

The :class:`Diagram` encapsulates an entire diagram, with methods for
drawing. A diagram has an associated :class:`ShapeCanvas`.

Add a shape to the diagram. If addAfter is not None, the shape

:param `object`: an instance of :class:`~lib.ogl.Shape`

Draw an outline rectangle on the current device context.

:param `dc`: the :class:`wx.MemoryDC` device context

Return the shape for the given identifier.

:param `id`: the shape id to find

Insert a shape at the front of the shape list.

Recentre all the text that should be centred.

Redraw the shapes in the diagram on the specified device context.

Remove all shapes from the diagram but do not delete the shapes.

Remove the shape from the diagram (non-recursively) but do not
delete it.

Set the canvas associated with this diagram.

Set the tolerance within which a mouse move is ignored.

The default is 3 pixels.

:param `tolerance`: the tolerance level

Set quick-edit-mode on of off.

In this mode, refreshes are minimized, but the diagram may need
manual refreshing occasionally.

:param `mode`: `True` to quick edit or `False` for normal edit

Sets snap-to-grid mode.

:param `snap`: `True` to snap to grid or `False` not to snap

Call Show for each shape in the diagram.

:param `show`: True or False

'Snaps' the coordinate to the nearest grid position, if
snap-to-grid is on.

# Name:         divided.py
# Purpose:      DividedShape class
#
#

A :class:`DividedShape` is a rectangle with a number of vertical divisions.
Each division may have its text formatted with independent characteristics,
and the size of each division relative to the whole image may be specified.

:param `w`: width of rectangle
:param `h`: height of rectangle

Attachment points correspond to regions in the divided box.

Get the number of attachments.

There are two attachments for each region (left and right),
plus one on the top and one on the bottom.

Reset the control points.

:note: May only have the region handles, (n - 1) of them

Set all region sizes according to proportions and this object
total size.

:param `recursive`: not implemented

:param `region`: an instance of :class:`~lib.ogl.ShapeRegion`
:param float `the_m_xoffset`: the the_m_xoffset position ???
:param float `the_m_yoffset`: the the_m_yoffset position ???

__init__(self, the_canvas, object, region, size, the_m_xoffset, the_m_yoffset, the_type)

The class :class:`~lib.ogl.drawn.DrawnShape`.

THIS DOES NOT SEEM TO BE USED ANYWHERE

# Name:         drawn.py
# Purpose:      DrawnShape class
#
#
# Created:      2004-08-25

Draws a pseudo-metafile shape, which can be loaded from a simple
Windows metafile.

wxDrawnShape allows you to specify a different shape for each of four
orientations (North, West, South and East). It also provides a set of
drawing functions for programmatic drawing of a shape, so that during
construction of the shape you can draw into it as if it were a device
context.

Derived from:
  RectangleShape

Calculate the wxDrawnShape size from the current metafile.

Call this after you have drawn into the shape.

Set the metafile for the given orientation, which can be one of:

* DRAWN_ANGLE_0
* DRAWN_ANGLE_90
* DRAWN_ANGLE_180
* DRAWN_ANGLE_270

Draw a polygon.

flags can be one or more of:
METAFLAGS_OUTLINE (use this polygon for the drag outline) and
METAFLAGS_ATTACHMENTS (use the vertices of this polygon for attachments).

Draw a rounded rectangle.

radius is the corner radius. If radius is negative, it expresses
the radius as a proportion of the smallest dimension of the rectangle.

Return the current orientation, which can be one of:

Load a (very simple) Windows metafile, created for example by
Top Draw, the Windows shareware graphics package.

Set the brush for this metafile.

If isFill is True, the brush is used as the fill brush.

Set the pen for this metafile.

If isOutline is True, this pen is taken to indicate the outline
(and if the outline pen is changed for the whole shape, the pen
will be replaced with the outline pen).

If save is True, the image will be saved along with the shape's
other attributes. The reason why this might not be desirable is that
if there are many shapes with the same image, it would be more
efficient for the application to save one copy, and not duplicate
the information for every shape. The default is True.

GetPerimeterPoint(self, x1, y1, x2, y2, xOffset, yOffset, attachmentMode)

Draw line, rectangle, rounded rectangle, ellipse, point, arc, text.

__init__(self, theOp, theX1, theY1, theX2, theY2, theRadius = 0.0, s = "")

A simple metafile-like class which can load data from a Windows
metafile on all platforms.

The :class:`~lib.ogl.lines.LineShape` class may have arrowheads at the
beginning and end.

# Name:         lines.py
# Purpose:      LineShape class
#
#

Miscellaneous support functions for OGL.

params marked with '???' need review!

# Name:         oglmisc.py
# Purpose:      Miscellaneous OGL support functions
#
#

# pylint: disable=C0413
#   C0413: Import should be placed at the top of the module

demo.py
=======

This is a demo showing some of the capabilities of the :mod:`wx.lib.plot`
package. It is intended to be run as a standalone script via::

  user@host:.../site-packages/wx/lib/plot$ python examples/demo.py

# pylint: disable=E1101, C0330, C0103
#   E1101: Module X has no Y member
#   C0330: Wrong continued indentation
#   C0103: Invalid attribute/variable/method name

### Demo Application

This is the function that defines how the pointLabels are plotted

:param dc: DC that will be passed
:param mDataDict: Dictionary of data that you want to use
                  for the pointLabel

As an example I have decided I want a box at the curve point
with some text information about the curve plotted below.
Any wxDC method can be used.

A simple example showing how to use lib.plot from wxPython.

It is intended to be run as a standalone script via::

  user@host:.../site-packages/wx/lib/plot$ python examples/simple_example.py

plotcanvas.py

This is the main window that you will want to import into your application.

Generic class for describing which sides of a box are displayed.

Used for fine-tuning the axis, ticks, and values of a graph.

This class somewhat mimics a collections.namedtuple factory function in
that it is an iterable and can have individual elements accessible by name.
It differs from a namedtuple in a few ways:

- it's mutable
- it's not a factory function but a full-fledged class
- it contains type checking, only allowing boolean values
- it contains name checking, only allowing valid_names as attributes

:param bottom: Display the bottom side
:type bottom: bool
:param left: Display the left side
:type left: bool
:param top: Display the top side
:type top: bool
:param right: Display the right side
:type right: bool

Creates a PlotCanvas object.

Subclass of a wx.Panel which holds two scrollbars and the actual
plotting canvas (self.canvas). It allows for simple general plotting
of data with zoom, labels, and automatic axis scaling.

This is the main window that you will want to import into your

Parameters for ``__init__`` are the same as any :class:`wx.Panel`.

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="plotCanvas")

Returns list with
[curveNumber, legend, index of closest point,
pointXY, scaledXY, distance]
list for only the closest curve.
Returns [] if no curves are being plotted.

x, y in user coords
if pointScaled == True based on screen coords
if pointScaled == False based on user coords

list for each curve.

Get the enableAntiAliasing value.

.. deprecated:: Feb 27, 2016

   Use the
   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableAntiAliasing`
   property instead.

Get the enableCenterLines value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableCenterLines`

Get the enableDiagonals value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableDiagonals`

Get the enableDrag value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableDrag`

Get the enableGrid value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableGrid`

Get the enableHiRes value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableHiRes`

Get the enableLegend value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableLegend`

Set the enablePointLabel value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enablePointLabel`

Get the enableTitle value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableTitle`

Get the enableZoom value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableZoom`

Get current tick and axis label font size in points

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.fontSizeAxis`
   property
   instead.

Get legend font size (default is 7 point)

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.fontSizeLegend'

Get Title font size (default is 15 point)

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.fontSizeTitle`

Set the log scale boolean value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.logScale`

Get the enablePointLabel value.

Get the showScrollbars value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.showScrollbars`

Get the useScientificNotation value.

   Use the
   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.useScientificNotation`

Get the xCurrentRange value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xCurrentRange`

Get the xMaxRange value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xMaxRange`

Get the xSpec value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xSpec`

Get the yCurrentRange value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.yCurrentRange`

Get the yMaxRange value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.yMaxRange`

Get the ySpec value.

   Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.ySpec`

Saves the file to the type specified in the extension. If no file
name is specified a dialog box is provided.  Returns True if
successful, otherwise False.

.bmp  Save a Windows bitmap file.
.xbm  Save an X bitmap file.
.xpm  Save an XPM bitmap file.
.png  Save a Portable Network Graphics file.
.jpg  Save a Joint Photographic Experts Group file.

Set the enableAntiAliasing value.

   Use the

Set the enableCenterLines value.

Set the enableDiagonals value.

Set the enableDrag value.

Set the enableGrid value.

Set the enableHiRes value.

Set the enableLegend value.

Set the enableTitle value.

Set the enableZoom value.

Set the tick and axis label font size (default is 10 point)

   property
   instead.

Set legend font size (default is 7 point)

Set Title font size (default is 15 point)

Set the showScrollbars value.

Set the useScientificNotation value.

   Use the

Set the xSpec value.

Set the ySpec value.

Updates the pointLabel point on screen with data contained in
mDataDict.

mDataDict will be passed to your function set by
SetPointLabelFunc.  It can contain anything you
want to display on the screen at the scaledXY point
you specify.

This function can be called from parent window with onClick,
onMotion events etc.

Zoom on the plot
Centers on the X,Y coords given in Center
Zooms by the Ratio = (Xratio, Yratio) given

The absScale value as a 2-tuple of bools:
``(x_axis_is_abs_scale, y_axis_is_abs_scale)``.

:getter: Returns the value of absScale.
:setter: Sets the value of absScale.
:type:   tuple of bools, length 2
:raise:  `TypeError` when setting an invalid value.

The :class:`wx.Pen` used to draw the axes lines on the plot.

:getter: Returns the :class:`wx.Pen` used for drawing the axes
         lines.
:setter: Sets the :class:`wx.Pen` use for drawging the axes lines.
:type:   :class:`wx.Pen`
:raise:  `TypeError` when setting a value that is not a
         :class:`wx.Pen`.

The :class:`wx.Pen` used to draw the center lines on the plot.

:getter: Returns the :class:`wx.Pen` used for drawing the center
         lines.
:setter: Sets the :class:`wx.Pen` use for drawging the center lines.

The :class:`wx.Pen` used to draw the diagonal lines on the plot.

:getter: Returns the :class:`wx.Pen` used for drawing the diagonal
         lines.
:setter: Sets the :class:`wx.Pen` use for drawging the diagonal lines.

The current enableAntiAliasing value.

:getter: Returns the value of enableAntiAliasing.
:setter: Sets the value of enableAntiAliasing.
:type:   bool
:raises: `TypeError` if setting a non-boolean value.

The current enableAxes value.

:getter: Returns the value of enableAxes.
:setter: Sets the value of enableAxes.
:type:   bool, 2-tuple of bool, or 4-tuple of bool
:raises: `TypeError` if setting an invalid value.
:raises: `ValueError` if the tuple has incorrect length.

If bool, enable or disable all axis

If 2-tuple, enable or disable the bottom or left axes: ``(bottom,
left)``

If 4-tuple, enable or disable each axis individually: ``(bottom,
left, top, right)``

The current enableAxesLabels value.

:getter: Returns the value of enableAxesLabels.
:setter: Sets the value of enableAxesLabels.

The current enableAxesValues value.

:getter: Returns the value of enableAxesValues.
:setter: Sets the value of enableAxesValues.

If bool, enable or disable all axis values

If 2-tuple, enable or disable the bottom or left axes values:
``(bottom, left)``

If 4-tuple, enable or disable each axis value individually:
``(bottom, left, top, right)``

The current enableCenterLines value.

:getter: Returns the value of enableCenterLines.
:setter: Sets the value of enableCenterLines.
:type:   bool or str

If set to a single boolean value, then both horizontal and vertical
lines will be enabled or disabled.

If a string, must be one of ``('Horizontal', 'Vertical')``.

The current enableDiagonals value.

:getter: Returns the value of enableDiagonals.
:setter: Sets the value of enableDiagonals.

If set to a single boolean value, then both diagonal lines will
be enabled or disabled.

If a string, must be one of ``('Bottomleft-Topright',
'Bottomright-Topleft')``.

The current enableDrag value.

:getter: Returns the value of enableDrag.
:setter: Sets the value of enableDrag.

.. note::
   This is mutually exclusive with
   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableZoom`. Setting
   one will disable the other.

.. seealso::
   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableZoom`

The current enableGrid value.

:getter: Returns the value of enableGrid.
:setter: Sets the value of enableGrid.
:type:   bool or 2-tuple of bools

If set to a single boolean value, then both X and y grids will be
enabled (``enableGrid = True``) or disabled (``enableGrid = False``).

If a 2-tuple of bools, the 1st value is the X (vertical) grid and
the 2nd value is the Y (horizontal) grid.

The current enableHiRes value.

:getter: Returns the value of enableHiRes.
:setter: Sets the value of enableHiRes.

The current enableLegend value.

:getter: Returns the value of enableLegend.
:setter: Sets the value of enableLegend.

The current enablePlotTitle value.

:getter: Returns the value of enablePlotTitle.
:setter: Sets the value of enablePlotTitle.

The current enablePointLabel value.

:getter: Returns the value of enablePointLabel.
:setter: Sets the value of enablePointLabel.

The current enableTicks value.

:getter: Returns the value of enableTicks.
:setter: Sets the value of enableTicks.

If bool, enable or disable all ticks

If 2-tuple, enable or disable the bottom or left ticks:

If 4-tuple, enable or disable each tick side individually:

The current enableTitle value.

:getter: Returns the value of enableTitle.
:setter: Sets the value of enableTitle.

The current enableXAxisLabel value.

:getter: Returns the value of enableXAxisLabel.
:setter: Sets the value of enableXAxisLabel.

The current enableYAxisLabel value.

:getter: Returns the value of enableYAxisLabel.
:setter: Sets the value of enableYAxisLabel.

The current enableZoom value.

:getter: Returns the value of enableZoom.
:setter: Sets the value of enableZoom.

.. note::
   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableDrag`. Setting

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.enableDrag`

The current tick and axis label font size in points.

Default is 10pt font.

:getter: Returns the value of fontSizeAxis.
:setter: Sets the value of fontSizeAxis.
:type:   int or float

The current Legned font size in points.

Default is 7pt font.

:getter: Returns the value of fontSizeLegend.
:setter: Sets the value of fontSizeLegend.

The current Title font size in points.

Default is 15pt font.

:getter: Returns the value of fontSizeTitle.
:setter: Sets the value of fontSizeTitle.

The :class:`wx.Pen` used to draw the grid lines on the plot.

:getter: Returns the :class:`wx.Pen` used for drawing the grid
         lines.
:setter: Sets the :class:`wx.Pen` use for drawging the grid lines.

The logScale value as a 2-tuple of bools:
``(x_axis_is_log_scale, y_axis_is_log_scale)``.

:getter: Returns the value of logScale.
:setter: Sets the value of logScale.

The current pointLabelFunc value.

:getter: Returns the value of pointLabelFunc.
:setter: Sets the value of pointLabelFunc.
:type:   function

TODO: More information is needed.
Sets the function with custom code for pointLabel drawing

The current showScrollbars value.

:getter: Returns the value of showScrollbars.
:setter: Sets the value of showScrollbars.

The length of the tick marks on an axis.

:getter: Returns the length of the tick marks.
:setter: Sets the length of the tick marks.
:type:   tuple of (xlength, ylength): int or float
:raise:  `TypeError` when setting a value that is not an int or float.

The :class:`wx.Pen` used to draw the tick marks on the plot.

:getter: Returns the :class:`wx.Pen` used for drawing the tick marks.
:setter: Sets the :class:`wx.Pen` use for drawging the tick marks.

The current useScientificNotation value.

:getter: Returns the value of useScientificNotation.
:setter: Sets the value of useScientificNotation.

The plots' X range of the currently displayed portion as
a tuple of ``(min, max)``

:getter: Returns the value of xCurrentRange.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.yCurrentRange`

The plots' maximum X range as a tuple of ``(min, max)``.

:getter: Returns the value of xMaxRange.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.yMaxRange`

Defines the X axis type.

Default is 'auto'.

:getter: Returns the value of xSpec.
:setter: Sets the value of xSpec.
:type:   str, int, or length-2 sequence of floats

Valid strings:
+ 'none' - shows no axis or tick mark values
+ 'min' - shows min bounding box values
+ 'auto' - rounds axis range to sensible values

Other valid values:
+ <number> - like 'min', but with <number> tick marks
+ list or tuple: a list of (min, max) values. Must be length 2.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.ySpec`

The plots' Y range of the currently displayed portion as

:getter: Returns the value of yCurrentRange.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xCurrentRange`

The plots' maximum Y range as a tuple of ``(min, max)``.

:getter: Returns the value of yMaxRange.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xMaxRange`

Defines the Y axis type.

   :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.xSpec`

GetPageInfo() -> (minPage, maxPage, pageFrom, pageTo)

Called by the framework to obtain information from the application
about minimum and maximum page values that the user can select, and
the required page range to be printed.

HasPage(pageNum) -> bool

Should be overridden to return true if the document has this page, or
false if not.

OnPrintPage(pageNum) -> bool

Called by the framework when a page should be printed.

Creates a PolyBoxPlot object.

:param data: Raw data to create a box plot from.
:type data: sequence of int or float
:param **attr: keyword attributes

=================================  =============  =======================
Keyword and Default                Description    Type
``colour='black'``                 edge color     :class:`wx.Colour`
``width=1``                        edge width     float
``style=wx.PENSTYLE_SOLID``        edge style     :class:`wx.PenStyle`
``legend=''``                      legend string  str

.. note::

   ``np.NaN`` and ``np.inf`` values are ignored.

.. admonition:: TODO

   + [ ] Figure out a better way to get multiple box plots side-by-side
     (current method is a hack).
   + [ ] change the X axis to some labels.
   + [ ] Change getClosestPoint to only grab box plot items and outlers?
     Currently grabs every data point.
   + [ ] Add more customization such as Pens/Brushes, outlier shapes/size,
     and box width.
   + [ ] Figure out how I want to handle log-y: log data then calcBP? Or
     should I calc the BP first then the plot it on a log scale?

Box plot points:

Median (50%)
75%
25%
low_whisker = lowest value that's >= (25% - (IQR * 1.5))
high_whisker = highest value that's <= 75% + (IQR * 1.5)

outliers are outside of 1.5 * IQR

Parameters
----------
data : array-like
    The data to plot

Returns
-------
bpdata : collections.namedtuple
    Descriptive statistics for data:
    (min_data, low_whisker, q25, median, q75, high_whisker, max_data)

Draws a box plot on the DC.

Notes
-----
The following draw order is required:

1. First the whisker line
2. Then the IQR box
3. Lasly the median line.

This is because

+ The whiskers are drawn as single line rather than two lines
+ The median line must be visible over the box if the box has a fill.

Other than that, the draw order can be changed.

Returns the index of closest point on the curve, pointXY,
scaledXY, distance x, y in user coords.

Override method.

if pointScaled == True, then based on screen coords
if pointScaled == False, then based on user coords

Creates PolyLine object

:param points: The points that make up the line
:type points: list of ``[x, y]`` values

===========================  =============  ====================
Keyword and Default          Description    Type
``colour='black'``           Line color     :class:`wx.Colour`
``width=1``                  Line width     float
``style=wx.PENSTYLE_SOLID``  Line style     :class:`wx.PenStyle`
``legend=''``                Legend string  str
``drawstyle='line'``         see below      str

==================  ==================================================
Draw style          Description
``'line'``          Draws an straight line between consecutive points
``'steps-pre'``     Draws a line down from point A and then right to
                    point B
``'steps-post'``    Draws a line right from point A and then down
                    to point B
``'steps-mid-x'``   Draws a line horizontally to half way between A
                    and B, then draws a line vertically, then again
                    horizontally to point B.
``'steps-mid-y'``   Draws a line vertically to half way between A
                    and B, then draws a line horizonatally, then
                    again vertically to point B.
                    *Note: This typically does not look very good*

   All methods except ``__init__`` are private.

Draw the lines.

:param dc: The DC to draw on.
:type dc: :class:`wx.DC`
:param printerScale:
:type printerScale: float
:param coord: The legend coordinate?
:type coord: ???

Get the Width and Height of the symbol.

Creates a PolyMarker object.

:param points: The marker coordinates.

=================================  =============  ====================
``marker='circle'``                see below      str
``size=2``                         Marker size    float
``colour='black'``                 Outline color  :class:`wx.Colour`
``width=1``                        Outline width  float
``style=wx.PENSTYLE_SOLID``        Outline style  :class:`wx.PenStyle`
``fillcolour=colour``              fill color     :class:`wx.Colour`
``fillstyle=wx.BRUSHSTYLE_SOLID``  fill style     :class:`wx.BrushStyle`
``legend=''``                      Legend string  str

===================  ==================================
Marker               Description
``'circle'``         A circle of diameter ``size``
``'dot'``            A dot. Does not have a size.
``'square'``         A square with side length ``size``
``'triangle'``       An upward-pointed triangle
``'triangle_down'``  A downward-pointed triangle
``'cross'``          An "X" shape
``'plus'``           A "+" shape

Decorator / Context Manager to revert pen or brush changes.

Will revert pen, brush, or both to their previous values after a method
call or block finish.

:param which: The item to save and revert after execution. Can be
              one of ``{'both', 'pen', 'brush'}``.
:type which: str
:param dc: The DC to get brush/pen info from.

::

    # Using as a method decorator:
    @TempStyle()                        # same as @TempStyle('both')
    def func(self, dc, a, b, c):        # dc must be 1st arg (beside self)
        # edit pen and brush here

    # Or as a context manager:
    with TempStyle('both', dc):
        # do stuff

.. Note::

   As of 2016-06-15, this can only be used as a decorator for **class
   methods**, not standard functions. There is a plan to try and remove
   this restriction, but I don't know when that will happen...

.. epigraph::

   *Combination Decorator and Context Manager! Also makes Julienne fries!
   Will not break! Will not... It broke!*

   -- The Genie

# TODO: replace with wx.DCPenChanger/wx.DCBrushChanger, etc.
#       Alternatively, replace those with this function...

Raise `PendingDeprecationWarning` and display a message.

Uses inspect.stack() to determine the name of the item that this
is called from.

:param new_func: The name of the function that should be used instead.
:type new_func: string.

Creates a scaled and shifted 2x1 numpy array of [x, y] values.

The shift value must be in the scaled units.

:param float `x`:        The x value of the unscaled, unshifted point
:param float `y`:        The y valye of the unscaled, unshifted point
:param np.array `scale`: The scale factor to use ``[x_sacle, y_scale]``
:param np.array `shift`: The offset to apply ``[x_shift, y_shift]``.
                         Must be in scaled units

:returns: a numpy array of 2 elements
:rtype: np.array

.. note::

   :math:`new = (scale * old) + shift`

Wrapper around :class:`~wx.lib.plot._DisplaySide` that allows for "overloaded" calls.

If ``value`` is a boolean: all 4 sides are set to ``value``

If ``value`` is a 2-tuple: the bottom and left sides are set to ``value``
and the other sides are set to False.

If ``value`` is a 4-tuple, then each item is set individually: ``(bottom,

:param value: Which sides to display.
:type value:   bool, 2-tuple of bool, or 4-tuple of bool
:rtype: :class:`~wx.lib.plot._DisplaySide`

polyobjects.py
==============

This contains all of the PolyXXX objects used by :mod:`wx.lib.plot`.

Creates a PlotGraphics object.

:param objects: The Poly objects to plot.
:type objects: list of :class:`~wx.lib.plot.PolyPoints` objects
:param title: The title shown at the top of the graph.
:type title: str
:param xLabel: The x-axis label.
:type xLabel: str
:param yLabel: The y-axis label.
:type yLabel: str

Get max width and height of lines and markers symbols for legend

Get the title at the top of graph

   Use the :attr:`~wx.lib.plot.polyobjects.PlotGraphics.title`

Get X axis label string

   Use the :attr:`~wx.lib.plot.polyobjects.PlotGraphics.xLabel`

Get Y axis label string

   Use the :attr:`~wx.lib.plot.polyobjects.PlotGraphics.yLabel`

   Use the :attr:`~wx.lib.plot.polyobjects.PlotGraphics.logScale`

Thickens up lines and markers only for printing

   Use the :attr:`~wx.lib.plot.polyobjects.PlotGraphics.printerScale`

Set the title at the top of graph

Set the X axis label on the graph

Set the Y axis label on the graph

Creates a PolyBars object.

:param points: The data to plot.
:type points: sequence of ``(center, height)`` points

``barwidth=1.0``                   bar width      float or list of floats
``edgecolour='black'``             edge color     :class:`wx.Colour`
``edgewidth=1``                    edge width     float
``edgestyle=wx.PENSTYLE_SOLID``    edge style     :class:`wx.PenStyle`
``fillcolour='red'``               fill color     :class:`wx.Colour`

.. important::

   If ``barwidth`` is a list of floats:

   + each bar will have a separate width
   + ``len(barwidth)`` must equal ``len(points)``.

Base class for PolyBars and PolyHistogram.

   All methods are private.

Creates a PolyHistogram object.

:param hist: The histogram data.
:type hist: sequence of ``y`` values that define the heights of the bars
:param binspec: The bin specification.
:type binspec: sequence of ``x`` values that define the edges of the bins

``edgewidth=3``                    edge width     float
``fillcolour='blue'``              fill color     :class:`wx.Colour`

.. tip::

   Use ``np.histogram()`` to easily create your histogram parameters::

     hist_data, binspec = np.histogram(data)
     hist_plot = PolyHistogram(hist_data, binspec)

   ``len(binspec)`` must equal ``len(hist) + 1``.

Base Class for lines and markers.

:param points: The points to plot
:type points: list of ``(x, y)`` pairs
:param attr: Additional attributes
:type attr: dict

Returns the bounding box for the entire dataset as a tuple with this
format::

    ((minX, minY), (maxX, maxY))

:returns: boundingbox
:rtype: numpy array of ``[[minX, minY], [maxX, maxY]]``

Scales and shifts the data for plotting.

:param scale: The values to scale the data by.
:type scale: list of floats: ``[x_scale, y_scale]``
:param shift: The value to shift the data by. This should be in scaled
              units
:type shift: list of floats: ``[x_shift, y_shift]``
:returns: None

Set to change the axes to plot Log10(values)

Value must be a tuple of booleans (x_axis_bool, y_axis_bool)

   Use the :attr:`~wx.lib.plot.polyobjects.PolyPoints.logScale`

A tuple of ``(x_axis_is_abs, y_axis_is_abs)`` booleans. If a value
is ``True``, then that axis is plotted on an absolute value scale.

:getter: Returns the current value of absScale
:setter: Sets the value of absScale
:type: tuple of bool, length 2
:raises ValueError: when setting an invalid value

A tuple of ``(x_axis_is_log10, y_axis_is_log10)`` booleans. If a value
is ``True``, then that axis is plotted on a logarithmic base 10 scale.

:getter: Returns the current value of logScale
:setter: Sets the value of logScale

Get or set the plotted points.

:getter: Returns the current value of points, adjusting for the
         various scale options such as Log, Abs, or SymLog.
:setter: Sets the value of points.
:type: list of `(x, y)` pairs

.. Note::

   Only set unscaled points - do not perform the log, abs, or symlog
   adjustments yourself.

   Not yet implemented.

A tuple of ``(x_axis_is_SymLog10, y_axis_is_SymLog10)`` booleans.
If a value is ``True``, then that axis is plotted on a symmetric
logarithmic base 10 scale.

A Symmetric Log10 scale means that values can be positive and
negative. Any values less than
:attr:`~wx.lig.plot.PolyPoints.symLogThresh` will be plotted on
a linear scale to avoid the plot going to infinity near 0.

:getter: Returns the current value of symLogScale
:setter: Sets the value of symLogScale

.. notes::

   This is a simplified example of how SymLog works::

     if x >= thresh:
         x = Log10(x)
     elif x =< thresh:
         x = -Log10(Abs(x))
     else:
         x = x

   + :attr:`~wx.lib.plot.PolyPoints.symLogThresh`
   + See http://matplotlib.org/examples/pylab_examples/symlog_demo.html
     for an example.

A tuple of ``(x_thresh, y_thresh)`` floats that define where the plot
changes to linear scale when using a symmetric log scale.

:getter: Returns the current value of symLogThresh
:setter: Sets the value of symLogThresh
:type: tuple of float, length 2

.. notes::

     else:
         x = x

   + :attr:`~wx.lib.plot.PolyPoints.symLogScale`

Creates PolySpline object

:param points: The points that make up the spline

Returns a new subclass of tuple with named fields.

>>> Point = namedtuple('Point', ['x', 'y'])
>>> Point.__doc__                   # docstring for the new class
'Point(x, y)'
>>> p = Point(11, y=22)             # instantiate with positional args or keywords
>>> p[0] + p[1]                     # indexable like a plain tuple
33
>>> x, y = p                        # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y                       # fields also accessible by name
33
>>> d = p._asdict()                 # convert to a dictionary
>>> d['x']
11
>>> Point(**d)                      # convert from a dictionary
Point(x=11, y=22)
>>> p._replace(x=100)               # _replace() is like str.replace() but targets named fields
Point(x=100, y=22)

namedtuple(typename, field_names, \*, rename=False, defaults=None, module=None)

utils.py
=========

This is a collection of utilities used by the :mod:`wx.lib.plot` package.

Pubsub package initialization.

:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
:license: BSD, see LICENSE_BSD_Simple.txt for details.

Core package of pubsub, holding the publisher, listener, and topic
object modules. Functions defined here are used internally by
pubsub so that the right modules can be found later, based on the
selected messaging protocol.

Indeed some of the API depends on the messaging
protocol used. For instance sendMessage(), defined in publisher.py,
has a different signature (and hence implementation) for the kwargs
protocol than for the arg1 protocol.

The most convenient way to
support this is to put the parts of the package that differ based
on protocol in separate folder, and add one of those folders to
the package's __path__ variable (defined automatically by the Python
interpreter when __init__.py is executed). For instance, code
specific to the kwargs protocol goes in the kwargs folder, and code
specific to the arg1 protocol in the arg1 folder. Then when doing
"from pubsub.core import listener", the correct listener.py will be
found for the specified protocol. The default protocol is kwargs.

Only one protocol can be used in an application. The default protocol,
if none is chosen by user, is kwargs, as selected by the call to
_prependModulePath() at end of this file. 

Low level functions and classes related to callables.

The AUTO_TOPIC
is the "marker" to use in callables to indicate that when a message
is sent to those callables, the topic object for that message should be
added to the data sent via the call arguments. See the docs in
CallArgsInfo regarding its autoTopicArgName data member.

Represent the "signature" or protocol of a listener in the context of
topics.

Inputs:
- Args and defaultVals are the complete set of arguments and
  default values as obtained form inspect.getargspec();
- The firstArgIdx points to the first item in
  args that is of use, so it is typically 0 if listener is a function,
  and 1 if listener is a method.
- The acceptsAllKwargs should be true
  if the listener has **kwargs in its protocol.

After construction,
- self.allParams will contain the subset of 'args' without first
  firstArgIdx items,
- self.numRequired will indicate number of required arguments
  (ie self.allParams[:self.numRequired] are the required args names);
- self.acceptsAllKwargs = acceptsAllKwargs
- self.autoTopicArgName will be the name of argument
  in which to put the topic object for which pubsub message is
  sent, or None. This is identified by the argument that has a
  default value of AUTO_TOPIC.

For instance, listener(self, arg1, arg2=AUTO_TOPIC, arg3=None) will
have self.allParams = (arg1, arg2, arg3), self.numRequired=1, and
self.autoTopicArgName = 'arg2', whereas
listener(self, arg1, arg3=None) will have
self.allParams = (arg1, arg3), self.numRequired=1, and
self.autoTopicArgName = None.

Return a tuple of names indicating which call arguments
are required to be present when pub.sendMessage(...) is called. 

Raised when an attempt is made to subscribe a listener to
a topic, but listener does not satisfy the topic's message data
specification (MDS). This specification is inferred from the first
listener subscribed to a topic, or from an imported topic tree
specification (see pub.addTopicDefnProvider()).

Returns an instance of CallArgsInfo for the given callable_.
Raises ListenerMismatchError if callable_ is not a callable.

Get the names and default values of a function's parameters.

A tuple of four things is returned: (args, varargs, keywords, defaults).
'args' is a list of the argument names, including keyword-only argument names.
'varargs' and 'keywords' are the names of the * and ** parameters or None.
'defaults' is an n-tuple of the default values of the last n parameters.

This function is deprecated, as it does not support annotations or
keyword-only parameters and will raise ValueError if either is present
on the supplied callable.

For a more structured introspection API, use inspect.signature() instead.

Alternatively, use getfullargspec() for an API with a similar namedtuple
based interface, but full support for annotations and keyword-only

Deprecated since Python 3.5, use `inspect.getfullargspec()`.

Get name and module name for a callable, ie function, bound
method or callable instance, by inspecting the callable. E.g.
getID(Foo.bar) returns ('Foo.bar', 'a.b') if Foo.bar was
defined in module a.b. 

Get the module in which an object was defined. Returns '__main__'
if no module defined (which usually indicates either a builtin, or
a definition within main script). 

Given a callable, return (offset, func) where func is the
function corresponding to callable, and offset is 0 or 1 to
indicate whether the function's first argument is 'self' (1)
or not (0). Raises ValueError if callable_ is not of a
recognized type (function, method or has __call__ method).

Return true if the object is a user-defined function.

Function objects provide these attributes:
    __doc__         documentation string
    __name__        name with which this function was defined
    __code__        code object containing compiled function bytecode
    __defaults__    tuple of any default values for arguments
    __globals__     global namespace in which this function was defined
    __annotations__ dict of parameter annotations
    __kwdefaults__  dict of keyword only parameters with defaults

Return true if the object is an instance method.

Instance method objects provide these attributes:
    __name__        name with which this method was defined
    __func__        function object containing implementation of method
    __self__        instance to which this method is bound

'## your listener wants topic name ## (string unlikely to be used by caller)'

A simple container object for the two components of a message in the 
arg1 messaging protocol: the 
topic and the user data. Each listener called by sendMessage(topic, data)
gets an instance of Message. The given 'data' is accessed
via Message.data, while the topic name is available in Message.topic::

    def listener(msg):
        print "data is ", msg.data
        print "topic name is ", msg.topic
        print msg
        
The example also shows (last line) how a message is convertible to a string.

The _resolve_name and _import_module were taken from the backport of 
importlib.import_module from 3.x to 2.7. Thanks to the Python developers
for making this available as a standalone module. This makes it possible
to have an import module that mimics the "import" statement more
closely.

Try to import moduleName. If this doesn't work, use the "imp" module
that is part of Python. 

Interface class base class for any handler given to pub.setListenerExcHandler()
Such handler is called whenever a listener raises an exception during a 
pub.sendMessage(). Example::

    from pubsub import pub
    
    class MyHandler(pub.IListenerExcHandler):
        def __call__(self, listenerID, topicObj):
            ... do something with listenerID ...
            
    pub.setListenerExcHandler(MyHandler())

Wraps a callable so it can be stored by weak reference and introspected
to verify that it adheres to a topic's MDS. 

A Listener instance 
has the same hash value as the callable that it wraps. 

Callables that have 'argName=pub.AUTO_TOPIC' as a kwarg will
be given the Topic object for the message sent by sendMessage().
Such a Listener will have wantsTopicObjOnCall() True.

Callables that have a '**kargs' argument will receive all message
data, not just that for the topic they are subscribed to. Such a listener
will have wantsAllMessageData() True. 

Do not accept any required args or *args; accept any **kwarg, 
and require that the Listener have at least all the kwargs (can 
have extra) of Topic.

Use callable_ as a listener of topicName. The argsInfo is the
return value from a Validator, ie an instance of callables.CallArgsInfo.
If given, the onDead will be called with self as parameter, if/when
callable_ gets garbage collected (callable_ is held only by weak
reference). 

Get the listener that was given at initialization. Note that
this could be None if it has been garbage collected (e.g. if it was 
created as a wrapper of some other callable, and not stored 
locally).

Return a human readable name for listener, based on the
listener's type name and its id (as obtained from id(listener)). If 
caller just needs name based on type info, specify instance=False. 
Note that the listener's id() was saved at construction time (since 
it may get garbage collected at any time) so the return value of 
name() is not necessarily unique if the callable has died (because 
id's can be re-used after garbage collection).

Get a type name for the listener. This is a class name or
function name, as appropriate. 

True if this listener wants all message data: it has a **kwargs argument

True if this listener wants topic object: it has a arg=pub.AUTO_TOPIC

Validates listeners. It checks whether the listener given to 
validate() method complies with required and optional arguments
specified for topic. 

topicArgs is a list of argument names that will be required when sending
a message to listener. Hence order of items in topicArgs matters. The topicKwargs
is a list of argument names that will be optional, ie given as keyword arguments
when sending a message to listener. The list is unordered. 

Return true only if listener can subscribe to messages where
topic has kwargs keys topicKwargKeys. Just calls validate() in 
a try-except clause.

Validate that listener satisfies the requirements of
being a topic listener, if topic's kwargs keys are topicKwargKeys
(so only the list of keyword arg names for topic are necessary). 
Raises ListenerMismatchError if listener not usable for topic. 

Otherwise, returns an CallArgsInfo object containing information about
the listener's call arguments, such as whether listener wants topic
name (signified by a kwarg value = AUTO_TOPIC in listener protocol).
E.g. def fn1(msgTopic=Listener.AUTO_TOPIC) would 
cause validate(fn1) to return True, whereas any other kwarg name or value 
would cause a False to be returned. 

Defines the interface expected by pubsub for pubsub activity 
notifications. Any instance that supports the same methods, or 
derives from this class, will work as a notification handler
for pubsub events (see pub.addNotificationHandler).

Called when a listener has been garbage collected.
:param pubListener: the pubsub.core.Listener that wraps GC'd listener.
:param topicObj: the pubsub.core.Topic object it was subscribed to.

Called whenever a topic is removed from topic tree.
:param topicName: name of topic removed.

Called whenever a new topic is added to the topic tree.
:param topicObj: the Topic object for the message.
:param description: docstring for the topic.
:param required: list of message data names (keys in argsDocs) that are required.
:param argsDocs: dictionary of all message data names, with the 
corresponding docstring. 

Called multiple times during a sendMessage: once before message
sending has started (pre), once for each listener about to be sent the 
message, and once after all listeners have received the message (post).
:param stage: 'pre', 'post', or 'loop'.
:param pubListener: None for pre and post stages; for loop, the listener
    that is about to be sent the message.

Called when a listener is subscribed to a topic.
:param pubListener: the pubsub.core.Listener that wraps subscribed listener.
:param topicObj: the pubsub.core.Topic object subscribed to.
:param newSub: false if pubListener was already subscribed. 

Called when a listener is unsubscribed from given topic.
:param pubListener: the pubsub.core.Listener that wraps unsubscribed listener.
:param topicObj: the pubsub.core.Topic object unsubscribed from.

Manages notifications for tracing pubsub activity. When pubsub takes a 
certain action such as sending a message or creating a topic, and 
the notification flag for that activity is True, all registered
notification handlers get corresponding method called with information
about the activity, such as which listener subscribed to which topic. 
See INotificationHandler for which method gets called for each activity.

If more than one notification handler has been registered, the order in 
which they are notified is unspecified (do not rely on it).

Note that this manager automatically unregisters all handlers when
the Python interpreter exits, to help avoid NoneType exceptions during
shutdown. This "shutdown" starts when the last line of app "main" has
executed; the Python interpreter then starts cleaning up, garbage 
collecting everything, which could lead to various pubsub notifications
-- by then they should be of no interest -- such as dead
listeners, etc. 

Set the notification flag on/off for various aspects of pubsub.
The kwargs that are None are left at their current value. The 'all',
if not None, is set first. E.g.

    mgr.setFlagStates(all=True, delTopic=False)

will toggle all notifications on, but will turn off the 'delTopic'
notification.

setFlagStates(self, subscribe=None, unsubscribe=None, deadListener=None, sendMessage=None, newTopic=None, delTopic=None, all=None)

Publisher used for kwargs protocol, ie when sending message data
via keyword arguments.

Send a message.

:param topicName: name of message topic (dotted or tuple format)
:param kwargs: message data (must satisfy the topic's MDS)

This is used when transitioning from arg1 to kwargs
messaging protocol.

If treeConfig is None, a default one is created from an
instance of TreeConfig.

Represent the class that send messages to listeners of given
topics and that knows how to subscribe/unsubscribe listeners
from topics.

Add a handler for tracing pubsub activity. The handler should be
a class that adheres to the API of INotificationHandler. 

Remove all notification handlers that were added via
self.addNotificationHandler(). 

Get the listener exception handler that was registered
via setListenerExcHandler(), or None of none registered.

Send a message for topic name with given data (args and kwargs).
This will be overridden by derived classes that implement
message-sending for different messaging protocols; not all 
parameters may be accepted.

Set the function to call when a listener raises an exception
during a sendMessage(). The handler must adhere to the 
IListenerExcHandler API. 

Set the notification flags on or off for each type of
pubsub activity. The kwargs keys can be any of the following:

- subscribe:    if True, get notified whenever a listener subscribes to a topic;
- unsubscribe:  if True, get notified whenever a listener unsubscribes from a topic;
- deadListener: if True, get notified whenever a subscribed listener has been garbage-collected;
- sendMessage:  if True, get notified whenever sendMessage() is called;
- newTopic:     if True, get notified whenever a new topic is created;
- delTopic:     if True, get notified whenever a topic is "deleted" from topic tree;
- all:          set all of the above to the given value (True or False).

The kwargs that are None are left at their current value. Those that are 
False will cause corresponding notification to be silenced. The 'all'
is set first, then the others. E.g.

Changes the creation policy for topics.

By default, pubsub will accept topic names for topics that 
don't have a message data specification (MDS). This default behavior 
makes pubsub easier to use initially, but allows topic
names with typos to go uncaught in common operations such as
sendMessage() and subscribe(). In a large application, this 
can lead to nasty bugs. Pubsub's default behavior is equivalent
to setTopicUnspecifiedFatal(false).

When called with newVal=True, any future pubsub operation that
requires a topic (such as subscribe and sendMessage) will require 
an MDS; if none is available, pubsub will raise a TopicDefnError
exception. 

If checkExisting is not given or True, all existing
topics are validated. A TopicDefnError exception is
raised if one is found to be incomplete (has hasMDS() false).

Returns previous value of newVal.

Note that this method can be used in several ways:

1. Only use it in your application when something is not working
   as expected: just add a call at the beginning of your app when
   you have a problem with topic messages not being received
   (for instance), and remove it when you have fixed the problem.

2. Use it from the beginning of your app and never use newVal=False:
   add a call at the beginning of your app and you leave it in
   (forever), and use Topic Definition Providers to provide the
   listener specifications. These are easy to use via the
   pub.addTopicDefnProvider().

3. Use it as in #1 during app development, and once stable, use
   #2. This is easiest to do in combination with
   pub.exportTopicTreeSpec().
 
Subscribe listener to named topic. Raises ListenerMismatchError
if listener isn't compatible with the topic's MDS. Returns
(pubsub.core.Listener, success), where success is False if listener 
was already subscribed. The pub.core.Listener wraps the callable 
subscribed and provides introspection-based info about 
the callable.

Note that if 'subscribe' notification is on, the handler's
'notifySubscribe' method is called after subscription.

By default (no args given), unsubscribe all listeners from all
topics. A listenerFilter can be given so that only the listeners
that satisfy listenerFilter(listener) == True will be unsubscribed
(with listener being a pub.Listener wrapper instance for each listener
subscribed). A topicFilter can also be given so that only topics
that satisfy topicFilter(topic name) == True will be affected.
If only one topic should have listeners unsubscribed, then a topic
name 'topicName' can be given *instead* instead of a topic filter.

Returns the list of all listeners (instances of pub.Listener) that
were unsubscribed from the topic tree).

Note: this method will generate one 'unsubcribe' notification message
(see pub.setNotificationFlags()) for each listener unsubscribed.

unsubAll(self, topicName = None, listenerFilter = None, topicFilter = None)

Unsubscribe from given topic. Returns the pubsub.core.Listener
instance that was used to wrap listener at subscription
time. Raises an TopicNameError if topicName doesn't exist.

Note that if 'unsubscribe' notification is on, the handler's
notifyUnsubscribe() method will be called after unsubscribing. 

Manages the registry of all topics and creation/deletion
of topics. 

Note that any method that accepts a topic name can accept it in the 
'dotted' format such as ``'a.b.c.'`` or in tuple format such as 
``('a', 'b', 'c')``. Any such method will raise a ValueError
if name not valid (empty, invalid characters, etc). 

The optional treeConfig is an instance of TreeConfig, used to
configure the topic tree such as notification settings, etc. A
default config is created if not given. This method should only be 
called by an instance of Publisher (see Publisher.getTopicManager()).

Register a topic definition provider. After this method is called, whenever a topic must be created,
the first definition provider that has a definition
for the required topic is used to instantiate the topic. 

If providerOrSource is an instance of ITopicDefnProvider, register 
it as a provider of topic definitions. Otherwise, register a new 
instance of TopicDefnProvider(providerOrSource, format). In that case, 
if format is not given, it defaults to TOPIC_TREE_FROM_MODULE. Either
way, returns the instance of ITopicDefnProvider registered.

Check that all topics that have been created for their MDS.
Raise a TopicDefnError if one is found that does not have one.

Delete the named topic, including all sub-topics. Returns False
if topic does not exist; True otherwise. Also unsubscribe any listeners 
of topic and all subtopics. 

Get the Topic instance for topic of given name, creating it
(and any of its missing parent topics) as necessary. Pubsub 
functions such as subscribe() use this to obtain the Topic object
corresponding to a topic name. 

The name can be in dotted or string format (``'a.b.'`` or ``('a','b')``). 

This method always attempts to return a "complete" topic, i.e. one 
with a Message Data Specification (MDS). So if the topic does not have 
an MDS, it attempts to add it. It first tries to find an MDS 
from a TopicDefnProvider (see addDefnProvider()). If none is available, 
it attempts to set it from protoListener, if it has been given. If not, 
the topic has no MDS. 

Once a topic's MDS has been set, it is never again changed or accessed
by this method. 
        
Examples::
    
    # assume no topics exist
    # but a topic definition provider has been added via 
    # pub.addTopicDefnProvider() and has definition for topics 'a' and 'a.b'
    
    # creates topic a and a.b; both will have MDS from the defn provider:
    t1 = topicMgr.getOrCreateTopic('a.b')
    t2 = topicMgr.getOrCreateTopic('a.b')
    assert(t1 is t2)
    assert(t1.getParent().getName() == 'a')
    
    def proto(req1, optarg1=None): pass
    # creates topic c.d with MDS based on proto; creates c without an MDS
    # since no proto for it, nor defn provider:
    t1 = topicMgr.getOrCreateTopic('c.d', proto)
    
The MDS can also be defined via a call to subscribe(listener, topicName), 
which indirectly calls getOrCreateTopic(topicName, listener).

Get the topic that is parent of all root (ie top-level) topics,
for default TopicManager instance created when this module is imported. 
Some notes:

- "root of all topics" topic satisfies isAll()==True, isRoot()==False,
  getParent() is None;
- all root-level topics satisfy isAll()==False, isRoot()==True, and
  getParent() is getDefaultTopicTreeRoot();
- all other topics satisfy neither. 

Get the Topic instance for the given topic name. By default, raises
an TopicNameError exception if a topic with given name doesn't exist. If
okIfNone=True, returns None instead of raising an exception.

Get the list of Topic objects that have given listener
subscribed. Note: the listener can also get messages from any 
sub-topic of returned list.

Determine if there is a definition available for topic 'name'. Return
true if there is, false otherwise. Note: a topic may have a
definition without being in use, and vice versa.

Determine if topic 'name' is in use. True if a Topic object exists
for topic name (i.e. message has already been sent for that topic, or a 
least one listener subscribed), false otherwise. Note: a topic may be in use 
but not have a definition (MDS and docstring); or a topic may have a
definition, but not be in use.

Deprecated legacy method.
If topic _name already exists, just returns it and does nothing else.
Otherwise, uses getOrCreateTopic() to create it, then sets its
description (_desc) and its message data specification (_argDocs
and _required). Replaced by getOrCreateTopic().

Each topic tree has its own topic manager and configuration,
such as notification and exception handling.

__init__(self, notificationHandler=None, listenerExcHandler=None)

Mixin for publishing messages to a topic's listeners. This will be
mixed into topicobj.Topic so that a user can use a Topic object to
send a message to the topic's listeners via a publish() method.

Note that it is important that the PublisherMixin NOT modify any
state data during message sending, because in principle it could
happen that a listener causes another message of same topic to be
sent (presumably, the listener has a way of preventing infinite
loop).

Definitions related to message data specification.

Encode the Message Data Specification (MDS) for a given
topic. ArgsInfos form a tree identical to that of Topics in that
ArgInfos have a reference to their parent and children ArgInfos,
created for the parent and children topics.

The only difference
between an ArgsInfo and an ArgSpecGiven is that the latter is
what "user thinks is ok" whereas former has been validated:
the specification for this topic is a strict superset of the
specification of its parent, and a strict subset of the
specification of each of its children. Also, the instance
can be used to check validity and filter arguments.

The MDS can be created "empty", ie "incomplete", meaning it cannot
yet be used to validate listener subscriptions to topics.

Check that the message arguments given satisfy the topic message
data specification (MDS). Raises SenderMissingReqdMsgDataError if some required
args are missing or not known, and raises SenderUnknownMsgDataError if some
optional args are unknown. 

Returns a dict which contains only those items of msgKwargs
which are defined for topic. E.g. if msgKwargs is {a:1, b:'b'}
and topic arg spec is ('a',) then return {a:1}. The returned dict
is valid only if check(msgKwargs) was called (or
check(superset of msgKwargs) was called).

Get the closest arg spec, starting from self and moving to parent,
that is complete. So if self.isComplete() is True, then returns self,
otherwise returns parent (if parent.isComplete()), etc. 

Returns true if self has all the message arguments given, no
more and no less. Order does not matter. So if getArgs()
returns ('arg1', 'arg2') then self.hasSameArgs('arg2', 'arg1')
will return true. 

This can only be called once, if the construction was done
with ArgSpecGiven.SPEC_GIVEN_NONE

The message data specification (MDS) for a topic.
This consists of each argument name that listener should have in its
call protocol, plus which ones are required in any sendMessage(), and a
documentation string for each argument. This instance will be transformed
into an ArgsInfo object which is basically a superset of that information,
needed to ensure that the arguments specifications satisfy
pubsub policies for chosen API version.

Raised when an attempt is made to define a topic's Message Data
Specification (MDS) to something that is not valid.

The keyword names for invalid data go in the 'args' list,
and the msg should state the problem and contain "%s" for the
args, such as MessageDataSpecError('duplicate args %s', ('arg1', 'arg2')).

Raised when a sendMessage() is missing arguments tagged as
'required' by pubsub topic of message.

Raised when a sendMessage() has arguments not listed among the topic's
message data specification (MDS).

Get the topic message data names and list of those that are required,
by introspecting given callable. Returns a pair, (args, required)
where args is a dictionary of allowed message data names vs docstring,
and required states which ones are required rather than optional.

Pretend to be a weak reference to nothing. Used by ArgsInfos to
refer to parent when None so no if-else blocks needed. 

If topicName is a string, just return it
as is. If it is a topic definition object (ie an object that has 
'msgDataSpec' as data member), return the dotted name of corresponding
topic. Otherwise, assume topicName is a tuple and convert it to to a 
dotted name i.e. ('a','b','c') => 'a.b.c'. Empty name is not allowed 
(ValueError). The reverse operation is tupleize(topicName).

Verify that sub is a subset of all for topicName. Raise
MessageDataSpecError if fail. 

Interface class for all topic definition de-serializers that can be
accepted by TopicDefnProvider. A deserializer
creates a topic tree from something such as file, module, or string.

Encapsulate date for a topic definition. Used by
getNextTopic().

Called automatically by TopicDefnProvider once
it considers the iteration completed. Override this only if
deserializer needs to take action, such as closing a file.

Get the next topic definition available from the data. The return
must be an instance of TopicDefn. Must return None when no topics
are left.

Called by the TopicDefnProvider if it needs to
restart the topic iteration. Override this only if special action needed,
such as resetting a file pointer to beginning of file.

All topic definition providers added via pub.addTopicDefnProvider()
must have this interface. Derived classes must override the getDefn(),
getTreeDoc() and topicNames() methods.

Must return a pair (string, ArgSpecGiven) for given topic.
The first item is a description for topic, the second item
contains the message data specification (MDS). Note topic name
is in tuple format ('a', 'b', 'c') rather than 'a.b.c'. 

Return an iterator over topic names available from this provider.
Note that the topic names should be in tuple rather than dotted-string
format so as to be compatible with getDefn().

Object for wrapping/filling text.  The public interface consists of
the wrap() and fill() methods; the other methods are just there for
subclasses to override in order to tweak the default behaviour.
If you want to completely replace the main wrapping algorithm,
you'll probably have to override _wrap_chunks().

Several instance attributes control various aspects of wrapping:
  width (default: 70)
    the maximum width of wrapped lines (unless break_long_words
    is false)
  initial_indent (default: "")
    string that will be prepended to the first line of wrapped
    output.  Counts towards the line's width.
  subsequent_indent (default: "")
    string that will be prepended to all lines save the first
    of wrapped output; also counts towards each line's width.
  expand_tabs (default: true)
    Expand tabs in input text to spaces before further processing.
    Each tab will become 0 .. 'tabsize' spaces, depending on its position
    in its line.  If false, each tab is treated as a single character.
  tabsize (default: 8)
    Expand tabs in input text to 0 .. 'tabsize' spaces, unless
    'expand_tabs' is false.
  replace_whitespace (default: true)
    Replace all whitespace characters in the input text by spaces
    after tab expansion.  Note that if expand_tabs is false and
    replace_whitespace is true, every tab will be converted to a
    single space!
  fix_sentence_endings (default: false)
    Ensure that sentence-ending punctuation is always followed
    by two spaces.  Off by default because the algorithm is
    (unavoidably) imperfect.
  break_long_words (default: true)
    Break words longer than 'width'.  If false, those words will not
    be broken, and some lines might be longer than 'width'.
  break_on_hyphens (default: true)
    Allow breaking hyphenated words. If true, wrapping will occur
    preferably on whitespaces and right after hyphens part of
    compound words.
  drop_whitespace (default: true)
    Drop leading and trailing whitespace from lines.
  max_lines (default: None)
    Truncate wrapped lines.
  placeholder (default: ' [...]')
    Append to the last line of truncated text.

__init__(self, width=70, initial_indent="", subsequent_indent="", expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, \*, max_lines=None, placeholder=' [...]')

fill(text : string) -> string

Reformat the single paragraph in 'text' to fit in lines of no
more than 'self.width' columns, and return a new string
containing the entire wrapped paragraph.

wrap(text : string) -> [string]

Reformat the single paragraph in 'text' so it fits in lines of
no more than 'self.width' columns, and return a list of wrapped
lines.  Tabs in 'text' are expanded with string.expandtabs(),
and all other whitespace characters (including newline) are
converted to space.

re.compile('\n        ( # any whitespace\n          [\\\t\\\n\\\x0b\\\x0c\\\r\\ ]+\n        | # em-dash between words\n          (?<=[\\w!"\\\'&.,?]) -{2,} (?=\\w)\n        | # word, possibly hyphenated\n       , re.VERBOSE)

Convert a nested class tree as a topic definition tree. Format: the class
name is the topic name, its doc string is its description. The topic's
message data specification is determined by inspecting a class method called
the same as SPEC_METHOD_NAME. The doc string of that method is parsed to
extract the description for each message data.
 
If pyClassObj is given, it is an object that contains nested
classes defining root topics; the root topics contain nested
classes defining subtopics; etc.

Deserialize a module containing Python source code defining a topic tree.
This loads the module and gives it to an instance of TopicDefnDeserialClass.

Load the given named module, searched for in searchPath or, if not
specified, in sys.path. Give it to a TopicDefnDeserialClass.

Deserialize a string containing Python source code defining a topic tree.
The string has the same format as expected by TopicDefnDeserialModule.

This just saves the string into a temporary file created in
os.getcwd(), and the rest is delegated to TopicDefnDeserialModule.
The temporary file (module -- as well as its byte-compiled
version) will be deleted when the doneIter() method is called.

Default implementation of the ITopicDefnProvider API. This
implementation accepts several formats for the topic tree
source data and delegates to a registered ITopicDefnDeserializer
that converts source data into topic definitions.

This provider is instantiated automatically by
``pub.addTopicDefnProvider(source, format)``
when source is *not* an ITopicDefnProvider.

Additional de-serializers can be registered via registerTypeForImport().

Find the correct de-serializer class from registry for the given
format; instantiate it with given source and providerKwargs; get
all available topic definitions.

Helper class to print the topic tree using the Python class
syntax. The "printout" can be sent to any file object (object that has a
write() method). If printed to a module, the module can be imported and
given to pub.addTopicDefnProvider(module, 'module'). Importing the module
also provides code completion of topic names (rootTopic.subTopic can be
given to any pubsub function requiring a topic name).

For formatting, can specify the width of output, the indent step, the
header and footer to print to override defaults. The destination is fileObj;
if none is given, then sys.stdout is used. If rootTopic is given, calls
writeAll(rootTopic) at end of __init__.

Topic tree for application.
Used via pub.addTopicDefnProvider(thisModuleName).

# End of topic tree definition. Note that application may load
# more than one definitions provider.

__init__(self, rootTopic=None, fileObj=None, width=70, indentStep=4, treeDoc = defaultTopicTreeSpecHeader, footer = defaultTopicTreeSpecFooter)

Each line that was sent to fileObj was saved in a list; returns a
string which is ``'\n'.join(list)``.

Traverse each topic of topic tree, starting at topicObj, printing
each topic definition as the tree gets traversed. 

Supports taking action on every topic in the topic tree. The traverse() method 
traverses a topic tree and calls visitor._onTopic() for each topic in the tree 
that satisfies visitor._accept(). Additionally it calls visitor._startChildren() 
whenever it starts traversing the subtopics of a topic, and 
visitor._endChildren() when it is done with the subtopics. Finally, it calls 
visitor._doneTraversal() when traversal has been completed. The visitor must 
therefore adhere to the ITopicTreeVisitor interface.

The visitor, if given, must adhere to API of
ITopicTreeVisitor. The visitor can be changed or
set via setVisitor(visitor) before calling traverse().

Start traversing tree at topicObj. Note that topicObj is a
Topic object, not a topic name. The how defines if tree should
be traversed breadth or depth first. If onlyFiltered is
False, then all nodes are accepted (_accept(node) not called).

This method can be called multiple times.

Raised when a topic definition provider doesn't recognize the format 
of source input it was given. 

Remove any common leading whitespace from every line in `text`.

This can be used to make triple-quoted strings line up with the left
edge of the display, while still presenting them in the source code
in indented form.

Note that tabs and spaces are both treated as whitespace, but they
are not equal: the lines "  hello" and "\thello" are
considered to have no common leading whitespace.

Entirely blank lines are normalized to a newline character.

Using TopicTreeSpecPrinter, exports the topic tree rooted at rootTopic to a
Python module (.py) file. This module will define module-level classes
representing root topics, nested classes for subtopics etc. Returns a string
representing the contents of the file. Parameters:

    - If moduleName is given, the topic tree is written to moduleName.py in
      os.getcwd(). By default, it is first backed up, it it already exists,
      using bak as the filename extension. If bak is None, existing module file
      gets overwritten.
    - If rootTopic is specified, the export only traverses tree from
      corresponding topic. Otherwise, complete tree, using
      pub.getDefaultTopicTreeRoot() as starting  point.
    - The moduleDoc is the doc string for the module ie topic tree.

exportTopicTreeSpec(moduleName = None, rootTopic=None, bak='bak', moduleDoc=None)

'# End of topic tree definition. Note that application may load\n# more than one definitions provider.\n'

'\nTopic tree for application.\nUsed via pub.addTopicDefnProvider(thisModuleName).\n'

Raised when a listener exception handler (see pub.setListenerExcHandler())
raises an exception. The original exception is contained.

The badExcListenerID is the name of the listener that raised
the original exception that handler was attempting to handle.
The topicObj is the Topic object for the topic of the
sendMessage that had an exception raised. 
The origExc is currently not used. 

Raised when an operation requires a topic have an MDS, but it doesn't. 
See also pub.setTopicUnspecifiedFatal().

Raised when the topic name is not properly formatted or
no corresponding Topic object found. 

Code related to the concept of topic tree and its management: creating 
and removing topics, getting info about a particular topic, etc. 

Stores a list of topic definition providers. When queried for a topic
definition, queries each provider (registered via addProvider()) and
returns the first complete definition provided, or (None,None).

The providers must follow the ITopicDefnProvider protocol.

Returns a pair (docstring, MDS) for the topic. The first item is
a string containing the topic's "docstring", i.e. a description string 
for the topic, or None if no docstring available for the topic. The 
second item is None or an instance of ArgSpecGiven specifying the
required and optional message data for listeners of this topic. 

Returns True only if a complete definition exists, ie topic
has a description and a complete message data specification (MDS).

Represent topics in pubsub. Contains information about a topic, 
including topic's message data specification (MDS), the list of 
subscribed listeners, docstring for the topic. It allows Python-like 
access to subtopics (e.g. A.B is subtopic B of topic A).

Create a topic. Should only be called by TopicManager via its
getOrCreateTopic() method (which gets called in several places 
in pubsub, such as sendMessage, subscribe, and newTopic).

:param treeConfig: topic tree configuration settings
:param nameTuple: topic name, in tuple format (no dots)
:param description: "docstring" for topic
:param ArgsInfo msgArgsInfo: object that defines MDS for topic
:param parent: parent of topic

:raises ValueError: invalid topic name

__init__(self, treeConfig, nameTuple, description, msgArgsInfo, parent=None)

Get a map of keyword names to docstrings: documents each MDS element. 

Returns a pair (reqdArgs, optArgs) where reqdArgs is tuple
of names of required message arguments, optArgs is tuple
of names for optional arguments. If topic args not specified
yet, returns (None, None).

Get a copy of list of listeners subscribed to this topic. Safe to iterate over while listeners
get un/subscribed from this topics (such as while sending a message).

Get an iterator over listeners subscribed to this topic. Do not use if listeners can be
un/subscribed while iterating. 

Return number of listeners currently subscribed to topic. This is
different from number of listeners that will get notified since more
general topics up the topic tree may have listeners.

Get Topic object that is parent of self (i.e. self is a subtopic
of parent). Return none if self is the "all topics" topic.

Get the specified subtopic object. The relName can be a valid
subtopic name, a dotted-name string, or a tuple. 

Return true if there are any listeners subscribed to
this topic, false otherwise.

Return true if this topic has a message data specification (MDS).

Return true only if name is a subtopic of self. If name not
specified, return true only if self has at least one subtopic.

Returns true if this topic is the 'all topics' topic. All root
topics behave as though they are child of that topic. 

Returns true if this is a "root" topic, false otherwise. A
root topic is a topic whose name contains no dots and which
has pub.ALL_TOPICS as parent.

Return True only if listener could be subscribed to this topic,
otherwise returns False. Note that method raises TopicDefnError
if self not hasMDS().

Specify the message data for topic messages.
:param argsDocs: a dictionary of keyword names (message data name) and data 'docstring'; cannot be None
:param required: a list of those keyword names, appearing in argsDocs, 
which are required (all others are assumed optional)
    
Can only be called if this info has not been already set at construction 
or in a previous call. 
:raise RuntimeError: if MDS already set at construction or previous call.

Subscribe listener to this topic. Returns a pair
(pub.Listener, success). The success is true only if listener
was not already subscribed and is now subscribed. 

Unsubscribe the specified listener from this topic. Returns
the pub.Listener object associated with the listener that was
unsubscribed, or None if the specified listener was not
subscribed to this topic.  Note that this method calls
``notifyUnsubscribe(listener, self)`` on all registered notification
handlers (see pub.addNotificationHandler).

Clears list of subscribed listeners. If filter is given, it must
be a function that takes a listener and returns true if the listener
should be unsubscribed. Returns the list of Listener for listeners 
that were unsubscribed.

Checks whether listener could be subscribed to this topic:
if yes, just returns; if not, raises ListenerMismatchError.
Note that method raises TopicDefnError if self not
hasMDS().

If topicName is a tuple of strings, just return it as is. Otherwise,
convert it to tuple, assuming dotted notation used for topicName. I.e. 
'a.b.c' => ('a','b','c'). Empty topicName is not allowed (ValueError). 
The reverse operation is stringize(topicNameTuple).

Check that names in topicTuple are valid: no spaces, not empty.
Raise ValueError if fails check. E.g. ('',) and ('a',' ') would
both fail, but ('a','b') would be ok. 

Provide the Topic class.

Dedent paragraph using textwrap.dedent(), but properly dedents
even if the first line of paragraph does not contain blanks. 
This handles the case where a user types a documentation string as 
    '''A long string spanning
    several lines.'''

Derive from ITopicTreeVisitor and override one or more of the
self._*() methods. Give an instance to an instance of 
TopicTreeTraverser.

Various utilities used by topic-related modules. 

Some topic definition validation functions. 

Verify that allArgs does not contain any of allParentArgs. Raise

This module provides a basic "weak method" implementation, WeakMethod. It uses
weakref.WeakRef which, used on its own, produces weak methods that are dead on
creation, not very useful. Use the getWeakRef(object) module function to create the
proper type of weak reference (weakref.WeakRef or WeakMethod) for given object.

method(function, instance)

Create a bound instance method object.

Represent a weak bound method, i.e. a method which doesn't keep alive the
object that it is bound to. 

The method must be bound. notifyDead will be called when
object that method is bound to dies. 

Return true if we are storing same object referred to by weakRef.

Get a weak reference to obj. If obj is a bound method, a WeakMethod
object, that behaves like a WeakRef, is returned; if it is
anything else a WeakRef is returned. If obj is an unbound method,
a ValueError will be raised.

Provides utility functions and classes that are not required for using 
pubsub but are likely to be very useful. 

Some utility classes for exception handling of exceptions raised
within listeners:

- TracebackInfo: convenient way of getting stack trace of latest
  exception raised. The handler can create the instance to retrieve
  the stack trace and then log it, present it to user, etc.
- ExcPublisher: example handler that publishes a message containing
  traceback info

Example exception handler that simply publishes the exception traceback
as a message of topic name given by topicUncaughtExc.

If topic manager is specified, will automatically call init().
Otherwise, caller must call init() after pubsub imported. See
pub.setListenerExcHandler().

Must be called only after pubsub has been imported since this
handler creates a pubsub topic.

Represent the traceback information for when an exception is
raised -- but not caught -- in a listener. The complete
traceback cannot be stored since this leads to circular
references (see docs for sys.exc_info()) which keeps
listeners alive even after the application is no longer
referring to them.

Instances of this object are given to listeners of the
'uncaughtExcInListener' topic as the excTraceback kwarg.
The instance calls sys.exc_info() to get the traceback
info but keeps only the following info:

 * self.ExcClass: the class of exception that was raised and not caught
 * self.excArg: the argument given to exception when raised
 * self.traceback: list of quadruples as returned by traceback.extract_tb()

Normally you just need to call one of the two getFormatted() methods.

Get a list of strings as returned by the traceback module's
format_list() and format_exception_only() functions.

Get a string similar to the stack trace that gets printed
to stdout by Python interpreter when an exception is not caught.

Provides useful functions and classes. Most useful are probably
printTreeDocs and printTreeSpec.

This can be used to wrap functions that are referenced by class
data if the data should be called as a function. E.g. given
>>> def func(): pass
>>> class A:
....def __init__(self): self.a = func
then doing
>>> boo=A(); boo.a()
will fail since Python will try to call a() as a method of boo,
whereas a() is a free function. But if you have instead
"self.a = Callback(func)", then "boo.a()" works as expected.

Used only internally. Represent one value out of an enumeration
set.  It is meant to be used as::

    class YourAllowedValues:
        enum1 = Enum()
        # or:
        enum2 = Enum(value)
        # or:
        enum3 = Enum(value, 'descriptionLine1')
        # or:
        enum3 = Enum(None, 'descriptionLine1', 'descriptionLine2', ...)

    val = YourAllowedValues.enum1
    ...
    if val is YourAllowedValues.enum1:
        ...

set() -> new empty set object
set(iterable) -> new set object

Build an unordered collection of unique elements.

This *can* be used to package message data. Each of the keyword
args given at construction will be stored as a member of the 'data'
member of instance. E.g. "m=Message2(a=1, b='b')" would succeed
"assert m.data.a==1" and "assert m.data.b=='b'". However, use of
Message2 makes your messaging code less documented and harder to
debug.

Provide an interface class for handling pubsub notification messages, 
and an example class (though very useful in practice) showing how to 
use it. 

Notification messages are generated by pubsub

- if a handler has been configured via pub.addNotificationHandler()
- when pubsub does certain tasks, such as when a listener subscribes to
  or unsubscribes from a topic
  
Derive from this class to handle notification events from 
various parts of pubsub. E.g. when a listener subscribes, 
unsubscribes, or dies, a notification handler, if you 
specified one via pub.addNotificationHandler(), is given the 
relevant information. 

Derive your Notifications handler from this class if your handler
just wants to be notified of one or two types of pubsub events.
Then just override the desired methods. The rest of the notifications
will automatically be ignored.

Handle pubsub notification messages by generating
messages of a 'pubsub.' subtopic. Also provides
an example of how to create a notification handler.  

Use it by calling::

    import pubsub.utils
    pubsub.utils.useNotifyByPubsubMessage()
    ...
    pub.setNotificationFlags(...) # optional
    
E.g. whenever a listener is unsubscribed, a 'pubsub.unsubscribe'
message is generated. If you have subscribed a listener of 
this topic, your listener will be notified of what listener 
unsubscribed from what topic. 

Create the notification topics. The root of the topics created
is self.topicRoot. The topicMgr is (usually) pub.topicMgr.

Stage must be 'pre' or 'post'. Note that any pubsub sendMessage
operation resulting from this notification (which sends a message; 
listener could handle by sending another message!) will NOT themselves
lead to a send notification. 

{'send': 'pubsub.sendMessage', 'subscribe': 'pubsub.subscribe', 'unsubscribe': 'pubsub.unsubscribe', 'newTopic': 'pubsub.newTopic', 'delTopic': 'pubsub.delTopic', 'deadListener': 'pubsub.deadListener'}

Will write to stdout unless fileObj given. Will use
defaultPrefix as prefix for each line output, unless prefix
specified. 

Will cause all of pubsub's notifications of pubsub "actions" (such as
new topic created, message sent, listener subscribed, etc) to be sent
out as messages. Topic will be 'pubsub' subtopics, such as
'pubsub.newTopic', 'pubsub.delTopic', 'pubsub.sendMessage', etc.

The 'all' and kwargs args are the same as pubsub's setNotificationFlags(), 
except that 'all' defaults to True.

The publisher is rarely needed:

* The publisher must be specified if pubsub is not installed
  on the system search path (ie from pubsub import ... would fail or
  import wrong pubsub -- such as if pubsub is within wxPython's
  wx.lib package). Then pbuModule is the pub module to use::

    from wx.lib.pubsub import pub
    from wx.lib.pubsub.utils import notification
    notification.useNotifyByPubsubMessage()

Will cause all pubsub notifications of pubsub "actions" (such as
new topic created, message sent, listener died etc) to be written to
specified file (or stdout if none given). The fileObj need only
provide a 'write(string)' method.

The first two arguments are the same as those of NotifyByWriteFile
constructor. The 'all' and kwargs arguments are those of pubsub's
setNotificationFlags(), except that 'all' defaults to True.  See
useNotifyByPubsubMessage() for an explanation of pubModule (typically
only if pubsub inside wxPython's wx.lib)

useNotifyByWriteFile(fileObj=None, prefix=None, publisher=None, all=True, \*\*kwargs)

Output various aspects of topic tree to string or file.

Example topic tree visitor that prints a prettified representation
of topic tree by doing a depth-first traversal of topic tree and
print information at each (topic) node of tree. Extra info to be
printed is specified via the 'extra' kwarg. Its value must be a
list of characters, the order determines output order:
- D: print description of topic
- a: print kwarg names only
- A: print topic kwargs and their description
- L: print listeners currently subscribed to topic

E.g. TopicTreePrinter(extra='LaDA') would print, for each topic,
the list of subscribed listeners, the topic's list of kwargs, the
topic description, and the description for each kwarg,

    >>> Topic "delTopic"
       >> Listeners:
          > listener1_2880 (from yourModule)
          > listener2_3450 (from yourModule)
       >> Names of Message arguments:
          > arg1
          > arg2
       >> Description: whenever a topic is deleted
       >> Descriptions of Message arguments:
          > arg1: (required) its description
          > arg2: some other description

Topic tree printer will print listeners for each topic only
if printListeners is True. The width will be used to limit
the width of text output, while indentStep is the number of
spaces added each time the text is indented further. The
three bullet parameters define the strings used for each
item (topic, topic items, and kwargs). 

__init__(self, extra=None, width=70, indentStep=4, bulletTopic='\\--', bulletTopicItem='|==', bulletTopicArg='-', fileObj=None)

frozenset() -> empty frozenset object
frozenset(iterable) -> frozenset object

Build an immutable unordered collection of unique elements.

Print out the topic tree to a file (or file-like object like a
StringIO), starting at rootTopic. If root topic should be root of
whole tree, get it from pub.getDefaultTopicTreeRoot().
The treeVisitor is an instance of pub.TopicTreeTraverser.

Printing the tree docs would normally involve this::

    from pubsub.utils.topictreeprinter import TopicTreePrinter
    traverser = pub.TopicTreeTraverser( TopicTreePrinter(**kwargs) )
    traverser.traverse( pub.getDefaultTopicTreeRoot() )

With printTreeDocs, it looks like this::

    from pubsub.utils import printTreeDocs
    printTreeDocs()

The kwargs are the same as for TopicTreePrinter constructor:
extra(None), width(70), indentStep(4), bulletTopic, bulletTopicItem,
bulletTopicArg, fileObj(stdout). If fileObj not given, stdout is used.

Contributed by Joshua R English, adapted by Oliver Schoenborn to be
consistent with pubsub API.

An extension for pubsub (http://pubsub.sourceforge.net) so topic tree
specification can be encoded in XML format rather than pubsub's default
Python nested class format.

To use:

    xml = '''
        <topicdefntree>
        <description>Test showing topic hierarchy and inheritance</description>
        <topic id="parent">
            <description>Parent with a parameter and subtopics</description>
            <listenerspec>
                <arg id="name" optional="true">given name</arg>
                <arg id="lastname">surname</arg>
            </listenerspec>

            <topic id="child">
                <description>This is the first child</description>
                <listenerspec>
                    <arg id="nick">A nickname</arg>
                </listenerspec>
            </topic>
        </topic>
        </topicdefntree>
    '''

These topic definitions are loaded through an XmlTopicDefnProvider:

    pub.addTopicDefnProvider( XmlTopicDefnProvider(xml) )

The XmlTopicDefnProvider also accepts a filename instead of XML string:

    provider = XmlTopicDefnProvider("path/to/XMLfile.xml", TOPIC_TREE_FROM_FILE)
    pub.addTopicDefnProvider( provider )

Topics can be exported to an XML file using the exportTopicTreeSpecXml function.
This will create a text file for the XML and return the string representation
of the XML tree.

:copyright: Copyright since 2013 by Oliver Schoenborn, all rights reserved.

If rootTopic is None, then pub.getDefaultTopicTreeRoot() is assumed.

exportTopicTreeSpecXml(moduleName=None, rootTopic=None, bak='bak', moduleDoc=None)

Aggregates policies for pubsub. Mainly, related to messaging protocol. 

setMsgDataArgName(stage, listenerArgName, senderArgNameAny=False)

This is the main entry-point to pubsub's core functionality. The :mod:`~pubsub.pub` 
module supports:

* messaging: publishing and receiving messages of a given topic
* tracing: tracing pubsub activity in an application
* trapping exceptions: dealing with "badly behaved" listeners (ie that leak exceptions)
* specificatio of topic tree: defining (or just documenting) the topic tree of an 
  application; message data specification (MDS)

The recommended usage is ::

    // use pub functions:
    pub.sendMessage(...)
    
Note that this module creates a "default" instance of 
pubsub.core.Publisher and binds several local functions to some of its methods
and those of the pubsub.core.TopicManager instance that it contains. However, an
application may create as many independent instances of Publisher as
required (for instance, one in each thread; with a custom queue to mediate 
message transfer between threads).

Get the Publisher instance created by default when this module
is imported. See the module doc for details about this instance.

Get the TopicManager instance created by default when this 
module is imported. This function is a shortcut for 
``pub.getDefaultPublisher().getTopicMgr()``.

Loop over all topics of given provider and "instantiate" each topic, thus 
forcing a parse of the topics documentation, message data specification (MDS), 
comparison with parent MDS, and MDS documentation. Without this function call, 
an error among any of those characteristics will manifest only if the a 
listener is registered on it. 

Returns true if listener has subscribed to topicName, false otherwise.
WARNING: a false return is not a guarantee that listener won't get
messages of topicName: it could receive messages of a subtopic of
topicName. 

Return true only if listener can subscribe to messages of given topic.

Checks if listener can subscribe to topicName. If not, raises
ListenerMismatchError, otherwise just returns.

<wx.lib.pubsub.core.publisher.Publisher object at 0x7fe267ba3c90>

<wx.lib.pubsub.core.topicmgr.TopicManager object at 0x7fe267ba3f50>

{'ALL_TOPICS': <wx.lib.pubsub.core.topicobj.Topic object at 0x7fe2684d2650>}

Return a copy of B with only its first character capitalized (ASCII)
and the rest lower-cased.

Return B centered in a string of length width.  Padding is
done using the specified fill character (default is a space).

Return the number of non-overlapping occurrences of subsection sub in
bytes B[start:end].  Optional arguments start and end are interpreted
as in slice notation.

Decode the bytes using the codec registered for encoding.

encoding
  The encoding with which to decode the bytes.
errors
  The error handling scheme to use for the handling of decoding errors.
  The default is 'strict' meaning that decoding errors raise a
  UnicodeDecodeError. Other possible values are 'ignore' and 'replace'
  as well as any other name registered with codecs.register_error that
  can handle UnicodeDecodeErrors.

Return True if B ends with the specified suffix, False otherwise.
With optional start, test B beginning at that position.
With optional end, stop comparing B at that position.
suffix can also be a tuple of bytes to try.

Return a copy of B where all tab characters are expanded using spaces.
If tabsize is not given, a tab size of 8 characters is assumed.

Return the lowest index in B where subsection sub is found,
such that sub is contained within B[start,end].  Optional
arguments start and end are interpreted as in slice notation.

Return -1 on failure.

Create a bytes object from a string of hexadecimal numbers.

Spaces between two numbers are accepted.
Example: bytes.fromhex('B9 01EF') -> b'\\xb9\\x01\\xef'.

Create a string of hexadecimal numbers from a bytes object.
Example: b'\xb9\x01\xef'.hex() -> 'b901ef'.

Raises ValueError when the subsection is not found.

Return True if all characters in B are alphanumeric
and there is at least one character in B, False otherwise.

Return True if all characters in B are alphabetic

Return True if B is empty or all characters in B are ASCII,
False otherwise.

Return True if all characters in B are digits

Return True if all cased characters in B are lowercase and there is
at least one cased character in B, False otherwise.

Return True if all characters in B are whitespace

Return True if B is a titlecased string and there is at least one
character in B, i.e. uppercase characters may only follow uncased
characters and lowercase characters only cased ones. Return False

Return True if all cased characters in B are uppercase and there is

Concatenate any number of bytes objects.

The bytes whose method is called is inserted in between each pair.

The result is returned as a new bytes object.

Example: b'.'.join([b'ab', b'pq', b'rs']) -> b'ab.pq.rs'.

Return B left justified in a string of length width. Padding is

Return a copy of B with all ASCII characters converted to lowercase.

Strip leading bytes contained in the argument.

If the argument is omitted or None, strip leading  ASCII whitespace.

Partition the bytes into three parts using the given separator.

This will search for the separator sep in the bytes. If the separator is found,
returns a 3-tuple containing the part before the separator, the separator
itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original bytes
object and two empty bytes objects.

Return a copy with all occurrences of substring old replaced by new.

  count
    Maximum number of occurrences to replace.
    -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are
replaced.

Return the highest index in B where subsection sub is found,

Raise ValueError when the subsection is not found.

Return B right justified in a string of length width. Padding is
done using the specified fill character (default is a space)

This will search for the separator sep in the bytes, starting at the end. If
the separator is found, returns a 3-tuple containing the part before the
separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty bytes
objects and the original bytes object.

Return a list of the sections in the bytes, using sep as the delimiter.

  sep
    The delimiter according which to split the bytes.
    None (the default value) means split on ASCII whitespace characters
    (space, tab, return, newline, formfeed, vertical tab).
  maxsplit
    Maximum number of splits to do.
    -1 (the default value) means no limit.

Splitting is done starting at the end of the bytes and working to the front.

Strip trailing bytes contained in the argument.

If the argument is omitted or None, strip trailing ASCII whitespace.

sep
  The delimiter according which to split the bytes.
  None (the default value) means split on ASCII whitespace characters
  (space, tab, return, newline, formfeed, vertical tab).
maxsplit
  Maximum number of splits to do.
  -1 (the default value) means no limit.

Return a list of the lines in the bytes, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and
true.

Return True if B starts with the specified prefix, False otherwise.
prefix can also be a tuple of bytes to try.

Strip leading and trailing bytes contained in the argument.

If the argument is omitted or None, strip leading and trailing ASCII whitespace.

Return a copy of B with uppercase ASCII characters converted
to lowercase ASCII and vice versa.

Return a titlecased version of B, i.e. ASCII words start with uppercase
characters, all remaining cased characters have lowercase.

Return a copy with each character mapped by the given translation table.

  table
    Translation table, which must be a bytes object of length 256.

All characters occurring in the optional argument delete are removed.
The remaining characters are mapped through the given translation table.

Return a copy of B with all ASCII characters converted to uppercase.

Pad a numeric string B with zeros on the left, to fill a field
of the specified width.  B is never truncated.

Create a six.moves.urllib namespace that resembles the Python 3 namespace

__init__(self, name, old_mod, new_mod, old_attr=None, new_attr=None)

range(stop) -> range object
range(start, stop[, step]) -> range object

Return an object that produces a sequence of integers from start (inclusive)
to stop (exclusive) by step.  range(i, j) produces i, i+1, i+2, ..., j-1.
start defaults to 0, and stop is omitted!  range(4) produces 0, 1, 2, 3.
These are exactly the valid indices for a list of 4 elements.
When step is given, it specifies the increment (or decrement).

count(value) -> integer -- return number of occurrences of value

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower
case.

Return a version of the string suitable for caseless comparisons.

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

Return the number of non-overlapping occurrences of substring sub in
string S[start:end].  Optional arguments start and end are
interpreted as in slice notation.

Encode the string using the codec registered for encoding.

encoding
  The encoding in which to encode the string.
errors
  The error handling scheme to use for encoding errors.
  The default is 'strict' meaning that encoding errors raise a
  UnicodeEncodeError.  Other possible values are 'ignore', 'replace' and
  'xmlcharrefreplace' as well as any other name registered with
  codecs.register_error that can handle UnicodeEncodeErrors.

Return True if S ends with the specified suffix, False otherwise.
With optional start, test S beginning at that position.
With optional end, stop comparing S at that position.
suffix can also be a tuple of strings to try.

Return a copy where all tab characters are expanded using spaces.

Return the lowest index in S where substring sub is found,
such that sub is contained within S[start:end].  Optional

Return a formatted version of S, using substitutions from args and kwargs.
The substitutions are identified by braces ('{' and '}').

Return a formatted version of S, using substitutions from mapping.

Return the lowest index in S where substring sub is found, 

Raises ValueError when the substring is not found.

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and
there is at least one character in the string.

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there
is at least one character in the string.

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F.
Empty string is ASCII too.

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there

Return True if the string is a valid Python identifier, False otherwise.

Use keyword.iskeyword() to test for reserved identifiers such as "def" and
"class".

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and
there is at least one cased character in the string.

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at
least one character in the string.

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in
repr() or if it is empty.

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only
follow uncased characters and lowercase characters only cased ones.

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and

Concatenate any number of strings.

The string whose method is called is inserted in between each given string.
The result is returned as a new string.

Example: '.'.join(['ab', 'pq', 'rs']) -> 'ab.pq.rs'

Return a left-justified string of length width.

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

Partition the string into three parts using the given separator.

This will search for the separator in the string.  If the separator is found,

If the separator is not found, returns a 3-tuple containing the original string
and two empty strings.

Return the highest index in S where substring sub is found,

Return a right-justified string of length width.

This will search for the separator in the string, starting at the end. If

If the separator is not found, returns a 3-tuple containing two empty strings
and the original string.

Return a list of the words in the string, using sep as the delimiter string.

  sep
    The delimiter according which to split the string.
    None (the default value) means split according to any whitespace,
    and discard empty strings from the result.
  maxsplit

Splits are done starting at the end of the string and working to the front.

Return a copy of the string with trailing whitespace removed.

sep
  The delimiter according which to split the string.
  None (the default value) means split according to any whitespace,
  and discard empty strings from the result.
maxsplit

Return a list of the lines in the string, breaking at line boundaries.

true.

Return True if S starts with the specified prefix, False otherwise.
prefix can also be a tuple of strings to try.

Return a copy of the string with leading and trailing whitespace removed.

Convert uppercase characters to lowercase and lowercase characters to uppercase.

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining
cased characters have lower case.

Replace each character in the string using the given translation table.

  table
    Translation table, which must be a mapping of Unicode ordinals to
    Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a
dictionary or list.  If this operation raises LookupError, the character is
left untouched.  Characters mapped to None are deleted.

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

Text I/O implementation using an in-memory buffer.

The initial_value argument sets the value of object.  The newline
argument is like the one of TextIOWrapper's constructor.

Close the IO object.

Attempting any further operation after the object is closed
will raise a ValueError.

This method has no effect if the file is already closed.

Read at most size characters, returned as a string.

If the argument is negative or omitted, read until EOF
is reached. Return an empty string at EOF.

Read until newline or EOF.

Returns an empty string if EOF is hit immediately.

Seek to character offset pos relative to position indicated by whence:
    0  Start of stream (the default).  pos should be >= 0;
    1  Current position - pos must be 0;
    2  End of stream - pos must be 0.

Truncate size to pos.

The pos argument defaults to the current file position, as
returned by tell().  The current file position is unchanged.

Write string to file.

Returns the number of characters written, which is always equal to
the length of the string.

Line endings translated so far.

Only line endings translated during reading are considered.

Subclasses should override.

Return an iterator over the (key, [values]) pairs of a dictionary.

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7350>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7390>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be73d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7410>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7450>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7490>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be74d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7510>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7550>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7590>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be75d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7610>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be7650>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7690>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be76d0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7710>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7750>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7790>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be77d0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7810>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7850>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7890>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be78d0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7910>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7950>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7990>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be79d0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7a10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7a50>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7a90>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7ad0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7b10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7b50>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7b90>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7bd0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7c10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7c50>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7c90>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7cd0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7d10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7d50>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7d90>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7dd0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7e10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7e50>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7ed0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7f10>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7f90>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be7fd0>, <wx.lib.pubsub.py2and3.MovedModule object at 0x7fe267be8090>]

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be86d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8710>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8750>]

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8150>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8190>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8210>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be82d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8390>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be83d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8450>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8490>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be84d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8510>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8550>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8590>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be85d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8610>]

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8810>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8850>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be88d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8910>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8950>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8990>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be89d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8a50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8a90>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8ad0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8b50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8b90>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8bd0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8c10>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8c50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8cd0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8d10>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8d50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8dd0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8e50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8ed0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8f10>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8f50>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8f90>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267be8fd0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea090>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea0d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea110>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea150>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea190>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea1d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea210>]

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea2d0>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea310>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea350>, <wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea390>]

[<wx.lib.pubsub.py2and3.MovedAttribute object at 0x7fe267bea410>]

itemgetter(item, ...) --> itemgetter object

Return a callable object that fetches the given item(s) from its operand.
After f = itemgetter(2), the call f(r) returns r[2].
After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

methodcaller(name, ...) --> methodcaller object

Return a callable object that calls the given method on its operand.
After f = methodcaller('name'), the call f(r) returns r.name().
After g = methodcaller('name', 'date', foo=1), the call g(r) returns
r.name('date', foo=1).

Setup pubsub for the *arg1* message protocol. In a default pubsub installation
the default protocol is *kargs*.

This module must be imported before the first ``from pubsub import pub``
statement in the application. Once :mod:pub has been imported, the messaging
protocol must not be changed (i.e., importing it after the first
``from pubsub import pub`` statement has undefined behavior).
::

    from .. import setuparg1
    from .. import pub

The *arg1* protocol is identical to the legacy messaging protocol from
first version of pubsub (when it was still part of wxPython) and
is *deprecated*. This module is therefore *deprecated*.

This will configure pubsub to require that all listeners use
the same argument name (*commonName*) as first parameter. This
is a useful first step in migrating an application that has been
using *arg1* protocol to the more powerful *kwargs* protocol. 

Setup pubsub for the kwargs message protocol. In a default installation
this is the default protocol so this module is only needed if setupkargs
utility functions are used, or in a custom installation where kwargs 
is not the default messaging protocol (such as in some versions of 
wxPython). 

statement in the application. Once :mod:pub has been imported, the messaging 
protocol cannot be changed (i.e., importing it after the first 
``from pubsub import pub`` statement has undefined behavior). 

Utility function to assist migrating an application from using 
the arg1 messaging protocol to using the kwargs protocol. Call this 
after having run and debugged your application with ``setuparg1.enforceArgName(commonName)``. See the migration docs
for more details. 

{'version': 2, ('wx.lib.pubsub has been deprecated, please migrate your code to use pypubsub, available on PyPI.', <class 'wx.core.wxPyDeprecationWarning'>, 25): True}

This package provides some glue code that allows the Cairo library to draw
directly on :class:`wx.DC` objects, convert to/from :class:`wx.Bitmap`
objects, etc. using either the PyCairo or the newer cairocffi Cairo wrappers.
In Cairo terms, the DC is the drawing surface.  The ``CairoContextFromDC``
function in this module will return an instance of the Cairo Context class
that is ready for drawing, using the native cairo surface type for the current
platform.

.. note:: Be sure to import ``wx.lib.wxcairo`` before importing the ``cairo``
   module.

To use Cairo with wxPython you will need to have a few dependencies
installed.  On Linux and other unix-like systems you may already have
them, or can easily get them with your system's package manager.  Just
check if libcairo and either cairocffi or pycairo packages are installed.

On Mac you can get Cairo from MacPorts or similar tools.  Make sure that
the quartz option is turned on so those Mac-specific APIs will be included in
the Cairo library when it is built.  You can then use ``pip install cairocffi``
to get the Python wrappers. If your cairo shared library is in a non-standard
location, then you can help it be found by setting DYLD_FALLBACK_LIBRARY_PATH
in the environment.

On Windows a copy of the Cairo and related DLLs are included with wxPython
inside the wx package folder.  These files were extracted from the GTK runtime
installers found at the following URLs. You can replace those DLLs with others
if you choose, or you can cause the wx_cairocffi module to use DLLs from some
other location by setting the CAIRO environment variable.

    32bit: http://gtk-win.sourceforge.net/home/index.php/Main/Downloads
    64bit: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer

# Name:        wx.lib.wxcairo
# Purpose:     Glue code to allow either the PyCairo package or the
#              cairocffi package to be used with a wx.DC as the cairo
#              surface.
#
#
# Created:     3-Sept-2008
# Copyright:   (c) 2008-2020 by Total Control Software
#

Creates and returns a ``cairo.Context`` object using the :class:`wx.DC` as
the surface.  (Only window, client, paint and memory DC's are allowed at
this time.)

Creates and returns a ``cairo.FontFace`` object from the native
information in a :class:`wx.Font`.

`LayoutAnchors` is a class that implements Delphi's Anchors using
`wx.LayoutConstraints`.

# Name:        wx.lib.anchors
# Purpose:     A class that provides an easy to use interface over layout
#              constraints for anchored layout.
#
#
# Created:     15-Dec-2000
# Copyright:   (c) 2000-2020 by Total Control Software
# 11/30/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Tested with updated demo
#

A class that implements Delphi's Anchors with :class:`wx.LayoutConstraints`.

Anchored sides maintain the distance from the edge of the control
to the same edge of the parent.  When neither side is selected,
the control keeps the same relative position to both sides.

The current position and size of the control and it's parent is
used when setting up the constraints. To change the size or
position of an already anchored control, set the constraints to
None, reposition or resize and reapply the anchors.

    Let's anchor the right and bottom edge of a control and
    resize it's parent.

    ctrl.SetConstraints(LayoutAnchors(ctrl, left=0, top=0, right=1, bottom=1))

    +=========+         +===================+
    | +-----+ |         |                   |
    | |     * |   ->    |                   |
    | +--*--+ |         |           +-----+ |
    +---------+         |           |     * |
                        |           +--*--+ |
                        +-------------------+
    * = anchored edge

    When anchored on both sides the control will stretch horizontally.

    ctrl.SetConstraints(LayoutAnchors(ctrl, 1, 0, 1, 1))

    | *     * |   ->    |                   |
    | +--*--+ |         | +---------------+ |
    +---------+         | *     ctrl      * |
                        | +-------*-------+ |

setConstraintSides(self, side1, side1Edge, side1Anchor, side2, side2Edge, side2Anchor, size, sizeEdge, centre, cPos, cSize, pSize, parent)

A class like :class:`wx.BusyInfo` but which doesn't take up so much space by default
and which has a nicer look.

#  File:         busy.py
#  Description:  A class like wx.BusyInfo but which doesn't take up so much
#                space by default and which has a nicer look.
#
#  Date:         11-Sept-2012
#  Author:       Robin Dunn
#  Tags:         phoenix-port, unittest, documented

This class is just like :class:`wx.BusyInfo`, except that its default
size is smaller, (unless the size of the message requires a larger window
size) and the background and foreground colors of the message box can be
set.

Creating an instance of the class will create and show a window with the
given message, and when the instance is deleted then that window will be
closed. This class also implements the context manager magic methods, so
it can be used with Python's `with` statement, like this::

    with BusyInfo('Please wait...'):
        doSomethingThatNeedsWaiting()

Create a new :class:`BusyInfo`.

:param string `msg`:     a string to be displayed in the BusyInfo window.
:param wx.Window `parent`:  an optional window to be used as the parent of
    the `:class:`BusyInfo`.  If given then the ``BusyInfo`` will be centered
    over that window, otherwise it will be centered on the screen.
:param wx.Colour `bgColour`: colour to be used for the background
    of the :class:`BusyInfo`
:param wx.Colour `fgColour`: colour to be used for the foreground (text)

This module implements various forms of generic buttons, meaning that
they are not built on native controls but are self-drawn.

They act like normal buttons but you are able to better control how they look,
bevel width, colours, etc...

Usage
=====

    import wx
    import wx.lib.buttons as buttons

        def __init__(self, parent, title):

            wx.Frame.__init__(self, parent, wx.ID_ANY, title, size=(400, 300))

            # Build a bitmap button and a normal one
            bmp = wx.ArtProvider.GetBitmap(wx.ART_INFORMATION, wx.ART_OTHER, (16, 16))
            btn1 = buttons.ThemedGenBitmapButton(panel, -1, bmp, pos=(50, 50))

            btn2 = buttons.GenButton(panel, -1, "Hello World!", pos=(50, 100))

    app = wx.App()
    frame = MyFrame(None, 'wx.lib.buttons Test')

# Name:        wx.lib.buttons
# Purpose:     Various kinds of generic buttons, (not native controls but
#              self-drawn.)
#
#
# Created:     9-Dec-1999
#
#

Uses the native renderer to draw the bezel, also handle mouse-overs. 

Handles the ``wx.EVT_ENTER_WINDOW`` and ``wx.EVT_LEAVE_WINDOW`` events for
:class:`GenButton` when used as a themed button.

A mixin that allows to transform :class:`GenButton` in the corresponding
toggle button.

Handles the ``wx.EVT_KEY_DOWN`` event for :class:`GenButton` when used as toggle button.

Handles the ``wx.EVT_KEY_UP`` event for :class:`GenButton` when used as toggle button.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`GenButton` when used as toggle button.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`GenButton` when used as toggle button.

Handles the ``wx.EVT_MOTION`` event for :class:`GenButton` when used as toggle button.

:param wx.Bitmap `bitmap`: the button bitmap;

__init__(self, parent, id=-1, bitmap=wx.NullBitmap, pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, validator = wx.DefaultValidator, name = "genbutton")

Returns the bitmap for the button's disabled state, which may be invalid.

:rtype: :class:`wx.Bitmap`

.. seealso:: :meth:`SetBitmapDisabled`

Returns the bitmap for the button's focused state, which may be invalid.

.. seealso:: :meth:`SetBitmapFocus`

Returns the bitmap for the button's normal state.

.. seealso:: :meth:`SetBitmapLabel`

Returns the bitmap for the button's pressed state, which may be invalid.

.. seealso:: :meth:`SetBitmapSelected`

Sets the bitmap for the disabled button appearance.

:param wx.Bitmap `bitmap`: the bitmap for the disabled button appearance.

   :meth:`GetBitmapDisabled`, :meth:`SetBitmapLabel`,
   :meth:`SetBitmapSelected`, :meth:`SetBitmapFocus`

Sets the bitmap for the focused button appearance.

:param wx.Bitmap `bitmap`: the bitmap for the focused button appearance.

   :meth:`GetBitmapFocus`, :meth:`SetBitmapLabel`,
   :meth:`SetBitmapSelected`, :meth:`SetBitmapDisabled`

Set the bitmap to display normally.
This is the only one that is required.

If `createOthers` is ``True``, then the other bitmaps will be generated
on the fly.  Currently, only the disabled bitmap is generated.

:param wx.Bitmap `bitmap`: the bitmap for the normal button appearance.

.. note:: This is the bitmap used for the unselected state, and for all other
   states if no other bitmaps are provided.

Sets the bitmap for the selected (depressed) button appearance.

:param wx.Bitmap `bitmap`: the bitmap for the selected (depressed) button appearance.

   :meth:`GetBitmapSelected`, :meth:`SetBitmapLabel`,
   :meth:`SetBitmapDisabled`, :meth:`SetBitmapFocus`

__init__(self, parent, id=-1, bitmap=wx.NullBitmap, label='', pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, validator = wx.DefaultValidator, name = "genbutton")

:param integer `id`: the event identifier.

:return: An instance of :class:`GenButton`.

Returns the button toggle status as ``True`` if the button is down, ``False``

:param `btn`: the button object, an instance of :class:`GenButton`.

Set the button toggle status as 'down' or 'up'.

:param bool `isDown`: ``True`` if the button is clicked, ``False`` otherwise.

A module with a calendar control and a calendar dialog and some utility
methods and classes.

# #----------------------------------------------------------------------------
# Name:         calendar.py
# Purpose:      Calendar display control
#
# Author:       Lorne White (email: lorne.white@telusplanet.net)
#
# Created:
# Version:      0.92
# Date:         Nov 26, 2001
# 12/01/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Added new event type EVT_CALENDAR. The reason for this is that the original
#   library used a hardcoded ID of 2100 for generating events. This makes it
#   very difficult to fathom when trying to decode the code since there's no
#   published API. Creating the new event binder might seem like overkill -
#   after all, you might ask, why not just use a new event ID and be done with
#   it? However, a consistent interface is very useful at times; also it makes
#   it clear that we're not just hunting for mouse clicks -- we're hunting
#   wabbit^H^H^H^H (sorry bout that) for calender-driven mouse clicks. So
#   that's my sad story. Shoot me if you must :-)
# o There's still one deprecation warning buried in here somewhere, but I
#   haven't been able to find it yet. It only occurs when displaying a
#   print preview, and only the first time. It *could* be an error in the
#   demo, I suppose.
#
#   Here's the traceback:
#
#   C:\Python\lib\site-packages\wx\core.py:949: DeprecationWarning:
#       integer argument expected, got float
#   newobj = _core.new_Rect(*args, **kwargs)
#
# 12/17/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o A few style-guide nips and tucks
# o Renamed wxCalendar to Calendar
# o Couple of bugfixes
#
# 06/02/2004 - Joerg "Adi" Sieker adi@sieker.info
#
# o Changed color handling, use dictionary instead of members.
#   This causes all color changes to be ignored if they manipulate the members directly.
#   SetWeekColor and other method color methods were adapted to use the new dictionary.
# o Added COLOR_* constants
# o Added SetColor method for Calendar class
# o Added 3D look of week header
# o Added colors for 3D look of header
# o Fixed width calculation.
#   Because of rounding difference the total width and height of the
#   calendar could be up to 6 pixels to small. The last column and row
#   are now wider/taller by the missing amount.
# o Added SetTextAlign method to wxCalendar. This exposes logic
#   which was already there.
# o Fixed CalDraw.SetMarg which set set_x_st and set_y_st which don't get used anywhere.
#   Instead set set_x_mrg and set_y_mrg
# o Changed default X and Y Margin to 0.
# o Added wxCalendar.SetMargin.
#
# 17/03/2004 - Joerg "Adi" Sieker adi@sieker.info
# o Added keyboard navigation to the control.
#   Use the cursor keys to navigate through the ages. :)
#   The Home key function as go to today
# o select day is now a filled rect instead of just an outline
#
# 15/04/2005 - Joe "shmengie" Brown joebrown@podiatryfl.com
# o Adjusted spin control size/placement (On Windows ctrls were overlapping).
# o Set Ok/Cancel buttons to wx.ID_OK & wx.ID_CANCEL to provide default dialog
#   behaviour.
# o If no date has been clicked clicked, OnOk set the result to calend's date,
#   important if keyboard only navigation is used.
#
# 12/10/2006 - Walter Barnes walter_barnes05@yahoo.com
# o Fixed CalDraw to properly render months that start on a Sunday.
#
# 21/10/2006 - Walter Barnes walter_barnes05@yahoo.com
# o Fixed a bug in Calendar: Shift and Control key status was only recorded for
#   left-down events.
# o Added handlers for wxEVT_MIDDLE_DOWN and wxEVT_MIDDLE_DCLICK to generate
#   EVT_CALENDAR for these mouse events.

:param wx.Window `parent`: parent window.

Add a selection of days.

:param `list`: a list of days to select
:param `cfont`: the font color to use
:param `cbackgrd`: the background color to use

Draw a border around the outside of the main display rectangle.

:param `DC`: the :class:`wx.DC` to use
:param `transparent`: use a transparent brush, default is ``False``.

Draw the calendar.

:param `DC`: the :class:`wx.DC` to use to draw upon.
:param `sel_list`: a list of days to override the weekend highlight.

Draw the day text.

:param `DC`: the :class:`wx.DC` to use.
:param `key`: the day to draw

Draw the focus indicator

Calculate and draw the grid lines.

Draw the month and year titles.

Highlight selected days.

Calculate the calendar days and offset position.

:param int `year`: the year to calculate.
:param int `month`: the month to calculate.

Set a color.

:param `name`: the name to assign the color too.
:param `value`: the color to use, see :class:`wx.Colour`

Set the margins.

:param `xmarg`: the x margin
:param `ymarg`: the y margin, also used for the end margin

:param int `xpos`: the x position
:param int `ypos`: the y position

:param `size`: a tuple/list with width and height

Set the font and background color of the week title.

:param `font_color`: the font color, a value as is accepted by :class:`wx.Colour`
:param `week_color`: the week color, a value as is accepted by :class:`wx.Colour`

Set the weekend backgrounds.

:param `font_color`: the font color to use, if ``None`` the default is used.
:param `backgrd`: the background color to use, if ``None`` the default is used.

:param string `name`: the calendar name.

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.Size(200, 200), style=0, validator=wx.DefaultValidator, name="calendar")

Add a selection.

:param `list`: list of days to select
:param `font_color`: the font color to use
:param `back_color`: the back color to use

Draw the focus indicator or a border.

:param `draw`: True draws the focus indicator, False a border

Draw a rectangle.

:param `key`: the day to draw the rectangle on
:param `bgcolor`: the background color

:param `fgcolor`: the color for the pen
:param `width`: the width for the pen

Get a color.

:param `name`: a valid color name, can be defined using :meth:`SetColor`

Get the set calendar date.

:returns: the day, the month and the year

Find the clicked area rectangle.

:param `mx`: the x position
:param `my`: the y position

Move the current date by a given interval of months/years.

:param int `months`: months to add (can be negative)
:param int `years`: years to add (can be negative)
:returns: the new date set.

Determine the calendar rectangle click area and draw a selection.

:param `name`: the name to be assigned to the color.
:param `value`: the color value, see :class:`wx.Colour` for valid values

Set a calendar date.

:param int `day`: the day
:param int `month`: the month
:param int `year`: the year
:raises: `ValueError` when setting an invalid month/year

Set the day.

:raises: `ValueError` if the resulting date is invalid.

Set the margins

:param `xmarg`: the 'x' margin
:param `ymarg`: the 'y' margin

Set the Month.

Set the days to highlight.

:param list `sel`: the list of days to highlight

:param `set_size`: the control size. A value of (-1, -1) indicates a default size,
:type `set_size`: tuple or :class:`wx.Size`

Set the text alignment.

:param `vert`: the vertical alignment
:param `horz`: the horizontal alignment

Set the week title color.

:param `font_color`: the font color to use.
:param `week_color`: the week color to use for the background.

Set the year.

Test to see if the selection has a date and create event.

:param `key`: the day to test

:param integer `month`: the month, if None the current day will be used
:param integer `day`: the day
:param integer `year`: the year

Try and create a :class:`wx.Colour`.

:returns: a :class:`wx.Colour` instance to `in_colour`

{6: 'Sun', 0: 'Mon', 1: 'Tue', 2: 'Wed', 3: 'Thu', 4: 'Fri', 5: 'Sat'}

{0: None, 1: 'January', 2: 'February', 3: 'March', 4: 'April', 5: 'May', 6: 'June', 7: 'July', 8: 'August', 9: 'September', 10: 'October', 11: 'November', 12: 'December'}

# Name:         CDate.py
# Purpose:      Date and Calendar classes
#
# Author:       Lorne White (email: lwhite1@planet.eon.net)
#
# Created:
# Version       0.2 08-Nov-1999
# Tags:         phoenix-port, py3-port, documented, unittest
# Updated:      01-Dec-2004
# Action:       Cast the year variable to an integer under the Date Class
# Reason:       When the year was compared in the isleap() function, if it was
#               in a string format, then an error was raised.
#

:param `year`: the year as an int or string
:param `month`: the month as an int or string
:param `day`: the day as an int or string

Get day of week from a julian day

:param `julian`: the julian day

:returns: the day of week as an integer and Monday = 1

Get the number of days for the month.

:returns: the number of days in the requested month

Convert a julian date

:param int `julian`: the julian date to convert

:returns: year, month day as integers

Verify if year is a leap year.

:param int `year`: the year to check
:return: True or False

Convert a date to Julian

:returns: the julian date number

Return number of leap years in range [y1, y2]
Assume y1 <= y2 and no funny (non-leap century) years

['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']

This module implements various forms of generic checkboxes, meaning that

They should act like normal checkboxes but you are able to better control how they look, etc...

Usage
=====

    class MyFrame(wx.Frame, DefineNativeCheckBoxBitmapsMixin):
        def __init__(self, parent, id=wx.ID_ANY, title=wx.EmptyString,
                     pos=wx.DefaultPosition, size=wx.DefaultSize,
                     style=wx.DEFAULT_FRAME_STYLE, name='frame'):
            wx.Frame.__init__(self, parent, id, title, pos, size, style, name)
            ## self.DefineNativeCheckBoxBitmaps()
            ## self.checkbox_bitmaps = self.GetNativeCheckBoxBitmaps()
            cb1 = GenCheckBox(self, label="PurePython Checkbox1", pos=(10, 10))
            cb2 = GenCheckBox(self, label="PurePython Checkbox2", pos=(10, 50))
            cb1.Bind(wx.EVT_CHECKBOX, self.OnCheckBox)
            cb2.Bind(wx.EVT_CHECKBOX, self.OnCheckBox)
            cb2.SetForegroundColour(wx.GREEN)
            cb2.SetBackgroundColour(wx.BLACK)
            sizer = wx.BoxSizer()
            sizer.Add(cb1, 0, wx.ALL, 5)
            sizer.Add(cb2, 0, wx.ALL, 5)

        def OnCheckBox(self, event):
            evtObj = event.GetEventObject()
            print(evtObj.GetLabel(), evtObj.IsChecked())

    frame = MyFrame(None, wx.ID_ANY, "Test Pure-Py Checkbox")

# Name:        wx.lib.checkbox
# Purpose:     Various kinds of generic checkbox stuff, (not native controls
#              but self-drawn.)
#
# Author:      wxPython Team and wxPyWiki Contributors
#
# Created:     22-June-2020
# Copyright:   (c) 2020 by Total Control Software
# Tags:        phoenix-port, py3-port, documented

Inherit this mixin in your :class:`wx.Window` based subclass to easily
define the native CheckBox Bitmaps as attributes which can then be used
to customize a widgets appearance/functionality with.

Sample example usage::

    class MyCheckListBoxSTC(wx.stc.StyledTextCtrl, DefineNativeCheckBoxBitmapsMixin):
        '''Customized StyledTextCtrl Setup like a CheckListBox.'''
        def __init__(self, parent, id=wx.ID_ANY,
                     style=0, name='styledtextctrl'):
            wx.stc.StyledTextCtrl.__init__(self, parent, id, pos, size, style, name)

            # Define the checkbox bitmaps as attributes.
            self.DefineNativeCheckBoxBitmaps()
            # After the bitmaps have become attributes you can easily snag
            # them all later on from inside a method with this inherited method.

            # Setup a margin to hold bookmarks.
            self.SetMarginType(1, wx.stc.STC_MARGIN_SYMBOL)
            self.SetMarginSensitive(1, True)
            self.SetMarginWidth(1, 16)
            # Define the bookmark images.
            self.MarkerDefineBitmap(0, self.native_checkbox_unchecked_bmp)
            self.MarkerDefineBitmap(1, self.native_checkbox_checked_bmp)

            # ... do something with the bitmaps when you click the margin event.

Define native checkbox bitmaps as attributes. Returns True if all bitmaps was defined Ok.

bitmaps defined::

    self.native_checkbox_unchecked_bmp
    self.native_checkbox_unchecked_disabled_bmp
    self.native_checkbox_checked_bmp
    self.native_checkbox_checked_disabled_bmp
    self.native_checkbox_3state_bmp
    self.native_checkbox_3state_disabled_bmp
    self.native_checkbox_current_bmp
    self.native_checkbox_pressed_bmp

A generic class that replicates some of the functionalities of :class:`wx.Checkbox`,
while being completely owner-drawn with a nice check bitmaps.

:param `parent`: Pointer to a parent window. Must not be ``None``.
:type `parent`: `wx.Window`
:param `id`: Window identifier. ``wx.ID_ANY`` indicates a default value.
:type `id`: int
:param `label`: Text to be displayed next to the checkbox.
:type `label`: str
:param `pos`: Window position. The value ``wx.DefaultPosition`` indicates
 a default position, chosen by either the windowing system or wxWidgets, depending on platform.
:type `pos`: `wx.Point`
:param `size`: Window size. The value ``wx.DefaultSize`` indicates a default size,
 chosen by either the windowing system or wxWidgets, depending on platform.
:type `size`: `wx.Size`
:param `style`: Window style. Not used in this widget, GenCheckBox has only 2 state.
:type `style`: long
:param `validator`: Window validator.
:type `validator`: `wx.Validator`
:param `name`: Window name.
:type `name`: str

__init__(self, parent, id=wx.ID_ANY, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, validator=wx.DefaultValidator, name="GenCheckBox")

Overridden base class virtual.  Determines the best size of the control
based on the label size, the bitmap size and the current font.

Actually performs the drawing operations, for the bitmap and
for the text, positioning them centered vertically.

:param `dc`: device context to use.
:type `dc`: `wx.DC`

Enables/Disables :class:`GenCheckBox`.

:param `enable`: Set the enabled state of the checkbox.
:type `enable`: bool

Returns the appropriated bitmap depending on the checking state
(Checked/UnChecked) and the control state (Enabled/Disabled).

the same font/colour attributes as the native wx.CheckBox.

Returns the state of :class:`GenCheckBox`, True if checked, False

This is just a maybe more readable synonym for GetValue: just as the
latter, it returns True if the :class:`GenCheckBox` is checked and False

Handles the ``wx.EVT_KEY_UP`` or ``wx.EVT_KEY_UP`` event (depending on
platform) for :class:`GenCheckBox`.

:param `event`: A `wx.KeyEvent` to be processed.
:type `event`: `wx.KeyEvent`

Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`GenCheckBox`.

:param `event`: A `wx.FocusEvent` to be processed.
:type `event`: `wx.FocusEvent`

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`GenCheckBox`.

:param `event`: A `wx.MouseEvent` to be processed.
:type `event`: `wx.MouseEvent`

Handles the ``wx.EVT_PAINT`` event for :class:`GenCheckBox`.

:param `event`: A `wx.PaintEvent` to be processed.
:type `event`: `wx.PaintEvent`

Handles the ``wx.EVT_SET_FOCUS`` event for :class:`GenCheckBox`.

Handles the ``wx.EVT_SIZE`` event for :class:`GenCheckBox`.

:param `event`: A `wx.SizeEvent` to be processed.
:type `event`: `wx.SizeEvent`

:param `colour`: Set the background colour of the checkbox.
:type `colour`: `wx.Colour`

Sets the :class:`GenCheckBox` text font and updates the control's
size to exactly fit the label plus the bitmap.

:param `font`: Font to be used to render the checkboxs label.
:type `font`: `wx.Font`

:param `colour`: Set the foreground colour of the checkboxs label.

Sets the :class:`GenCheckBox` text label and updates the control's

Sets a new spacing between the check bitmap and the text.

:param `spacing`: Set the amount of space between the checkboxs bitmap and text.
:type `spacing`: int

Sets the :class:`GenCheckBox` to the given state. This does not cause a
``wx.wxEVT_COMMAND_CHECKBOX_CLICKED`` event to get emitted.

:param `state`: Set the value of the checkbox. True or False.
:type `state`: bool

#
# o Updated for wx namespace. Not tested though.
#
#
# o Removed wx prefix from class name,
#   updated reverse renamer
#

Class for a :class:`wx.html.HtmlWindow` which responds to clicks on
links by opening a browser pointed at that link, and to shift-clicks
by copying the link to the clipboard.

This module loads additional colour names/values into the :class:`wx.ColourDatabase`.

The :mod:`wx.Colourdb` will update the wxPython :class:`wx.ColourDatabase` using a pre-defined
set of colour names/colour tuples, hard-coded in this module source code.

Usage
=====

    import wx
    import wx.lib.colourdb

            # show the selected colour in this panel
            self.panel = wx.Panel(self)

            wx.lib.colourdb.updateColourDB()
            # create a colour list from the colourdb database
            colour_list = wx.lib.colourdb.getColourList()

            # create a choice widget
            self.choice = wx.Choice(self.panel, -1, choices=colour_list)
            # select item 0 (first item) in choice list to show
            self.choice.SetSelection(0)
            # set the current frame colour to the choice
            self.SetBackgroundColour(self.choice.GetStringSelection())
            # bind the checkbox events to an action
            self.choice.Bind(wx.EVT_CHOICE, self.OnChoice)

        def OnChoice(self, event):
            bgcolour = self.choice.GetStringSelection()
            # change colour of the panel to the selected colour ...
            self.panel.SetBackgroundColour(bgcolour)
            self.panel.Refresh()
            # show the selected colour in the frame title
            self.SetTitle(bgcolour.lower())

    frame = MyFrame(None, 'Select a colour')

# Name:        wx.lib.colourdb.py
# Purpose:     Adds a bunch of colour names and RGB values to the
#              colour database so they can be found by name
#
#
# Created:     13-March-2001

Returns the list of colour name/value tuples used by this module.

:rtype: list of tuples

Returns a list of just the colour names used by this module.

:rtype: list of strings

Updates the :class:`wx.ColourDatabase` by adding new colour names and RGB values.

Provides a :class:`wx.ColourSelect` button that, when clicked, will display a
colour selection dialog.

This module provides a :class:`wx.ColourSelect` button that, when clicked, will display a
colour selection dialog. The selected colour is displayed on the button itself.

Usage
=====

    import wx
    import wx.lib.colourselect as csel

            colour_button = csel.ColourSelect(self.panel, -1, "Choose...", wx.WHITE)
            colour_button.Bind(csel.EVT_COLOURSELECT, self.OnChooseBackground)

        def OnChooseBackground(self, event):

            col1 = event.GetValue()
            self.panel.SetBackgroundColour(col1)

# Name:         ColourSelect.py
# Purpose:      Colour Box Selection Control
#
# Author:       Lorne White, Lorne.White@telusplanet.net
#
# Created:      Feb 25, 2001
# Tags:         phoenix-port, unittest, documented

A subclass of :class:`wx.lib.buttons.GenBitmapButton` that,
when clicked, will display a colour selection dialog.

:param wx.Colour: a valid :class:`wx.Colour` instance, which will be the default initial
 colour for this button;
:type `colour`: :class:`wx.Colour` or tuple
:param PyObject `callback`: a callable method/function that will be called every time
 the user chooses a new colour;

__init__(self, parent, id=wx.ID_ANY, label="", colour=wx.BLACK, pos=wx.DefaultPosition, size=wx.DefaultSize, callback=None, style=0)

Returns the current colour set for the :class:`ColourSelect`.

:rtype: :class:`wx.Colour`

Returns the current set of custom colour values to be shown in the
colour dialog, if supported.

:rtype: :class:`CustomColourData`

Returns the current text label for the :class:`ColourSelect`.

:rtype: string

Same as :meth:`~ColourSelect.GetColour`.

Creates a bitmap representation of the current selected colour. 

Fires the ``EVT_COLOURSELECT`` event, as the user has changed the current colour. 

Handles the ``wx.EVT_BUTTON`` event for :class:`ColourSelect`.

:param `event`: a :class:`wx.CommandEvent` event to be processed.

Sets the bitmap representation of the current selected colour to the button.

:param wx.Bitmap `bmp`: the new bitmap.

Sets the current colour for :class:`ColourSelect`.

:param `colour`: the new colour for :class:`ColourSelect`.
:type `colour`: tuple or string or :class:`wx.Colour`

Sets the list of custom colour values to be shown in colour dialog, if
supported.

:param `colours`: An instance of :class:`CustomColourData` or a 16
element list of ``None`` or :class:`wx.Colour` values.

Sets the new text label for :class:`wx.ColourSelect`.

:param string `label`: the new text label for :class:`ColourSelect`.

Sets the current colour for :class:`ColourSelect`.  Same as
:meth:`~ColourSelect.SetColour`.

:class:`wx.ColourSelectEvent` is a special subclassing of :class:`wx.CommandEvent`
and it provides for a custom event sent every time the user chooses a colour.

:param integer `id`: the event identifier;
:param wx.Colour `value`: the colour currently selected.

Returns the currently selected colour.

A simple container for tracking custom colours to be shown in the colour
dialog, and which facilitates reuse of this collection across multiple
instances or multiple invocations of the :class:`ColourSelect` button.

# Name:        colourutils.py
# Purpose:     Some useful colour-related utility functions.
#
# Author:      Cody Precord
#
# Tags:        phoenix-port, documented

Adjust the alpha of a given colour

:param integer `alpha`: the new value for the colour alpha channel (between 0
 and 255).

:returns: A new :class:`wx.Colour` with the alpha channel specified as input

Brighten/darken input colour by `percent` and adjust alpha
channel if needed. Returns the modified color.

:param wx.Colour `color`: color object to adjust;
:param integer `percent`: percent to adjust +(brighten) or -(darken);
:param integer `alpha`: amount to adjust alpha channel.

:returns: A new darkened/lightened :class:`wx.Colour` with the alpha channel
 specified as input

Get the best color to use for the label that will be drawn on
top of the given color.

:param wx.Colour `color`: background color that text will be drawn on;
:param bool `bw`: If ``True``, only return black or white.

ComboTreeBox provides a ComboBox that pops up a tree instead of a list.

ComboTreeBox tries to provide the same interface as :class:`wx.ComboBox` as much as
possible. However, whereas the ComboBox widget uses indices to access
items in the list of choices, ComboTreeBox uses TreeItemId's instead. If
you add an item to the ComboTreeBox (using Append or Insert), the
:class:`wx.TreeItemId` associated with the added item is returned. You can then use
that `wx.TreeItemId` to add items as children of that first item. For
example::

    from wx.lib.combotreebox import ComboTreeBox
    combo = ComboTreeBox(parent)
    item1 = combo.Append('Item 1') # Add a root item
    item1a = combo.Append('Item 1a', parent=item1) # Add a child to item1

You can also add client data to each of the items like this::

    item1 = combo.Append('Item 1', clientData=somePythonObject)
    item1a = combo.Append('Item 1a', parent=item1,
                           clientData=someOtherPythonObject)

And later fetch the client data like this::

    somePythonObject = combo.GetClientData(item1)

To get the client data of the currently selected item (if any)::

    currentItem = combo.GetSelection()
    if currentItem:
        somePythonObject = combo.GetClientData(currentItem)

Supported styles are the same as for :class:`wx.ComboBox`, i.e. ``wx.CB_READONLY`` and
``wx.CB_SORT``. Provide them as usual::

    combo = ComboTreeBox(parent, style=wx.CB_READONLY|wx.CB_SORT)

Supported platforms: wxMSW and wxMAC natively, wxGTK by means of a
workaround.

Copyright 2006, 2008, 2010, Frank Niessink
Date: August 1, 2010

# Name:         combotreebox.py
# Purpose:
#
# Author:       Frank Niessink <frank@niessink.com>
#
# Created:
# Version:      1.1
# Date:         August 1, 2010
# Licence:      wxWidgets license

BaseComboTreeBox is the base class for platform specific versions of the
ComboTreeBox.

Adds the itemText to the control, associating the given clientData
with the item if not None. If parent is None, itemText is added
as a root item, else itemText is added as a child item of
parent. The return value is the :class:`TreeItemId` of the newly added
item.

:param string `itemText`: text to add to the control
:keyword TreeItemId `parent`: if None item is added as a root, else it
  is added as a child of the parent.
:keyword PyObject `clientData`: the client data to find
:return: :class:`TreeItemId` of newly added item
:rtype: :class:`TreeItemId`

Finds the *first* item in the tree with client data equal to the
given clientData. If no such item exists, an invalid item is
returned.

:param PyObject `clientData`: the client data to find
:keyword TreeItemId `parent`: :class:`TreeItemId` parent or None
:return: :class:`TreeItemId`

Finds the *first* item in the tree with a label equal to the
given string. If no such item exists, an invalid item is
returned.

:param string `string`: string to be found in label

Returns the client data associated with the given item, if any.

:param TreeItemId `item`: item for which to get clientData
:return: the client data
:rtype: PyObject

Returns the number of items in the control.

:return: items in control
:rtype: integer

Returns the :class:`TreeItemId` of the selected item or an invalid item
if no item is selected.

:return: a TreeItemId

Returns the label of the given item.

:param TreeItemId `item`: :class:`TreeItemId` for which to get the label
:return: label

Returns the label of the selected item or an empty string if no item
is selected.

:return: the label of the selected item or an empty string

Returns the current value in the combobox text field.

:return: the current value in the combobox text field

Insert an item into the control before the ``previous`` item
and/or as child of the ``parent`` item. The itemText is associated
with clientData when not None.

:param string `itemText`: the items label
:keyword TreeItemId `previous`: the previous item
:keyword TreeItemId `parent`: the parent item
:keyword PyObject `clientData`: the data to associate
:return: the create :class:`TreeItemId`

Insert(self, itemText, previous=None, parent=None, clientData=None)

Returns True if the control is empty or False if it has some items.

:return: True if control is empty
:rtype: boolean

Simulate selection of an item by the user. This is meant to
be called by the PopupFrame when the user selects an item.

This is called by the PopupFrame when the user closes the
PopupFrame, without selecting an item.

Associate the given client data with the provided item.

:param TreeItemId `item`: item for which to set the clientData
:param PyObject `clientData`: the data to set

Selects the item with the provided clientData in the control.
Returns True if the item belonging to the clientData has been
selected, False if it wasn't found in the control.

:return: True if an item has been selected, otherwise False

Sets the provided item to be the selected item.

:param TreeItemId `item`: Select this item

Sets the label for the provided item.

:param TreeItemId `item`: item on which to set the label
:param string `string`: the label to set

Selects the item with the provided string in the control.
Returns True if the provided string has been selected, False if
it wasn't found in the control.

:param string `string`: try to select the item with this string
:return: True if an item has been selected

Sets the text for the combobox text field.

NB: For a combobox with wxCB_READONLY style the string must be
in the combobox choices list, otherwise the call to SetValue()
is ignored.

:param string `value`: set the combobox text field

BasePopupFrame is the base class for platform specific versions of the
PopupFrame. The PopupFrame is the frame that is popped up by ComboTreeBox.
It contains the tree of items that the user can select one item from. Upon
selection, or when focus is lost, the frame is hidden.

The ComboTreeBox widget for wxGTK. This is actually a work
around because on wxGTK, there doesn't seem to be a way to intercept
mouse events sent to the Combobox. Intercepting those events is
necessary to prevent the Combobox from popping up the list and pop up
the tree instead. So, until wxPython makes intercepting those events
possible we build a poor man's Combobox ourselves using a TextCtrl and
a BitmapButton.

TreeCtrl is the same as :class:`TreeCtrl`, with a few convenience methods
added for easier navigation of items. 

Returns the very first item in the tree. This is the root item
unless the root item is hidden. In that case the first child of
the root item is returned, if any. If the tree is empty, an
invalid tree item is returned.

Returns the last child of the last child ... of item. If item
has no children, item itself is returned. So the returned item
is always valid, assuming a valid item has been passed.

:param TreeItemId `item`: a :class:`TreeItemId`
:return: :class:`TreeItemId` of the last item or an invalid item

Returns the item that is on the line immediately below item
(as is displayed when the tree is fully expanded). The returned
item is invalid if item is the last item in the tree.

:return: :class:`TreeItemId` of the next item or an invalid item

Returns the next sibling of item if it has one. If item has no
next sibling the next sibling of the parent of item is returned.
If the parent has no next sibling the next sibling of the parent
of the parent is returned, etc. If none of the ancestors of item
has a next sibling, an invalid item is returned.

Returns the item that is on the line immediately above item
item is invalid if item is the first item in the tree.

:return: the :class:`TreeItemId` previous to the one passed in or an invalid item

Extend GetSelection to never return the root item if the
root item is hidden.

MSWComboTreeBox adds one piece of functionality as compared to
NativeComboTreeBox: when the user browses through the tree, the
ComboTreeBox's text field is continuously updated to show the
currently selected item in the tree. If the user cancels
selecting a new item from the tree, e.g. by hitting escape, the
previous value (the one that was selected before the PopupFrame
was popped up) is restored.

Restore the value copied previously, because the user has
not selected a new value.

Extend Popup to store a copy of the current value, so we can
restore it later (in NotifyNoItemSelected). This is necessary
because MSWComboTreeBox will change the value as the user
browses through the items in the popped up tree.

Extend SetValue to also select the text in the
ComboTreeBox's text field.

:param string `value`: set the value and select it

NativeComboTreeBox, and any subclass, uses the native ComboBox as basis,
but prevent it from popping up its drop down list and instead pops up a
PopupFrame containing a tree of items.

Factory function to create the right ComboTreeBox depending on
platform. You may force a specific class, e.g. for testing
purposes, by setting the keyword argument 'platform', e.g.
'platform=GTK' or 'platform=MSW' or 'platform=MAC'.

:keyword string `platform`: 'GTK'|'MSW'|'MAC' can be used to override the
  actual platform for testing

This module supports the thread-safe, asynchronous transmission of data
('delayed results') from a worker (non-GUI) thread to the main thread. Ie you don't
need to mutex lock any data, the worker thread doesn't wait (or even check)
for the result to be received, and the main thread doesn't wait for the
worker thread to send the result. Instead, the consumer will be called
automatically by the wx app when the worker thread result is available.

In most cases you just need to use startWorker() with the correct parameters
(your worker function and your 'consumer' in the simplest of cases). The
only requirement on consumer is that it must accept a DelayedResult instance
as first arg.

In the following example, this will call consumer(delayedResult) with the
return value from workerFn::

    from wx.lib.delayedresult import startWorker
    startWorker(consumer, workerFn)

More advanced uses:

- The other parameters to startWorker()
- Derive from Producer to override _extraInfo (e.g. to provide traceback info)
- Create your own worker-function-thread wrapper instead of using Producer
- Create your own Handler-like wrapper to pre- or post-process the result
  (see PreProcessChain)
- Derive from Sender to use your own way of making result hop over the
  "thread boundary" (from non-main thread to main thread), e.g. using Queue

Thanks to Josiah Carlson for critical feedback/ideas that helped me
improve this module.

:Copyright: (c) 2006 by Oliver Schoenborn
:License: wxWidgets license
:Version: 1.0

Raise this in your worker function so that the sender knows
not to send a result to handler.

Convenience class that represents a kind of threading.Event that
raises AbortedException when called (see the __call__ method, everything
else is just to make it look like threading.Event).

Represent the actual delayed result coming from the non-main thread.
An instance of this is given to the result handler. This result is
either a (reference to a) the value sent, or an exception.
If the latter, the exception is raised when the get() method gets
called.

You should never have to call this yourself. A DelayedResult
is created by a concrete Sender for you.

__init__(self, result, jobID=None, exception = None, originalTb = None)

Get the result. If an exception was sent instead of a result,
(via Sender's sendExcept()), that **exception is raised**, and
the original traceback is available as the 'originalTraceback'
variable in the exception object.

Otherwise, the result is simply returned.

Return the jobID given when Sender initialized,
or None if none given. 

Bind some of the arguments and keyword arguments of a callable ('listener').
Then when the Handler instance is called (e.g. `handler(result, **kwargs)`)
the result is passed as first argument to callable, the kwargs is
combined with those given at construction, and the args are those
given at construction. Its return value is returned.

Represent a 'delayed result pre-processing chain', a kind of Handler.
Useful when lower-level objects need to apply a sequence of transformations
to the delayed result before handing it over to a final handler.
This allows the starter of the worker function to not know
anything about the lower-level objects.

Wrap `handler(result, *args, **kwargs)` so that the result
it receives has been transformed by us. 

Traverses the chain of pre-processors it is given, transforming
the original delayedResult along the way. The return value of each
callable added via addSub() is given to the previous addSub() callable,
until the handler is reached.

Add a sub-callable, ie a `callable(result, *args, **kwargs)`
that returns a transformed result to the previously added
sub-callable (or the handler given at construction, if this is
the first call to addSub). 

Clone the chain. Shallow only. Useful when several threads
must be started but have different sub-callables. 

Convenience method that first clones self, then calls addSub()
on that clone with given arguments. 

Represent the worker thread that produces delayed results.
It causes the given function to run in a separate thread,
and a sender to be used to send the return value of the function.
As with any threading.Thread, instantiate and call start().
Note that if the workerFn raises AbortedException, the result is not
sent and the thread terminates gracefully.

The sender will send the return value of
`workerFn(*args, **kwargs)` to the main thread. The name and group
are same as threading.Thread constructor parameters. Daemon causes
setDaemon() to be called. If sendReturn is False, then the return
value of workerFn() will not be sent. If senderArg is given, it
must be the name of the keyword arg to use to pass the sender into
the workerFn, so the function can send (typically many) results.

__init__(self, sender, workerFn, args=(), kwargs={}, name=None, group=None, daemon=False, sendReturn=True, senderArg=None)

Base class for various kinds of senders. A sender sends a result
produced by a worker function to a result handler (listener). Note
that each sender can be given a "job id". This can be anything
(number, string, id, and object, etc) and is not used, it is
simply added as attribute whenever a DelayedResult is created.
This allows you to know, if desired, what result corresponds to
which sender. Note that uniqueness is not necessary.

Derive from this class if none of the existing derived classes
are adequate, and override _sendImpl().

The optional jobID can be anything that you want to use to
track which sender particular results come from. 

Use this when the worker function raised an exception.
The *exception* is the instance of Exception caught. The extraInfo
could be anything you want (e.g. locals or traceback etc),
it will be added to the exception as attribute 'extraInfo'. The
exception will be raised when DelayedResult.get() is called.

sendException(self, exception, extraInfo = None, originalTb = None)

This will send the result to handler, using whatever
technique the derived class uses. 

This sender sends the delayed result produced in the worker thread
to a callable in the main thread, via wx.CallAfter.

Sender that works without wx. The results are sent directly, ie
the consumer will get them "in the worker thread". So it should
only be used for testing.

The consumer can be any callable of the form
`callable(result, *args, **kwargs)`

to an event handler in the main thread, via a wx event of class
*eventClass*. The result is an attribute of the event (default:
"delayedResult".

The handler must derive from wx.EvtHandler. The event class
is typically the first item in the pair returned by
wx.lib.newevent.NewEvent(). You can use the *resultAttr*
to change the attribute name of the generated event's
delayed result. 

__init__(self, handler, eventClass, resultAttr="delayedResult", jobID=None, \*\*kwargs)

An object that has attributes built from the dictionary given in
constructor. So ss=Struct(a=1, b='b') will satisfy assert ss.a == 1
and assert ss.b == 'b'.

Convenience function to send data produced by `workerFn(*wargs, **wkwargs)`
running in separate thread, to a `consumer(*cargs, **ckwargs)` running in
the main thread. This function merely creates a SenderCallAfter (or a
SenderWxEvent, if consumer derives from wx.EvtHandler), and a Producer,
and returns immediately after starting the Producer thread. The jobID
is used for the Sender and as name for the Producer thread. Returns the
thread created, in case caller needs join/etc.

startWorker( consumer, workerFn, cargs=(), ckwargs={}, wargs=(), wkwargs={}, jobID=None, group=None, daemon=False, sendReturn=True, senderArg=None)

# Name:        wx.lib.dialogs
# Purpose:     ScrolledMessageDialog, MultipleChoiceDialog and
#              function wrappers for the common dialogs by Kevin Altis.
#
# Author:      Various
#
# Created:     3-January-2002
# Copyright:   (c) 2002-2020 by Total Control Software
#
# o Updated for 2.5 compatibility.
#
# 12/18/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o wxScrolledMessageDialog -> ScrolledMessageDialog
# o wxMultipleChoiceDialog -> MultipleChoiceDialog
#

A dialog like :class:`wx.MessageDialog`, but with an optional 2nd message string
that is shown in a scrolled window, and also allows passing in the icon to
be shown instead of the stock error, question, etc. icons. The btnLabels
can be used if you'd like to change the stock labels on the buttons, it's
a dictionary mapping stock IDs to label strings.

__init__(self, parent, message, caption = "Message Box", msg2="", style = wx.OK | wx.CANCEL, pos = wx.DefaultPosition, icon=None, btnLabels=None)

Dialog()
Dialog(parent, id=ID_ANY, title=EmptyString, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)

A dialog box is a window with a title bar and sometimes a system menu,
which can be moved around the screen.

__init__(self, parent, msg, title, lst, pos = wx.DefaultPosition, size = (200,200), style = wx.DEFAULT_DIALOG_STYLE)

__init__(self, parent, msg, caption, pos=wx.DefaultPosition, size=(500,300), style=wx.DEFAULT_DIALOG_STYLE)

alertDialog(parent=None, message='', title='Alert', pos=wx.DefaultPosition)

dirDialog(parent=None, message='Choose a directory', path='', style=0, pos=wx.DefaultPosition, size=wx.DefaultSize)

fileDialog(parent=None, title='Open', directory='', filename='', wildcard='\*.\*', style=wx.FD_OPEN | wx.FD_MULTIPLE)

findDialog(parent=None, searchText='', wholeWordsOnly=0, caseSensitive=0)

messageDialog(parent=None, message='', title='Message box', aStyle = wx.OK | wx.CANCEL | wx.CENTRE, pos=wx.DefaultPosition)

A function like :class:`wx.MessageBox` which uses :class:`MultiMessageDialog`.

MultiMessageBox(message, caption, msg2="", style=wx.OK, parent=None, icon=None, btnLabels=None)

multipleChoiceDialog(parent=None, message='', title='', lst=[], pos=wx.DefaultPosition, size=wx.DefaultSize)

openFileDialog(parent=None, title='Open', directory='', filename='', wildcard='All Files (\*.\*)|\*.\*', style=wx.FD_OPEN | wx.FD_MULTIPLE)

saveFileDialog(parent=None, title='Save', directory='', filename='', wildcard='All Files (\*.\*)|\*.\*', style=wx.FD_SAVE | wx.FD_OVERWRITE_PROMPT)

scrolledMessageDialog(parent=None, message='', title='', pos=wx.DefaultPosition, size=(500,300))

singleChoiceDialog(parent=None, message='', title='', lst=[], style=wx.OK | wx.CANCEL | wx.CENTRE)

textEntryDialog(parent=None, message='', title='', defaultText='', style=wx.OK | wx.CANCEL)

# Name:         docview.py
# Purpose:      Port of the wxWindows docview classes
#
# Author:       Peter Yared
#
# Created:      5/15/03
# Copyright:    (c) 2003-2006 ActiveGrid, Inc. (Port of wxWindows classes by Julian Smart et al)
# Tags:         phoenix-port, docs

``Command`` is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing a
toolbar button or any other means provided by the application to
change the data or view.

Constructor. :class:`Command` is an abstract class, so you will need to
derive a new class and call this constructor from your own constructor.

``canUndo`` tells the command processor whether this command is undo-able.
You can achieve the same functionality by overriding the CanUndo member
function (if for example the criteria for undoability is context-
dependent).

``name`` must be supplied for the command processor to display the command
name in the application's edit menu.

Override this member function to execute the appropriate action when
called. Return ``True`` to indicate that the action has taken place, false
otherwise. Returning false will indicate to the command processor that
the action is not undoable and should not be added to the command
history.

Override this member function to un-execute a previous :meth:`Do`.
Return ``True`` to indicate that the action has taken place, ``False``
otherwise. Returning ``False`` will indicate to the command processor
that the action is not redoable and no change should be made to the
command history.

How you implement this command is totally application dependent, but
typical strategies include:

Perform an inverse operation on the last modified piece of data in the
document. When redone, a copy of data stored in command is pasted back
or some operation reapplied. This relies on the fact that you know the
ordering of Undos; the user can never Undo at an arbitrary position in
he command history.

Restore the entire document state (perhaps using document
transactioning). Potentially very inefficient, but possibly easier to
code if the user interface and data are complex, and an 'inverse
execute' operation is hard to write.

:class:`CommandProcessor` is a class that maintains a history of
:class:`Commands`, with undo/redo functionality built-in. Derive a
new class from this if you want different behaviour.

Constructor.  ``maxCommands`` may be set to a positive integer to limit
the number of commands stored to it, otherwise (and by default) the
list of commands can grow arbitrarily.

Returns ``True`` if the currently-active command can be redone,

Returns ``True`` if the currently-active command can be undone,

Deletes all the commands in the list and sets the current command
pointer to None.

Returns the maximum number of commands that the command processor
stores.

Tells the command processor to update the Undo and Redo items on this
menu as appropriate. Set this to ``None`` if the menu is about to be
destroyed and command operations may still be performed, or the
command processor may try to access an invalid pointer.

Sets the menu labels according to the currently set menu and the
current command state.

Submits a new command to the command processor. The command processor
calls :meth:`Command.Do` to execute the command; if it succeeds, the
command is stored in the history list, and the associated edit menu
(if any) updated appropriately. If it fails, the command is deleted
immediately. Once Submit has been called, the passed command should
not be deleted directly by the application.

``storeIt`` indicates whether the successful command should be stored in
the history list.

The :class:`DocChildFrame` class provides a default frame for displaying
documents on separate windows. This class can only be used for SDI (not
MDI) child frames.

The class is part of the document/view framework and cooperates with
the :class:`View`, :class:`Document`, :class:`DocManager` and
:class:`DocTemplate` classes.

__init__(self, doc, view, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame")

Processes an event, searching event tables and calling zero or more
suitable event handler function(s).

Processes a UI event, searching event tables and calling zero or more

The :class:`DocManager` class is part of the document/view framework,
and cooperates with the :class:`View`, :class:`Document` and

Constructor. Create a document manager instance dynamically near the
start of your application before doing any document or view operations.

flags is used in the Python version to indicate whether the document
manager is in DOC_SDI or DOC_MDI mode.

If initialize is true, the Initialize function will be called to
create a default history list object. If you derive from wxDocManager,
you may wish to call the base constructor with false, and then call
Initialize in your own constructor, to allow your own Initialize or
OnCreateFileHistory functions to be called.

Adds a file to the file history list, if we have a pointer to an

Closes all currently opened document by callling :meth:`CloseDocuments`
and clears the document manager's templates.

Creates a new document in a manner determined by the flags parameter,
which can be:

``wx.lib.docview.DOC_NEW`` Creates a fresh document.
``wx.lib.docview.DOC_SILENT`` Silently loads the given document file.

If ``wx.lib.docview.DOC_NEW`` is present, a new document will be
created and returned, possibly after asking the user for a template to
use if there is more than one document template. ``If
wx.lib.docview.DOC_SILENT`` is present, a new document will be created
and the given file loaded into it. If neither of these flags is
present, the user will be presented with a file selector for the file
to load, and the template to use will be determined by the extension
(Windows) or by popping up a template choice list (other platforms).

If the maximum number of documents has been reached, this function
will delete the oldest currently loaded document before creating a new
one.

wxPython version supports the document manager's
``wx.lib.docview.DOC_OPEN_ONCE`` and ``wx.lib.docview.DOC_NO_VIEW``
flag.

if ``wx.lib.docview.DOC_OPEN_ONCE`` is present, trying to open the
same file multiple times will just return the same document. if
``wx.lib.docview.DOC_NO_VIEW`` is present, opening a file will
generate the document, but not generate a corresponding view.

Creates a new view for the given document. If more than one view is
allowed for the document (by virtue of multiple templates mentioning
the same document type), a choice of view is presented to the user.

Appends the files in the history list, to all menus managed by the
file history object.

If menu is specified, appends the files in the history list to the
given menu only.

Removes the given menu from the list of menus managed by the file
history object.

Saves the file history into a config object. This must be called
explicitly by the application.

Use this menu for appending recently-visited document filenames, for
convenient access. Calling this function with a valid menu enables the
history list functionality.

Note that you can add multiple menus using this function, to be
managed by the file history object.

Returns a parent frame or dialog, either the frame with the current
focus or if there is no current focus the application's top frame.

Given a path, try to find template that matches the extension. This is
only an approximate method of finding a template for creating a
document.

Note this wxPython version looks for and returns a default template
if no specific template is found.

Returns the document associated with the currently active view (if any).

Returns the number of files currently stored in the file history.

Returns the last active view.  This is used in the SDI framework where dialogs can be mistaken for a view
and causes the framework to deactivete the current view.  This happens when something like a custom dialog box used
to operate on the current view is shown.

Returns the number of documents that can be open simultaneously.

Initializes data; currently just calls :meth:`OnCreateFileHistory`. Some data
cannot always be initialized in the constructor because the programmer
must be given the opportunity to override functionality. In fact
``Initialize`` is called from the :class:`DocManager` constructor, but this can
be vetoed by passing false to the second argument, allowing the
derived class's constructor to call ``Initialize``, possibly calling a
different :meth:`OnCreateFileHistory` from the default.

The bottom line: if you're not deriving from ``Initialize``, forget it and
construct :class:`DocManager` with no arguments.

Returns a suitable default name. This is implemented by appending an
integer counter to the string "Untitled" and incrementing the counter.

Returns a suitable title for a document frame. This is implemented by
appending the document name to the application name.

A hook to allow a derived class to create a different type of file
history. Called from :meth:`Initialize`.

Reverts the current document by calling wxDocument.Save for the current
document.

Saves the current document by calling :meth:`Document.Save` for
the current document.

Previews the current document by calling its View's
:meth:`~View.OnCreatePrintout` method.

Prints the current document by calling its View's

Issues a Redo command to the current document's command processor.

Issues an Undo command to the current document's command processor.

suitable event handler function(s).  Note that the ProcessEvent
method is called from the wxPython docview framework directly since
wxPython does not have a virtual ProcessEvent function.

Removes a file from the file history list, if we have a pointer to an

Under Windows, pops up a file selector with a list of filters
corresponding to document templates. The wxDocTemplate corresponding
to the selected file's extension is returned.

On other platforms, if there is more than one document template a
choice list is popped up, followed by a file selector.

This function is used in :meth:`DocManager.CreateDocument`.

Returns a document template by asking the user (if there is more than
one template). This function is used in :methW`DocManager.CreateDocument`.

templates - list of templates from which to choose a desired template.

sort - If more than one template is passed in in templates, then this
parameter indicates whether the list of templates that the user will
have to choose from is sorted or not when shown the choice box dialog.
Default is false.

Returns a document template by asking the user (if there is
more than one template), displaying a list of valid views.
This function is used in wxDocManager::CreateView. The dialog
normally will not appear because the array of templates only
contains those relevant to the document in question, and
often there will only be one such.

Sets the maximum number of documents that can be open at a time. By
default, this is 10,000. If you set it to 1, existing documents will
be saved and deleted when the user tries to open or create a new one
(similar to the behaviour of Windows Write, for example). Allowing
multiple documents gives behaviour more akin to MS Word and other
Multiple Document Interface applications.

The :class:`DocMDIChildFrame` class provides a default frame for displaying
documents on separate windows. This class can only be used for MDI child
frames.

The class is part of the document/view framework and cooperates with the
:class:`View`, :class:`Document`, :class:`DocManager` and :class:`DocTemplate`
classes.

Constructor.  Note that the event table must be rebuilt for the
frame since the EvtHandler is not virtual.

Sets the currently active view to be the frame's view. You may need to
override (but still call) this function in order to set the keyboard
focus for your subwindow.

Add/remove to the frame's title an indication that the document is dirty.
If the document is dirty, an '*' is appended to the title

The :class:`DocMDIParentFrame` class provides a default top-level frame for
applications using the document/view framework. This class can only be
used for MDI parent frames.

It cooperates with the :class:`View`, :class:`Document`,
:class:`DocManager` and :class:`DocTemplate` classes.

__init__(self, manager, frame, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="frame")

Deletes all views and documents. If no user input cancelled the
operation, the frame will be destroyed and the application will exit.

Opens the appropriate file when it is selected from the file history
menu.

The :class:`DocParentFrame` class provides a default top-level frame for
used for SDI (not MDI) parent frames.

It cooperates with the :class:`View`, :class:`Document`, :class:`DocManager`
and :class:`DocTemplates` classes.

DocPrintout is a default :class:`wx.Printout` that prints the first
page of a document view.

The :class:`DocTemplate` class is used to model the relationship between a
document class and a view class.

Constructor. Create instances dynamically near the start of your
application after creating a wxDocManager instance, and before doing
any document or view operations.

manager is the document manager object which manages this template.

description is a short description of what the template is for. This
string will be displayed in the file filter list of Windows file
selectors.

filter is an appropriate file filter such as \*.txt.

dir is the default directory to use for file selectors.

ext is the default file extension (such as txt).

docTypeName is a name that should be unique for a given type of
document, used for gathering a list of views relevant to a
particular document.

viewTypeName is a name that should be unique for a given view.

docClass is a Python class. If this is not supplied, you will need to
derive a new wxDocTemplate class and override the CreateDocument
member to return a new document instance on demand.

viewClass is a Python class. If this is not supplied, you will need to
derive a new wxDocTemplate class and override the CreateView member to
return a new view instance on demand.

flags is a bit list of the following:
``TEMPLATE_VISIBLE``: The template may be displayed to the user in
dialogs.

``TEMPLATE_INVISIBLE``: The template may not be displayed to the user in
dialogs.

``DEFAULT_TEMPLATE_FLAGS``: Defined as ``TEMPLATE_VISIBLE``.

__init__(self, manager, description, filter, dir, ext, docTypeName, viewTypeName, docType, viewType, flags=DEFAULT_TEMPLATE_FLAGS, icon=None)

Creates a new instance of the associated document class. If you have
not supplied a class to the template constructor, you will need to
override this function to return an appropriate document instance.

Creates a new instance of the associated document view. If you have
override this function to return an appropriate view instance.

Returns True if the path's extension matches one of this template's
file filter extensions.

Returns the default file extension for the document data, as passed to
the document template constructor.

Returns the text description of this template, as passed to the
document template constructor.

Returns the default directory, as passed to the document template

Returns the document manager instance for which this template was
created.

Returns the document type name, as passed to the document template

Returns the Python document class, as passed to the document template

Returns the file filter, as passed to the document template

Returns the flags, as passed to the document template constructor.
(see the constructor description for more details).

Returns the icon, as passed to the document template

Returns the view type name, as passed to the document template

Returns the Python view class, as passed to the document template

Returns true if the document template can be shown in "New" dialogs,
false otherwise.

Returns true if the document template can be shown in user dialogs,

Sets the document manager instance for which this template was
created. Should not be called by the application.

Sets the internal document template flags (see the constructor
description for more details).

The document class can be used to model an application's file-based data. It
is part of the document/view framework supported by wxWindows, and cooperates
with the :class:`View`, :class:`DocTemplate` and :class:`DocManager` classes.

Note this wxPython version also keeps track of the modification date of the
document and if it changes on disk outside of the application, we will warn the
user before saving to avoid clobbering the file.

Constructor.  Define your own default constructor to initialize
application-specific data.

If the view is not already in the list of views, adds the view and
calls :meth:`OnChangedViewList`.

Closes the document, by calling :meth:`OnSaveModified` and then (if this true)
:meth:`OnCloseDocument`. This does not normally delete the document object:
use :meth:`DeleteAllViews` to do this implicitly.

Calls :meth:`View.Close` and deletes each view. Deleting the final view will
implicitly delete the document itself, because the wxView destructor
calls RemoveView. This in turn calls :meth:`Document.OnChangedViewList`,
whose default implementation is to save and delete the document if no
views exist.

Deletes the contents of the document.  Override this method as
necessary.

Returns the file's modification date when it was loaded from disk.
This is used to check if the file has been modified outside of the application.

The document type name given to the wxDocTemplate constructor,
copied to this document when the document is created. If several
document templates are created that use the same document type, this
variable is used in :meth:`DocManager.CreateView` to collate a list of
alternative view types that can be used on this kind of document.

Intended to return a suitable window for using as a parent for
document-related dialog boxes. By default, uses the frame associated
with the first view.

Gets the filename associated with this document, or "" if none is
associated.

A convenience function to get the first view for a document, because
in many cases a document will only have a single view.

Copies a suitable document name into the supplied name buffer.
The default function uses the title, or if there is no title, uses the
filename; or if no filename, the string 'Untitled'.

Gets the title for this document. The document title is used for an
associated frame (if any), and is usually constructed by the framework
from the filename.

Returns true if the document can be written to its accociated file path.

Returns False if the file has been modified outside of the application.

Returns true if the document has been modified since the last save,
false otherwise. You may need to override this if your document view
maintains its own record of being modified (for example if using
wxTextWindow to view and edit the document).

Override this function and call it from your own ``LoadObject`` before
loading your own data. ``LoadObject`` is called by the framework
automatically when the document contents need to be loaded.

Note that the wxPython version simply sends you a Python file object,
so you can use pickle.

Call with true to mark the document as modified since the last save,
:class:`wx.TextWindow` to view and edit the document).
This method has been extended to notify its views that the dirty
flag has changed.

Called when a view is added to or deleted from this document. The
default implementation saves and deletes the document if no views
exist (the last one has just been removed).

The default implementation calls :meth:`DeleteContents` (an empty
implementation) sets the modified flag to false. Override this to
supply additional behaviour when the document is closed with Close.

supply additional behaviour when the document is opened with Open.

Override this function if you want a different (or no) command
processor to be created when the document is created. By default, it
returns an instance of :class:`CommandProcessor`.

The default implementation calls OnSaveModified and DeleteContents,
makes a default title for the document, and notifies the views that
the filename (in fact, the title) has changed.

Constructs an input file for the given filename (which must not
be empty), and calls :meth:`LoadObject`. If LoadObject returns true, the
document is set to unmodified; otherwise, an error message box is
displayed. The document's views are notified that the filename has
changed, to give windows an opportunity to update their titles. All of
the document's views are then updated.

Constructs an output file for the given filename (which must
not be empty), and calls :meth:`SaveObject`. If :meth:`SaveObject`
returns true, the document is set to unmodified; otherwise, an
error message box is displayed.

If the document has been modified, prompts the user to ask if the
changes should be changed. If the user replies Yes, the Save function
is called. If No, the document is marked as unmodified and the
function succeeds. If Cancel, the function fails.

Removes the view from the document's list of views, and calls
:meth:`OnChangedViewList`.

Override this function to revert the document to its last saved state.

Saves the document by calling :meth:`OnSaveDocument` if there is an
associated filename, or :meth:`SaveAs` if there is no filename.

Prompts the user for a file to save to, and then calls :meth:`OnSaveDocument`.

Override this function and call it from your own ``SaveObject`` before
saving your own data. ``SaveObject`` is called by the framework
automatically when the document contents need to be saved.

Sets the command processor to be used for this document. The document
will then be responsible for its deletion. Normally you should not
call this; override :meth:`OnCreateCommandProcessor` instead.

Saves the file's last modification date.
This is used to check if the file has been modified outside of
the application.

Sets the document type name given to the :class:`DocTemplate` constructor,
alternative view types that can be used on this kind of document. Do
not change the value of this variable.

Sets the template that created the document. Should only be called by
the framework.

Sets the filename for this document. Usually called by the framework.
If notifyViews is true, :meth:`View.OnChangeFilename` is called for all
views.

Sets the title for this document. The document title is used for an

Set to False if the document can not be saved.  This will disable the
``ID_SAVE_AS`` event and is useful for custom documents that should
not be saveable.  The ``ID_SAVE`` event can be disabled by never
modifying the document.

Updates all views. If sender is non-NULL, does not update this view.
hint represents optional information to allow a view to optimize its
update.

The view class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view
framework supported by wxWindows, and cooperates with the :class:`Document`,
:class:`DocTemplate` and :class:`DocManager` classes.

Constructor. Define your own default constructor to initialize

Call this from your view frame's ``OnActivate`` member to tell the
framework which view is currently active. If your windowing system
doesn't call ``OnActivate``, you may need to call this function from
OnMenuCommand or any place where you know the view must be active, and
the framework will need to get the current view.

The prepackaged view frame :class:`DocChildFrame` calls ``View.Activate` from
its ``OnActivate`` member and from its ``OnMenuCommand`` member.

Closes the view by calling :meth:`OnClose`. If deleteWindow is true, this
function should delete the window associated with the view.

Returns the document manager instance associated with this view.

Gets the frame associated with the view (if any). Note that this
"frame" is not a :class:`wx.Frame` at all in the generic MDI implementation
which uses the notebook pages instead of the frames and this is why
this method returns a :class:`wx.Window` and not a :class:`wx.Frame`.

Gets the name associated with the view (passed to the :class:`DocTemplate`
constructor). Not currently used by the framework.

Called when a view is activated by means of :meth:`View.Activate`. The
default implementation does nothing.

Called when the filename has changed. The default implementation
constructs a suitable title and sets the title of the view frame (if
any).

Implements closing behaviour. The default implementation calls
:meth:`Document.Close` to close the associated document. Does not delete the
view. The application may wish to do some cleaning up operations in
this function, if a call to :meth:`Document::Close` succeeded. For example,
if your application's all share the same window, you need to
disassociate the window from the view and perhaps clear the window. If
deleteWindow is true, delete the frame associated with the view.

Override this to clean up the view when the document is being closed.
The default implementation does nothing.

:class:`DocManager` or :class:`Document` creates a :class:`View` via
a :class:`DocTemplate`. Just after the :class:`DocTemplate` creates
the :class:`View`, it calls :meth:`xView.OnCreate`. In its ``OnCreate``
member function, the ``View`` can create a :class:`DocChildFrame` or
a derived class. This :class:`DocChildFrame` provides user
interface elements to view and/or edit the contents of the wxDocument.

By default, simply returns true. If the function returns false, the
view will be deleted.

Returns a :class:`wx.Printout` object for the purposes of printing. It
should create a new object every time it is called; the framework will delete
objects it creates.

By default, this function returns an instance of :class:`DocPrintout`, which
prints and previews one page by calling :meth:`View.OnDraw`.

Override to return an instance of a class other than :class:`DocPrintout`.

Override this to draw the view for the printing framework.  The

Override this to print the view for the printing framework.  The
default implementation calls :meth:`View.OnDraw`.

Called when the view should be updated. sender is a pointer to the
view that sent the update request, or None if no single view requested
the update (for instance, when the document is opened). hint is as yet
unused but may in future contain application-specific information for
making updating more efficient.

Associates the given document with the view. Normally called by the
framework.

Sets the frame associated with this view. The application should call
this if possible, to tell the view about the frame.  See :meth:`GetFrame`
for the explanation about the mismatch between the "Frame" in the method
name and the type of its parameter.

Sets the view type name. Should only be called by the framework.

# Name:        dragscroller.py
# Purpose:     Scrolls a wx.ScrollWindow by dragging
#
#
# Created:     2006/09/05

Scrolls a wx.ScrollWindow in the direction and speed of a mouse drag.

Call Start with the position of the drag start.
Call Stop on the drag release. 

# Name:        wx.lib.embeddedimage
# Purpose:     Defines a class used for embedding PNG images in Python
#              code. The primary method of using this module is via
#              the code generator in wx.tools.img2py.
#
# Author:      Anthony Tuininga
#
# Created:     26-Nov-2007
# Copyright:   (c) 2007 by Anthony Tuininga

Decode the Base64 encoded bytes-like object or ASCII string s.

Optional altchars must be a bytes-like object or ASCII string of length 2
which specifies the alternative alphabet used instead of the '+' and '/'
characters.

The result is returned as a bytes object.  A binascii.Error is raised if
s is incorrectly padded.

If validate is False (the default), characters that are neither in the
normal base-64 alphabet nor the alternative alphabet are discarded prior
to the padding check.  If validate is True, these non-alphabet characters
in the input result in a binascii.Error.

# Name:        wx.lib.eventStack
# Purpose:     These mixins implement a push and pop menu/UI update event
#              handler system at the wx.App level. This is useful for resolving
#              cases where multiple views may want to respond to an event
#              (say, wx.ID_COPY) and where you also want a "default" handler
#              for the event (and UI update status) when there is no active
#              view which wishes to handle the event.
#
# Author:      Kevin Ollivier
#
# Created:     -Mar-
# Copyright:   (c)  Kevin Ollivier

The purpose of the AppEventHandlerMixin is to provide a centralized
location to manage menu and toolbar events. In an IDE which may have
any number of file editors and services open that may want to respond
to certain menu and toolbar events (e.g. copy, paste, select all),
we need this to efficiently make sure that the right handler is handling
the event.

To work with this system, views must call::

        AddHandlerForID(ID, handlerFunc)

or::

        AddUIHandlerForID(ID, handlerFunc)

in their EVT_SET_FOCUS handler, and call Remove(UI)HandlerForID(ID) in their
EVT_KILL_FOCUS handler.

AppEventManager: ui_events = [ wx.ID_NEW, wx.ID_OPEN, wx.ID_CLOSE_ALL, wx.ID_CLOSE, wx.ID_REVERT, wx.ID_SAVE, wx.ID_SAVEAS, wx.ID_UNDO, wx.ID_REDO, wx.ID_PRINT, wx.ID_PRINT_SETUP, wx.ID_PREVIEW, wx.ID_EXIT ]

A widget and supporting classes for watching the events sent to some other widget.

# Name:        wx.lib.eventwatcher
# Purpose:     A widget that allows some or all events for a particular widget
#              to be captured and displayed.
#
#
# Created:     21-Jan-2009
#

Panel with CheckListBox for selecting which events will be watched.

A virtual listctrl that displays information about the watched events.

OnGetItemAttr(item) -> ItemAttr

This function may be overridden in the derived class for a control
with wxLC_VIRTUAL style.

OnGetItemImage(item) -> int

This function must be overridden in the derived class for a control
with wxLC_VIRTUAL style using images.

OnGetItemText(item, column) -> String

A frame that will catch and display all events sent to some widget.

Adds all the items in module that start with ``EVT_`` to the event
data structures used by the EventWatcher.

Add the event binders from the main wx namespace.  This is called
automatically from the EventWatcher.

[<wx.core.PyEventBinder object at 0x7fe27a678c50>, <wx.core.PyEventBinder object at 0x7fe27a678c90>, <wx.core.PyEventBinder object at 0x7fe27a678cd0>, <wx.core.PyEventBinder object at 0x7fe27a67ea10>, <wx.core.PyEventBinder object at 0x7fe27a67ea50>, <wx.core.PyEventBinder object at 0x7fe27a67ea90>]

A module that allows multiple handlers to respond to single wxWidgets
events.  This allows true NxN Observer/Observable connections: One
event can be received by multiple handlers, and one handler can
receive multiple events.

There are two ways to register event handlers.  The first way is
similar to standard wxPython handler registration::

    from wx.lib.evtmgr import eventManager
    eventManager.Register(handleEvents, EVT_BUTTON, win=frame, id=101)

There's also a new object-oriented way to register for events.  This
invocation is equivalent to the one above, but does not require the
programmer to declare or track control ids or parent containers::

    eventManager.Register(handleEvents, EVT_BUTTON, myButton)

# Name:        wx.lib.evtmgr
# Purpose:     An easier, more "Pythonic" and more OO method of registering
#              handlers for wxWindows events using the Publish/Subscribe
#              pattern.
#
# Author:      Robb Shecter and Robin Dunn
#
# Created:     12-December-2002
# Copyright:   (c) 2003 by db-X Corporation
# 12/02/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
#

A class that adapts incoming wxWindows events to
Publish/Subscribe messages.

In other words, this is the object that's seen by the
wxWindows system.  Only one of these registers for any
particular wxWindows event.  It then relays it into the
PS system, which lets many listeners respond.

Instantiate a new adapter. Pre-compute my Publish/Subscribe
topic, which is constant, and register with wxWindows.

Return the list of event types that the given
macro corresponds to.

Return True if the given macro actually causes
multiple events to be registered.

Return True if the macro is in the macroList.
The added value of this method is that it takes
multi-events into account.  The macroList parameter
will be coerced into a sequence if needed.

This is the main class in the module, and is the only class that
the application programmer needs to use.  There is a pre-created
instance of this class called 'eventManager'.  It should not be
necessary to create other instances.

Deregister any entries relating to dead
wxPython objects.  Not sure if this is an
important issue; 1) My app code always de-registers
listeners it doesn't need.  2) I don't think
that lingering references to these dead objects
is a problem.

Registers a listener function (or any callable object) to
receive events of type event coming from the source window.

    eventManager.Register(self.OnButton, EVT_BUTTON, theButton)

Alternatively, the specific window where the event is
delivered, and/or the ID of the event source can be specified.

    eventManager.Register(self.OnButton, EVT_BUTTON, win=self, id=ID_BUTTON)

or::

    eventManager.Register(self.OnButton, EVT_BUTTON, theButton, self)

Used internally by the EventMacroInfo class.  The FakeWindow is
the most important component of the macro-info utility: it
implements the Connect() protocol of wxWindow, but instead of
registering for events, it keeps track of what parameters were
passed to it.

A class that adapts incoming Publish/Subscribe messages
to wxWindows event calls.

This class works opposite the EventAdapter, and
retrieves the information an EventAdapter has sent in a message.
Strictly speaking, this class is not required: Event listeners
could pull the original wxEvent object out of the PS Message
themselves.

However, by pairing an instance of this class with each wxEvent
handler, the handlers can use the standard API: they receive an
event as a parameter.

Instantiate a new MessageAdapter that send wxEvents to the
given eventHandler.

This module contains the :class:`~lib.expando.ExpandoTextCtrl`, which is a multi-line
text control that will expand its height on the fly to be able to show
all the lines of the content of the control.

The :class:`ExpandoTextCtrl` is a multi-line :class:`TextCtrl` that will

Usage
=====

    import wx
    from wx.lib.expando import ExpandoTextCtrl, EVT_ETC_LAYOUT_NEEDED

            wx.Frame.__init__(self, None, title="Test ExpandoTextCtrl")
            self.pnl = p = wx.Panel(self)
            self.eom = ExpandoTextCtrl(p, size=(250,-1),
                                       value="This control will expand as you type")
            self.Bind(EVT_ETC_LAYOUT_NEEDED, self.OnRefit, self.eom)

            # create some buttons and sizers to use in testing some
            # features and also the layout
            vBtnSizer = wx.BoxSizer(wx.VERTICAL)

            btn = wx.Button(p, -1, "Write Text")
            self.Bind(wx.EVT_BUTTON, self.OnWriteText, btn)
            vBtnSizer.Add(btn, 0, wx.ALL|wx.EXPAND, 5)

            btn = wx.Button(p, -1, "Append Text")
            self.Bind(wx.EVT_BUTTON, self.OnAppendText, btn)

            col1 = wx.BoxSizer(wx.VERTICAL)
            col1.Add(self.eom, 0, wx.ALL, 10)
            sizer.Add(col1)
            sizer.Add(vBtnSizer)
            p.SetSizer(sizer)

            # Put the panel in a sizer for the frame so we can use self.Fit()
            frameSizer = wx.BoxSizer()
            frameSizer.Add(p, 1, wx.EXPAND)
            self.SetSizer(frameSizer)

            self.Fit()

        def OnRefit(self, evt):
            # The Expando control will redo the layout of the
            # sizer it belongs to, but sometimes this may not be
            # enough, so it will send us this event so we can do any
            # other layout adjustments needed.  In this case we'll
            # just resize the frame to fit the new needs of the sizer.

        def OnWriteText(self, evt):
            self.eom.WriteText("This is a test...  Only a test.  If this had "
                               "been a real emergency you would have seen the "
                               "quick brown fox jump over the lazy dog.")

        def OnAppendText(self, evt):
            self.eom.AppendText("Appended text.")

# Name:        expando.py
# Purpose:     A multi-line text control that expands and collapses as more
#              or less lines are needed to display its content.
#
#
# Created:     18-Sept-2006
#

FancyText -- methods for rendering XML specified text

This module exports four main methods::

    def GetExtent(str, dc=None, enclose=True)
    def GetFullExtent(str, dc=None, enclose=True)
    def RenderToBitmap(str, background=None, enclose=True)
    def RenderToDC(str, dc, x, y, enclose=True)

In all cases, 'str' is an XML string. Note that start and end tags are
only required if *enclose* is set to False. In this case the text
should be wrapped in FancyText tags.

In addition, the module exports one class::

    class StaticFancyText(self, window, id, text, background, ...)

This class works similar to StaticText except it interprets its text
as FancyText.

The text can support superscripts and subscripts, text in different
sizes, colors, styles, weights and families. It also supports a
limited set of symbols, currently *times*, *infinity*, *angle* as well
as greek letters in both upper case (*Alpha* *Beta*... *Omega*) and
lower case (*alpha* *beta*... *omega*).

>>> frame = wx.Frame(wx.NULL, -1, "FancyText demo", wx.DefaultPosition)
>>> sft = StaticFancyText(frame, -1, testText, wx.Brush("light grey", wx.BRUSHSTYLE_SOLID))
>>> frame.SetClientSize(sft.GetSize())
>>> didit = frame.Show()
>>> from guitest import PauseTests; PauseTests()

# Name:         fancytext.py
# Purpose:      Methods for rendering XML specified text
#
# Author:
#
# Created:
# Version:
# Date:
# Licence:
#
#

Class for rendering XML marked up text.

See the module docstring for a description of the markup.

This class must be subclassed and the methods the methods that do
the drawing overridden for a particular output device.

StaticBitmap()
StaticBitmap(parent, id=ID_ANY, bitmap=NullBitmap, pos=DefaultPosition, size=DefaultSize, style=0, name=StaticBitmapNameStr)

A static bitmap control displays a bitmap.

{'fixed': 76, 'default': 70, 'decorative': 71, 'roman': 72, 'script': 73, 'swiss': 74, 'modern': 75, 'teletype': 76, 'unknown': 77}

('alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta', 'eta', 'theta', 'iota', 'kappa', 'lambda', 'mu', 'nu', 'xi', 'omnikron', 'pi', 'rho', 'altsigma', 'sigma', 'tau', 'upsilon', 'phi', 'chi', 'psi', 'omega')

{'normal': 400, 'light': 300, 'bold': 700, 'invalid': 0, 'thin': 100, 'extra-light': 200, 'medium': 500, 'semi-bold': 600, 'extra-bold': 800, 'heavy': 900, 'extra-heavy': 1000}

# Name:        wx.lib.filebrowsebutton
# Purpose:     Composite controls that provide a Browse button next to
#              either a wxTextCtrl or a wxComboBox.  The Browse button
#              launches a wxFileDialog and loads the result into the
#              other control.
#
# Author:      Mike Fletcher
#
#
# o 2.5 Compatibility changes
#

A control to allow the user to type in a filename or browse with
the standard file dialog to select file

:param labelText:      Text for label to left of text field
:param buttonText:     Text for button which launches the file dialog
:param toolTip:        Help text
:param dialogTitle:    Title used in file dialog
:param startDirectory: Default directory for file dialog startup
:param fileMask:       File mask (glob pattern, such as *.*) to use in file dialog
:param fileMode:       wx.FD_OPEN or wx.FD_SAVE, indicates type of file dialog to use
:param changeCallback: Optional callback called for all changes in value of the control
:param labelWidth:     Width of the label

__init__(self, parent, id = -1, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TAB_TRAVERSAL, labelText = 'Select a directory:', buttonText = 'Browse', toolTip = 'Type directory name or browse to select', dialogTitle = '', startDirectory = '.', changeCallback = None, dialogClass = wx.DirDialog, newDirectory = False, name = 'dirBrowseButton')

__init__ (self, parent, id= -1, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TAB_TRAVERSAL, labelText= "File Entry:", buttonText= "Browse", toolTip= "Type filename or click browse to choose file",  dialogTitle = "Choose a file", startDirectory = ".", initialValue = "", fileMask = "\*.\*", fileMode = wx.FD_OPEN,  changeCallback= lambda x:x, labelWidth = 0, name = 'fileBrowseButton', )

SetBackgroundColour(colour) -> bool

Sets the background colour of the window.

with following additions:
    __init__(..., history=None)

        history -- optional list of paths for initial history drop-down
            (must be passed by name, not a positional argument)
            If history is callable it will must return a list used
            for the history drop-down

        changeCallback -- as for FileBrowseButton, but with a work-around
            for win32 systems which don't appear to create wx.EVT_COMBOBOX
            events properly.  There is a (slight) chance that this work-around
            will cause some systems to create two events for each Combobox
            selection. If you discover this condition, please report it!

        As for a FileBrowseButton.__init__ otherwise.

    GetHistoryControl()
        Return reference to the control which implements interfaces
        required for manipulating the history list.  See GetHistoryControl
        documentation for description of what that interface is.

    GetHistory()
        Return current history list

    SetHistory( value=(), selectionIndex = None )
        Set current history list, if selectionIndex is not None, select that index

Return a pointer to the control which provides (at least)
the following methods for manipulating the history list:

    Append( item ) -- add item
    Clear() -- clear all items
    Delete( index ) -- 0-based index to delete from list
    SetSelection( index ) -- 0-based index to select in list

Semantics of the methods follow those for the wxComboBox control

SetHistory( self, value=(), selectionIndex = None, control=None )

# 12/07/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
#

BitmapButton()
BitmapButton(parent, id=ID_ANY, bitmap=NullBitmap, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ButtonNameStr)

A bitmap button is a control that contains a bitmap.

__init__(self,parent,id,bitmap,pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.BU_AUTODRAW, validator = wx.DefaultValidator, name = "button")

PopupWindow()
PopupWindow(parent, flags=BORDER_NONE)

A special kind of top level window used for popup menus, combobox
popups and such.

This is a class to add Mouse Gestures to a program.
It can be used in two ways:

1.  Automatic:
    Automatically runs mouse gestures.
    You need to set the gestures, and their associated actions,
    as well as the Mouse Button/Modifiers to use.

2.  Manual:
    Same as above, but you do not need to set the mouse button/modifiers.
    You can launch this from events as you wish.

An example is provided in the demo.
The parent window is where the mouse events will be recorded.
(So if you want to record them in a pop up window, use manual mode,
and set the pop up as the parent).

Start() starts recording mouse movement.
End() stops the recording, compiles all the gestures into a list,
and looks through the registered gestures to find a match.
The first match associated action is then run.

The marginoferror is how much to forgive when calculating movement:
If the margin is 25, then movement less than 25 pixels will not be detected.

Recognized:  L, R, U, D, 1, 3, 7, 9

Styles:  Manual (Automatic By Default), DisplayNumbersForDiagonals (Off By Default).
Not Yet Implemented

The criteria for a direction is as follows:
x in a row.  (Where x is the WobbleTolerance).
So if the WobbleTolerance is 9
'URUUUUUUUUUUUUUUURUURUUUU1' is Up.

The higher this number, the less sensitive this class is.
So the more likely something like 1L will translate to 1.

This is good, since the mouse does tend to wobble somewhat,
and a higher number allows for this.

To change this, use SetWobbleTolerance

Also, to help with recognition of a diagonal versus
a vey messy straight line, if the greater absolute value
is not greater than twice the lesser, only the grater value
is counted.

In automatic mode, EVT_MOUSE_EVENTS is used.
This allows the user to change the mouse button/modifiers at runtime.

__init__(self, parent, Auto=True, MouseButton=wx.MOUSE_BTN_MIDDLE)

Registers a gesture, and an associated function, with any arguments needed.

If the gesture is in the array of registered gestures, run the associated function.

Stops recording the points to create the mouse gesture from,
and creates the mouse gesture, returns the result as a string.

Warning:  Once auto is set, it stays set, unless you manually use UnBind

Sets the colour and width of the line drawn to visually represent each gesture

Takes an array of wx Key constants (Control, Shift, and/or Alt).
Leave empty to unset all modifiers.

# Name:         GridColMover.py
# Purpose:      Grid Column Mover Extension
#
# Author:       Gerrit van Dyk (email: gerritvd@decillion.net)
#
# Version       0.1
# Date:         Nov 19, 2002
#
#
#
# o wxGridColMoveEvent -> GridColMoveEvent
# o wxGridRowMoveEvent -> GridRowMoveEvent
# o wxGridColMover -> GridColMover
# o wxGridRowMover -> GridRowMover
#

Window()
Window(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, name=PanelNameStr)

wxWindow is the base class for all windows and represents any visible
object on screen.

PyCommandEvent(eventType=wxEVT_NULL, id=0)

:class:`PyCommandEvent` can be used as a base class for implementing
custom event types in Python. You should derive from this class
instead of :class:`CommandEvent` because this class is Python-aware
and is able to transport its Python bits safely through the
wxWidgets event system and have them still be there when the
event handler is invoked. Note that since :class:`PyCommandEvent` is
taking care of preserving the extra attributes that have been set
then you do not need to override the Clone method in your
derived classes.

:see: :class:`PyEvent`

This module provides the :class:`~lib.imagebrowser.ImageDialog` which allows to view and select
an image.

The :class:`wx.ImageDialog` allows the user to view images and select one.

Usage
=====

A simple usage would be::

    import wx
    import wx.lib.imagebrowser as ib

    with ib.ImageDialog(None) as dlg:
            # show the selected file
            print("You Selected File: " + dlg.GetFile())
        else:
            print("You pressed Cancel")

# Name:         BrowseImage.py
# Purpose:      Display and Select Image Files
#
# Original Author:       Lorne White
#
# Version:      2.0
# Date:         June 16, 2007
# 2.0 Release - Bill Baxter (wbaxter@gmail.com)
# o Changed to use sizers instead of fixed placement.
# o Made dialog resizeable
# o Added a splitter between file list and view pane
# o Made directory path editable
# o Added an "up" button" to go to the parent dir
# o Changed to show directories in file list
# o Don't select images on double click any more
# o Added a 'broken image' display for files that wx fails to identify
# o Redesigned appearance -- using bitmap buttons now, and rearranged things
# o Fixed display of masked gifs
# o Fixed zooming logic to show shrunken images at correct aspect ratio
# o Added different background modes for preview (white/grey/dark/checkered)
# o Added framing modes for preview (no frame/box frame/tinted border)
#
#
# 12/08/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Corrected a nasty bug or two - see comments below.
# o There was a duplicate ImageView.DrawImage() method. Que?
#
# 1.0 Release - Lorne White
# Date:         January 29, 2002
# Create list of all available image file types
# View "All Image" File Types as default filter
# Sort the file list
# Use newer "re" function for patterns
#
# Tags:        phoenix-port, documented, unittest

:class:`wx.ImageDialog` derived from :class:`Dialog` allows the user
to display images and to select an image.

:param string `set_dir`: path to set as working directory

Change list of file types to be supported

:param tuple `ft_tuple`: tuple of files types, e.g. to support just
   .gif and .png you would use:

   (("GIF (*.gif)", "*.gif"),
    ("PNG (*.png)", "*.png"))

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER )

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.BORDER_SUNKEN )

Convert file

:param string `file_nm`: path to file

:return: :class:`wx.Image` or BAD_IMAGE

Creates a square RGB checkered bitmap using the two specified colors.

The bitmap returned will have width = height = blocksize*ntiles*2

:param int `blocksize`:  the number of pixels in each solid color square
:param int `ntiles1`:  the number of tiles along width and height.  Each
    tile is 2x2 blocks.
:param `rbg0`: the first color, as 3-character bytes object.
:param `rgb1`: the second color, as 3-character bytes object. If only 1
    character is provided, it is treated as a grey value.

:return: :class:`wx.Bitmap`

GetCheckeredBitmap(blocksize=8, ntiles=4, rgb0=b'\xFF', rgb1=b'\xCC')

{'White': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe267d2b210>, 'Grey': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56550>, 'Black': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56c90>, 'Checked': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56c50>, 'NoFrame': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56a10>, 'BoxFrame': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56910>, 'CropFrame': <wx.lib.embeddedimage.PyEmbeddedImage object at 0x7fe25ae56090>}

This module contains a collection of functions for simple image manipulations.

The 2 functions defined here (:func:`grayOut`, :func:`makeGray` and :func:`stepColour`)
can be used to convert a given image into a grey-scale representation and to
darken/lighten a specific wxPython :class:`wx.Colour`.

Usage
=====

    import wx
    from wx.lib.imageutils import grayOut, stepColour

    bmp = wx.ArtProvider.GetBitmap(wx.ART_INFORMATION, wx.ART_OTHER, (32, 32))
    disabled_bmp = wx.Bitmap(grayOut(bmp.ConvertToImage()))

    colour = wx.Colour(100, 120, 130)

    # Darker
    dark_colour = stepColour(colour, 50)

    # Lighter
    light_colour = stepColour(colour, 120)

# Name:        wx.lib.imageutils
# Purpose:     A collection of functions for simple image manipulations
#
# Author:      Robb Shecter
#
# Created:     7-Nov-2002
# Copyright:   (c) 2002 by

Convert the given image (in place) to a grayed-out
version, appropriate for a 'disabled' appearance.

:param wx.Image `anImage`: the image we want to convert to gray-scale.

:rtype: :class:`wx.Image`
:returns: The modified (greyed out) image.

.. note:: the image is converted in place, i.e. the input image will
   be modified to a greyed out version.

Make a pixel grayed-out. If the pixel matches the maskColor, it won't be
changed.

:param tuple `rgb`: a tuple of red, green, blue integers, defining the pixel :class:`wx.Colour`;
:param float `factor`: the amount for which we want to grey out a pixel colour;
:param `maskColor`: the mask colour.

:type `maskColor`: tuple or :class:`wx.Colour`.

:rtype: tuple
:returns: An RGB tuple with the greyed out pixel colour.

An utility function that simply darkens or lightens a
color, based on the specified step value.  A step of 0 is
completely black and a step of 200 is totally white, and 100
results in the same color as was passed in.

:param wx.Colour `c`: the input colour to be modified (darkened or lightened);
:param integer `step`: the step value.

:returns: A new colour, darkened or lightened depending on the input `step` value.

infoframe.py
Released under wxWindows license etc.

This is a fairly rudimentary, but slightly fancier than
wxPyOnDemandOutputWindow (on which it's based; thanks Robin), version
of the same sort of thing: a file-like class called
wxInformationalMessagesFrame. This window also has a status bar with a
couple of buttons for controlling the echoing of all output to a file
with a randomly-chosen filename...

The class behaves similarly to wxPyOnDemandOutputWindow in that (at
least by default) the frame does not appear until written to, but is
somewhat different in that, either under programmatic (the
DisableOutput method) or user (the frame's close button, it's status
bar's "Dismiss" button, or a "Disable output" item of some menu,
perhaps of some other frame), the frame will be destroyed, an
associated file closed, and writing to it will then do nothing.  This
can be reversed: either under programmatic (the EnableOutput method)
or user (an "Enable output" item of some menu), a new frame will be
opened,And an associated file (with a "randomly"selected filename)
opened for writing [to which all subsequent displayed messages will be
echoed].

Please note that, like wxPyOnDemandOutputWindow, the instance is not
itself a subclass of wxWindow: when the window is open (and ONLY
then), it's "frame" attribute is the actual instance of wFrame...

    from wx.lib.infoframe import *
    ... # ... modify your wxApp as follows:
    class myApp(wxApp):
        outputWindowClass = PyInformationalMessagesFrame
        # ...

If you're running on Linux, you'll also have to supply an argument 1 to your
constructor of myApp to redirect stdout/stderr to this window (it's done
automatically for you on Windows).

If you don't want to redirect stdout/stderr, but use the class directly: do
it this way::

    InformationalMessagesFrame = PyInformationalMessagesFrame(                                                 options_from_progname,  # (default = "")
                                                txt),                   # (default = "informational messages")

    #^^^^ early in the program
    # ...

    InformationalMessagesFrame(list_of_items)

    # where list_of_items:
    #
    # comma-separated list of items to display.
    # Note that these will never be separated by spaces as they may
    # be when used in the Python 'print' command

The latter statement, of course, may be repeated arbitrarily often.
The window will not appear until it is written to, and it may be
manually closed by the user, after which it will reappear again until
written to... Also note that all output is echoed to a file with a
randomly-generated name [see the mktemp module in the standard
library], in the directory given as the 'dir' keyword argument to the
InformationalMessagesFrame constructor [which has a default value of
'.'), or set via the method SetOutputDirectory... This file will be
closed with the window--a new one will be created [by default] upon
each subsequent reopening.

Please also note the methods EnableOutput and DisableOutput, and the
possible arguments for the constructor in the code below... (* TO DO:
explain this here...*) Neither of these methods need be used at all,
and in this case the frame will only be displayed once it has been
written to, like wxPyOnDemandOutputWindow.

The former, EnableOutput, displays the frame with an introductory
message, opens a random file to which future displayed output also
goes (unless the nofile attribute is present), and sets the __debug__
variable of each module to 1 (unless the no __debug__ attribute is
present].  This is so that you can say, in any module whatsoever::

    if __debug__:
        InformationalMessagesFrame("... with lots of %<Character> constructs"
                                    % TUPLE)

without worrying about the overhead of evaluating the arguments, and
calling the wxInformationalMessagesFrame instance, in the case where
debugging is not turned on.  (This won't happen if the instance has an
attribute no__debug__; you can arrange this by sub-classing...)

"Debug mode" can also be turned on by selecting the item-"Enable
output" from the "Debug" menu [the default--see the optional arguments
to the SetOtherMenuBar method] of a frame which has been either passed
appropriately to the constructor of the wxInformationalMessagesFrame
(see the code), or set via the SetOtherMenuBar method thereof.  This
also writes an empty string to the instance, meaning that the frame
will open (unless DisablOutput has been called) with an appropriate
introductory message (which will vary according to whether the
instance/class has the "no __debug__" attribute)^  I have found this to
be an extremely useful tool, in lieu of a full wxPython debugger...

Following this, the menu item is also disabled, and an item "Disable
output" (again, by default) is enabled.  Note that these need not be
done: e.g., you don't NEED to have a menu with appropriate items; in
this case simply do not call the SetOtherMenuBar method or use the
othermenubar keyword argument of the class instance constructor.

The DisableOutput method does the reverse of this; it closes the
window (and associated file), and sets the __debug__ variable of each
module whose name begins with a capital letter {this happens to be the
author's personal practice; all my python module start with capital
letters} to 0.  It also enables/disabled the appropriate menu items,
if this was done previously (or SetOtherMenuBar has been called...).
Note too that after a call to DisableOutput, nothing further will be
done upon subsequent write()'s, until the EnableOutput method is
called, either explicitly or by the menu selection above...

Finally, note that the file-like method close() destroys the window
(and closes any associated file) and there is a file-like method
write() which displays it's argument.

All (well, most) of this is made clear by the example code at the end
of this file, which is run if the file is run by itself; otherwise,
see the appropriate "stub" file in the wxPython demo.

#
# o wxPyInformationalMessagesFrame -> PyInformationalMessagesFrame
# o dummy_wxPyInformationalMessagesFrame -> dummy_PyInformationalMessagesFrame
#

StatusBar()
StatusBar(parent, id=ID_ANY, style=STB_DEFAULT_STYLE, name=StatusBarNameStr)

A status bar is a narrow window that can be placed along the bottom of
a frame to give small amounts of status information.

__init__(self, progname="", text="informational messages", dir='.', menuname="Debug", enableitem="Enable output", disableitem="Disable output", othermenubar=None)

EnableOutput(self, event=None, othermenubar=None, menuname="Debug", enableitem="Enable output", disableitem="Disable output")

SetOtherMenuBar(self, othermenu, menuname="Debug", enableitem="Enable output", disableitem="Disable output")

This modules provides the :class:`~wx.lib.inspection.InspectionTool` and
everything else needed to provide the Widget Inspection Tool (WIT).

# Name:        wx.lib.inspection
# Purpose:     A widget inspection tool that allows easy introspection of
#              all the live widgets and sizers in an application.
#
#
# Created:     26-Jan-2007
# Copyright:   (c) 2007-2020 by Total Control Software
#
# Tags:        py3-port, phoenix-port, documented

All the highlighting code.  A separate class to help reduce the
clutter in InspectionFrame.

Use a timer to alternate a TLW between shown and hidden state a
few times.  Use to highlight a TLW since drawing and clearing an
outline is trickier.

Draw a highlight rectangle around the item represented by the
current tree selection.

This class is the frame that holds the wxPython inspection tools.
The toolbar and AUI splitters/floating panes are also managed
here.  The contents of the tool windows are handled by other
classes.

__init__(self, wnd=None, locals=None, config=None, app=None, title="wxPython Widget Inspection Tool", \*args, \*\*kw)

Used to display information about the currently selected items.
Currently just a read-only :class:`stc.StyledTextCtrl` with some plain
text.  Should probably add some styles to make things easier to
read.

All of the widgets in the app, and optionally their sizers, are
loaded into this tree.

BuildTree(self, startWidget, includeSizers=False, expandFrame=False)

TreeCtrl()
TreeCtrl(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=TR_DEFAULT_STYLE, validator=DefaultValidator, name=TreeCtrlNameStr)

A tree control presents information as a hierarchy, with items that
may be expanded to show further items.

GetItemData(item) -> TreeItemData

Returns the tree item data associated with the item.

GetBoundingRect(item, textOnly=False) -> PyObject

Returns the rectangle bounding the item. If textOnly is true,
only the rectangle around the item's label will be returned, otherwise
the item's image is also taken into account. The return value may be
None
if the rectangle was not successfully retrieved, such as if the item
is
currently not visible.

GetCount() -> unsignedint

GetEditControl() -> TextCtrl

Returns the edit control being currently used to edit a label.

GetFirstVisibleItem() -> TreeItemId

GetFocusedItem() -> TreeItemId

Returns the item last clicked or otherwise selected.

GetIndent() -> unsignedint

Returns the current tree control indentation.

GetQuickBestSize() -> bool

Returns true if the control will use a quick calculation for the best
size, looking only at the first and last items.

GetRootItem() -> TreeItemId

Returns the root item for the tree control.

GetSelection() -> TreeItemId

Returns the selection, or an invalid item if there is no selection.

GetSelections() -> PyObject

Returns a list of currently selected items in the tree.  This function
can be called only if the control has the wx.TR_MULTIPLE style.

GetSpacing() -> unsignedint

Returns the current tree control spacing.

GetStateImageList() -> ImageList

Returns the state image list (from which application-defined state
images are taken).

{0: 'wx.FLEX_GROWMODE_NONE', 1: 'wx.FLEX_GROWMODE_SPECIFIED', 2: 'wx.FLEX_GROWMODE_ALL'}

{64: 'wx.TOP', 128: 'wx.BOTTOM', 16: 'wx.LEFT', 32: 'wx.RIGHT', 8192: 'wx.EXPAND', 16384: 'wx.SHAPED', 0: 'wx.ADJUST_MINSIZE', 512: 'wx.ALIGN_RIGHT', 1024: 'wx.ALIGN_BOTTOM', 2048: 'wx.ALIGN_CENTER_VERTICAL', 256: 'wx.ALIGN_CENTER_HORIZONTAL', 32768: 'wx.FIXED_MINSIZE'}

# Name:         wx.lib.intctrl.py
# Created:      01/16/2003
# NOTE:
#   This was written to provide a standard integer edit control for wxPython.
#
#   IntCtrl permits integer (long) values to be retrieved or  set via
#   .GetValue() and .SetValue(), and provides an EVT_INT() event function
#   for trapping changes to the control.
#
#   It supports negative integers as well as the naturals, and does not
#   permit leading zeros or an empty control; attempting to delete the
#   contents of the control will result in a (selected) value of zero,
#   thus preserving a legitimate integer value, or an empty control
#   (if a value of None is allowed for the control.) Similarly, replacing the
#   contents of the control with '-' will result in a selected (absolute)
#   value of -1.
#
#   IntCtrl also supports range limits, with the option of either
#
#
#
# o wxIntUpdateEvent -> IntUpdateEvent
# o wxIntValidator -> IntValidator
# o wxIntCtrl -> IntCtrl
#

This class provides a control that takes and returns integers as
value, and provides bounds support and optional value limiting.

Default constructor

:param int `id`: window identifier. A value of -1 indicates a
  default value

:param `value`: If no initial value is set, the default will be zero,
  or the minimum value, if specified.  If an illegal string is
  specified, a ValueError will result. (You can always later set the
  initial value with ChangeValue() after instantiation of the control.)

:param tuple `pos`: the control position. A value of (-1, -1) indicates
  a default position, chosen by either the windowing system or
  wxPython, depending on platform

:param wx.Size `size`: the control size. A value of (-1, -1) indicates a
  default size, chosen by either the windowing system or wxPython,
  depending on platform

:param int `style`: the underlying :class:`TextCtrl` style

:param wx.Validator `validator`: Normally None, IntCtrl uses its own
  validator to do value validation and input control.  However, a
  validator derived from :class:`~lib.intctrl.IntValidator` can be
  supplied to override the data transfer methods for the
  :class:`~lib.intctrl.IntValidator` class.

:param int `min`: The minimum value that the control should allow.  This
  can be adjusted with SetMin().  If the control is not limited, any
  value below this bound will be colored with the current out-of-bounds
  color. If min < -sys.maxsize-1 and the control is configured to not
  allow long values, the minimum bound will still be set to the long
  value, but the implicit bound will be -sys.maxsize-1.

:param int `max`: The maximum value that the control should allow.  This
  can be adjusted with SetMax().  If the control is not limited, any
  value above this bound will be colored with the current out-of-bounds
  color.  if max > sys.maxsize and the control is configured to not
  allow long values, the maximum bound will still be set to the long
  value, but the implicit bound will be sys.maxsize.

:param bool `limited`: Boolean indicating whether the control
  prevents values from exceeding the currently set minimum and maximum
  values (bounds).  If False and bounds are set, out-of-bounds values
  will be colored with the current out-of-bounds color.

:param bool `allow_none`: Boolean indicating whether or not the
  control is allowed to be empty, representing a value of None for the
  control.

:param bool `allow_long`:  Boolean indicating whether or not the
  control is allowed to hold and return a long as well as an int.

:param Color `default_color`:  Color value used for in-bounds values
  of the control.

:param Color `oob_color`:  Color value used for out-of-bounds values
  of the control when the bounds are set but the control is not limited.

__init__ ( self, parent, id=-1, value = 0, pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, validator = wx.DefaultValidator, name = "integer", min=None, max=None, limited = 0, allow_none = 0, allow_long = 0, default_color = wx.NullColour, oob_color = wx.RED, )

Change the value without sending an EVT_TEXT event.

:param int `value`: The value to be set

Override the :func:`TextCtrl.Cut` function, with our own
that does validation.  Will result in a value of 0
if entire contents of control are removed.

Returns a tuple of (default_color, oob_color), indicating
the current color settings for the control.

Gets the minimum value of the control.  It will return the current
minimum integer, or None if not specified.

:param int `value`: value to check or None

has changed, and issue EVT_INT event.
NOTE: using wx.TextCtrl.SetValue() to change the control's
contents from within a wx.EVT_CHAR handler can cause double
text events.  So we check for actual changes to the text
before passing the events on.

Override the :func:`TextCtrl.Paste` function, with our own
that does validation.  Will raise ValueError if not a
valid integerizable value.

..note::
  Leaving out an argument will remove the corresponding bound.

:param int `min`: The value to be set as minimum

:param int `max`: The value to be set as maximum

Tells the control what colors to use for normal and out-of-bounds
values.  If the value currently exceeds the bounds, it will be
recolored accordingly.

:param Color `default_color`: default color to be used
:param Color `oob_color`: out of bound color to be used

:param bool `limited`: If True set to control to be limited.

to have a long value or not, as appropriate.  If the value
of the control is currently long, and allow_long is 0, the
value of the control will be adjusted to fall within the
size of an integer type, at either the sys.maxsize or -sys.maxsize-1,
for positive and negative values, respectively.

:param bool `allow_long`: If True allow long values for control

the function returns 0 and the maximum will not change from its
current setting. On success, the function returns 1.

control will be colored with the current out-of-bounds color.

If max > sys.maxsize and the control is configured to not allow longs,
the function will return 0, and the max will not be set.

If min > -sys.maxsize-1 and the control is configured to not allow longs,
the function will return 0, and the min will not be set.

of the control is currently None, and allow_none is 0, the

:param bool `allow_none`: If True a None value is allowed

Sets the value of the control to the integer value specified.

Event sent from the :class:`~lib.intctrl.IntCtrl` when control is updated.

:param int `id`: the object id
:param int `value`: the value
:param `object`: the object of the event

Validator class used with :class:`~lib.intctrl.IntCtrl` handles all validation of
input prior to changing the value of the underlying :class:`TextCtrl`.

Standard cloner

..note::
  Every validator must implement the Clone() method.

Validates keystrokes to make sure the resulting value will a legal
value.  Erasing the value causes it to be set to 0, with the value
selected, so it can be replaced.  Similarly, replacing the value
with a '-' sign causes the value to become -1, with the value
selected.  Leading zeros are removed if introduced by selection,
and are prevented from being inserted.

Transfer data from window to validator.

The default implementation returns False, indicating that an error
occurred.  We simply return True, to indicate to e.g. :class:`Dialog`
that all is well.

If data comes e.g. from a database then you need to override this.

Transfer data from validator to window.

Because each operation on the control is vetted as it's made,
the value of the control is always valid.

Created on Oct 3, 2010

@authors: Daphna Rosenbom,Gitty Zinger,Moshe Cohavi and Yoav Glazner
The widget is contributed by NDS ltd under the same license as wxPython

items_picker.ItemsPicker:
  - Displays available items to choose from,</LI>
  - Selection is done by the Add button or Double Click,</LI>
  - De-Selection is done by the Remove button or Double Click,</LI>

  Derived from wxPanel

# Name:         itemspicker.py
# Purpose:
#
# Author:       Daphna Rosenbom, Gitty Zinger, Moshe Cohavi and Yoav Glazner
#
# Created:      Oct 3, 2010
# Version:
# Date:
# Licence:      wxPython license

ItemsPicker is a widget that allows the user to form a set of picked
items out of a given list

ItemsPicker(parent, choices = [], label = '', selectedLabel = '',
            ipStyle = IP_DEFAULT_STYLE)

__init__(self, parent, id=wx.ID_ANY, choices = [], label = '', selectedLabel = '', ipStyle = IP_DEFAULT_STYLE, \*args, \*\*kw)

GetItems(self)=> items
returns list of strings that the user can pick from

GetSelections(self)=>items
returns list of strings that were selected

SetItems(self, items)=> None
items - Sequence of strings that the user can pick from

SetSelections(self, items)=>None
items - Sequence of strings to be selected
The items are displayed in the selection part of the widget

ListCtrl and functions to display languages and the flags of their countries

# Name:        languagectrls.py
# Purpose:
#
#
# Created:     2006
# Copyright:   (c) 2006 Riaan Booysen
# License:     wxPython

:class:`wx.ListCtrl` derived control that displays languages and flags

:param `parent`: Parent window. Must not be ``None``.
:type `parent`: wx.Window
:param `id`: Window identifier. The value ``ID_ANY`` indicates a default value.
:param `pos`: Window position. If ``DefaultPosition`` is specified then a default position is chosen.
:type `pos`: wx.Point
:param `size`: Window size. If ``DefaultSize``   is specified then the window is sized appropriately.
:type `size`: wx.Size
:param `style`: Window style. See :ref:`wx.ListCtrl`.
:param `filter`: Filter the list of languages (LC_AVAILABLE, LC_ALL or LC_ONLY)
:param `only`: a tuple of language ids
:param `select`: a 'wx.LANGUAGE_*' id to be selected

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.LC_REPORT | wx.LC_NO_HEADER | wx.LC_SINGLE_SEL, filter=LC_AVAILABLE, only=(), select=None, name='languagelistctrl')

Get the currently selected language in the control.

:returns: The currently selected language

Selects the given language ids item in the control.

:param `lang`: a 'wx.LANGUAGE_*' id

Filters the languages displayed in the control.

Builds a mapping of language ids to LANG_COUNTRY codes.

:returns: the mapping as a {langID: countryCode}

Create a language resource list

:returns: a tuple of (bitmaps, language descriptions, language ids)

Get the wx identifier for a language.

:returns: The language id as a string

['LANGUAGE_ABKHAZIAN', 'LANGUAGE_AFAR', 'LANGUAGE_AFAR_DJIBOUTI', 'LANGUAGE_AFAR_ERITREA', 'LANGUAGE_AFAR_ETHIOPIA', 'LANGUAGE_AFRIKAANS', 'LANGUAGE_AFRIKAANS_NAMIBIA', 'LANGUAGE_AFRIKAANS_SOUTH_AFRICA', 'LANGUAGE_AGHEM', 'LANGUAGE_AGHEM_CAMEROON', 'LANGUAGE_AKAN', 'LANGUAGE_AKAN_GHANA', 'LANGUAGE_ALBANIAN', 'LANGUAGE_ALBANIAN_ALBANIA', 'LANGUAGE_ALBANIAN_KOSOVO', 'LANGUAGE_ALBANIAN_NORTH_MACEDONIA', 'LANGUAGE_ALSATIAN_FRANCE', 'LANGUAGE_AMHARIC', 'LANGUAGE_AMHARIC_ETHIOPIA', 'LANGUAGE_ARABIC', 'LANGUAGE_ARABIC_ALGERIA', 'LANGUAGE_ARABIC_BAHRAIN', 'LANGUAGE_ARABIC_CHAD', 'LANGUAGE_ARABIC_COMOROS', 'LANGUAGE_ARABIC_DJIBOUTI', 'LANGUAGE_ARABIC_EGYPT', 'LANGUAGE_ARABIC_ERITREA', 'LANGUAGE_ARABIC_IRAQ', 'LANGUAGE_ARABIC_ISRAEL', 'LANGUAGE_ARABIC_JORDAN', 'LANGUAGE_ARABIC_KUWAIT', 'LANGUAGE_ARABIC_LEBANON', 'LANGUAGE_ARABIC_LIBYA', 'LANGUAGE_ARABIC_MAURITANIA', 'LANGUAGE_ARABIC_MOROCCO', 'LANGUAGE_ARABIC_OMAN', 'LANGUAGE_ARABIC_PALESTINIAN_AUTHORITY', 'LANGUAGE_ARABIC_QATAR', 'LANGUAGE_ARABIC_SAUDI_ARABIA', 'LANGUAGE_ARABIC_SOMALIA', 'LANGUAGE_ARABIC_SOUTH_SUDAN', 'LANGUAGE_ARABIC_SUDAN', 'LANGUAGE_ARABIC_SYRIA', 'LANGUAGE_ARABIC_TUNISIA', 'LANGUAGE_ARABIC_UAE', 'LANGUAGE_ARABIC_WORLD', 'LANGUAGE_ARABIC_YEMEN', 'LANGUAGE_ARMENIAN', 'LANGUAGE_ARMENIAN_ARMENIA', 'LANGUAGE_ASSAMESE', 'LANGUAGE_ASSAMESE_INDIA', 'LANGUAGE_ASTURIAN', 'LANGUAGE_ASTURIAN_SPAIN', 'LANGUAGE_ASU', 'LANGUAGE_ASU_TANZANIA', 'LANGUAGE_AYMARA', 'LANGUAGE_AZERBAIJANI', 'LANGUAGE_AZERBAIJANI_CYRILLIC', 'LANGUAGE_AZERBAIJANI_CYRILLIC_AZERBAIJAN', 'LANGUAGE_AZERBAIJANI_LATIN', 'LANGUAGE_AZERBAIJANI_LATIN_AZERBAIJAN', 'LANGUAGE_AZERI', 'LANGUAGE_AZERI_CYRILLIC', 'LANGUAGE_AZERI_LATIN', 'LANGUAGE_BAFIA', 'LANGUAGE_BAFIA_CAMEROON', 'LANGUAGE_BAMANANKAN', 'LANGUAGE_BAMANANKAN_LATIN', 'LANGUAGE_BAMANANKAN_LATIN_MALI', 'LANGUAGE_BANGLA', 'LANGUAGE_BANGLA_BANGLADESH', 'LANGUAGE_BANGLA_INDIA', 'LANGUAGE_BASAA', 'LANGUAGE_BASAA_CAMEROON', 'LANGUAGE_BASHKIR', 'LANGUAGE_BASHKIR_RUSSIA', 'LANGUAGE_BASQUE', 'LANGUAGE_BASQUE_SPAIN', 'LANGUAGE_BELARUSIAN', 'LANGUAGE_BELARUSIAN_BELARUS', 'LANGUAGE_BEMBA', 'LANGUAGE_BEMBA_ZAMBIA', 'LANGUAGE_BENA', 'LANGUAGE_BENA_TANZANIA', 'LANGUAGE_BENGALI', 'LANGUAGE_BENGALI_BANGLADESH', 'LANGUAGE_BENGALI_INDIA', 'LANGUAGE_BHUTANI', 'LANGUAGE_BIHARI', 'LANGUAGE_BISLAMA', 'LANGUAGE_BLIN', 'LANGUAGE_BLIN_ERITREA', 'LANGUAGE_BODO', 'LANGUAGE_BODO_INDIA', 'LANGUAGE_BOSNIAN', 'LANGUAGE_BOSNIAN_CYRILLIC', 'LANGUAGE_BOSNIAN_CYRILLIC_BOSNIA_AND_HERZEGOVINA', 'LANGUAGE_BOSNIAN_LATIN', 'LANGUAGE_BOSNIAN_LATIN_BOSNIA_AND_HERZEGOVINA', 'LANGUAGE_BRETON', 'LANGUAGE_BRETON_FRANCE', 'LANGUAGE_BULGARIAN', 'LANGUAGE_BULGARIAN_BULGARIA', 'LANGUAGE_BURMESE', 'LANGUAGE_BURMESE_MYANMAR', 'LANGUAGE_CAMBODIAN', 'LANGUAGE_CATALAN', 'LANGUAGE_CATALAN_ANDORRA', 'LANGUAGE_CATALAN_FRANCE', 'LANGUAGE_CATALAN_ITALY', 'LANGUAGE_CATALAN_SPAIN', 'LANGUAGE_CEBUANO', 'LANGUAGE_CEBUANO_LATIN', 'LANGUAGE_CEBUANO_LATIN_PHILIPPINES', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_ARABIC', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_ARABIC_MOROCCO', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_LATIN', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_LATIN_ALGERIA', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_LATIN_MOROCCO', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_TIFINAGH', 'LANGUAGE_CENTRAL_ATLAS_TAMAZIGHT_TIFINAGH_MOROCCO', 'LANGUAGE_CENTRAL_KURDISH', 'LANGUAGE_CENTRAL_KURDISH_IRAQ', 'LANGUAGE_CHAKMA', 'LANGUAGE_CHAKMA_CHAKMA', 'LANGUAGE_CHAKMA_CHAKMA_BANGLADESH', 'LANGUAGE_CHAKMA_CHAKMA_INDIA', 'LANGUAGE_CHECHEN', 'LANGUAGE_CHECHEN_RUSSIA', 'LANGUAGE_CHEROKEE', 'LANGUAGE_CHEROKEE_CHEROKEE', 'LANGUAGE_CHEROKEE_US', 'LANGUAGE_CHIGA', 'LANGUAGE_CHIGA_UGANDA', 'LANGUAGE_CHINESE', 'LANGUAGE_CHINESE_CHINA', 'LANGUAGE_CHINESE_HONGKONG', 'LANGUAGE_CHINESE_MACAO', 'LANGUAGE_CHINESE_MACAU', 'LANGUAGE_CHINESE_SIMPLIFIED', 'LANGUAGE_CHINESE_SIMPLIFIED_EXPLICIT', 'LANGUAGE_CHINESE_SIMPLIFIED_HONGKONG', 'LANGUAGE_CHINESE_SIMPLIFIED_MACAO', 'LANGUAGE_CHINESE_SINGAPORE', 'LANGUAGE_CHINESE_TAIWAN', 'LANGUAGE_CHINESE_TRADITIONAL', 'LANGUAGE_CHINESE_TRADITIONAL_EXPLICIT', 'LANGUAGE_CHURCH_SLAVIC', 'LANGUAGE_CHURCH_SLAVIC_RUSSIA', 'LANGUAGE_COLOGNIAN', 'LANGUAGE_COLOGNIAN_GERMANY', 'LANGUAGE_CORNISH', 'LANGUAGE_CORNISH_UK', 'LANGUAGE_CORSICAN', 'LANGUAGE_CORSICAN_FRANCE', 'LANGUAGE_CROATIAN', 'LANGUAGE_CROATIAN_BOSNIA_AND_HERZEGOVINA', 'LANGUAGE_CROATIAN_CROATIA', 'LANGUAGE_CZECH', 'LANGUAGE_CZECH_CZECHIA', 'LANGUAGE_DANISH', 'LANGUAGE_DANISH_DENMARK', 'LANGUAGE_DANISH_GREENLAND', 'LANGUAGE_DARI', 'LANGUAGE_DARI_AFGHANISTAN', 'LANGUAGE_DEFAULT', 'LANGUAGE_DIVEHI', 'LANGUAGE_DIVEHI_MALDIVES', 'LANGUAGE_DUALA', 'LANGUAGE_DUALA_CAMEROON', 'LANGUAGE_DUTCH', 'LANGUAGE_DUTCH_ARUBA', 'LANGUAGE_DUTCH_BELGIAN', 'LANGUAGE_DUTCH_BONAIRE_SINT_EUSTATIUS_AND_SABA', 'LANGUAGE_DUTCH_CURACAO', 'LANGUAGE_DUTCH_NETHERLANDS', 'LANGUAGE_DUTCH_SINT_MAARTEN', 'LANGUAGE_DUTCH_SURINAME', 'LANGUAGE_DZONGKHA', 'LANGUAGE_DZONGKHA_BHUTAN', 'LANGUAGE_EDO', 'LANGUAGE_EDO_NIGERIA', 'LANGUAGE_EMBU', 'LANGUAGE_EMBU_KENYA', 'LANGUAGE_ENGLISH', 'LANGUAGE_ENGLISH_AMERICAN_SAMOA', 'LANGUAGE_ENGLISH_ANGUILLA', 'LANGUAGE_ENGLISH_ANTIGUA_AND_BARBUDA', 'LANGUAGE_ENGLISH_AUSTRALIA', 'LANGUAGE_ENGLISH_AUSTRIA', 'LANGUAGE_ENGLISH_BAHAMAS', 'LANGUAGE_ENGLISH_BARBADOS', 'LANGUAGE_ENGLISH_BELGIUM', 'LANGUAGE_ENGLISH_BELIZE', 'LANGUAGE_ENGLISH_BERMUDA', 'LANGUAGE_ENGLISH_BOTSWANA', 'LANGUAGE_ENGLISH_BRITISH_INDIAN_OCEAN_TERRITORY', 'LANGUAGE_ENGLISH_BRITISH_VIRGIN_ISLANDS', 'LANGUAGE_ENGLISH_BURUNDI', 'LANGUAGE_ENGLISH_CAMEROON', 'LANGUAGE_ENGLISH_CANADA', 'LANGUAGE_ENGLISH_CARIBBEAN', 'LANGUAGE_ENGLISH_CARIBBEAN_CB', 'LANGUAGE_ENGLISH_CAYMAN_ISLANDS', 'LANGUAGE_ENGLISH_CHRISTMAS_ISLAND', 'LANGUAGE_ENGLISH_COCOS_KEELING_ISLANDS', 'LANGUAGE_ENGLISH_COOK_ISLANDS', 'LANGUAGE_ENGLISH_CYPRUS', 'LANGUAGE_ENGLISH_DENMARK', 'LANGUAGE_ENGLISH_DOMINICA', 'LANGUAGE_ENGLISH_EIRE', 'LANGUAGE_ENGLISH_ERITREA', 'LANGUAGE_ENGLISH_ESWATINI', 'LANGUAGE_ENGLISH_EUROPE', 'LANGUAGE_ENGLISH_FALKLAND_ISLANDS', 'LANGUAGE_ENGLISH_FIJI', 'LANGUAGE_ENGLISH_FINLAND', 'LANGUAGE_ENGLISH_GAMBIA', 'LANGUAGE_ENGLISH_GERMANY', 'LANGUAGE_ENGLISH_GHANA', 'LANGUAGE_ENGLISH_GIBRALTAR', 'LANGUAGE_ENGLISH_GRENADA', 'LANGUAGE_ENGLISH_GUAM', 'LANGUAGE_ENGLISH_GUERNSEY', 'LANGUAGE_ENGLISH_GUYANA', 'LANGUAGE_ENGLISH_HONG_KONG_SAR', 'LANGUAGE_ENGLISH_INDIA', 'LANGUAGE_ENGLISH_INDONESIA', 'LANGUAGE_ENGLISH_ISLE_OF_MAN', 'LANGUAGE_ENGLISH_ISRAEL', 'LANGUAGE_ENGLISH_JAMAICA', 'LANGUAGE_ENGLISH_JERSEY', 'LANGUAGE_ENGLISH_KENYA', 'LANGUAGE_ENGLISH_KIRIBATI', 'LANGUAGE_ENGLISH_LESOTHO', 'LANGUAGE_ENGLISH_LIBERIA', 'LANGUAGE_ENGLISH_MACAO_SAR', 'LANGUAGE_ENGLISH_MADAGASCAR', 'LANGUAGE_ENGLISH_MALAWI', 'LANGUAGE_ENGLISH_MALAYSIA', 'LANGUAGE_ENGLISH_MALTA', 'LANGUAGE_ENGLISH_MARSHALL_ISLANDS', 'LANGUAGE_ENGLISH_MAURITIUS', 'LANGUAGE_ENGLISH_MICRONESIA', 'LANGUAGE_ENGLISH_MONTSERRAT', 'LANGUAGE_ENGLISH_NAMIBIA', 'LANGUAGE_ENGLISH_NAURU', 'LANGUAGE_ENGLISH_NETHERLANDS', 'LANGUAGE_ENGLISH_NEW_ZEALAND', 'LANGUAGE_ENGLISH_NIGERIA', 'LANGUAGE_ENGLISH_NIUE', 'LANGUAGE_ENGLISH_NORFOLK_ISLAND', 'LANGUAGE_ENGLISH_NORTHERN_MARIANA_ISLANDS', 'LANGUAGE_ENGLISH_PAKISTAN', 'LANGUAGE_ENGLISH_PALAU', 'LANGUAGE_ENGLISH_PAPUA_NEW_GUINEA', 'LANGUAGE_ENGLISH_PHILIPPINES', 'LANGUAGE_ENGLISH_PITCAIRN_ISLANDS', 'LANGUAGE_ENGLISH_PUERTO_RICO', 'LANGUAGE_ENGLISH_RWANDA', 'LANGUAGE_ENGLISH_SAMOA', 'LANGUAGE_ENGLISH_SEYCHELLES', 'LANGUAGE_ENGLISH_SIERRA_LEONE', 'LANGUAGE_ENGLISH_SINGAPORE', 'LANGUAGE_ENGLISH_SINT_MAARTEN', 'LANGUAGE_ENGLISH_SLOVENIA', 'LANGUAGE_ENGLISH_SOLOMON_ISLANDS', 'LANGUAGE_ENGLISH_SOUTH_AFRICA', 'LANGUAGE_ENGLISH_SOUTH_SUDAN', 'LANGUAGE_ENGLISH_ST_HELENA_ASCENSION_TRISTAN_DA_CUNHA', 'LANGUAGE_ENGLISH_ST_KITTS_AND_NEVIS', 'LANGUAGE_ENGLISH_ST_LUCIA', 'LANGUAGE_ENGLISH_ST_VINCENT_AND_GRENADINES', 'LANGUAGE_ENGLISH_SUDAN', 'LANGUAGE_ENGLISH_SWEDEN', 'LANGUAGE_ENGLISH_SWITZERLAND', 'LANGUAGE_ENGLISH_TANZANIA', 'LANGUAGE_ENGLISH_TOKELAU', 'LANGUAGE_ENGLISH_TONGA', 'LANGUAGE_ENGLISH_TRINIDAD', 'LANGUAGE_ENGLISH_TURKS_AND_CAICOS_ISLANDS', 'LANGUAGE_ENGLISH_TUVALU', 'LANGUAGE_ENGLISH_UGANDA', 'LANGUAGE_ENGLISH_UK', 'LANGUAGE_ENGLISH_UNITED_ARAB_EMIRATES', 'LANGUAGE_ENGLISH_US', 'LANGUAGE_ENGLISH_US_OUTLYING_ISLANDS', 'LANGUAGE_ENGLISH_US_VIRGIN_ISLANDS', 'LANGUAGE_ENGLISH_VANUATU', 'LANGUAGE_ENGLISH_WORLD', 'LANGUAGE_ENGLISH_ZAMBIA', 'LANGUAGE_ENGLISH_ZIMBABWE', 'LANGUAGE_ESPERANTO', 'LANGUAGE_ESPERANTO_WORLD', 'LANGUAGE_ESTONIAN', 'LANGUAGE_ESTONIAN_ESTONIA', 'LANGUAGE_EWE', 'LANGUAGE_EWE_GHANA', 'LANGUAGE_EWE_TOGO', 'LANGUAGE_EWONDO', 'LANGUAGE_EWONDO_CAMEROON', 'LANGUAGE_FAEROESE', 'LANGUAGE_FAEROESE_DENMARK', 'LANGUAGE_FAEROESE_FAROE_ISLANDS', 'LANGUAGE_FARSI', 'LANGUAGE_FIJI', 'LANGUAGE_FILIPINO', 'LANGUAGE_FILIPINO_PHILIPPINES', 'LANGUAGE_FINNISH', 'LANGUAGE_FINNISH_FINLAND', 'LANGUAGE_FRENCH', 'LANGUAGE_FRENCH_ALGERIA', 'LANGUAGE_FRENCH_BELGIAN', 'LANGUAGE_FRENCH_BENIN', 'LANGUAGE_FRENCH_BURKINA_FASO', 'LANGUAGE_FRENCH_BURUNDI', 'LANGUAGE_FRENCH_CAMEROON', 'LANGUAGE_FRENCH_CANADIAN', 'LANGUAGE_FRENCH_CARIBBEAN', 'LANGUAGE_FRENCH_CENTRAL_AFRICAN_REPUBLIC', 'LANGUAGE_FRENCH_CHAD', 'LANGUAGE_FRENCH_COMOROS', 'LANGUAGE_FRENCH_CONGO', 'LANGUAGE_FRENCH_CONGO_DRC', 'LANGUAGE_FRENCH_COTE_DIVOIRE', 'LANGUAGE_FRENCH_DJIBOUTI', 'LANGUAGE_FRENCH_EQUATORIAL_GUINEA', 'LANGUAGE_FRENCH_FRANCE', 'LANGUAGE_FRENCH_FRENCH_GUIANA', 'LANGUAGE_FRENCH_FRENCH_POLYNESIA', 'LANGUAGE_FRENCH_GABON', 'LANGUAGE_FRENCH_GUADELOUPE', 'LANGUAGE_FRENCH_GUINEA', 'LANGUAGE_FRENCH_HAITI', 'LANGUAGE_FRENCH_LUXEMBOURG', 'LANGUAGE_FRENCH_MADAGASCAR', 'LANGUAGE_FRENCH_MALI', 'LANGUAGE_FRENCH_MARTINIQUE', 'LANGUAGE_FRENCH_MAURITANIA', 'LANGUAGE_FRENCH_MAURITIUS', 'LANGUAGE_FRENCH_MAYOTTE', 'LANGUAGE_FRENCH_MONACO', 'LANGUAGE_FRENCH_MOROCCO', 'LANGUAGE_FRENCH_NEW_CALEDONIA', 'LANGUAGE_FRENCH_NIGER', 'LANGUAGE_FRENCH_REUNION', 'LANGUAGE_FRENCH_RWANDA', 'LANGUAGE_FRENCH_SENEGAL', 'LANGUAGE_FRENCH_SEYCHELLES', 'LANGUAGE_FRENCH_ST_BARTHELEMY', 'LANGUAGE_FRENCH_ST_MARTIN', 'LANGUAGE_FRENCH_ST_PIERRE_AND_MIQUELON', 'LANGUAGE_FRENCH_SWISS', 'LANGUAGE_FRENCH_SYRIA', 'LANGUAGE_FRENCH_TOGO', 'LANGUAGE_FRENCH_TUNISIA', 'LANGUAGE_FRENCH_VANUATU', 'LANGUAGE_FRENCH_WALLIS_AND_FUTUNA', 'LANGUAGE_FRISIAN', 'LANGUAGE_FRISIAN_NETHERLANDS', 'LANGUAGE_FRIULIAN', 'LANGUAGE_FRIULIAN_ITALY', 'LANGUAGE_FULAH', 'LANGUAGE_FULAH_LATIN', 'LANGUAGE_FULAH_LATIN_BURKINA_FASO', 'LANGUAGE_FULAH_LATIN_CAMEROON', 'LANGUAGE_FULAH_LATIN_GAMBIA', 'LANGUAGE_FULAH_LATIN_GHANA', 'LANGUAGE_FULAH_LATIN_GUINEA', 'LANGUAGE_FULAH_LATIN_GUINEA_BISSAU', 'LANGUAGE_FULAH_LATIN_LIBERIA', 'LANGUAGE_FULAH_LATIN_MAURITANIA', 'LANGUAGE_FULAH_LATIN_NIGER', 'LANGUAGE_FULAH_LATIN_NIGERIA', 'LANGUAGE_FULAH_LATIN_SENEGAL', 'LANGUAGE_FULAH_LATIN_SIERRA_LEONE', 'LANGUAGE_GALICIAN', 'LANGUAGE_GALICIAN_SPAIN', 'LANGUAGE_GANDA', 'LANGUAGE_GANDA_UGANDA', 'LANGUAGE_GEORGIAN', 'LANGUAGE_GEORGIAN_GEORGIA', 'LANGUAGE_GERMAN', 'LANGUAGE_GERMAN_AUSTRIAN', 'LANGUAGE_GERMAN_BELGIUM', 'LANGUAGE_GERMAN_GERMANY', 'LANGUAGE_GERMAN_ITALY', 'LANGUAGE_GERMAN_LIECHTENSTEIN', 'LANGUAGE_GERMAN_LUXEMBOURG', 'LANGUAGE_GERMAN_SWISS', 'LANGUAGE_GREEK', 'LANGUAGE_GREEK_CYPRUS', 'LANGUAGE_GREEK_GREECE', 'LANGUAGE_GREENLANDIC', 'LANGUAGE_GUARANI', 'LANGUAGE_GUARANI_PARAGUAY', 'LANGUAGE_GUJARATI', 'LANGUAGE_GUJARATI_INDIA', 'LANGUAGE_GUSII', 'LANGUAGE_GUSII_KENYA', 'LANGUAGE_HAUSA', 'LANGUAGE_HAUSA_LATIN', 'LANGUAGE_HAUSA_LATIN_GHANA', 'LANGUAGE_HAUSA_LATIN_NIGER', 'LANGUAGE_HAUSA_LATIN_NIGERIA', 'LANGUAGE_HAWAIIAN', 'LANGUAGE_HAWAIIAN_US', 'LANGUAGE_HEBREW', 'LANGUAGE_HEBREW_ISRAEL', 'LANGUAGE_HINDI', 'LANGUAGE_HINDI_INDIA', 'LANGUAGE_HUNGARIAN', 'LANGUAGE_HUNGARIAN_HUNGARY', 'LANGUAGE_IBIBIO', 'LANGUAGE_IBIBIO_NIGERIA', 'LANGUAGE_ICELANDIC', 'LANGUAGE_ICELANDIC_ICELAND', 'LANGUAGE_IGBO', 'LANGUAGE_IGBO_NIGERIA', 'LANGUAGE_INDONESIAN', 'LANGUAGE_INDONESIAN_INDONESIA', 'LANGUAGE_INTERLINGUA', 'LANGUAGE_INTERLINGUA_WORLD', 'LANGUAGE_INTERLINGUE', 'LANGUAGE_INUKTITUT', 'LANGUAGE_INUKTITUT_LATIN', 'LANGUAGE_INUKTITUT_LATIN_CANADA', 'LANGUAGE_INUKTITUT_SYLLABICS', 'LANGUAGE_INUKTITUT_SYLLABICS_CANADA', 'LANGUAGE_INUPIAK', 'LANGUAGE_IRISH', 'LANGUAGE_IRISH_IRELAND', 'LANGUAGE_ITALIAN', 'LANGUAGE_ITALIAN_ITALY', 'LANGUAGE_ITALIAN_SAN_MARINO', 'LANGUAGE_ITALIAN_SWISS', 'LANGUAGE_ITALIAN_VATICAN_CITY', 'LANGUAGE_JAPANESE', 'LANGUAGE_JAPANESE_JAPAN', 'LANGUAGE_JAVANESE', 'LANGUAGE_JAVANESE_INDONESIA', 'LANGUAGE_JAVANESE_JAVANESE', 'LANGUAGE_JAVANESE_JAVANESE_INDONESIA', 'LANGUAGE_JOLA_FONYI', 'LANGUAGE_JOLA_FONYI_SENEGAL', 'LANGUAGE_KABUVERDIANU', 'LANGUAGE_KABUVERDIANU_CABO_VERDE', 'LANGUAGE_KABYLE', 'LANGUAGE_KABYLE_ALGERIA', 'LANGUAGE_KAKO', 'LANGUAGE_KAKO_CAMEROON', 'LANGUAGE_KALAALLISUT', 'LANGUAGE_KALENJIN', 'LANGUAGE_KALENJIN_KENYA', 'LANGUAGE_KAMBA', 'LANGUAGE_KAMBA_KENYA', 'LANGUAGE_KANNADA', 'LANGUAGE_KANNADA_INDIA', 'LANGUAGE_KANURI', 'LANGUAGE_KANURI_LATIN', 'LANGUAGE_KANURI_NIGERIA', 'LANGUAGE_KASHMIRI', 'LANGUAGE_KASHMIRI_DEVANAGARI', 'LANGUAGE_KASHMIRI_DEVANAGARI_INDIA', 'LANGUAGE_KASHMIRI_INDIA', 'LANGUAGE_KASHMIRI_PERSO_ARABIC', 'LANGUAGE_KASHMIRI_PERSO_ARABIC_INDIA', 'LANGUAGE_KAZAKH', 'LANGUAGE_KAZAKH_KAZAKHSTAN', 'LANGUAGE_KERNEWEK', 'LANGUAGE_KHMER', 'LANGUAGE_KHMER_CAMBODIA', 'LANGUAGE_KICHE', 'LANGUAGE_KICHE_GUATEMALA', 'LANGUAGE_KICHE_LATIN', 'LANGUAGE_KIKUYU', 'LANGUAGE_KIKUYU_KENYA', 'LANGUAGE_KINYARWANDA', 'LANGUAGE_KINYARWANDA_RWANDA', 'LANGUAGE_KIRGHIZ', 'LANGUAGE_KIRGHIZ_KYRGYZSTAN', 'LANGUAGE_KIRUNDI', 'LANGUAGE_KIRUNDI_BURUNDI', 'LANGUAGE_KONKANI', 'LANGUAGE_KONKANI_INDIA', 'LANGUAGE_KOREAN', 'LANGUAGE_KOREAN_KOREA', 'LANGUAGE_KOREAN_NORTH_KOREA', 'LANGUAGE_KOYRABORO_SENNI', 'LANGUAGE_KOYRABORO_SENNI_MALI', 'LANGUAGE_KOYRA_CHIINI', 'LANGUAGE_KOYRA_CHIINI_MALI', 'LANGUAGE_KURDISH', 'LANGUAGE_KURDISH_PERSO_ARABIC_IRAN', 'LANGUAGE_KWASIO', 'LANGUAGE_KWASIO_CAMEROON', 'LANGUAGE_LAKOTA', 'LANGUAGE_LAKOTA_US', 'LANGUAGE_LANGI', 'LANGUAGE_LANGI_TANZANIA', 'LANGUAGE_LAOTHIAN', 'LANGUAGE_LAOTHIAN_LAOS', 'LANGUAGE_LATIN', 'LANGUAGE_LATIN_WORLD', 'LANGUAGE_LATVIAN', 'LANGUAGE_LATVIAN_LATVIA', 'LANGUAGE_LINGALA', 'LANGUAGE_LINGALA_ANGOLA', 'LANGUAGE_LINGALA_CENTRAL_AFRICAN_REPUBLIC', 'LANGUAGE_LINGALA_CONGO', 'LANGUAGE_LINGALA_CONGO_DRC', 'LANGUAGE_LITHUANIAN', 'LANGUAGE_LITHUANIAN_LITHUANIA', 'LANGUAGE_LOWER_SORBIAN', 'LANGUAGE_LOWER_SORBIAN_GERMANY', 'LANGUAGE_LOW_GERMAN', 'LANGUAGE_LOW_GERMAN_GERMANY', 'LANGUAGE_LOW_GERMAN_NETHERLANDS', 'LANGUAGE_LUBA_KATANGA', 'LANGUAGE_LUBA_KATANGA_CONGO_DRC', 'LANGUAGE_LUO', 'LANGUAGE_LUO_KENYA', 'LANGUAGE_LUXEMBOURGISH', 'LANGUAGE_LUXEMBOURGISH_LUXEMBOURG', 'LANGUAGE_LUYIA', 'LANGUAGE_LUYIA_KENYA', 'LANGUAGE_MACEDONIAN', 'LANGUAGE_MACEDONIAN_NORTH_MACEDONIA', 'LANGUAGE_MACHAME', 'LANGUAGE_MACHAME_TANZANIA', 'LANGUAGE_MAKHUWA_MEETTO', 'LANGUAGE_MAKHUWA_MEETTO_MOZAMBIQUE', 'LANGUAGE_MAKONDE', 'LANGUAGE_MAKONDE_TANZANIA', 'LANGUAGE_MALAGASY', 'LANGUAGE_MALAGASY_MADAGASCAR', 'LANGUAGE_MALAY', 'LANGUAGE_MALAYALAM', 'LANGUAGE_MALAYALAM_INDIA', 'LANGUAGE_MALAY_BRUNEI', 'LANGUAGE_MALAY_BRUNEI_DARUSSALAM', 'LANGUAGE_MALAY_MALAYSIA', 'LANGUAGE_MALAY_SINGAPORE', 'LANGUAGE_MALTESE', 'LANGUAGE_MALTESE_MALTA', 'LANGUAGE_MANIPURI', 'LANGUAGE_MANIPURI_INDIA', 'LANGUAGE_MANX', 'LANGUAGE_MANX_ISLE_OF_MAN', 'LANGUAGE_MAORI', 'LANGUAGE_MAORI_NEW_ZEALAND', 'LANGUAGE_MAPUCHE', 'LANGUAGE_MAPUCHE_CHILE', 'LANGUAGE_MARATHI', 'LANGUAGE_MARATHI_INDIA', 'LANGUAGE_MASAI', 'LANGUAGE_MASAI_KENYA', 'LANGUAGE_MASAI_TANZANIA', 'LANGUAGE_MAZANDERANI', 'LANGUAGE_MAZANDERANI_IRAN', 'LANGUAGE_MERU', 'LANGUAGE_MERU_KENYA', 'LANGUAGE_META', 'LANGUAGE_META_CAMEROON', 'LANGUAGE_MOHAWK', 'LANGUAGE_MOHAWK_CANADA', 'LANGUAGE_MOLDAVIAN', 'LANGUAGE_MONGOLIAN', 'LANGUAGE_MONGOLIAN_CYRILLIC', 'LANGUAGE_MONGOLIAN_MONGOLIA', 'LANGUAGE_MONGOLIAN_TRADITIONAL', 'LANGUAGE_MONGOLIAN_TRADITIONAL_CHINA', 'LANGUAGE_MONGOLIAN_TRADITIONAL_MONGOLIA', 'LANGUAGE_MORISYEN', 'LANGUAGE_MORISYEN_MAURITIUS', 'LANGUAGE_MUNDANG', 'LANGUAGE_MUNDANG_CAMEROON', 'LANGUAGE_NAMA', 'LANGUAGE_NAMA_NAMIBIA', 'LANGUAGE_NAURU', 'LANGUAGE_NEPALI', 'LANGUAGE_NEPALI_INDIA', 'LANGUAGE_NEPALI_NEPAL', 'LANGUAGE_NGIEMBOON', 'LANGUAGE_NGIEMBOON_CAMEROON', 'LANGUAGE_NGOMBA', 'LANGUAGE_NGOMBA_CAMEROON', 'LANGUAGE_NKO', 'LANGUAGE_NKO_GUINEA', 'LANGUAGE_NORTHERN_LURI', 'LANGUAGE_NORTHERN_LURI_IRAN', 'LANGUAGE_NORTHERN_LURI_IRAQ', 'LANGUAGE_NORTH_NDEBELE', 'LANGUAGE_NORTH_NDEBELE_ZIMBABWE', 'LANGUAGE_NORWEGIAN', 'LANGUAGE_NORWEGIAN_BOKMAL', 'LANGUAGE_NORWEGIAN_BOKMAL_NORWAY', 'LANGUAGE_NORWEGIAN_BOKMAL_SVALBARD_AND_JAN_MAYEN', 'LANGUAGE_NORWEGIAN_NYNORSK', 'LANGUAGE_NORWEGIAN_NYNORSK_NORWAY', 'LANGUAGE_NUER', 'LANGUAGE_NUER_SOUTH_SUDAN', 'LANGUAGE_NYANKOLE', 'LANGUAGE_NYANKOLE_UGANDA', 'LANGUAGE_OCCITAN', 'LANGUAGE_OCCITAN_FRANCE', 'LANGUAGE_ODIA', 'LANGUAGE_ODIA_INDIA', 'LANGUAGE_ORIYA', 'LANGUAGE_ORIYA_INDIA', 'LANGUAGE_OROMO', 'LANGUAGE_OROMO_ETHIOPIA', 'LANGUAGE_OROMO_KENYA', 'LANGUAGE_OSSETIC', 'LANGUAGE_OSSETIC_GEORGIA', 'LANGUAGE_OSSETIC_RUSSIA', 'LANGUAGE_PAPIAMENTO', 'LANGUAGE_PAPIAMENTO_CARIBBEAN', 'LANGUAGE_PASHTO', 'LANGUAGE_PASHTO_AFGHANISTAN', 'LANGUAGE_PASHTO_PAKISTAN', 'LANGUAGE_PERSIAN_IRAN', 'LANGUAGE_POLISH', 'LANGUAGE_POLISH_POLAND', 'LANGUAGE_PORTUGUESE', 'LANGUAGE_PORTUGUESE_ANGOLA', 'LANGUAGE_PORTUGUESE_BRAZILIAN', 'LANGUAGE_PORTUGUESE_CABO_VERDE', 'LANGUAGE_PORTUGUESE_EQUATORIAL_GUINEA', 'LANGUAGE_PORTUGUESE_GUINEA_BISSAU', 'LANGUAGE_PORTUGUESE_LUXEMBOURG', 'LANGUAGE_PORTUGUESE_MACAO_SAR', 'LANGUAGE_PORTUGUESE_MOZAMBIQUE', 'LANGUAGE_PORTUGUESE_PORTUGAL', 'LANGUAGE_PORTUGUESE_SAO_TOME_AND_PRINCIPE', 'LANGUAGE_PORTUGUESE_SWITZERLAND', 'LANGUAGE_PORTUGUESE_TIMOR_LESTE', 'LANGUAGE_PRUSSIAN', 'LANGUAGE_PRUSSIAN_WORLD', 'LANGUAGE_PUNJABI', 'LANGUAGE_PUNJABI_ARABIC', 'LANGUAGE_PUNJABI_GURMUKHI', 'LANGUAGE_PUNJABI_INDIA', 'LANGUAGE_PUNJABI_PAKISTAN', 'LANGUAGE_QUECHUA', 'LANGUAGE_QUECHUA_BOLIVIA', 'LANGUAGE_QUECHUA_ECUADOR', 'LANGUAGE_QUECHUA_MACRO', 'LANGUAGE_QUECHUA_PERU', 'LANGUAGE_RHAETO_ROMANCE', 'LANGUAGE_RHAETO_ROMANCE_SWITZERLAND', 'LANGUAGE_ROMANIAN', 'LANGUAGE_ROMANIAN_MOLDOVA', 'LANGUAGE_ROMANIAN_ROMANIA', 'LANGUAGE_ROMBO', 'LANGUAGE_ROMBO_TANZANIA', 'LANGUAGE_RUSSIAN', 'LANGUAGE_RUSSIAN_BELARUS', 'LANGUAGE_RUSSIAN_KAZAKHSTAN', 'LANGUAGE_RUSSIAN_KYRGYZSTAN', 'LANGUAGE_RUSSIAN_MOLDOVA', 'LANGUAGE_RUSSIAN_RUSSIA', 'LANGUAGE_RUSSIAN_UKRAINE', 'LANGUAGE_RWA', 'LANGUAGE_RWA_TANZANIA', 'LANGUAGE_SAHO', 'LANGUAGE_SAHO_ERITREA', 'LANGUAGE_SAKHA', 'LANGUAGE_SAKHA_RUSSIA', 'LANGUAGE_SAMBURU', 'LANGUAGE_SAMBURU_KENYA', 'LANGUAGE_SAMI', 'LANGUAGE_SAMI_FINLAND', 'LANGUAGE_SAMI_INARI', 'LANGUAGE_SAMI_INARI_FINLAND', 'LANGUAGE_SAMI_LULE', 'LANGUAGE_SAMI_LULE_NORWAY', 'LANGUAGE_SAMI_LULE_SWEDEN', 'LANGUAGE_SAMI_NORWAY', 'LANGUAGE_SAMI_SKOLT', 'LANGUAGE_SAMI_SKOLT_FINLAND', 'LANGUAGE_SAMI_SOUTHERN', 'LANGUAGE_SAMI_SOUTHERN_NORWAY', 'LANGUAGE_SAMI_SOUTHERN_SWEDEN', 'LANGUAGE_SAMI_SWEDEN', 'LANGUAGE_SAMOAN', 'LANGUAGE_SANGHO', 'LANGUAGE_SANGHO_CENTRAL_AFRICAN_REPUBLIC', 'LANGUAGE_SANGU', 'LANGUAGE_SANGU_TANZANIA', 'LANGUAGE_SANSKRIT', 'LANGUAGE_SANSKRIT_INDIA', 'LANGUAGE_SCOTS_GAELIC', 'LANGUAGE_SCOTS_GAELIC_UK', 'LANGUAGE_SENA', 'LANGUAGE_SENA_MOZAMBIQUE', 'LANGUAGE_SERBIAN_CYRILLIC', 'LANGUAGE_SERBIAN_CYRILLIC_BOSNIA_AND_HERZEGOVINA', 'LANGUAGE_SERBIAN_CYRILLIC_KOSOVO', 'LANGUAGE_SERBIAN_CYRILLIC_MONTENEGRO', 'LANGUAGE_SERBIAN_CYRILLIC_SERBIA', 'LANGUAGE_SERBIAN_CYRILLIC_YU', 'LANGUAGE_SERBIAN_LATIN', 'LANGUAGE_SERBIAN_LATIN_BOSNIA_AND_HERZEGOVINA', 'LANGUAGE_SERBIAN_LATIN_KOSOVO', 'LANGUAGE_SERBIAN_LATIN_MONTENEGRO', 'LANGUAGE_SERBIAN_LATIN_SERBIA', 'LANGUAGE_SERBIAN_LATIN_YU', 'LANGUAGE_SERBIAN_SERBIA', 'LANGUAGE_SERBIAN_YU', 'LANGUAGE_SERBO_CROATIAN', 'LANGUAGE_SESOTHO', 'LANGUAGE_SESOTHO_LESOTHO', 'LANGUAGE_SESOTHO_SA_LEBOA', 'LANGUAGE_SESOTHO_SA_LEBOA_SOUTH_AFRICA', 'LANGUAGE_SESOTHO_SOUTH_AFRICA', 'LANGUAGE_SETSWANA', 'LANGUAGE_SETSWANA_BOTSWANA', 'LANGUAGE_SETSWANA_SOUTH_AFRICA', 'LANGUAGE_SHAMBALA', 'LANGUAGE_SHAMBALA_TANZANIA', 'LANGUAGE_SHONA', 'LANGUAGE_SHONA_LATIN', 'LANGUAGE_SHONA_LATIN_ZIMBABWE', 'LANGUAGE_SINDHI', 'LANGUAGE_SINDHI_ARABIC', 'LANGUAGE_SINDHI_DEVANAGARI', 'LANGUAGE_SINDHI_DEVANAGARI_INDIA', 'LANGUAGE_SINDHI_PAKISTAN', 'LANGUAGE_SINHALESE', 'LANGUAGE_SINHALESE_SRI_LANKA', 'LANGUAGE_SISWATI', 'LANGUAGE_SISWATI_ESWATINI', 'LANGUAGE_SISWATI_SOUTH_AFRICA', 'LANGUAGE_SLOVAK', 'LANGUAGE_SLOVAK_SLOVAKIA', 'LANGUAGE_SLOVENIAN', 'LANGUAGE_SLOVENIAN_SLOVENIA', 'LANGUAGE_SOGA', 'LANGUAGE_SOGA_UGANDA', 'LANGUAGE_SOMALI', 'LANGUAGE_SOMALI_DJIBOUTI', 'LANGUAGE_SOMALI_ETHIOPIA', 'LANGUAGE_SOMALI_KENYA', 'LANGUAGE_SOMALI_SOMALIA', 'LANGUAGE_SOUTH_NDEBELE', 'LANGUAGE_SOUTH_NDEBELE_SOUTH_AFRICA', 'LANGUAGE_SPANISH', 'LANGUAGE_SPANISH_ARGENTINA', 'LANGUAGE_SPANISH_BELIZE', 'LANGUAGE_SPANISH_BOLIVIA', 'LANGUAGE_SPANISH_BRAZIL', 'LANGUAGE_SPANISH_CHILE', 'LANGUAGE_SPANISH_COLOMBIA', 'LANGUAGE_SPANISH_COSTA_RICA', 'LANGUAGE_SPANISH_CUBA', 'LANGUAGE_SPANISH_DOMINICAN_REPUBLIC', 'LANGUAGE_SPANISH_ECUADOR', 'LANGUAGE_SPANISH_EL_SALVADOR', 'LANGUAGE_SPANISH_EQUATORIAL_GUINEA', 'LANGUAGE_SPANISH_GUATEMALA', 'LANGUAGE_SPANISH_HONDURAS', 'LANGUAGE_SPANISH_LATIN_AMERICA', 'LANGUAGE_SPANISH_MEXICAN', 'LANGUAGE_SPANISH_MODERN', 'LANGUAGE_SPANISH_NICARAGUA', 'LANGUAGE_SPANISH_PANAMA', 'LANGUAGE_SPANISH_PARAGUAY', 'LANGUAGE_SPANISH_PERU', 'LANGUAGE_SPANISH_PHILIPPINES', 'LANGUAGE_SPANISH_PUERTO_RICO', 'LANGUAGE_SPANISH_SPAIN', 'LANGUAGE_SPANISH_URUGUAY', 'LANGUAGE_SPANISH_US', 'LANGUAGE_SPANISH_VENEZUELA', 'LANGUAGE_STANDARD_MOROCCAN_TAMAZIGHT', 'LANGUAGE_STANDARD_MOROCCAN_TAMAZIGHT_TIFINAGH', 'LANGUAGE_STANDARD_MOROCCAN_TAMAZIGHT_TIFINAGH_MOROCCO', 'LANGUAGE_SUNDANESE', 'LANGUAGE_SWAHILI', 'LANGUAGE_SWAHILI_CONGO_DRC', 'LANGUAGE_SWAHILI_KENYA', 'LANGUAGE_SWAHILI_TANZANIA', 'LANGUAGE_SWAHILI_UGANDA', 'LANGUAGE_SWEDISH', 'LANGUAGE_SWEDISH_ALAND_ISLANDS', 'LANGUAGE_SWEDISH_FINLAND', 'LANGUAGE_SWEDISH_SWEDEN', 'LANGUAGE_SWISS_GERMAN', 'LANGUAGE_SWISS_GERMAN_LIECHTENSTEIN', 'LANGUAGE_SWISS_GERMAN_SWITZERLAND', 'LANGUAGE_SYRIAC', 'LANGUAGE_SYRIAC_SYRIA', 'LANGUAGE_TACHELHIT', 'LANGUAGE_TACHELHIT_LATIN', 'LANGUAGE_TACHELHIT_LATIN_MOROCCO', 'LANGUAGE_TACHELHIT_TIFINAGH', 'LANGUAGE_TACHELHIT_TIFINAGH_MOROCCO', 'LANGUAGE_TAGALOG', 'LANGUAGE_TAITA', 'LANGUAGE_TAITA_KENYA', 'LANGUAGE_TAJIK', 'LANGUAGE_TAJIK_CYRILLIC', 'LANGUAGE_TAJIK_CYRILLIC_TAJIKISTAN', 'LANGUAGE_TAMIL', 'LANGUAGE_TAMIL_INDIA', 'LANGUAGE_TAMIL_MALAYSIA', 'LANGUAGE_TAMIL_SINGAPORE', 'LANGUAGE_TAMIL_SRI_LANKA', 'LANGUAGE_TASAWAQ', 'LANGUAGE_TASAWAQ_NIGER', 'LANGUAGE_TATAR', 'LANGUAGE_TATAR_RUSSIA', 'LANGUAGE_TELUGU', 'LANGUAGE_TELUGU_INDIA', 'LANGUAGE_TESO', 'LANGUAGE_TESO_KENYA', 'LANGUAGE_TESO_UGANDA', 'LANGUAGE_THAI', 'LANGUAGE_THAI_THAILAND', 'LANGUAGE_TIBETAN', 'LANGUAGE_TIBETAN_CHINA', 'LANGUAGE_TIBETAN_INDIA', 'LANGUAGE_TIGRE', 'LANGUAGE_TIGRE_ERITREA', 'LANGUAGE_TIGRINYA', 'LANGUAGE_TIGRINYA_ERITREA', 'LANGUAGE_TIGRINYA_ETHIOPIA', 'LANGUAGE_TONGA', 'LANGUAGE_TONGA_TONGA', 'LANGUAGE_TSONGA', 'LANGUAGE_TSONGA_SOUTH_AFRICA', 'LANGUAGE_TURKISH', 'LANGUAGE_TURKISH_CYPRUS', 'LANGUAGE_TURKISH_TURKEY', 'LANGUAGE_TURKMEN', 'LANGUAGE_TURKMEN_TURKMENISTAN', 'LANGUAGE_TWI', 'LANGUAGE_UIGHUR', 'LANGUAGE_UIGHUR_CHINA', 'LANGUAGE_UKRAINIAN', 'LANGUAGE_UKRAINIAN_UKRAINE', 'LANGUAGE_UPPER_SORBIAN', 'LANGUAGE_UPPER_SORBIAN_GERMANY', 'LANGUAGE_URDU', 'LANGUAGE_URDU_INDIA', 'LANGUAGE_URDU_PAKISTAN', 'LANGUAGE_UZBEK', 'LANGUAGE_UZBEK_CYRILLIC', 'LANGUAGE_UZBEK_CYRILLIC_UZBEKISTAN', 'LANGUAGE_UZBEK_LATIN', 'LANGUAGE_UZBEK_LATIN_UZBEKISTAN', 'LANGUAGE_UZBEK_PERSO_ARABIC', 'LANGUAGE_UZBEK_PERSO_ARABIC_AFGHANISTAN', 'LANGUAGE_VAI', 'LANGUAGE_VAI_LATIN', 'LANGUAGE_VAI_LATIN_LIBERIA', 'LANGUAGE_VAI_VAI', 'LANGUAGE_VAI_VAI_LIBERIA', 'LANGUAGE_VALENCIAN', 'LANGUAGE_VENDA', 'LANGUAGE_VENDA_SOUTH_AFRICA', 'LANGUAGE_VIETNAMESE', 'LANGUAGE_VIETNAMESE_VIETNAM', 'LANGUAGE_VOLAPUK', 'LANGUAGE_VOLAPUK_WORLD', 'LANGUAGE_VUNJO', 'LANGUAGE_VUNJO_TANZANIA', 'LANGUAGE_WALSER', 'LANGUAGE_WALSER_SWITZERLAND', 'LANGUAGE_WELSH', 'LANGUAGE_WELSH_UK', 'LANGUAGE_WOLAYTTA', 'LANGUAGE_WOLAYTTA_ETHIOPIA', 'LANGUAGE_WOLOF', 'LANGUAGE_WOLOF_SENEGAL', 'LANGUAGE_XHOSA', 'LANGUAGE_XHOSA_SOUTH_AFRICA', 'LANGUAGE_YANGBEN', 'LANGUAGE_YANGBEN_CAMEROON', 'LANGUAGE_YI', 'LANGUAGE_YIDDISH', 'LANGUAGE_YIDDISH_WORLD', 'LANGUAGE_YI_CHINA', 'LANGUAGE_YORUBA', 'LANGUAGE_YORUBA_BENIN', 'LANGUAGE_YORUBA_NIGERIA', 'LANGUAGE_ZARMA', 'LANGUAGE_ZARMA_NIGER', 'LANGUAGE_ZHUANG', 'LANGUAGE_ZULU', 'LANGUAGE_ZULU_SOUTH_AFRICA']

{7: 'ZA', 14: 'AL', 22: 'DZ', 23: 'BH', 27: 'EG', 29: 'IQ', 31: 'JO', 32: 'KW', 33: 'LB', 34: 'LY', 36: 'MA', 37: 'OM', 39: 'QA', 40: 'SA', 43: 'SD', 44: 'SY', 45: 'TN', 46: 'AE', 48: 'YE', 49: 'AM', 58: 'AZ', 59: 'AZ', 61: 'AZ', 75: 'ES', 77: 'BY', 68: 'IN', 94: 'FR', 96: 'BG', 100: 'ES', 129: 'CN', 131: 'HK', 132: 'MO', 130: 'CN', 136: 'SG', 137: 'CN', 147: 'HR', 150: 'CZ', 152: 'DK', 161: 'NL', 163: 'BE', 175: 'GB', 179: 'AU', 184: 'BZ', 186: 'BW', 191: 'CA', 192: 'CB', 199: 'DK', 201: 'IE', 221: 'JM', 239: 'NZ', 247: 'PH', 258: 'ZA', 270: 'TT', 274: 'GB', 276: 'US', 282: 'ZW', 285: 'EE', 292: 'FO', 295: 'IR', 299: 'FI', 301: 'FR', 303: 'BE', 308: 'CA', 325: 'LU', 332: 'MC', 343: 'CH', 349: 'NL', 367: 'ES', 371: 'GE', 373: 'DE', 374: 'AT', 375: 'BE', 378: 'LI', 379: 'LU', 380: 'CH', 381: 'GR', 384: 'GL', 387: 'IN', 398: 'IL', 400: 'IN', 402: 'HU', 406: 'IS', 410: 'ID', 415: 'CA', 421: 'IE', 423: 'IT', 426: 'CH', 428: 'JP', 447: 'IN', 455: 'IN', 458: 'KZ', 143: 'GB', 469: 'KG', 475: 'KR', 494: 'LV', 501: 'LT', 516: 'MK', 526: 'MY', 527: 'IN', 529: 'BN', 530: 'MY', 532: 'MT', 538: 'NZ', 542: 'IN', 556: 'MN', 569: 'NP', 570: 'IN', 584: 'NO', 587: 'NO', 593: 'FR', 595: 'IN', 605: 'AF', 609: 'PL', 611: 'PT', 613: 'BR', 626: 'IN', 636: 'CH', 638: 'RO', 643: 'RU', 649: 'UA', 677: 'IN', 684: 'YU', 690: 'YU', 704: 'ZA', 722: 'SK', 724: 'SI', 735: 'ES', 736: 'AR', 738: 'BO', 740: 'CL', 741: 'CO', 742: 'CR', 744: 'DO', 745: 'EC', 746: 'SV', 748: 'GT', 749: 'HN', 751: 'MX', 752: 'NI', 753: 'PA', 754: 'PY', 755: 'PE', 757: 'PR', 759: 'UY', 760: 'US', 761: 'VE', 766: 'KE', 771: 'SE', 773: 'FI', 785: 'PH', 791: 'IN', 798: 'RU', 800: 'IN', 805: 'TH', 819: 'TR', 827: 'UA', 831: 'PK', 832: 'IN', 833: 'PK', 834: 'UZ', 835: 'UZ', 837: 'UZ', 849: 'VN', 857: 'GB', 863: 'ZA', 877: 'ZA', 2: 'GE', 3: 'ET', 19: 'ET', 51: 'IN', 57: 'BO', 21: 'SA', 73: 'RU', 169: 'BT', 83: 'IN', 84: 'VU', 98: 'MM', 460: 'KH', 145: 'FR', 283: 'ESPERANTO', 296: 'FJ', 385: 'PY', 391: 'NG', 412: 'US', 414: 'US', 420: 'US', 430: 'IN', 452: 'IN', 467: 'RW', 471: 'BI', 473: 'IN', 482: 'IQ', 490: 'LA', 492: 'VA', 496: 'CD', 524: 'MG', 534: 'IN', 555: 'MD', 568: 'NR', 597: 'ET', 631: 'BO', 672: 'WS', 673: 'CF', 679: 'GB', 698: 'HR', 699: 'ZA', 709: 'ZW', 712: 'PK', 717: 'IN', 719: 'SZ', 728: 'SB', 765: 'SD', 788: 'TJ', 807: 'CN', 812: 'ET', 815: 'TO', 817: 'MZ', 822: 'TM', 824: 'GH', 825: 'CN', 851: 'VOLAPUK', 861: 'SN', 868: 'IL', 871: 'NG', 876: 'CN'}

#
#
#
#
# Tags:

The class Layoutf(wxLayoutConstraints) presents a simplification
of the wxLayoutConstraints syntax. The name Layoutf is chosen
because of the similarity with C's printf function.

Quick Example::

    lc = Layoutf('t=t#1;l=r10#2;r!100;h%h50#1', (self, self.panel))

is equivalent to::

    lc = wx.LayoutContraints()
    lc.top.SameAs(self, wx.Top)
    lc.left.SameAs(self.panel, wx.Right, 10)
    lc.right.Absolute(100)
    lc.height.PercentOf(self, wx.Height, 50)

Usage:

You can give a constraint string to the Layoutf constructor,
or use the 'pack' method. The following are equivalent::

    lc = Layoutf('t=t#1;l=r#2;r!100;h%h50#1', (self, self.panel))

and::

    lc = Layoutf()
    lc.pack('t=t#1;l=r#2;r!100;h%h50#1', (self, self.panel))

Besides 'pack' there's also 'debug_pack' which does not set
constraints, but prints traditional wxLayoutConstraint calls to
stdout.

The calls to the Layoutf constructor and pack methods have
the following argument list:

`(constraint_string, objects_tuple)`

Constraint String syntax:

Constraint directives are separated by semi-colons. You
generally (always?) need four directives to completely describe a
subwindow's location.

A single directive has either of the following forms:

1. <own attribute><compare operation>[numerical argument]
   for example ``r!100`` -> lc.right.Absolute(100) )
   and ``w*`` -> lc.width.AsIs()

2. <own attribute><compare operation>[numerical argument]
   #<compare object nr.>
   for example ``t_10#2`` -> lc.top.Below(<second obj>, 10)

3. <own attribute><compare operation><compare attribute>
   [numerical argument]#<compare object nr.>
   for example ``w%h50#2`` -> lc.width.PercentOf(<second obj>, wx.Height, 50) and ``t=b#1`` -> lc.top.SameAs(<first obj>, wx.Bottom)

Which one you need is defined by the <compare operation>
type. The following take type 1 (no object to compare with):

* '!': 'Absolute', '?': 'Unconstrained', '*': 'AsIs'

These take type 2 (need to be compared with another object)

* '<': 'LeftOf', '>': 'RightOf', '^': 'Above', '_': 'Below'

These take type 3 (need to be compared to another object
attribute)

* '=': 'SameAs', '%': 'PercentOf'

For all types, the <own attribute> letter can be any of

* 't': 'top', 'l': 'left', 'b': 'bottom',
* 'r': 'right', 'h': 'height', 'w': 'width',
* 'x': 'centreX', 'y': 'centreY'

If the operation takes an (optional) numerical argument, place it
in [numerical argument].  For type 3 directives, the <compare
attribute> letter can be any of

* 't': 'wxTop', 'l': 'wxLeft', 'b': 'wx.Bottom'
* 'r': 'wxRight', 'h': 'wxHeight', 'w': 'wx.Width',
* 'x': 'wxCentreX', 'y': 'wx.CentreY'

Note that these are the same letters as used for <own attribute>,
so you'll only need to remember one set. Finally, the object
whose attribute is referred to, is specified by #<compare object
nr>, where <compare object nr> is the 1-based (stupid, I know,
but I've gotten used to it) index of the object in the
objects_tuple argument.

Bugs:

Not entirely happy about the logic in the order of arguments
after the <compare operation> character.

Not all wxLayoutConstraint methods are included in the
syntax. However, the type 3 directives are generally the most
used. Further excuse: wxWindows layout constraints are at the
time of this writing not documented.

{'t': 'top', 'l': 'left', 'b': 'bottom', 'r': 'right', 'h': 'height', 'w': 'width', 'x': 'centreX', 'y': 'centreY'}

{'t': 'wx.Top', 'l': 'wx.Left', 'b': 'wx.Bottom', 'r': 'wx.Right', 'h': 'wx.Height', 'w': 'wx.Width', 'x': 'wx.CentreX', 'y': 'wx.CentreY'}

{'=': 'SameAs', '%': 'PercentOf', '<': 'LeftOf', '>': 'RightOf', '^': 'Above', '_': 'Below', '!': 'Absolute', '?': 'Unconstrained', '*': 'AsIs'}

MessagePanel is a simple panel class for displaying a message, very
much like how wx.MessageDialog works, including the icon flags.

# Name:        wx.lib.msgpanel
# Purpose:     The MessagePanel class  (Note: this class used to live
#              in the demo's Main module.)
#
#
# Created:     19-Oct-2009

# Name:         multisash
# Purpose:      Multi Sash control
#
# Author:       Gerrit van Dyk
#
# Created:      2002/11/20
# Version:      0.1
#
#
#
# o wxMultiSash -> MultiSash
# o wxMultiSplit -> MultiSplit
# o wxMultiViewLeaf -> MultiViewLeaf
#

Easy generation of new events classes and binder objects.

This module contains two functions which makes the generation of custom wxPython events
particularly easy.

Usage
=====

    import wx
    import time
    import threading

    import wx.lib.newevent as NE

    MooEvent, EVT_MOO = NE.NewEvent()
    GooEvent, EVT_GOO = NE.NewCommandEvent()

    DELAY = 0.7

    def evt_thr(win):
        time.sleep(DELAY)
        wx.PostEvent(win, MooEvent(moo=1))

    def cmd_thr(win, id):
        wx.PostEvent(win, GooEvent(id, goo=id))

    ID_CMD1 = wx.NewIdRef()
    ID_CMD2 = wx.NewIdRef()

    class Frame(wx.Frame):
            wx.Frame.__init__(self, None, -1, "MOO")
            self.Bind(EVT_MOO, self.on_moo)
            b = wx.Button(self, -1, "Generate MOO")
            sizer.Add(b, 1, wx.EXPAND)
            b.Bind(wx.EVT_BUTTON, self.on_evt_click)
            b = wx.Button(self, ID_CMD1, "Generate GOO with %d" % ID_CMD1)
            b.Bind(wx.EVT_BUTTON, self.on_cmd_click)
            b = wx.Button(self, ID_CMD2, "Generate GOO with %d" % ID_CMD2)

            self.Bind(EVT_GOO, self.on_cmd1, id=ID_CMD1)
            self.Bind(EVT_GOO, self.on_cmd2, id=ID_CMD2)

            self.SetAutoLayout(True)
            sizer.Fit(self)

        def on_evt_click(self, e):
            t = threading.Thread(target=evt_thr, args=(self, ))
            t.setDaemon(True)
            t.start()

        def on_cmd_click(self, e):
            t = threading.Thread(target=cmd_thr, args=(self, e.GetId()))
            t.start()

        def show(self, msg, title):
            dlg = wx.MessageDialog(self, msg, title, wx.OK)
            dlg.ShowModal()

        def on_moo(self, e):
            self.show("MOO = %s" % e.moo, "Got Moo")

        def on_cmd1(self, e):
            self.show("goo = %s" % e.goo, "Got Goo (cmd1)")

        def on_cmd2(self, e):
            self.show("goo = %s" % e.goo, "Got Goo (cmd2)")

    f = Frame()
    f.Show(True)

# Name:        newevent.py
# Purpose:     Easy generation of new events classes and binder objects.
#
# Author:      Miki Tebeka <miki.tebeka@gmail.com>
#
#

Generates a new `(command_event, binder)` tuple.

::

    MooCmdEvent, EVT_MOO = NewCommandEvent()

A simple dialog that can prompt for values for any arbitrary set of name/value
pairs, where the fields are defined by a list of info passed to the
constructor. A dictionary of initial values can also be passed. Each item in
the fields list is a tuple of 3 items, which are:

    * a string to be used for the attribute name for storing the value
    * a string to be used for the label
    * None, or a dictionary of kwargs to be passed to the wx.TextCtrl ctor

# Name:        wx.lib.nvdlg
# Purpose:     Dialog for editing name/value pairs
#
#
# Created:     30-Nov-2009

This validator is used to transfer values to/from the widgets and
attributes of the dialog.

Clone() -> Object

All validator classes must implement the Clone() function, which
returns an identical copy of itself.

TransferFromWindow() -> bool

This overridable function is called when the value in the window must
be transferred to the validator.

TransferToWindow() -> bool

This overridable function is called when the value associated with the
validator must be transferred to the window.

Validate(parent) -> bool

This overridable function is called when the value in the associated
window must be validated.

__init__(self, parent, id=-1, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, fields=[], initialValues=None, captionTitle="", captionDescr="")

# Name:        wx.lib.pdfwin
# Purpose:     A class that allows the use of the Acrobat PDF reader
#              ActiveX control
#
#
# Created:     22-March-2004

Editra Control Library: PlateButton

The PlateButton is a custom owner drawn flat button, that in many ways emulates
the buttons found the bookmark bar of the Safari browser. It can be used as a
drop in replacement for wx.Button/wx.BitmapButton under most circumstances. It
also offers a wide range of options for customizing its appearance, a
description of each of the main style settings is listed below.

Main Button Styles:
Any combination of the following values may be passed to the constructor's style
keyword parameter.

PB_STYLE_DEFAULT:
Creates a flat label button with rounded corners, the highlight for mouse over
and press states is based off of the highlight color from the systems current
theme.

PB_STYLE_GRADIENT:
The highlight and press states are drawn with gradient using the current
highlight color.

PB_STYLE_SQUARE:
Instead of the default rounded shape use a rectangular shaped button with
square edges.

PB_STYLE_NOBG:
This style only has an effect on Windows but does not cause harm to use on the
platforms. It should only be used when the control is shown on a panel or other
window that has a non solid color for a background. i.e a gradient or image is
painted on the background of the parent window. If used on a background with
a solid color it may cause the control to loose its transparent appearance.

PB_STYLE_DROPARROW:
Add a drop button arrow to the button that will send a separate event when
clicked on.

Other attributes can be configured after the control has been created. The
settings that are currently available are as follows:

  - SetBitmap: Change/Add the bitmap at any time and the control will resize and
               refresh to display it.
  - SetLabelColor: Explicitly set text colors
  - SetMenu: Set the button to have a popupmenu. When a menu is set a small drop
             arrow will be drawn on the button that can then be clicked to show
             a menu.
  - SetPressColor: Use a custom highlight color

Overridden Methods Inherited from PyControl:

  - SetFont: Changing the font is one way to set the size of the button, by
             default the control will inherit its font from its parent.

  - SetWindowVariant: Setting the window variant will cause the control to
                      resize to the corresponding variant size. However if the
                      button is using a bitmap the bitmap will remain unchanged
                      and only the font will be adjusted.

Requirements:
  - python2.4 or higher
  - wxPython2.8 or higher

###############################################################################
# Name: platebtn.py                                                           #
# Purpose: PlateButton is a flat label button with support for bitmaps and    #
#          drop menu.                                                         #
# Author: Cody Precord <cprecord@editra.org>                                  #
# Copyright: (c) 2007 Cody Precord <staff@editra.org>                         #
# Licence: wxWindows Licence                                                  #
# Tags: phoenix-port

PlateButton is a custom type of flat button with support for
displaying bitmaps and having an attached dropdown menu.

Create a PlateButton

:keyword string `label`: Buttons label text
:keyword wx.Bitmap `bmp`: Buttons bitmap
:keyword `style`: Button style

__init__(self, parent, id=wx.ID_ANY, label='', bmp=None, pos=wx.DefaultPosition, size=wx.DefaultSize, style=PB_STYLE_DEFAULT, name=wx.ButtonNameStr)

Calculate the best size of the button

:return: :class:`wx.Size`

Get the brush for drawing the background of the button

:return: :class:`wx.Brush`

..note::
    used internally when on gtk

Get the bitmap of the disable state

:return: :class:`wx.Bitmap` or None

Return the menu associated with this button or None if no
menu is associated with it.

Get the current state of the button

:return: int

.. seeAlso::
    PLATE_NORMAL, PLATE_HIGHLIGHT, PLATE_PRESSED

Trap the erase event to keep the background transparent
on windows.

:param `evt`: wx.EVT_ERASE_BACKGROUND

Execute a single button press action when the Return key is pressed
and this control has the focus.

:param `evt`: wx.EVT_KEY_UP

Set the visual state back to normal when focus is lost
unless the control is currently in a pressed state.

Sets the pressed state and depending on the click position will
show the popup menu if one has been set.

Post a button event if the control was previously in a
pressed state.

:param `evt`: :class:`wx.MouseEvent`

Refresh the control to a proper state after the menu has been
dismissed.

:param `evt`: wx.EVT_MENU_CLOSE

Set the bitmap displayed in the button

:param `bmp`: :class:`wx.Bitmap`

Set the bitmap for the disabled state

Set the label of the button

:param string `label`: label string

Set the color of the label. The optimal label color is usually
automatically selected depending on the button color. In some
cases the colors that are chosen may not be optimal.

The normal state must be specified, if the other two params are left
Null they will be automatically guessed based on the normal color. To
prevent this automatic color choices from happening either specify
a color or None for the other params.

:param wx.Colour `normal`: Label color for normal state (:class:`wx.Colour`)
:keyword wx.Colour `hlight`: Color for when mouse is hovering over

Set the menu that can be shown when clicking on the
drop arrow of the button.

:param wx.Menu `menu`: :class:`wx.Menu` to use as a PopupMenu

.. note::
    Arrow is not drawn unless a menu is set

Set the color used for highlighting the pressed state

:param wx.Colour `color`: :class:`wx.Colour`

.. note::
    also resets all text colours as necessary

Sets the window style bytes, the updates take place
immediately no need to call refresh afterwards.

:param `style`: bitmask of PB_STYLE_* values

Overridden base class virtual. If the parent has non-default

# Name:         popup
# Purpose:      Generic popup control
#
#
# 11/24/2007 - Cody Precord
#
# o Use RendererNative to draw button
#
#
#
#
# o wxPopupDialog -> PopupDialog
# o wxPopupControl -> PopupControl
#

Control(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr)
Control()

This is the base class for a control or "widget".

Enable(enable=True) -> bool

# Name:         printout.py
# Purpose:      preview and printing class -> table/grid printing
#
#
# Created:
# Version       0.75
# Date:         May 15, 2002
# Release Notes

OutTextPageWidth(self, textout, y_out, align, indent, txtdraw = True)

__init__(self, parent, grid, format = [], total_col = None, total_row = None)

SetFooter(self, text = "", type = None, font=None, align = None, indent = None, colour = None, size = None)

SetHeader(self, text = "", type = "Text", font=None, align = None, indent = None, colour = None, size = None)

Printout(title="Printout")

This class encapsulates the functionality of printing out an
application document.

OnBeginDocument(startPage, endPage) -> bool

Called by the framework at the start of document printing.

OnBeginPrinting()

Called by the framework at the start of printing.

OnEndDocument()

Called by the framework at the end of document printing.

OnPreparePrinting()

Called once by the framework before any other demands are made of the
wxPrintout object.

A simple gauge with a label that is suitable for use in places like a
status bar.  It can be used in either an automatic indeterminant
(pulse) mode or in determinante mode where the programmer will need to
update the position of the progress bar.  The indicator can be set to
hide itself when it is not active.

# Name:        wx.lib.progressindicator
# Purpose:
#
#
# Created:     22-Oct-2009

For determinante mode (non-pulse) set the max value that the gauge can
be set to. Defaults to 100.

For determinante mode (non-pulse) update the progress indicator to the
given value. For example, if the job is 45% done then pass 45 to this
method (as long as the range is still set to 100.)

# Name:         pydocview.py
# Purpose:      Python extensions to the wxWindows docview framework
#
# Author:       Peter Yared, Morgan Hua, Matt Fryer
#
# Copyright:    (c) 2003-2006 ActiveGrid, Inc.

Initializes the FileDropTarget class with the active docManager and the docFrame.

Called when files are dropped in the drop target and tells the docManager to open
the files.

Opens an AboutDialog.  Shared by DocMDIParentFrame and DocSDIFrame.

About Dialog Service that installs under the Help menu to show the properties of the current application.

A ChildDocTemplate is a DocTemplate subclass that enables the creation of ChildDocuments
that represents a portion of a Document.  The child document is managed by the parent document,
so it will be prompted to close if its parent is closed, etc.  Child Documents are useful
when there are complicated  Views of a Document and users will need to tunnel into the View.

__init__(self, manager, description, filter, dir, ext, docTypeName, viewTypeName, docType, viewType, flags=wx.lib.docview.TEMPLATE_INVISIBLE, icon=None)

Called when a ChildDocument is to be created and does the minimum such that the
ChildDocument looks like a real Document to the framework.

CreateDocument(self, path, flags, data=None, parentDocument=None)

A ChildDocument is a document that represents a portion of a Document.  The child
document is managed by the parent document, so it will be prompted to close if its
parent is closed, etc.  Child Documents are useful when there are complicated
Views of a Document and users will need to tunnel into the View.

Called when the ChildDocument is opened and does the minimum such that the

Called when the ChildDocument is saved and does the minimum such that the

The DocApp class serves as the base class for pydocview applications and offers
functionality such as services, creation of SDI and MDI frames, show tips,
and a splash screen.

Creates a child window of a document that edits an object.  The child window
is managed by the parent document frame, so it will be prompted to close if its

CreateChildDocument(self, parentDocument, documentType, objectToEdit, path='')

Called by the DocManager to create and return a new Frame for a Document.
Chooses whether to create an MDIChildFrame or SDI Frame based on the
DocManager's flags.

CreateDocumentFrame(self, view, doc, flags, id = -1, title = "", pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.DEFAULT_FRAME_STYLE)

CreateMDIDocumentFrame(self, doc, view, id=-1, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE)

CreateSDIDocumentFrame(self, doc, view, id=-1, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE)

CreateTabbedDocumentFrame(self, doc, view, id=-1, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE)

Open any files specified in the given command line argument passed in via shared memory

Utility method that finds the Edit menu within the menubar of a frame.

Returns the instance of a particular type of service that has been installed
into the DocApp.  For example, "wx.GetApp().GetService(pydocview.OptionsService)"
returns the instance of the OptionsService that is running within the DocApp.

Returns the DocService instances that have been installed into the DocApp.

Returns True if the application is in single instance mode.  Used to determine if multiple instances of the application is allowed to launch.

Returns True if Windows MDI should use folder tabs instead of child windows.

MacOpenFile(fileName)

Called in response of an "open-document" Apple event.

Called when an MDI Child Frame is closed.  Calls SaveMDIDocumentFrameMaximizedState to
remember whether the MDI Frame is maximized so that it can be restored on open.

Called when the MDI Parent Frame is closed.  Remembers whether the MDI Parent Frame is
maximized.

Called when the DocApp is exited, enables the installed DocServices to exit
and saves the DocManager's file history.

Called to open files that have been passed to the application from the
command line.

Enables services to process an event before the main window has a chance to
process the window.

Enables services to process a UI event before the main window has a chance
to process the window.

Remember in the config whether the MDI Frame is maximized so that it can be restored
on open.

Sets the document manager associated with the DocApp and loads the
DocApp's file history into the document manager.

Set to True if Windows MDI should use folder tabs instead of child windows.

Shows a splash window with the given image.  Input parameter 'image' can either be a wx.Bitmap or a filename.

Shows the tip window, generally this is called when an application starts.
A wx.TipProvider must be passed.

Class with common code used by DocMDIParentFrame, DocTabbedParentFrame, and
DocSDIFrame.

Creates the default MenuBar.  Contains File, Edit, View, Tools, and Help menus.

Returns the document manager associated with the DocMDIParentFrame.

The wxDocMDIChildFrame class provides a default frame for displaying
frames.

The class is part of the document/view framework supported by wxWindows,
and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
classes.

The DocMDIParentFrame is the primary frame which the DocApp uses to host MDI child windows.  It offers
features such as a default menubar, toolbar, and status bar, and a mechanism to manage embedded windows
on the edges of the DocMDIParentFrame.

Initializes the DocMDIParentFrame with the default menubar, toolbar, and status bar.  Use the
optional embeddedWindows parameter with the embedded window constants to create embedded
windows around the edges of the DocMDIParentFrame.

__init__(self, docManager, parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="DocMDIFrame", embeddedWindows=0, minSize=20)

Called when the DocMDIParentFrame is closed.  Remembers the frame size.

Called when the DocMDIParentFrame is resized and lays out the MDI client window.

Class with common code used by DocMDIParentFrame and DocTabbedParentFrame.

Create the specified embedded windows around the edges of the frame.

Returns the instance of the embedded window specified by the embedded window location constant.

Hides the embedded window specified by the embedded window location constant.

Shows or hides the embedded window specified by the embedded window location constant.

A service that implements an options menu item and an options dialog with
notebook tabs.  New tabs can be added by other services by calling the
"AddOptionsPanel" method.

Initializes the options service with the option of suppressing the default
general options pane that is included with the options service by setting
showGeneralOptions to False.  It allowModeChanges is set to False, the
default general options pane will allow users to change the document
interface mode between SDI and MDI modes.

__init__(self, showGeneralOptions=True, supportedModes=wx.lib.docview.DOC_SDI & wx.lib.docview.DOC_MDI)

Clears all of the options panels that have been added into the
options dialog.

Return the modes supported by the application.  Use docview.DOC_SDI and
docview.DOC_MDI flags to check if SDI and/or MDI modes are supported.

InstallControls(self, frame, menuBar=None, toolBar=None, statusBar=None, document=None)

Shows the options dialog, called when the "Options" menu item is selected.

Sets the modes supported by the application.  Use docview.DOC_SDI and
docview.DOC_MDI flags to set if SDI and/or MDI modes are supported.

The DocSDIFrame host DocManager Document windows.  It offers features such as a default menubar,
toolbar, and status bar.

Initializes the DocSDIFrame with the default menubar, toolbar, and status bar.

__init__(self, doc, view, parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE, name="DocSDIFrame")

Called when the window is saved.  Enables services to help close the frame.

An abstract class used to add reusable services to a docview application.

Utility method used to find the position of a menu item so that services can
easily find where to insert a menu item in InstallControls.

Called by WindowMenuService to get views for services that don't
have dedicated documents such as the Outline Service.

Called to install controls into the menubar and toolbar of a SDI or MDI window.  Override this method for a particular service.

Called when the a docview frame is being closed.  Override this method
so a service can either do cleanup or veto the frame being closed by
returning false.

Called when the the docview application is being closed.  Override this method

Processes an event before the main window has a chance to process the window.
Override this method for a particular service.

Processes a UI event before the main window has a chance to process the window.

Dummy method since the icon of tabbed frames are managed by the notebook.

The DocTabbedParentFrame class provides a default top-level frame for
used for MDI parent frames that use a tabbed interface.

It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate
classes.

__init__(self, docManager, frame, id, title, pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.DEFAULT_FRAME_STYLE, name = "DocTabbedParentFrame", embeddedWindows = 0, minSize=20)

Returns the active notebook page, which to the framework is treated as
a document frame.

Handles middle clicks for the notebook, closing the document whose tab was

Handles right clicks for the notebook, enabling users to either close
a tab or select from the available documents if the user clicks on the
notebook's white space.

Called when the frame is resized and lays out the client window.

DocTabbedParentFrame(wx.Frame, DocFrameMixIn, DocMDIParentFrameMixIn)

Dialog that shows the properties of a file.  Invoked by the PropertiesService.

Service that installs under the File menu to show the properties of the file associated
with the current document.

Adds a custom event handlers for the PropertyService.  A custom event handler enables
a different dialog to be provided for a particular file.

Simple version of textwrap.  textwrap.fill() unfortunately chops lines at spaces
and creates odd word boundaries.  Instead, we will chop the path without regard to
spaces, but pay attention to path delimiters.

A general options panel that is used in the OptionDialog to configure the
generic properties of a pydocview application, such as "show tips at startup"
and whether to use SDI or MDI for the application.

Initializes the panel by adding an "Options" folder tab to the parent notebook and
populating the panel with the generic properties of a pydocview application.

Updates the config based on the selections in the options panel.

A default options dialog used by the OptionsService that hosts a notebook
tab of options panels.

Initializes the options dialog with a notebook page that contains new
instances of the passed optionsPanelClasses.

wxBug: On Windows XP when using a multiline notebook the default page doesn't get
drawn, but it works when using a single line notebook.

Returns the document manager passed to the OptionsDialog constructor.

Calls the OnOK method of all of the OptionDialog's embedded panels

Sizer()

wxSizer is the abstract base class used for laying out subwindows in a
window.

Add(window, flags) -> SizerItem
Add(window, proportion=0, flag=0, border=0, userData=None) -> SizerItem
Add(sizer, flags) -> SizerItem
Add(sizer, proportion=0, flag=0, border=0, userData=None) -> SizerItem
Add(width, height, proportion=0, flag=0, border=0, userData=None) -> SizerItem
Add(width, height, flags) -> SizerItem
Add(item) -> SizerItem
Add(size, proportion=0, flag=0, border=0, /Transfer/=None) -> SizerItem
Add(size, flags) -> SizerItem

Appends a child to the sizer.

Add(self, item, option=0, flag=0, border=0,  row=-1, col=-1, rowspan=1, colspan=1,  pos=None, size=None, )

AddSpacer(size) -> SizerItem

This base function adds non-stretchable space to both the horizontal
and vertical orientation of the sizer.

AddSpacer(self, width, height, option=0, flag=0, border=0, row=-1, col=-1, rowspan=1, colspan=1, pos=None, size=None, )

CalcMin() -> Size

This method is abstract and has to be overwritten by any derived
class.

RecalcSizes()

This is a deprecated version of RepositionChildren()

The WindowMenuService is a service that implements a standard Window menu that is used
by the DocSDIFrame.  The MDIFrame automatically includes a Window menu and does not use
the WindowMenuService.

Builds the Window menu and adds menu items for all of the open documents in the DocManager.

Called when the "Window/Select More Windows..." menu item is selected and enables user to
select from the Frames that do not in the Window list.  Useful when there are more than
10 open frames in the application.

Called when the Window menu item representing a Frame is selected and brings the selected
Frame to the front of the desktop.

A pure-Python Sizer that lays out items in a grid similar to
wx.FlexGridSizer but item position is not implicit but explicitly
specified by row and col, and row/col spanning is supported.

Adapted from code by Niki Spahiev.

NOTE: There is now a C++ version of this class that has been wrapped
as wx.GridBagSizer.  It is quicker and more capable so you are
encouraged to switch.

# Name:        wx.lib.rcsizer
# Purpose:     RowColSizer:
#
# Author:      Robin Dunn, adapted from code by Niki Spahiev
#
# Created:     26-Feb-2002
# 12/10/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o There appears to be a prob with the wx.Sizer.GetSize() method.
#
# 12/23/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o wx.Sizer.GetSize() method working right now.
#

Reparents a given widget into a specialized panel that provides a resize
handle for the widget. When the user drags the resize handle the widget is
resized accordingly, and an event is sent to notify parents that they should
recalculate their layout.

# Name:        wx.lib.resizewidget
# Purpose:     Adds a resize handle to any widget, with support for
#              notifying parents when layout needs done.
#
#
# Created:     12-June-2008

handle for the widget.

:param `args`: arguments will be passed on to the wx.Panel
:param `kw`: key words will be passed on to the wx.Panel

Enable resizing.

:param boolean `enable`: enable or disable resizing.

Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`ResizeWidget`.

:param `evt`: a :class:`MouseEvent` event to be processed.

Handles the ``wx.EVT_LEFT_UP`` event for :class:`ResizeWidget`.

Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`ResizeWidget`.

Handles the ``wx.EVT_MOTION`` event for :class:`ResizeWidget`.

Handles the ``wx.EVT_PAINT`` event for :class:`ResizeWidget`.

:param `evt`: a :class:`PaintEvent` event to be processed.

Handles the ``wx.EVT_SIZE`` event for :class:`ResizeWidget`.

:param `evt`: a :class:`wx.SizeEvent` event to be processed.

Set the colors of handles.

:param `pen`: the pen color
:param `fill`: the fill color
:param `fill2`: the secondary fill color

Set the dimensions of handles.

:param `thickness`: the thickness of the handles
:param `length`: the length of the handles

:class:`~lib.scrolledpanel.ScrolledPanel` extends :class:`ScrolledWindow`, adding all
the necessary bits to set up scroll handling for you.

:class:`ScrolledPanel` fills a "hole" in the implementation of
:class:`ScrolledWindow`, providing automatic scrollbar and scrolling
behavior and the tab traversal management that :class:`ScrolledWindow`
lacks.  This code was based on the original demo code showing how
to do this, but is now available for general use as a proper class
(and the demo is now converted to just use it.)

It is assumed that the :class:`ScrolledPanel` will have a sizer, as it is
used to calculate the minimal virtual size of the panel and etc.

Usage
=====

    text = '''
    ScrolledPanel extends wx.ScrolledWindow, adding all
    the necessary bits to set up scroll handling for you.

    Here are three fixed size examples of its use. The
    demo panel for this sample is also using it -- the
    wx.StaticLine below is intentionally made too long so a scrollbar will be
    activated.'''

    import wx
    import wx.lib.scrolledpanel as scrolled

    class TestPanel(scrolled.ScrolledPanel):

            scrolled.ScrolledPanel.__init__(self, parent, -1)

            vbox = wx.BoxSizer(wx.VERTICAL)

            desc = wx.StaticText(self, -1, text)

            desc.SetForegroundColour("Blue")
            vbox.Add(desc, 0, wx.ALIGN_LEFT | wx.ALL, 5)
            vbox.Add(wx.StaticLine(self, -1, size=(1024, -1)), 0, wx.ALL, 5)
            vbox.Add((20, 20))

            self.SetSizer(vbox)
            self.SetupScrolling()

    frame = wx.Frame(None, wx.ID_ANY)
    fa = TestPanel(frame)

# Name:         scrolledpanel.py
# Created:      03/21/2003
# Copyright:    (c) 2003 by Will Sadkin
# 12/11/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
#
#
# o wxScrolledPanel -> ScrolledPanel
#
# 21 Dec 2012 - Andrea Gavana (andrea.gavana@gmail.com)
#
#

behavior and the tab traversal management that :class:`ScrolledWindow` lacks.

:param integer `style`: the underlying :class:`wx.ScrolledWindow` style;
:param string `name`: the scrolled panel name.

__init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.TAB_TRAVERSAL, name="scrolledpanel")

If the child window that gets the focus is not fully visible,
this handler will try to scroll enough to see it.

:param `evt`: a :class:`ChildFocusEvent` event to be processed.

Scroll the panel so that the specified child window is in view.

:param wx.Window `child`: any :class:`wx.Window` - derived control.

.. note:: This method looks redundant if `evt.Skip()` is
   called as well - the base :class:`ScrolledWindow` widget now seems
   to be doing the same thing anyway.

This function sets up the event handling necessary to handle
scrolling properly. It should be called within the `__init__`
function of any class that is derived from :class:`ScrolledPanel`,
once the controls on the panel have been constructed and
thus the size of the scrolling area can be determined.

:param bool `scroll_x`: ``True`` to allow horizontal scrolling, ``False`` otherwise;
:param bool `scroll_y`: ``True`` to allow vertical scrolling, ``False`` otherwise;
:param int `rate_x`: the horizontal scroll increment;
:param int `rate_y`: the vertical scroll increment;
:param bool `scrollToTop`: ``True`` to scroll all way to the top, ``False`` otherwise;
:param bool `scrollIntoView`: ``True`` to scroll a focused child into view, ``False`` otherwise.

SetupScrolling(self, scroll_x=True, scroll_y=True, rate_x=20, rate_y=20, scrollToTop=True, scrollIntoView=True)

# sheet.py
# CSheet - A wxPython spreadsheet class.
# This is free software.  Feel free to adapt it as you like.
# Author: Mark F. Russo (russomf@hotmail.com) 2002/01/31
#
#

Fetch the value from the table and prepare edit control to begin editing.
Set the focus to the edit control.  Must Override.

Create a new object which is the copy of this one. Must Override. 

Create the actual edit control.  Must derive from wxControl.
Must Override

Final cleanup

NOTE: There is no need to everride this if you don't need
to do something out of the ordinary.

Commit editing the current cell. Returns True if the value has changed.
If necessary, the control may be destroyed. Must Override.

Return True to allow the given key to start editing.  The base class
version only checks that the event has no modifiers.  F2 is special
and will always start the editor.

Draws the part of the cell not occupied by the edit control.  The
base class version just fills it with background colour from the
attribute.

Reset the value in the control back to its starting value. Must Override. 

Show or hide the edit control.  Use the attr (if not None)
to set colors or fonts for the control.

If the editor is enabled by clicking on the cell, this method will be
called to allow the editor to simulate the click on the control.

If the editor is enabled by pressing keys on the grid, this will be
called to let the editor react to that first key.

Grid()
Grid(parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.WANTS_CHARS, name=GridNameStr)

wxGrid and its related classes are used for displaying and editing
tabular data.

Override left-click behavior to prevent left-click edit initiation 

Track which cells are selected so that copy/paste behavior can be implemented 

Paste the contents of the clipboard into the currently selected cells 

The sized controls default HIG compliant sizers under the hood and provides
a simple interface for customizing those sizers.

The following sized controls exist:

:class:`SizedFrame`
:class:`SizedDialog`
:class:`SizedPanel`
:class:`SizedScrolledPanel`
:class `SizedStaticBox`

The sized controls allow you to create sizer based layouts without having to
code the sizers by hand, but still provide you the manual detailed control of
the sizer and sizer items if necessary.

Usage
=====

    import wx

    frame = sc.SizedFrame(None, -1, "A sized frame")

# Name:        sized_controls.py
# Purpose:     Implements default, HIG-compliant sizers under the hood
#              and provides a simple interface for customizing those sizers.
#
#
# Created:     26-May-2006
# Copyright:   (c) 2006 Kevin Ollivier
#
#

A sized dialog

Controls added to its content pane will automatically be added to
the panes sizer.

`self` in the following sample is a :class:`wx.SizedDialog` instance.

    pane = self.GetContentsPane()

    t1 = wx.TextCtrl(pane, wx.ID_ANY)

A sized frame.

`self` in the following sample is a :class:`wx.SizedFrame` instance

A sized panel.

Controls added to it will automatically be added to its sizer.

`self` in the following sample is a :class:`wx.SizedPanel` instance.

    self.SetSizerType("horizontal")

    b1 = wx.Button(self, wx.ID_ANY)
    t1 = wx.TextCtrl(self, -1)

This extends the default wx.Window behavior to also add the child
to its parent's sizer, if one exists, and set default properties.
When an entire UI layout is managed via Sizers, this helps reduce
the amount of sizer boilerplate code that needs to be written.

:param `child`: child (window or another sizer) to be added to sizer.
:type `child`: :class:`wx.Window` or :class:`wx.Sizer`

Sets the sizer type and automatically re-assign any children
to it.

:param string `type`: sizer type, valid values are "horizontal", "vertical",
 "form", and "grid";
:param dict `options`: dictionary of options depending on type.

A sized scrolled panel.

`self` in the following sample is a :class:`wx.SizedScrolledPanel` instance.

Called automatically by wx, should not be called from user code.

StaticBox()
StaticBox(parent, id=ID_ANY, label=EmptyString, pos=DefaultPosition, size=DefaultSize, style=0, name=StaticBoxNameStr)

A static box is a rectangle drawn around other windows to denote a
logical grouping of items.

Default panel border is set to 0 by default as the child control
will set their borders.

Set horizontal grow proportion.

:param int `proportion`: proportion to use

Sets a sizer property

Sample usages::

    control.SetSizerProp('expand', True)

:param string `prop`: valid strings are "proportion", "hgrow", "vgrow",
 "align", "halign", "valign", "border", "minsize" and "expand"
:param `value`: corresponding value for the prop

Allows to set multiple sizer properties

    control.SetSizerProps(expand=True, proportion=1)

    control.SetSizerProps(expand=True, valign='center', border=(['top',
                                                                 'bottom'], 5))

    control.SetSizerProps({'growable_row': (1, 1),
                           'growable_col': (0, 1),})

:param dict `props`: a dictionary of prop name + value
:param `kwargs`: keywords can be used for properties, e.g. expand=True

Set vertical grow proportion.

This module provides a class designed to be mixed with wx.App to form a
derived class which is able to auto-self-update the application when new
versions are released. It is built upon the Esky package, available in PyPi at
http://pypi.python.org/pypi/esky.

In order for the software update to work the application must be put into an
esky bundle using the bdist_esky distutils command, which in turn will use
py2app, py2exe or etc. to freeze the actual application. See Esky's docs for
more details. The code in this module will only have effect if the application
is frozen, and is silently ignored otherwise.

# Name:        wx.lib.softwareupdate
# Purpose:     A mixin class using Esky that allows a frozen application
#              to update itself when new versions of the software become
#              available.
#
#
# Created:     1-Aug-2011
# Copyright:   (c) 2011-2020 by Total Control Software
#
# Tags:        py3-port??

Mix this class with :class:`App` and call :meth:`InitForUpdates` from the derived class'
OnInit method. Be sure that the :class:`App` has set a display name
(self.SetAppDisplayName) as that value will be used in the update dialogs.

If it has been `frequencyInDays` since the last auto-check then check if
a software update is available and prompt the user to download and
install it. This can be called after a application has started up, and
if there is no update available the user will not be bothered.

AutoCheckForUpdate(self, frequencyInDays, parentWindow=None, cfg=None)

This method will check for the availability of a new update, and will
prompt the user with details if there is one there. By default it will
also tell the user if there is not a new update, but you can pass
silentUnlessUpdate=True to not bother the user if there isn't a new
update available.

This method should be called from an event handler for a "Check for
updates" menu item, or something similar. The actual update check
will be run in a background thread and this function will return
immediately after starting the thread so the application is not
blocked if there is network communication problems. A callback to the
GUI thread will be made to do the update or report problems as
needed.

CheckForUpdate(self, silentUnlessUpdate=False, parentWindow=None, cfg=None)

Set up the Esky object for doing software updates. Passing either the
base URL (with a trailing '/') for the location of the update
packages, or an instance of a class derived from the
esky.finder.VersionFinder class is required. A custom VersionFinder
can be used to find and fetch the newer version of the software in
some other way, if desired.

Call this method from the app's OnInit method.

Open the URL url, which can be either a string or a Request object.

*data* must be an object specifying additional data to be sent to
the server, or None if no such data is needed.  See Request for
details.

urllib.request module uses HTTP/1.1 and includes a "Connection:close"
header in its HTTP requests.

The optional *timeout* parameter specifies a timeout in seconds for
blocking operations like the connection attempt (if not specified, the
global default timeout setting will be used). This only works for HTTP,
HTTPS and FTP connections.

If *context* is specified, it must be a ssl.SSLContext instance describing
the various SSL options. See HTTPSConnection for more details.

The optional *cafile* and *capath* parameters specify a set of trusted CA
certificates for HTTPS requests. cafile should point to a single file
containing a bundle of CA certificates, whereas capath should point to a
directory of hashed certificate files. More information can be found in
ssl.SSLContext.load_verify_locations().

The *cadefault* parameter is ignored.

This function always returns an object which can work as a context
manager and has methods such as

* geturl() - return the URL of the resource retrieved, commonly used to
  determine if a redirect was followed

* info() - return the meta-information of the page, such as headers, in the
  form of an email.message_from_string() instance (see Quick Reference to
  HTTP Headers)

* getcode() - return the HTTP status code of the response.  Raises URLError
  on errors.

For HTTP and HTTPS URLs, this function returns a http.client.HTTPResponse
object slightly modified. In addition to the three new methods above, the
msg attribute contains the same information as the reason attribute ---
the reason phrase returned by the server --- instead of the response
headers as it is specified in the documentation for HTTPResponse.

For FTP, file, and data URLs and requests explicitly handled by legacy
URLopener and FancyURLopener classes, this function returns a
urllib.response.addinfourl object.

Note that None may be returned if no handler handles the request (though
the default installed global OpenerDirector uses UnknownHandler to ensure
this never happens).

In addition, if proxy settings are detected (for example, when a *_proxy
environment variable like http_proxy is set), ProxyHandler is default
installed and makes sure the requests are handled through the proxy.

urlopen(url, data=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT, \*, cafile=None, capath=None, cadefault=False, context=None)

This module provides the :class:`~lib.splitter.MultiSplitterWindow` class, which is very
similar to the standard :class:`SplitterWindow` except it can be split
more than once.

# Name:        wx.lib.splitter
# Purpose:     A class similar to wx.SplitterWindow but that allows more
#              than a single split
#
#
# Created:     9-June-2005
# Copyright:   (c) 2005-2020 by Total Control Software
# Tags:        phoenix-port, unittest, documentation, py3-port

This event class is almost the same as `wx.SplitterEvent` except
`wx.SplitterEvent`.

Constructor.

Used internally by wxWidgets only.

:param `eventType`:
:type `eventType`: EventType
:param `splitter`:
:type `splitter`: SplitterWindow

This is the opposite of :meth:`Veto` : it explicitly allows the
event to be processed.

For most events it is not necessary to call this method as the events
are allowed anyhow but some are forbidden by default (this will be
mentioned in the corresponding event description).

Returns the new sash index.

May only be called while processing ``wxEVT_SPLITTER_SASH_POS_CHANGING``
and  ``wxEVT_SPLITTER_SASH_POS_CHANGED`` events.

:rtype: `int`

Returns ``True`` if the change is allowed (:meth:`Veto` hasn't been
called) or ``False`` otherwise (if it was).

:rtype: `bool`

In the case of ``wxEVT_SPLITTER_SASH_POS_CHANGED`` events, sets the
new sash index.

In the case of ``wxEVT_SPLITTER_SASH_POS_CHANGING`` events, sets the
new tracking bar position so visual feedback during dragging will
represent that change that will actually take place. Set to -1 from
the event handler code to prevent reindexing.

and ``wxEVT_SPLITTER_SASH_POS_CHANGED`` events.

:param int `pos`: New sash index.

new sash position.

the event handler code to prevent repositioning.

:param int `pos`: New sash position.

It is in general a good idea to notify the user about the reasons
for vetoing the change because otherwise the applications behaviour
(which just refuses to do what the user wants) might be quite
surprising.

This class is very similar to `wx.SplitterWindow` except that it
allows for more than two windows and more than one sash.  Many of
the same styles, constants, and methods behave the same as in
wx.SplitterWindow.  The key differences are seen in the methods
that deal with the child windows managed by the splitter, and also
those that deal with the sash positions.  In most cases you will
need to pass an index value to tell the class which window or sash
you are referring to.

The concept of the sash position is also different than in
wx.SplitterWindow.  Since the wx.Splitterwindow has only one sash
you can think of it's position as either relative to the whole
splitter window, or as relative to the first window pane managed
by the splitter.  Once there is more than one sash then the
distinciton between the two concepts needs to be clairified.  I've
chosen to use the second definition, and sash positions are the
distance (either horizontally or vertically) from the origin of
the window just before the sash in the splitter stack.

NOTE: These things are not yet supported:

    * Using negative sash positions to indicate a position offset
      from the end.

    * User controlled unsplitting (with double clicks on the sash
      or dragging a sash until the pane size is zero.)

    * Sash gravity

:param wx.Window `parent`: the parent window
:param integer `id`: an identifier for the control: a value of -1 is taken to mean a default
  chosen by either the windowing system or wxPython, depending on platform
:param integer `style`: the control window style
:param string `name`: the control name

__init__(self, parent, id=-1, pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, name="multiSplitter")

:param `window`: the window to add to the splitter
:param `sashPos`: if given it is used to size the new window

Removes the window from the stack of windows managed by the
splitter.  The window will still exist so you should `Hide` or
`Destroy` it as needed.

:param `window`: the window to be removed from the splitter

the control based on the best sizes of the child windows.

:param `window1`: the first window to switch position
:param `window2`: the second window to switch position

Returns the current orientation of the splitter, either
``wx.VERTICAL`` or ``wx.HORIZONTAL``.

Returns the position of the idx'th sash, measured from the
left/top of the window preceding the sash.

:param int `idx`: get the sash position of the given index

Returns the idx'th window being managed by the splitter.

:param int `idx`: get the window at the given index

Insert a new window into the splitter.

:param int `idx`: the position to insert the window at.

Replaces oldWindow (which is currently being managed by the
splitter) with newWindow.  The oldWindow window will still

:param `oldWindow`: the window to be replace
:param `newWindow`: the window to replace the above window

Sets the back ground colour.

:param wx.Colour `color`: the colour to use.

Set the smallest size that any pane will be allowed to be
resized to.

:param int `minSize`: the minimum size of pane

Set whether the windows managed by the splitter will be
stacked vertically or horizontally.  The default is
horizontal.

:param `orient`: either ``wx.VERTICAL`` or ``wx.HORIZONTAL``

Set the position of the idx'th sash, measured from the left/top
of the window preceding the sash.

:param int `idx`: set the sash position of the given index
:param int `pos`: the sash position

Reposition and size the windows managed by the splitter.
Useful when windows have been added/removed or when styles
have been changed.

:class:`GenStaticBitmap` is a generic implementation of :class:`wx.StaticBitmap`.

:class:`GenStaticBitmap` is a generic implementation of
:class:`wx.StaticBitmap`.

Some of the platforms supported by wxPython (most notably GTK), do not
consider :class:`wx.StaticBitmap` as a separate widget; instead, the bitmap is
just drawn on its parent window. This essentially bars the use of almost all
mouse events (such as detection of mouse motions, mouse clicks and so on) on
the widget.

Using :class:`GenStaticBitmap` will overcome the problems described above, as
it is a generic widget and a real window on its own.

Usage
=====

    import wx
    import wx.lib.statbmp as SB

    frame = wx.Frame(None, -1, "wx.lib.statbmp Test")
    panel = wx.Panel(frame)

    bmp = wx.ArtProvider.GetBitmap(wx.ART_INFORMATION, wx.ART_OTHER, (16, 16))
    st1 = SB.GenStaticBitmap(panel, -1, bmp, (20, 10))

    bmp = wx.ArtProvider.GetBitmap(wx.ART_WARNING, wx.ART_OTHER, (32, 32))
    st2 = SB.GenStaticBitmap(panel, -1, bmp, (20, 60))

# Name:        wx.lib.statbmp
# Purpose:     A generic StaticBitmap class.
#
#
# Created:     12-May-2004
# Copyright:   (c) 2004-2020 by Total Control Software

:class:`GenStaticBitmap` is a generic implementation of :class:`wx.StaticBitmap`. 

:param wx.Bitmap `bitmap`: the static bitmap used in the control;

__init__(self, parent, ID, bitmap, pos = wx.DefaultPosition, size = wx.DefaultSize, style = 0, name = "genstatbmp")

Returns the bitmap currently used in the control.

:rtype: wx.Bitmap

.. seealso:: :meth:`SetBitmap`

the same font/colour attributes as the native :class:`StaticBitmap`.

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`GenStaticBitmap`.

Handles the ``wx.EVT_PAINT`` for :class:`GenStaticBitmap`.

Sets the bitmap label.

:param wx.Bitmap `bitmap`: the new bitmap.

.. seealso:: :meth:`GetBitmap`

consider :class:`wx.StaticText` as a separate widget; instead, the label is
just drawn directly on its parent window. This essentially bars the use of
almost all mouse events (such as detection of mouse motions, mouse clicks and
so on) on that widget.

Moreover, these platforms do not allow the developer to change the widget's
background colour.

Using :class:`GenStaticText` will overcome all the problems described above,
as it is a generic widget and a real window on its own.

Usage
=====

    import wx
    import wx.lib.stattext as ST

    frame = wx.Frame(None, -1, "wx.lib.stattext Test")

    st1 = ST.GenStaticText(panel, -1, "This is an example of static text", (20, 10))

    st2 = ST.GenStaticText(panel, -1, "Is this yellow?", (20, 70), (120, -1))
    st2.SetBackgroundColour('Yellow')

    ST.GenStaticText(panel, -1, "align center", (160, 70), (120, -1), wx.ALIGN_CENTER)
    ST.GenStaticText(panel, -1, "align right", (300, 70), (120, -1), wx.ALIGN_RIGHT)

# Name:        wx.lib.stattext
# Purpose:     A generic wxGenStaticText class.  Using this should
#              eliminate some of the platform differences in wxStaticText,
#              such as background colours and mouse sensitivity.
#
#
# Created:     8-July-2002
# 12/12/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
#

A throbber displays an animated image that can be
started, stopped, reversed, etc.  Useful for showing
an ongoing process (like most web browsers use) or
simply for adding eye-candy to an application.

Throbbers utilize a wxTimer so that normal processing
can continue unencumbered.

The first argument is either the name of a file that will be split into frames
(a composite image) or a list of  strings of image names that will be treated
as individual frames.  If a single (composite) image is given, then additional
information must be provided: the number of frames in the image and the width
of each frame.  The first frame is treated as the "at rest" frame (it is not
shown during animation, but only when Throbber.Rest() is called.
A second, single image may be optionally specified to overlay on top of the
animation. A label may also be specified to show on top of the animation.

:param `parent`: parent window, must not be ``None``
:param `bitmap`: a :class:`wx.Bitmap` to be used
:param `frameDelay`: time delay between frames
:param `frames`: number of frames (only necessary for composite image)
:param `frameWidth`: width of each frame (only necessary for composite image)
:param string `label`: optional text to be displayed
:param `overlay`: optional :class:`wx.Bitmap` to overlay on animation
:param boolean `reverse`: reverse direction at end of animation
:param integer `style`: the underlying :class:`wx.Control` style
:param `rest`: the rest frame
:param `current`: the current frame
:param `direction`: 1 advances = -1 reverses
:param `sequence`: sequence of frames, defaults to range(self.frames)

__init__(self, parent, id, bitmap, pos = wx.DefaultPosition, size = wx.DefaultSize, frameDelay = 0.1, frames = 0, frameWidth = 0, label = None, overlay = None, reverse = 0, style = 0, name = "throbber", rest = 0, current = 0, direction = 1, sequence = None )

Get the best size of the widget.

:returns: the width and height

Handles the ``wx.EVT_WINDOW_DESTROY`` event for :class:`Throbber`.

Handles the ``wx.EVT_PAINT`` event for :class:`Throbber`.

Handles the ``wx.EVT_TIMER`` event for :class:`Throbber`.

Set current image.

:param int `current`: the index to the current image

Set the font for the label.

:param `font`: the :class:`wx.Font` to use

Delay between each frame.

:param float `frameDelay`: the delay between frames.

Change the text of the label.

:param string `label`: the label text.

Set rest image.

:param int `rest`: the index for the rest frame.

Order to display images in.

:param `sequence`: a sequence containing the order to display images in.

Toggle the label.

:param boolean `state`: set the label state or if None toggle state.

Toggle the overlay image.

:param boolean `state`: set the overlay state or if None toggle state.

Handles the ``EVT_UPDATE_THROBBER`` event for :class:`ResizeWidget`.

:param `event`: a :class:`UpdateThrobberEvent` event to be processed.

News-ticker style scrolling text control

    * Can scroll from right to left or left to right.

    * Speed of the ticking is controlled by two parameters:

      - Frames per Second(FPS): How many times per second the ticker updates

      - Pixels per Frame(PPF): How many pixels the text moves each update

Low FPS with high PPF will result in "jumpy" text, lower PPF with higher FPS
is smoother (but blurrier and more CPU intensive) text.

# Name:        wx.lib.ticker
# Purpose:     A news-ticker style scrolling text control
#
# Author:      Chris Mellon
#
# Created:     29-Aug-2004
# Copyright:   (c) 2004 by Chris Mellon

:param wx.Window `parent`: the parent
:param string `text`: text in the ticker
:param wx.Colour `fgcolor`: text/foreground color
:param wx.Colour `bgcolor`: background color
:param boolean `start`: if True, the ticker starts immediately
:param int `ppf`: pixels per frame
:param int `fps`: frames per second
:param `direction`: direction of ticking, 'rtl' or 'ltr'
:param `name`: the control name

__init__(self, parent, id=-1, text=wx.EmptyString, fgcolor = wx.BLACK, bgcolor = wx.WHITE, start=True, ppf=2, fps=20, direction="rtl", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, name="Ticker" )

Width we don't care about, height is either -1, or the character
height of our text with a little extra padding

Draws the ticker text at the current offset using the provided DC.

:param wx.DC `dc`: the dc to use.

Noop because of double buffering

Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`Ticker`.

:param `evt`: a :class:`EraseEvent` event to be processed.

Handles the ``wx.EVT_PAINT`` event for :class:`Ticker`.

Handles the ``wx.EVT_TIMER`` event for :class:`Ticker`.

:param `evt`: a :class:`TimerEvent` event to be processed.

Sets the direction of the ticker: right to left (rtl) or
left to right (ltr).

:param `dir`: the direction 'rtl' or 'ltr'

Set the font for the control.

:param wx.Font `font`: the font to be used.

Adjust the update speed of the ticker.

:param int `fps`: frames per second.

Set the number of pixels per frame the ticker moves - ie,
how "jumpy" it is.

:param int `ppf`: the pixels per frame setting.

Updates the cached text extent if needed.

# Name:        wx.lib.ticker_xrc
# Purpose:     A XRC handler for wx.lib.ticker
#
#
# Created:     17-May-2005
# Copyright:   (c) 2005 by Chris Mellon

XmlResourceHandler()

wxSizerXmlHandler is a class for resource handlers capable of creating
a wxSizer object from an XML node.

CanHandle(node) -> bool

Returns true if it understands this node and can create a resource
from it, false otherwise.

DoCreateResource() -> Object

Called from CreateResource after variables were filled.

# Name:        wx.lib.utils
# Purpose:     Miscellaneous utility functions
#
#
# Created:     18-Jan-2009
# Copyright:   (c) 2009-2020 Total Control Software
#
#

Compare the rect with the dimensions of the display that the rect's
upper left corner is positioned on. If it doesn't fit entirely on
screen then attempt to make it do so either by repositioning the
rectangle, resizing it, or both.  Returns the adjusted rectangle.

If the adjustment value is given then it will be used to ensure that
the rectangle is at least that much smaller than the display's client
area.

:param wx.Rect `rect`: the rectangle to be repositioned;
:param tuple `adjust`: if given, it will be used to ensure that
 the rectangle is at least that much smaller than the display's client
 area.

:rtype: `rect`

# Name:        wx.lib.wordwrap
# Purpose:     Contains a function to aid in word-wrapping some text
#
#
# Created:     15-Oct-2006

wx.lib.wxpTag

This module contains a wxHtmlTagHandler that knows how to build
and place wxPython widgets onto wxHtmlWindow web pages.

You don't need to use anything in this module directly, just
importing it will create the tag handler and add it to any
wxHtmlWinParsers created from that time forth.

Tags of the following form are recognised::

    <WXP class="classname" [module="modulename"] [width="num"] [height="num"]>
        <PARAM name="parameterName" value="parameterValue">
        ...
    </WXP>

where modulename is the name of a module (possibly in package
notation) to import and classname is the name of a class in that
module to create an instance of.  If the module tag-attribute is not
given or is an empty string, then wx is used.  The width and height
attributes are expected to be integers and will be passed to the
__init__ method of the class as a wxSize object named size.  However,
if the width attribute ends with the percent (%) symbol then the value
will be used as a percentage of the available width and the
wxHtmlWindow will manage the size.

The name-value pairs in all the nested PARAM tags are packaged up as
strings into a python dictionary and passed to the __init__ method of
the class as keyword arguments.  This means that they are all
accessible from the __init__ method as regular parameters, or you use
the special Python \*\*kw syntax in your __init__ method to get the
dictionary directly.

Some parameter values are special and if they are present then they will
be converted from strings to alternate datatypes.  They are:

    id           If the value of id can be converted to an integer, it will
                 be.  Otherwise it is assumed to be the name of an integer
                 variable in the module.

    colours      Any value of the form "#123ABC" will automatically be
                 converted to a wxColour object.

    Py Types     Any value beginning with "(", "[" or "{" are expected to
                 be a Python tuple, list, or dictionary and eval()
                 will be used to convert them to that type.  If the
                 eval() fails then the original string value will be
                 preserved.

    wx Types     Any value beginning with "wx" is expected to be an attempt
                 to create a wxPython object, such as a wxSize, etc.
                 The eval() will be used to try and construct the
                 object and if it fails then the original string value
                 will be used instead.

An example::

    <wxp module="wx" class="Button">
        <param name="label" value="Click here">
        <param name="id" value="ID_OK">
    </wxp>

Both the beginning and ending WXP tags are required.

In the future support will be added for another tag that can be
embedded between the two beginning and ending WXP tags and will
facilitate calling methods of the widget to help initialize it.
Additionally, support may be added to fetch the module from a web
server as is done with java applets.

# Name:        wx.lib.wxpTag
# Purpose:     A wxHtmlTagHandler that knows how to build and place
#              wxPython widgets onto web pages.
#
#
# Created:     13-Sept-1999
#
#

# just a place to hold some values

HtmlWinTagHandler()

This is basically wxHtmlTagHandler except that it is extended with
protected member m_WParser pointing to the wxHtmlWinParser object
(value of this member is identical to wxHtmlParser's m_Parser).

HandleTag(tag) -> bool

This is the core method of each handler.