interface/aui/aui.h

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