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