interface/wx/sizer.h

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