1"""
2AUI is an Advanced User Interface library that aims to implement "cutting-edge"
3interface usability and design features so developers can quickly and easily create
4beautiful and usable application interfaces.
5
6
7Vision and Design Principles
8============================
9
10AUI attempts to encapsulate the following aspects of the user interface:
11
12* **Frame Management**: Frame management provides the means to open, move and hide common
13  controls that are needed to interact with the document, and allow these configurations
14  to be saved into different perspectives and loaded at a later time.
15
16* **Toolbars**: Toolbars are a specialized subset of the frame management system and should
17  behave similarly to other docked components. However, they also require additional
18  functionality, such as "spring-loaded" rebar support, "chevron" buttons and end-user
19  customizability.
20
21* **Modeless Controls**: Modeless controls expose a tool palette or set of options that
22  float above the application content while allowing it to be accessed. Usually accessed
23  by the toolbar, these controls disappear when an option is selected, but may also be
24  "torn off" the toolbar into a floating frame of their own.
25
26* **Look and Feel**: Look and feel encompasses the way controls are drawn, both when shown
27  statically as well as when they are being moved. This aspect of user interface design
28  incorporates "special effects" such as transparent window dragging as well as frame animation.
29
30AUI adheres to the following principles:
31
32- Use native floating frames to obtain a native look and feel for all platforms;
33- Use existing wxPython code where possible, such as sizer implementation for frame management;
34- Use standard wxPython coding conventions.
35
36
37Usage
38=====
39
40The following example shows a simple implementation that uses :class:`framemanager.AuiManager` to manage
41three text controls in a frame window::
42
43    import wx
44    import wx.lib.agw.aui as aui
45
46    class MyFrame(wx.Frame):
47
48        def __init__(self, parent, id=-1, title="AUI Test", pos=wx.DefaultPosition,
49                     size=(800, 600), style=wx.DEFAULT_FRAME_STYLE):
50
51            wx.Frame.__init__(self, parent, id, title, pos, size, style)
52
53            self._mgr = aui.AuiManager()
54
55            # notify AUI which frame to use
56            self._mgr.SetManagedWindow(self)
57
58            # create several text controls
59            text1 = wx.TextCtrl(self, -1, "Pane 1 - sample text",
60                                wx.DefaultPosition, wx.Size(200,150),
61                                wx.NO_BORDER | wx.TE_MULTILINE)
62
63            text2 = wx.TextCtrl(self, -1, "Pane 2 - sample text",
64                                wx.DefaultPosition, wx.Size(200,150),
65                                wx.NO_BORDER | wx.TE_MULTILINE)
66
67            text3 = wx.TextCtrl(self, -1, "Main content window",
68                                wx.DefaultPosition, wx.Size(200,150),
69                                wx.NO_BORDER | wx.TE_MULTILINE)
70
71            # add the panes to the manager
72            self._mgr.AddPane(text1, aui.AuiPaneInfo().Left().Caption("Pane Number One"))
73            self._mgr.AddPane(text2, aui.AuiPaneInfo().Bottom().Caption("Pane Number Two"))
74            self._mgr.AddPane(text3, aui.AuiPaneInfo().CenterPane())
75
76            # tell the manager to "commit" all the changes just made
77            self._mgr.Update()
78
79            self.Bind(wx.EVT_CLOSE, self.OnClose)
80
81
82        def OnClose(self, event):
83            # deinitialize the frame manager
84            self._mgr.UnInit()
85            event.Skip()
86
87
88    # our normal wxApp-derived class, as usual
89
90    app = wx.App(0)
91
92    frame = MyFrame(None)
93    app.SetTopWindow(frame)
94    frame.Show()
95
96    app.MainLoop()
97
98
99What's New
100==========
101
102Current wxAUI Version Tracked: wxWidgets 2.9.5 (SVN HEAD)
103
104The wxPython AUI version fixes the following bugs or implement the following
105missing features (the list is not exhaustive):
106
107- Visual Studio 2005 style docking: http://www.kirix.com/forums/viewtopic.php?f=16&t=596
108- Dock and Pane Resizing: http://www.kirix.com/forums/viewtopic.php?f=16&t=582
109- Patch concerning dock resizing: http://www.kirix.com/forums/viewtopic.php?f=16&t=610
110- Patch to effect wxAuiToolBar orientation switch: http://www.kirix.com/forums/viewtopic.php?f=16&t=641
111- AUI: Core dump when loading a perspective in wxGTK (MSW OK): http://www.kirix.com/forums/viewtopic.php?f=15&t=627
112- wxAuiNotebook reordered AdvanceSelection(): http://www.kirix.com/forums/viewtopic.php?f=16&t=617
113- Vertical Toolbar Docking Issue: http://www.kirix.com/forums/viewtopic.php?f=16&t=181
114- Patch to show the resize hint on mouse-down in aui: http://trac.wxwidgets.org/ticket/9612
115- The Left/Right and Top/Bottom Docks over draw each other: http://trac.wxwidgets.org/ticket/3516
116- MinSize() not honoured: http://trac.wxwidgets.org/ticket/3562
117- Layout problem with wxAUI: http://trac.wxwidgets.org/ticket/3597
118- Resizing children ignores current window size: http://trac.wxwidgets.org/ticket/3908
119- Resizing panes under Vista does not repaint background: http://trac.wxwidgets.org/ticket/4325
120- Resize sash resizes in response to click: http://trac.wxwidgets.org/ticket/4547
121- "Illegal" resizing of the AuiPane? (wxPython): http://trac.wxwidgets.org/ticket/4599
122- Floating wxAUIPane Resize Event doesn't update its position: http://trac.wxwidgets.org/ticket/9773
123- Don't hide floating panels when we maximize some other panel: http://trac.wxwidgets.org/ticket/4066
124- wxAUINotebook incorrect ALLOW_ACTIVE_PANE handling: http://trac.wxwidgets.org/ticket/4361
125- Page changing veto doesn't work, (patch supplied): http://trac.wxwidgets.org/ticket/4518
126- Show and DoShow are mixed around in wxAuiMDIChildFrame: http://trac.wxwidgets.org/ticket/4567
127- wxAuiManager & wxToolBar - ToolBar Of Size Zero: http://trac.wxwidgets.org/ticket/9724
128- wxAuiNotebook doesn't behave properly like a container as far as...: http://trac.wxwidgets.org/ticket/9911
129- Serious layout bugs in wxAUI: http://trac.wxwidgets.org/ticket/10620
130- wAuiDefaultTabArt::Clone() should just use copy contructor: http://trac.wxwidgets.org/ticket/11388
131- Drop down button for check tool on wxAuiToolbar: http://trac.wxwidgets.org/ticket/11139
132
133Plus the following features:
134
135- AuiManager:
136
137  (a) Implementation of a simple minimize pane system: Clicking on this minimize button causes a new
138      AuiToolBar to be created and added to the frame manager, (currently the implementation is such
139      that panes at West will have a toolbar at the right, panes at South will have toolbars at the
140      bottom etc...) and the pane is hidden in the manager.
141      Clicking on the restore button on the newly created toolbar will result in the toolbar being
142      removed and the original pane being restored;
143  (b) Panes can be docked on top of each other to form `AuiNotebooks`; `AuiNotebooks` tabs can be torn
144      off to create floating panes;
145  (c) On Windows XP, use the nice sash drawing provided by XP while dragging the sash;
146  (d) Possibility to set an icon on docked panes;
147  (e) Possibility to draw a sash visual grip, for enhanced visualization of sashes;
148  (f) Implementation of a native docking art (`ModernDockArt`). Windows XP only, **requires** Mark Hammond's
149      pywin32 package (winxptheme);
150  (g) Possibility to set a transparency for floating panes (a la Paint .NET);
151  (h) Snapping the main frame to the screen in any positin specified by horizontal and vertical
152      alignments;
153  (i) Snapping floating panes on left/right/top/bottom or any combination of directions, a la Winamp;
154  (j) "Fly-out" floating panes, i.e. panes which show themselves only when the mouse hover them;
155  (k) Ability to set custom bitmaps for pane buttons (close, maximize, etc...);
156  (l) Implementation of the style ``AUI_MGR_ANIMATE_FRAMES``, which fade-out floating panes when
157      they are closed (all platforms which support frames transparency) and show a moving rectangle
158      when they are docked and minimized (Windows < Vista and GTK only);
159  (m) A pane switcher dialog is available to cycle through existing AUI panes;
160  (n) Some flags which allow to choose the orientation and the position of the minimized panes;
161  (o) The functions [Get]MinimizeMode() in `AuiPaneInfo` which allow to set/get the flags described above;
162  (p) Events like ``EVT_AUI_PANE_DOCKING``, ``EVT_AUI_PANE_DOCKED``, ``EVT_AUI_PANE_FLOATING`` and ``EVT_AUI_PANE_FLOATED`` are
163      available for all panes *except* toolbar panes;
164  (q) Implementation of the RequestUserAttention method for panes;
165  (r) Ability to show the caption bar of docked panes on the left instead of on the top (with caption
166      text rotated by 90 degrees then). This is similar to what `wxDockIt` did. To enable this feature on any
167      given pane, simply call `CaptionVisible(True, left=True)`;
168  (s) New Aero-style docking guides: you can enable them by using the `AuiManager` style ``AUI_MGR_AERO_DOCKING_GUIDES``;
169  (t) A slide-in/slide-out preview of minimized panes can be seen by enabling the `AuiManager` style
170      ``AUI_MGR_PREVIEW_MINIMIZED_PANES`` and by hovering with the mouse on the minimized pane toolbar tool;
171  (u) New Whidbey-style docking guides: you can enable them by using the `AuiManager` style ``AUI_MGR_WHIDBEY_DOCKING_GUIDES``;
172  (v) Native of custom-drawn mini frames can be used as floating panes, depending on the ``AUI_MGR_USE_NATIVE_MINIFRAMES`` style;
173  (w) A "smooth docking effect" can be obtained by using the ``AUI_MGR_SMOOTH_DOCKING`` style (similar to PyQT docking style);
174  (x) Implementation of "Movable" panes, i.e. a pane that is set as `Movable()` but not `Floatable()` can be dragged and docked
175      into a new location but will not form a floating window in between.
176
177
178- AuiNotebook:
179
180  (a) Implementation of the style ``AUI_NB_HIDE_ON_SINGLE_TAB``, a la :mod:`lib.agw.flatnotebook`;
181  (b) Implementation of the style ``AUI_NB_SMART_TABS``, a la :mod:`lib.agw.flatnotebook`;
182  (c) Implementation of the style ``AUI_NB_USE_IMAGES_DROPDOWN``, which allows to show tab images
183      on the tab dropdown menu instead of bare check menu items (a la :mod:`lib.agw.flatnotebook`);
184  (d) 6 different tab arts are available, namely:
185
186      (1) Default "glossy" theme (as in :class:`~auibook.AuiNotebook`)
187      (2) Simple theme (as in :class:`~auibook.AuiNotebook`)
188      (3) Firefox 2 theme
189      (4) Visual Studio 2003 theme (VC71)
190      (5) Visual Studio 2005 theme (VC81)
191      (6) Google Chrome theme
192
193  (e) Enabling/disabling tabs;
194  (f) Setting the colour of the tab's text;
195  (g) Implementation of the style ``AUI_NB_CLOSE_ON_TAB_LEFT``, which draws the tab close button on
196      the left instead of on the right (a la Camino browser);
197  (h) Ability to save and load perspectives in `AuiNotebook` (experimental);
198  (i) Possibility to add custom buttons in the `AuiNotebook` tab area;
199  (j) Implementation of the style ``AUI_NB_TAB_FLOAT``, which allows the floating of single tabs.
200      Known limitation: when the notebook is more or less full screen, tabs cannot be dragged far
201      enough outside of the notebook to become floating pages;
202  (k) Implementation of the style ``AUI_NB_DRAW_DND_TAB`` (on by default), which draws an image
203      representation of a tab while dragging;
204  (l) Implementation of the `AuiNotebook` unsplit functionality, which unsplit a splitted AuiNotebook
205      when double-clicking on a sash;
206  (m) Possibility to hide all the tabs by calling `HideAllTAbs`;
207  (n) wxPython controls can now be added inside page tabs by calling `AddControlToPage`, and they can be
208      removed by calling `RemoveControlFromPage`;
209  (o) Possibility to preview all the pages in a `AuiNotebook` (as thumbnails) by using the `NotebookPreview`
210      method of `AuiNotebook`;
211  (p) Tab labels can be edited by calling the `SetRenamable` method on a `AuiNotebook` page;
212  (q) Support for multi-lines tab labels in `AuiNotebook`;
213  (r) Support for setting minimum and maximum tab widths for fixed width tabs;
214  (s) Implementation of the style ``AUI_NB_ORDER_BY_ACCESS``, which orders the tabs by last access time
215      inside the Tab Navigator dialog;
216  (t) Implementation of the style ``AUI_NB_NO_TAB_FOCUS``, allowing the developer not to draw the tab
217      focus rectangle on tne `AuiNotebook` tabs.
218
219|
220
221- AuiToolBar:
222
223  (a) ``AUI_TB_PLAIN_BACKGROUND`` style that allows to easy setup a plain background to the AUI toolbar,
224      without the need to override drawing methods. This style contrasts with the default behaviour
225      of the :class:`~auibar.AuiToolBar` that draws a background gradient and this break the window design when
226      putting it within a control that has margin between the borders and the toolbar (example: put
227      :class:`~auibar.AuiToolBar` within a :class:`StaticBoxSizer` that has a plain background);
228  (b) `AuiToolBar` allow item alignment: http://trac.wxwidgets.org/ticket/10174;
229  (c) `AUIToolBar` `DrawButton()` improvement: http://trac.wxwidgets.org/ticket/10303;
230  (d) `AuiToolBar` automatically assign new id for tools: http://trac.wxwidgets.org/ticket/10173;
231  (e) `AuiToolBar` Allow right-click on any kind of button: http://trac.wxwidgets.org/ticket/10079;
232  (f) `AuiToolBar` idle update only when visible: http://trac.wxwidgets.org/ticket/10075;
233  (g) Ability of creating `AuiToolBar` tools with [counter]clockwise rotation. This allows to propose a
234      variant of the minimizing functionality with a rotated button which keeps the caption of the pane
235      as label;
236  (h) Allow setting the alignment of all tools in a toolbar that is expanded;
237  (i) Implementation of the ``AUI_MINIMIZE_POS_TOOLBAR`` flag, which allows to minimize a pane inside
238      an existing toolbar. Limitation: if the minimized icon in the toolbar ends up in the overflowing
239      items (i.e., a menu is needed to show the icon), this style will not work.
240
241
242
243TODOs
244=====
245
246- Documentation, documentation and documentation;
247- Fix `tabmdi.AuiMDIParentFrame` and friends, they do not work correctly at present;
248- Allow specification of `CaptionLeft()` to `AuiPaneInfo` to show the caption bar of docked panes
249  on the left instead of on the top (with caption text rotated by 90 degrees then). This is
250  similar to what `wxDockIt` did - DONE;
251- Make developer-created `AuiNotebooks` and automatic (framemanager-created) `AuiNotebooks` behave
252  the same way (undocking of tabs) - DONE, to some extent;
253- Find a way to dock panes in already floating panes (`AuiFloatingFrames`), as they already have
254  their own `AuiManager`;
255- Add more gripper styles (see, i.e., PlusDock 4.0);
256- Add an "AutoHide" feature to docked panes, similar to fly-out floating panes (see, i.e., PlusDock 4.0);
257- Add events for panes when they are about to float or to be docked (something like
258  ``EVT_AUI_PANE_FLOATING/ED`` and ``EVT_AUI_PANE_DOCKING/ED``) - DONE, to some extent;
259- Implement the 4-ways splitter behaviour for horizontal and vertical sashes if they intersect;
260- Extend `tabart.py` with more aui tab arts;
261- Implement ``AUI_NB_LEFT`` and ``AUI_NB_RIGHT`` tab locations in `AuiNotebook`;
262- Move `AuiDefaultToolBarArt` into a separate module (as with `tabart.py` and `dockart.py`) and
263  provide more arts for toolbars (maybe from :mod:`lib.agw.flatmenu`?)
264- Support multiple-rows/multiple columns toolbars;
265- Integrate as much as possible with :mod:`lib.agw.flatmenu`, from dropdown menus in `AuiNotebook` to
266  toolbars and menu positioning;
267- Possibly handle minimization of panes in a different way (or provide an option to switch to
268  another way of minimizing panes);
269- Clean up/speed up the code, especially time-consuming for-loops;
270- Possibly integrate `wxPyRibbon` (still on development), at least on Windows.
271
272
273License And Version
274===================
275
276AUI library is distributed under the wxPython license.
277
278Latest Revision: Andrea Gavana @ 09 Jan 2014, 22.00 GMT
279
280Version 1.3.
281
282"""
283
284__author__ = "Andrea Gavana <andrea.gavana@gmail.com>"
285__date__ = "31 March 2009"
286
287
288from .aui_constants import *
289from .aui_utilities import *
290from .framemanager import *
291from .auibar import *
292from .auibook import *
293from .tabart import *
294from .dockart import *
295from .tabmdi import *
296