interface/wx/sizer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        sizer.h
   3 // Purpose:     interface of wxStdDialogButtonSizer
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     @class wxSizer
  11
  12     wxSizer is the abstract base class used for laying out subwindows in a window.
  13     You cannot use wxSizer directly; instead, you will have to use one of the sizer
  14     classes derived from it. Currently there are wxBoxSizer, wxStaticBoxSizer,
  15     wxGridSizer, wxFlexGridSizer, wxWrapSizer and wxGridBagSizer.
  16
  17     The layout algorithm used by sizers in wxWidgets is closely related to layout
  18     in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit.
  19     It is based upon the idea of the individual subwindows reporting their minimal
  20     required size and their ability to get stretched if the size of the parent window
  21     has changed.
  22
  23     This will most often mean that the programmer does not set the original size of
  24     a dialog in the beginning, rather the dialog will be assigned a sizer and this
  25     sizer will be queried about the recommended size. The sizer in turn will query
  26     its children, which can be normal windows, empty space or other sizers, so that
  27     a hierarchy of sizers can be constructed. Note that wxSizer does not derive
  28     from wxWindow and thus does not interfere with tab ordering and requires very little
  29     resources compared to a real window on screen.
  30
  31     What makes sizers so well fitted for use in wxWidgets is the fact that every
  32     control reports its own minimal size and the algorithm can handle differences in
  33     font sizes or different window (dialog item) sizes on different platforms without
  34     problems. If e.g. the standard font as well as the overall design of Motif widgets
  35     requires more space than on Windows, the initial dialog size will automatically
  36     be bigger on Motif than on Windows.
  37
  38     Sizers may also be used to control the layout of custom drawn items on the
  39     window. The wxSizer::Add(), wxSizer::Insert(), and wxSizer::Prepend() functions
  40     return a pointer to the newly added wxSizerItem.
  41     Just add empty space of the desired size and attributes, and then use the
  42     wxSizerItem::GetRect() method to determine where the drawing operations
  43     should take place.
  44
  45     Please notice that sizers, like child windows, are owned by the library and
  46     will be deleted by it which implies that they must be allocated on the heap.
  47     However if you create a sizer and do not add it to another sizer or
  48     window, the library wouldn't be able to delete such an orphan sizer and in
  49     this, and only this, case it should be deleted explicitly.
  50
  51     @section wxsizer_flags wxSizer flags
  52
  53     The "flag" argument accepted by wxSizeItem constructors and other
  54     functions, e.g. wxSizer::Add(), is OR-combination of the following flags.
  55     Two main behaviours are defined using these flags. One is the border around
  56     a window: the border parameter determines the border width whereas the
  57     flags given here determine which side(s) of the item that the border will
  58     be added.  The other flags determine how the sizer item behaves when the
  59     space allotted to the sizer changes, and is somewhat dependent on the
  60     specific kind of sizer used.
  61
  62     @beginDefList
  63     @itemdef{wxTOP<br>
  64              wxBOTTOM<br>
  65              wxLEFT<br>
  66              wxRIGHT<br>
  67              wxALL,
  68              These flags are used to specify which side(s) of the sizer item
  69              the border width will apply to.}
  70     @itemdef{wxEXPAND,
  71              The item will be expanded to fill the space assigned to the item.}
  72     @itemdef{wxSHAPED,
  73              The item will be expanded as much as possible while also
  74              maintaining its aspect ratio.}
  75     @itemdef{wxFIXED_MINSIZE,
  76              Normally wxSizers will use GetAdjustedBestSize() to determine what
  77              the minimal size of window items should be, and will use that size
  78              to calculate the layout. This allows layouts to adjust when an
  79              item changes and its best size becomes different. If you would
  80              rather have a window item stay the size it started with then use
  81              @c wxFIXED_MINSIZE.}
  82     @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN,
  83              Normally wxSizers don't allocate space for hidden windows or other
  84              items. This flag overrides this behaviour so that sufficient space
  85              is allocated for the window even if it isn't visible. This makes
  86              it possible to dynamically show and hide controls without resizing
  87              parent dialog, for example. (Available since 2.8.8.)}
  88     @itemdef{wxALIGN_CENTER<br>
  89              wxALIGN_CENTRE<br>
  90              wxALIGN_LEFT<br>
  91              wxALIGN_RIGHT<br>
  92              wxALIGN_TOP<br>
  93              wxALIGN_BOTTOM<br>
  94              wxALIGN_CENTER_VERTICAL<br>
  95              wxALIGN_CENTRE_VERTICAL<br>
  96              wxALIGN_CENTER_HORIZONTAL<br>
  97              wxALIGN_CENTRE_HORIZONTAL,
  98              The @c wxALIGN_* flags allow you to specify the alignment of the item
  99              within the space allotted to it by the sizer, adjusted for the
 100              border if any.}
 101     @endDefList
 102
 103     @library{wxcore}
 104     @category{winlayout}
 105
 106     @see @ref overview_sizer
 107 */
 108 class wxSizer : public wxObject
 109 {
 110 public:
 111     /**
 112         The constructor.
 113         Note that wxSizer is an abstract base class and may not be instantiated.
 114     */
 115     wxSizer();
 116
 117     /**
 118         The destructor.
 119     */
 120     virtual ~wxSizer();
 121
 122     /**
 123         Appends a child to the sizer.
 124
 125         wxSizer itself is an abstract class, but the parameters are equivalent
 126         in the derived classes that you will instantiate to use it so they are
 127         described here:
 128
 129         @param window
 130             The window to be added to the sizer. Its initial size (either set
 131             explicitly by the user or calculated internally when using
 132             wxDefaultSize) is interpreted as the minimal and in many cases also
 133             the initial size.
 134         @param flags
 135             A wxSizerFlags object that enables you to specify most of the above
 136             parameters more conveniently.
 137     */
 138     wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags);
 139
 140     /**
 141         Appends a child to the sizer.
 142
 143         wxSizer itself is an abstract class, but the parameters are equivalent
 144         in the derived classes that you will instantiate to use it so they are
 145         described here:
 146
 147         @param window
 148             The window to be added to the sizer. Its initial size (either set
 149             explicitly by the user or calculated internally when using
 150             wxDefaultSize) is interpreted as the minimal and in many cases also
 151             the initial size.
 152         @param proportion
 153             Although the meaning of this parameter is undefined in wxSizer, it
 154             is used in wxBoxSizer to indicate if a child of a sizer can change
 155             its size in the main orientation of the wxBoxSizer - where 0 stands
 156             for not changeable and a value of more than zero is interpreted
 157             relative to the value of other children of the same wxBoxSizer. For
 158             example, you might have a horizontal wxBoxSizer with three
 159             children, two of which are supposed to change their size with the
 160             sizer. Then the two stretchable windows would get a value of 1 each
 161             to make them grow and shrink equally with the sizer's horizontal
 162             dimension.
 163         @param flag
 164             OR-combination of flags affecting sizer's behaviour. See
 165             @ref wxsizer_flags "wxSizer flags list" for details.
 166         @param border
 167             Determines the border width, if the flag parameter is set to
 168             include any border flag.
 169         @param userData
 170             Allows an extra object to be attached to the sizer item, for use in
 171             derived classes when sizing information is more complex than the
 172             proportion and flag will allow for.
 173     */
 174     wxSizerItem* Add(wxWindow* window,
 175                      int proportion = 0,
 176                      int flag = 0,
 177                      int border = 0,
 178                      wxObject* userData = NULL);
 179
 180     /**
 181         Appends a child to the sizer.
 182
 183         wxSizer itself is an abstract class, but the parameters are equivalent
 184         in the derived classes that you will instantiate to use it so they are
 185         described here:
 186
 187         @param sizer
 188             The (child-)sizer to be added to the sizer. This allows placing a
 189             child sizer in a sizer and thus to create hierarchies of sizers
 190             (typically a vertical box as the top sizer and several horizontal
 191             boxes on the level beneath).
 192         @param flags
 193             A wxSizerFlags object that enables you to specify most of the above
 194             parameters more conveniently.
 195     */
 196     wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags);
 197
 198     /**
 199         Appends a child to the sizer.
 200
 201         wxSizer itself is an abstract class, but the parameters are equivalent
 202         in the derived classes that you will instantiate to use it so they are
 203         described here:
 204
 205         @param sizer
 206             The (child-)sizer to be added to the sizer. This allows placing a
 207             child sizer in a sizer and thus to create hierarchies of sizers
 208             (typically a vertical box as the top sizer and several horizontal
 209             boxes on the level beneath).
 210         @param proportion
 211             Although the meaning of this parameter is undefined in wxSizer, it
 212             is used in wxBoxSizer to indicate if a child of a sizer can change
 213             its size in the main orientation of the wxBoxSizer - where 0 stands
 214             for not changeable and a value of more than zero is interpreted
 215             relative to the value of other children of the same wxBoxSizer. For
 216             example, you might have a horizontal wxBoxSizer with three
 217             children, two of which are supposed to change their size with the
 218             sizer. Then the two stretchable windows would get a value of 1 each
 219             to make them grow and shrink equally with the sizer's horizontal
 220             dimension.
 221         @param flag
 222             OR-combination of flags affecting sizer's behaviour. See
 223             @ref wxsizer_flags "wxSizer flags list" for details.
 224         @param border
 225             Determines the border width, if the flag parameter is set to
 226             include any border flag.
 227         @param userData
 228             Allows an extra object to be attached to the sizer item, for use in
 229             derived classes when sizing information is more complex than the
 230             proportion and flag will allow for.
 231     */
 232     wxSizerItem* Add(wxSizer* sizer,
 233                      int proportion = 0,
 234                      int flag = 0,
 235                      int border = 0,
 236                      wxObject* userData = NULL);
 237
 238     /**
 239         Appends a spacer child to the sizer.
 240
 241         wxSizer itself is an abstract class, but the parameters are equivalent
 242         in the derived classes that you will instantiate to use it so they are
 243         described here.
 244
 245         @a width and @a height specify the dimension of a spacer to be added to
 246         the sizer. Adding spacers to sizers gives more flexibility in the
 247         design of dialogs; imagine for example a horizontal box with two
 248         buttons at the bottom of a dialog: you might want to insert a space
 249         between the two buttons and make that space stretchable using the
 250         proportion flag and the result will be that the left button will be
 251         aligned with the left side of the dialog and the right button with the
 252         right side - the space in between will shrink and grow with the dialog.
 253
 254         @param width
 255             Width of the spacer.
 256         @param height
 257             Height of the spacer.
 258         @param proportion
 259             Although the meaning of this parameter is undefined in wxSizer, it
 260             is used in wxBoxSizer to indicate if a child of a sizer can change
 261             its size in the main orientation of the wxBoxSizer - where 0 stands
 262             for not changeable and a value of more than zero is interpreted
 263             relative to the value of other children of the same wxBoxSizer. For
 264             example, you might have a horizontal wxBoxSizer with three
 265             children, two of which are supposed to change their size with the
 266             sizer. Then the two stretchable windows would get a value of 1 each
 267             to make them grow and shrink equally with the sizer's horizontal
 268             dimension.
 269         @param flag
 270             OR-combination of flags affecting sizer's behaviour. See
 271             @ref wxsizer_flags "wxSizer flags list" for details.
 272         @param border
 273             Determines the border width, if the flag parameter is set to
 274             include any border flag.
 275         @param userData
 276             Allows an extra object to be attached to the sizer item, for use in
 277             derived classes when sizing information is more complex than the
 278             proportion and flag will allow for.
 279     */
 280     wxSizerItem* Add(int width, int height,
 281                      int proportion = 0,
 282                      int flag = 0,
 283                      int border = 0,
 284                      wxObject* userData = NULL);
 285
 286     /**
 287         Appends a spacer child to the sizer.
 288
 289         @param width
 290             Width of the spacer.
 291         @param height
 292             Height of the spacer.
 293         @param flags
 294             A wxSizerFlags object that enables you to specify most of the other
 295             parameters more conveniently.
 296     */
 297     wxSizerItem* Add( int width, int height, const wxSizerFlags& flags);
 298
 299     wxSizerItem* Add(wxSizerItem* item);
 300
 301     /**
 302         This base function adds non-stretchable space to both the horizontal
 303         and vertical orientation of the sizer.
 304         More readable way of calling:
 305         @code
 306         wxSizer::Add(size, size, 0).
 307         @endcode
 308         @see wxBoxSizer::AddSpacer()
 309     */
 310     virtual wxSizerItem *AddSpacer(int size);
 311
 312     /**
 313         Adds stretchable space to the sizer.
 314         More readable way of calling:
 315         @code
 316         wxSizer::Add(0, 0, prop).
 317         @endcode
 318     */
 319     wxSizerItem* AddStretchSpacer(int prop = 1);
 320
 321     /**
 322         This method is abstract and has to be overwritten by any derived class.
 323         Here, the sizer will do the actual calculation of its children's minimal sizes.
 324     */
 325     virtual wxSize CalcMin() = 0;
 326
 327     /**
 328         Detaches all children from the sizer.
 329
 330         If @a delete_windows is @true then child windows will also be deleted.
 331
 332         Notice that child sizers are always deleted, as a general consequence
 333         of the principle that sizers own their sizer children, but don't own
 334         their window children (because they are already owned by their parent
 335         windows).
 336     */
 337     virtual void Clear(bool delete_windows = false);
 338
 339     /**
 340         Computes client area size for @a window so that it matches the sizer's
 341         minimal size. Unlike GetMinSize(), this method accounts for other
 342         constraints imposed on @e window, namely display's size (returned size
 343         will never be too large for the display) and maximum window size if
 344         previously set by wxWindow::SetMaxSize().
 345
 346         The returned value is suitable for passing to wxWindow::SetClientSize() or
 347         wxWindow::SetMinClientSize().
 348
 349         @since 2.8.8
 350
 351         @see ComputeFittingWindowSize(), Fit()
 352     */
 353     wxSize ComputeFittingClientSize(wxWindow* window);
 354
 355     /**
 356         Like ComputeFittingClientSize(), but converts the result into window
 357         size. The returned value is suitable for passing to wxWindow::SetSize()
 358         or wxWindow::SetMinSize().
 359
 360         @since 2.8.8
 361
 362         @see ComputeFittingClientSize(), Fit()
 363     */
 364     wxSize ComputeFittingWindowSize(wxWindow* window);
 365
 366     /**
 367         Detach the child @a window from the sizer without destroying it.
 368
 369         This method does not cause any layout or resizing to take place, call Layout()
 370         to update the layout "on screen" after detaching a child from the sizer.
 371
 372         Returns @true if the child item was found and detached, @false otherwise.
 373
 374         @see Remove()
 375     */
 376     virtual bool Detach(wxWindow* window);
 377
 378     /**
 379         Detach the child @a sizer from the sizer without destroying it.
 380
 381         This method does not cause any layout or resizing to take place, call Layout()
 382         to update the layout "on screen" after detaching a child from the sizer.
 383
 384         Returns @true if the child item was found and detached, @false otherwise.
 385
 386         @see Remove()
 387     */
 388     virtual bool Detach(wxSizer* sizer);
 389
 390     /**
 391         Detach a item at position @a index from the sizer without destroying it.
 392
 393         This method does not cause any layout or resizing to take place, call Layout()
 394         to update the layout "on screen" after detaching a child from the sizer.
 395         Returns @true if the child item was found and detached, @false otherwise.
 396
 397         @see Remove()
 398     */
 399     virtual bool Detach(int index);
 400
 401     /**
 402         Tell the sizer to resize the @a window so that its client area matches the
 403         sizer's minimal size (ComputeFittingClientSize() is called to determine it).
 404         This is commonly done in the constructor of the window itself, see sample
 405         in the description of wxBoxSizer.
 406
 407         @return The new window size.
 408
 409         @see ComputeFittingClientSize(), ComputeFittingWindowSize()
 410     */
 411     wxSize Fit(wxWindow* window);
 412
 413     /**
 414         Tell the sizer to resize the virtual size of the @a window to match the sizer's
 415         minimal size. This will not alter the on screen size of the window, but may
 416         cause the addition/removal/alteration of scrollbars required to view the virtual
 417         area in windows which manage it.
 418
 419         @see wxScrolled::SetScrollbars(), SetVirtualSizeHints()
 420     */
 421     void FitInside(wxWindow* window);
 422
 423     /**
 424        Inform sizer about the first direction that has been decided (by
 425        parent item).  Returns true if it made use of the information (and
 426        recalculated min size).
 427     */
 428     virtual bool InformFirstDirection(int direction, int size, int availableOtherDir);
 429
 430
 431     //@{
 432     /**
 433         Returns the list of the items in this sizer.
 434
 435         The elements of type-safe wxList @c wxSizerItemList are pointers to
 436         objects of type wxSizerItem.
 437     */
 438     wxSizerItemList& GetChildren();
 439     const wxSizerItemList& GetChildren() const;
 440     //@}
 441
 442     /**
 443         Returns the window this sizer is used in or @NULL if none.
 444     */
 445     wxWindow* GetContainingWindow() const;
 446
 447     /**
 448        Set the window this sizer is used in.
 449     */
 450     void SetContainingWindow(wxWindow *window);
 451
 452     /**
 453        Returns the number of items in the sizer.
 454
 455        If you just need to test whether the sizer is empty or not you can also
 456        use IsEmpty() function.
 457     */
 458     size_t GetItemCount() const;
 459
 460     /**
 461         Finds wxSizerItem which holds the given @a window.
 462         Use parameter @a recursive to search in subsizers too.
 463         Returns pointer to item or @NULL.
 464     */
 465     wxSizerItem* GetItem(wxWindow* window, bool recursive = false);
 466
 467     /**
 468         Finds wxSizerItem which holds the given @a sizer.
 469         Use parameter @a recursive to search in subsizers too.
 470         Returns pointer to item or @NULL.
 471     */
 472
 473     wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false);
 474
 475     /**
 476         Finds wxSizerItem which is located in the sizer at position @a index.
 477         Use parameter @a recursive to search in subsizers too.
 478         Returns pointer to item or @NULL.
 479     */
 480     wxSizerItem* GetItem(size_t index);
 481
 482     /**
 483         Finds item of the sizer which has the given @e id.
 484         This @a id is not the window id but the id of the wxSizerItem itself.
 485         This is mainly useful for retrieving the sizers created from XRC resources.
 486         Use parameter @a recursive to search in subsizers too.
 487         Returns pointer to item or @NULL.
 488     */
 489     wxSizerItem* GetItemById(int id, bool recursive = false);
 490
 491     /**
 492         Returns the minimal size of the sizer.
 493
 494         This is either the combined minimal size of all the children and their
 495         borders or the minimal size set by SetMinSize(), depending on which is bigger.
 496         Note that the returned value is client size, not window size.
 497         In particular, if you use the value to set toplevel window's minimal or
 498         actual size, use wxWindow::SetMinClientSize() or wxWindow::SetClientSize(),
 499         not wxWindow::SetMinSize() or wxWindow::SetSize().
 500     */
 501     wxSize GetMinSize();
 502
 503     /**
 504         Returns the current position of the sizer.
 505     */
 506     wxPoint GetPosition() const;
 507
 508     /**
 509         Returns the current size of the sizer.
 510     */
 511     wxSize GetSize() const;
 512
 513     /**
 514         Hides the child @a window.
 515
 516         To make a sizer item disappear, use Hide() followed by Layout().
 517
 518         Use parameter @a recursive to hide elements found in subsizers.
 519         Returns @true if the child item was found, @false otherwise.
 520
 521         @see IsShown(), Show()
 522     */
 523     bool Hide(wxWindow* window, bool recursive = false);
 524
 525     /**
 526         Hides the child @a sizer.
 527
 528         To make a sizer item disappear, use Hide() followed by Layout().
 529
 530         Use parameter @a recursive to hide elements found in subsizers.
 531         Returns @true if the child item was found, @false otherwise.
 532
 533         @see IsShown(), Show()
 534     */
 535     bool Hide(wxSizer* sizer, bool recursive = false);
 536
 537     /**
 538         Hides the item at position @a index.
 539
 540         To make a sizer item disappear, use Hide() followed by Layout().
 541
 542         Use parameter @a recursive to hide elements found in subsizers.
 543         Returns @true if the child item was found, @false otherwise.
 544
 545         @see IsShown(), Show()
 546     */
 547     bool Hide(size_t index);
 548
 549     /**
 550         Insert a child into the sizer before any existing item at @a index.
 551
 552         See Add() for the meaning of the other parameters.
 553     */
 554     wxSizerItem* Insert(size_t index, wxWindow* window,
 555                         const wxSizerFlags& flags);
 556
 557     /**
 558         Insert a child into the sizer before any existing item at @a index.
 559
 560         See Add() for the meaning of the other parameters.
 561     */
 562     wxSizerItem* Insert(size_t index, wxWindow* window,
 563                         int proportion = 0,
 564                         int flag = 0,
 565                         int border = 0,
 566                         wxObject* userData = NULL);
 567
 568     /**
 569         Insert a child into the sizer before any existing item at @a index.
 570
 571         See Add() for the meaning of the other parameters.
 572     */
 573     wxSizerItem* Insert(size_t index, wxSizer* sizer,
 574                         const wxSizerFlags& flags);
 575
 576     /**
 577         Insert a child into the sizer before any existing item at @a index.
 578
 579         See Add() for the meaning of the other parameters.
 580     */
 581     wxSizerItem* Insert(size_t index, wxSizer* sizer,
 582                         int proportion = 0,
 583                         int flag = 0,
 584                         int border = 0,
 585                         wxObject* userData = NULL);
 586
 587     /**
 588         Insert a child into the sizer before any existing item at @a index.
 589
 590         See Add() for the meaning of the other parameters.
 591     */
 592     wxSizerItem* Insert(size_t index, int width, int height,
 593                         int proportion = 0,
 594                         int flag = 0,
 595                         int border = 0,
 596                         wxObject* userData = NULL);
 597     /**
 598         Insert a child into the sizer before any existing item at @a index.
 599
 600         See Add() for the meaning of the other parameters.
 601     */
 602     wxSizerItem* Insert(size_t index,
 603                         int width,
 604                         int height,
 605                         const wxSizerFlags& flags);
 606
 607     wxSizerItem* Insert(size_t index, wxSizerItem* item);
 608
 609     /**
 610         Inserts non-stretchable space to the sizer.
 611         More readable way of calling wxSizer::Insert(index, size, size).
 612     */
 613     wxSizerItem* InsertSpacer(size_t index, int size);
 614
 615     /**
 616         Inserts stretchable space to the sizer.
 617         More readable way of calling wxSizer::Insert(0, 0, prop).
 618     */
 619     wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1);
 620
 621     /**
 622         Return @true if the sizer has no elements.
 623
 624         @see GetItemCount()
 625      */
 626     bool IsEmpty() const;
 627
 628     /**
 629         Returns @true if the @a window is shown.
 630
 631         @see Hide(), Show(), wxSizerItem::IsShown()
 632     */
 633     bool IsShown(wxWindow* window) const;
 634
 635     /**
 636         Returns @true if the @a sizer is shown.
 637
 638         @see Hide(), Show(), wxSizerItem::IsShown()
 639     */
 640     bool IsShown(wxSizer* sizer) const;
 641
 642     /**
 643         Returns @true if the item at @a index is shown.
 644
 645         @see Hide(), Show(), wxSizerItem::IsShown()
 646     */
 647     bool IsShown(size_t index) const;
 648
 649     /**
 650         Call this to force layout of the children anew, e.g.\ after having added a child
 651         to or removed a child (window, other sizer or space) from the sizer while
 652         keeping the current dimension.
 653     */
 654     virtual void Layout();
 655
 656     /**
 657         Same as Add(), but prepends the items to the beginning of the
 658         list of items (windows, subsizers or spaces) owned by this sizer.
 659     */
 660     wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags);
 661
 662     /**
 663         Same as Add(), but prepends the items to the beginning of the
 664         list of items (windows, subsizers or spaces) owned by this sizer.
 665     */
 666     wxSizerItem* Prepend(wxWindow* window, int proportion = 0,
 667                          int flag = 0,
 668                          int border = 0,
 669                          wxObject* userData = NULL);
 670
 671     /**
 672         Same as Add(), but prepends the items to the beginning of the
 673         list of items (windows, subsizers or spaces) owned by this sizer.
 674     */
 675     wxSizerItem* Prepend(wxSizer* sizer,
 676                          const wxSizerFlags& flags);
 677
 678     /**
 679         Same as Add(), but prepends the items to the beginning of the
 680         list of items (windows, subsizers or spaces) owned by this sizer.
 681     */
 682     wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0,
 683                          int flag = 0,
 684                          int border = 0,
 685                          wxObject* userData = NULL);
 686
 687     /**
 688         Same as Add(), but prepends the items to the beginning of the
 689         list of items (windows, subsizers or spaces) owned by this sizer.
 690     */
 691     wxSizerItem* Prepend(int width, int height,
 692                          int proportion = 0,
 693                          int flag = 0,
 694                          int border = 0,
 695                          wxObject* userData = NULL);
 696
 697     /**
 698         Same as Add(), but prepends the items to the beginning of the
 699         list of items (windows, subsizers or spaces) owned by this sizer.
 700     */
 701     wxSizerItem* Prepend(int width, int height, const wxSizerFlags& flags);
 702
 703     wxSizerItem* Prepend(wxSizerItem* item);
 704
 705     /**
 706         Prepends non-stretchable space to the sizer.
 707         More readable way of calling wxSizer::Prepend(size, size, 0).
 708     */
 709     wxSizerItem* PrependSpacer(int size);
 710
 711     /**
 712         Prepends stretchable space to the sizer.
 713         More readable way of calling wxSizer::Prepend(0, 0, prop).
 714     */
 715     wxSizerItem* PrependStretchSpacer(int prop = 1);
 716
 717     /**
 718         This method is abstract and has to be overwritten by any derived class.
 719         Here, the sizer will do the actual calculation of its children's
 720         positions and sizes.
 721     */
 722     virtual void RecalcSizes() = 0;
 723
 724     /**
 725         Removes a child window from the sizer, but does @b not destroy it
 726         (because windows are owned by their parent window, not the sizer).
 727
 728         @deprecated
 729         The overload of this method taking a wxWindow* parameter
 730         is deprecated as it does not destroy the window as would usually be
 731         expected from Remove(). You should use Detach() in new code instead.
 732         There is currently no wxSizer method that will both detach and destroy
 733         a wxWindow item.
 734
 735         @note This method does not cause any layout or resizing to take
 736               place, call Layout() to update the layout "on screen" after
 737               removing a child from the sizer.
 738
 739         @return @true if the child item was found and removed, @false otherwise.
 740     */
 741     virtual bool Remove(wxWindow* window);
 742
 743     /**
 744         Removes a sizer child from the sizer and destroys it.
 745
 746         @note This method does not cause any layout or resizing to take
 747               place, call Layout() to update the layout "on screen" after
 748               removing a child from the sizer.
 749
 750         @param sizer The wxSizer to be removed.
 751
 752         @return @true if the child item was found and removed, @false otherwise.
 753     */
 754     virtual bool Remove(wxSizer* sizer);
 755
 756     /**
 757         Removes a child from the sizer and destroys it if it is a sizer or a
 758         spacer, but not if it is a window (because windows are owned by their
 759         parent window, not the sizer).
 760
 761         @note This method does not cause any layout or resizing to take
 762               place, call Layout() to update the layout "on screen" after
 763               removing a child from the sizer.
 764
 765         @param index
 766             The position of the child in the sizer, e.g. 0 for the first item.
 767
 768         @return @true if the child item was found and removed, @false otherwise.
 769     */
 770     virtual bool Remove(int index);
 771
 772     /**
 773         Detaches the given @a oldwin from the sizer and replaces it with the
 774         given @a newwin. The detached child window is @b not deleted (because
 775         windows are owned by their parent window, not the sizer).
 776
 777         Use parameter @a recursive to search the given element recursively in subsizers.
 778
 779         This method does not cause any layout or resizing to take place,
 780         call Layout() to update the layout "on screen" after replacing a
 781         child from the sizer.
 782
 783         Returns @true if the child item was found and removed, @false otherwise.
 784     */
 785     virtual bool Replace(wxWindow* oldwin, wxWindow* newwin,
 786                          bool recursive = false);
 787
 788     /**
 789         Detaches the given @a oldsz from the sizer and replaces it with the
 790         given @a newsz. The detached child sizer is deleted.
 791
 792         Use parameter @a recursive to search the given element recursively in subsizers.
 793
 794         This method does not cause any layout or resizing to take place,
 795         call Layout() to update the layout "on screen" after replacing a
 796         child from the sizer.
 797
 798         Returns @true if the child item was found and removed, @false otherwise.
 799     */
 800     virtual bool Replace(wxSizer* oldsz, wxSizer* newsz,
 801                          bool recursive = false);
 802
 803     /**
 804         Detaches the given item at position @a index from the sizer and
 805         replaces it with the given wxSizerItem @a newitem.
 806
 807         The detached child is deleted @b only if it is a sizer or a spacer
 808         (but not if it is a wxWindow because windows are owned by their
 809         parent window, not the sizer).
 810
 811         This method does not cause any layout or resizing to take place,
 812         call Layout() to update the layout "on screen" after replacing a
 813         child from the sizer.
 814
 815         Returns @true if the child item was found and removed, @false otherwise.
 816     */
 817     virtual bool Replace(size_t index, wxSizerItem* newitem);
 818
 819     /**
 820         Call this to force the sizer to take the given dimension and thus force
 821         the items owned by the sizer to resize themselves according to the
 822         rules defined by the parameter in the Add() and Prepend() methods.
 823     */
 824     void SetDimension(int x, int y, int width, int height);
 825
 826     /**
 827         @overload
 828      */
 829     void SetDimension(const wxPoint& pos, const wxSize& size);
 830
 831     /**
 832         Set an item's minimum size by window, sizer, or position.
 833
 834         This function enables an application to set the size of an item after
 835         initial creation.
 836
 837         The @a window or @a sizer will be found recursively in the sizer's
 838         descendants.
 839
 840         @see wxSizerItem::SetMinSize()
 841
 842         @return
 843             @true if the minimal size was successfully set or @false if the
 844             item was not found.
 845     */
 846     //@{
 847     bool SetItemMinSize(wxWindow* window, int width, int height);
 848     bool SetItemMinSize(wxWindow* window, const wxSize& size);
 849
 850     bool SetItemMinSize(wxSizer* sizer, int width, int height);
 851     bool SetItemMinSize(wxSizer* sizer, const wxSize& size);
 852
 853     bool SetItemMinSize(size_t index, int width, int height);
 854     bool SetItemMinSize(size_t index, const wxSize& size);
 855     //@}
 856
 857     /**
 858         Call this to give the sizer a minimal size.
 859
 860         Normally, the sizer will calculate its minimal size based purely on how
 861         much space its children need. After calling this method GetMinSize()
 862         will return either the minimal size as requested by its children or the
 863         minimal size set here, depending on which is bigger.
 864     */
 865     void SetMinSize(const wxSize& size);
 866
 867     /**
 868         @overload
 869      */
 870     void SetMinSize(int width, int height);
 871
 872     /**
 873         This method first calls Fit() and then wxTopLevelWindow::SetSizeHints()
 874         on the @a window passed to it.
 875
 876         This only makes sense when @a window is actually a wxTopLevelWindow such
 877         as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes.
 878         It does nothing in normal windows or controls.
 879
 880         This method is implicitly used by wxWindow::SetSizerAndFit() which is
 881         commonly invoked in the constructor of a toplevel window itself (see
 882         the sample in the description of wxBoxSizer) if the toplevel window is
 883         resizable.
 884     */
 885     void SetSizeHints(wxWindow* window);
 886
 887     /**
 888         Tell the sizer to set the minimal size of the @a window virtual area to match
 889         the sizer's minimal size. For windows with managed scrollbars this will set them
 890         appropriately.
 891
 892         @deprecated This is exactly the same as FitInside() in wxWidgets 2.9
 893         and later, please replace calls to it with FitInside().
 894
 895         @see wxScrolled::SetScrollbars()
 896     */
 897     void SetVirtualSizeHints(wxWindow* window);
 898
 899     /**
 900         Shows or hides the @a window.
 901         To make a sizer item disappear or reappear, use Show() followed by Layout().
 902
 903         Use parameter @a recursive to show or hide elements found in subsizers.
 904
 905         Returns @true if the child item was found, @false otherwise.
 906
 907         @see Hide(), IsShown()
 908     */
 909     bool Show(wxWindow* window, bool show = true,
 910               bool recursive = false);
 911
 912     /**
 913         Shows or hides @a sizer.
 914         To make a sizer item disappear or reappear, use Show() followed by Layout().
 915
 916         Use parameter @a recursive to show or hide elements found in subsizers.
 917
 918         Returns @true if the child item was found, @false otherwise.
 919
 920         @see Hide(), IsShown()
 921     */
 922     bool Show(wxSizer* sizer, bool show = true,
 923               bool recursive = false);
 924
 925     /**
 926         Shows the item at @a index.
 927         To make a sizer item disappear or reappear, use Show() followed by Layout().
 928
 929         Returns @true if the child item was found, @false otherwise.
 930
 931         @see Hide(), IsShown()
 932     */
 933     bool Show(size_t index, bool show = true);
 934
 935
 936     /**
 937        Show or hide all items managed by the sizer.
 938     */
 939     virtual void ShowItems(bool show);
 940
 941 };
 942
 943
 944 /**
 945     @class wxStdDialogButtonSizer
 946
 947     This class creates button layouts which conform to the standard button spacing
 948     and ordering defined by the platform or toolkit's user interface guidelines
 949     (if such things exist). By using this class, you can ensure that all your
 950     standard dialogs look correct on all major platforms. Currently it conforms to
 951     the Windows, GTK+ and Mac OS X human interface guidelines.
 952
 953     When there aren't interface guidelines defined for a particular platform or
 954     toolkit, wxStdDialogButtonSizer reverts to the Windows implementation.
 955
 956     To use this class, first add buttons to the sizer by calling
 957     wxStdDialogButtonSizer::AddButton (or wxStdDialogButtonSizer::SetAffirmativeButton,
 958     wxStdDialogButtonSizer::SetNegativeButton or wxStdDialogButtonSizer::SetCancelButton)
 959     and then call Realize in order to create the actual button layout used.
 960     Other than these special operations, this sizer works like any other sizer.
 961
 962     If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to
 963     "Save" and the wxID_NO button will be renamed to "Don't Save" in accordance
 964     with the Mac OS X Human Interface Guidelines.
 965
 966     @library{wxcore}
 967     @category{winlayout}
 968
 969     @see wxSizer, @ref overview_sizer, wxDialog::CreateButtonSizer
 970 */
 971 class wxStdDialogButtonSizer : public wxBoxSizer
 972 {
 973 public:
 974     /**
 975         Constructor for a wxStdDialogButtonSizer.
 976     */
 977     wxStdDialogButtonSizer();
 978
 979     /**
 980         Adds a button to the wxStdDialogButtonSizer. The @a button must have
 981         one of the following identifiers:
 982          - wxID_OK
 983          - wxID_YES
 984          - wxID_SAVE
 985          - wxID_APPLY
 986          - wxID_CLOSE
 987          - wxID_NO
 988          - wxID_CANCEL
 989          - wxID_HELP
 990          - wxID_CONTEXT_HELP
 991     */
 992     void AddButton(wxButton* button);
 993
 994     /**
 995         Rearranges the buttons and applies proper spacing between buttons to make
 996         them match the platform or toolkit's interface guidelines.
 997     */
 998     void Realize();
 999
1000     /**
1001         Sets the affirmative button for the sizer.
1002
1003         This allows you to use identifiers other than the standard identifiers
1004         outlined above.
1005     */
1006     void SetAffirmativeButton(wxButton* button);
1007
1008     /**
1009         Sets the cancel button for the sizer.
1010
1011         This allows you to use identifiers other than the standard identifiers
1012         outlined above.
1013     */
1014     void SetCancelButton(wxButton* button);
1015
1016     /**
1017         Sets the negative button for the sizer.
1018
1019         This allows you to use identifiers other than the standard identifiers
1020         outlined above.
1021     */
1022     void SetNegativeButton(wxButton* button);
1023
1024     virtual void RecalcSizes();
1025     virtual wxSize CalcMin();
1026 };
1027
1028
1029
1030 /**
1031     @class wxSizerItem
1032
1033     The wxSizerItem class is used to track the position, size and other
1034     attributes of each item managed by a wxSizer.
1035
1036     It is not usually necessary to use this class because the sizer elements can
1037     also be identified by their positions or window or sizer pointers but sometimes
1038     it may be more convenient to use it directly.
1039
1040     @library{wxcore}
1041     @category{winlayout}
1042 */
1043 class wxSizerItem : public wxObject
1044 {
1045 public:
1046     /**
1047         Construct a sizer item for tracking a spacer.
1048     */
1049     wxSizerItem(int width, int height, int proportion=0, int flag=0,
1050                 int border=0, wxObject* userData=NULL);
1051
1052     //@{
1053     /**
1054         Construct a sizer item for tracking a window.
1055     */
1056     wxSizerItem(wxWindow* window, const wxSizerFlags& flags);
1057     wxSizerItem(wxWindow* window, int proportion=0, int flag=0,
1058                 int border=0,
1059                 wxObject* userData=NULL);
1060     //@}
1061
1062     //@{
1063     /**
1064         Construct a sizer item for tracking a subsizer.
1065     */
1066     wxSizerItem(wxSizer* sizer, const wxSizerFlags& flags);
1067     wxSizerItem(wxSizer* sizer, int proportion=0, int flag=0,
1068                 int border=0,
1069                 wxObject* userData=NULL);
1070     //@}
1071
1072     /**
1073         Deletes the user data and subsizer, if any.
1074     */
1075     virtual ~wxSizerItem();
1076
1077     /**
1078         Set the window to be tracked by this item.
1079
1080         The old window isn't deleted as it is now owned by the sizer item.
1081     */
1082     void AssignWindow(wxWindow *window);
1083
1084     /**
1085         Set the sizer tracked by this item.
1086
1087         Old sizer, if any, is deleted.
1088     */
1089     void AssignSizer(wxSizer *sizer);
1090
1091     //@{
1092     /**
1093         Set the size of the spacer tracked by this item.
1094
1095         Old spacer, if any, is deleted.
1096     */
1097     void AssignSpacer(const wxSize& size);
1098     void AssignSpacer(int w, int h);
1099     //@}
1100
1101     /**
1102         Calculates the minimum desired size for the item, including any space
1103         needed by borders.
1104     */
1105     virtual wxSize CalcMin();
1106
1107     /**
1108         Destroy the window or the windows in a subsizer, depending on the type
1109         of item.
1110     */
1111     virtual void DeleteWindows();
1112
1113     /**
1114         Enable deleting the SizerItem without destroying the contained sizer.
1115     */
1116     void DetachSizer();
1117
1118     /**
1119         Return the border attribute.
1120     */
1121     int GetBorder() const;
1122
1123     /**
1124         Return the flags attribute.
1125
1126         See @ref wxsizer_flags "wxSizer flags list" for details.
1127     */
1128     int GetFlag() const;
1129
1130     /**
1131         Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has
1132         not been set.
1133     */
1134     int GetId() const;
1135
1136     /**
1137         Get the minimum size needed for the item.
1138     */
1139     wxSize GetMinSize() const;
1140
1141     /**
1142         Sets the minimum size to be allocated for this item.
1143
1144         If this item is a window, the @a size is also passed to
1145         wxWindow::SetMinSize().
1146      */
1147     void SetMinSize(const wxSize& size);
1148
1149     /**
1150         @overload
1151      */
1152     void SetMinSize(int x, int y);
1153
1154     /**
1155         What is the current position of the item, as set in the last Layout.
1156     */
1157     wxPoint GetPosition() const;
1158
1159     /**
1160         Get the proportion item attribute.
1161     */
1162     int GetProportion() const;
1163
1164     /**
1165         Get the ration item attribute.
1166     */
1167     float GetRatio() const;
1168
1169     /**
1170         Get the rectangle of the item on the parent window, excluding borders.
1171     */
1172     virtual wxRect GetRect();
1173
1174     /**
1175         Get the current size of the item, as set in the last Layout.
1176     */
1177     virtual wxSize GetSize() const;
1178
1179     /**
1180         If this item is tracking a sizer, return it.  @NULL otherwise.
1181     */
1182     wxSizer* GetSizer() const;
1183
1184     /**
1185         If this item is tracking a spacer, return its size.
1186     */
1187     wxSize GetSpacer() const;
1188
1189     /**
1190         Get the userData item attribute.
1191     */
1192     wxObject* GetUserData() const;
1193
1194     /**
1195         If this item is tracking a window then return it. @NULL otherwise.
1196     */
1197     wxWindow* GetWindow() const;
1198
1199     /**
1200         Returns @true if this item is a window or a spacer and it is shown or
1201         if this item is a sizer and not all of its elements are hidden.
1202
1203         In other words, for sizer items, all of the child elements must be
1204         hidden for the sizer itself to be considered hidden.
1205
1206         As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was
1207         used for this sizer item, then IsShown() always returns @true for it
1208         (see wxSizerFlags::ReserveSpaceEvenIfHidden()).
1209     */
1210     bool IsShown() const;
1211
1212     /**
1213         Is this item a sizer?
1214     */
1215     bool IsSizer() const;
1216
1217     /**
1218         Is this item a spacer?
1219     */
1220     bool IsSpacer() const;
1221
1222     /**
1223         Is this item a window?
1224     */
1225     bool IsWindow() const;
1226
1227     /**
1228         Set the border item attribute.
1229     */
1230     void SetBorder(int border);
1231
1232     /**
1233         Set the position and size of the space allocated to the sizer, and
1234         adjust the position and size of the item to be within that space
1235         taking alignment and borders into account.
1236     */
1237     virtual void SetDimension(const wxPoint& pos, const wxSize& size);
1238
1239     /**
1240         Set the flag item attribute.
1241     */
1242     void SetFlag(int flag);
1243
1244     /**
1245         Sets the numeric id of the wxSizerItem to @e id.
1246     */
1247     void SetId(int id);
1248
1249     /**
1250         @todo docme.
1251     */
1252     void SetInitSize(int x, int y);
1253
1254     /**
1255         Set the proportion item attribute.
1256     */
1257     void SetProportion(int proportion);
1258
1259     //@{
1260     /**
1261         Set the ratio item attribute.
1262     */
1263     void SetRatio(int width, int height);
1264     void SetRatio(wxSize size);
1265     void SetRatio(float ratio);
1266     //@}
1267
1268     /**
1269         Set the sizer tracked by this item.
1270
1271         @deprecated This function does not free the old sizer which may result
1272         in memory leaks, use AssignSizer() which does free it instead.
1273     */
1274     void SetSizer(wxSizer* sizer);
1275
1276     /**
1277         Set the size of the spacer tracked by this item.
1278
1279         @deprecated This function does not free the old spacer which may result
1280         in memory leaks, use AssignSpacer() which does free it instead.
1281     */
1282     void SetSpacer(const wxSize& size);
1283
1284     void SetUserData(wxObject* userData);
1285
1286     /**
1287         Set the window to be tracked by this item.
1288         @deprecated @todo provide deprecation description
1289     */
1290     void SetWindow(wxWindow* window);
1291
1292     /**
1293         Set the show item attribute, which sizers use to determine if the item
1294         is to be made part of the layout or not. If the item is tracking a
1295         window then it is shown or hidden as needed.
1296     */
1297     void Show(bool show);
1298 };
1299
1300
1301
1302 /**
1303     @class wxSizerFlags
1304
1305     Container for sizer items flags providing readable names for them.
1306
1307     Normally, when you add an item to a sizer via wxSizer::Add, you have to
1308     specify a lot of flags and parameters which can be unwieldy. This is where
1309     wxSizerFlags comes in: it allows you to specify all parameters using the
1310     named methods instead. For example, instead of
1311
1312     @code
1313     sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10);
1314     @endcode
1315
1316     you can now write
1317
1318     @code
1319     sizer->Add(ctrl, wxSizerFlags().Expand().Border(wxALL, 10));
1320     @endcode
1321
1322     This is more readable and also allows you to create wxSizerFlags objects which
1323     can be reused for several sizer items.
1324
1325     @code
1326     wxSizerFlags flagsExpand(1);
1327         flagsExpand.Expand().Border(wxALL, 10);
1328
1329         sizer->Add(ctrl1, flagsExpand);
1330         sizer->Add(ctrl2, flagsExpand);
1331     @endcode
1332
1333     Note that by specification, all methods of wxSizerFlags return the wxSizerFlags
1334     object itself to allowing chaining multiple methods calls like in the examples
1335     above.
1336
1337     @library{wxcore}
1338     @category{winlayout}
1339
1340     @see wxSizer
1341 */
1342 class wxSizerFlags
1343 {
1344 public:
1345     /**
1346         Creates the wxSizer with the proportion specified by @a proportion.
1347     */
1348     wxSizerFlags(int proportion = 0);
1349
1350     /**
1351         Sets the alignment of this wxSizerFlags to @a align.
1352
1353         This method replaces the previously set alignment with the specified one.
1354
1355         @param alignment
1356             Combination of @c wxALIGN_XXX bit masks.
1357
1358         @see Top(), Left(), Right(), Bottom(), Centre()
1359     */
1360     wxSizerFlags& Align(int alignment);
1361
1362     /**
1363         Sets the wxSizerFlags to have a border of a number of pixels specified
1364         by @a borderinpixels with the directions specified by @a direction.
1365     */
1366     wxSizerFlags& Border(int direction, int borderinpixels);
1367
1368     /**
1369         Sets the wxSizerFlags to have a border with size as returned by
1370         GetDefaultBorder().
1371
1372         @param direction
1373             Direction(s) to apply the border in.
1374     */
1375     wxSizerFlags& Border(int direction = wxALL);
1376
1377     /**
1378         Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM).
1379
1380         Unlike Align(), this method doesn't change the horizontal alignment of
1381         the item.
1382     */
1383     wxSizerFlags& Bottom();
1384
1385     /**
1386         Sets the object of the wxSizerFlags to center itself in the area it is
1387         given.
1388     */
1389     wxSizerFlags& Center();
1390
1391     /**
1392         Center() for people with the other dialect of English.
1393     */
1394     wxSizerFlags& Centre();
1395
1396     /**
1397         Sets the border in the given @a direction having twice the default
1398         border size.
1399     */
1400     wxSizerFlags& DoubleBorder(int direction = wxALL);
1401
1402     /**
1403         Sets the border in left and right directions having twice the default
1404         border size.
1405     */
1406     wxSizerFlags& DoubleHorzBorder();
1407
1408     /**
1409         Sets the object of the wxSizerFlags to expand to fill as much area as
1410         it can.
1411     */
1412     wxSizerFlags& Expand();
1413
1414     /**
1415         Set the @c wxFIXED_MINSIZE flag which indicates that the initial size
1416         of the window should be also set as its minimal size.
1417     */
1418     wxSizerFlags& FixedMinSize();
1419
1420     /**
1421         Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers
1422         don't allocate space for hidden windows or other items. This flag
1423         overrides this behaviour so that sufficient space is allocated for the
1424         window even if it isn't visible. This makes it possible to dynamically
1425         show and hide controls without resizing parent dialog, for example.
1426
1427         @since 2.8.8
1428     */
1429     wxSizerFlags& ReserveSpaceEvenIfHidden();
1430
1431     /**
1432         Returns the border used by default in Border() method.
1433     */
1434     static int GetDefaultBorder();
1435
1436     /**
1437         Aligns the object to the left, similar for @c Align(wxALIGN_LEFT).
1438
1439         Unlike Align(), this method doesn't change the vertical alignment of
1440         the item.
1441     */
1442     wxSizerFlags& Left();
1443
1444     /**
1445         Sets the proportion of this wxSizerFlags to @e proportion
1446     */
1447     wxSizerFlags& Proportion(int proportion);
1448
1449     /**
1450         Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT).
1451
1452         Unlike Align(), this method doesn't change the vertical alignment of
1453         the item.
1454     */
1455     wxSizerFlags& Right();
1456
1457     /**
1458         Set the @c wx_SHAPED flag which indicates that the elements should
1459         always keep the fixed width to height ratio equal to its original value.
1460     */
1461     wxSizerFlags& Shaped();
1462
1463     /**
1464         Aligns the object to the top, similar for @c Align(wxALIGN_TOP).
1465
1466         Unlike Align(), this method doesn't change the horizontal alignment of
1467         the item.
1468     */
1469     wxSizerFlags& Top();
1470
1471     /**
1472         Sets the border in the given @a direction having thrice the default
1473         border size.
1474     */
1475     wxSizerFlags& TripleBorder(int direction = wxALL);
1476 };
1477
1478
1479 /**
1480     Values which define the behaviour for resizing wxFlexGridSizer cells in the
1481     "non-flexible" direction.
1482 */
1483 enum wxFlexSizerGrowMode
1484 {
1485     /// Don't resize the cells in non-flexible direction at all.
1486     wxFLEX_GROWMODE_NONE,
1487
1488     /// Uniformly resize only the specified ones (default).
1489     wxFLEX_GROWMODE_SPECIFIED,
1490
1491     /// Uniformly resize all cells.
1492     wxFLEX_GROWMODE_ALL
1493 };
1494
1495 /**
1496     @class wxFlexGridSizer
1497
1498     A flex grid sizer is a sizer which lays out its children in a two-dimensional
1499     table with all table fields in one row having the same height and all fields
1500     in one column having the same width, but all rows or all columns are not
1501     necessarily the same height or width as in the wxGridSizer.
1502
1503     Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one
1504     direction but unequally ("flexibly") in the other. If the sizer is only
1505     flexible in one direction (this can be changed using wxFlexGridSizer::SetFlexibleDirection),
1506     it needs to be decided how the sizer should grow in the other ("non-flexible")
1507     direction in order to fill the available space.
1508     The wxFlexGridSizer::SetNonFlexibleGrowMode() method serves this purpose.
1509
1510     @library{wxcore}
1511     @category{winlayout}
1512
1513     @see wxSizer, @ref overview_sizer
1514 */
1515 class wxFlexGridSizer : public wxGridSizer
1516 {
1517 public:
1518     //@{
1519     /**
1520         wxFlexGridSizer constructors.
1521
1522         Please see wxGridSizer::wxGridSizer documentation.
1523
1524         @since 2.9.1 (except for the four argument overload)
1525     */
1526     wxFlexGridSizer( int cols, int vgap, int hgap );
1527     wxFlexGridSizer( int cols, const wxSize& gap = wxSize(0, 0) );
1528
1529     wxFlexGridSizer( int rows, int cols, int vgap, int hgap );
1530     wxFlexGridSizer( int rows, int cols, const wxSize& gap );
1531     //@}
1532
1533     /**
1534         Specifies that column @a idx (starting from zero) should be grown if
1535         there is extra space available to the sizer.
1536
1537         The @a proportion parameter has the same meaning as the stretch factor
1538         for the sizers (see wxBoxSizer) except that if all proportions are 0,
1539         then all columns are resized equally (instead of not being resized at all).
1540
1541         Notice that the column must not be already growable, if you need to change
1542         the proportion you must call RemoveGrowableCol() first and then make it
1543         growable (with a different proportion) again. You can use IsColGrowable()
1544         to check whether a column is already growable.
1545     */
1546     void AddGrowableCol(size_t idx, int proportion = 0);
1547
1548     /**
1549         Specifies that row idx (starting from zero) should be grown if there
1550         is extra space available to the sizer.
1551
1552         This is identical to AddGrowableCol() except that it works with rows
1553         and not columns.
1554     */
1555     void AddGrowableRow(size_t idx, int proportion = 0);
1556
1557     /**
1558         Returns a ::wxOrientation value that specifies whether the sizer flexibly
1559         resizes its columns, rows, or both (default).
1560
1561         @return
1562             One of the following values:
1563             - wxVERTICAL: Rows are flexibly sized.
1564             - wxHORIZONTAL: Columns are flexibly sized.
1565             - wxBOTH: Both rows and columns are flexibly sized (this is the default value).
1566
1567         @see SetFlexibleDirection()
1568     */
1569     int GetFlexibleDirection() const;
1570
1571     /**
1572         Returns the value that specifies how the sizer grows in the "non-flexible"
1573         direction if there is one.
1574
1575         The behaviour of the elements in the flexible direction (i.e. both rows
1576         and columns by default, or rows only if GetFlexibleDirection() is
1577         @c wxVERTICAL or columns only if it is @c wxHORIZONTAL) is always governed
1578         by their proportion as specified in the call to AddGrowableRow() or
1579         AddGrowableCol(). What happens in the other direction depends on the
1580         value of returned by this function as described below.
1581
1582         @return
1583             One of the following values:
1584             - wxFLEX_GROWMODE_NONE: Sizer doesn't grow its elements at all in
1585               the non-flexible direction.
1586             - wxFLEX_GROWMODE_SPECIFIED: Sizer honors growable columns/rows set
1587               with AddGrowableCol() and AddGrowableRow() in the non-flexible
1588               direction as well. In this case equal sizing applies to minimum
1589               sizes of columns or rows (this is the default value).
1590             - wxFLEX_GROWMODE_ALL: Sizer equally stretches all columns or rows in
1591               the non-flexible direction, independently of the proportions
1592               applied in the flexible direction.
1593
1594         @see SetFlexibleDirection(), SetNonFlexibleGrowMode()
1595     */
1596     wxFlexSizerGrowMode GetNonFlexibleGrowMode() const;
1597
1598     /**
1599         Returns @true if column @a idx is growable.
1600
1601         @since 2.9.0
1602     */
1603     bool IsColGrowable(size_t idx);
1604
1605     /**
1606         Returns @true if row @a idx is growable.
1607
1608         @since 2.9.0
1609     */
1610     bool IsRowGrowable(size_t idx);
1611
1612     /**
1613         Specifies that the @a idx column index is no longer growable.
1614     */
1615     void RemoveGrowableCol(size_t idx);
1616
1617     /**
1618         Specifies that the @a idx row index is no longer growable.
1619     */
1620     void RemoveGrowableRow(size_t idx);
1621
1622     /**
1623         Specifies whether the sizer should flexibly resize its columns, rows, or both.
1624
1625         Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
1626         (which is the default value). Any other value is ignored.
1627
1628         See GetFlexibleDirection() for the explanation of these values.
1629         Note that this method does not trigger relayout.
1630     */
1631     void SetFlexibleDirection(int direction);
1632
1633     /**
1634         Specifies how the sizer should grow in the non-flexible direction if
1635         there is one (so SetFlexibleDirection() must have been called previously).
1636
1637         Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(),
1638         please see there for their explanation.
1639         Note that this method does not trigger relayout.
1640     */
1641     void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode);
1642
1643     virtual void RecalcSizes();
1644     virtual wxSize CalcMin();
1645
1646 };
1647
1648
1649 /**
1650     @class wxGridSizer
1651
1652     A grid sizer is a sizer which lays out its children in a two-dimensional
1653     table with all table fields having the same size, i.e. the width of each
1654     field is the width of the widest child, the height of each field is the
1655     height of the tallest child.
1656
1657     @library{wxcore}
1658     @category{winlayout}
1659
1660     @see wxSizer, @ref overview_sizer
1661 */
1662 class wxGridSizer : public wxSizer
1663 {
1664 public:
1665     //@{
1666     /**
1667         wxGridSizer constructors.
1668
1669         Usually only the number of columns in the flex grid sizer needs to be
1670         specified using @a cols argument. The number of rows will be deduced
1671         automatically depending on the number of the elements added to the
1672         sizer.
1673
1674         If a constructor form with @a rows parameter is used (and the value of
1675         @a rows argument is not zero, meaning "unspecified") the sizer will
1676         check that no more than @c cols*rows elements are added to it, i.e.
1677         that no more than the given number of @a rows is used. Adding less than
1678         maximally allowed number of items is not an error however.
1679
1680         Finally, it is also possible to specify the number of rows and use 0
1681         for @a cols. In this case, the sizer will use the given fixed number of
1682         rows and as many columns as necessary.
1683
1684         The @a gap (or @a vgap and @a hgap, which correspond to the height and
1685         width of the wxSize object) argument defines the size of the padding
1686         between the rows (its vertical component, or @a vgap) and columns
1687         (its horizontal component, or @a hgap), in pixels.
1688
1689
1690         @since 2.9.1 (except for the four argument overload)
1691     */
1692     wxGridSizer( int cols, int vgap, int hgap );
1693     wxGridSizer( int cols, const wxSize& gap = wxSize(0, 0) );
1694
1695     wxGridSizer( int rows, int cols, int vgap, int hgap );
1696     wxGridSizer( int rows, int cols, const wxSize& gap );
1697     //@}
1698
1699     /**
1700         Returns the number of columns that has been specified for the
1701         sizer.
1702
1703         Returns zero if the sizer is automatically adjusting the number of
1704         columns depending on number of its children. To get the effective
1705         number of columns or rows being currently used, see GetEffectiveColsCount()
1706     */
1707     int GetCols() const;
1708
1709     /**
1710         Returns the number of rows that has been specified for the
1711         sizer.
1712
1713         Returns zero if the sizer is automatically adjusting the number of
1714         rows depending on number of its children. To get the effective
1715         number of columns or rows being currently used, see GetEffectiveRowsCount().
1716     */
1717     int GetRows() const;
1718
1719     /**
1720         Returns the number of columns currently used by the sizer.
1721
1722         This will depend on the number of children the sizer has if
1723         the sizer is automatically adjusting the number of columns/rows.
1724
1725         @since 2.9.1
1726     */
1727     int GetEffectiveColsCount() const;
1728
1729     /**
1730         Returns the number of rows currently used by the sizer.
1731
1732         This will depend on the number of children the sizer has if
1733         the sizer is automatically adjusting the number of columns/rows.
1734
1735         @since 2.9.1
1736     */
1737     int GetEffectiveRowsCount() const;
1738
1739     /**
1740         Returns the horizontal gap (in pixels) between cells in the sizer.
1741     */
1742     int GetHGap() const;
1743
1744     /**
1745         Returns the vertical gap (in pixels) between the cells in the sizer.
1746     */
1747     int GetVGap() const;
1748
1749     /**
1750         Sets the number of columns in the sizer.
1751     */
1752     void SetCols(int cols);
1753
1754     /**
1755         Sets the horizontal gap (in pixels) between cells in the sizer.
1756     */
1757     void SetHGap(int gap);
1758
1759     /**
1760         Sets the number of rows in the sizer.
1761     */
1762     void SetRows(int rows);
1763
1764     /**
1765         Sets the vertical gap (in pixels) between the cells in the sizer.
1766     */
1767     void SetVGap(int gap);
1768
1769     virtual wxSize CalcMin();
1770     virtual void RecalcSizes();
1771 };
1772
1773
1774
1775 /**
1776     @class wxStaticBoxSizer
1777
1778     wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around
1779     the sizer.
1780
1781     The static box may be either created independently or the sizer may create it
1782     itself as a convenience. In any case, the sizer owns the wxStaticBox control
1783     and will delete it in the wxStaticBoxSizer destructor.
1784
1785     Note that since wxWidgets 2.9.1 you are encouraged to create the windows
1786     which are added to wxStaticBoxSizer as children of wxStaticBox itself, see
1787     this class documentation for more details.
1788
1789     Example of use of this class:
1790     @code
1791         void MyFrame::CreateControls()
1792         {
1793             wxPanel *panel = new wxPanel(this);
1794             ...
1795             wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, panel, "Box");
1796             sz->Add(new wxStaticText(sz->GetStaticBox(), wxID_ANY,
1797                                      "This window is a child of the staticbox"));
1798             ...
1799         }
1800     @endcode
1801
1802     @library{wxcore}
1803     @category{winlayout}
1804
1805     @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer
1806 */
1807 class wxStaticBoxSizer : public wxBoxSizer
1808 {
1809 public:
1810     /**
1811         This constructor uses an already existing static box.
1812
1813         @param box
1814             The static box to associate with the sizer (which will take its
1815             ownership).
1816         @param orient
1817             Can be either @c wxVERTICAL or @c wxHORIZONTAL.
1818     */
1819     wxStaticBoxSizer(wxStaticBox* box, int orient);
1820
1821     /**
1822         This constructor creates a new static box with the given label and parent window.
1823     */
1824     wxStaticBoxSizer(int orient, wxWindow *parent,
1825                      const wxString& label = wxEmptyString);
1826
1827     /**
1828         Returns the static box associated with the sizer.
1829     */
1830     wxStaticBox* GetStaticBox() const;
1831
1832     virtual wxSize CalcMin();
1833     virtual void RecalcSizes();
1834 };
1835
1836
1837
1838 /**
1839     @class wxBoxSizer
1840
1841     The basic idea behind a box sizer is that windows will most often be laid out
1842     in rather simple basic geometry, typically in a row or a column or several
1843     hierarchies of either.
1844
1845     For more information, please see @ref overview_sizer_box.
1846
1847     @library{wxcore}
1848     @category{winlayout}
1849
1850     @see wxSizer, @ref overview_sizer
1851 */
1852 class wxBoxSizer : public wxSizer
1853 {
1854 public:
1855     /**
1856         Constructor for a wxBoxSizer. @a orient may be either of wxVERTICAL
1857         or wxHORIZONTAL for creating either a column sizer or a row sizer.
1858     */
1859     wxBoxSizer(int orient);
1860
1861     /**
1862         Adds non-stretchable space to the main orientation of the sizer only.
1863         More readable way of calling:
1864         @code
1865         if ( wxBoxSizer::IsVertical() )
1866         {
1867             wxBoxSizer::Add(0, size, 0).
1868         }
1869         else
1870         {
1871             wxBoxSizer::Add(size, 0, 0).
1872         }
1873         @endcode
1874     */
1875     virtual wxSizerItem *AddSpacer(int size);
1876
1877     /**
1878         Implements the calculation of a box sizer's minimal.
1879
1880         It is used internally only and must not be called by the user.
1881         Documented for information.
1882     */
1883     virtual wxSize CalcMin();
1884
1885     /**
1886         Returns the orientation of the box sizer, either wxVERTICAL
1887         or wxHORIZONTAL.
1888     */
1889     int GetOrientation() const;
1890
1891     /**
1892         Sets the orientation of the box sizer, either wxVERTICAL
1893         or wxHORIZONTAL.
1894     */
1895     void SetOrientation(int orient);
1896
1897     /**
1898         Implements the calculation of a box sizer's dimensions and then sets
1899         the size of its children (calling wxWindow::SetSize if the child is a window).
1900
1901         It is used internally only and must not be called by the user
1902         (call Layout() if you want to resize). Documented for information.
1903     */
1904     virtual void RecalcSizes();
1905 };
1906