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