]> git.saurik.com Git - wxWidgets.git/blob - interface/sizer.h
add default parameters for width and style parameters of FindOrCreatePen() for consis...
[wxWidgets.git] / 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 sizer's
879 minimal size. Unlike GetMinSize(), this method accounts for other
880 constraints imposed on @e window, namely display's size (returned size
881 will never be too large for the display) and maximum window size if
882 previously set by wxWindow::SetMaxSize(). The returned value is
883 suitable for passing to wxWindow::SetClientSize() or
884 wxWindow::SetMinClientSize().
885
886 @since 2.8.8
887
888 @see ComputeFittingWindowSize(), Fit()
889 */
890 wxSize ComputeFittingClientSize(wxWindow* window);
891
892 /**
893 Like ComputeFittingClientSize(), but converts the result into window
894 size. The returned value is suitable for passing to wxWindow::SetSize()
895 or wxWindow::SetMinSize().
896
897 @since 2.8.8
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