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