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