1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
15 /// Roll window to the left
16 wxSHOW_EFFECT_ROLL_TO_LEFT
,
18 /// Roll window to the right
19 wxSHOW_EFFECT_ROLL_TO_RIGHT
,
21 /// Roll window to the top
22 wxSHOW_EFFECT_ROLL_TO_TOP
,
24 /// Roll window to the bottom
25 wxSHOW_EFFECT_ROLL_TO_BOTTOM
,
27 /// Slide window to the left
28 wxSHOW_EFFECT_SLIDE_TO_LEFT
,
30 /// Slide window to the right
31 wxSHOW_EFFECT_SLIDE_TO_RIGHT
,
33 /// Slide window to the top
34 wxSHOW_EFFECT_SLIDE_TO_TOP
,
36 /// Slide window to the bottom
37 wxSHOW_EFFECT_SLIDE_TO_BOTTOM
,
39 /// Fade in or out effect
42 /// Expanding or collapsing effect
47 Different window variants, on platforms like eg mac uses different
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)
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.
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.
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.
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
92 @style{wxBORDER_RAISED}
93 Displays a raised border. wxRAISED_BORDER is the old name for this
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
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.
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.
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.
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.
185 @beginEventEmissionTable
186 @event{EVT_ACTIVATE(id, func)}
187 Process a @c wxEVT_ACTIVATE event. See wxActivateEvent.
188 @event{EVT_CHILD_FOCUS(func)}
189 Process a @c wxEVT_CHILD_FOCUS event. See wxChildFocusEvent.
190 @event{EVT_CONTEXT_MENU(func)}
191 A right click (or other context menu command depending on platform) has been detected.
192 See wxContextMenuEvent.
193 @event{EVT_HELP(id, func)}
194 Process a @c wxEVT_HELP event. See wxHelpEvent.
195 @event{EVT_HELP_RANGE(id1, id2, func)}
196 Process a @c wxEVT_HELP event for a range of ids. See wxHelpEvent.
197 @event{EVT_DROP_FILES(func)}
198 Process a @c wxEVT_DROP_FILES event. See wxDropFilesEvent.
199 @event{EVT_ERASE_BACKGROUND(func)}
200 Process a @c wxEVT_ERASE_BACKGROUND event. See wxEraseEvent.
201 @event{EVT_SET_FOCUS(func)}
202 Process a @c wxEVT_SET_FOCUS event. See wxFocusEvent.
203 @event{EVT_KILL_FOCUS(func)}
204 Process a @c wxEVT_KILL_FOCUS event. See wxFocusEvent.
205 @event{EVT_IDLE(func)}
206 Process a @c wxEVT_IDLE event. See wxIdleEvent.
207 @event{EVT_JOY_*(func)}
208 Processes joystick events. See wxJoystickEvent.
209 @event{EVT_KEY_DOWN(func)}
210 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
212 @event{EVT_KEY_UP(func)}
213 Process a @c wxEVT_KEY_UP event (any key has been released).
214 @event{EVT_CHAR(func)}
215 Process a @c wxEVT_CHAR event.
217 @event{EVT_MOUSE_CAPTURE_LOST(func)}
218 Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
219 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
220 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. See wxMouseCaptureChangedEvent.
221 @event{EVT_MOUSE_*(func)}
223 @event{EVT_PAINT(func)}
224 Process a @c wxEVT_PAINT event. See wxPaintEvent.
225 @event{EVT_POWER_*(func)}
226 The system power state changed. See wxPowerEvent.
227 @event{EVT_SCROLLWIN_*(func)}
228 Process scroll events. See wxScrollWinEvent.
229 @event{EVT_SET_CURSOR(func)}
230 Process a @c wxEVT_SET_CURSOR event. See wxSetCursorEvent.
231 @event{EVT_SHOW(func)}
232 Process a @c wxEVT_SHOW event. See wxShowEvent.
233 @event{EVT_SIZE(func)}
234 Process a @c wxEVT_SIZE event. See wxSizeEvent.
235 @event{EVT_SYS_COLOUR_CHANGED(func)}
236 Process a @c wxEVT_SYS_COLOUR_CHANGED event. See wxSysColourChangedEvent.
242 @see @ref overview_events, @ref overview_windowsizing
244 class wxWindow
: public wxEvtHandler
253 Constructs a window, which can be a child of a frame, dialog or any other
257 Pointer to a parent window.
259 Window identifier. If wxID_ANY, will automatically create an identifier.
261 Window position. wxDefaultPosition indicates that wxWidgets
262 should generate a default position for the window.
263 If using the wxWindow class directly, supply an actual position.
265 Window size. wxDefaultSize indicates that wxWidgets should generate
266 a default size for the window. If no suitable size can be found, the
267 window will be sized to 20x20 pixels so that the window is visible but
268 obviously not correctly sized.
270 Window style. For generic window styles, please see wxWindow.
274 wxWindow(wxWindow
* parent
, wxWindowID id
,
275 const wxPoint
& pos
= wxDefaultPosition
,
276 const wxSize
& size
= wxDefaultSize
,
278 const wxString
& name
= wxPanelNameStr
);
283 Deletes all sub-windows, then deletes itself. Instead of using
284 the @b delete operator explicitly, you should normally use Destroy()
285 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
287 @see @ref overview_windowdeletion "Window Deletion Overview",
288 Destroy(), wxCloseEvent
294 @name Focus functions
296 See also the static function FindFocus().
301 This method may be overridden in the derived classes to return @false to
302 indicate that this control doesn't accept input at all (i.e. behaves like
303 e.g. wxStaticText) and so doesn't need focus.
305 @see AcceptsFocusFromKeyboard()
307 virtual bool AcceptsFocus() const;
310 This method may be overridden in the derived classes to return @false to
311 indicate that while this control can, in principle, have focus if the user
312 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
313 when using the keyboard.
315 virtual bool AcceptsFocusFromKeyboard() const;
318 Overridden to indicate wehter this window or one of its children accepts
319 focus. Usually it's the same as AcceptsFocus() but is overridden for
322 virtual bool AcceptsFocusRecursively() const;
325 Returns @true if the window (or in case of composite controls, its main
326 child window) has focus.
330 virtual bool HasFocus() const;
333 This method is only implemented by ports which have support for
334 native TAB traversal (such as GTK+ 2.0).
336 It is called by wxWidgets' container control code to give the native
337 system a hint when doing TAB traversal. A call to this does not disable
338 or change the effect of programmatically calling SetFocus().
340 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
342 virtual void SetCanFocus(bool canFocus
);
345 This sets the window to receive keyboard input.
347 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
348 wxPanel::SetFocusIgnoringChildren
350 virtual void SetFocus();
353 This function is called by wxWidgets keyboard navigation code when the user
354 gives the focus to this window from keyboard (e.g. using @c TAB key).
356 By default this method simply calls SetFocus() but
357 can be overridden to do something in addition to this in the derived classes.
359 virtual void SetFocusFromKbd();
365 @name Child management functions
370 Adds a child window. This is called automatically by window creation
371 functions so should not be required by the application programmer.
372 Notice that this function is mostly internal to wxWidgets and shouldn't be
373 called by the user code.
378 virtual void AddChild(wxWindow
* child
);
381 Destroys all children of a window. Called automatically by the destructor.
383 bool DestroyChildren();
386 Find a child of this window, by @a id.
387 May return @a this if it matches itself.
389 wxWindow
* FindWindow(long id
) const;
392 Find a child of this window, by name.
393 May return @a this if it matches itself.
395 wxWindow
* FindWindow(const wxString
& name
) const;
398 Returns a reference to the list of the window's children. @c wxWindowList
399 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
401 wxWindowList
& GetChildren();
406 const wxWindowList
& GetChildren() const;
409 Removes a child window.
411 This is called automatically by window deletion functions so should not
412 be required by the application programmer.
413 Notice that this function is mostly internal to wxWidgets and shouldn't be
414 called by the user code.
417 Child window to remove.
419 virtual void RemoveChild(wxWindow
* child
);
425 @name Sibling and parent management functions
430 Returns the grandparent of a window, or @NULL if there isn't one.
432 wxWindow
* GetGrandParent() const;
435 Returns the next window after this one among the parent children or @NULL
436 if this window is the last child.
440 @see GetPrevSibling()
442 wxWindow
* GetNextSibling() const;
445 Returns the parent of the window, or @NULL if there is no parent.
447 wxWindow
* GetParent() const;
450 Returns the previous window before this one among the parent children or @c
451 @NULL if this window is the first child.
455 @see GetNextSibling()
457 wxWindow
* GetPrevSibling() const;
459 Reparents the window, i.e the window will be removed from its
460 current parent window (e.g. a non-standard toolbar in a wxFrame)
461 and then re-inserted into another.
466 virtual bool Reparent(wxWindow
* newParent
);
472 @name Scrolling and scrollbars functions
474 Note that these methods don't work with native controls which don't use
475 wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
480 Call this function to force one or both scrollbars to be always shown, even if
481 the window is big enough to show its entire contents without scrolling.
486 Whether the horizontal scroll bar should always be visible.
488 Whether the vertical scroll bar should always be visible.
490 @remarks This function is currently only implemented under Mac/Carbon.
492 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
495 Returns the built-in scrollbar position.
499 virtual int GetScrollPos(int orientation
) const;
502 Returns the built-in scrollbar range.
506 virtual int GetScrollRange(int orientation
) const;
509 Returns the built-in scrollbar thumb size.
513 virtual int GetScrollThumb(int orientation
) const;
516 Returns @true if this window has a scroll bar for this orientation.
519 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
521 bool HasScrollbar(int orient
) const;
524 Return whether a scrollbar is always shown.
527 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
529 @see AlwaysShowScrollbars()
531 virtual bool IsScrollbarAlwaysShown(int orient
) const;
534 Scrolls the window by the given number of lines down (if @a lines is
537 @return Returns @true if the window was scrolled, @false if it was already
538 on top/bottom and nothing was done.
540 @remarks This function is currently only implemented under MSW and
541 wxTextCtrl under wxGTK (it also works for wxScrolled classes
542 under all platforms).
546 virtual bool ScrollLines(int lines
);
549 Scrolls the window by the given number of pages down (if @a pages is
552 @return Returns @true if the window was scrolled, @false if it was already
553 on top/bottom and nothing was done.
555 @remarks This function is currently only implemented under MSW and wxGTK.
559 virtual bool ScrollPages(int pages
);
562 Physically scrolls the pixels in the window and move child windows accordingly.
565 Amount to scroll horizontally.
567 Amount to scroll vertically.
569 Rectangle to scroll, if it is @NULL, the whole window is
570 scrolled (this is always the case under wxGTK which doesn't support this
573 @remarks Note that you can often use wxScrolled instead of using this
576 virtual void ScrollWindow(int dx
, int dy
,
577 const wxRect
* rect
= NULL
);
580 Same as #ScrollLines (-1).
585 Same as #ScrollLines (1).
590 Same as #ScrollPages (-1).
595 Same as #ScrollPages (1).
600 Sets the position of one of the built-in scrollbars.
603 Determines the scrollbar whose position is to be set.
604 May be wxHORIZONTAL or wxVERTICAL.
606 Position in scroll units.
608 @true to redraw the scrollbar, @false otherwise.
610 @remarks This function does not directly affect the contents of the
611 window: it is up to the application to take note of
612 scrollbar attributes and redraw contents accordingly.
614 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
617 virtual void SetScrollPos(int orientation
, int pos
,
618 bool refresh
= true);
621 Sets the scrollbar properties of a built-in scrollbar.
624 Determines the scrollbar whose page size is to be set.
625 May be wxHORIZONTAL or wxVERTICAL.
627 The position of the scrollbar in scroll units.
629 The size of the thumb, or visible portion of the scrollbar, in scroll units.
631 The maximum position of the scrollbar. Value of -1 can be used to
632 ask for the scrollbar to be shown but in the disabled state: this
633 can be used to avoid removing the scrollbar even when it is not
634 needed (currently this is only implemented in wxMSW port).
636 @true to redraw the scrollbar, @false otherwise.
639 Let's say you wish to display 50 lines of text, using the same font.
640 The window is sized so that you can only see 16 lines at a time.
643 SetScrollbar(wxVERTICAL, 0, 16, 50);
645 Note that with the window at this size, the thumb position can never
646 go above 50 minus 16, or 34. You can determine how many lines are
647 currently visible by dividing the current view size by the character
649 When defining your own scrollbar behaviour, you will always need
650 to recalculate the scrollbar settings when the window size changes.
651 You could therefore put your scrollbar calculations and SetScrollbar
652 call into a function named AdjustScrollbars, which can be called
653 initially and also from your wxSizeEvent handler function.
655 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
657 virtual void SetScrollbar(int orientation
, int position
,
658 int thumbSize
, int range
,
659 bool refresh
= true);
664 @name Sizing functions
666 See also the protected functions DoGetBestSize() and SetInitialBestSize().
671 Sets the cached best size value.
675 void CacheBestSize(const wxSize
& size
) const;
678 Converts client area size @a size to corresponding window size.
680 In other words, the returned value is what would GetSize() return if this
681 window had client area of given size. Components with wxDefaultCoord
682 value are left unchanged. Note that the conversion is not always
683 exact, it assumes that non-client area doesn't change and so doesn't
684 take into account things like menu bar (un)wrapping or (dis)appearance
689 @see WindowToClientSize()
691 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
694 Converts window size @a size to corresponding client area size
695 In other words, the returned value is what would GetClientSize() return if
696 this window had given window size. Components with wxDefaultCoord value
699 Note that the conversion is not always exact, it assumes that
700 non-client area doesn't change and so doesn't take into account things
701 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
705 @see ClientToWindowSize()
707 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
710 Sizes the window so that it fits around its subwindows.
712 This function won't do anything if there are no subwindows and will only really
713 work correctly if sizers are used for the subwindows layout.
715 Also, if the window has exactly one subwindow it is better (faster and the result
716 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
720 window->SetClientSize(child->GetSize());
723 instead of calling Fit().
725 @see @ref overview_windowsizing
730 Similar to Fit(), but sizes the interior (virtual) size of a window.
732 Mainly useful with scrolled windows to reset scrollbars after sizing
733 changes that do not trigger a size event, and/or scrolled windows without
734 an interior sizer. This function similarly won't do anything if there are
737 virtual void FitInside();
740 This functions returns the best acceptable minimal size for the window.
742 For example, for a static control, it will be the minimal size such that the
743 control label is not truncated. For windows containing subwindows (typically
744 wxPanel), the size returned by this function will be the same as the size
745 the window would have had after calling Fit().
747 Note that when you write your own widget you need to overload the
748 DoGetBestSize() function instead of this (non-virtual!) function.
750 @see CacheBestSize(), @ref overview_windowsizing
752 wxSize
GetBestSize() const;
755 Returns the size of the window 'client area' in pixels.
757 The client area is the area which may be drawn on by the programmer,
758 excluding title bar, border, scrollbars, etc.
759 Note that if this window is a top-level one and it is currently minimized, the
760 return size is empty (both width and height are 0).
762 @see GetSize(), GetVirtualSize()
764 void GetClientSize(int* width
, int* height
) const;
769 wxSize
GetClientSize() const;
772 Merges the window's best size into the min size and returns the result.
773 This is the value used by sizers to determine the appropriate
774 ammount of space to allocate for the widget.
776 This is the method called by any wxSizer when they query the size
777 of a certain window or control.
779 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
781 virtual wxSize
GetEffectiveMinSize() const;
784 Returns the maximum size of window's client area.
786 This is an indication to the sizer layout mechanism that this is the maximum
787 possible size as well as the upper bound on window's size settable using
790 @see GetMaxSize(), @ref overview_windowsizing
792 virtual wxSize
GetMaxClientSize() const;
795 Returns the maximum size of the window.
797 This is an indication to the sizer layout mechanism that this is the maximum
798 possible size as well as the upper bound on window's size settable using SetSize().
800 @see GetMaxClientSize(), @ref overview_windowsizing
802 virtual wxSize
GetMaxSize() const;
805 Returns the minimum size of window's client area, an indication to the sizer
806 layout mechanism that this is the minimum required size of its client area.
808 It normally just returns the value set by SetMinClientSize(), but it can be
809 overridden to do the calculation on demand.
811 @see GetMinSize(), @ref overview_windowsizing
813 virtual wxSize
GetMinClientSize() const;
816 Returns the minimum size of the window, an indication to the sizer layout
817 mechanism that this is the minimum required size.
819 This method normally just returns the value set by SetMinSize(), but it
820 can be overridden to do the calculation on demand.
822 @see GetMinClientSize(), @ref overview_windowsizing
824 virtual wxSize
GetMinSize() const;
827 Returns the size of the entire window in pixels, including title bar, border,
830 Note that if this window is a top-level one and it is currently minimized, the
831 returned size is the restored window size, not the size of the window icon.
834 Receives the window width.
836 Receives the window height.
838 @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
840 void GetSize(int* width
, int* height
) const;
843 See the GetSize(int*,int*) overload for more info.
845 wxSize
GetSize() const;
848 This gets the virtual size of the window in pixels.
849 By default it returns the client size of the window, but after a call to
850 SetVirtualSize() it will return the size set with that method.
852 @see @ref overview_windowsizing
854 wxSize
GetVirtualSize() const;
857 Like the other GetVirtualSize() overload but uses pointers instead.
860 Receives the window virtual width.
862 Receives the window virtual height.
864 void GetVirtualSize(int* width
, int* height
) const;
867 Returns the size of the left/right and top/bottom borders of this window in x
868 and y components of the result respectively.
870 virtual wxSize
GetWindowBorderSize() const;
873 Resets the cached best size value so it will be recalculated the next time it
878 void InvalidateBestSize();
881 Posts a size event to the window.
883 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
885 void PostSizeEvent();
888 Posts a size event to the parent of this window.
890 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
893 void PostSizeEventToParent();
896 This function sends a dummy @ref wxSizeEvent "size event" to
897 the window allowing it to re-layout its children positions.
899 It is sometimes useful to call this function after adding or deleting a
900 children after the frame creation or if a child size changes. Note that
901 if the frame is using either sizers or constraints for the children
902 layout, it is enough to call wxWindow::Layout() directly and this
903 function should not be used in this case.
905 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
906 the event, i.e. schedules it for later processing, instead of
907 dispatching it directly. You can also use PostSizeEvent() as a more
908 readable equivalent of calling this function with this flag.
911 May include @c wxSEND_EVENT_POST. Default value is 0.
913 virtual void SendSizeEvent(int flags
= 0);
916 Safe wrapper for GetParent()->SendSizeEvent().
918 This function simply checks that the window has a valid parent which is
919 not in process of being deleted and calls SendSizeEvent() on it. It is
920 used internally by windows such as toolbars changes to whose state
921 should result in parent re-layout (e.g. when a toolbar is added to the
922 top of the window, all the other windows must be shifted down).
924 @see PostSizeEventToParent()
927 See description of this parameter in SendSizeEvent() documentation.
929 void SendSizeEventToParent(int flags
= 0);
932 This sets the size of the window client area in pixels.
934 Using this function to size a window tends to be more device-independent
935 than SetSize(), since the application need not worry about what dimensions
936 the border or title bar have when trying to fit the window around panel
939 @see @ref overview_windowsizing
941 virtual void SetClientSize(int width
, int height
);
946 virtual void SetClientSize(const wxSize
& size
);
949 This normally does not need to be called by user code.
950 It is called when a window is added to a sizer, and is used so the window
951 can remove itself from the sizer when it is destroyed.
953 void SetContainingSizer(wxSizer
* sizer
);
956 A @e smart SetSize that will fill in default size components with the
957 window's @e best size values.
959 Also sets the window's minsize to the value passed in for use with sizers.
960 This means that if a full or partial size is passed to this function then
961 the sizers will use that size instead of the results of GetBestSize() to
962 determine the minimum needs of the window for layout.
964 Most controls will use this to set their initial size, and their min
965 size to the passed in value (if any.)
967 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
968 @ref overview_windowsizing
970 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
973 Sets the maximum client size of the window, to indicate to the sizer
974 layout mechanism that this is the maximum possible size of its client area.
976 Note that this method is just a shortcut for:
978 SetMaxSize(ClientToWindowSize(size));
981 @see SetMaxSize(), @ref overview_windowsizing
983 virtual void SetMaxClientSize(const wxSize
& size
);
986 Sets the maximum size of the window, to indicate to the sizer layout mechanism
987 that this is the maximum possible size.
989 @see SetMaxClientSize(), @ref overview_windowsizing
991 virtual void SetMaxSize(const wxSize
& size
);
994 Sets the minimum client size of the window, to indicate to the sizer
995 layout mechanism that this is the minimum required size of window's client
998 You may need to call this if you change the window size after
999 construction and before adding to its parent sizer.
1001 Note, that just as with SetMinSize(), calling this method doesn't
1002 prevent the program from explicitly making the window smaller than the
1005 Note that this method is just a shortcut for:
1007 SetMinSize(ClientToWindowSize(size));
1010 @see SetMinSize(), @ref overview_windowsizing
1012 virtual void SetMinClientSize(const wxSize
& size
);
1015 Sets the minimum size of the window, to indicate to the sizer layout
1016 mechanism that this is the minimum required size.
1018 You may need to call this if you change the window size after
1019 construction and before adding to its parent sizer.
1021 Notice that calling this method doesn't prevent the program from making
1022 the window explicitly smaller than the specified size by calling
1023 SetSize(), it just ensures that it won't become smaller than this size
1024 during the automatic layout.
1026 @see SetMinClientSize(), @ref overview_windowsizing
1028 virtual void SetMinSize(const wxSize
& size
);
1031 Sets the size of the window in pixels.
1034 Required x position in pixels, or wxDefaultCoord to indicate that the
1035 existing value should be used.
1037 Required y position in pixels, or wxDefaultCoord to indicate that the
1038 existing value should be used.
1040 Required width in pixels, or wxDefaultCoord to indicate that the existing
1041 value should be used.
1043 Required height position in pixels, or wxDefaultCoord to indicate that the
1044 existing value should be used.
1046 Indicates the interpretation of other parameters.
1047 It is a bit list of the following:
1048 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
1049 a wxWidgets-supplied default width.
1050 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
1051 a wxWidgets-supplied default height.
1052 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1053 a wxWidgets-supplied default size.
1054 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1055 if wxDefaultCoord values are supplied.
1056 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1057 wxDefaultCoord) to be interpreted as real
1058 dimensions, not default values.
1059 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1060 already the same as the parameters of this function,
1061 nothing is done. but with this flag a window resize may
1062 be forced even in this case (supported in wx 2.6.2 and
1063 later and only implemented for MSW and ignored elsewhere
1066 @remarks This overload sets the position and optionally size, of the window.
1067 Parameters may be wxDefaultCoord to indicate either that a default
1068 should be supplied by wxWidgets, or that the current value of the
1069 dimension should be used.
1071 @see Move(), @ref overview_windowsizing
1073 void SetSize(int x
, int y
, int width
, int height
,
1074 int sizeFlags
= wxSIZE_AUTO
);
1077 Sets the size of the window in pixels.
1078 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1080 @remarks This form must be used with non-default width and height values.
1082 @see Move(), @ref overview_windowsizing
1084 virtual void SetSize(const wxRect
& rect
);
1089 virtual void SetSize(const wxSize
& size
);
1094 virtual void SetSize(int width
, int height
);
1097 Use of this function for windows which are not toplevel windows
1098 (such as wxDialog or wxFrame) is discouraged.
1099 Please use SetMinSize() and SetMaxSize() instead.
1101 @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
1103 void SetSizeHints( const wxSize
& minSize
,
1104 const wxSize
& maxSize
=wxDefaultSize
,
1105 const wxSize
& incSize
=wxDefaultSize
);
1108 Sets the virtual size of the window in pixels.
1110 @see @ref overview_windowsizing
1112 void SetVirtualSize(int width
, int height
);
1117 void SetVirtualSize(const wxSize
& size
);
1123 @name Positioning functions
1128 A synonym for Centre().
1130 void Center(int dir
= wxBOTH
);
1133 A synonym for CentreOnParent().
1135 void CenterOnParent(int dir
= wxBOTH
);
1141 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1142 or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
1143 if you want to center the window on the entire screen and not on its
1146 @remarks If the window is a top level one (i.e. doesn't have a parent),
1147 it will be centered relative to the screen anyhow.
1151 void Centre(int direction
= wxBOTH
);
1154 Centres the window on its parent. This is a more readable synonym for Centre().
1157 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1160 @remarks This methods provides for a way to center top level windows over
1161 their parents instead of the entire screen. If there
1162 is no parent or if the window is not a top level
1163 window, then behaviour is the same as Centre().
1165 @see wxTopLevelWindow::CentreOnScreen
1167 void CentreOnParent(int direction
= wxBOTH
);
1169 This gets the position of the window in pixels, relative to the parent window
1170 for the child windows or relative to the display origin for the top level windows.
1173 Receives the x position of the window if non-@NULL.
1175 Receives the y position of the window if non-@NULL.
1177 @see GetScreenPosition()
1179 void GetPosition(int* x
, int* y
) const;
1182 This gets the position of the window in pixels, relative to the parent window
1183 for the child windows or relative to the display origin for the top level windows.
1185 @see GetScreenPosition()
1187 wxPoint
GetPosition() const;
1190 Returns the position and size of the window as a wxRect object.
1192 @see GetScreenRect()
1194 wxRect
GetRect() const;
1197 Returns the window position in screen coordinates, whether the window is a
1198 child window or a top level one.
1201 Receives the x position of the window on the screen if non-@NULL.
1203 Receives the y position of the window on the screen if non-@NULL.
1207 void GetScreenPosition(int* x
, int* y
) const;
1210 Returns the window position in screen coordinates, whether the window is a
1211 child window or a top level one.
1215 wxPoint
GetScreenPosition() const;
1218 Returns the position and size of the window on the screen as a wxRect object.
1222 wxRect
GetScreenRect() const;
1225 Moves the window to the given position.
1228 Required x position.
1230 Required y position.
1232 See SetSize() for more info about this parameter.
1234 @remarks Implementations of SetSize can also implicitly implement the
1235 Move() function, which is defined in the base wxWindow class as the call:
1237 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1242 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1245 Moves the window to the given position.
1248 wxPoint object representing the position.
1250 See SetSize() for more info about this parameter.
1252 @remarks Implementations of SetSize() can also implicitly implement the
1253 Move() function, which is defined in the base wxWindow class as the call:
1255 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1260 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1266 @name Coordinate conversion functions
1271 Converts to screen coordinates from coordinates relative to this window.
1274 A pointer to a integer value for the x coordinate. Pass the client
1275 coordinate in, and a screen coordinate will be passed out.
1277 A pointer to a integer value for the y coordinate. Pass the client
1278 coordinate in, and a screen coordinate will be passed out.
1281 In place of a single overloaded method name, wxPython implements the following methods:
1282 - ClientToScreen(point): Accepts and returns a wxPoint
1283 - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
1286 void ClientToScreen(int* x
, int* y
) const;
1289 Converts to screen coordinates from coordinates relative to this window.
1292 The client position for the second form of the function.
1294 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
1297 Converts a point or size from dialog units to pixels.
1299 For the x dimension, the dialog units are multiplied by the average character
1300 width and then divided by 4.
1301 For the y dimension, the dialog units are multiplied by the average character
1302 height and then divided by 8.
1304 @remarks Dialog units are used for maintaining a dialog's proportions
1305 even if the font changes.
1306 You can also use these functions programmatically.
1307 A convenience macro is defined:
1309 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1312 @see ConvertPixelsToDialog()
1314 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
);
1319 wxSize
ConvertDialogToPixels(const wxSize
& sz
);
1322 Converts a point or size from pixels to dialog units.
1324 For the x dimension, the pixels are multiplied by 4 and then divided by the
1325 average character width.
1326 For the y dimension, the pixels are multiplied by 8 and then divided by the
1327 average character height.
1329 @remarks Dialog units are used for maintaining a dialog's proportions
1330 even if the font changes.
1332 @see ConvertDialogToPixels()
1334 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
);
1339 wxSize
ConvertPixelsToDialog(const wxSize
& sz
);
1342 Converts from screen to client window coordinates.
1345 Stores the screen x coordinate and receives the client x coordinate.
1347 Stores the screen x coordinate and receives the client x coordinate.
1349 void ScreenToClient(int* x
, int* y
) const;
1352 Converts from screen to client window coordinates.
1355 The screen position.
1357 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1363 @name Drawing-related functions
1368 Clears the window by filling it with the current background colour. Does not
1369 cause an erase background event to be generated.
1371 virtual void ClearBackground();
1374 Freezes the window or, in other words, prevents any updates from taking
1375 place on screen, the window is not redrawn at all.
1377 Thaw() must be called to reenable window redrawing. Calls to these two
1378 functions may be nested but to ensure that the window is properly
1379 repainted again, you must thaw it exactly as many times as you froze it.
1381 If the window has any children, they are recursively frozen too.
1383 This method is useful for visual appearance optimization (for example,
1384 it is a good idea to use it before doing many large text insertions in
1385 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1386 platforms nor for all controls so it is mostly just a hint to wxWidgets
1387 and not a mandatory directive.
1389 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1394 Reenables window updating after a previous call to Freeze().
1396 To really thaw the control, it must be called exactly the same number
1397 of times as Freeze().
1399 If the window has any children, they are recursively thawn too.
1401 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1406 Returns @true if the window is currently frozen by a call to Freeze().
1408 @see Freeze(), Thaw()
1410 bool IsFrozen() const;
1413 Returns the background colour of the window.
1415 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1417 wxColour
GetBackgroundColour() const;
1420 Returns the background style of the window.
1422 @see SetBackgroundColour(), GetForegroundColour(),
1423 SetBackgroundStyle(), SetTransparent()
1425 virtual wxBackgroundStyle
GetBackgroundStyle() const;
1428 Returns the character height for this window.
1430 virtual int GetCharHeight() const;
1433 Returns the average character width for this window.
1435 virtual int GetCharWidth() const;
1438 Currently this is the same as calling
1439 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1441 One advantage of using this function compared to the static version is that
1442 the call is automatically dispatched to the correct class (as usual with
1443 virtual functions) and you don't have to specify the class name explicitly.
1445 The other one is that in the future this function could return different
1446 results, for example it might return a different font for an "Ok" button
1447 than for a generic button if the users GUI is configured to show such buttons
1448 in bold font. Of course, the down side is that it is impossible to call this
1449 function without actually having an object to apply it to whereas the static
1450 version can be used without having to create an object first.
1452 virtual wxVisualAttributes
GetDefaultAttributes() const;
1455 Returns the font for this window.
1459 wxFont
GetFont() const;
1462 Returns the foreground colour of the window.
1464 @remarks The interpretation of foreground colour is open to
1465 interpretation according to the window class; it may be
1466 the text colour or other colour, or it may not be used at all.
1468 @see SetForegroundColour(), SetBackgroundColour(),
1469 GetBackgroundColour()
1471 wxColour
GetForegroundColour() const;
1474 Gets the dimensions of the string as it would be drawn on the
1475 window with the currently selected font.
1477 The text extent is returned in @a w and @a h pointers.
1480 String whose extent is to be measured.
1482 Return value for width.
1484 Return value for height.
1486 Return value for descent (optional).
1487 @param externalLeading
1488 Return value for external leading (optional).
1490 Font to use instead of the current window font (optional).
1492 void GetTextExtent(const wxString
& string
,
1494 int* descent
= NULL
,
1495 int* externalLeading
= NULL
,
1496 const wxFont
* font
= NULL
) const;
1499 Gets the dimensions of the string as it would be drawn on the
1500 window with the currently selected font.
1502 wxSize
GetTextExtent(const wxString
& string
) const;
1505 Returns the region specifying which parts of the window have been damaged.
1506 Should only be called within an wxPaintEvent handler.
1508 @see wxRegion, wxRegionIterator
1510 const wxRegion
& GetUpdateRegion() const;
1513 Returns @true if this window background is transparent (as, for example,
1514 for wxStaticText) and should show the parent window background.
1516 This method is mostly used internally by the library itself and you normally
1517 shouldn't have to call it. You may, however, have to override it in your
1518 wxWindow-derived class to ensure that background is painted correctly.
1520 virtual bool HasTransparentBackground();
1523 Causes this window, and all of its children recursively (except under wxGTK1
1524 where this is not implemented), to be repainted. Note that repainting doesn't
1525 happen immediately but only during the next event loop iteration, if you need
1526 to update the window immediately you should use Update() instead.
1528 @param eraseBackground
1529 If @true, the background will be erased.
1531 If non-@NULL, only the given rectangle will be treated as damaged.
1535 virtual void Refresh(bool eraseBackground
= true,
1536 const wxRect
* rect
= NULL
);
1539 Redraws the contents of the given rectangle: only the area inside it will be
1542 This is the same as Refresh() but has a nicer syntax as it can be called
1543 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1545 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1548 Calling this method immediately repaints the invalidated area of the window and
1549 all of its children recursively while this would usually only happen when the
1550 flow of control returns to the event loop.
1552 Notice that this function doesn't invalidate any area of the window so
1553 nothing happens if nothing has been invalidated (i.e. marked as requiring
1554 a redraw). Use Refresh() first if you want to immediately redraw the
1555 window unconditionally.
1557 virtual void Update();
1560 Sets the background colour of the window.
1561 Please see InheritAttributes() for explanation of the difference between
1562 this method and SetOwnBackgroundColour().
1565 The colour to be used as the background colour, pass
1566 wxNullColour to reset to the default colour.
1568 @remarks The background colour is usually painted by the default
1569 wxEraseEvent event handler function under Windows and
1570 automatically under GTK.
1571 Note that setting the background colour does not cause an
1572 immediate refresh, so you may wish to call wxWindow::ClearBackground
1573 or wxWindow::Refresh after calling this function.
1574 Using this function will disable attempts to use themes for
1575 this window, if the system supports them. Use with care since
1576 usually the themes represent the appearance chosen by the user
1577 to be used for all applications on the system.
1579 @see GetBackgroundColour(), SetForegroundColour(),
1580 GetForegroundColour(), ClearBackground(),
1581 Refresh(), wxEraseEvent
1583 virtual bool SetBackgroundColour(const wxColour
& colour
);
1586 Sets the background style of the window.
1588 The default background style is wxBG_STYLE_ERASE which indicates that
1589 the window background may be erased in EVT_ERASE_BACKGROUND handler.
1590 This is a safe compatibility default however you may want to change it
1591 to wxBG_STYLE_SYSTEM if you don't define any erase background event
1592 handlers at all to avoid unnecessary generation of erase background
1593 events and always let system erase the background. And you should
1594 change the background style to wxBG_STYLE_PAINT if you define an
1595 EVT_PAINT handler which completely overwrites the window background as
1596 in this case erasing it previously, either in EVT_ERASE_BACKGROUND
1597 handler or in the system default handler, would result in flicker as
1598 the background pixels will be repainted twice every time the window is
1599 redrawn. Do ensure that the background is entirely erased by your
1600 EVT_PAINT handler in this case however as otherwise garbage may be left
1603 Notice that in previous versions of wxWidgets a common way to work
1604 around the above mentioned flickering problem was to define an empty
1605 EVT_ERASE_BACKGROUND handler. Setting background style to
1606 wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
1609 @see SetBackgroundColour(), GetForegroundColour(),
1612 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
1615 Sets the font for this window. This function should not be called for the
1616 parent window if you don't want its font to be inherited by its children,
1617 use SetOwnFont() instead in this case and see InheritAttributes() for more
1620 Please notice that the given font is not automatically used for
1621 wxPaintDC objects associated with this window, you need to
1622 call wxDC::SetFont too. However this font is used by
1623 any standard controls for drawing their text as well as by
1627 Font to associate with this window, pass
1628 wxNullFont to reset to the default font.
1630 @return @true if the want was really changed, @false if it was already set
1631 to this font and so nothing was done.
1633 @see GetFont(), InheritAttributes()
1635 virtual bool SetFont(const wxFont
& font
);
1638 Sets the foreground colour of the window.
1639 Please see InheritAttributes() for explanation of the difference between
1640 this method and SetOwnForegroundColour().
1643 The colour to be used as the foreground colour, pass
1644 wxNullColour to reset to the default colour.
1646 @remarks The interpretation of foreground colour is open to
1647 interpretation according to the window class; it may be
1648 the text colour or other colour, or it may not be used at all.
1650 @see GetForegroundColour(), SetBackgroundColour(),
1651 GetBackgroundColour(), ShouldInheritColours()
1653 virtual bool SetForegroundColour(const wxColour
& colour
);
1656 Sets the background colour of the window but prevents it from being inherited
1657 by the children of this window.
1659 @see SetBackgroundColour(), InheritAttributes()
1661 void SetOwnBackgroundColour(const wxColour
& colour
);
1664 Sets the font of the window but prevents it from being inherited by the
1665 children of this window.
1667 @see SetFont(), InheritAttributes()
1669 void SetOwnFont(const wxFont
& font
);
1672 Sets the foreground colour of the window but prevents it from being inherited
1673 by the children of this window.
1675 @see SetForegroundColour(), InheritAttributes()
1677 void SetOwnForegroundColour(const wxColour
& colour
);
1680 @deprecated use wxDC::SetPalette instead.
1682 void SetPalette(const wxPalette
& pal
);
1685 Return @true from here to allow the colours of this window to be changed by
1686 InheritAttributes(), returning @false forbids inheriting them from the parent window.
1688 The base class version returns @false, but this method is overridden in
1689 wxControl where it returns @true.
1691 virtual bool ShouldInheritColours() const;
1694 This function tells a window if it should use the system's "theme" code
1695 to draw the windows' background instead if its own background drawing
1696 code. This does not always have any effect since the underlying platform
1697 obviously needs to support the notion of themes in user defined windows.
1698 One such platform is GTK+ where windows can have (very colourful) backgrounds
1699 defined by a user's selected theme.
1701 Dialogs, notebook pages and the status bar have this flag set to @true
1702 by default so that the default look and feel is simulated best.
1704 virtual void SetThemeEnabled(bool enable
);
1707 Returns @true if the system supports transparent windows and calling
1708 SetTransparent() may succeed. If this function returns @false, transparent
1709 windows are definitely not supported by the current system.
1711 virtual bool CanSetTransparent();
1714 Set the transparency of the window. If the system supports transparent windows,
1715 returns @true, otherwise returns @false and the window remains fully opaque.
1716 See also CanSetTransparent().
1718 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1719 fully transparent window and 255 to the fully opaque one. The constants
1720 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1722 virtual bool SetTransparent(wxByte alpha
);
1728 @name Event-handling functions
1730 wxWindow allows you to build a (sort of) stack of event handlers which
1731 can be used to override the window's own event handling.
1736 Returns the event handler for this window.
1737 By default, the window is its own event handler.
1739 @see SetEventHandler(), PushEventHandler(),
1740 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1742 wxEvtHandler
* GetEventHandler() const;
1745 This function will generate the appropriate call to Navigate() if the key
1746 event is one normally used for keyboard navigation and return @true in this case.
1748 @return Returns @true if the key pressed was for navigation and was
1749 handled, @false otherwise.
1753 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
1758 GetEventHandler()->SafelyProcessEvent(event);
1761 @see ProcessWindowEvent()
1763 bool HandleWindowEvent(wxEvent
& event
) const;
1766 Convenient wrapper for ProcessEvent().
1768 This is the same as writing @code GetEventHandler()->ProcessEvent(event);
1769 @endcode but more convenient. Notice that ProcessEvent() itself can't
1770 be called for wxWindow objects as it ignores the event handlers
1771 associated with the window, use this function instead.
1773 bool ProcessWindowEvent(wxEvent
& event
);
1776 Removes and returns the top-most event handler on the event handler stack.
1778 E.g. in the case of:
1779 @image html overview_events_winstack.png
1780 when calling @c W->PopEventHandler(), the event handler @c A will be
1781 removed and @c B will be the first handler of the stack.
1783 Note that it's an error to call this function when no event handlers
1784 were pushed on this window (i.e. when the window itself is its only
1787 @param deleteHandler
1788 If this is @true, the handler will be deleted after it is removed
1789 (and the returned value will be @NULL).
1791 @see @ref overview_events_processing
1793 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
1796 Pushes this event handler onto the event stack for the window.
1798 An event handler is an object that is capable of processing the events sent
1799 to a window. By default, the window is its own event handler, but an application
1800 may wish to substitute another, for example to allow central implementation
1801 of event-handling for a variety of different window classes.
1803 wxWindow::PushEventHandler allows an application to set up a @e stack
1804 of event handlers, where an event not handled by one event handler is
1805 handed to the next one in the chain.
1807 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
1810 W->PushEventHandler(A);
1811 W->PushEventHandler(B);
1813 you will end up with the following situation:
1814 @image html overview_events_winstack.png
1816 Note that you can use wxWindow::PopEventHandler to remove the event handler.
1819 Specifies the handler to be pushed.
1820 It must not be part of a wxEvtHandler chain; an assert will fail
1821 if it's not unlinked (see wxEvtHandler::IsUnlinked).
1823 @see @ref overview_events_processing
1825 void PushEventHandler(wxEvtHandler
* handler
);
1828 Find the given @a handler in the windows event handler stack and
1829 removes (but does not delete) it from the stack.
1831 See wxEvtHandler::Unlink() for more info.
1834 The event handler to remove, must be non-@NULL and
1835 must be present in this windows event handlers stack.
1837 @return Returns @true if it was found and @false otherwise (this also
1838 results in an assert failure so this function should
1839 only be called when the handler is supposed to be there).
1841 @see PushEventHandler(), PopEventHandler()
1843 bool RemoveEventHandler(wxEvtHandler
* handler
);
1846 Sets the event handler for this window.
1848 Note that if you use this function you may want to use as the "next" handler
1849 of @a handler the window itself; in this way when @a handler doesn't process
1850 an event, the window itself will have a chance to do it.
1853 Specifies the handler to be set. Cannot be @NULL.
1855 @see @ref overview_events_processing
1857 void SetEventHandler(wxEvtHandler
* handler
);
1860 wxWindows cannot be used to form event handler chains; this function
1861 thus will assert when called.
1863 Note that instead you can use PushEventHandler() or SetEventHandler() to
1864 implement a stack of event handlers to override wxWindow's own
1865 event handling mechanism.
1867 virtual void SetNextHandler(wxEvtHandler
* handler
);
1870 wxWindows cannot be used to form event handler chains; this function
1871 thus will assert when called.
1873 Note that instead you can use PushEventHandler() or SetEventHandler() to
1874 implement a stack of event handlers to override wxWindow's own
1875 event handling mechanism.
1877 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
1884 @name Window styles functions
1889 Returns the extra style bits for the window.
1891 long GetExtraStyle() const;
1894 Gets the window style that was passed to the constructor or Create()
1895 method. GetWindowStyle() is another name for the same function.
1897 virtual long GetWindowStyleFlag() const;
1900 See GetWindowStyleFlag() for more info.
1902 long GetWindowStyle() const;
1905 Returns @true if the window has the given @a exFlag bit set in its
1908 @see SetExtraStyle()
1910 bool HasExtraStyle(int exFlag
) const;
1913 Returns @true if the window has the given @a flag bit set.
1915 bool HasFlag(int flag
) const;
1918 Sets the extra style bits for the window.
1919 The currently defined extra style bits are reported in the class
1922 virtual void SetExtraStyle(long exStyle
);
1925 Sets the style of the window. Please note that some styles cannot be changed
1926 after the window creation and that Refresh() might need to be be called
1927 after changing the others for the change to take place immediately.
1929 See @ref overview_windowstyles "Window styles" for more information about flags.
1931 @see GetWindowStyleFlag()
1933 virtual void SetWindowStyleFlag(long style
);
1936 See SetWindowStyleFlag() for more info.
1938 void SetWindowStyle(long style
);
1941 Turns the given @a flag on if it's currently turned off and vice versa.
1942 This function cannot be used if the value of the flag is 0 (which is often
1943 the case for default flags).
1945 Also, please notice that not all styles can be changed after the control
1948 @return Returns @true if the style was turned on by this function, @false
1949 if it was switched off.
1951 @see SetWindowStyleFlag(), HasFlag()
1953 bool ToggleWindowStyle(int flag
);
1959 @name Tab order functions
1964 Moves this window in the tab navigation order after the specified @e win.
1965 This means that when the user presses @c TAB key on that other window,
1966 the focus switches to this window.
1968 Default tab order is the same as creation order, this function and
1969 MoveBeforeInTabOrder() allow to change
1970 it after creating all the windows.
1973 A sibling of this window which should precede it in tab order,
1976 void MoveAfterInTabOrder(wxWindow
* win
);
1979 Same as MoveAfterInTabOrder() except that it inserts this window just
1980 before @a win instead of putting it right after it.
1982 void MoveBeforeInTabOrder(wxWindow
* win
);
1985 Performs a keyboard navigation action starting from this window.
1986 This method is equivalent to calling NavigateIn() method on the
1990 A combination of wxNavigationKeyEvent::IsForward and
1991 wxNavigationKeyEvent::WinChange.
1993 @return Returns @true if the focus was moved to another window or @false
1996 @remarks You may wish to call this from a text control custom keypress
1997 handler to do the default navigation behaviour for the
1998 tab key, since the standard default behaviour for a
1999 multiline text control with the wxTE_PROCESS_TAB style
2000 is to insert a tab and not navigate to the next
2001 control. See also wxNavigationKeyEvent and
2002 HandleAsNavigationKey.
2004 bool Navigate(int flags
= IsForward
);
2007 Performs a keyboard navigation action inside this window.
2008 See Navigate() for more information.
2010 bool NavigateIn(int flags
= IsForward
);
2017 @name Z order functions
2022 Lowers the window to the bottom of the window hierarchy (Z-order).
2025 This function only works for wxTopLevelWindow-derived classes.
2029 virtual void Lower();
2032 Raises the window to the top of the window hierarchy (Z-order).
2035 This function only works for wxTopLevelWindow-derived classes.
2039 virtual void Raise();
2045 @name Window status functions
2051 Equivalent to calling wxWindow::Show(@false).
2056 This function hides a window, like Hide(), but using a special visual
2059 The parameters of this function are the same as for ShowWithEffect(),
2060 please see their description there.
2064 virtual bool HideWithEffect(wxShowEffect effect
,
2065 unsigned int timeout
= 0);
2067 Returns @true if the window is enabled, i.e. if it accepts user input,
2070 Notice that this method can return @false even if this window itself hadn't
2071 been explicitly disabled when one of its parent windows is disabled.
2072 To get the intrinsic status of this window, use IsThisEnabled()
2076 bool IsEnabled() const;
2079 Returns @true if the given point or rectangle area has been exposed since the
2080 last repaint. Call this in an paint event handler to optimize redrawing by
2081 only redrawing those areas, which have been exposed.
2083 bool IsExposed(int x
, int y
) const;
2088 bool IsExposed(wxPoint
& pt
) const;
2093 bool IsExposed(int x
, int y
, int w
, int h
) const;
2098 bool IsExposed(wxRect
& rect
) const;
2100 Returns @true if the window is shown, @false if it has been hidden.
2102 @see IsShownOnScreen()
2104 virtual bool IsShown() const;
2107 Returns @true if the window is physically visible on the screen, i.e. it
2108 is shown and all its parents up to the toplevel window are shown as well.
2112 virtual bool IsShownOnScreen() const;
2115 Disables the window. Same as @ref Enable() Enable(@false).
2117 @return Returns @true if the window has been disabled, @false if it had
2118 been already disabled before the call to this function.
2123 Enable or disable the window for user input. Note that when a parent window is
2124 disabled, all of its children are disabled as well and they are reenabled again
2128 If @true, enables the window for input. If @false, disables the window.
2130 @return Returns @true if the window has been enabled or disabled, @false
2131 if nothing was done, i.e. if the window had already
2132 been in the specified state.
2134 @see IsEnabled(), Disable(), wxRadioBox::Enable
2136 virtual bool Enable(bool enable
= true);
2139 Shows or hides the window. You may need to call Raise()
2140 for a top level window if you want to bring it to top, although this is not
2141 needed if Show() is called immediately after the frame creation.
2144 If @true displays the window. Otherwise, hides it.
2146 @return @true if the window has been shown or hidden or @false if nothing
2147 was done because it already was in the requested state.
2149 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2151 virtual bool Show(bool show
= true);
2154 This function shows a window, like Show(), but using a special visual
2161 The @a timeout parameter specifies the time of the animation, in
2162 milliseconds. If the default value of 0 is used, the default
2163 animation time for the current platform is used.
2165 @note Currently this function is only implemented in wxMSW and does the
2166 same thing as Show() in the other ports.
2170 @see HideWithEffect()
2172 virtual bool ShowWithEffect(wxShowEffect effect
,
2173 unsigned int timeout
= 0);
2179 @name Context-sensitive help functions
2184 Gets the help text to be used as context-sensitive help for this window.
2185 Note that the text is actually stored by the current wxHelpProvider
2186 implementation, and not in the window object itself.
2188 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2190 wxString
GetHelpText() const;
2193 Sets the help text to be used as context-sensitive help for this window.
2194 Note that the text is actually stored by the current wxHelpProvider
2195 implementation, and not in the window object itself.
2197 @see GetHelpText(), wxHelpProvider::AddHelp()
2199 void SetHelpText(const wxString
& helpText
);
2202 Gets the help text to be used as context-sensitive help for this window.
2203 This method should be overridden if the help message depends on the position
2204 inside the window, otherwise GetHelpText() can be used.
2207 Coordinates of the mouse at the moment of help event emission.
2209 Help event origin, see also wxHelpEvent::GetOrigin.
2211 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
2212 wxHelpEvent::Origin origin
) const;
2215 Get the associated tooltip or @NULL if none.
2217 wxToolTip
* GetToolTip() const;
2220 Attach a tooltip to the window.
2222 wxToolTip pointer can be @NULL in the overload taking the pointer,
2223 meaning to unset any existing tooltips, however UnsetToolTip() provides
2224 a more readable alternative to this operation.
2226 Notice that these methods are always available, even if wxWidgets was
2227 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2230 @see GetToolTip(), wxToolTip
2232 void SetToolTip(const wxString
& tip
);
2237 void SetToolTip(wxToolTip
* tip
);
2240 Unset any existing tooltip.
2246 void UnsetToolTip();
2252 @name Popup/context menu functions
2257 This function shows a popup menu at the given position in this window and
2258 returns the selected id.
2260 It can be more convenient than the general purpose PopupMenu() function
2261 for simple menus proposing a choice in a list of strings to the user.
2263 Notice that to avoid unexpected conflicts between the (usually
2264 consecutive range of) ids used by the menu passed to this function and
2265 the existing EVT_UPDATE_UI() handlers, this function temporarily
2266 disables UI updates for the window, so you need to manually disable
2267 (or toggle or ...) any items which should be disabled in the menu
2270 The parameter @a menu is the menu to show.
2271 The parameter @a pos (or the parameters @a x and @a y) is the
2272 position at which to show the menu in client coordinates.
2275 The selected menu item id or @c wxID_NONE if none selected or an
2280 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, const wxPoint
& pos
);
2285 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
2288 Pops up the given menu at the specified coordinates, relative to this
2289 window, and returns control when the user has dismissed the menu.
2291 If a menu item is selected, the corresponding menu event is generated and will be
2292 processed as usually. If the coordinates are not specified, current mouse
2293 cursor position is used.
2295 @a menu is the menu to pop up.
2297 The position where the menu will appear can be specified either as a
2298 wxPoint @a pos or by two integers (@a x and @a y).
2300 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2301 ensure that the menu items are in the correct state.
2302 The menu does not get deleted by the window.
2303 It is recommended to not explicitly specify coordinates when
2304 calling PopupMenu in response to mouse click, because some of
2305 the ports (namely, wxGTK) can do a better job of positioning
2306 the menu in that case.
2310 bool PopupMenu(wxMenu
* menu
,
2311 const wxPoint
& pos
= wxDefaultPosition
);
2316 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
2327 Returns a pointer to the current validator for the window, or @NULL if
2330 virtual wxValidator
* GetValidator();
2333 Deletes the current validator (if any) and sets the window validator, having
2334 called wxValidator::Clone to create a new validator of this type.
2336 virtual void SetValidator(const wxValidator
& validator
);
2339 Transfers values from child controls to data areas specified by their
2340 validators. Returns @false if a transfer failed.
2342 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2343 the method will also call TransferDataFromWindow() of all child windows.
2345 @see TransferDataToWindow(), wxValidator, Validate()
2347 virtual bool TransferDataFromWindow();
2350 Transfers values to child controls from data areas specified by their
2353 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2354 the method will also call TransferDataToWindow() of all child windows.
2356 @return Returns @false if a transfer failed.
2358 @see TransferDataFromWindow(), wxValidator, Validate()
2360 virtual bool TransferDataToWindow();
2363 Validates the current values of the child controls using their validators.
2364 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2365 the method will also call Validate() of all child windows.
2367 @return Returns @false if any of the validations failed.
2369 @see TransferDataFromWindow(), TransferDataToWindow(),
2372 virtual bool Validate();
2378 @name wxWindow properties functions
2383 Returns the identifier of the window.
2385 @remarks Each window has an integer identifier. If the application
2386 has not provided one (or the default wxID_ANY) an unique
2387 identifier with a negative value will be generated.
2389 @see SetId(), @ref overview_windowids
2391 wxWindowID
GetId() const;
2394 Generic way of getting a label from any window, for
2395 identification purposes.
2397 @remarks The interpretation of this function differs from class to class.
2398 For frames and dialogs, the value returned is the
2399 title. For buttons or static text controls, it is the
2400 button text. This function can be useful for
2401 meta-programs (such as testing tools or special-needs
2402 access programs) which need to identify windows by name.
2404 virtual wxString
GetLabel() const;
2407 Returns the layout direction for this window,
2408 Note that @c wxLayout_Default is returned if layout direction is not supported.
2410 virtual wxLayoutDirection
GetLayoutDirection() const;
2413 Returns the window's name.
2415 @remarks This name is not guaranteed to be unique; it is up to the
2416 programmer to supply an appropriate name in the window
2417 constructor or via SetName().
2421 virtual wxString
GetName() const;
2424 Returns the value previously passed to SetWindowVariant().
2426 wxWindowVariant
GetWindowVariant() const;
2429 Sets the identifier of the window.
2431 @remarks Each window has an integer identifier. If the application has
2432 not provided one, an identifier will be generated.
2433 Normally, the identifier should be provided on creation
2434 and should not be modified subsequently.
2436 @see GetId(), @ref overview_windowids
2438 void SetId(wxWindowID winid
);
2441 Sets the window's label.
2448 virtual void SetLabel(const wxString
& label
);
2451 Sets the layout direction for this window.
2453 virtual void SetLayoutDirection(wxLayoutDirection dir
);
2456 Sets the window's name.
2459 A name to set for the window.
2463 virtual void SetName(const wxString
& name
);
2466 This function can be called under all platforms but only does anything under
2467 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2468 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2470 By default the controls use the normal size, of course, but this function can
2471 be used to change this.
2473 void SetWindowVariant(wxWindowVariant variant
);
2476 Gets the accelerator table for this window. See wxAcceleratorTable.
2478 wxAcceleratorTable
* GetAcceleratorTable();
2481 Returns the accessible object for this window, if any.
2482 See also wxAccessible.
2484 wxAccessible
* GetAccessible();
2487 Sets the accelerator table for this window. See wxAcceleratorTable.
2489 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
2492 Sets the accessible for this window. Any existing accessible for this window
2493 will be deleted first, if not identical to @e accessible.
2494 See also wxAccessible.
2496 void SetAccessible(wxAccessible
* accessible
);
2502 @name Window deletion functions
2507 This function simply generates a wxCloseEvent whose handler usually tries
2508 to close the window. It doesn't close the window itself, however.
2511 @false if the window's close handler should be able to veto the destruction
2512 of this window, @true if it cannot.
2514 @remarks Close calls the close handler for the window, providing an
2515 opportunity for the window to choose whether to destroy
2516 the window. Usually it is only used with the top level
2517 windows (wxFrame and wxDialog classes) as the others
2518 are not supposed to have any special OnClose() logic.
2519 The close handler should check whether the window is being deleted
2520 forcibly, using wxCloseEvent::CanVeto, in which case it should
2521 destroy the window using wxWindow::Destroy.
2522 Note that calling Close does not guarantee that the window will
2523 be destroyed; but it provides a way to simulate a manual close
2524 of a window, which may or may not be implemented by destroying
2525 the window. The default implementation of wxDialog::OnCloseWindow
2526 does not necessarily delete the dialog, since it will simply
2527 simulate an wxID_CANCEL event which is handled by the appropriate
2528 button event handler and may do anything at all.
2529 To guarantee that the window will be destroyed, call
2530 wxWindow::Destroy instead
2532 @see @ref overview_windowdeletion "Window Deletion Overview",
2533 Destroy(), wxCloseEvent
2535 bool Close(bool force
= false);
2538 Destroys the window safely. Use this function instead of the delete operator,
2539 since different window classes can be destroyed differently. Frames and dialogs
2540 are not destroyed immediately when this function is called -- they are added
2541 to a list of windows to be deleted on idle time, when all the window's events
2542 have been processed. This prevents problems with events being sent to
2543 non-existent windows.
2545 @return @true if the window has either been successfully deleted, or it
2546 has been added to the list of windows pending real deletion.
2548 virtual bool Destroy();
2551 Returns true if this window is in process of being destroyed.
2553 The top level windows are not deleted immediately but are rather
2554 scheduled for later destruction to give them time to process any
2555 pending messages, see Destroy() description.
2557 This function returns @true if this window, or one of its parent
2558 windows, is scheduled for destruction and can be useful to avoid
2559 manipulating it as it's usually useless to do something with a window
2560 which is on the point of disappearing anyhow.
2562 bool IsBeingDeleted() const;
2569 @name Drag and drop functions
2574 Returns the associated drop target, which may be @NULL.
2576 @see SetDropTarget(), @ref overview_dnd
2578 virtual wxDropTarget
* GetDropTarget() const;
2581 Associates a drop target with this window.
2582 If the window already has a drop target, it is deleted.
2584 @see GetDropTarget(), @ref overview_dnd
2586 virtual void SetDropTarget(wxDropTarget
* target
);
2589 Enables or disables eligibility for drop file events (OnDropFiles).
2592 If @true, the window is eligible for drop file events.
2593 If @false, the window will not accept drop file events.
2595 @remarks Windows only until version 2.8.9, available on all platforms
2596 since 2.8.10. Cannot be used together with SetDropTarget() on
2597 non-Windows platforms.
2599 @see SetDropTarget()
2601 virtual void DragAcceptFiles(bool accept
);
2607 @name Constraints, sizers and window layouting functions
2612 Return the sizer that this window is a member of, if any, otherwise @NULL.
2614 wxSizer
* GetContainingSizer() const;
2617 Return the sizer associated with the window by a previous call to
2618 SetSizer() or @NULL.
2620 wxSizer
* GetSizer() const;
2623 Sets the window to have the given layout sizer.
2625 The window will then own the object, and will take care of its deletion.
2626 If an existing layout constraints object is already owned by the
2627 window, it will be deleted if the @a deleteOld parameter is @true.
2629 Note that this function will also call SetAutoLayout() implicitly with @true
2630 parameter if the @a sizer is non-@NULL and @false otherwise so that the
2631 sizer will be effectively used to layout the window children whenever
2635 The sizer to set. Pass @NULL to disassociate and conditionally delete
2636 the window's sizer. See below.
2638 If @true (the default), this will delete any pre-existing sizer.
2639 Pass @false if you wish to handle deleting the old sizer yourself
2640 but remember to do it yourself in this case to avoid memory leaks.
2642 @remarks SetSizer enables and disables Layout automatically.
2644 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2647 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2648 window size to the size needed to accommodate all sizer elements and sets the
2649 size hints which, if this window is a top level one, prevent the user from
2650 resizing it to be less than this minimial size.
2652 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2655 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2657 wxLayoutConstraints
* GetConstraints() const;
2660 Sets the window to have the given layout constraints. The window
2661 will then own the object, and will take care of its deletion.
2662 If an existing layout constraints object is already owned by the
2663 window, it will be deleted.
2666 The constraints to set. Pass @NULL to disassociate and delete the window's
2669 @remarks You must call SetAutoLayout() to tell a window to use
2670 the constraints automatically in OnSize; otherwise, you
2671 must override OnSize and call Layout() explicitly. When
2672 setting both a wxLayoutConstraints and a wxSizer, only
2673 the sizer will have effect.
2675 void SetConstraints(wxLayoutConstraints
* constraints
);
2679 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2682 This function does not get called automatically when the window is resized
2683 because lots of windows deriving from wxWindow does not need this functionality.
2684 If you want to have Layout() called automatically, you should derive
2685 from wxPanel (see wxPanel::Layout).
2687 @see @ref overview_windowsizing
2689 virtual bool Layout();
2692 Determines whether the Layout() function will be called automatically
2693 when the window is resized.
2695 This method is called implicitly by SetSizer() but if you use SetConstraints()
2696 you should call it manually or otherwise the window layout won't be correctly
2697 updated when its size changes.
2700 Set this to @true if you wish the Layout() function to be called
2701 automatically when the window is resized.
2703 @see SetSizer(), SetConstraints()
2705 void SetAutoLayout(bool autoLayout
);
2712 @name Mouse functions
2717 Directs all mouse input to this window.
2718 Call ReleaseMouse() to release the capture.
2720 Note that wxWidgets maintains the stack of windows having captured the mouse
2721 and when the mouse is released the capture returns to the window which had had
2722 captured it previously and it is only really released if there were no previous
2723 window. In particular, this means that you must release the mouse as many times
2724 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
2726 Any application which captures the mouse in the beginning of some operation
2727 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
2728 the event. The event handler must not recapture mouse.
2730 @see ReleaseMouse(), wxMouseCaptureLostEvent
2732 void CaptureMouse();
2735 Returns the caret() associated with the window.
2737 wxCaret
* GetCaret() const;
2740 Return the cursor associated with this window.
2744 const wxCursor
& GetCursor() const;
2747 Returns @true if this window has the current mouse capture.
2749 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
2750 wxMouseCaptureChangedEvent
2752 virtual bool HasCapture() const;
2755 Releases mouse input captured with CaptureMouse().
2757 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
2758 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2760 void ReleaseMouse();
2763 Sets the caret() associated with the window.
2765 void SetCaret(wxCaret
* caret
);
2768 Sets the window's cursor. Notice that the window cursor also sets it for the
2769 children of the window implicitly.
2771 The @a cursor may be @c wxNullCursor in which case the window cursor will
2772 be reset back to default.
2775 Specifies the cursor that the window should normally display.
2777 @see ::wxSetCursor, wxCursor
2779 virtual bool SetCursor(const wxCursor
& cursor
);
2782 Moves the pointer to the given position on the window.
2784 @note This function is not supported under Mac because Apple Human
2785 Interface Guidelines forbid moving the mouse cursor programmatically.
2788 The new x position for the cursor.
2790 The new y position for the cursor.
2792 virtual void WarpPointer(int x
, int y
);
2800 @name Miscellaneous functions
2805 Does the window-specific updating after processing the update event.
2806 This function is called by UpdateWindowUI() in order to check return
2807 values in the wxUpdateUIEvent and act appropriately.
2808 For example, to allow frame and dialog title updating, wxWidgets
2809 implements this function as follows:
2812 // do the window-specific processing after processing the update event
2813 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
2815 if ( event.GetSetEnabled() )
2816 Enable(event.GetEnabled());
2818 if ( event.GetSetText() )
2820 if ( event.GetText() != GetTitle() )
2821 SetTitle(event.GetText());
2826 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
2829 Returns the platform-specific handle of the physical window.
2830 Cast it to an appropriate handle, such as @b HWND for Windows,
2831 @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
2833 virtual WXWidget
GetHandle() const;
2836 This method should be overridden to return @true if this window has
2837 multiple pages. All standard class with multiple pages such as
2838 wxNotebook, wxListbook and wxTreebook already override it to return @true
2839 and user-defined classes with similar behaviour should do it as well to
2840 allow the library to handle such windows appropriately.
2842 virtual bool HasMultiplePages() const;
2845 This function is (or should be, in case of custom controls) called during
2846 window creation to intelligently set up the window visual attributes, that is
2847 the font and the foreground and background colours.
2849 By "intelligently" the following is meant: by default, all windows use their
2850 own @ref GetClassDefaultAttributes() default attributes.
2851 However if some of the parents attributes are explicitly (that is, using
2852 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
2853 attribute hadn't been explicitly set for this window itself, then this
2854 window takes the same value as used by the parent.
2855 In addition, if the window overrides ShouldInheritColours() to return @false,
2856 the colours will not be changed no matter what and only the font might.
2858 This rather complicated logic is necessary in order to accommodate the
2859 different usage scenarios. The most common one is when all default attributes
2860 are used and in this case, nothing should be inherited as in modern GUIs
2861 different controls use different fonts (and colours) than their siblings so
2862 they can't inherit the same value from the parent. However it was also deemed
2863 desirable to allow to simply change the attributes of all children at once by
2864 just changing the font or colour of their common parent, hence in this case we
2865 do inherit the parents attributes.
2867 virtual void InheritAttributes();
2870 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
2871 to the dialog via validators.
2873 virtual void InitDialog();
2876 Returns @true if the window contents is double-buffered by the system, i.e. if
2877 any drawing done on the window is really done on a temporary backing surface
2878 and transferred to the screen all at once later.
2882 virtual bool IsDoubleBuffered() const;
2885 Returns @true if the window is retained, @false otherwise.
2887 @remarks Retained windows are only available on X platforms.
2889 virtual bool IsRetained() const;
2892 Returns @true if this window is intrinsically enabled, @false otherwise,
2893 i.e. if @ref Enable() Enable(@false) had been called. This method is
2894 mostly used for wxWidgets itself, user code should normally use
2895 IsEnabled() instead.
2897 bool IsThisEnabled() const;
2900 Returns @true if the given window is a top-level one. Currently all frames and
2901 dialogs are considered to be top-level windows (even if they have a parent
2904 virtual bool IsTopLevel() const;
2907 Disables all other windows in the application so that
2908 the user can only interact with this window.
2911 If @true, this call disables all other windows in the application so that
2912 the user can only interact with this window. If @false, the effect is
2915 virtual void MakeModal(bool modal
= true);
2918 This virtual function is normally only used internally, but
2919 sometimes an application may need it to implement functionality
2920 that should not be disabled by an application defining an OnIdle
2921 handler in a derived class.
2923 This function may be used to do delayed painting, for example,
2924 and most implementations call UpdateWindowUI()
2925 in order to send update events to the window in idle time.
2927 virtual void OnInternalIdle();
2930 Registers a system wide hotkey. Every time the user presses the hotkey
2931 registered here, this window will receive a hotkey event.
2933 It will receive the event even if the application is in the background
2934 and does not have the input focus because the user is working with some
2938 Numeric identifier of the hotkey. For applications this must be between 0
2939 and 0xBFFF. If this function is called from a shared DLL, it must be a
2940 system wide unique identifier between 0xC000 and 0xFFFF.
2941 This is a MSW specific detail.
2943 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
2944 or wxMOD_WIN specifying the modifier keys that have to be pressed along
2946 @param virtualKeyCode
2947 The virtual key code of the hotkey.
2949 @return @true if the hotkey was registered successfully. @false if some
2950 other application already registered a hotkey with this
2951 modifier/virtualKeyCode combination.
2953 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
2954 event. This function is currently only implemented
2955 under Windows. It is used in the Windows CE port for
2956 detecting hardware button presses.
2958 @see UnregisterHotKey()
2960 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
2961 int virtualKeyCode
);
2964 Unregisters a system wide hotkey.
2967 Numeric identifier of the hotkey. Must be the same id that was passed to
2970 @return @true if the hotkey was unregistered successfully, @false if the
2973 @remarks This function is currently only implemented under MSW.
2975 @see RegisterHotKey()
2977 virtual bool UnregisterHotKey(int hotkeyId
);
2980 This function sends one or more wxUpdateUIEvent to the window.
2981 The particular implementation depends on the window; for example a
2982 wxToolBar will send an update UI event for each toolbar button,
2983 and a wxFrame will send an update UI event for each menubar menu item.
2985 You can call this function from your application to ensure that your
2986 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
2987 are concerned). This may be necessary if you have called
2988 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
2989 the overhead that wxWidgets incurs by sending update UI events in idle time.
2990 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
2992 If you are calling this function from an OnInternalIdle or OnIdle
2993 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
2994 this tells the window to only update the UI elements that need
2995 to be updated in idle time. Some windows update their elements
2996 only when necessary, for example when a menu is about to be shown.
2997 The following is an example of how to call UpdateWindowUI from
3001 void MyWindow::OnInternalIdle()
3003 if (wxUpdateUIEvent::CanUpdate(this))
3004 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
3008 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
3010 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
3015 // NOTE: static functions must have their own group or Doxygen will screw
3016 // up the ordering of the member groups
3019 @name Miscellaneous static functions
3024 Returns the default font and colours which are used by the control.
3026 This is useful if you want to use the same font or colour in your own control
3027 as in a standard control -- which is a much better idea than hard coding specific
3028 colours or fonts which might look completely out of place on the users
3029 system, especially if it uses themes.
3031 The @a variant parameter is only relevant under Mac currently and is
3032 ignore under other platforms. Under Mac, it will change the size of the
3033 returned font. See SetWindowVariant() for more about this.
3035 This static method is "overridden" in many derived classes and so calling,
3036 for example, wxButton::GetClassDefaultAttributes() will typically
3037 return the values appropriate for a button which will be normally different
3038 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
3040 The @c wxVisualAttributes structure has at least the fields
3041 @c font, @c colFg and @c colBg. All of them may be invalid
3042 if it was not possible to determine the default control appearance or,
3043 especially for the background colour, if the field doesn't make sense as is
3044 the case for @c colBg for the controls with themed background.
3046 @see InheritAttributes()
3048 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
3051 Finds the window or control which currently has the keyboard focus.
3053 @remarks Note that this is a static function, so it can be called without
3054 needing a wxWindow pointer.
3056 @see SetFocus(), HasFocus()
3058 static wxWindow
* FindFocus();
3061 Find the first window with the given @e id.
3063 If @a parent is @NULL, the search will start from all top-level frames
3064 and dialog boxes; if non-@NULL, the search will be limited to the given
3066 The search is recursive in both cases.
3070 static wxWindow
* FindWindowById(long id
, const wxWindow
* parent
= 0);
3073 Find a window by its label.
3075 Depending on the type of window, the label may be a window title
3076 or panel item label. If @a parent is @NULL, the search will start from all
3077 top-level frames and dialog boxes; if non-@NULL, the search will be
3078 limited to the given window hierarchy.
3079 The search is recursive in both cases.
3083 static wxWindow
* FindWindowByLabel(const wxString
& label
,
3084 const wxWindow
* parent
= 0);
3087 Find a window by its name (as given in a window constructor or Create()
3090 If @a parent is @NULL, the search will start from all top-level frames
3091 and dialog boxes; if non-@NULL, the search will be limited to the given
3094 The search is recursive in both cases. If no window with such name is found,
3095 FindWindowByLabel() is called.
3099 static wxWindow
* FindWindowByName(const wxString
& name
,
3100 const wxWindow
* parent
= 0);
3103 Returns the currently captured window.
3105 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
3106 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3108 static wxWindow
* GetCapture();
3111 Create a new ID or range of IDs that are not currently in use.
3112 The IDs will be reserved until assigned to a wxWindow ID
3113 or unreserved with UnreserveControlId().
3115 See @ref overview_windowids for more information.
3118 The number of sequential IDs to reserve.
3120 @return Returns the ID or the first ID of the range, or wxID_NONE if the
3121 specified number of identifiers couldn't be allocated.
3123 @see UnreserveControlId(), wxIdManager,
3124 @ref overview_windowids
3126 static wxWindowID
NewControlId(int count
= 1);
3129 Unreserve an ID or range of IDs that was reserved by NewControlId().
3130 See @ref overview_windowids for more information.
3133 The starting ID of the range of IDs to unreserve.
3135 The number of sequential IDs to unreserve.
3137 @see NewControlId(), wxIdManager, @ref overview_windowids
3139 static void UnreserveControlId(wxWindowID id
, int count
= 1);
3148 Gets the size which best suits the window: for a control, it would be
3149 the minimal size which doesn't truncate the control, for a panel - the
3150 same size as it would have after a call to Fit().
3152 The default implementation of this function is designed for use in container
3153 windows, such as wxPanel, and works something like this:
3154 -# If the window has a sizer then it is used to calculate the best size.
3155 -# Otherwise if the window has layout constraints then those are used to
3156 calculate the best size.
3157 -# Otherwise if the window has children then the best size is set to be large
3158 enough to show all the children.
3159 -# Otherwise if there are no children then the window's minimal size will be
3160 used as its best size.
3161 -# Otherwise if there is no minimal size set, then the current size is used
3164 @see @ref overview_windowsizing
3166 virtual wxSize
DoGetBestSize() const;
3170 Sets the initial window size if none is given (i.e. at least one of the
3171 components of the size passed to ctor/Create() is wxDefaultCoord).
3172 @deprecated @todo provide deprecation description
3174 virtual void SetInitialBestSize(const wxSize
& size
);
3177 Generate wxWindowDestroyEvent for this window.
3179 This is called by the window itself when it is being destroyed and
3180 usually there is no need to call it but see wxWindowDestroyEvent for
3181 explanations of when you might want to do it.
3183 void SendDestroyEvent();
3186 This function is public in wxEvtHandler but protected in wxWindow
3187 because for wxWindows you should always call ProcessEvent() on the
3188 pointer returned by GetEventHandler() and not on the wxWindow object
3191 For convenience, a ProcessWindowEvent() method is provided as a synonym
3192 for @code GetEventHandler()->ProcessEvent() @endcode.
3194 Note that it's still possible to call these functions directly on the
3195 wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
3196 create subtle bugs when windows with event handlers pushed on them are
3199 This holds also for all other wxEvtHandler functions.
3201 virtual bool ProcessEvent(wxEvent
& event
);
3205 See ProcessEvent() for more info about why you shouldn't use this function
3206 and the reason for making this function protected in wxWindow.
3208 bool SafelyProcessEvent(wxEvent
& event
);
3209 virtual void QueueEvent(wxEvent
*event
);
3210 virtual void AddPendingEvent(const wxEvent
& event
);
3211 void ProcessPendingEvents();
3212 bool ProcessThreadEvent(const wxEvent
& event
);
3218 // ============================================================================
3219 // Global functions/macros
3220 // ============================================================================
3222 /** @addtogroup group_funcmacro_misc */
3226 Find the deepest window at the mouse pointer position, returning the window
3227 and current pointer position in screen coordinates.
3229 @header{wx/window.h}
3231 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
3234 Gets the currently active window (implemented for MSW and GTK only
3235 currently, always returns @NULL in the other ports).
3237 @header{wx/window.h}
3239 wxWindow
* wxGetActiveWindow();
3242 Returns the first top level parent of the given window, or in other words,
3243 the frame or dialog containing it, or @NULL.
3245 @header{wx/window.h}
3247 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);