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