interface/sizer.h

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