]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/window.h
Fixed wxPropertyGrid::HitTest() documentation
[wxWidgets.git] / interface / wx / window.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: window.h
3 // Purpose: interface of wxWindow
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
12 */
13 enum wxShowEffect
14 {
15 /// Roll window to the left
16 wxSHOW_EFFECT_ROLL_TO_LEFT,
17
18 /// Roll window to the right
19 wxSHOW_EFFECT_ROLL_TO_RIGHT,
20
21 /// Roll window to the top
22 wxSHOW_EFFECT_ROLL_TO_TOP,
23
24 /// Roll window to the bottom
25 wxSHOW_EFFECT_ROLL_TO_BOTTOM,
26
27 /// Slide window to the left
28 wxSHOW_EFFECT_SLIDE_TO_LEFT,
29
30 /// Slide window to the right
31 wxSHOW_EFFECT_SLIDE_TO_RIGHT,
32
33 /// Slide window to the top
34 wxSHOW_EFFECT_SLIDE_TO_TOP,
35
36 /// Slide window to the bottom
37 wxSHOW_EFFECT_SLIDE_TO_BOTTOM,
38
39 /// Fade in or out effect
40 wxSHOW_EFFECT_BLEND,
41
42 /// Expanding or collapsing effect
43 wxSHOW_EFFECT_EXPAND
44 };
45
46 /**
47 Different window variants, on platforms like eg mac uses different
48 rendering sizes.
49 */
50 enum wxWindowVariant
51 {
52 wxWINDOW_VARIANT_NORMAL, //!< Normal size
53 wxWINDOW_VARIANT_SMALL, //!< Smaller size (about 25 % smaller than normal)
54 wxWINDOW_VARIANT_MINI, //!< Mini size (about 33 % smaller than normal)
55 wxWINDOW_VARIANT_LARGE, //!< Large size (about 25 % larger than normal)
56 wxWINDOW_VARIANT_MAX
57 };
58
59
60 /**
61 @class wxWindow
62
63 wxWindow is the base class for all windows and represents any visible object
64 om screen. All controls, top level windows and so on are windows. Sizers and
65 device contexts are not, however, as they don't appear on screen themselves.
66
67 Please note that all children of the window will be deleted automatically by
68 the destructor before the window itself is deleted which means that you don't
69 have to worry about deleting them manually. Please see the @ref
70 overview_windowdeletion "window deletion overview" for more information.
71
72 Also note that in this, and many others, wxWidgets classes some
73 @c GetXXX() methods may be overloaded (as, for example,
74 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
75 are non-virtual because having multiple virtual functions with the same name
76 results in a virtual function name hiding at the derived class level (in
77 English, this means that the derived class has to override all overloaded
78 variants if it overrides any of them). To allow overriding them in the derived
79 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
80 and all @c GetXXX() ones are forwarded to it, so overriding the former
81 changes the behaviour of the latter.
82
83 @beginStyleTable
84 @style{wxBORDER_DEFAULT}
85 The window class will decide the kind of border to show, if any.
86 @style{wxBORDER_SIMPLE}
87 Displays a thin border around the window. wxSIMPLE_BORDER is the
88 old name for this style.
89 @style{wxBORDER_SUNKEN}
90 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
91 style.
92 @style{wxBORDER_RAISED}
93 Displays a raised border. wxRAISED_BORDER is the old name for this
94 style.
95 @style{wxBORDER_STATIC}
96 Displays a border suitable for a static control. wxSTATIC_BORDER
97 is the old name for this style. Windows only.
98 @style{wxBORDER_THEME}
99 Displays a native border suitable for a control, on the current
100 platform. On Windows XP or Vista, this will be a themed border; on
101 most other platforms a sunken border will be used. For more
102 information for themed borders on Windows, please see Themed
103 borders on Windows.
104 @style{wxBORDER_NONE}
105 Displays no border, overriding the default border style for the
106 window. wxNO_BORDER is the old name for this style.
107 @style{wxBORDER_DOUBLE}
108 This style is obsolete and should not be used.
109 @style{wxTRANSPARENT_WINDOW}
110 The window is transparent, that is, it will not receive paint
111 events. Windows only.
112 @style{wxTAB_TRAVERSAL}
113 Use this to enable tab traversal for non-dialog windows.
114 @style{wxWANTS_CHARS}
115 Use this to indicate that the window wants to get all char/key
116 events for all keys - even for keys like TAB or ENTER which are
117 usually used for dialog navigation and which wouldn't be generated
118 without this style. If you need to use this style in order to get
119 the arrows or etc., but would still like to have normal keyboard
120 navigation take place, you should call Navigate in response to the
121 key events for Tab and Shift-Tab.
122 @style{wxNO_FULL_REPAINT_ON_RESIZE}
123 On Windows, this style used to disable repainting the window
124 completely when its size is changed. Since this behaviour is now
125 the default, the style is now obsolete and no longer has an effect.
126 @style{wxVSCROLL}
127 Use this style to enable a vertical scrollbar. Notice that this
128 style cannot be used with native controls which don't support
129 scrollbars nor with top-level windows in most ports.
130 @style{wxHSCROLL}
131 Use this style to enable a horizontal scrollbar. The same
132 limitations as for wxVSCROLL apply to this style.
133 @style{wxALWAYS_SHOW_SB}
134 If a window has scrollbars, disable them instead of hiding them
135 when they are not needed (i.e. when the size of the window is big
136 enough to not require the scrollbars to navigate it). This style is
137 currently implemented for wxMSW, wxGTK and wxUniversal and does
138 nothing on the other platforms.
139 @style{wxCLIP_CHILDREN}
140 Use this style to eliminate flicker caused by the background being
141 repainted, then children being painted over them. Windows only.
142 @style{wxFULL_REPAINT_ON_RESIZE}
143 Use this style to force a complete redraw of the window whenever it
144 is resized instead of redrawing just the part of the window
145 affected by resizing. Note that this was the behaviour by default
146 before 2.5.1 release and that if you experience redraw problems
147 with code which previously used to work you may want to try this.
148 Currently this style applies on GTK+ 2 and Windows only, and full
149 repainting is always done on other platforms.
150 @endStyleTable
151
152 @beginExtraStyleTable
153 @style{wxWS_EX_VALIDATE_RECURSIVELY}
154 By default, wxWindow::Validate(), wxWindow::TransferDataTo() and
155 wxWindow::TransferDataFromWindow() only work on
156 direct children of the window (compatible behaviour).
157 Set this flag to make them recursively descend into all subwindows.
158 @style{wxWS_EX_BLOCK_EVENTS}
159 wxCommandEvents and the objects of the derived classes are
160 forwarded to the parent window and so on recursively by default.
161 Using this flag for the given window allows to block this
162 propagation at this window, i.e. prevent the events from being
163 propagated further upwards. Dialogs have this flag on by default
164 for the reasons explained in the @ref overview_events.
165 @style{wxWS_EX_TRANSIENT}
166 Don't use this window as an implicit parent for the other windows:
167 this must be used with transient windows as otherwise there is the
168 risk of creating a dialog/frame with this window as a parent which
169 would lead to a crash if the parent is destroyed before the child.
170 @style{wxWS_EX_CONTEXTHELP}
171 Under Windows, puts a query button on the caption. When pressed,
172 Windows will go into a context-sensitive help mode and wxWidgets
173 will send a @c wxEVT_HELP event if the user clicked on an application window.
174 This style cannot be used (because of the underlying native behaviour)
175 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
176 are automatically turned off if this one is used.
177 @style{wxWS_EX_PROCESS_IDLE}
178 This window should always process idle events, even if the mode set
179 by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED.
180 @style{wxWS_EX_PROCESS_UI_UPDATES}
181 This window should always process UI update events, even if the
182 mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED.
183 @endExtraStyleTable
184
185 @library{wxcore}
186 @category{miscwnd}
187
188 @see @ref overview_events "Event handling overview",
189 @ref overview_windowsizing "Window sizing overview"
190 */
191 class wxWindow : public wxEvtHandler
192 {
193 public:
194 /**
195 Default constructor
196 */
197 wxWindow();
198
199 /**
200 Constructs a window, which can be a child of a frame, dialog or any other
201 non-control window.
202
203 @param parent
204 Pointer to a parent window.
205 @param id
206 Window identifier. If wxID_ANY, will automatically create an identifier.
207 @param pos
208 Window position. wxDefaultPosition indicates that wxWidgets
209 should generate a default position for the window.
210 If using the wxWindow class directly, supply an actual position.
211 @param size
212 Window size. wxDefaultSize indicates that wxWidgets should generate
213 a default size for the window. If no suitable size can be found, the
214 window will be sized to 20x20 pixels so that the window is visible but
215 obviously not correctly sized.
216 @param style
217 Window style. For generic window styles, please see wxWindow.
218 @param name
219 Window name.
220 */
221 wxWindow(wxWindow* parent, wxWindowID id,
222 const wxPoint& pos = wxDefaultPosition,
223 const wxSize& size = wxDefaultSize,
224 long style = 0,
225 const wxString& name = wxPanelNameStr);
226
227 /**
228 Destructor.
229
230 Deletes all sub-windows, then deletes itself. Instead of using
231 the @b delete operator explicitly, you should normally use Destroy()
232 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
233
234 @see @ref overview_windowdeletion "Window Deletion Overview",
235 Destroy(), wxCloseEvent
236 */
237 virtual ~wxWindow();
238
239
240 /**
241 @name Focus functions
242
243 See also the static function FindFocus().
244 */
245 //@{
246
247 /**
248 This method may be overridden in the derived classes to return @false to
249 indicate that this control doesn't accept input at all (i.e. behaves like
250 e.g. wxStaticText) and so doesn't need focus.
251
252 @see AcceptsFocusFromKeyboard()
253 */
254 virtual bool AcceptsFocus() const;
255
256 /**
257 This method may be overridden in the derived classes to return @false to
258 indicate that while this control can, in principle, have focus if the user
259 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
260 when using the keyboard.
261 */
262 virtual bool AcceptsFocusFromKeyboard() const;
263
264 /**
265 Overridden to indicate wehter this window or one of its children accepts
266 focus. Usually it's the same as AcceptsFocus() but is overridden for
267 container windows.
268 */
269 virtual bool AcceptsFocusRecursively() const;
270
271 /**
272 Returns @true if the window (or in case of composite controls, its main
273 child window) has focus.
274
275 @see FindFocus()
276 */
277 virtual bool HasFocus() const;
278
279 /**
280 This method is only implemented by ports which have support for
281 native TAB traversal (such as GTK+ 2.0).
282
283 It is called by wxWidgets' container control code to give the native
284 system a hint when doing TAB traversal. A call to this does not disable
285 or change the effect of programmatically calling SetFocus().
286
287 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
288 */
289 virtual void SetCanFocus(bool canFocus);
290
291 /**
292 This sets the window to receive keyboard input.
293
294 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
295 wxPanel::SetFocusIgnoringChildren
296 */
297 virtual void SetFocus();
298
299 /**
300 This function is called by wxWidgets keyboard navigation code when the user
301 gives the focus to this window from keyboard (e.g. using @c TAB key).
302
303 By default this method simply calls SetFocus() but
304 can be overridden to do something in addition to this in the derived classes.
305 */
306 virtual void SetFocusFromKbd();
307
308 //@}
309
310
311 /**
312 @name Child management functions
313 */
314 //@{
315
316 /**
317 Adds a child window. This is called automatically by window creation
318 functions so should not be required by the application programmer.
319 Notice that this function is mostly internal to wxWidgets and shouldn't be
320 called by the user code.
321
322 @param child
323 Child window to add.
324 */
325 virtual void AddChild(wxWindow* child);
326
327 /**
328 Destroys all children of a window. Called automatically by the destructor.
329 */
330 bool DestroyChildren();
331
332 /**
333 Find a child of this window, by @a id.
334 May return @a this if it matches itself.
335 */
336 wxWindow* FindWindow(long id) const;
337
338 /**
339 Find a child of this window, by name.
340 May return @a this if it matches itself.
341 */
342 wxWindow* FindWindow(const wxString& name) const;
343
344 /**
345 Returns a reference to the list of the window's children. @c wxWindowList
346 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
347 */
348 wxWindowList& GetChildren();
349
350 /**
351 @overload
352 */
353 const wxWindowList& GetChildren() const;
354
355 /**
356 Removes a child window.
357
358 This is called automatically by window deletion functions so should not
359 be required by the application programmer.
360 Notice that this function is mostly internal to wxWidgets and shouldn't be
361 called by the user code.
362
363 @param child
364 Child window to remove.
365 */
366 virtual void RemoveChild(wxWindow* child);
367
368 //@}
369
370
371 /**
372 @name Sibling and parent management functions
373 */
374 //@{
375
376 /**
377 Returns the grandparent of a window, or @NULL if there isn't one.
378 */
379 wxWindow* GetGrandParent() const;
380
381 /**
382 Returns the next window after this one among the parent children or @NULL
383 if this window is the last child.
384
385 @since 2.8.8
386
387 @see GetPrevSibling()
388 */
389 wxWindow* GetNextSibling() const;
390
391 /**
392 Returns the parent of the window, or @NULL if there is no parent.
393 */
394 wxWindow* GetParent() const;
395
396 /**
397 Returns the previous window before this one among the parent children or @c
398 @NULL if this window is the first child.
399
400 @since 2.8.8
401
402 @see GetNextSibling()
403 */
404 wxWindow* GetPrevSibling() const;
405 /**
406 Reparents the window, i.e the window will be removed from its
407 current parent window (e.g. a non-standard toolbar in a wxFrame)
408 and then re-inserted into another.
409
410 @param newParent
411 New parent.
412 */
413 virtual bool Reparent(wxWindow* newParent);
414
415 //@}
416
417
418 /**
419 @name Scrolling and scrollbars functions
420
421 Note that these methods don't work with native controls which don't use
422 wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
423 */
424 //@{
425
426 /**
427 Call this function to force one or both scrollbars to be always shown, even if
428 the window is big enough to show its entire contents without scrolling.
429
430 @since 2.9.0
431
432 @param hflag
433 Whether the horizontal scroll bar should always be visible.
434 @param vflag
435 Whether the vertical scroll bar should always be visible.
436
437 @remarks This function is currently only implemented under Mac/Carbon.
438 */
439 virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
440
441 /**
442 Returns the built-in scrollbar position.
443
444 @see SetScrollbar()
445 */
446 virtual int GetScrollPos(int orientation) const;
447
448 /**
449 Returns the built-in scrollbar range.
450
451 @see SetScrollbar()
452 */
453 virtual int GetScrollRange(int orientation) const;
454
455 /**
456 Returns the built-in scrollbar thumb size.
457
458 @see SetScrollbar()
459 */
460 virtual int GetScrollThumb(int orientation) const;
461
462 /**
463 Returns @true if this window has a scroll bar for this orientation.
464
465 @param orient
466 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
467 */
468 bool HasScrollbar(int orient) const;
469
470 /**
471 Return whether a scrollbar is always shown.
472
473 @param orient
474 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
475
476 @see AlwaysShowScrollbars()
477 */
478 virtual bool IsScrollbarAlwaysShown(int orient) const;
479
480 /**
481 Scrolls the window by the given number of lines down (if @a lines is
482 positive) or up.
483
484 @return Returns @true if the window was scrolled, @false if it was already
485 on top/bottom and nothing was done.
486
487 @remarks This function is currently only implemented under MSW and
488 wxTextCtrl under wxGTK (it also works for wxScrolled classes
489 under all platforms).
490
491 @see ScrollPages()
492 */
493 virtual bool ScrollLines(int lines);
494
495 /**
496 Scrolls the window by the given number of pages down (if @a pages is
497 positive) or up.
498
499 @return Returns @true if the window was scrolled, @false if it was already
500 on top/bottom and nothing was done.
501
502 @remarks This function is currently only implemented under MSW and wxGTK.
503
504 @see ScrollLines()
505 */
506 virtual bool ScrollPages(int pages);
507
508 /**
509 Physically scrolls the pixels in the window and move child windows accordingly.
510
511 @param dx
512 Amount to scroll horizontally.
513 @param dy
514 Amount to scroll vertically.
515 @param rect
516 Rectangle to scroll, if it is @NULL, the whole window is
517 scrolled (this is always the case under wxGTK which doesn't support this
518 parameter)
519
520 @remarks Note that you can often use wxScrolled instead of using this
521 function directly.
522 */
523 virtual void ScrollWindow(int dx, int dy,
524 const wxRect* rect = NULL);
525
526 /**
527 Same as #ScrollLines (-1).
528 */
529 bool LineUp();
530
531 /**
532 Same as #ScrollLines (1).
533 */
534 bool LineDown();
535
536 /**
537 Same as #ScrollPages (-1).
538 */
539 bool PageUp();
540
541 /**
542 Same as #ScrollPages (1).
543 */
544 bool PageDown();
545
546 /**
547 Sets the position of one of the built-in scrollbars.
548
549 @param orientation
550 Determines the scrollbar whose position is to be set.
551 May be wxHORIZONTAL or wxVERTICAL.
552 @param pos
553 Position in scroll units.
554 @param refresh
555 @true to redraw the scrollbar, @false otherwise.
556
557 @remarks This function does not directly affect the contents of the
558 window: it is up to the application to take note of
559 scrollbar attributes and redraw contents accordingly.
560
561 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
562 wxScrolled
563 */
564 virtual void SetScrollPos(int orientation, int pos,
565 bool refresh = true);
566
567 /**
568 Sets the scrollbar properties of a built-in scrollbar.
569
570 @param orientation
571 Determines the scrollbar whose page size is to be set.
572 May be wxHORIZONTAL or wxVERTICAL.
573 @param position
574 The position of the scrollbar in scroll units.
575 @param thumbSize
576 The size of the thumb, or visible portion of the scrollbar, in scroll units.
577 @param range
578 The maximum position of the scrollbar. Value of -1 can be used to
579 ask for the scrollbar to be shown but in the disabled state: this
580 can be used to avoid removing the scrollbar even when it is not
581 needed (currently this is only implemented in wxMSW port).
582 @param refresh
583 @true to redraw the scrollbar, @false otherwise.
584
585 @remarks
586 Let's say you wish to display 50 lines of text, using the same font.
587 The window is sized so that you can only see 16 lines at a time.
588 You would use:
589 @code
590 SetScrollbar(wxVERTICAL, 0, 16, 50);
591 @endcode
592 Note that with the window at this size, the thumb position can never
593 go above 50 minus 16, or 34. You can determine how many lines are
594 currently visible by dividing the current view size by the character
595 height in pixels.
596 When defining your own scrollbar behaviour, you will always need
597 to recalculate the scrollbar settings when the window size changes.
598 You could therefore put your scrollbar calculations and SetScrollbar
599 call into a function named AdjustScrollbars, which can be called
600 initially and also from your wxSizeEvent handler function.
601
602 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
603 */
604 virtual void SetScrollbar(int orientation, int position,
605 int thumbSize, int range,
606 bool refresh = true);
607 //@}
608
609
610 /**
611 @name Sizing functions
612
613 See also the protected functions DoGetBestSize() and SetInitialBestSize().
614 */
615 //@{
616
617 /**
618 Sets the cached best size value.
619
620 @see GetBestSize()
621 */
622 void CacheBestSize(const wxSize& size) const;
623
624 /**
625 Converts client area size @a size to corresponding window size.
626
627 In other words, the returned value is what would GetSize() return if this
628 window had client area of given size. Components with wxDefaultCoord
629 value are left unchanged. Note that the conversion is not always
630 exact, it assumes that non-client area doesn't change and so doesn't
631 take into account things like menu bar (un)wrapping or (dis)appearance
632 of the scrollbars.
633
634 @since 2.8.8
635
636 @see WindowToClientSize()
637 */
638 virtual wxSize ClientToWindowSize(const wxSize& size) const;
639
640 /**
641 Converts window size @a size to corresponding client area size
642 In other words, the returned value is what would GetClientSize() return if
643 this window had given window size. Components with wxDefaultCoord value
644 are left unchanged.
645
646 Note that the conversion is not always exact, it assumes that
647 non-client area doesn't change and so doesn't take into account things
648 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
649
650 @since 2.8.8
651
652 @see ClientToWindowSize()
653 */
654 virtual wxSize WindowToClientSize(const wxSize& size) const;
655
656 /**
657 Sizes the window so that it fits around its subwindows.
658
659 This function won't do anything if there are no subwindows and will only really
660 work correctly if sizers are used for the subwindows layout.
661
662 Also, if the window has exactly one subwindow it is better (faster and the result
663 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
664 to call:
665
666 @code
667 window->SetClientSize(child->GetSize());
668 @endcode
669
670 instead of calling Fit().
671
672 @see @ref overview_windowsizing
673 */
674 virtual void Fit();
675
676 /**
677 Similar to Fit(), but sizes the interior (virtual) size of a window.
678
679 Mainly useful with scrolled windows to reset scrollbars after sizing
680 changes that do not trigger a size event, and/or scrolled windows without
681 an interior sizer. This function similarly won't do anything if there are
682 no subwindows.
683 */
684 virtual void FitInside();
685
686 /**
687 This functions returns the best acceptable minimal size for the window.
688
689 For example, for a static control, it will be the minimal size such that the
690 control label is not truncated. For windows containing subwindows (typically
691 wxPanel), the size returned by this function will be the same as the size
692 the window would have had after calling Fit().
693
694 Note that when you write your own widget you need to overload the
695 DoGetBestSize() function instead of this (non-virtual!) function.
696
697 @see CacheBestSize(), @ref overview_windowsizing
698 */
699 wxSize GetBestSize() const;
700
701 /**
702 Returns the size of the window 'client area' in pixels.
703
704 The client area is the area which may be drawn on by the programmer,
705 excluding title bar, border, scrollbars, etc.
706 Note that if this window is a top-level one and it is currently minimized, the
707 return size is empty (both width and height are 0).
708
709 @see GetSize(), GetVirtualSize()
710 */
711 void GetClientSize(int* width, int* height) const;
712
713 /**
714 @overload
715 */
716 wxSize GetClientSize() const;
717
718 /**
719 Merges the window's best size into the min size and returns the result.
720 This is the value used by sizers to determine the appropriate
721 ammount of space to allocate for the widget.
722
723 This is the method called by any wxSizer when they query the size
724 of a certain window or control.
725
726 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
727 */
728 virtual wxSize GetEffectiveMinSize() const;
729
730 /**
731 Returns the maximum size of window's client area.
732
733 This is an indication to the sizer layout mechanism that this is the maximum
734 possible size as well as the upper bound on window's size settable using
735 SetClientSize().
736
737 @see GetMaxSize(), @ref overview_windowsizing
738 */
739 virtual wxSize GetMaxClientSize() const;
740
741 /**
742 Returns the maximum size of the window.
743
744 This is an indication to the sizer layout mechanism that this is the maximum
745 possible size as well as the upper bound on window's size settable using SetSize().
746
747 @see GetMaxClientSize(), @ref overview_windowsizing
748 */
749 virtual wxSize GetMaxSize() const;
750
751 /**
752 Returns the minimum size of window's client area, an indication to the sizer
753 layout mechanism that this is the minimum required size of its client area.
754
755 It normally just returns the value set by SetMinClientSize(), but it can be
756 overridden to do the calculation on demand.
757
758 @see GetMinSize(), @ref overview_windowsizing
759 */
760 virtual wxSize GetMinClientSize() const;
761
762 /**
763 Returns the minimum size of the window, an indication to the sizer layout
764 mechanism that this is the minimum required size.
765
766 This method normally just returns the value set by SetMinSize(), but it
767 can be overridden to do the calculation on demand.
768
769 @see GetMinClientSize(), @ref overview_windowsizing
770 */
771 virtual wxSize GetMinSize() const;
772
773 /**
774 Returns the size of the entire window in pixels, including title bar, border,
775 scrollbars, etc.
776
777 Note that if this window is a top-level one and it is currently minimized, the
778 returned size is the restored window size, not the size of the window icon.
779
780 @param width
781 Receives the window width.
782 @param height
783 Receives the window height.
784
785 @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
786 */
787 void GetSize(int* width, int* height) const;
788
789 /**
790 See the GetSize(int*,int*) overload for more info.
791 */
792 wxSize GetSize() const;
793
794 /**
795 This gets the virtual size of the window in pixels.
796 By default it returns the client size of the window, but after a call to
797 SetVirtualSize() it will return the size set with that method.
798
799 @see @ref overview_windowsizing
800 */
801 wxSize GetVirtualSize() const;
802
803 /**
804 Like the other GetVirtualSize() overload but uses pointers instead.
805
806 @param width
807 Receives the window virtual width.
808 @param height
809 Receives the window virtual height.
810 */
811 void GetVirtualSize(int* width, int* height) const;
812
813 /**
814 Returns the size of the left/right and top/bottom borders of this window in x
815 and y components of the result respectively.
816 */
817 virtual wxSize GetWindowBorderSize() const;
818
819 /**
820 Resets the cached best size value so it will be recalculated the next time it
821 is needed.
822
823 @see CacheBestSize()
824 */
825 void InvalidateBestSize();
826
827 /**
828 Posts a size event to the window.
829
830 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
831 */
832 void PostSizeEvent();
833
834 /**
835 Posts a size event to the parent of this window.
836
837 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
838 argument.
839 */
840 void PostSizeEventToParent();
841
842 /**
843 This function sends a dummy @ref wxSizeEvent "size event" to
844 the window allowing it to re-layout its children positions.
845
846 It is sometimes useful to call this function after adding or deleting a
847 children after the frame creation or if a child size changes. Note that
848 if the frame is using either sizers or constraints for the children
849 layout, it is enough to call wxWindow::Layout() directly and this
850 function should not be used in this case.
851
852 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
853 the event, i.e. schedules it for later processing, instead of
854 dispatching it directly. You can also use PostSizeEvent() as a more
855 readable equivalent of calling this function with this flag.
856
857 @param flags
858 May include @c wxSEND_EVENT_POST. Default value is 0.
859 */
860 virtual void SendSizeEvent(int flags = 0);
861
862 /**
863 Safe wrapper for GetParent()->SendSizeEvent().
864
865 This function simply checks that the window has a valid parent which is
866 not in process of being deleted and calls SendSizeEvent() on it. It is
867 used internally by windows such as toolbars changes to whose state
868 should result in parent re-layout (e.g. when a toolbar is added to the
869 top of the window, all the other windows must be shifted down).
870
871 @see PostSizeEventToParent()
872
873 @param flags
874 See description of this parameter in SendSizeEvent() documentation.
875 */
876 void SendSizeEventToParent(int flags = 0);
877
878 /**
879 This sets the size of the window client area in pixels.
880
881 Using this function to size a window tends to be more device-independent
882 than SetSize(), since the application need not worry about what dimensions
883 the border or title bar have when trying to fit the window around panel
884 items, for example.
885
886 @see @ref overview_windowsizing
887 */
888 virtual void SetClientSize(int width, int height);
889
890 /**
891 @overload
892 */
893 virtual void SetClientSize(const wxSize& size);
894
895 /**
896 This normally does not need to be called by user code.
897 It is called when a window is added to a sizer, and is used so the window
898 can remove itself from the sizer when it is destroyed.
899 */
900 void SetContainingSizer(wxSizer* sizer);
901
902 /**
903 A @e smart SetSize that will fill in default size components with the
904 window's @e best size values.
905
906 Also sets the window's minsize to the value passed in for use with sizers.
907 This means that if a full or partial size is passed to this function then
908 the sizers will use that size instead of the results of GetBestSize() to
909 determine the minimum needs of the window for layout.
910
911 Most controls will use this to set their initial size, and their min
912 size to the passed in value (if any.)
913
914 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
915 @ref overview_windowsizing
916 */
917 void SetInitialSize(const wxSize& size = wxDefaultSize);
918
919 /**
920 Sets the maximum client size of the window, to indicate to the sizer
921 layout mechanism that this is the maximum possible size of its client area.
922
923 Note that this method is just a shortcut for:
924 @code
925 SetMaxSize(ClientToWindowSize(size));
926 @endcode
927
928 @see SetMaxSize(), @ref overview_windowsizing
929 */
930 virtual void SetMaxClientSize(const wxSize& size);
931
932 /**
933 Sets the maximum size of the window, to indicate to the sizer layout mechanism
934 that this is the maximum possible size.
935
936 @see SetMaxClientSize(), @ref overview_windowsizing
937 */
938 virtual void SetMaxSize(const wxSize& size);
939
940 /**
941 Sets the minimum client size of the window, to indicate to the sizer
942 layout mechanism that this is the minimum required size of window's client
943 area.
944
945 You may need to call this if you change the window size after
946 construction and before adding to its parent sizer.
947
948 Note, that just as with SetMinSize(), calling this method doesn't
949 prevent the program from explicitly making the window smaller than the
950 specified size.
951
952 Note that this method is just a shortcut for:
953 @code
954 SetMinSize(ClientToWindowSize(size));
955 @endcode
956
957 @see SetMinSize(), @ref overview_windowsizing
958 */
959 virtual void SetMinClientSize(const wxSize& size);
960
961 /**
962 Sets the minimum size of the window, to indicate to the sizer layout
963 mechanism that this is the minimum required size.
964
965 You may need to call this if you change the window size after
966 construction and before adding to its parent sizer.
967
968 Notice that calling this method doesn't prevent the program from making
969 the window explicitly smaller than the specified size by calling
970 SetSize(), it just ensures that it won't become smaller than this size
971 during the automatic layout.
972
973 @see SetMinClientSize(), @ref overview_windowsizing
974 */
975 virtual void SetMinSize(const wxSize& size);
976
977 /**
978 Sets the size of the window in pixels.
979
980 @param x
981 Required x position in pixels, or wxDefaultCoord to indicate that the
982 existing value should be used.
983 @param y
984 Required y position in pixels, or wxDefaultCoord to indicate that the
985 existing value should be used.
986 @param width
987 Required width in pixels, or wxDefaultCoord to indicate that the existing
988 value should be used.
989 @param height
990 Required height position in pixels, or wxDefaultCoord to indicate that the
991 existing value should be used.
992 @param sizeFlags
993 Indicates the interpretation of other parameters.
994 It is a bit list of the following:
995 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
996 a wxWidgets-supplied default width.
997 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
998 a wxWidgets-supplied default height.
999 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1000 a wxWidgets-supplied default size.
1001 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1002 if wxDefaultCoord values are supplied.
1003 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1004 wxDefaultCoord) to be interpreted as real
1005 dimensions, not default values.
1006 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1007 already the same as the parameters of this function,
1008 nothing is done. but with this flag a window resize may
1009 be forced even in this case (supported in wx 2.6.2 and
1010 later and only implemented for MSW and ignored elsewhere
1011 currently).
1012
1013 @remarks This overload sets the position and optionally size, of the window.
1014 Parameters may be wxDefaultCoord to indicate either that a default
1015 should be supplied by wxWidgets, or that the current value of the
1016 dimension should be used.
1017
1018 @see Move(), @ref overview_windowsizing
1019 */
1020 void SetSize(int x, int y, int width, int height,
1021 int sizeFlags = wxSIZE_AUTO);
1022
1023 /**
1024 Sets the size of the window in pixels.
1025 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1026
1027 @remarks This form must be used with non-default width and height values.
1028
1029 @see Move(), @ref overview_windowsizing
1030 */
1031 virtual void SetSize(const wxRect& rect);
1032
1033 /**
1034 @overload
1035 */
1036 virtual void SetSize(const wxSize& size);
1037
1038 /**
1039 @overload
1040 */
1041 virtual void SetSize(int width, int height);
1042
1043 /**
1044 Use of this function for windows which are not toplevel windows
1045 (such as wxDialog or wxFrame) is discouraged.
1046 Please use SetMinSize() and SetMaxSize() instead.
1047
1048 @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
1049 */
1050 void SetSizeHints( const wxSize& minSize,
1051 const wxSize& maxSize=wxDefaultSize,
1052 const wxSize& incSize=wxDefaultSize);
1053
1054 /**
1055 Sets the virtual size of the window in pixels.
1056
1057 @see @ref overview_windowsizing
1058 */
1059 void SetVirtualSize(int width, int height);
1060
1061 /**
1062 @overload
1063 */
1064 void SetVirtualSize(const wxSize& size);
1065
1066 //@}
1067
1068
1069 /**
1070 @name Positioning functions
1071 */
1072 //@{
1073
1074 /**
1075 A synonym for Centre().
1076 */
1077 void Center(int dir = wxBOTH);
1078
1079 /**
1080 A synonym for CentreOnParent().
1081 */
1082 void CenterOnParent(int dir = wxBOTH);
1083
1084 /**
1085 Centres the window.
1086
1087 @param direction
1088 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1089 or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
1090 if you want to center the window on the entire screen and not on its
1091 parent window.
1092
1093 @remarks If the window is a top level one (i.e. doesn't have a parent),
1094 it will be centered relative to the screen anyhow.
1095
1096 @see Center()
1097 */
1098 void Centre(int direction = wxBOTH);
1099
1100 /**
1101 Centres the window on its parent. This is a more readable synonym for Centre().
1102
1103 @param direction
1104 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1105 or wxBOTH.
1106
1107 @remarks This methods provides for a way to center top level windows over
1108 their parents instead of the entire screen. If there
1109 is no parent or if the window is not a top level
1110 window, then behaviour is the same as Centre().
1111
1112 @see wxTopLevelWindow::CentreOnScreen
1113 */
1114 void CentreOnParent(int direction = wxBOTH);
1115 /**
1116 This gets the position of the window in pixels, relative to the parent window
1117 for the child windows or relative to the display origin for the top level windows.
1118
1119 @param x
1120 Receives the x position of the window if non-@NULL.
1121 @param y
1122 Receives the y position of the window if non-@NULL.
1123
1124 @see GetScreenPosition()
1125 */
1126 void GetPosition(int* x, int* y) const;
1127
1128 /**
1129 This gets the position of the window in pixels, relative to the parent window
1130 for the child windows or relative to the display origin for the top level windows.
1131
1132 @see GetScreenPosition()
1133 */
1134 wxPoint GetPosition() const;
1135
1136 /**
1137 Returns the position and size of the window as a wxRect object.
1138
1139 @see GetScreenRect()
1140 */
1141 wxRect GetRect() const;
1142
1143 /**
1144 Returns the window position in screen coordinates, whether the window is a
1145 child window or a top level one.
1146
1147 @param x
1148 Receives the x position of the window on the screen if non-@NULL.
1149 @param y
1150 Receives the y position of the window on the screen if non-@NULL.
1151
1152 @see GetPosition()
1153 */
1154 void GetScreenPosition(int* x, int* y) const;
1155
1156 /**
1157 Returns the window position in screen coordinates, whether the window is a
1158 child window or a top level one.
1159
1160 @see GetPosition()
1161 */
1162 wxPoint GetScreenPosition() const;
1163
1164 /**
1165 Returns the position and size of the window on the screen as a wxRect object.
1166
1167 @see GetRect()
1168 */
1169 wxRect GetScreenRect() const;
1170
1171 /**
1172 Moves the window to the given position.
1173
1174 @param x
1175 Required x position.
1176 @param y
1177 Required y position.
1178 @param flags
1179 See SetSize() for more info about this parameter.
1180
1181 @remarks Implementations of SetSize can also implicitly implement the
1182 Move() function, which is defined in the base wxWindow class as the call:
1183 @code
1184 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1185 @endcode
1186
1187 @see SetSize()
1188 */
1189 void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);
1190
1191 /**
1192 Moves the window to the given position.
1193
1194 @param pt
1195 wxPoint object representing the position.
1196 @param flags
1197 See SetSize() for more info about this parameter.
1198
1199 @remarks Implementations of SetSize() can also implicitly implement the
1200 Move() function, which is defined in the base wxWindow class as the call:
1201 @code
1202 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1203 @endcode
1204
1205 @see SetSize()
1206 */
1207 void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
1208
1209 //@}
1210
1211
1212 /**
1213 @name Coordinate conversion functions
1214 */
1215 //@{
1216
1217 /**
1218 Converts to screen coordinates from coordinates relative to this window.
1219
1220 @param x
1221 A pointer to a integer value for the x coordinate. Pass the client
1222 coordinate in, and a screen coordinate will be passed out.
1223 @param y
1224 A pointer to a integer value for the y coordinate. Pass the client
1225 coordinate in, and a screen coordinate will be passed out.
1226
1227 @beginWxPythonOnly
1228 In place of a single overloaded method name, wxPython implements the following methods:
1229 - ClientToScreen(point): Accepts and returns a wxPoint
1230 - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
1231 @endWxPythonOnly
1232 */
1233 void ClientToScreen(int* x, int* y) const;
1234
1235 /**
1236 Converts to screen coordinates from coordinates relative to this window.
1237
1238 @param pt
1239 The client position for the second form of the function.
1240 */
1241 wxPoint ClientToScreen(const wxPoint& pt) const;
1242
1243 /**
1244 Converts a point or size from dialog units to pixels.
1245
1246 For the x dimension, the dialog units are multiplied by the average character
1247 width and then divided by 4.
1248 For the y dimension, the dialog units are multiplied by the average character
1249 height and then divided by 8.
1250
1251 @remarks Dialog units are used for maintaining a dialog's proportions
1252 even if the font changes.
1253 You can also use these functions programmatically.
1254 A convenience macro is defined:
1255 @code
1256 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1257 @endcode
1258
1259 @see ConvertPixelsToDialog()
1260 */
1261 wxPoint ConvertDialogToPixels(const wxPoint& pt);
1262
1263 /**
1264 @overload
1265 */
1266 wxSize ConvertDialogToPixels(const wxSize& sz);
1267
1268 /**
1269 Converts a point or size from pixels to dialog units.
1270
1271 For the x dimension, the pixels are multiplied by 4 and then divided by the
1272 average character width.
1273 For the y dimension, the pixels are multiplied by 8 and then divided by the
1274 average character height.
1275
1276 @remarks Dialog units are used for maintaining a dialog's proportions
1277 even if the font changes.
1278
1279 @see ConvertDialogToPixels()
1280 */
1281 wxPoint ConvertPixelsToDialog(const wxPoint& pt);
1282
1283 /**
1284 @overload
1285 */
1286 wxSize ConvertPixelsToDialog(const wxSize& sz);
1287
1288 /**
1289 Converts from screen to client window coordinates.
1290
1291 @param x
1292 Stores the screen x coordinate and receives the client x coordinate.
1293 @param y
1294 Stores the screen x coordinate and receives the client x coordinate.
1295 */
1296 void ScreenToClient(int* x, int* y) const;
1297
1298 /**
1299 Converts from screen to client window coordinates.
1300
1301 @param pt
1302 The screen position.
1303 */
1304 wxPoint ScreenToClient(const wxPoint& pt) const;
1305
1306 //@}
1307
1308
1309 /**
1310 @name Drawing-related functions
1311 */
1312 //@{
1313
1314 /**
1315 Clears the window by filling it with the current background colour. Does not
1316 cause an erase background event to be generated.
1317 */
1318 virtual void ClearBackground();
1319
1320 /**
1321 Freezes the window or, in other words, prevents any updates from taking
1322 place on screen, the window is not redrawn at all.
1323
1324 Thaw() must be called to reenable window redrawing. Calls to these two
1325 functions may be nested but to ensure that the window is properly
1326 repainted again, you must thaw it exactly as many times as you froze it.
1327
1328 If the window has any children, they are recursively frozen too.
1329
1330 This method is useful for visual appearance optimization (for example,
1331 it is a good idea to use it before doing many large text insertions in
1332 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1333 platforms nor for all controls so it is mostly just a hint to wxWidgets
1334 and not a mandatory directive.
1335
1336 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1337 */
1338 void Freeze();
1339
1340 /**
1341 Reenables window updating after a previous call to Freeze().
1342
1343 To really thaw the control, it must be called exactly the same number
1344 of times as Freeze().
1345
1346 If the window has any children, they are recursively thawn too.
1347
1348 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1349 */
1350 void Thaw();
1351
1352 /**
1353 Returns @true if the window is currently frozen by a call to Freeze().
1354
1355 @see Freeze(), Thaw()
1356 */
1357 bool IsFrozen() const;
1358
1359 /**
1360 Returns the background colour of the window.
1361
1362 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1363 */
1364 wxColour GetBackgroundColour() const;
1365
1366 /**
1367 Returns the background style of the window.
1368 The background style can be one of the wxBackgroundStyle.
1369
1370 @see SetBackgroundColour(), GetForegroundColour(),
1371 SetBackgroundStyle(), SetTransparent()
1372 */
1373 virtual wxBackgroundStyle GetBackgroundStyle() const;
1374 /**
1375 Returns the character height for this window.
1376 */
1377 virtual int GetCharHeight() const;
1378
1379 /**
1380 Returns the average character width for this window.
1381 */
1382 virtual int GetCharWidth() const;
1383
1384 /**
1385 Currently this is the same as calling
1386 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1387
1388 One advantage of using this function compared to the static version is that
1389 the call is automatically dispatched to the correct class (as usual with
1390 virtual functions) and you don't have to specify the class name explicitly.
1391
1392 The other one is that in the future this function could return different
1393 results, for example it might return a different font for an "Ok" button
1394 than for a generic button if the users GUI is configured to show such buttons
1395 in bold font. Of course, the down side is that it is impossible to call this
1396 function without actually having an object to apply it to whereas the static
1397 version can be used without having to create an object first.
1398 */
1399 virtual wxVisualAttributes GetDefaultAttributes() const;
1400
1401 /**
1402 Returns the font for this window.
1403
1404 @see SetFont()
1405 */
1406 wxFont GetFont() const;
1407
1408 /**
1409 Returns the foreground colour of the window.
1410
1411 @remarks The interpretation of foreground colour is open to
1412 interpretation according to the window class; it may be
1413 the text colour or other colour, or it may not be used at all.
1414
1415 @see SetForegroundColour(), SetBackgroundColour(),
1416 GetBackgroundColour()
1417 */
1418 wxColour GetForegroundColour() const;
1419
1420 /**
1421 Gets the dimensions of the string as it would be drawn on the
1422 window with the currently selected font.
1423
1424 The text extent is returned in @a w and @a h pointers.
1425
1426 @param string
1427 String whose extent is to be measured.
1428 @param w
1429 Return value for width.
1430 @param h
1431 Return value for height.
1432 @param descent
1433 Return value for descent (optional).
1434 @param externalLeading
1435 Return value for external leading (optional).
1436 @param font
1437 Font to use instead of the current window font (optional).
1438 */
1439 virtual void GetTextExtent(const wxString& string, int* w, int* h,
1440 int* descent = NULL,
1441 int* externalLeading = NULL,
1442 const wxFont* font = NULL) const;
1443
1444 /**
1445 Gets the dimensions of the string as it would be drawn on the
1446 window with the currently selected font.
1447 */
1448 wxSize GetTextExtent(const wxString& string) const;
1449
1450 /**
1451 Returns the region specifying which parts of the window have been damaged.
1452 Should only be called within an wxPaintEvent handler.
1453
1454 @see wxRegion, wxRegionIterator
1455 */
1456 const wxRegion& GetUpdateRegion() const;
1457
1458 /**
1459 Returns @true if this window background is transparent (as, for example,
1460 for wxStaticText) and should show the parent window background.
1461
1462 This method is mostly used internally by the library itself and you normally
1463 shouldn't have to call it. You may, however, have to override it in your
1464 wxWindow-derived class to ensure that background is painted correctly.
1465 */
1466 virtual bool HasTransparentBackground();
1467
1468 /**
1469 Causes this window, and all of its children recursively (except under wxGTK1
1470 where this is not implemented), to be repainted. Note that repainting doesn't
1471 happen immediately but only during the next event loop iteration, if you need
1472 to update the window immediately you should use Update() instead.
1473
1474 @param eraseBackground
1475 If @true, the background will be erased.
1476 @param rect
1477 If non-@NULL, only the given rectangle will be treated as damaged.
1478
1479 @see RefreshRect()
1480 */
1481 virtual void Refresh(bool eraseBackground = true,
1482 const wxRect* rect = NULL);
1483
1484 /**
1485 Redraws the contents of the given rectangle: only the area inside it will be
1486 repainted.
1487
1488 This is the same as Refresh() but has a nicer syntax as it can be called
1489 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1490 */
1491 void RefreshRect(const wxRect& rect, bool eraseBackground = true);
1492
1493 /**
1494 Calling this method immediately repaints the invalidated area of the window and
1495 all of its children recursively while this would usually only happen when the
1496 flow of control returns to the event loop.
1497
1498 Notice that this function doesn't invalidate any area of the window so
1499 nothing happens if nothing has been invalidated (i.e. marked as requiring
1500 a redraw). Use Refresh() first if you want to immediately redraw the
1501 window unconditionally.
1502 */
1503 virtual void Update();
1504
1505 /**
1506 Sets the background colour of the window.
1507 Please see InheritAttributes() for explanation of the difference between
1508 this method and SetOwnBackgroundColour().
1509
1510 @param colour
1511 The colour to be used as the background colour, pass
1512 wxNullColour to reset to the default colour.
1513
1514 @remarks The background colour is usually painted by the default
1515 wxEraseEvent event handler function under Windows and
1516 automatically under GTK.
1517 Note that setting the background colour does not cause an
1518 immediate refresh, so you may wish to call wxWindow::ClearBackground
1519 or wxWindow::Refresh after calling this function.
1520 Using this function will disable attempts to use themes for
1521 this window, if the system supports them. Use with care since
1522 usually the themes represent the appearance chosen by the user
1523 to be used for all applications on the system.
1524
1525 @see GetBackgroundColour(), SetForegroundColour(),
1526 GetForegroundColour(), ClearBackground(),
1527 Refresh(), wxEraseEvent
1528 */
1529 virtual bool SetBackgroundColour(const wxColour& colour);
1530
1531 /**
1532 Sets the background style of the window. see GetBackgroundStyle() for
1533 the description of the possible style values.
1534
1535 @see SetBackgroundColour(), GetForegroundColour(),
1536 SetTransparent()
1537 */
1538 virtual bool SetBackgroundStyle(wxBackgroundStyle style);
1539
1540 /**
1541 Sets the font for this window. This function should not be called for the
1542 parent window if you don't want its font to be inherited by its children,
1543 use SetOwnFont() instead in this case and see InheritAttributes() for more
1544 explanations.
1545
1546 Please notice that the given font is not automatically used for
1547 wxPaintDC objects associated with this window, you need to
1548 call wxDC::SetFont too. However this font is used by
1549 any standard controls for drawing their text as well as by
1550 GetTextExtent().
1551
1552 @param font
1553 Font to associate with this window, pass
1554 wxNullFont to reset to the default font.
1555
1556 @return @true if the want was really changed, @false if it was already set
1557 to this font and so nothing was done.
1558
1559 @see GetFont(), InheritAttributes()
1560 */
1561 virtual bool SetFont(const wxFont& font);
1562
1563 /**
1564 Sets the foreground colour of the window.
1565 Please see InheritAttributes() for explanation of the difference between
1566 this method and SetOwnForegroundColour().
1567
1568 @param colour
1569 The colour to be used as the foreground colour, pass
1570 wxNullColour to reset to the default colour.
1571
1572 @remarks The interpretation of foreground colour is open to
1573 interpretation according to the window class; it may be
1574 the text colour or other colour, or it may not be used at all.
1575
1576 @see GetForegroundColour(), SetBackgroundColour(),
1577 GetBackgroundColour(), ShouldInheritColours()
1578 */
1579 virtual bool SetForegroundColour(const wxColour& colour);
1580
1581 /**
1582 Sets the background colour of the window but prevents it from being inherited
1583 by the children of this window.
1584
1585 @see SetBackgroundColour(), InheritAttributes()
1586 */
1587 void SetOwnBackgroundColour(const wxColour& colour);
1588
1589 /**
1590 Sets the font of the window but prevents it from being inherited by the
1591 children of this window.
1592
1593 @see SetFont(), InheritAttributes()
1594 */
1595 void SetOwnFont(const wxFont& font);
1596
1597 /**
1598 Sets the foreground colour of the window but prevents it from being inherited
1599 by the children of this window.
1600
1601 @see SetForegroundColour(), InheritAttributes()
1602 */
1603 void SetOwnForegroundColour(const wxColour& colour);
1604
1605 /**
1606 @deprecated use wxDC::SetPalette instead.
1607 */
1608 void SetPalette(const wxPalette& pal);
1609
1610 /**
1611 Return @true from here to allow the colours of this window to be changed by
1612 InheritAttributes(), returning @false forbids inheriting them from the parent window.
1613
1614 The base class version returns @false, but this method is overridden in
1615 wxControl where it returns @true.
1616 */
1617 virtual bool ShouldInheritColours() const;
1618
1619 /**
1620 This function tells a window if it should use the system's "theme" code
1621 to draw the windows' background instead if its own background drawing
1622 code. This does not always have any effect since the underlying platform
1623 obviously needs to support the notion of themes in user defined windows.
1624 One such platform is GTK+ where windows can have (very colourful) backgrounds
1625 defined by a user's selected theme.
1626
1627 Dialogs, notebook pages and the status bar have this flag set to @true
1628 by default so that the default look and feel is simulated best.
1629 */
1630 virtual void SetThemeEnabled(bool enable);
1631
1632 /**
1633 Returns @true if the system supports transparent windows and calling
1634 SetTransparent() may succeed. If this function returns @false, transparent
1635 windows are definitely not supported by the current system.
1636 */
1637 virtual bool CanSetTransparent();
1638
1639 /**
1640 Set the transparency of the window. If the system supports transparent windows,
1641 returns @true, otherwise returns @false and the window remains fully opaque.
1642 See also CanSetTransparent().
1643
1644 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1645 fully transparent window and 255 to the fully opaque one. The constants
1646 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1647 */
1648 virtual bool SetTransparent(wxByte alpha);
1649
1650 //@}
1651
1652
1653 /**
1654 @name Event-handling functions
1655
1656 wxWindow allows you to build a (sort of) stack of event handlers which
1657 can be used to override the window's own event handling.
1658 */
1659 //@{
1660
1661 /**
1662 Returns the event handler for this window.
1663 By default, the window is its own event handler.
1664
1665 @see SetEventHandler(), PushEventHandler(),
1666 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1667 */
1668 wxEvtHandler* GetEventHandler() const;
1669
1670 /**
1671 This function will generate the appropriate call to Navigate() if the key
1672 event is one normally used for keyboard navigation and return @true in this case.
1673
1674 @return Returns @true if the key pressed was for navigation and was
1675 handled, @false otherwise.
1676
1677 @see Navigate()
1678 */
1679 bool HandleAsNavigationKey(const wxKeyEvent& event);
1680
1681 /**
1682 Shorthand for:
1683 @code
1684 GetEventHandler()->SafelyProcessEvent(event);
1685 @endcode
1686
1687 @see ProcessWindowEvent()
1688 */
1689 bool HandleWindowEvent(wxEvent& event) const;
1690
1691 /**
1692 Convenient wrapper for ProcessEvent().
1693
1694 This is the same as writing @code GetEventHandler()->ProcessEvent(event);
1695 @endcode but more convenient. Notice that ProcessEvent() itself can't
1696 be called for wxWindow objects as it ignores the event handlers
1697 associated with the window, use this function instead.
1698 */
1699 bool ProcessWindowEvent(wxEvent& event);
1700
1701 /**
1702 Removes and returns the top-most event handler on the event handler stack.
1703
1704 E.g. in the case of:
1705 @image html overview_eventhandling_winstack.png
1706 when calling @c W->PopEventHandler(), the event handler @c A will be
1707 removed and @c B will be the first handler of the stack.
1708
1709 Note that it's an error to call this function when no event handlers
1710 were pushed on this window (i.e. when the window itself is its only
1711 event handler).
1712
1713 @param deleteHandler
1714 If this is @true, the handler will be deleted after it is removed
1715 (and the returned value will be @NULL).
1716
1717 @see @ref overview_events_processing
1718 */
1719 wxEvtHandler* PopEventHandler(bool deleteHandler = false);
1720
1721 /**
1722 Pushes this event handler onto the event stack for the window.
1723
1724 An event handler is an object that is capable of processing the events sent
1725 to a window. By default, the window is its own event handler, but an application
1726 may wish to substitute another, for example to allow central implementation
1727 of event-handling for a variety of different window classes.
1728
1729 wxWindow::PushEventHandler allows an application to set up a @e stack
1730 of event handlers, where an event not handled by one event handler is
1731 handed to the next one in the chain.
1732
1733 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
1734 @c W and you call:
1735 @code
1736 W->PushEventHandler(A);
1737 W->PushEventHandler(B);
1738 @endcode
1739 you will end up with the following situation:
1740 @image html overview_eventhandling_winstack.png
1741
1742 Note that you can use wxWindow::PopEventHandler to remove the event handler.
1743
1744 @param handler
1745 Specifies the handler to be pushed.
1746 It must not be part of a wxEvtHandler chain; an assert will fail
1747 if it's not unlinked (see wxEvtHandler::IsUnlinked).
1748
1749 @see @ref overview_events_processing
1750 */
1751 void PushEventHandler(wxEvtHandler* handler);
1752
1753 /**
1754 Find the given @a handler in the windows event handler stack and
1755 removes (but does not delete) it from the stack.
1756
1757 See wxEvtHandler::Unlink() for more info.
1758
1759 @param handler
1760 The event handler to remove, must be non-@NULL and
1761 must be present in this windows event handlers stack.
1762
1763 @return Returns @true if it was found and @false otherwise (this also
1764 results in an assert failure so this function should
1765 only be called when the handler is supposed to be there).
1766
1767 @see PushEventHandler(), PopEventHandler()
1768 */
1769 bool RemoveEventHandler(wxEvtHandler* handler);
1770
1771 /**
1772 Sets the event handler for this window.
1773
1774 Note that if you use this function you may want to use as the "next" handler
1775 of @a handler the window itself; in this way when @a handler doesn't process
1776 an event, the window itself will have a chance to do it.
1777
1778 @param handler
1779 Specifies the handler to be set. Cannot be @NULL.
1780
1781 @see @ref overview_events_processing
1782 */
1783 void SetEventHandler(wxEvtHandler* handler);
1784
1785 /**
1786 wxWindows cannot be used to form event handler chains; this function
1787 thus will assert when called.
1788
1789 Note that instead you can use PushEventHandler() or SetEventHandler() to
1790 implement a stack of event handlers to override wxWindow's own
1791 event handling mechanism.
1792 */
1793 virtual void SetNextHandler(wxEvtHandler* handler);
1794
1795 /**
1796 wxWindows cannot be used to form event handler chains; this function
1797 thus will assert when called.
1798
1799 Note that instead you can use PushEventHandler() or SetEventHandler() to
1800 implement a stack of event handlers to override wxWindow's own
1801 event handling mechanism.
1802 */
1803 virtual void SetPreviousHandler(wxEvtHandler* handler);
1804
1805 //@}
1806
1807
1808
1809 /**
1810 @name Window styles functions
1811 */
1812 //@{
1813
1814 /**
1815 Returns the extra style bits for the window.
1816 */
1817 long GetExtraStyle() const;
1818
1819 /**
1820 Gets the window style that was passed to the constructor or Create()
1821 method. GetWindowStyle() is another name for the same function.
1822 */
1823 virtual long GetWindowStyleFlag() const;
1824
1825 /**
1826 See GetWindowStyleFlag() for more info.
1827 */
1828 long GetWindowStyle() const;
1829
1830 /**
1831 Returns @true if the window has the given @a exFlag bit set in its
1832 extra styles.
1833
1834 @see SetExtraStyle()
1835 */
1836 bool HasExtraStyle(int exFlag) const;
1837
1838 /**
1839 Returns @true if the window has the given @a flag bit set.
1840 */
1841 bool HasFlag(int flag) const;
1842
1843 /**
1844 Sets the extra style bits for the window.
1845 The currently defined extra style bits are reported in the class
1846 description.
1847 */
1848 virtual void SetExtraStyle(long exStyle);
1849
1850 /**
1851 Sets the style of the window. Please note that some styles cannot be changed
1852 after the window creation and that Refresh() might need to be be called
1853 after changing the others for the change to take place immediately.
1854
1855 See @ref overview_windowstyles "Window styles" for more information about flags.
1856
1857 @see GetWindowStyleFlag()
1858 */
1859 virtual void SetWindowStyleFlag(long style);
1860
1861 /**
1862 See SetWindowStyleFlag() for more info.
1863 */
1864 void SetWindowStyle(long style);
1865
1866 /**
1867 Turns the given @a flag on if it's currently turned off and vice versa.
1868 This function cannot be used if the value of the flag is 0 (which is often
1869 the case for default flags).
1870
1871 Also, please notice that not all styles can be changed after the control
1872 creation.
1873
1874 @return Returns @true if the style was turned on by this function, @false
1875 if it was switched off.
1876
1877 @see SetWindowStyleFlag(), HasFlag()
1878 */
1879 bool ToggleWindowStyle(int flag);
1880
1881 //@}
1882
1883
1884 /**
1885 @name Tab order functions
1886 */
1887 //@{
1888
1889 /**
1890 Moves this window in the tab navigation order after the specified @e win.
1891 This means that when the user presses @c TAB key on that other window,
1892 the focus switches to this window.
1893
1894 Default tab order is the same as creation order, this function and
1895 MoveBeforeInTabOrder() allow to change
1896 it after creating all the windows.
1897
1898 @param win
1899 A sibling of this window which should precede it in tab order,
1900 must not be @NULL
1901 */
1902 void MoveAfterInTabOrder(wxWindow* win);
1903
1904 /**
1905 Same as MoveAfterInTabOrder() except that it inserts this window just
1906 before @a win instead of putting it right after it.
1907 */
1908 void MoveBeforeInTabOrder(wxWindow* win);
1909
1910 /**
1911 Performs a keyboard navigation action starting from this window.
1912 This method is equivalent to calling NavigateIn() method on the
1913 parent window.
1914
1915 @param flags
1916 A combination of wxNavigationKeyEvent::IsForward and
1917 wxNavigationKeyEvent::WinChange.
1918
1919 @return Returns @true if the focus was moved to another window or @false
1920 if nothing changed.
1921
1922 @remarks You may wish to call this from a text control custom keypress
1923 handler to do the default navigation behaviour for the
1924 tab key, since the standard default behaviour for a
1925 multiline text control with the wxTE_PROCESS_TAB style
1926 is to insert a tab and not navigate to the next
1927 control. See also wxNavigationKeyEvent and
1928 HandleAsNavigationKey.
1929 */
1930 bool Navigate(int flags = IsForward);
1931
1932 /**
1933 Performs a keyboard navigation action inside this window.
1934 See Navigate() for more information.
1935 */
1936 bool NavigateIn(int flags = IsForward);
1937
1938 //@}
1939
1940
1941
1942 /**
1943 @name Z order functions
1944 */
1945 //@{
1946
1947 /**
1948 Lowers the window to the bottom of the window hierarchy (Z-order).
1949
1950 @remarks
1951 This function only works for wxTopLevelWindow-derived classes.
1952
1953 @see Raise()
1954 */
1955 virtual void Lower();
1956
1957 /**
1958 Raises the window to the top of the window hierarchy (Z-order).
1959
1960 @remarks
1961 This function only works for wxTopLevelWindow-derived classes.
1962
1963 @see Lower()
1964 */
1965 virtual void Raise();
1966
1967 //@}
1968
1969
1970 /**
1971 @name Window status functions
1972 */
1973 //@{
1974
1975
1976 /**
1977 Equivalent to calling wxWindow::Show(@false).
1978 */
1979 bool Hide();
1980
1981 /**
1982 This function hides a window, like Hide(), but using a special visual
1983 effect if possible.
1984
1985 The parameters of this function are the same as for ShowWithEffect(),
1986 please see their description there.
1987
1988 @since 2.9.0
1989 */
1990 virtual bool HideWithEffect(wxShowEffect effect,
1991 unsigned int timeout = 0);
1992 /**
1993 Returns @true if the window is enabled, i.e. if it accepts user input,
1994 @false otherwise.
1995
1996 Notice that this method can return @false even if this window itself hadn't
1997 been explicitly disabled when one of its parent windows is disabled.
1998 To get the intrinsic status of this window, use IsThisEnabled()
1999
2000 @see Enable()
2001 */
2002 bool IsEnabled() const;
2003
2004 /**
2005 Returns @true if the given point or rectangle area has been exposed since the
2006 last repaint. Call this in an paint event handler to optimize redrawing by
2007 only redrawing those areas, which have been exposed.
2008 */
2009 bool IsExposed(int x, int y) const;
2010
2011 /**
2012 @overload
2013 */
2014 bool IsExposed(wxPoint& pt) const;
2015
2016 /**
2017 @overload
2018 */
2019 bool IsExposed(int x, int y, int w, int h) const;
2020
2021 /**
2022 @overload
2023 */
2024 bool IsExposed(wxRect& rect) const;
2025 /**
2026 Returns @true if the window is shown, @false if it has been hidden.
2027
2028 @see IsShownOnScreen()
2029 */
2030 virtual bool IsShown() const;
2031
2032 /**
2033 Returns @true if the window is physically visible on the screen, i.e. it
2034 is shown and all its parents up to the toplevel window are shown as well.
2035
2036 @see IsShown()
2037 */
2038 virtual bool IsShownOnScreen() const;
2039
2040 /**
2041 Disables the window. Same as @ref Enable() Enable(@false).
2042
2043 @return Returns @true if the window has been disabled, @false if it had
2044 been already disabled before the call to this function.
2045 */
2046 bool Disable();
2047
2048 /**
2049 Enable or disable the window for user input. Note that when a parent window is
2050 disabled, all of its children are disabled as well and they are reenabled again
2051 when the parent is.
2052
2053 @param enable
2054 If @true, enables the window for input. If @false, disables the window.
2055
2056 @return Returns @true if the window has been enabled or disabled, @false
2057 if nothing was done, i.e. if the window had already
2058 been in the specified state.
2059
2060 @see IsEnabled(), Disable(), wxRadioBox::Enable
2061 */
2062 virtual bool Enable(bool enable = true);
2063
2064 /**
2065 Shows or hides the window. You may need to call Raise()
2066 for a top level window if you want to bring it to top, although this is not
2067 needed if Show() is called immediately after the frame creation.
2068
2069 @param show
2070 If @true displays the window. Otherwise, hides it.
2071
2072 @return @true if the window has been shown or hidden or @false if nothing
2073 was done because it already was in the requested state.
2074
2075 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2076 */
2077 virtual bool Show(bool show = true);
2078
2079 /**
2080 This function shows a window, like Show(), but using a special visual
2081 effect if possible.
2082
2083 @param effect
2084 The effect to use.
2085
2086 @param timeout
2087 The @a timeout parameter specifies the time of the animation, in
2088 milliseconds. If the default value of 0 is used, the default
2089 animation time for the current platform is used.
2090
2091 @note Currently this function is only implemented in wxMSW and does the
2092 same thing as Show() in the other ports.
2093
2094 @since 2.9.0
2095
2096 @see HideWithEffect()
2097 */
2098 virtual bool ShowWithEffect(wxShowEffect effect,
2099 unsigned int timeout = 0);
2100
2101 //@}
2102
2103
2104 /**
2105 @name Context-sensitive help functions
2106 */
2107 //@{
2108
2109 /**
2110 Gets the help text to be used as context-sensitive help for this window.
2111 Note that the text is actually stored by the current wxHelpProvider
2112 implementation, and not in the window object itself.
2113
2114 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2115 */
2116 wxString GetHelpText() const;
2117
2118 /**
2119 Sets the help text to be used as context-sensitive help for this window.
2120 Note that the text is actually stored by the current wxHelpProvider
2121 implementation, and not in the window object itself.
2122
2123 @see GetHelpText(), wxHelpProvider::AddHelp()
2124 */
2125 void SetHelpText(const wxString& helpText);
2126
2127 /**
2128 Gets the help text to be used as context-sensitive help for this window.
2129 This method should be overridden if the help message depends on the position
2130 inside the window, otherwise GetHelpText() can be used.
2131
2132 @param point
2133 Coordinates of the mouse at the moment of help event emission.
2134 @param origin
2135 Help event origin, see also wxHelpEvent::GetOrigin.
2136 */
2137 virtual wxString GetHelpTextAtPoint(const wxPoint& point,
2138 wxHelpEvent::Origin origin) const;
2139
2140 /**
2141 Get the associated tooltip or @NULL if none.
2142 */
2143 wxToolTip* GetToolTip() const;
2144
2145 /**
2146 Attach a tooltip to the window.
2147
2148 wxToolTip pointer can be @NULL in the overload taking the pointer,
2149 meaning to unset any existing tooltips, however UnsetToolTip() provides
2150 a more readable alternative to this operation.
2151
2152 Notice that these methods are always available, even if wxWidgets was
2153 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2154 case.
2155
2156 @see GetToolTip(), wxToolTip
2157 */
2158 void SetToolTip(const wxString& tip);
2159
2160 /**
2161 @overload
2162 */
2163 void SetToolTip(wxToolTip* tip);
2164
2165 /**
2166 Unset any existing tooltip.
2167
2168 @since 2.9.0
2169
2170 @see SetToolTip()
2171 */
2172 void UnsetToolTip();
2173
2174 //@}
2175
2176
2177 /**
2178 @name Popup/context menu functions
2179 */
2180 //@{
2181
2182 /**
2183 This function shows a popup menu at the given position in this window and
2184 returns the selected id.
2185
2186 It can be more convenient than the general purpose PopupMenu() function
2187 for simple menus proposing a choice in a list of strings to the user.
2188
2189 Notice that to avoid unexpected conflicts between the (usually
2190 consecutive range of) ids used by the menu passed to this function and
2191 the existing EVT_UPDATE_UI() handlers, this function temporarily
2192 disables UI updates for the window, so you need to manually disable
2193 (or toggle or ...) any items which should be disabled in the menu
2194 before showing it.
2195
2196 The parameter @a menu is the menu to show.
2197 The parameter @a pos (or the parameters @a x and @a y) is the
2198 position at which to show the menu in client coordinates.
2199
2200 @return
2201 The selected menu item id or @c wxID_NONE if none selected or an
2202 error occurred.
2203
2204 @since 2.9.0
2205 */
2206 int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
2207
2208 /**
2209 @overload
2210 */
2211 int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
2212
2213 /**
2214 Pops up the given menu at the specified coordinates, relative to this
2215 window, and returns control when the user has dismissed the menu.
2216
2217 If a menu item is selected, the corresponding menu event is generated and will be
2218 processed as usually. If the coordinates are not specified, current mouse
2219 cursor position is used.
2220
2221 @a menu is the menu to pop up.
2222
2223 The position where the menu will appear can be specified either as a
2224 wxPoint @a pos or by two integers (@a x and @a y).
2225
2226 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2227 ensure that the menu items are in the correct state.
2228 The menu does not get deleted by the window.
2229 It is recommended to not explicitly specify coordinates when
2230 calling PopupMenu in response to mouse click, because some of
2231 the ports (namely, wxGTK) can do a better job of positioning
2232 the menu in that case.
2233
2234 @see wxMenu
2235 */
2236 bool PopupMenu(wxMenu* menu,
2237 const wxPoint& pos = wxDefaultPosition);
2238
2239 /**
2240 @overload
2241 */
2242 bool PopupMenu(wxMenu* menu, int x, int y);
2243
2244 //@}
2245
2246
2247 /**
2248 Validator functions
2249 */
2250 //@{
2251
2252 /**
2253 Returns a pointer to the current validator for the window, or @NULL if
2254 there is none.
2255 */
2256 virtual wxValidator* GetValidator();
2257
2258 /**
2259 Deletes the current validator (if any) and sets the window validator, having
2260 called wxValidator::Clone to create a new validator of this type.
2261 */
2262 virtual void SetValidator(const wxValidator& validator);
2263
2264 /**
2265 Transfers values from child controls to data areas specified by their
2266 validators. Returns @false if a transfer failed.
2267
2268 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2269 the method will also call TransferDataFromWindow() of all child windows.
2270
2271 @see TransferDataToWindow(), wxValidator, Validate()
2272 */
2273 virtual bool TransferDataFromWindow();
2274
2275 /**
2276 Transfers values to child controls from data areas specified by their
2277 validators.
2278
2279 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2280 the method will also call TransferDataToWindow() of all child windows.
2281
2282 @return Returns @false if a transfer failed.
2283
2284 @see TransferDataFromWindow(), wxValidator, Validate()
2285 */
2286 virtual bool TransferDataToWindow();
2287
2288 /**
2289 Validates the current values of the child controls using their validators.
2290 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2291 the method will also call Validate() of all child windows.
2292
2293 @return Returns @false if any of the validations failed.
2294
2295 @see TransferDataFromWindow(), TransferDataToWindow(),
2296 wxValidator
2297 */
2298 virtual bool Validate();
2299
2300 //@}
2301
2302
2303 /**
2304 @name wxWindow properties functions
2305 */
2306 //@{
2307
2308 /**
2309 Returns the identifier of the window.
2310
2311 @remarks Each window has an integer identifier. If the application
2312 has not provided one (or the default wxID_ANY) an unique
2313 identifier with a negative value will be generated.
2314
2315 @see SetId(), @ref overview_windowids
2316 */
2317 wxWindowID GetId() const;
2318
2319 /**
2320 Generic way of getting a label from any window, for
2321 identification purposes.
2322
2323 @remarks The interpretation of this function differs from class to class.
2324 For frames and dialogs, the value returned is the
2325 title. For buttons or static text controls, it is the
2326 button text. This function can be useful for
2327 meta-programs (such as testing tools or special-needs
2328 access programs) which need to identify windows by name.
2329 */
2330 virtual wxString GetLabel() const;
2331
2332 /**
2333 Returns the layout direction for this window,
2334 Note that @c wxLayout_Default is returned if layout direction is not supported.
2335 */
2336 virtual wxLayoutDirection GetLayoutDirection() const;
2337
2338 /**
2339 Returns the window's name.
2340
2341 @remarks This name is not guaranteed to be unique; it is up to the
2342 programmer to supply an appropriate name in the window
2343 constructor or via SetName().
2344
2345 @see SetName()
2346 */
2347 virtual wxString GetName() const;
2348
2349 /**
2350 Returns the value previously passed to SetWindowVariant().
2351 */
2352 wxWindowVariant GetWindowVariant() const;
2353
2354 /**
2355 Sets the identifier of the window.
2356
2357 @remarks Each window has an integer identifier. If the application has
2358 not provided one, an identifier will be generated.
2359 Normally, the identifier should be provided on creation
2360 and should not be modified subsequently.
2361
2362 @see GetId(), @ref overview_windowids
2363 */
2364 void SetId(wxWindowID winid);
2365
2366 /**
2367 Sets the window's label.
2368
2369 @param label
2370 The window label.
2371
2372 @see GetLabel()
2373 */
2374 virtual void SetLabel(const wxString& label);
2375
2376 /**
2377 Sets the layout direction for this window.
2378 */
2379 virtual void SetLayoutDirection(wxLayoutDirection dir);
2380
2381 /**
2382 Sets the window's name.
2383
2384 @param name
2385 A name to set for the window.
2386
2387 @see GetName()
2388 */
2389 virtual void SetName(const wxString& name);
2390
2391 /**
2392 This function can be called under all platforms but only does anything under
2393 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2394 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2395
2396 By default the controls use the normal size, of course, but this function can
2397 be used to change this.
2398 */
2399 void SetWindowVariant(wxWindowVariant variant);
2400
2401 /**
2402 Gets the accelerator table for this window. See wxAcceleratorTable.
2403 */
2404 wxAcceleratorTable* GetAcceleratorTable();
2405
2406 /**
2407 Returns the accessible object for this window, if any.
2408 See also wxAccessible.
2409 */
2410 wxAccessible* GetAccessible();
2411
2412 /**
2413 Sets the accelerator table for this window. See wxAcceleratorTable.
2414 */
2415 virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
2416
2417 /**
2418 Sets the accessible for this window. Any existing accessible for this window
2419 will be deleted first, if not identical to @e accessible.
2420 See also wxAccessible.
2421 */
2422 void SetAccessible(wxAccessible* accessible);
2423
2424 //@}
2425
2426
2427 /**
2428 @name Window deletion functions
2429 */
2430 //@{
2431
2432 /**
2433 This function simply generates a wxCloseEvent whose handler usually tries
2434 to close the window. It doesn't close the window itself, however.
2435
2436 @param force
2437 @false if the window's close handler should be able to veto the destruction
2438 of this window, @true if it cannot.
2439
2440 @remarks Close calls the close handler for the window, providing an
2441 opportunity for the window to choose whether to destroy
2442 the window. Usually it is only used with the top level
2443 windows (wxFrame and wxDialog classes) as the others
2444 are not supposed to have any special OnClose() logic.
2445 The close handler should check whether the window is being deleted
2446 forcibly, using wxCloseEvent::CanVeto, in which case it should
2447 destroy the window using wxWindow::Destroy.
2448 Note that calling Close does not guarantee that the window will
2449 be destroyed; but it provides a way to simulate a manual close
2450 of a window, which may or may not be implemented by destroying
2451 the window. The default implementation of wxDialog::OnCloseWindow
2452 does not necessarily delete the dialog, since it will simply
2453 simulate an wxID_CANCEL event which is handled by the appropriate
2454 button event handler and may do anything at all.
2455 To guarantee that the window will be destroyed, call
2456 wxWindow::Destroy instead
2457
2458 @see @ref overview_windowdeletion "Window Deletion Overview",
2459 Destroy(), wxCloseEvent
2460 */
2461 bool Close(bool force = false);
2462
2463 /**
2464 Destroys the window safely. Use this function instead of the delete operator,
2465 since different window classes can be destroyed differently. Frames and dialogs
2466 are not destroyed immediately when this function is called -- they are added
2467 to a list of windows to be deleted on idle time, when all the window's events
2468 have been processed. This prevents problems with events being sent to
2469 non-existent windows.
2470
2471 @return @true if the window has either been successfully deleted, or it
2472 has been added to the list of windows pending real deletion.
2473 */
2474 virtual bool Destroy();
2475
2476 /**
2477 Returns true if this window is in process of being destroyed.
2478
2479 The top level windows are not deleted immediately but are rather
2480 scheduled for later destruction to give them time to process any
2481 pending messages, see Destroy() description.
2482
2483 This function returns @true if this window, or one of its parent
2484 windows, is scheduled for destruction and can be useful to avoid
2485 manipulating it as it's usually useless to do something with a window
2486 which is on the point of disappearing anyhow.
2487 */
2488 bool IsBeingDeleted() const;
2489
2490 //@}
2491
2492
2493
2494 /**
2495 @name Drag and drop functions
2496 */
2497 //@{
2498
2499 /**
2500 Returns the associated drop target, which may be @NULL.
2501
2502 @see SetDropTarget(), @ref overview_dnd
2503 */
2504 virtual wxDropTarget* GetDropTarget() const;
2505
2506 /**
2507 Associates a drop target with this window.
2508 If the window already has a drop target, it is deleted.
2509
2510 @see GetDropTarget(), @ref overview_dnd
2511 */
2512 virtual void SetDropTarget(wxDropTarget* target);
2513
2514 /**
2515 Enables or disables eligibility for drop file events (OnDropFiles).
2516
2517 @param accept
2518 If @true, the window is eligible for drop file events.
2519 If @false, the window will not accept drop file events.
2520
2521 @remarks Windows only until version 2.8.9, available on all platforms
2522 since 2.8.10. Cannot be used together with SetDropTarget() on
2523 non-Windows platforms.
2524
2525 @see SetDropTarget()
2526 */
2527 virtual void DragAcceptFiles(bool accept);
2528
2529 //@}
2530
2531
2532 /**
2533 @name Constraints, sizers and window layouting functions
2534 */
2535 //@{
2536
2537 /**
2538 Return the sizer that this window is a member of, if any, otherwise @NULL.
2539 */
2540 wxSizer* GetContainingSizer() const;
2541
2542 /**
2543 Return the sizer associated with the window by a previous call to
2544 SetSizer() or @NULL.
2545 */
2546 wxSizer* GetSizer() const;
2547
2548 /**
2549 Sets the window to have the given layout sizer.
2550 The window will then own the object, and will take care of its deletion.
2551 If an existing layout constraints object is already owned by the
2552 window, it will be deleted if the deleteOld parameter is @true.
2553
2554 Note that this function will also call SetAutoLayout() implicitly with @true
2555 parameter if the @a sizer is non-@NULL and @false otherwise.
2556
2557 @param sizer
2558 The sizer to set. Pass @NULL to disassociate and conditionally delete
2559 the window's sizer. See below.
2560 @param deleteOld
2561 If @true (the default), this will delete any pre-existing sizer.
2562 Pass @false if you wish to handle deleting the old sizer yourself.
2563
2564 @remarks SetSizer enables and disables Layout automatically.
2565 */
2566 void SetSizer(wxSizer* sizer, bool deleteOld = true);
2567
2568 /**
2569 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2570 window size to the size needed to accommodate all sizer elements and sets the
2571 size hints which, if this window is a top level one, prevent the user from
2572 resizing it to be less than this minimial size.
2573 */
2574 void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
2575
2576 /**
2577 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2578 */
2579 wxLayoutConstraints* GetConstraints() const;
2580
2581 /**
2582 Sets the window to have the given layout constraints. The window
2583 will then own the object, and will take care of its deletion.
2584 If an existing layout constraints object is already owned by the
2585 window, it will be deleted.
2586
2587 @param constraints
2588 The constraints to set. Pass @NULL to disassociate and delete the window's
2589 constraints.
2590
2591 @remarks You must call SetAutoLayout() to tell a window to use
2592 the constraints automatically in OnSize; otherwise, you
2593 must override OnSize and call Layout() explicitly. When
2594 setting both a wxLayoutConstraints and a wxSizer, only
2595 the sizer will have effect.
2596 */
2597 void SetConstraints(wxLayoutConstraints* constraints);
2598
2599
2600 /**
2601 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2602 for this window.
2603
2604 This function does not get called automatically when the window is resized
2605 because lots of windows deriving from wxWindow does not need this functionality.
2606 If you want to have Layout() called automatically, you should derive
2607 from wxPanel (see wxPanel::Layout).
2608
2609 @see @ref overview_windowsizing
2610 */
2611 virtual bool Layout();
2612
2613 /**
2614 Determines whether the Layout() function will be called automatically
2615 when the window is resized. Please note that this only happens for the
2616 windows usually used to contain children, namely wxPanel and wxTopLevelWindow
2617 (and the classes deriving from them).
2618
2619 This method is called implicitly by SetSizer() but if you use SetConstraints()
2620 you should call it manually or otherwise the window layout won't be correctly
2621 updated when its size changes.
2622
2623 @param autoLayout
2624 Set this to @true if you wish the Layout() function to be
2625 called automatically when the window is resized
2626 (really happens only if you derive from wxPanel or wxTopLevelWindow).
2627
2628 @see SetConstraints()
2629 */
2630 void SetAutoLayout(bool autoLayout);
2631
2632 //@}
2633
2634
2635
2636 /**
2637 @name Mouse functions
2638 */
2639 //@{
2640
2641 /**
2642 Directs all mouse input to this window.
2643 Call ReleaseMouse() to release the capture.
2644
2645 Note that wxWidgets maintains the stack of windows having captured the mouse
2646 and when the mouse is released the capture returns to the window which had had
2647 captured it previously and it is only really released if there were no previous
2648 window. In particular, this means that you must release the mouse as many times
2649 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
2650
2651 Any application which captures the mouse in the beginning of some operation
2652 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
2653 the event. The event handler must not recapture mouse.
2654
2655 @see ReleaseMouse(), wxMouseCaptureLostEvent
2656 */
2657 void CaptureMouse();
2658
2659 /**
2660 Returns the caret() associated with the window.
2661 */
2662 wxCaret* GetCaret() const;
2663
2664 /**
2665 Return the cursor associated with this window.
2666
2667 @see SetCursor()
2668 */
2669 const wxCursor& GetCursor() const;
2670
2671 /**
2672 Returns @true if this window has the current mouse capture.
2673
2674 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
2675 wxMouseCaptureChangedEvent
2676 */
2677 virtual bool HasCapture() const;
2678
2679 /**
2680 Releases mouse input captured with CaptureMouse().
2681
2682 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
2683 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2684 */
2685 void ReleaseMouse();
2686
2687 /**
2688 Sets the caret() associated with the window.
2689 */
2690 void SetCaret(wxCaret* caret);
2691
2692 /**
2693 Sets the window's cursor. Notice that the window cursor also sets it for the
2694 children of the window implicitly.
2695
2696 The @a cursor may be @c wxNullCursor in which case the window cursor will
2697 be reset back to default.
2698
2699 @param cursor
2700 Specifies the cursor that the window should normally display.
2701
2702 @see ::wxSetCursor, wxCursor
2703 */
2704 virtual bool SetCursor(const wxCursor& cursor);
2705
2706 /**
2707 Moves the pointer to the given position on the window.
2708
2709 @note This function is not supported under Mac because Apple Human
2710 Interface Guidelines forbid moving the mouse cursor programmatically.
2711
2712 @param x
2713 The new x position for the cursor.
2714 @param y
2715 The new y position for the cursor.
2716 */
2717 virtual void WarpPointer(int x, int y);
2718
2719 //@}
2720
2721
2722
2723
2724 /**
2725 @name Miscellaneous functions
2726 */
2727 //@{
2728
2729 /**
2730 Does the window-specific updating after processing the update event.
2731 This function is called by UpdateWindowUI() in order to check return
2732 values in the wxUpdateUIEvent and act appropriately.
2733 For example, to allow frame and dialog title updating, wxWidgets
2734 implements this function as follows:
2735
2736 @code
2737 // do the window-specific processing after processing the update event
2738 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
2739 {
2740 if ( event.GetSetEnabled() )
2741 Enable(event.GetEnabled());
2742
2743 if ( event.GetSetText() )
2744 {
2745 if ( event.GetText() != GetTitle() )
2746 SetTitle(event.GetText());
2747 }
2748 }
2749 @endcode
2750 */
2751 virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
2752
2753 /**
2754 Returns the platform-specific handle of the physical window.
2755 Cast it to an appropriate handle, such as @b HWND for Windows,
2756 @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
2757 */
2758 virtual WXWidget GetHandle() const;
2759
2760 /**
2761 This method should be overridden to return @true if this window has
2762 multiple pages. All standard class with multiple pages such as
2763 wxNotebook, wxListbook and wxTreebook already override it to return @true
2764 and user-defined classes with similar behaviour should do it as well to
2765 allow the library to handle such windows appropriately.
2766 */
2767 virtual bool HasMultiplePages() const;
2768
2769 /**
2770 This function is (or should be, in case of custom controls) called during
2771 window creation to intelligently set up the window visual attributes, that is
2772 the font and the foreground and background colours.
2773
2774 By "intelligently" the following is meant: by default, all windows use their
2775 own @ref GetClassDefaultAttributes() default attributes.
2776 However if some of the parents attributes are explicitly (that is, using
2777 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
2778 attribute hadn't been explicitly set for this window itself, then this
2779 window takes the same value as used by the parent.
2780 In addition, if the window overrides ShouldInheritColours() to return @false,
2781 the colours will not be changed no matter what and only the font might.
2782
2783 This rather complicated logic is necessary in order to accommodate the
2784 different usage scenarios. The most common one is when all default attributes
2785 are used and in this case, nothing should be inherited as in modern GUIs
2786 different controls use different fonts (and colours) than their siblings so
2787 they can't inherit the same value from the parent. However it was also deemed
2788 desirable to allow to simply change the attributes of all children at once by
2789 just changing the font or colour of their common parent, hence in this case we
2790 do inherit the parents attributes.
2791 */
2792 virtual void InheritAttributes();
2793
2794 /**
2795 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
2796 to the dialog via validators.
2797 */
2798 virtual void InitDialog();
2799
2800 /**
2801 Returns @true if the window contents is double-buffered by the system, i.e. if
2802 any drawing done on the window is really done on a temporary backing surface
2803 and transferred to the screen all at once later.
2804
2805 @see wxBufferedDC
2806 */
2807 virtual bool IsDoubleBuffered() const;
2808
2809 /**
2810 Returns @true if the window is retained, @false otherwise.
2811
2812 @remarks Retained windows are only available on X platforms.
2813 */
2814 virtual bool IsRetained() const;
2815
2816 /**
2817 Returns @true if this window is intrinsically enabled, @false otherwise,
2818 i.e. if @ref Enable() Enable(@false) had been called. This method is
2819 mostly used for wxWidgets itself, user code should normally use
2820 IsEnabled() instead.
2821 */
2822 bool IsThisEnabled() const;
2823
2824 /**
2825 Returns @true if the given window is a top-level one. Currently all frames and
2826 dialogs are considered to be top-level windows (even if they have a parent
2827 window).
2828 */
2829 virtual bool IsTopLevel() const;
2830
2831 /**
2832 Disables all other windows in the application so that
2833 the user can only interact with this window.
2834
2835 @param modal
2836 If @true, this call disables all other windows in the application so that
2837 the user can only interact with this window. If @false, the effect is
2838 reversed.
2839 */
2840 virtual void MakeModal(bool modal = true);
2841
2842 /**
2843 This virtual function is normally only used internally, but
2844 sometimes an application may need it to implement functionality
2845 that should not be disabled by an application defining an OnIdle
2846 handler in a derived class.
2847
2848 This function may be used to do delayed painting, for example,
2849 and most implementations call UpdateWindowUI()
2850 in order to send update events to the window in idle time.
2851 */
2852 virtual void OnInternalIdle();
2853
2854 /**
2855 Registers a system wide hotkey. Every time the user presses the hotkey
2856 registered here, this window will receive a hotkey event.
2857
2858 It will receive the event even if the application is in the background
2859 and does not have the input focus because the user is working with some
2860 other application.
2861
2862 @param hotkeyId
2863 Numeric identifier of the hotkey. For applications this must be between 0
2864 and 0xBFFF. If this function is called from a shared DLL, it must be a
2865 system wide unique identifier between 0xC000 and 0xFFFF.
2866 This is a MSW specific detail.
2867 @param modifiers
2868 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
2869 or wxMOD_WIN specifying the modifier keys that have to be pressed along
2870 with the key.
2871 @param virtualKeyCode
2872 The virtual key code of the hotkey.
2873
2874 @return @true if the hotkey was registered successfully. @false if some
2875 other application already registered a hotkey with this
2876 modifier/virtualKeyCode combination.
2877
2878 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
2879 event. This function is currently only implemented
2880 under Windows. It is used in the Windows CE port for
2881 detecting hardware button presses.
2882
2883 @see UnregisterHotKey()
2884 */
2885 virtual bool RegisterHotKey(int hotkeyId, int modifiers,
2886 int virtualKeyCode);
2887
2888 /**
2889 Unregisters a system wide hotkey.
2890
2891 @param hotkeyId
2892 Numeric identifier of the hotkey. Must be the same id that was passed to
2893 RegisterHotKey().
2894
2895 @return @true if the hotkey was unregistered successfully, @false if the
2896 id was invalid.
2897
2898 @remarks This function is currently only implemented under MSW.
2899
2900 @see RegisterHotKey()
2901 */
2902 virtual bool UnregisterHotKey(int hotkeyId);
2903
2904 /**
2905 This function sends one or more wxUpdateUIEvent to the window.
2906 The particular implementation depends on the window; for example a
2907 wxToolBar will send an update UI event for each toolbar button,
2908 and a wxFrame will send an update UI event for each menubar menu item.
2909
2910 You can call this function from your application to ensure that your
2911 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
2912 are concerned). This may be necessary if you have called
2913 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
2914 the overhead that wxWidgets incurs by sending update UI events in idle time.
2915 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
2916
2917 If you are calling this function from an OnInternalIdle or OnIdle
2918 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
2919 this tells the window to only update the UI elements that need
2920 to be updated in idle time. Some windows update their elements
2921 only when necessary, for example when a menu is about to be shown.
2922 The following is an example of how to call UpdateWindowUI from
2923 an idle function.
2924
2925 @code
2926 void MyWindow::OnInternalIdle()
2927 {
2928 if (wxUpdateUIEvent::CanUpdate(this))
2929 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
2930 }
2931 @endcode
2932
2933 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
2934 */
2935 virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE);
2936
2937 //@}
2938
2939
2940 // NOTE: static functions must have their own group or Doxygen will screw
2941 // up the ordering of the member groups
2942
2943 /**
2944 @name Miscellaneous static functions
2945 */
2946 //@{
2947
2948 /**
2949 Returns the default font and colours which are used by the control.
2950
2951 This is useful if you want to use the same font or colour in your own control
2952 as in a standard control -- which is a much better idea than hard coding specific
2953 colours or fonts which might look completely out of place on the users
2954 system, especially if it uses themes.
2955
2956 The @a variant parameter is only relevant under Mac currently and is
2957 ignore under other platforms. Under Mac, it will change the size of the
2958 returned font. See SetWindowVariant() for more about this.
2959
2960 This static method is "overridden" in many derived classes and so calling,
2961 for example, wxButton::GetClassDefaultAttributes() will typically
2962 return the values appropriate for a button which will be normally different
2963 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
2964
2965 The @c wxVisualAttributes structure has at least the fields
2966 @c font, @c colFg and @c colBg. All of them may be invalid
2967 if it was not possible to determine the default control appearance or,
2968 especially for the background colour, if the field doesn't make sense as is
2969 the case for @c colBg for the controls with themed background.
2970
2971 @see InheritAttributes()
2972 */
2973 static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
2974
2975 /**
2976 Finds the window or control which currently has the keyboard focus.
2977
2978 @remarks Note that this is a static function, so it can be called without
2979 needing a wxWindow pointer.
2980
2981 @see SetFocus(), HasFocus()
2982 */
2983 static wxWindow* FindFocus();
2984
2985 /**
2986 Find the first window with the given @e id.
2987
2988 If @a parent is @NULL, the search will start from all top-level frames
2989 and dialog boxes; if non-@NULL, the search will be limited to the given
2990 window hierarchy.
2991 The search is recursive in both cases.
2992
2993 @see FindWindow()
2994 */
2995 static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
2996
2997 /**
2998 Find a window by its label.
2999
3000 Depending on the type of window, the label may be a window title
3001 or panel item label. If @a parent is @NULL, the search will start from all
3002 top-level frames and dialog boxes; if non-@NULL, the search will be
3003 limited to the given window hierarchy.
3004 The search is recursive in both cases.
3005
3006 @see FindWindow()
3007 */
3008 static wxWindow* FindWindowByLabel(const wxString& label,
3009 const wxWindow* parent = 0);
3010
3011 /**
3012 Find a window by its name (as given in a window constructor or Create()
3013 function call).
3014
3015 If @a parent is @NULL, the search will start from all top-level frames
3016 and dialog boxes; if non-@NULL, the search will be limited to the given
3017 window hierarchy.
3018
3019 The search is recursive in both cases. If no window with such name is found,
3020 FindWindowByLabel() is called.
3021
3022 @see FindWindow()
3023 */
3024 static wxWindow* FindWindowByName(const wxString& name,
3025 const wxWindow* parent = 0);
3026
3027 /**
3028 Returns the currently captured window.
3029
3030 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
3031 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3032 */
3033 static wxWindow* GetCapture();
3034
3035 /**
3036 Create a new ID or range of IDs that are not currently in use.
3037 The IDs will be reserved until assigned to a wxWindow ID
3038 or unreserved with UnreserveControlId().
3039
3040 See @ref overview_windowids for more information.
3041
3042 @param count
3043 The number of sequential IDs to reserve.
3044
3045 @return Returns the ID or the first ID of the range, or wxID_NONE if the
3046 specified number of identifiers couldn't be allocated.
3047
3048 @see UnreserveControlId(), wxIdManager,
3049 @ref overview_windowids
3050 */
3051 static wxWindowID NewControlId(int count = 1);
3052
3053 /**
3054 Unreserve an ID or range of IDs that was reserved by NewControlId().
3055 See @ref overview_windowids for more information.
3056
3057 @param id
3058 The starting ID of the range of IDs to unreserve.
3059 @param count
3060 The number of sequential IDs to unreserve.
3061
3062 @see NewControlId(), wxIdManager, @ref overview_windowids
3063 */
3064 static void UnreserveControlId(wxWindowID id, int count = 1);
3065
3066 //@}
3067
3068
3069
3070 protected:
3071
3072 /**
3073 Gets the size which best suits the window: for a control, it would be
3074 the minimal size which doesn't truncate the control, for a panel - the
3075 same size as it would have after a call to Fit().
3076
3077 The default implementation of this function is designed for use in container
3078 windows, such as wxPanel, and works something like this:
3079 -# If the window has a sizer then it is used to calculate the best size.
3080 -# Otherwise if the window has layout constraints then those are used to
3081 calculate the best size.
3082 -# Otherwise if the window has children then the best size is set to be large
3083 enough to show all the children.
3084 -# Otherwise if there are no children then the window's minimal size will be
3085 used as its best size.
3086 -# Otherwise if there is no minimal size set, then the current size is used
3087 for the best size.
3088
3089 @see @ref overview_windowsizing
3090 */
3091 virtual wxSize DoGetBestSize() const;
3092
3093
3094 /**
3095 Sets the initial window size if none is given (i.e. at least one of the
3096 components of the size passed to ctor/Create() is wxDefaultCoord).
3097 @deprecated @todo provide deprecation description
3098 */
3099 virtual void SetInitialBestSize(const wxSize& size);
3100
3101 /**
3102 Generate wxWindowDestroyEvent for this window.
3103
3104 This is called by the window itself when it is being destroyed and
3105 usually there is no need to call it but see wxWindowDestroyEvent for
3106 explanations of when you might want to do it.
3107 */
3108 void SendDestroyEvent();
3109
3110 /**
3111 This function is public in wxEvtHandler but protected in wxWindow
3112 because for wxWindows you should always call ProcessEvent() on the
3113 pointer returned by GetEventHandler() and not on the wxWindow object
3114 itself.
3115
3116 For convenience, a ProcessWindowEvent() method is provided as a synonym
3117 for @code GetEventHandler()->ProcessEvent() @endcode.
3118
3119 Note that it's still possible to call these functions directly on the
3120 wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
3121 create subtle bugs when windows with event handlers pushed on them are
3122 involved.
3123
3124 This holds also for all other wxEvtHandler functions.
3125 */
3126 virtual bool ProcessEvent(wxEvent& event);
3127
3128 //@{
3129 /**
3130 See ProcessEvent() for more info about why you shouldn't use this function
3131 and the reason for making this function protected in wxWindow.
3132 */
3133 bool SafelyProcessEvent(wxEvent& event);
3134 virtual void QueueEvent(wxEvent *event);
3135 virtual void AddPendingEvent(const wxEvent& event);
3136 void ProcessPendingEvents();
3137 bool ProcessThreadEvent(const wxEvent& event);
3138 //@}
3139 };
3140
3141
3142
3143 // ============================================================================
3144 // Global functions/macros
3145 // ============================================================================
3146
3147 /** @addtogroup group_funcmacro_misc */
3148 //@{
3149
3150 /**
3151 Find the deepest window at the mouse pointer position, returning the window
3152 and current pointer position in screen coordinates.
3153
3154 @header{wx/window.h}
3155 */
3156 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
3157
3158 /**
3159 Gets the currently active window (implemented for MSW and GTK only
3160 currently, always returns @NULL in the other ports).
3161
3162 @header{wx/window.h}
3163 */
3164 wxWindow* wxGetActiveWindow();
3165
3166 /**
3167 Returns the first top level parent of the given window, or in other words,
3168 the frame or dialog containing it, or @NULL.
3169
3170 @header{wx/window.h}
3171 */
3172 wxWindow* wxGetTopLevelParent(wxWindow* window);
3173
3174 //@}
3175