1\section{\class{wxAuiManager}}\label{wxauimanager} 2 3wxAuiManager is the central class of the wxAUI class framework. 4 5See also \helpref{wxAUI overview}{wxauioverview}. 6 7wxAuiManager manages the panes associated with it 8for a particular wxFrame, using a pane's wxAuiPaneInfo information to 9determine each pane's docking and floating behavior. wxAuiManager 10uses wxWidgets' sizer mechanism to plan the layout of each frame. It 11uses a replaceable dock art class to do all drawing, so all drawing is 12localized in one area, and may be customized depending on an 13application's specific needs. 14 15wxAuiManager works as follows: the programmer adds panes to the class, 16or makes changes to existing pane properties (dock position, floating 17state, show state, etc.). To apply these changes, wxAuiManager's 18Update() function is called. This batch processing can be used to avoid 19flicker, by modifying more than one pane at a time, and then "committing" 20all of the changes at once by calling Update(). 21 22Panes can be added quite easily: 23 24\begin{verbatim} 25wxTextCtrl* text1 = new wxTextCtrl(this, -1); 26wxTextCtrl* text2 = new wxTextCtrl(this, -1); 27m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption")); 28m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption")); 29m_mgr.Update(); 30\end{verbatim} 31 32Later on, the positions can be modified easily. The following will float 33an existing pane in a tool window: 34 35\begin{verbatim} 36m_mgr.GetPane(text1).Float(); 37\end{verbatim} 38 39\wxheading{Layers, Rows and Directions, Positions} 40 41Inside wxAUI, the docking layout is figured out by checking several 42pane parameters. Four of these are important for determining where a 43pane will end up: 44 45{\bf Direction:} 46Each docked pane has a direction, Top, Bottom, Left, Right, or 47Center. This is fairly self-explanatory. The pane will be placed in the 48location specified by this variable. 49 50{\bf Position:} 51More than one pane can be placed inside of a dock. Imagine two panes 52being docked on the left side of a window. One pane can be placed over 53another. In proportionally managed docks, the pane position indicates 54its sequential position, starting with zero. So, in our scenario with 55two panes docked on the left side, the top pane in the dock would have 56position 0, and the second one would occupy position 1. 57 58{\bf Row:} 59A row can allow for two docks to be placed next to each other. One of 60the most common places for this to happen is in the toolbar. Multiple 61toolbar rows are allowed, the first row being row 0, and the second 62row 1. Rows can also be used on vertically docked panes. 63 64{\bf Layer:} 65A layer is akin to an onion. Layer 0 is the very center of the 66managed pane. Thus, if a pane is in layer 0, it will be closest to the 67center window (also sometimes known as the "content window"). 68Increasing layers "swallow up" all layers of a lower value. This can 69look very similar to multiple rows, but is different because all panes 70in a lower level yield to panes in higher levels. The best way to 71understand layers is by running the wxAUI sample. 72 73\wxheading{Derived from} 74 75\helpref{wxEvtHandler}{wxevthandler} 76 77\wxheading{Include files} 78 79<wx/aui/aui.h> 80 81\wxheading{See also} 82 83\helpref{wxAuiPaneInfo}{wxauipaneinfo}, 84\helpref{wxAuiDockArt}{wxauidockart} 85 86\wxheading{Data structures} 87 88\begin{verbatim} 89enum wxAuiManagerDock 90{ 91 wxAUI_DOCK_NONE = 0, 92 wxAUI_DOCK_TOP = 1, 93 wxAUI_DOCK_RIGHT = 2, 94 wxAUI_DOCK_BOTTOM = 3, 95 wxAUI_DOCK_LEFT = 4, 96 wxAUI_DOCK_CENTER = 5, 97 wxAUI_DOCK_CENTRE = wxAUI_DOCK_CENTER 98} 99\end{verbatim} 100 101\begin{verbatim} 102enum wxAuiManagerOption 103{ 104 wxAUI_MGR_ALLOW_FLOATING = 1 << 0, 105 wxAUI_MGR_ALLOW_ACTIVE_PANE = 1 << 1, 106 wxAUI_MGR_TRANSPARENT_DRAG = 1 << 2, 107 wxAUI_MGR_TRANSPARENT_HINT = 1 << 3, 108 wxAUI_MGR_VENETIAN_BLINDS_HINT = 1 << 4, 109 wxAUI_MGR_RECTANGLE_HINT = 1 << 5, 110 wxAUI_MGR_HINT_FADE = 1 << 6, 111 wxAUI_MGR_NO_VENETIAN_BLINDS_FADE = 1 << 7, 112 wxAUI_MGR_LIVE_RESIZE = 1 << 8, 113 114 wxAUI_MGR_DEFAULT = wxAUI_MGR_ALLOW_FLOATING | 115 wxAUI_MGR_TRANSPARENT_HINT | 116 wxAUI_MGR_HINT_FADE | 117 wxAUI_MGR_NO_VENETIAN_BLINDS_FADE 118} 119\end{verbatim} 120 121 122\latexignore{\rtfignore{\wxheading{Members}}} 123 124 125\membersection{wxAuiManager::wxAuiManager}\label{wxauimanagerwxauimanager} 126 127\func{}{wxAuiManager}{\param{wxWindow* }{managed\_wnd = NULL}, \param{unsigned int }{flags = wxAUI\_MGR\_DEFAULT}} 128 129Constructor. \arg{managed\_wnd} specifies the wxFrame which should be managed. 130\arg{flags} specifies options which allow the frame management behavior 131to be modified. 132 133\membersection{wxAuiManager::\destruct{wxAuiManager}}\label{wxauimanagerdtor} 134 135\func{}{\destruct{wxAuiManager}}{\void} 136 137\membersection{wxAuiManager::AddPane}\label{wxauimanageraddpane} 138 139\func{bool}{AddPane}{\param{wxWindow* }{window}, \param{const wxAuiPaneInfo\& }{pane\_info}} 140 141\func{bool}{AddPane}{\param{wxWindow* }{window}, \param{int }{direction = wxLEFT}, \param{const wxString\& }{caption = wxEmptyString}} 142 143\func{bool}{AddPane}{\param{wxWindow* }{window}, \param{const wxAuiPaneInfo\& }{pane\_info}, \param{const wxPoint\& }{drop\_pos}} 144 145 146AddPane() tells the frame manager to start managing a child window. There are several versions of this function. The first version allows the full spectrum of pane parameter possibilities. The second version is used for simpler user interfaces which do not require as much configuration. The last version allows a drop position to be specified, which will determine where the pane will be added. 147 148\membersection{wxAuiManager::DetachPane}\label{wxauimanagerdetachpane} 149 150\func{bool}{DetachPane}{\param{wxWindow* }{window}} 151 152Tells the wxAuiManager to stop managing the pane specified by window. 153The window, if in a floated frame, is reparented to the frame managed 154by wxAuiManager. 155 156\membersection{wxAuiManager::GetAllPanes}\label{wxauimanagergetallpanes} 157 158\func{wxAuiPaneInfoArray\&}{GetAllPanes}{\void} 159 160Returns an array of all panes managed by the frame manager. 161 162\membersection{wxAuiManager::GetArtProvider}\label{wxauimanagergetartprovider} 163 164\constfunc{wxAuiDockArt*}{GetArtProvider}{\void} 165 166Returns the current art provider being used. 167 168See also: \helpref{wxAuiDockArt}{wxauidockart}. 169 170\membersection{wxAuiManager::GetDockSizeConstraint}\label{wxauimanagergetdocksizeconstraint} 171 172\func{void}{GetDockSizeConstraint}{\param{double* }{widthpct}, \param{double* }{heightpct}} 173 174Returns the current dock constraint values. See \helpref{SetDockSizeConstraint()}{wxauimanagersetdocksizeconstraint} for more information. 175 176\membersection{wxAuiManager::GetFlags}\label{wxauimanagergetflags} 177 178\constfunc{unsigned int}{GetFlags}{\void} 179 180Returns the current manager's flags. 181 182\membersection{wxAuiManager::GetManagedWindow}\label{wxauimanagergetmanagedwindow} 183 184\constfunc{wxWindow*}{GetManagedWindow}{\void} 185 186Returns the frame currently being managed by wxAuiManager. 187 188\membersection{wxAuiManager::GetManager}\label{wxauimanagergetmanager} 189 190\func{static wxAuiManager*}{GetManager}{\param{wxWindow* }{window}} 191 192Calling this method will return the wxAuiManager for a given window. The \arg{window} parameter should 193specify any child window or sub-child window of the frame or window managed by wxAuiManager. 194The \arg{window} parameter need not be managed by the manager itself, nor does it even need to be a child 195or sub-child of a managed window. It must however be inside the window hierarchy underneath the managed 196window. 197 198\membersection{wxAuiManager::GetPane}\label{wxauimanagergetpane} 199 200\func{wxAuiPaneInfo\&}{GetPane}{\param{wxWindow* }{window}} 201 202\func{wxAuiPaneInfo\&}{GetPane}{\param{const wxString\& }{name}} 203 204{\it GetPane} is used to lookup a wxAuiPaneInfo object 205either by window pointer or by pane name, which acts as a unique id for 206a window pane. The returned wxAuiPaneInfo object may then be modified to 207change a pane's look, state or position. After one or more 208modifications to wxAuiPaneInfo, wxAuiManager::Update() should be called 209to commit the changes to the user interface. If the lookup failed 210(meaning the pane could not be found in the manager), a call to the 211returned wxAuiPaneInfo's IsOk() method will return false. 212 213\membersection{wxAuiManager::HideHint}\label{wxauimanagerhidehint} 214 215\func{void}{HideHint}{\void} 216 217HideHint() hides any docking hint that may be visible. 218 219\membersection{wxAuiManager::InsertPane}\label{wxauimanagerinsertpane} 220 221\func{bool}{InsertPane}{\param{wxWindow* }{window}, \param{const wxAuiPaneInfo\& }{insert\_location}, \param{int }{insert\_level = wxAUI\_INSERT\_PANE}} 222 223This method is used to insert either a previously unmanaged pane window 224into the frame manager, or to insert a currently managed pane somewhere 225else. {\it InsertPane} will push all panes, rows, or docks aside and 226insert the window into the position specified by \arg{insert\_location}. 227Because \arg{insert\_location} can specify either a pane, dock row, or dock 228layer, the \arg{insert\_level} parameter is used to disambiguate this. The 229parameter \arg{insert\_level} can take a value of wxAUI\_INSERT\_PANE, wxAUI\_INSERT\_ROW 230or wxAUI\_INSERT\_DOCK. 231 232\membersection{wxAuiManager::LoadPaneInfo}\label{wxauimanagerloadpaneinfo} 233 234\func{void}{LoadPaneInfo}{\param{wxString }{pane\_part}, \param{wxAuiPaneInfo\& }{pane}} 235 236LoadPaneInfo() is similar to to LoadPerspective, with the exception that it only loads information about a single pane. It is used in combination with SavePaneInfo(). 237 238\membersection{wxAuiManager::LoadPerspective}\label{wxauimanagerloadperspective} 239 240\func{bool}{LoadPerspective}{\param{const wxString\& }{perspective}, \param{bool }{update = true}} 241 242Loads a saved perspective. If update is true, wxAuiManager::Update() 243is automatically invoked, thus realizing the saved perspective on screen. 244 245\membersection{wxAuiManager::ProcessDockResult}\label{wxauimanagerprocessdockresult} 246 247\func{bool}{ProcessDockResult}{\param{wxAuiPaneInfo\& }{target}, \param{const wxAuiPaneInfo\& }{new\_pos}} 248 249ProcessDockResult() is a protected member of the wxAUI layout manager. It can be overridden by derived classes to provide custom docking calculations. 250 251\membersection{wxAuiManager::SavePaneInfo}\label{wxauimanagersavepaneinfo} 252 253\func{wxString}{SavePaneInfo}{\param{wxAuiPaneInfo\& }{pane}} 254 255SavePaneInfo() is similar to SavePerspective, with the exception that it only saves information about a single pane. It is used in combination with LoadPaneInfo(). 256 257\membersection{wxAuiManager::SavePerspective}\label{wxauimanagersaveperspective} 258 259\func{wxString}{SavePerspective}{\void} 260 261Saves the entire user interface layout into an encoded wxString, which 262can then be stored by the application (probably using wxConfig). When 263a perspective is restored using LoadPerspective(), the entire user 264interface will return to the state it was when the perspective was saved. 265 266\membersection{wxAuiManager::SetArtProvider}\label{wxauimanagersetartprovider} 267 268\func{void}{SetArtProvider}{\param{wxAuiDockArt* }{art\_provider}} 269 270Instructs wxAuiManager to use art provider specified by parameter 271\arg{art\_provider} for all drawing calls. This allows plugable 272look-and-feel features. The previous art provider object, if any, 273will be deleted by wxAuiManager. 274 275See also: \helpref{wxAuiDockArt}{wxauidockart}. 276 277\membersection{wxAuiManager::SetDockSizeConstraint}\label{wxauimanagersetdocksizeconstraint} 278 279\func{void}{SetDockSizeConstraint}{\param{double }{widthpct}, \param{double }{heightpct}} 280 281When a user creates a new dock by dragging a window into a docked position, often times the large size of the 282window will create a dock that is unwieldly large. wxAuiManager by default limits the size of any 283new dock to 1/3 of the window size. For horizontal docks, this would be 1/3 of the window height. For 284vertical docks, 1/3 of the width. Calling this function will adjust this constraint value. The numbers 285must be between 0.0 and 1.0. For instance, calling SetDockSizeContraint with 0.5, 0.5 will cause new 286docks to be limited to half of the size of the entire managed window. 287 288\membersection{wxAuiManager::SetFlags}\label{wxauimanagersetflags} 289 290\func{void}{SetFlags}{\param{unsigned int }{flags}} 291 292This method is used to specify wxAuiManager's settings flags. \arg{flags} 293specifies options which allow the frame management behavior to be modified. 294 295\membersection{wxAuiManager::SetManagedWindow}\label{wxauimanagersetmanagedwindow} 296 297\func{void}{SetManagedWindow}{\param{wxWindow* }{managed\_wnd}} 298 299Called to specify the frame or window which is to be managed by wxAuiManager. Frame management is not restricted to just frames. Child windows or custom controls are also allowed. 300 301\membersection{wxAuiManager::ShowHint}\label{wxauimanagershowhint} 302 303\func{void}{ShowHint}{\param{const wxRect\& }{rect}} 304 305This function is used by controls to explicitly show a hint window at the specified rectangle. It is rarely called, and is mostly used by controls implementing custom pane drag/drop behaviour. The specified rectangle should be in screen coordinates. 306 307\membersection{wxAuiManager::UnInit}\label{wxauimanageruninit} 308 309\func{void}{UnInit}{\void} 310 311Uninitializes the framework and should be called before a managed frame or window is destroyed. UnInit() is usually called in the managed wxFrame's 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. 312 313\membersection{wxAuiManager::Update}\label{wxauimanagerupdate} 314 315\func{void}{Update}{\void} 316 317This method is called after any number of changes are 318made to any of the managed panes. Update() must be invoked after 319AddPane() or InsertPane() are called in order to "realize" or "commit" 320the changes. In addition, any number of changes may be made to 321wxAuiPaneInfo structures (retrieved with wxAuiManager::GetPane), but to 322realize the changes, Update() must be called. This construction allows 323pane flicker to be avoided by updating the whole layout at one time. 324 325