interface/wx/sizer.h

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