interface/aui/aui.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        aui/aui.h
   3 // Purpose:     documentation for wxAuiManager class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxAuiManager
  11     @headerfile aui.h wx/aui/aui.h
  12
  13     wxAuiManager is the central class of the wxAUI class framework.
  14
  15     See also @ref overview_wxauioverview.
  16
  17     wxAuiManager manages the panes associated with it
  18     for a particular wxFrame, using a pane's wxAuiPaneInfo information to
  19     determine each pane's docking and floating behavior. wxAuiManager
  20     uses wxWidgets' sizer mechanism to plan the layout of each frame. It
  21     uses a replaceable dock art class to do all drawing, so all drawing is
  22     localized in one area, and may be customized depending on an
  23     application's specific needs.
  24
  25     wxAuiManager works as follows: the programmer adds panes to the class,
  26     or makes changes to existing pane properties (dock position, floating
  27     state, show state, etc.). To apply these changes, wxAuiManager's
  28     Update() function is called. This batch processing can be used to avoid
  29     flicker, by modifying more than one pane at a time, and then "committing"
  30     all of the changes at once by calling Update().
  31
  32     Panes can be added quite easily:
  33
  34     @code
  35     wxTextCtrl* text1 = new wxTextCtrl(this, -1);
  36     wxTextCtrl* text2 = new wxTextCtrl(this, -1);
  37     m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption"));
  38     m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption"));
  39     m_mgr.Update();
  40     @endcode
  41
  42     Later on, the positions can be modified easily. The following will float
  43     an existing pane in a tool window:
  44
  45     @code
  46     m_mgr.GetPane(text1).Float();
  47     @endcode
  48
  49     @library{wxbase}
  50     @category{aui}
  51
  52     @seealso
  53     wxAuiPaneInfo, wxAuiDockArt
  54 */
  55 class wxAuiManager : public wxEvtHandler
  56 {
  57 public:
  58     /**
  59         Constructor. @a managed_wnd specifies the wxFrame which should be managed.
  60         @a flags  specifies options which allow the frame management behavior
  61         to be modified.
  62     */
  63     wxAuiManager(wxWindow* managed_wnd = NULL,
  64                  unsigned int flags = wxAUI_MGR_DEFAULT);
  65
  66     /**
  67
  68     */
  69     ~wxAuiManager();
  70
  71     //@{
  72     /**
  73         AddPane() tells the frame manager to start managing a child window. There are
  74         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.
  75     */
  76     bool AddPane(wxWindow* window, const wxAuiPaneInfo& pane_info);
  77     bool AddPane(wxWindow* window, int direction = wxLEFT,
  78                  const wxString& caption = wxEmptyString);
  79     bool AddPane(wxWindow* window,
  80                  const wxAuiPaneInfo& pane_info,
  81                  const wxPoint& drop_pos);
  82     //@}
  83
  84     /**
  85         Tells the wxAuiManager to stop managing the pane specified by window.
  86         The window, if in a floated frame, is reparented to the frame managed
  87         by wxAuiManager.
  88     */
  89     bool DetachPane(wxWindow* window);
  90
  91     /**
  92         Returns an array of all panes managed by the frame manager.
  93     */
  94     wxAuiPaneInfoArray GetAllPanes();
  95
  96     /**
  97         Returns the current art provider being used.
  98         See also: wxAuiDockArt.
  99     */
 100     wxAuiDockArt* GetArtProvider() const;
 101
 102     /**
 103         Returns the current dock constraint values.  See SetDockSizeConstraint() for
 104         more information.
 105     */
 106     void GetDockSizeConstraint(double* widthpct, double* heightpct);
 107
 108     /**
 109         Returns the current manager's flags.
 110     */
 111     unsigned int GetFlags() const;
 112
 113     /**
 114         Returns the frame currently being managed by wxAuiManager.
 115     */
 116     wxWindow* GetManagedWindow() const;
 117
 118     /**
 119         Calling this method will return the wxAuiManager for a given window.  The @a
 120         window parameter should
 121         specify any child window or sub-child window of the frame or window managed by
 122         wxAuiManager.
 123         The @a window parameter need not be managed by the manager itself, nor does it
 124         even need to be a child
 125         or sub-child of a managed window.  It must however be inside the window
 126         hierarchy underneath the managed
 127         window.
 128     */
 129     static wxAuiManager* GetManager(wxWindow* window);
 130
 131     //@{
 132     /**
 133         @e GetPane is used to lookup a wxAuiPaneInfo object
 134         either by window pointer or by pane name, which acts as a unique id for
 135         a window pane. The returned wxAuiPaneInfo object may then be modified to
 136         change a pane's look, state or position. After one or more
 137         modifications to wxAuiPaneInfo, wxAuiManager::Update() should be called
 138         to commit the changes to the user interface. If the lookup failed
 139         (meaning the pane could not be found in the manager), a call to the
 140         returned wxAuiPaneInfo's IsOk() method will return @false.
 141     */
 142     wxAuiPaneInfo GetPane(wxWindow* window);
 143     wxAuiPaneInfo GetPane(const wxString& name);
 144     //@}
 145
 146     /**
 147         HideHint() hides any docking hint that may be visible.
 148     */
 149     void HideHint();
 150
 151     /**
 152         This method is used to insert either a previously unmanaged pane window
 153         into the frame manager, or to insert a currently managed pane somewhere
 154         else. @e InsertPane will push all panes, rows, or docks aside and
 155         insert the window into the position specified by @e insert_location.
 156         Because @a insert_location can specify either a pane, dock row, or dock
 157         layer, the @a insert_level parameter is used to disambiguate this. The
 158         parameter @a insert_level can take a value of wxAUI_INSERT_PANE,
 159         wxAUI_INSERT_ROW
 160         or wxAUI_INSERT_DOCK.
 161     */
 162     bool InsertPane(wxWindow* window,
 163                     const wxAuiPaneInfo& insert_location,
 164                     int insert_level = wxAUI_INSERT_PANE);
 165
 166     /**
 167         LoadPaneInfo() is similar to to LoadPerspective, with the exception that it
 168         only loads information about a single pane.  It is used in combination with SavePaneInfo().
 169     */
 170     void LoadPaneInfo(wxString pane_part, wxAuiPaneInfo& pane);
 171
 172     /**
 173         Loads a saved perspective. If update is @true, wxAuiManager::Update()
 174         is automatically invoked, thus realizing the saved perspective on screen.
 175     */
 176     bool LoadPerspective(const wxString& perspective,
 177                          bool update = true);
 178
 179     /**
 180         ProcessDockResult() is a protected member of the wxAUI layout manager.  It can
 181         be overridden by derived classes to provide custom docking calculations.
 182     */
 183     bool ProcessDockResult(wxAuiPaneInfo& target,
 184                            const wxAuiPaneInfo& new_pos);
 185
 186     /**
 187         SavePaneInfo() is similar to SavePerspective, with the exception that it only
 188         saves information about a single pane.  It is used in combination with LoadPaneInfo().
 189     */
 190     wxString SavePaneInfo(wxAuiPaneInfo& pane);
 191
 192     /**
 193         Saves the entire user interface layout into an encoded wxString, which
 194         can then be stored by the application (probably using wxConfig). When
 195         a perspective is restored using LoadPerspective(), the entire user
 196         interface will return to the state it was when the perspective was saved.
 197     */
 198     wxString SavePerspective();
 199
 200     /**
 201         Instructs wxAuiManager to use art provider specified by parameter
 202         @a art_provider for all drawing calls. This allows plugable
 203         look-and-feel features. The previous art provider object, if any,
 204         will be deleted by wxAuiManager.
 205         See also: wxAuiDockArt.
 206     */
 207     void SetArtProvider(wxAuiDockArt* art_provider);
 208
 209     /**
 210         When a user creates a new dock by dragging a window into a docked position,
 211         often times the large size of the
 212         window will create a dock that is unwieldly large.  wxAuiManager by default
 213         limits the size of any
 214         new dock to 1/3 of the window size.  For horizontal docks, this would be 1/3 of
 215         the window height.  For
 216         vertical docks, 1/3 of the width.  Calling this function will adjust this
 217         constraint value.  The numbers
 218         must be between 0.0 and 1.0.  For instance, calling SetDockSizeContraint with
 219         0.5, 0.5 will cause new
 220         docks to be limited to half of the size of the entire managed window.
 221     */
 222     void SetDockSizeConstraint(double widthpct, double heightpct);
 223
 224     /**
 225         This method is used to specify wxAuiManager's settings flags. @e flags
 226         specifies options which allow the frame management behavior to be modified.
 227     */
 228     void SetFlags(unsigned int flags);
 229
 230     /**
 231         Called to specify the frame or window which is to be managed by wxAuiManager.
 232         Frame management is not restricted to just frames.  Child windows or custom controls are also allowed.
 233     */
 234     void SetManagedWindow(wxWindow* managed_wnd);
 235
 236     /**
 237         This function is used by controls to explicitly show a hint window at the
 238         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.
 239     */
 240     void ShowHint(const wxRect& rect);
 241
 242     /**
 243         Uninitializes the framework and should be called before a managed frame or
 244         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.
 245     */
 246     void UnInit();
 247
 248     /**
 249         This method is called after any number of changes are
 250         made to any of the managed panes. Update() must be invoked after
 251         AddPane() or InsertPane() are called in order to "realize" or "commit"
 252         the changes. In addition, any number of changes may be made to
 253         wxAuiPaneInfo structures (retrieved with wxAuiManager::GetPane), but to
 254         realize the changes, Update() must be called. This construction allows
 255         pane flicker to be avoided by updating the whole layout at one time.
 256     */
 257     void Update();
 258 };
 259
 260
 261 /**
 262     @class wxAuiPaneInfo
 263     @headerfile aui.h wx/aui/aui.h
 264
 265     wxAuiPaneInfo is part of the wxAUI class framework.
 266     See also @ref overview_wxauioverview.
 267
 268     wxAuiPaneInfo specifies all the parameters for a pane.
 269     These parameters specify where the pane is on the
 270     screen, whether it is docked or floating, or hidden.
 271     In addition, these parameters specify the pane's
 272     docked position, floating position, preferred size,
 273     minimum size, caption text among many other parameters.
 274
 275     @library{wxbase}
 276     @category{aui}
 277
 278     @seealso
 279     wxAuiManager, wxAuiDockArt
 280 */
 281 class wxAuiPaneInfo
 282 {
 283 public:
 284     //@{
 285     /**
 286         Copy constructor.
 287     */
 288     wxAuiPaneInfo();
 289     wxAuiPaneInfo(const wxAuiPaneInfo& c);
 290     //@}
 291
 292     //@{
 293     /**
 294         BestSize() sets the ideal size for the pane. The docking manager will attempt
 295         to use this size as much as possible when docking or floating the pane.
 296     */
 297     wxAuiPaneInfo BestSize(const wxSize& size);
 298     wxAuiPaneInfo BestSize(int x, int y);
 299     //@}
 300
 301     /**
 302         Bottom() sets the pane dock position to the bottom side of the frame. This is
 303         the same thing as calling Direction(wxAUI_DOCK_BOTTOM).
 304     */
 305     wxAuiPaneInfo Bottom();
 306
 307     /**
 308         BottomDockable() indicates whether a pane can be docked at the bottom of the
 309         frame.
 310     */
 311     wxAuiPaneInfo BottomDockable(bool b = true);
 312
 313     /**
 314         Caption() sets the caption of the pane.
 315     */
 316     wxAuiPaneInfo Caption(const wxString& c);
 317
 318     /**
 319         CaptionVisible indicates that a pane caption should be visible. If @false, no
 320         pane caption is drawn.
 321     */
 322     wxAuiPaneInfo CaptionVisible(bool visible = true);
 323
 324     //@{
 325     /**
 326         Center() sets the pane dock position to the left side of the frame.
 327         The centre pane is the space in the middle after all border panes (left, top,
 328         right, bottom) are subtracted from the layout.
 329         This is the same thing as calling Direction(wxAUI_DOCK_CENTRE).
 330     */
 331     wxAuiPaneInfo Centre();
 332     wxAuiPaneInfo Center();
 333     //@}
 334
 335     //@{
 336     /**
 337         CentrePane() specifies that the pane should adopt the default center pane
 338         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.
 339     */
 340     wxAuiPaneInfo CentrePane();
 341     wxAuiPaneInfo CenterPane();
 342     //@}
 343
 344     /**
 345         CloseButton() indicates that a close button should be drawn for the pane.
 346     */
 347     wxAuiPaneInfo CloseButton(bool visible = true);
 348
 349     /**
 350         DefaultPane() specifies that the pane should adopt the default pane settings.
 351     */
 352     wxAuiPaneInfo DefaultPane();
 353
 354     /**
 355         DestroyOnClose() indicates whether a pane should be detroyed when it is closed.
 356         Normally a pane is simply hidden when the close button is clicked. Setting DestroyOnClose to @true will cause the window to be destroyed when the user clicks the pane's close button.
 357     */
 358     wxAuiPaneInfo DestroyOnClose(bool b = true);
 359
 360     /**
 361         Direction() determines the direction of the docked pane. It is functionally the
 362         same as calling Left(), Right(), Top() or Bottom(), except that docking direction may be specified programmatically via the parameter.
 363     */
 364     wxAuiPaneInfo Direction(int direction);
 365
 366     /**
 367         Dock() indicates that a pane should be docked.  It is the opposite of Float().
 368     */
 369     wxAuiPaneInfo Dock();
 370
 371     /**
 372         DockFixed() causes the containing dock to have no resize sash.  This is useful
 373         for creating panes that span the entire width or height of a dock, but should not be resizable in the other direction.
 374     */
 375     wxAuiPaneInfo DockFixed(bool b = true);
 376
 377     /**
 378         Dockable() specifies whether a frame can be docked or not. It is the same as
 379         specifying TopDockable(b).BottomDockable(b).LeftDockable(b).RightDockable(b).
 380     */
 381     wxAuiPaneInfo Dockable(bool b = true);
 382
 383     /**
 384         Fixed() forces a pane to be fixed size so that it cannot be resized. After
 385         calling Fixed(), IsFixed() will return @true.
 386     */
 387     wxAuiPaneInfo Fixed();
 388
 389     /**
 390         Float() indicates that a pane should be floated.  It is the opposite of Dock().
 391     */
 392     wxAuiPaneInfo Float();
 393
 394     /**
 395         Floatable() sets whether the user will be able to undock a pane and turn it
 396         into a floating window.
 397     */
 398     wxAuiPaneInfo Floatable(bool b = true);
 399
 400     //@{
 401     /**
 402         FloatingPosition() sets the position of the floating pane.
 403     */
 404     wxAuiPaneInfo FloatingPosition(const wxPoint& pos);
 405     wxAuiPaneInfo FloatingPosition(int x, int y);
 406     //@}
 407
 408     //@{
 409     /**
 410         FloatingSize() sets the size of the floating pane.
 411     */
 412     wxAuiPaneInfo FloatingSize(const wxSize& size);
 413     wxAuiPaneInfo FloatingSize(int x, int y);
 414     //@}
 415
 416     /**
 417         Gripper() indicates that a gripper should be drawn for the pane.
 418     */
 419     wxAuiPaneInfo Gripper(bool visible = true);
 420
 421     /**
 422         GripperTop() indicates that a gripper should be drawn at the top of the pane.
 423     */
 424     wxAuiPaneInfo GripperTop(bool attop = true);
 425
 426     /**
 427         HasBorder() returns @true if the pane displays a border.
 428     */
 429     bool HasBorder() const;
 430
 431     /**
 432         HasCaption() returns @true if the pane displays a caption.
 433     */
 434     bool HasCaption() const;
 435
 436     /**
 437         HasCloseButton() returns @true if the pane displays a button to close the pane.
 438     */
 439     bool HasCloseButton() const;
 440
 441     /**
 442         HasFlag() returns @true if the the property specified by flag is active for the
 443         pane.
 444     */
 445     bool HasFlag(unsigned int flag) const;
 446
 447     /**
 448         HasGripper() returns @true if the pane displays a gripper.
 449     */
 450     bool HasGripper() const;
 451
 452     /**
 453         HasGripper() returns @true if the pane displays a gripper at the top.
 454     */
 455     bool HasGripperTop() const;
 456
 457     /**
 458         HasMaximizeButton() returns @true if the pane displays a button to maximize the
 459         pane.
 460     */
 461     bool HasMaximizeButton() const;
 462
 463     /**
 464         HasMinimizeButton() returns @true if the pane displays a button to minimize the
 465         pane.
 466     */
 467     bool HasMinimizeButton() const;
 468
 469     /**
 470         HasPinButton() returns @true if the pane displays a button to float the pane.
 471     */
 472     bool HasPinButton() const;
 473
 474     /**
 475         Hide() indicates that a pane should be hidden.
 476     */
 477     wxAuiPaneInfo Hide();
 478
 479     /**
 480         IsBottomDockable() returns @true if the pane can be docked at the bottom of the
 481         managed frame.
 482     */
 483     bool IsBottomDockable() const;
 484
 485     /**
 486         IsDocked() returns @true if the pane is docked.
 487     */
 488     bool IsDocked() const;
 489
 490     /**
 491         IsFixed() returns @true if the pane cannot be resized.
 492     */
 493     bool IsFixed() const;
 494
 495     /**
 496         IsFloatable() returns @true if the pane can be undocked and displayed as a
 497         floating window.
 498     */
 499     bool IsFloatable() const;
 500
 501     /**
 502         IsFloating() returns @true if the pane is floating.
 503     */
 504     bool IsFloating() const;
 505
 506     /**
 507         IsLeftDockable() returns @true if the pane can be docked on the left of the
 508         managed frame.
 509     */
 510     bool IsLeftDockable() const;
 511
 512     /**
 513         IsMoveable() returns @true if the docked frame can be undocked or moved to
 514         another dock position.
 515     */
 516     bool IsMovable() const;
 517
 518     /**
 519         IsOk() returns @true if the wxAuiPaneInfo structure is valid. A pane structure
 520         is valid if it has an associated window.
 521     */
 522     bool IsOk() const;
 523
 524     /**
 525         IsResizable() returns @true if the pane can be resized.
 526     */
 527     bool IsResizable() const;
 528
 529     /**
 530         IsRightDockable() returns @true if the pane can be docked on the right of the
 531         managed frame.
 532     */
 533     bool IsRightDockable() const;
 534
 535     /**
 536         IsShown() returns @true if the pane is currently shown.
 537     */
 538     bool IsShown() const;
 539
 540     /**
 541         IsToolbar() returns @true if the pane contains a toolbar.
 542     */
 543     bool IsToolbar() const;
 544
 545     /**
 546         IsTopDockable() returns @true if the pane can be docked at the top of the
 547         managed frame.
 548     */
 549     bool IsTopDockable() const;
 550
 551     /**
 552         Layer() determines the layer of the docked pane. The dock layer is similar to
 553         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.
 554     */
 555     wxAuiPaneInfo Layer(int layer);
 556
 557     /**
 558         Left() sets the pane dock position to the left side of the frame. This is the
 559         same thing as calling Direction(wxAUI_DOCK_LEFT).
 560     */
 561     wxAuiPaneInfo Left();
 562
 563     /**
 564         LeftDockable() indicates whether a pane can be docked on the left of the frame.
 565     */
 566     wxAuiPaneInfo LeftDockable(bool b = true);
 567
 568     //@{
 569     /**
 570         MaxSize() sets the maximum size of the pane.
 571     */
 572     wxAuiPaneInfo MaxSize(const wxSize& size);
 573     wxAuiPaneInfo MaxSize(int x, int y);
 574     //@}
 575
 576     /**
 577         MaximizeButton() indicates that a maximize button should be drawn for the pane.
 578     */
 579     wxAuiPaneInfo MaximizeButton(bool visible = true);
 580
 581     //@{
 582     /**
 583         MinSize() sets the minimum size of the pane. Please note that this is only
 584         partially supported as of this writing.
 585     */
 586     wxAuiPaneInfo MinSize(const wxSize& size);
 587     wxAuiPaneInfo MinSize(int x, int y);
 588     //@}
 589
 590     /**
 591         MinimizeButton() indicates that a minimize button should be drawn for the pane.
 592     */
 593     wxAuiPaneInfo MinimizeButton(bool visible = true);
 594
 595     /**
 596         Movable indicates whether a frame can be moved.
 597     */
 598     wxAuiPaneInfo Movable(bool b = true);
 599
 600     /**
 601         Name() sets the name of the pane so it can be referenced in lookup functions.
 602         If a name is not specified by the user, a random name is assigned to the pane when it is added to the manager.
 603     */
 604     wxAuiPaneInfo Name(const wxString& n);
 605
 606     /**
 607         PaneBorder indicates that a border should be drawn for the pane.
 608     */
 609     wxAuiPaneInfo PaneBorder(bool visible = true);
 610
 611     /**
 612         PinButton() indicates that a pin button should be drawn for the pane.
 613     */
 614     wxAuiPaneInfo PinButton(bool visible = true);
 615
 616     /**
 617         Position() determines the position of the docked pane.
 618     */
 619     wxAuiPaneInfo Position(int pos);
 620
 621     /**
 622         Resizable() allows a pane to be resized if the parameter is @true, and forces it
 623         to be a fixed size if the parameter is @false. This is simply an antonym for Fixed().
 624     */
 625     wxAuiPaneInfo Resizable(bool resizable = true);
 626
 627     /**
 628         Right() sets the pane dock position to the right side of the frame.
 629     */
 630     wxAuiPaneInfo Right();
 631
 632     /**
 633         RightDockable() indicates whether a pane can be docked on the right of the
 634         frame.
 635     */
 636     wxAuiPaneInfo RightDockable(bool b = true);
 637
 638     /**
 639         Row() determines the row of the docked pane.
 640     */
 641     wxAuiPaneInfo Row(int row);
 642
 643     /**
 644         Write the safe parts of a newly loaded PaneInfo structure "source" into "this"
 645         used on loading perspectives etc.
 646     */
 647     void SafeSet(wxAuiPaneInfo source);
 648
 649     /**
 650         SetFlag() turns the property given by flag on or off with the option_state
 651         parameter.
 652     */
 653     wxAuiPaneInfo SetFlag(unsigned int flag, bool option_state);
 654
 655     /**
 656         Show() indicates that a pane should be shown.
 657     */
 658     wxAuiPaneInfo Show(bool show = true);
 659
 660     /**
 661         ToolbarPane() specifies that the pane should adopt the default toolbar pane
 662         settings.
 663     */
 664     wxAuiPaneInfo ToolbarPane();
 665
 666     /**
 667         Top() sets the pane dock position to the top of the frame.
 668     */
 669     wxAuiPaneInfo Top();
 670
 671     /**
 672         TopDockable() indicates whether a pane can be docked at the top of the frame.
 673     */
 674     wxAuiPaneInfo TopDockable(bool b = true);
 675
 676     /**
 677         Window() assigns the window pointer that the wxAuiPaneInfo should use. This
 678         normally does not need to be specified, as the window pointer is automatically assigned to the wxAuiPaneInfo structure as soon as it is added to the manager.
 679     */
 680     wxAuiPaneInfo Window(wxWindow* w);
 681
 682     /**
 683         Makes a copy of the wxAuiPaneInfo object.
 684     */
 685     wxAuiPaneInfo& operator operator=(const wxAuiPaneInfo& c);
 686 };