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