]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/sizer.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStdDialogButtonSizer
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 A generic orientation value.
15 /* don't change the values of these elements, they are used elsewhere */
16 wxHORIZONTAL
= 0x0004,
19 wxBOTH
= wxVERTICAL
| wxHORIZONTAL
,
21 /* a mask to extract orientation from the combination of flags */
22 wxORIENTATION_MASK
= wxBOTH
27 @class wxStdDialogButtonSizer
29 This class creates button layouts which conform to the standard button spacing
30 and ordering defined by the platform or toolkit's user interface guidelines
31 (if such things exist). By using this class, you can ensure that all your
32 standard dialogs look correct on all major platforms. Currently it conforms to
33 the Windows, GTK+ and Mac OS X human interface guidelines.
35 When there aren't interface guidelines defined for a particular platform or
36 toolkit, wxStdDialogButtonSizer reverts to the Windows implementation.
38 To use this class, first add buttons to the sizer by calling
39 wxStdDialogButtonSizer::AddButton (or wxStdDialogButtonSizer::SetAffirmativeButton,
40 wxStdDialogButtonSizer::SetNegativeButton or wxStdDialogButtonSizer::SetCancelButton)
41 and then call Realize in order to create the actual button layout used.
42 Other than these special operations, this sizer works like any other sizer.
44 If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to
45 "Save" and the wxID_NO button will be renamed to "Don't Save" in accordance
46 with the Mac OS X Human Interface Guidelines.
51 @see wxSizer, @ref overview_sizer, wxDialog::CreateButtonSizer
53 class wxStdDialogButtonSizer
: public wxBoxSizer
57 Constructor for a wxStdDialogButtonSizer.
59 wxStdDialogButtonSizer();
62 Adds a button to the wxStdDialogButtonSizer. The @a button must have
63 one of the following identifiers:
74 void AddButton(wxButton
* button
);
77 Rearranges the buttons and applies proper spacing between buttons to make
78 them match the platform or toolkit's interface guidelines.
83 Sets the affirmative button for the sizer.
85 This allows you to use identifiers other than the standard identifiers
88 void SetAffirmativeButton(wxButton
* button
);
91 Sets the cancel button for the sizer.
93 This allows you to use identifiers other than the standard identifiers
96 void SetCancelButton(wxButton
* button
);
99 Sets the negative button for the sizer.
101 This allows you to use identifiers other than the standard identifiers
104 void SetNegativeButton(wxButton
* button
);
112 The wxSizerItem class is used to track the position, size and other
113 attributes of each item managed by a wxSizer.
115 It is not usually necessary to use this class because the sizer elements can
116 also be identified by their positions or window or sizer pointers but sometimes
117 it may be more convenient to use it directly.
122 class wxSizerItem
: public wxObject
126 Construct a sizer item for tracking a spacer.
128 wxSizerItem(int width
, int height
, int proportion
, int flag
,
129 int border
, wxObject
* userData
);
133 Construct a sizer item for tracking a window.
135 wxSizerItem(wxWindow
* window
, const wxSizerFlags
& flags
);
136 wxSizerItem(wxWindow
* window
, int proportion
, int flag
,
143 Construct a sizer item for tracking a subsizer.
145 wxSizerItem(wxSizer
* window
, const wxSizerFlags
& flags
);
146 wxSizerItem(wxSizer
* sizer
, int proportion
, int flag
,
152 Deletes the user data and subsizer, if any.
154 virtual ~wxSizerItem();
157 Calculates the minimum desired size for the item, including any space
160 virtual wxSize
CalcMin();
163 Destroy the window or the windows in a subsizer, depending on the type
166 virtual void DeleteWindows();
169 Enable deleting the SizerItem without destroying the contained sizer.
174 Return the border attribute.
176 int GetBorder() const;
179 Return the flags attribute.
181 See @ref wxsizer_flags "wxSizer flags list" for details.
186 Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has
192 Get the minimum size needed for the item.
194 wxSize
GetMinSize() const;
197 Sets the minimum size to be allocated for this item.
199 If this item is a window, the @a size is also passed to
200 wxWindow::SetMinSize().
202 void SetMinSize(const wxSize
& size
);
207 void SetMinSize(int x
, int y
);
210 What is the current position of the item, as set in the last Layout.
212 wxPoint
GetPosition() const;
215 Get the proportion item attribute.
217 int GetProportion() const;
220 Get the ration item attribute.
222 float GetRatio() const;
225 Get the rectangle of the item on the parent window, excluding borders.
227 virtual wxRect
GetRect();
230 Get the current size of the item, as set in the last Layout.
232 virtual wxSize
GetSize() const;
235 If this item is tracking a sizer, return it. @NULL otherwise.
237 wxSizer
* GetSizer() const;
240 If this item is tracking a spacer, return its size.
242 wxSize
GetSpacer() const;
245 Get the userData item attribute.
247 wxObject
* GetUserData() const;
250 If this item is tracking a window then return it. @NULL otherwise.
252 wxWindow
* GetWindow() const;
255 Returns @true if this item is a window or a spacer and it is shown or
256 if this item is a sizer and not all of its elements are hidden.
258 In other words, for sizer items, all of the child elements must be
259 hidden for the sizer itself to be considered hidden.
261 As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was
262 used for this sizer item, then IsShown() always returns @true for it
263 (see wxSizerFlags::ReserveSpaceEvenIfHidden()).
265 bool IsShown() const;
268 Is this item a sizer?
270 bool IsSizer() const;
273 Is this item a spacer?
275 bool IsSpacer() const;
278 Is this item a window?
280 bool IsWindow() const;
283 Set the border item attribute.
285 void SetBorder(int border
);
288 Set the position and size of the space allocated to the sizer, and
289 adjust the position and size of the item to be within that space
290 taking alignment and borders into account.
292 virtual void SetDimension(const wxPoint
& pos
, const wxSize
& size
);
295 Set the flag item attribute.
297 void SetFlag(int flag
);
300 Sets the numeric id of the wxSizerItem to @e id.
307 void SetInitSize(int x
, int y
);
310 Set the proportion item attribute.
312 void SetProportion(int proportion
);
316 Set the ratio item attribute.
318 void SetRatio(int width
, int height
);
319 void SetRatio(wxSize size
);
320 void SetRatio(float ratio
);
324 Set the sizer tracked by this item.
325 @deprecated @todo provide deprecation description
327 void SetSizer(wxSizer
* sizer
);
330 Set the size of the spacer tracked by this item.
331 @deprecated @todo provide deprecation description
333 void SetSpacer(const wxSize
& size
);
336 Set the window to be tracked by this item.
337 @deprecated @todo provide deprecation description
339 void SetWindow(wxWindow
* window
);
342 Set the show item attribute, which sizers use to determine if the item
343 is to be made part of the layout or not. If the item is tracking a
344 window then it is shown or hidden as needed.
346 void Show(bool show
);
354 Container for sizer items flags providing readable names for them.
356 Normally, when you add an item to a sizer via wxSizer::Add, you have to
357 specify a lot of flags and parameters which can be unwieldy. This is where
358 wxSizerFlags comes in: it allows you to specify all parameters using the
359 named methods instead. For example, instead of
362 sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10);
368 sizer->Add(ctrl, wxSizerFlags().Expand().Border(wxALL, 10));
371 This is more readable and also allows you to create wxSizerFlags objects which
372 can be reused for several sizer items.
375 wxSizerFlags flagsExpand(1);
376 flagsExpand.Expand().Border(wxALL, 10);
378 sizer->Add(ctrl1, flagsExpand);
379 sizer->Add(ctrl2, flagsExpand);
382 Note that by specification, all methods of wxSizerFlags return the wxSizerFlags
383 object itself to allowing chaining multiple methods calls like in the examples
395 Creates the wxSizer with the proportion specified by @a proportion.
397 wxSizerFlags(int proportion
= 0);
400 Sets the alignment of this wxSizerFlags to @a align.
402 This method replaces the previously set alignment with the specified one.
405 Combination of @c wxALIGN_XXX bit masks.
407 @see Top(), Left(), Right(), Bottom(), Centre()
409 wxSizerFlags
& Align(int alignment
);
412 Sets the wxSizerFlags to have a border of a number of pixels specified
413 by @a borderinpixels with the directions specified by @a direction.
415 wxSizerFlags
& Border(int direction
, int borderinpixels
);
418 Sets the wxSizerFlags to have a border with size as returned by
422 Direction(s) to apply the border in.
424 wxSizerFlags
& Border(int direction
= wxALL
);
427 Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM).
429 Unlike Align(), this method doesn't change the horizontal alignment of
432 wxSizerFlags
& Bottom();
435 Sets the object of the wxSizerFlags to center itself in the area it is
438 wxSizerFlags
& Center();
441 Center() for people with the other dialect of English.
443 wxSizerFlags
& Centre();
446 Sets the border in the given @a direction having twice the default
449 wxSizerFlags
& DoubleBorder(int direction
= wxALL
);
452 Sets the border in left and right directions having twice the default
455 wxSizerFlags
& DoubleHorzBorder();
458 Sets the object of the wxSizerFlags to expand to fill as much area as
461 wxSizerFlags
& Expand();
464 Set the @c wxFIXED_MINSIZE flag which indicates that the initial size
465 of the window should be also set as its minimal size.
467 wxSizerFlags
& FixedMinSize();
470 Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers
471 don't allocate space for hidden windows or other items. This flag
472 overrides this behavior so that sufficient space is allocated for the
473 window even if it isn't visible. This makes it possible to dynamically
474 show and hide controls without resizing parent dialog, for example.
478 wxSizerFlags
& ReserveSpaceEvenIfHidden();
481 Returns the border used by default in Border() method.
483 static int GetDefaultBorder();
486 Aligns the object to the left, similar for @c Align(wxALIGN_LEFT).
488 Unlike Align(), this method doesn't change the vertical alignment of
491 wxSizerFlags
& Left();
494 Sets the proportion of this wxSizerFlags to @e proportion
496 wxSizerFlags
& Proportion(int proportion
);
499 Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT).
501 Unlike Align(), this method doesn't change the vertical alignment of
504 wxSizerFlags
& Right();
507 Set the @c wx_SHAPED flag which indicates that the elements should
508 always keep the fixed width to height ratio equal to its original value.
510 wxSizerFlags
& Shaped();
513 Aligns the object to the top, similar for @c Align(wxALIGN_TOP).
515 Unlike Align(), this method doesn't change the horizontal alignment of
521 Sets the border in the given @a direction having thrice the default
524 wxSizerFlags
& TripleBorder(int direction
= wxALL
);
530 @class wxNotebookSizer
533 This class is deprecated and should not be used in new code! It is no
534 longer needed, wxNotebook control can be inserted
535 into any sizer class and its minimal size will be determined correctly.
537 wxNotebookSizer is a specialized sizer to make sizers work in connection
538 with using notebooks. This sizer is different from any other sizer as you
539 must not add any children to it - instead, it queries the notebook class
540 itself. The only thing this sizer does is to determine the size of the
541 biggest page of the notebook and report an adjusted minimal size to a more
547 @see wxSizer, wxNotebook,
548 @ref overview_sizer "Sizers overview"
550 class wxNotebookSizer
: public wxSizer
554 Constructor. It takes an associated notebook as its only parameter.
556 wxNotebookSizer(wxNotebook
* notebook
);
559 Returns the notebook associated with the sizer.
561 wxNotebook
* GetNotebook();
567 @class wxFlexGridSizer
569 A flex grid sizer is a sizer which lays out its children in a two-dimensional
570 table with all table fields in one row having the same height and all fields
571 in one column having the same width, but all rows or all columns are not
572 necessarily the same height or width as in the wxGridSizer.
574 Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one
575 direction but unequally ("flexibly") in the other. If the sizer is only
576 flexible in one direction (this can be changed using wxFlexGridSizer::SetFlexibleDirection),
577 it needs to be decided how the sizer should grow in the other ("non-flexible")
578 direction in order to fill the available space.
579 The wxFlexGridSizer::SetNonFlexibleGrowMode() method serves this purpose.
584 @see wxSizer, @ref overview_sizer
586 class wxFlexGridSizer
: public wxGridSizer
591 Constructor for a wxFlexGridSizer.
593 @a rows and @a cols determine the number of columns and rows in the sizer -
594 if either of the parameters is zero, it will be calculated to form the
595 total number of children in the sizer, thus making the sizer grow
598 @a vgap and @a hgap define extra space between all children.
600 wxFlexGridSizer(int rows
, int cols
, int vgap
, int hgap
);
601 wxFlexGridSizer(int cols
, int vgap
= 0, int hgap
= 0);
605 Specifies that column @a idx (starting from zero) should be grown if
606 there is extra space available to the sizer.
608 The @a proportion parameter has the same meaning as the stretch factor
609 for the sizers() except that if all proportions are 0, then all columns
610 are resized equally (instead of not being resized at all).
612 Notice that the row must not be already growable, if you need to change
613 the proportion you must call RemoveGrowableCol() first and then make it
614 growable (with a different proportion) again. You can use IsColGrowable()
615 to check whether a column is already growable.
617 void AddGrowableCol(size_t idx
, int proportion
= 0);
620 Specifies that row idx (starting from zero) should be grown if there
621 is extra space available to the sizer.
623 This is identical to AddGrowableCol() except that it works with rows
626 void AddGrowableRow(size_t idx
, int proportion
= 0);
629 Returns a wxOrientation value that specifies whether the sizer flexibly
630 resizes its columns, rows, or both (default).
633 One of the following values:
634 - wxVERTICAL: Rows are flexibly sized.
635 - wxHORIZONTAL: Columns are flexibly sized.
636 - wxBOTH: Both rows and columns are flexibly sized (this is the default value).
638 @see SetFlexibleDirection()
640 int GetFlexibleDirection() const;
643 Returns the value that specifies how the sizer grows in the "non-flexible"
644 direction if there is one.
647 One of the following values:
648 - wxFLEX_GROWMODE_NONE: Sizer doesn't grow in the non-flexible direction.
649 - wxFLEX_GROWMODE_SPECIFIED: Sizer honors growable columns/rows set with
650 AddGrowableCol() and AddGrowableRow(). In this case equal sizing applies
651 to minimum sizes of columns or rows (this is the default value).
652 - wxFLEX_GROWMODE_ALL: Sizer equally stretches all columns or rows in
653 the non-flexible direction, whether they are growable or not in the
656 @see SetFlexibleDirection(), SetNonFlexibleGrowMode()
658 wxFlexSizerGrowMode
GetNonFlexibleGrowMode() const;
661 Returns @true if column @a idx is growable.
665 bool IsColGrowable(size_t idx
);
668 Returns @true if row @a idx is growable.
672 bool IsRowGrowable(size_t idx
);
675 Specifies that column idx is no longer growable.
677 void RemoveGrowableCol(size_t idx
);
680 Specifies that row idx is no longer growable.
682 void RemoveGrowableRow(size_t idx
);
685 Specifies whether the sizer should flexibly resize its columns, rows, or both.
687 Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
688 (which is the default value). Any other value is ignored.
689 See GetFlexibleDirection() for the explanation of these values.
690 Note that this method does not trigger relayout.
692 void SetFlexibleDirection(int direction
);
695 Specifies how the sizer should grow in the non-flexible direction if
696 there is one (so SetFlexibleDirection() must have been called previously).
698 Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(),
699 please see there for their explanation.
700 Note that this method does not trigger relayout.
702 void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode
);
710 wxSizer is the abstract base class used for laying out subwindows in a window.
711 You cannot use wxSizer directly; instead, you will have to use one of the sizer
712 classes derived from it. Currently there are wxBoxSizer, wxStaticBoxSizer,
713 wxGridSizer, wxFlexGridSizer, wxWrapSizer and wxGridBagSizer.
715 The layout algorithm used by sizers in wxWidgets is closely related to layout
716 in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit.
717 It is based upon the idea of the individual subwindows reporting their minimal
718 required size and their ability to get stretched if the size of the parent window
721 This will most often mean that the programmer does not set the original size of
722 a dialog in the beginning, rather the dialog will be assigned a sizer and this
723 sizer will be queried about the recommended size. The sizer in turn will query
724 its children, which can be normal windows, empty space or other sizers, so that
725 a hierarchy of sizers can be constructed. Note that wxSizer does not derive
726 from wxWindow and thus does not interfere with tab ordering and requires very little
727 resources compared to a real window on screen.
729 What makes sizers so well fitted for use in wxWidgets is the fact that every
730 control reports its own minimal size and the algorithm can handle differences in
731 font sizes or different window (dialog item) sizes on different platforms without
732 problems. If e.g. the standard font as well as the overall design of Motif widgets
733 requires more space than on Windows, the initial dialog size will automatically
734 be bigger on Motif than on Windows.
736 Sizers may also be used to control the layout of custom drawn items on the
737 window. The wxSizer::Add(), wxSizer::Insert(), and wxSizer::Prepend() functions
738 return a pointer to the newly added wxSizerItem.
739 Just add empty space of the desired size and attributes, and then use the
740 wxSizerItem::GetRect() method to determine where the drawing operations
743 Please notice that sizers, like child windows, are owned by the library and
744 will be deleted by it which implies that they must be allocated on the heap.
745 However if you create a sizer and do not add it to another sizer or
746 window, the library wouldn't be able to delete such an orphan sizer and in
747 this, and only this, case it should be deleted explicitly.
750 If you wish to create a sizer class in wxPython you should
751 derive the class from @c wxPySizer in order to get Python-aware
752 capabilities for the various virtual methods.
755 @anchor wxsizer_flags
758 The "flag" argument accepted by wxSizeItem constructors and other
759 functions, e.g. wxSizer::Add(), is OR-combination of the following flags.
760 Two main behaviours are defined using these flags. One is the border around
761 a window: the border parameter determines the border width whereas the
762 flags given here determine which side(s) of the item that the border will
763 be added. The other flags determine how the sizer item behaves when the
764 space allotted to the sizer changes, and is somewhat dependent on the
765 specific kind of sizer used.
773 These flags are used to specify which side(s) of the sizer item
774 the border width will apply to.}
776 The item will be expanded to fill the space assigned to the item.}
778 The item will be expanded as much as possible while also
779 maintaining its aspect ratio.}
780 @itemdef{wxFIXED_MINSIZE,
781 Normally wxSizers will use GetAdjustedBestSize() to determine what
782 the minimal size of window items should be, and will use that size
783 to calculate the layout. This allows layouts to adjust when an
784 item changes and its best size becomes different. If you would
785 rather have a window item stay the size it started with then use
787 @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN,
788 Normally wxSizers don't allocate space for hidden windows or other
789 items. This flag overrides this behavior so that sufficient space
790 is allocated for the window even if it isn't visible. This makes
791 it possible to dynamically show and hide controls without resizing
792 parent dialog, for example. (Available since 2.8.8.)
794 @itemdef{wxALIGN_CENTER<br>
800 wxALIGN_CENTER_VERTICAL<br>
801 wxALIGN_CENTRE_VERTICAL<br>
802 wxALIGN_CENTER_HORIZONTAL<br>
803 wxALIGN_CENTRE_HORIZONTAL,
804 The wxALIGN flags allow you to specify the alignment of the item
805 within the space allotted to it by the sizer, adjusted for the
812 @see @ref overview_sizer
814 class wxSizer
: public wxObject
819 Note that wxSizer is an abstract base class and may not be instantiated.
829 Appends a child to the sizer.
831 wxSizer itself is an abstract class, but the parameters are equivalent
832 in the derived classes that you will instantiate to use it so they are
836 The window to be added to the sizer. Its initial size (either set
837 explicitly by the user or calculated internally when using
838 wxDefaultSize) is interpreted as the minimal and in many cases also
841 A wxSizerFlags object that enables you to specify most of the above
842 parameters more conveniently.
844 wxSizerItem
* Add(wxWindow
* window
, const wxSizerFlags
& flags
);
847 Appends a child to the sizer.
849 wxSizer itself is an abstract class, but the parameters are equivalent
850 in the derived classes that you will instantiate to use it so they are
854 The window to be added to the sizer. Its initial size (either set
855 explicitly by the user or calculated internally when using
856 wxDefaultSize) is interpreted as the minimal and in many cases also
859 Although the meaning of this parameter is undefined in wxSizer, it
860 is used in wxBoxSizer to indicate if a child of a sizer can change
861 its size in the main orientation of the wxBoxSizer - where 0 stands
862 for not changeable and a value of more than zero is interpreted
863 relative to the value of other children of the same wxBoxSizer. For
864 example, you might have a horizontal wxBoxSizer with three
865 children, two of which are supposed to change their size with the
866 sizer. Then the two stretchable windows would get a value of 1 each
867 to make them grow and shrink equally with the sizer's horizontal
870 OR-combination of flags affecting sizer's behavior. See
871 @ref wxsizer_flags "wxSizer flags list" for details.
873 Determines the border width, if the flag parameter is set to
874 include any border flag.
876 Allows an extra object to be attached to the sizer item, for use in
877 derived classes when sizing information is more complex than the
878 proportion and flag will allow for.
880 wxSizerItem
* Add(wxWindow
* window
,
884 wxObject
* userData
= NULL
);
887 Appends a child to the sizer.
889 wxSizer itself is an abstract class, but the parameters are equivalent
890 in the derived classes that you will instantiate to use it so they are
894 The (child-)sizer to be added to the sizer. This allows placing a
895 child sizer in a sizer and thus to create hierarchies of sizers
896 (typically a vertical box as the top sizer and several horizontal
897 boxes on the level beneath).
899 A wxSizerFlags object that enables you to specify most of the above
900 parameters more conveniently.
902 wxSizerItem
* Add(wxSizer
* sizer
, const wxSizerFlags
& flags
);
905 Appends a child to the sizer.
907 wxSizer itself is an abstract class, but the parameters are equivalent
908 in the derived classes that you will instantiate to use it so they are
912 The (child-)sizer to be added to the sizer. This allows placing a
913 child sizer in a sizer and thus to create hierarchies of sizers
914 (typically a vertical box as the top sizer and several horizontal
915 boxes on the level beneath).
917 Although the meaning of this parameter is undefined in wxSizer, it
918 is used in wxBoxSizer to indicate if a child of a sizer can change
919 its size in the main orientation of the wxBoxSizer - where 0 stands
920 for not changeable and a value of more than zero is interpreted
921 relative to the value of other children of the same wxBoxSizer. For
922 example, you might have a horizontal wxBoxSizer with three
923 children, two of which are supposed to change their size with the
924 sizer. Then the two stretchable windows would get a value of 1 each
925 to make them grow and shrink equally with the sizer's horizontal
928 OR-combination of flags affecting sizer's behavior. See
929 @ref wxsizer_flags "wxSizer flags list" for details.
931 Determines the border width, if the flag parameter is set to
932 include any border flag.
934 Allows an extra object to be attached to the sizer item, for use in
935 derived classes when sizing information is more complex than the
936 proportion and flag will allow for.
938 wxSizerItem
* Add(wxSizer
* sizer
,
942 wxObject
* userData
= NULL
);
945 Appends a spacer child to the sizer.
947 wxSizer itself is an abstract class, but the parameters are equivalent
948 in the derived classes that you will instantiate to use it so they are
951 @a width and @a height specify the dimension of a spacer to be added to
952 the sizer. Adding spacers to sizers gives more flexibility in the
953 design of dialogs; imagine for example a horizontal box with two
954 buttons at the bottom of a dialog: you might want to insert a space
955 between the two buttons and make that space stretchable using the
956 proportion flag and the result will be that the left button will be
957 aligned with the left side of the dialog and the right button with the
958 right side - the space in between will shrink and grow with the dialog.
963 Height of the spacer.
965 Although the meaning of this parameter is undefined in wxSizer, it
966 is used in wxBoxSizer to indicate if a child of a sizer can change
967 its size in the main orientation of the wxBoxSizer - where 0 stands
968 for not changeable and a value of more than zero is interpreted
969 relative to the value of other children of the same wxBoxSizer. For
970 example, you might have a horizontal wxBoxSizer with three
971 children, two of which are supposed to change their size with the
972 sizer. Then the two stretchable windows would get a value of 1 each
973 to make them grow and shrink equally with the sizer's horizontal
976 OR-combination of flags affecting sizer's behavior. See
977 @ref wxsizer_flags "wxSizer flags list" for details.
979 Determines the border width, if the flag parameter is set to
980 include any border flag.
982 Allows an extra object to be attached to the sizer item, for use in
983 derived classes when sizing information is more complex than the
984 proportion and flag will allow for.
986 wxSizerItem
* Add(int width
, int height
,
990 wxObject
* userData
= NULL
);
993 Adds non-stretchable space to the sizer.
994 More readable way of calling:
996 wxSizer::Add(size, size, 0).
999 wxSizerItem
* AddSpacer(int size
);
1002 Adds stretchable space to the sizer.
1003 More readable way of calling:
1005 wxSizer::Add(0, 0, prop).
1008 wxSizerItem
* AddStretchSpacer(int prop
= 1);
1011 This method is abstract and has to be overwritten by any derived class.
1012 Here, the sizer will do the actual calculation of its children's minimal sizes.
1014 virtual wxSize
CalcMin() = 0;
1017 Detaches all children from the sizer.
1018 If @a delete_windows is @true then child windows will also be deleted.
1020 virtual void Clear(bool delete_windows
= false);
1023 Computes client area size for @a window so that it matches the sizer's
1024 minimal size. Unlike GetMinSize(), this method accounts for other
1025 constraints imposed on @e window, namely display's size (returned size
1026 will never be too large for the display) and maximum window size if
1027 previously set by wxWindow::SetMaxSize().
1029 The returned value is suitable for passing to wxWindow::SetClientSize() or
1030 wxWindow::SetMinClientSize().
1034 @see ComputeFittingWindowSize(), Fit()
1036 wxSize
ComputeFittingClientSize(wxWindow
* window
);
1039 Like ComputeFittingClientSize(), but converts the result into window
1040 size. The returned value is suitable for passing to wxWindow::SetSize()
1041 or wxWindow::SetMinSize().
1045 @see ComputeFittingClientSize(), Fit()
1047 wxSize
ComputeFittingWindowSize(wxWindow
* window
);
1050 Detach the child @a window from the sizer without destroying it.
1052 This method does not cause any layout or resizing to take place, call Layout()
1053 to update the layout "on screen" after detaching a child from the sizer.
1055 Returns @true if the child item was found and detached, @false otherwise.
1059 virtual bool Detach(wxWindow
* window
);
1062 Detach the child @a sizer from the sizer without destroying it.
1064 This method does not cause any layout or resizing to take place, call Layout()
1065 to update the layout "on screen" after detaching a child from the sizer.
1067 Returns @true if the child item was found and detached, @false otherwise.
1071 virtual bool Detach(wxSizer
* sizer
);
1074 Detach a item at position @a index from the sizer without destroying it.
1076 This method does not cause any layout or resizing to take place, call Layout()
1077 to update the layout "on screen" after detaching a child from the sizer.
1078 Returns @true if the child item was found and detached, @false otherwise.
1082 virtual bool Detach(int index
);
1085 Tell the sizer to resize the @a window so that its client area matches the
1086 sizer's minimal size (ComputeFittingClientSize() is called to determine it).
1087 This is commonly done in the constructor of the window itself, see sample
1088 in the description of wxBoxSizer.
1090 @return The new window size.
1092 @see ComputeFittingClientSize(), ComputeFittingWindowSize()
1094 wxSize
Fit(wxWindow
* window
);
1097 Tell the sizer to resize the virtual size of the @a window to match the sizer's
1098 minimal size. This will not alter the on screen size of the window, but may
1099 cause the addition/removal/alteration of scrollbars required to view the virtual
1100 area in windows which manage it.
1102 @see wxScrolled::SetScrollbars(), SetVirtualSizeHints()
1104 void FitInside(wxWindow
* window
);
1108 Returns the list of the items in this sizer.
1110 The elements of type-safe wxList @c wxSizerItemList are pointers to
1111 objects of type wxSizerItem.
1113 wxSizerItemList
& GetChildren();
1114 const wxSizerItemList
& GetChildren() const;
1118 Returns the window this sizer is used in or @NULL if none.
1120 wxWindow
* GetContainingWindow() const;
1123 Finds wxSizerItem which holds the given @a window.
1124 Use parameter @a recursive to search in subsizers too.
1125 Returns pointer to item or @NULL.
1127 wxSizerItem
* GetItem(wxWindow
* window
, bool recursive
= false);
1130 Finds wxSizerItem which holds the given @a sizer.
1131 Use parameter @a recursive to search in subsizers too.
1132 Returns pointer to item or @NULL.
1135 wxSizerItem
* GetItem(wxSizer
* sizer
, bool recursive
= false);
1138 Finds wxSizerItem which is located in the sizer at position @a index.
1139 Use parameter @a recursive to search in subsizers too.
1140 Returns pointer to item or @NULL.
1142 wxSizerItem
* GetItem(size_t index
);
1145 Finds item of the sizer which has the given @e id.
1146 This @a id is not the window id but the id of the wxSizerItem itself.
1147 This is mainly useful for retrieving the sizers created from XRC resources.
1148 Use parameter @a recursive to search in subsizers too.
1149 Returns pointer to item or @NULL.
1151 wxSizerItem
* GetItemById(int id
, bool recursive
= false);
1154 Returns the minimal size of the sizer.
1156 This is either the combined minimal size of all the children and their
1157 borders or the minimal size set by SetMinSize(), depending on which is bigger.
1158 Note that the returned value is client size, not window size.
1159 In particular, if you use the value to set toplevel window's minimal or
1160 actual size, use wxWindow::SetMinClientSize() or wxWindow::SetClientSize(),
1161 not wxWindow::SetMinSize() or wxWindow::SetSize().
1163 wxSize
GetMinSize();
1166 Returns the current position of the sizer.
1168 wxPoint
GetPosition() const;
1171 Returns the current size of the sizer.
1173 wxSize
GetSize() const;
1176 Hides the child @a window.
1178 To make a sizer item disappear, use Hide() followed by Layout().
1180 Use parameter @a recursive to hide elements found in subsizers.
1181 Returns @true if the child item was found, @false otherwise.
1183 @see IsShown(), Show()
1185 bool Hide(wxWindow
* window
, bool recursive
= false);
1188 Hides the child @a sizer.
1190 To make a sizer item disappear, use Hide() followed by Layout().
1192 Use parameter @a recursive to hide elements found in subsizers.
1193 Returns @true if the child item was found, @false otherwise.
1195 @see IsShown(), Show()
1197 bool Hide(wxSizer
* sizer
, bool recursive
= false);
1200 Hides the item at position @a index.
1202 To make a sizer item disappear, use Hide() followed by Layout().
1204 Use parameter @a recursive to hide elements found in subsizers.
1205 Returns @true if the child item was found, @false otherwise.
1207 @see IsShown(), Show()
1209 bool Hide(size_t index
);
1212 Insert a child into the sizer before any existing item at @a index.
1214 See Add() for the meaning of the other parameters.
1216 wxSizerItem
* Insert(size_t index
, wxWindow
* window
,
1217 const wxSizerFlags
& flags
);
1220 Insert a child into the sizer before any existing item at @a index.
1222 See Add() for the meaning of the other parameters.
1224 wxSizerItem
* Insert(size_t index
, wxWindow
* window
,
1228 wxObject
* userData
= NULL
);
1231 Insert a child into the sizer before any existing item at @a index.
1233 See Add() for the meaning of the other parameters.
1235 wxSizerItem
* Insert(size_t index
, wxSizer
* sizer
,
1236 const wxSizerFlags
& flags
);
1239 Insert a child into the sizer before any existing item at @a index.
1241 See Add() for the meaning of the other parameters.
1243 wxSizerItem
* Insert(size_t index
, wxSizer
* sizer
,
1247 wxObject
* userData
= NULL
);
1250 Insert a child into the sizer before any existing item at @a index.
1252 See Add() for the meaning of the other parameters.
1254 wxSizerItem
* Insert(size_t index
, int width
, int height
,
1258 wxObject
* userData
= NULL
);
1261 Inserts non-stretchable space to the sizer.
1262 More readable way of calling wxSizer::Insert(size, size, 0).
1264 wxSizerItem
* InsertSpacer(size_t index
, int size
);
1267 Inserts stretchable space to the sizer.
1268 More readable way of calling wxSizer::Insert(0, 0, prop).
1270 wxSizerItem
* InsertStretchSpacer(size_t index
, int prop
= 1);
1273 Returns @true if the @a window is shown.
1275 @see Hide(), Show(), wxSizerItem::IsShown()
1277 bool IsShown(wxWindow
* window
) const;
1280 Returns @true if the @a sizer is shown.
1282 @see Hide(), Show(), wxSizerItem::IsShown()
1284 bool IsShown(wxSizer
* sizer
) const;
1287 Returns @true if the item at @a index is shown.
1289 @see Hide(), Show(), wxSizerItem::IsShown()
1291 bool IsShown(size_t index
) const;
1294 Call this to force layout of the children anew, e.g. after having added a child
1295 to or removed a child (window, other sizer or space) from the sizer while
1296 keeping the current dimension.
1298 virtual void Layout();
1301 Same as Add(), but prepends the items to the beginning of the
1302 list of items (windows, subsizers or spaces) owned by this sizer.
1304 wxSizerItem
* Prepend(wxWindow
* window
, const wxSizerFlags
& flags
);
1307 Same as Add(), but prepends the items to the beginning of the
1308 list of items (windows, subsizers or spaces) owned by this sizer.
1310 wxSizerItem
* Prepend(wxWindow
* window
, int proportion
= 0,
1313 wxObject
* userData
= NULL
);
1316 Same as Add(), but prepends the items to the beginning of the
1317 list of items (windows, subsizers or spaces) owned by this sizer.
1319 wxSizerItem
* Prepend(wxSizer
* sizer
,
1320 const wxSizerFlags
& flags
);
1323 Same as Add(), but prepends the items to the beginning of the
1324 list of items (windows, subsizers or spaces) owned by this sizer.
1326 wxSizerItem
* Prepend(wxSizer
* sizer
, int proportion
= 0,
1329 wxObject
* userData
= NULL
);
1332 Same as Add(), but prepends the items to the beginning of the
1333 list of items (windows, subsizers or spaces) owned by this sizer.
1335 wxSizerItem
* Prepend(int width
, int height
,
1339 wxObject
* userData
= NULL
);
1342 Prepends non-stretchable space to the sizer.
1343 More readable way of calling wxSizer::Prepend(size, size, 0).
1345 wxSizerItem
* PrependSpacer(int size
);
1348 Prepends stretchable space to the sizer.
1349 More readable way of calling wxSizer::Prepend(0, 0, prop).
1351 wxSizerItem
* PrependStretchSpacer(int prop
= 1);
1354 This method is abstract and has to be overwritten by any derived class.
1355 Here, the sizer will do the actual calculation of its children's
1356 positions and sizes.
1358 virtual void RecalcSizes() = 0;
1361 Removes a child window from the sizer, but does @b not destroy it
1362 (because windows are owned by their parent window, not the sizer).
1365 The overload of this method taking a wxWindow* parameter
1366 is deprecated as it does not destroy the window as would usually be
1367 expected from Remove(). You should use Detach() in new code instead.
1368 There is currently no wxSizer method that will both detach and destroy
1371 @note This method does not cause any layout or resizing to take
1372 place, call Layout() to update the layout "on screen" after
1373 removing a child from the sizer.
1375 @return @true if the child item was found and removed, @false otherwise.
1377 virtual bool Remove(wxWindow
* window
);
1380 Removes a sizer child from the sizer and destroys it.
1382 @note This method does not cause any layout or resizing to take
1383 place, call Layout() to update the layout "on screen" after
1384 removing a child from the sizer.
1386 @param sizer The wxSizer to be removed.
1388 @return @true if the child item was found and removed, @false otherwise.
1390 virtual bool Remove(wxSizer
* sizer
);
1393 Removes a child from the sizer and destroys it if it is a sizer or a
1394 spacer, but not if it is a window (because windows are owned by their
1395 parent window, not the sizer).
1397 @note This method does not cause any layout or resizing to take
1398 place, call Layout() to update the layout "on screen" after
1399 removing a child from the sizer.
1402 The position of the child in the sizer, e.g. 0 for the first item.
1404 @return @true if the child item was found and removed, @false otherwise.
1406 virtual bool Remove(int index
);
1409 Detaches the given @a oldwin from the sizer and replaces it with the
1410 given @a newwin. The detached child window is @b not deleted (because
1411 windows are owned by their parent window, not the sizer).
1413 Use parameter @a recursive to search the given element recursively in subsizers.
1415 This method does not cause any layout or resizing to take place,
1416 call Layout() to update the layout "on screen" after replacing a
1417 child from the sizer.
1419 Returns @true if the child item was found and removed, @false otherwise.
1421 virtual bool Replace(wxWindow
* oldwin
, wxWindow
* newwin
,
1422 bool recursive
= false);
1425 Detaches the given @a oldsz from the sizer and replaces it with the
1426 given @a newsz. The detached child sizer is deleted.
1428 Use parameter @a recursive to search the given element recursively in subsizers.
1430 This method does not cause any layout or resizing to take place,
1431 call Layout() to update the layout "on screen" after replacing a
1432 child from the sizer.
1434 Returns @true if the child item was found and removed, @false otherwise.
1436 virtual bool Replace(wxSizer
* oldsz
, wxSizer
* newsz
,
1437 bool recursive
= false);
1440 Detaches the given item at position @a index from the sizer and
1441 replaces it with the given wxSizerItem @a newitem.
1443 The detached child is deleted @b only if it is a sizer or a spacer
1444 (but not if it is a wxWindow because windows are owned by their
1445 parent window, not the sizer).
1447 This method does not cause any layout or resizing to take place,
1448 call Layout() to update the layout "on screen" after replacing a
1449 child from the sizer.
1451 Returns @true if the child item was found and removed, @false otherwise.
1453 virtual bool Replace(size_t index
, wxSizerItem
* newitem
);
1456 Call this to force the sizer to take the given dimension and thus force
1457 the items owned by the sizer to resize themselves according to the
1458 rules defined by the parameter in the Add() and Prepend() methods.
1460 void SetDimension(int x
, int y
, int width
, int height
);
1465 void SetDimension(const wxPoint
& pos
, const wxSize
& size
);
1468 Set an item's minimum size by window, sizer, or position.
1470 The item will be found recursively in the sizer's descendants.
1471 This function enables an application to set the size of an item after
1474 @see wxSizerItem::SetMinSize()
1476 bool SetItemMinSize(wxWindow
* window
, int width
, int height
);
1479 Set an item's minimum size by window, sizer, or position.
1481 The item will be found recursively in the sizer's descendants.
1482 This function enables an application to set the size of an item after
1485 @see wxSizerItem::SetMinSize()
1487 bool SetItemMinSize(wxSizer
* sizer
, int width
, int height
);
1490 Set an item's minimum size by window, sizer, or position.
1492 The item will be found recursively in the sizer's descendants.
1493 This function enables an application to set the size of an item after
1496 @see wxSizerItem::SetMinSize()
1498 bool SetItemMinSize(size_t index
, int width
, int height
);
1501 Call this to give the sizer a minimal size.
1503 Normally, the sizer will calculate its minimal size based purely on how
1504 much space its children need. After calling this method GetMinSize()
1505 will return either the minimal size as requested by its children or the
1506 minimal size set here, depending on which is bigger.
1508 void SetMinSize(const wxSize
& size
);
1513 void SetMinSize(int width
, int height
);
1516 This method first calls Fit() and then wxTopLevelWindow::SetSizeHints()
1517 on the @a window passed to it.
1519 This only makes sense when @a window is actually a wxTopLevelWindow such
1520 as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes.
1521 It does nothing in normal windows or controls.
1523 This method is implicitly used by wxWindow::SetSizerAndFit() which is
1524 commonly invoked in the constructor of a toplevel window itself (see
1525 the sample in the description of wxBoxSizer) if the toplevel window is
1528 void SetSizeHints(wxWindow
* window
);
1531 Tell the sizer to set the minimal size of the @a window virtual area to match
1532 the sizer's minimal size. For windows with managed scrollbars this will set them
1535 @deprecated @todo provide deprecation description
1537 @see wxScrolled::SetScrollbars()
1539 void SetVirtualSizeHints(wxWindow
* window
);
1542 Shows or hides the @a window.
1543 To make a sizer item disappear or reappear, use Show() followed by Layout().
1545 Use parameter @a recursive to show or hide elements found in subsizers.
1547 Returns @true if the child item was found, @false otherwise.
1549 @see Hide(), IsShown()
1551 bool Show(wxWindow
* window
, bool show
= true,
1552 bool recursive
= false);
1555 Shows or hides @a sizer.
1556 To make a sizer item disappear or reappear, use Show() followed by Layout().
1558 Use parameter @a recursive to show or hide elements found in subsizers.
1560 Returns @true if the child item was found, @false otherwise.
1562 @see Hide(), IsShown()
1564 bool Show(wxSizer
* sizer
, bool show
= true,
1565 bool recursive
= false);
1568 Shows the item at @a index.
1569 To make a sizer item disappear or reappear, use Show() followed by Layout().
1571 Returns @true if the child item was found, @false otherwise.
1573 @see Hide(), IsShown()
1575 bool Show(size_t index
, bool show
= true);
1583 A grid sizer is a sizer which lays out its children in a two-dimensional
1584 table with all table fields having the same size, i.e. the width of each
1585 field is the width of the widest child, the height of each field is the
1586 height of the tallest child.
1589 @category{winlayout}
1591 @see wxSizer, @ref overview_sizer
1593 class wxGridSizer
: public wxSizer
1598 Constructor for a wxGridSizer.
1600 @a rows and @a cols determine the number of columns and rows in the sizer -
1601 if either of the parameters is zero, it will be calculated to form the
1602 total number of children in the sizer, thus making the sizer grow dynamically.
1604 @a vgap and @a hgap define extra space between all children.
1606 wxGridSizer(int rows
, int cols
, int vgap
, int hgap
);
1607 wxGridSizer(int cols
, int vgap
= 0, int hgap
= 0);
1611 Returns the number of columns in the sizer.
1613 int GetCols() const;
1616 Returns the horizontal gap (in pixels) between cells in the sizer.
1618 int GetHGap() const;
1621 Returns the number of rows in the sizer.
1623 int GetRows() const;
1626 Returns the vertical gap (in pixels) between the cells in the sizer.
1628 int GetVGap() const;
1631 Sets the number of columns in the sizer.
1633 void SetCols(int cols
);
1636 Sets the horizontal gap (in pixels) between cells in the sizer.
1638 void SetHGap(int gap
);
1641 Sets the number of rows in the sizer.
1643 void SetRows(int rows
);
1646 Sets the vertical gap (in pixels) between the cells in the sizer.
1648 void SetVGap(int gap
);
1654 @class wxStaticBoxSizer
1656 wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
1657 box around the sizer.
1658 This static box may be either created independently or the sizer may create
1659 it itself as a convenience. In any case, the sizer owns the wxStaticBox control
1660 and will delete it, if it is deleted.
1663 @category{winlayout}
1665 @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer
1667 class wxStaticBoxSizer
: public wxBoxSizer
1671 This constructor uses an already existing static box.
1673 It takes the associated static box and the orientation @a orient, which
1674 can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters.
1676 wxStaticBoxSizer(wxStaticBox
* box
, int orient
);
1679 This constructor creates a new static box with the given label and parent window.
1681 wxStaticBoxSizer(int orient
, wxWindow
*parent
,
1682 const wxString
& label
= wxEmptyString
);
1685 Returns the static box associated with the sizer.
1687 wxStaticBox
* GetStaticBox() const;
1695 The basic idea behind a box sizer is that windows will most often be laid out
1696 in rather simple basic geometry, typically in a row or a column or several
1697 hierarchies of either.
1699 For more information, please see @ref overview_sizer_box.
1702 @category{winlayout}
1704 @see wxSizer, @ref overview_sizer
1706 class wxBoxSizer
: public wxSizer
1710 Constructor for a wxBoxSizer. @a orient may be either of wxVERTICAL
1711 or wxHORIZONTAL for creating either a column sizer or a row sizer.
1713 wxBoxSizer(int orient
);
1716 Implements the calculation of a box sizer's minimal.
1718 It is used internally only and must not be called by the user.
1719 Documented for information.
1721 virtual wxSize
CalcMin();
1724 Returns the orientation of the box sizer, either wxVERTICAL
1727 int GetOrientation() const;
1730 Implements the calculation of a box sizer's dimensions and then sets
1731 the size of its children (calling wxWindow::SetSize if the child is a window).
1733 It is used internally only and must not be called by the user
1734 (call Layout() if you want to resize). Documented for information.