interface/wx/sizer.h

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