interface/sizer.h

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