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