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