1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
16 No effect, equivalent to normal wxWindow::Show() or Hide() call.
22 /// Roll window to the left
23 wxSHOW_EFFECT_ROLL_TO_LEFT
,
25 /// Roll window to the right
26 wxSHOW_EFFECT_ROLL_TO_RIGHT
,
28 /// Roll window to the top
29 wxSHOW_EFFECT_ROLL_TO_TOP
,
31 /// Roll window to the bottom
32 wxSHOW_EFFECT_ROLL_TO_BOTTOM
,
34 /// Slide window to the left
35 wxSHOW_EFFECT_SLIDE_TO_LEFT
,
37 /// Slide window to the right
38 wxSHOW_EFFECT_SLIDE_TO_RIGHT
,
40 /// Slide window to the top
41 wxSHOW_EFFECT_SLIDE_TO_TOP
,
43 /// Slide window to the bottom
44 wxSHOW_EFFECT_SLIDE_TO_BOTTOM
,
46 /// Fade in or out effect
49 /// Expanding or collapsing effect
58 Struct containing all the visual attributes of a control.
60 struct wxVisualAttributes
62 /// The font used for control label/text inside it.
65 /// The foreground colour.
69 The background colour.
71 May be wxNullColour if the controls background colour is not solid.
78 Different window variants, on platforms like eg mac uses different
83 wxWINDOW_VARIANT_NORMAL
, //!< Normal size
84 wxWINDOW_VARIANT_SMALL
, //!< Smaller size (about 25 % smaller than normal)
85 wxWINDOW_VARIANT_MINI
, //!< Mini size (about 33 % smaller than normal)
86 wxWINDOW_VARIANT_LARGE
, //!< Large size (about 25 % larger than normal)
94 wxWindow is the base class for all windows and represents any visible object
95 on screen. All controls, top level windows and so on are windows. Sizers and
96 device contexts are not, however, as they don't appear on screen themselves.
98 Please note that all children of the window will be deleted automatically by
99 the destructor before the window itself is deleted which means that you don't
100 have to worry about deleting them manually. Please see the @ref
101 overview_windowdeletion "window deletion overview" for more information.
103 Also note that in this, and many others, wxWidgets classes some
104 @c GetXXX() methods may be overloaded (as, for example,
105 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
106 are non-virtual because having multiple virtual functions with the same name
107 results in a virtual function name hiding at the derived class level (in
108 English, this means that the derived class has to override all overloaded
109 variants if it overrides any of them). To allow overriding them in the derived
110 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
111 and all @c GetXXX() ones are forwarded to it, so overriding the former
112 changes the behaviour of the latter.
115 @style{wxBORDER_DEFAULT}
116 The window class will decide the kind of border to show, if any.
117 @style{wxBORDER_SIMPLE}
118 Displays a thin border around the window. wxSIMPLE_BORDER is the
119 old name for this style.
120 @style{wxBORDER_SUNKEN}
121 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
123 @style{wxBORDER_RAISED}
124 Displays a raised border. wxRAISED_BORDER is the old name for this
126 @style{wxBORDER_STATIC}
127 Displays a border suitable for a static control. wxSTATIC_BORDER
128 is the old name for this style. Windows only.
129 @style{wxBORDER_THEME}
130 Displays a native border suitable for a control, on the current
131 platform. On Windows XP or Vista, this will be a themed border; on
132 most other platforms a sunken border will be used. For more
133 information for themed borders on Windows, please see Themed
135 @style{wxBORDER_NONE}
136 Displays no border, overriding the default border style for the
137 window. wxNO_BORDER is the old name for this style.
138 @style{wxBORDER_DOUBLE}
139 This style is obsolete and should not be used.
140 @style{wxTRANSPARENT_WINDOW}
141 The window is transparent, that is, it will not receive paint
142 events. Windows only.
143 @style{wxTAB_TRAVERSAL}
144 Use this to enable tab traversal for non-dialog windows.
145 @style{wxWANTS_CHARS}
146 Use this to indicate that the window wants to get all char/key
147 events for all keys - even for keys like TAB or ENTER which are
148 usually used for dialog navigation and which wouldn't be generated
149 without this style. If you need to use this style in order to get
150 the arrows or etc., but would still like to have normal keyboard
151 navigation take place, you should call Navigate in response to the
152 key events for Tab and Shift-Tab.
153 @style{wxNO_FULL_REPAINT_ON_RESIZE}
154 On Windows, this style used to disable repainting the window
155 completely when its size is changed. Since this behaviour is now
156 the default, the style is now obsolete and no longer has an effect.
158 Use this style to enable a vertical scrollbar. Notice that this
159 style cannot be used with native controls which don't support
160 scrollbars nor with top-level windows in most ports.
162 Use this style to enable a horizontal scrollbar. The same
163 limitations as for wxVSCROLL apply to this style.
164 @style{wxALWAYS_SHOW_SB}
165 If a window has scrollbars, disable them instead of hiding them
166 when they are not needed (i.e. when the size of the window is big
167 enough to not require the scrollbars to navigate it). This style is
168 currently implemented for wxMSW, wxGTK and wxUniversal and does
169 nothing on the other platforms.
170 @style{wxCLIP_CHILDREN}
171 Use this style to eliminate flicker caused by the background being
172 repainted, then children being painted over them. Windows only.
173 @style{wxFULL_REPAINT_ON_RESIZE}
174 Use this style to force a complete redraw of the window whenever it
175 is resized instead of redrawing just the part of the window
176 affected by resizing. Note that this was the behaviour by default
177 before 2.5.1 release and that if you experience redraw problems
178 with code which previously used to work you may want to try this.
179 Currently this style applies on GTK+ 2 and Windows only, and full
180 repainting is always done on other platforms.
183 @beginExtraStyleTable
184 @style{wxWS_EX_VALIDATE_RECURSIVELY}
185 By default, wxWindow::Validate(), wxWindow::TransferDataTo() and
186 wxWindow::TransferDataFromWindow() only work on
187 direct children of the window (compatible behaviour).
188 Set this flag to make them recursively descend into all subwindows.
189 @style{wxWS_EX_BLOCK_EVENTS}
190 wxCommandEvents and the objects of the derived classes are
191 forwarded to the parent window and so on recursively by default.
192 Using this flag for the given window allows to block this
193 propagation at this window, i.e. prevent the events from being
194 propagated further upwards. Dialogs have this flag on by default
195 for the reasons explained in the @ref overview_events.
196 @style{wxWS_EX_TRANSIENT}
197 Don't use this window as an implicit parent for the other windows:
198 this must be used with transient windows as otherwise there is the
199 risk of creating a dialog/frame with this window as a parent, which
200 would lead to a crash if the parent were destroyed before the child.
201 @style{wxWS_EX_CONTEXTHELP}
202 Under Windows, puts a query button on the caption. When pressed,
203 Windows will go into a context-sensitive help mode and wxWidgets
204 will send a @c wxEVT_HELP event if the user clicked on an application window.
205 This style cannot be used (because of the underlying native behaviour)
206 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
207 are automatically turned off if this one is used.
208 @style{wxWS_EX_PROCESS_IDLE}
209 This window should always process idle events, even if the mode set
210 by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED.
211 @style{wxWS_EX_PROCESS_UI_UPDATES}
212 This window should always process UI update events, even if the
213 mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED.
216 @beginEventEmissionTable
217 @event{EVT_ACTIVATE(id, func)}
218 Process a @c wxEVT_ACTIVATE event. See wxActivateEvent.
219 @event{EVT_CHILD_FOCUS(func)}
220 Process a @c wxEVT_CHILD_FOCUS event. See wxChildFocusEvent.
221 @event{EVT_CONTEXT_MENU(func)}
222 A right click (or other context menu command depending on platform) has been detected.
223 See wxContextMenuEvent.
224 @event{EVT_HELP(id, func)}
225 Process a @c wxEVT_HELP event. See wxHelpEvent.
226 @event{EVT_HELP_RANGE(id1, id2, func)}
227 Process a @c wxEVT_HELP event for a range of ids. See wxHelpEvent.
228 @event{EVT_DROP_FILES(func)}
229 Process a @c wxEVT_DROP_FILES event. See wxDropFilesEvent.
230 @event{EVT_ERASE_BACKGROUND(func)}
231 Process a @c wxEVT_ERASE_BACKGROUND event. See wxEraseEvent.
232 @event{EVT_SET_FOCUS(func)}
233 Process a @c wxEVT_SET_FOCUS event. See wxFocusEvent.
234 @event{EVT_KILL_FOCUS(func)}
235 Process a @c wxEVT_KILL_FOCUS event. See wxFocusEvent.
236 @event{EVT_IDLE(func)}
237 Process a @c wxEVT_IDLE event. See wxIdleEvent.
238 @event{EVT_JOY_*(func)}
239 Processes joystick events. See wxJoystickEvent.
240 @event{EVT_KEY_DOWN(func)}
241 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
243 @event{EVT_KEY_UP(func)}
244 Process a @c wxEVT_KEY_UP event (any key has been released).
246 @event{EVT_CHAR(func)}
247 Process a @c wxEVT_CHAR event.
249 @event{EVT_CHAR_HOOK(func)}
250 Process a @c wxEVT_CHAR_HOOK event.
252 @event{EVT_MOUSE_CAPTURE_LOST(func)}
253 Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
254 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
255 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. See wxMouseCaptureChangedEvent.
256 @event{EVT_MOUSE_*(func)}
258 @event{EVT_PAINT(func)}
259 Process a @c wxEVT_PAINT event. See wxPaintEvent.
260 @event{EVT_POWER_*(func)}
261 The system power state changed. See wxPowerEvent.
262 @event{EVT_SCROLLWIN_*(func)}
263 Process scroll events. See wxScrollWinEvent.
264 @event{EVT_SET_CURSOR(func)}
265 Process a @c wxEVT_SET_CURSOR event. See wxSetCursorEvent.
266 @event{EVT_SIZE(func)}
267 Process a @c wxEVT_SIZE event. See wxSizeEvent.
268 @event{EVT_SYS_COLOUR_CHANGED(func)}
269 Process a @c wxEVT_SYS_COLOUR_CHANGED event. See wxSysColourChangedEvent.
275 @see @ref overview_events, @ref overview_windowsizing
277 class wxWindow
: public wxEvtHandler
286 Constructs a window, which can be a child of a frame, dialog or any other
290 Pointer to a parent window.
292 Window identifier. If wxID_ANY, will automatically create an identifier.
294 Window position. wxDefaultPosition indicates that wxWidgets
295 should generate a default position for the window.
296 If using the wxWindow class directly, supply an actual position.
298 Window size. wxDefaultSize indicates that wxWidgets should generate
299 a default size for the window. If no suitable size can be found, the
300 window will be sized to 20x20 pixels so that the window is visible but
301 obviously not correctly sized.
303 Window style. For generic window styles, please see wxWindow.
307 wxWindow(wxWindow
* parent
, wxWindowID id
,
308 const wxPoint
& pos
= wxDefaultPosition
,
309 const wxSize
& size
= wxDefaultSize
,
311 const wxString
& name
= wxPanelNameStr
);
316 Deletes all sub-windows, then deletes itself. Instead of using
317 the @b delete operator explicitly, you should normally use Destroy()
318 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
320 @see @ref overview_windowdeletion "Window Deletion Overview",
321 Destroy(), wxCloseEvent
326 bool Create(wxWindow
*parent
,
328 const wxPoint
& pos
= wxDefaultPosition
,
329 const wxSize
& size
= wxDefaultSize
,
331 const wxString
& name
= wxPanelNameStr
);
334 @name Focus functions
336 See also the static function FindFocus().
341 This method may be overridden in the derived classes to return @false to
342 indicate that this control doesn't accept input at all (i.e. behaves like
343 e.g. wxStaticText) and so doesn't need focus.
345 @see AcceptsFocusFromKeyboard()
347 virtual bool AcceptsFocus() const;
350 This method may be overridden in the derived classes to return @false to
351 indicate that while this control can, in principle, have focus if the user
352 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
353 when using the keyboard.
355 virtual bool AcceptsFocusFromKeyboard() const;
358 Overridden to indicate whether this window or one of its children accepts
359 focus. Usually it's the same as AcceptsFocus() but is overridden for
362 virtual bool AcceptsFocusRecursively() const;
365 Can this window itself have focus?
367 bool IsFocusable() const;
370 Can this window have focus right now?
372 If this method returns true, it means that calling SetFocus() will
373 put focus either to this window or one of its children, if you need
374 to know whether this window accepts focus itself, use IsFocusable()
376 bool CanAcceptFocus() const;
379 Can this window be assigned focus from keyboard right now?
381 bool CanAcceptFocusFromKeyboard() const;
385 Returns @true if the window (or in case of composite controls, its main
386 child window) has focus.
390 virtual bool HasFocus() const;
393 This method is only implemented by ports which have support for
394 native TAB traversal (such as GTK+ 2.0).
396 It is called by wxWidgets' container control code to give the native
397 system a hint when doing TAB traversal. A call to this does not disable
398 or change the effect of programmatically calling SetFocus().
400 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
402 virtual void SetCanFocus(bool canFocus
);
405 This sets the window to receive keyboard input.
407 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
408 wxPanel::SetFocusIgnoringChildren
410 virtual void SetFocus();
413 This function is called by wxWidgets keyboard navigation code when the user
414 gives the focus to this window from keyboard (e.g. using @c TAB key).
416 By default this method simply calls SetFocus() but
417 can be overridden to do something in addition to this in the derived classes.
419 virtual void SetFocusFromKbd();
425 @name Child management functions
430 Adds a child window. This is called automatically by window creation
431 functions so should not be required by the application programmer.
432 Notice that this function is mostly internal to wxWidgets and shouldn't be
433 called by the user code.
438 virtual void AddChild(wxWindow
* child
);
441 Destroys all children of a window. Called automatically by the destructor.
443 bool DestroyChildren();
446 Find a child of this window, by @a id.
447 May return @a this if it matches itself.
449 wxWindow
* FindWindow(long id
) const;
452 Find a child of this window, by name.
453 May return @a this if it matches itself.
455 wxWindow
* FindWindow(const wxString
& name
) const;
458 Returns a reference to the list of the window's children. @c wxWindowList
459 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
461 wxWindowList
& GetChildren();
466 const wxWindowList
& GetChildren() const;
469 Removes a child window.
471 This is called automatically by window deletion functions so should not
472 be required by the application programmer.
473 Notice that this function is mostly internal to wxWidgets and shouldn't be
474 called by the user code.
477 Child window to remove.
479 virtual void RemoveChild(wxWindow
* child
);
485 @name Sibling and parent management functions
490 Returns the grandparent of a window, or @NULL if there isn't one.
492 wxWindow
* GetGrandParent() const;
495 Returns the next window after this one among the parent's children or @NULL
496 if this window is the last child.
500 @see GetPrevSibling()
502 wxWindow
* GetNextSibling() const;
505 Returns the parent of the window, or @NULL if there is no parent.
507 wxWindow
* GetParent() const;
510 Returns the previous window before this one among the parent's children or @c
511 @NULL if this window is the first child.
515 @see GetNextSibling()
517 wxWindow
* GetPrevSibling() const;
520 Check if the specified window is a descendant of this one.
522 Returns @true if the window is a descendant (i.e. a child or
523 grand-child or grand-grand-child or ...) of this one.
525 Notice that a window can never be a descendant of another one if they
526 are in different top level windows, i.e. a child of a wxDialog is not
527 considered to be a descendant of dialogs parent wxFrame.
529 @param win Any window, possible @NULL (@false is always returned then).
533 bool IsDescendant(wxWindowBase
* win
) const;
536 Reparents the window, i.e. the window will be removed from its
537 current parent window (e.g. a non-standard toolbar in a wxFrame)
538 and then re-inserted into another.
540 Notice that currently you need to explicitly call
541 wxNotebook::RemovePage() before reparenting a notebook page.
546 virtual bool Reparent(wxWindow
* newParent
);
552 @name Scrolling and scrollbars functions
554 Note that these methods don't work with native controls which don't use
555 wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
560 Call this function to force one or both scrollbars to be always shown, even if
561 the window is big enough to show its entire contents without scrolling.
566 Whether the horizontal scroll bar should always be visible.
568 Whether the vertical scroll bar should always be visible.
570 @remarks This function is currently only implemented under Mac/Carbon.
572 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
575 Returns the built-in scrollbar position.
579 virtual int GetScrollPos(int orientation
) const;
582 Returns the built-in scrollbar range.
586 virtual int GetScrollRange(int orientation
) const;
589 Returns the built-in scrollbar thumb size.
593 virtual int GetScrollThumb(int orientation
) const;
596 Returns @true if this window can have a scroll bar in this orientation.
599 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
603 bool CanScroll(int orient
) const;
606 Returns @true if this window currently has a scroll bar for this
609 This method may return @false even when CanScroll() for the same
610 orientation returns @true, but if CanScroll() returns @false, i.e.
611 scrolling in this direction is not enabled at all, HasScrollbar()
612 always returns @false as well.
615 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
617 bool HasScrollbar(int orient
) const;
620 Return whether a scrollbar is always shown.
623 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
625 @see AlwaysShowScrollbars()
627 virtual bool IsScrollbarAlwaysShown(int orient
) const;
630 Scrolls the window by the given number of lines down (if @a lines is
633 @return Returns @true if the window was scrolled, @false if it was already
634 on top/bottom and nothing was done.
636 @remarks This function is currently only implemented under MSW and
637 wxTextCtrl under wxGTK (it also works for wxScrolled classes
638 under all platforms).
642 virtual bool ScrollLines(int lines
);
645 Scrolls the window by the given number of pages down (if @a pages is
648 @return Returns @true if the window was scrolled, @false if it was already
649 on top/bottom and nothing was done.
651 @remarks This function is currently only implemented under MSW and wxGTK.
655 virtual bool ScrollPages(int pages
);
658 Physically scrolls the pixels in the window and move child windows accordingly.
661 Amount to scroll horizontally.
663 Amount to scroll vertically.
665 Rectangle to scroll, if it is @NULL, the whole window is
666 scrolled (this is always the case under wxGTK which doesn't support this
669 @remarks Note that you can often use wxScrolled instead of using this
672 virtual void ScrollWindow(int dx
, int dy
,
673 const wxRect
* rect
= NULL
);
676 Same as #ScrollLines (-1).
681 Same as #ScrollLines (1).
686 Same as #ScrollPages (-1).
691 Same as #ScrollPages (1).
696 Sets the position of one of the built-in scrollbars.
699 Determines the scrollbar whose position is to be set.
700 May be wxHORIZONTAL or wxVERTICAL.
702 Position in scroll units.
704 @true to redraw the scrollbar, @false otherwise.
706 @remarks This function does not directly affect the contents of the
707 window: it is up to the application to take note of
708 scrollbar attributes and redraw contents accordingly.
710 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
713 virtual void SetScrollPos(int orientation
, int pos
,
714 bool refresh
= true);
717 Sets the scrollbar properties of a built-in scrollbar.
720 Determines the scrollbar whose page size is to be set.
721 May be wxHORIZONTAL or wxVERTICAL.
723 The position of the scrollbar in scroll units.
725 The size of the thumb, or visible portion of the scrollbar, in scroll units.
727 The maximum position of the scrollbar. Value of -1 can be used to
728 ask for the scrollbar to be shown but in the disabled state: this
729 can be used to avoid removing the scrollbar even when it is not
730 needed (currently this is only implemented in wxMSW port).
732 @true to redraw the scrollbar, @false otherwise.
735 Let's say you wish to display 50 lines of text, using the same font.
736 The window is sized so that you can only see 16 lines at a time.
739 SetScrollbar(wxVERTICAL, 0, 16, 50);
741 Note that with the window at this size, the thumb position can never
742 go above 50 minus 16, or 34. You can determine how many lines are
743 currently visible by dividing the current view size by the character
745 When defining your own scrollbar behaviour, you will always need
746 to recalculate the scrollbar settings when the window size changes.
747 You could therefore put your scrollbar calculations and SetScrollbar
748 call into a function named AdjustScrollbars, which can be called
749 initially and also from your wxSizeEvent handler function.
751 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
753 virtual void SetScrollbar(int orientation
, int position
,
754 int thumbSize
, int range
,
755 bool refresh
= true);
760 @name Sizing functions
762 See also the protected functions DoGetBestSize() and
763 DoGetBestClientSize().
768 Sets the cached best size value.
772 void CacheBestSize(const wxSize
& size
) const;
775 Converts client area size @a size to corresponding window size.
777 In other words, the returned value is what would GetSize() return if this
778 window had client area of given size. Components with wxDefaultCoord
779 value are left unchanged. Note that the conversion is not always
780 exact, it assumes that non-client area doesn't change and so doesn't
781 take into account things like menu bar (un)wrapping or (dis)appearance
786 @see WindowToClientSize()
788 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
791 Converts window size @a size to corresponding client area size
792 In other words, the returned value is what would GetClientSize() return if
793 this window had given window size. Components with wxDefaultCoord value
796 Note that the conversion is not always exact, it assumes that
797 non-client area doesn't change and so doesn't take into account things
798 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
802 @see ClientToWindowSize()
804 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
807 Sizes the window so that it fits around its subwindows.
809 This function won't do anything if there are no subwindows and will only really
810 work correctly if sizers are used for the subwindows layout.
812 Also, if the window has exactly one subwindow it is better (faster and the result
813 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
817 window->SetClientSize(child->GetSize());
820 instead of calling Fit().
822 @see @ref overview_windowsizing
827 Similar to Fit(), but sizes the interior (virtual) size of a window.
829 Mainly useful with scrolled windows to reset scrollbars after sizing
830 changes that do not trigger a size event, and/or scrolled windows without
831 an interior sizer. This function similarly won't do anything if there are
834 virtual void FitInside();
837 This functions returns the best acceptable minimal size for the window.
839 For example, for a static control, it will be the minimal size such that the
840 control label is not truncated. For windows containing subwindows (typically
841 wxPanel), the size returned by this function will be the same as the size
842 the window would have had after calling Fit().
844 Override virtual DoGetBestSize() or, better, because it's usually more
845 convenient, DoGetBestClientSize() when writing your own custom window
846 class to change the value returned by this public non-virtual method.
848 Notice that the best size respects the minimal and maximal size
849 explicitly set for the window, if any. So even if some window believes
850 that it needs 200 pixels horizontally, calling SetMaxSize() with a
851 width of 100 would ensure that GetBestSize() returns the width of at
854 @see CacheBestSize(), @ref overview_windowsizing
856 wxSize
GetBestSize() const;
859 Returns the best height needed by this window if it had the given width.
861 @see DoGetBestClientHeight()
865 int GetBestHeight(int width
) const;
868 Returns the best width needed by this window if it had the given height.
870 @see DoGetBestClientWidth()
874 int GetBestWidth(int height
) const;
877 Returns the size of the window 'client area' in pixels.
879 The client area is the area which may be drawn on by the programmer,
880 excluding title bar, border, scrollbars, etc.
881 Note that if this window is a top-level one and it is currently minimized, the
882 return size is empty (both width and height are 0).
885 In wxPerl this method takes no parameters and returns
886 a 2-element list (width, height).
889 @see GetSize(), GetVirtualSize()
891 void GetClientSize(int* width
, int* height
) const;
896 wxSize
GetClientSize() const;
899 Merges the window's best size into the min size and returns the result.
900 This is the value used by sizers to determine the appropriate
901 amount of space to allocate for the widget.
903 This is the method called by a wxSizer when it queries the size
904 of a window or control.
906 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
908 virtual wxSize
GetEffectiveMinSize() const;
911 Returns the maximum size of window's client area.
913 This is an indication to the sizer layout mechanism that this is the maximum
914 possible size as well as the upper bound on window's size settable using
917 @see GetMaxSize(), @ref overview_windowsizing
919 virtual wxSize
GetMaxClientSize() const;
922 Returns the maximum size of the window.
924 This is an indication to the sizer layout mechanism that this is the maximum
925 possible size as well as the upper bound on window's size settable using SetSize().
927 @see GetMaxClientSize(), @ref overview_windowsizing
929 virtual wxSize
GetMaxSize() const;
932 Returns the minimum size of window's client area, an indication to the sizer
933 layout mechanism that this is the minimum required size of its client area.
935 It normally just returns the value set by SetMinClientSize(), but it can be
936 overridden to do the calculation on demand.
938 @see GetMinSize(), @ref overview_windowsizing
940 virtual wxSize
GetMinClientSize() const;
943 Returns the minimum size of the window, an indication to the sizer layout
944 mechanism that this is the minimum required size.
946 This method normally just returns the value set by SetMinSize(), but it
947 can be overridden to do the calculation on demand.
949 @see GetMinClientSize(), @ref overview_windowsizing
951 virtual wxSize
GetMinSize() const;
953 int GetMinWidth() const;
954 int GetMinHeight() const;
955 int GetMaxWidth() const;
956 int GetMaxHeight() const;
959 Returns the size of the entire window in pixels, including title bar, border,
962 Note that if this window is a top-level one and it is currently minimized, the
963 returned size is the restored window size, not the size of the window icon.
966 Receives the window width.
968 Receives the window height.
971 In wxPerl this method is implemented as GetSizeWH() returning
972 a 2-element list (width, height).
975 @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
977 void GetSize(int* width
, int* height
) const;
980 See the GetSize(int*,int*) overload for more info.
982 wxSize
GetSize() const;
985 This gets the virtual size of the window in pixels.
986 By default it returns the client size of the window, but after a call to
987 SetVirtualSize() it will return the size set with that method.
989 @see @ref overview_windowsizing
991 wxSize
GetVirtualSize() const;
994 Like the other GetVirtualSize() overload but uses pointers instead.
997 Receives the window virtual width.
999 Receives the window virtual height.
1001 void GetVirtualSize(int* width
, int* height
) const;
1004 Return the largest of ClientSize and BestSize (as determined
1005 by a sizer, interior children, or other means)
1007 virtual wxSize
GetBestVirtualSize() const;
1010 Returns the size of the left/right and top/bottom borders of this window in x
1011 and y components of the result respectively.
1013 virtual wxSize
GetWindowBorderSize() const;
1016 wxSizer and friends use this to give a chance to a component to recalc
1017 its min size once one of the final size components is known. Override
1018 this function when that is useful (such as for wxStaticText which can
1019 stretch over several lines). Parameter availableOtherDir
1020 tells the item how much more space there is available in the opposite
1021 direction (-1 if unknown).
1024 InformFirstDirection(int direction
,
1026 int availableOtherDir
);
1029 Resets the cached best size value so it will be recalculated the next time it
1032 @see CacheBestSize()
1034 void InvalidateBestSize();
1037 Posts a size event to the window.
1039 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
1041 void PostSizeEvent();
1044 Posts a size event to the parent of this window.
1046 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
1049 void PostSizeEventToParent();
1052 This function sends a dummy @ref wxSizeEvent "size event" to
1053 the window allowing it to re-layout its children positions.
1055 It is sometimes useful to call this function after adding or deleting a
1056 children after the frame creation or if a child size changes. Note that
1057 if the frame is using either sizers or constraints for the children
1058 layout, it is enough to call wxWindow::Layout() directly and this
1059 function should not be used in this case.
1061 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
1062 the event, i.e. schedules it for later processing, instead of
1063 dispatching it directly. You can also use PostSizeEvent() as a more
1064 readable equivalent of calling this function with this flag.
1067 May include @c wxSEND_EVENT_POST. Default value is 0.
1069 virtual void SendSizeEvent(int flags
= 0);
1072 Safe wrapper for GetParent()->SendSizeEvent().
1074 This function simply checks that the window has a valid parent which is
1075 not in process of being deleted and calls SendSizeEvent() on it. It is
1076 used internally by windows such as toolbars changes to whose state
1077 should result in parent re-layout (e.g. when a toolbar is added to the
1078 top of the window, all the other windows must be shifted down).
1080 @see PostSizeEventToParent()
1083 See description of this parameter in SendSizeEvent() documentation.
1085 void SendSizeEventToParent(int flags
= 0);
1088 This sets the size of the window client area in pixels.
1090 Using this function to size a window tends to be more device-independent
1091 than SetSize(), since the application need not worry about what dimensions
1092 the border or title bar have when trying to fit the window around panel
1095 @see @ref overview_windowsizing
1097 void SetClientSize(int width
, int height
);
1102 void SetClientSize(const wxSize
& size
);
1107 void SetClientSize(const wxRect
& rect
);
1110 This normally does not need to be called by user code.
1111 It is called when a window is added to a sizer, and is used so the window
1112 can remove itself from the sizer when it is destroyed.
1114 void SetContainingSizer(wxSizer
* sizer
);
1117 A @e smart SetSize that will fill in default size components with the
1118 window's @e best size values.
1120 Also sets the window's minsize to the value passed in for use with sizers.
1121 This means that if a full or partial size is passed to this function then
1122 the sizers will use that size instead of the results of GetBestSize() to
1123 determine the minimum needs of the window for layout.
1125 Most controls will use this to set their initial size, and their min
1126 size to the passed in value (if any.)
1128 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
1129 @ref overview_windowsizing
1131 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
1134 Sets the maximum client size of the window, to indicate to the sizer
1135 layout mechanism that this is the maximum possible size of its client area.
1137 Note that this method is just a shortcut for:
1139 SetMaxSize(ClientToWindowSize(size));
1142 @see SetMaxSize(), @ref overview_windowsizing
1144 virtual void SetMaxClientSize(const wxSize
& size
);
1147 Sets the maximum size of the window, to indicate to the sizer layout mechanism
1148 that this is the maximum possible size.
1150 @see SetMaxClientSize(), @ref overview_windowsizing
1152 virtual void SetMaxSize(const wxSize
& size
);
1155 Sets the minimum client size of the window, to indicate to the sizer
1156 layout mechanism that this is the minimum required size of window's client
1159 You may need to call this if you change the window size after
1160 construction and before adding to its parent sizer.
1162 Note, that just as with SetMinSize(), calling this method doesn't
1163 prevent the program from explicitly making the window smaller than the
1166 Note that this method is just a shortcut for:
1168 SetMinSize(ClientToWindowSize(size));
1171 @see SetMinSize(), @ref overview_windowsizing
1173 virtual void SetMinClientSize(const wxSize
& size
);
1176 Sets the minimum size of the window, to indicate to the sizer layout
1177 mechanism that this is the minimum required size.
1179 You may need to call this if you change the window size after
1180 construction and before adding to its parent sizer.
1182 Notice that calling this method doesn't prevent the program from making
1183 the window explicitly smaller than the specified size by calling
1184 SetSize(), it just ensures that it won't become smaller than this size
1185 during the automatic layout.
1187 @see SetMinClientSize(), @ref overview_windowsizing
1189 virtual void SetMinSize(const wxSize
& size
);
1192 Sets the size of the window in pixels.
1195 Required x position in pixels, or wxDefaultCoord to indicate that the
1196 existing value should be used.
1198 Required y position in pixels, or wxDefaultCoord to indicate that the
1199 existing value should be used.
1201 Required width in pixels, or wxDefaultCoord to indicate that the existing
1202 value should be used.
1204 Required height position in pixels, or wxDefaultCoord to indicate that the
1205 existing value should be used.
1207 Indicates the interpretation of other parameters.
1208 It is a bit list of the following:
1209 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
1210 a wxWidgets-supplied default width.
1211 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
1212 a wxWidgets-supplied default height.
1213 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1214 a wxWidgets-supplied default size.
1215 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1216 if wxDefaultCoord values are supplied.
1217 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1218 wxDefaultCoord) to be interpreted as real
1219 dimensions, not default values.
1220 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1221 already the same as the parameters of this function,
1222 nothing is done. but with this flag a window resize may
1223 be forced even in this case (supported in wx 2.6.2 and
1224 later and only implemented for MSW and ignored elsewhere
1227 @remarks This overload sets the position and optionally size, of the window.
1228 Parameters may be wxDefaultCoord to indicate either that a default
1229 should be supplied by wxWidgets, or that the current value of the
1230 dimension should be used.
1232 @see Move(), @ref overview_windowsizing
1234 void SetSize(int x
, int y
, int width
, int height
,
1235 int sizeFlags
= wxSIZE_AUTO
);
1238 Sets the size of the window in pixels.
1239 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1241 @remarks This form must be used with non-default width and height values.
1243 @see Move(), @ref overview_windowsizing
1245 void SetSize(const wxRect
& rect
);
1250 void SetSize(const wxSize
& size
);
1255 void SetSize(int width
, int height
);
1258 Use of this function for windows which are not toplevel windows
1259 (such as wxDialog or wxFrame) is discouraged.
1260 Please use SetMinSize() and SetMaxSize() instead.
1262 @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
1264 virtual void SetSizeHints( const wxSize
& minSize
,
1265 const wxSize
& maxSize
=wxDefaultSize
,
1266 const wxSize
& incSize
=wxDefaultSize
);
1267 virtual void SetSizeHints( int minW
, int minH
,
1268 int maxW
= -1, int maxH
= -1,
1269 int incW
= -1, int incH
= -1 );
1272 Sets the virtual size of the window in pixels.
1274 @see @ref overview_windowsizing
1276 void SetVirtualSize(int width
, int height
);
1281 void SetVirtualSize(const wxSize
& size
);
1287 @name Positioning functions
1292 A synonym for Centre().
1294 void Center(int dir
= wxBOTH
);
1297 A synonym for CentreOnParent().
1299 void CenterOnParent(int dir
= wxBOTH
);
1305 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1306 or wxBOTH. It may also include the wxCENTRE_ON_SCREEN flag
1307 if you want to centre the window on the entire screen and not on its
1310 @remarks If the window is a top level one (i.e. doesn't have a parent),
1311 it will be centred relative to the screen anyhow.
1315 void Centre(int direction
= wxBOTH
);
1318 Centres the window on its parent. This is a more readable synonym for Centre().
1321 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1324 @remarks This methods provides for a way to centre top level windows over
1325 their parents instead of the entire screen. If there
1326 is no parent or if the window is not a top level
1327 window, then behaviour is the same as Centre().
1329 @see wxTopLevelWindow::CentreOnScreen
1331 void CentreOnParent(int direction
= wxBOTH
);
1334 This gets the position of the window in pixels, relative to the parent window
1335 for the child windows or relative to the display origin for the top level windows.
1338 Receives the x position of the window if non-@NULL.
1340 Receives the y position of the window if non-@NULL.
1343 In wxPerl this method is implemented as GetPositionXY() returning
1344 a 2-element list (x, y).
1347 @see GetScreenPosition()
1349 void GetPosition(int* x
, int* y
) const;
1352 This gets the position of the window in pixels, relative to the parent window
1353 for the child windows or relative to the display origin for the top level windows.
1355 @see GetScreenPosition()
1357 wxPoint
GetPosition() const;
1360 Returns the position and size of the window as a wxRect object.
1362 @see GetScreenRect()
1364 wxRect
GetRect() const;
1367 Returns the window position in screen coordinates, whether the window is a
1368 child window or a top level one.
1371 Receives the x position of the window on the screen if non-@NULL.
1373 Receives the y position of the window on the screen if non-@NULL.
1377 void GetScreenPosition(int* x
, int* y
) const;
1380 Returns the window position in screen coordinates, whether the window is a
1381 child window or a top level one.
1385 wxPoint
GetScreenPosition() const;
1388 Returns the position and size of the window on the screen as a wxRect object.
1392 wxRect
GetScreenRect() const;
1395 Get the origin of the client area of the window relative to the
1396 window top left corner (the client area may be shifted because of
1397 the borders, scrollbars, other decorations...)
1399 virtual wxPoint
GetClientAreaOrigin() const;
1402 Get the client rectangle in window (i.e. client) coordinates
1404 wxRect
GetClientRect() const;
1409 Moves the window to the given position.
1412 Required x position.
1414 Required y position.
1416 See SetSize() for more info about this parameter.
1418 @remarks Implementations of SetSize can also implicitly implement the
1419 Move() function, which is defined in the base wxWindow class as the call:
1421 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1426 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1429 Moves the window to the given position.
1432 wxPoint object representing the position.
1434 See SetSize() for more info about this parameter.
1436 @remarks Implementations of SetSize() can also implicitly implement the
1437 Move() function, which is defined in the base wxWindow class as the call:
1439 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1444 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1446 void SetPosition(const wxPoint
& pt
);
1452 @name Coordinate conversion functions
1457 Converts to screen coordinates from coordinates relative to this window.
1460 A pointer to a integer value for the x coordinate. Pass the client
1461 coordinate in, and a screen coordinate will be passed out.
1463 A pointer to a integer value for the y coordinate. Pass the client
1464 coordinate in, and a screen coordinate will be passed out.
1467 In wxPerl this method returns a 2-element list instead of
1468 modifying its parameters.
1471 void ClientToScreen(int* x
, int* y
) const;
1474 Converts to screen coordinates from coordinates relative to this window.
1477 The client position for the second form of the function.
1479 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
1482 Converts a point or size from dialog units to pixels.
1484 For the x dimension, the dialog units are multiplied by the average character
1485 width and then divided by 4.
1486 For the y dimension, the dialog units are multiplied by the average character
1487 height and then divided by 8.
1489 @remarks Dialog units are used for maintaining a dialog's proportions
1490 even if the font changes.
1491 You can also use these functions programmatically.
1492 A convenience macro is defined:
1494 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1497 @see ConvertPixelsToDialog()
1499 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
) const;
1504 wxSize
ConvertDialogToPixels(const wxSize
& sz
) const;
1507 Converts a point or size from pixels to dialog units.
1509 For the x dimension, the pixels are multiplied by 4 and then divided by the
1510 average character width.
1511 For the y dimension, the pixels are multiplied by 8 and then divided by the
1512 average character height.
1514 @remarks Dialog units are used for maintaining a dialog's proportions
1515 even if the font changes.
1517 @see ConvertDialogToPixels()
1519 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
) const;
1524 wxSize
ConvertPixelsToDialog(const wxSize
& sz
) const;
1527 Converts from screen to client window coordinates.
1530 Stores the screen x coordinate and receives the client x coordinate.
1532 Stores the screen x coordinate and receives the client x coordinate.
1534 void ScreenToClient(int* x
, int* y
) const;
1537 Converts from screen to client window coordinates.
1540 The screen position.
1542 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1548 @name Drawing-related functions
1553 Clears the window by filling it with the current background colour.
1555 Does not cause an erase background event to be generated.
1557 Notice that this uses wxClientDC to draw on the window and the results
1558 of doing it while also drawing on wxPaintDC for this window are
1559 undefined. Hence this method shouldn't be used from EVT_PAINT handlers,
1560 just use wxDC::Clear() on the wxPaintDC you already use there instead.
1562 virtual void ClearBackground();
1565 Freezes the window or, in other words, prevents any updates from taking
1566 place on screen, the window is not redrawn at all.
1568 Thaw() must be called to reenable window redrawing. Calls to these two
1569 functions may be nested but to ensure that the window is properly
1570 repainted again, you must thaw it exactly as many times as you froze it.
1572 If the window has any children, they are recursively frozen too.
1574 This method is useful for visual appearance optimization (for example,
1575 it is a good idea to use it before doing many large text insertions in
1576 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1577 platforms nor for all controls so it is mostly just a hint to wxWidgets
1578 and not a mandatory directive.
1580 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1585 Re-enables window updating after a previous call to Freeze().
1587 To really thaw the control, it must be called exactly the same number
1588 of times as Freeze().
1590 If the window has any children, they are recursively thawed too.
1592 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1597 Returns @true if the window is currently frozen by a call to Freeze().
1599 @see Freeze(), Thaw()
1601 bool IsFrozen() const;
1604 Returns the background colour of the window.
1606 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1608 wxColour
GetBackgroundColour() const;
1611 Returns the background style of the window.
1613 @see SetBackgroundColour(), GetForegroundColour(),
1614 SetBackgroundStyle(), SetTransparent()
1616 virtual wxBackgroundStyle
GetBackgroundStyle() const;
1619 Returns the character height for this window.
1621 virtual int GetCharHeight() const;
1624 Returns the average character width for this window.
1626 virtual int GetCharWidth() const;
1629 Currently this is the same as calling
1630 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1632 One advantage of using this function compared to the static version is that
1633 the call is automatically dispatched to the correct class (as usual with
1634 virtual functions) and you don't have to specify the class name explicitly.
1636 The other one is that in the future this function could return different
1637 results, for example it might return a different font for an "Ok" button
1638 than for a generic button if the users GUI is configured to show such buttons
1639 in bold font. Of course, the down side is that it is impossible to call this
1640 function without actually having an object to apply it to whereas the static
1641 version can be used without having to create an object first.
1643 virtual wxVisualAttributes
GetDefaultAttributes() const;
1646 Returns the font for this window.
1650 wxFont
GetFont() const;
1653 Returns the foreground colour of the window.
1655 @remarks The meaning of foreground colour varies according to the window class;
1656 it may be the text colour or other colour, or it may not be used at all.
1658 @see SetForegroundColour(), SetBackgroundColour(),
1659 GetBackgroundColour()
1661 wxColour
GetForegroundColour() const;
1664 Gets the dimensions of the string as it would be drawn on the
1665 window with the currently selected font.
1667 The text extent is returned in the @a w and @a h pointers.
1670 String whose extent is to be measured.
1672 Return value for width.
1674 Return value for height.
1676 Return value for descent (optional).
1677 @param externalLeading
1678 Return value for external leading (optional).
1680 Font to use instead of the current window font (optional).
1683 In wxPerl this method takes only the @a string and optionally
1684 @a font parameters, and returns a 4-element list
1685 (x, y, descent, externalLeading).
1688 void GetTextExtent(const wxString
& string
,
1690 int* descent
= NULL
,
1691 int* externalLeading
= NULL
,
1692 const wxFont
* font
= NULL
) const;
1695 Gets the dimensions of the string as it would be drawn on the
1696 window with the currently selected font.
1698 wxSize
GetTextExtent(const wxString
& string
) const;
1701 Returns the region specifying which parts of the window have been damaged.
1702 Should only be called within an wxPaintEvent handler.
1704 @see wxRegion, wxRegionIterator
1706 const wxRegion
& GetUpdateRegion() const;
1709 Get the update rectangle bounding box in client coords
1711 wxRect
GetUpdateClientRect() const;
1714 Returns @true if this window background is transparent (as, for example,
1715 for wxStaticText) and should show the parent window background.
1717 This method is mostly used internally by the library itself and you normally
1718 shouldn't have to call it. You may, however, have to override it in your
1719 wxWindow-derived class to ensure that background is painted correctly.
1721 virtual bool HasTransparentBackground();
1724 Causes this window, and all of its children recursively (except under wxGTK1
1725 where this is not implemented), to be repainted. Note that repainting doesn't
1726 happen immediately but only during the next event loop iteration, if you need
1727 to update the window immediately you should use Update() instead.
1729 @param eraseBackground
1730 If @true, the background will be erased.
1732 If non-@NULL, only the given rectangle will be treated as damaged.
1736 virtual void Refresh(bool eraseBackground
= true,
1737 const wxRect
* rect
= NULL
);
1740 Redraws the contents of the given rectangle: only the area inside it will be
1743 This is the same as Refresh() but has a nicer syntax as it can be called
1744 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1746 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1749 Calling this method immediately repaints the invalidated area of the window and
1750 all of its children recursively (this normally only happens when the
1751 flow of control returns to the event loop).
1753 Notice that this function doesn't invalidate any area of the window so
1754 nothing happens if nothing has been invalidated (i.e. marked as requiring
1755 a redraw). Use Refresh() first if you want to immediately redraw the
1756 window unconditionally.
1758 virtual void Update();
1761 Sets the background colour of the window.
1763 Notice that as with SetForegroundColour(), setting the background
1764 colour of a native control may not affect the entire control and could
1765 be not supported at all depending on the control and platform.
1767 Please see InheritAttributes() for explanation of the difference between
1768 this method and SetOwnBackgroundColour().
1771 The colour to be used as the background colour; pass
1772 wxNullColour to reset to the default colour.
1773 Note that you may want to use wxSystemSettings::GetColour() to retrieve
1774 a suitable colour to use rather than setting an hard-coded one.
1776 @remarks The background colour is usually painted by the default
1777 wxEraseEvent event handler function under Windows and
1778 automatically under GTK.
1779 Note that setting the background colour does not cause an
1780 immediate refresh, so you may wish to call wxWindow::ClearBackground
1781 or wxWindow::Refresh after calling this function.
1782 Using this function will disable attempts to use themes for
1783 this window, if the system supports them. Use with care since
1784 usually the themes represent the appearance chosen by the user
1785 to be used for all applications on the system.
1787 @return @true if the colour was really changed, @false if it was already set
1788 to this colour and nothing was done.
1790 @see GetBackgroundColour(), SetForegroundColour(),
1791 GetForegroundColour(), ClearBackground(),
1792 Refresh(), wxEraseEvent, wxSystemSettings
1794 virtual bool SetBackgroundColour(const wxColour
& colour
);
1797 Sets the background style of the window.
1799 The default background style is @c wxBG_STYLE_ERASE which indicates that
1800 the window background may be erased in @c EVT_ERASE_BACKGROUND handler.
1801 This is a safe, compatibility default; however you may want to change it
1802 to @c wxBG_STYLE_SYSTEM if you don't define any erase background event
1803 handlers at all, to avoid unnecessary generation of erase background
1804 events and always let system erase the background. And you should
1805 change the background style to @c wxBG_STYLE_PAINT if you define an
1806 @c EVT_PAINT handler which completely overwrites the window background as
1807 in this case erasing it previously, either in @c EVT_ERASE_BACKGROUND
1808 handler or in the system default handler, would result in flicker as
1809 the background pixels will be repainted twice every time the window is
1810 redrawn. Do ensure that the background is entirely erased by your
1811 @c EVT_PAINT handler in this case however as otherwise garbage may be left
1814 Notice that in previous versions of wxWidgets a common way to work
1815 around the above mentioned flickering problem was to define an empty
1816 @c EVT_ERASE_BACKGROUND handler. Setting background style to
1817 @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
1821 Under wxGTK and wxOSX, you can use ::wxBG_STYLE_TRANSPARENT to obtain
1822 full transparency of the window background. Note that wxGTK supports
1823 this only since GTK 2.12 with a compositing manager enabled, call
1824 IsTransparentBackgroundSupported() to check whether this is the case.
1826 Also, on order for @c SetBackgroundStyle(wxBG_STYLE_TRANSPARENT) to
1827 work, it must be called before Create(). If you're using your own
1828 wxWindow-derived class you should write your code in the following way:
1830 class MyWidget : public wxWindow
1833 MyWidget(wxWindow* parent, ...)
1834 : wxWindow() // Use default ctor here!
1837 SetBackgroundStyle(wxBG_STYLE_TRANSPARENT);
1839 // And really create the window afterwards:
1840 Create(parent, ...);
1845 @see SetBackgroundColour(), GetForegroundColour(),
1846 SetTransparent(), IsTransparentBackgroundSupported()
1848 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
1851 Checks whether using transparent background might work.
1853 If this function returns @false, calling SetBackgroundStyle() with
1854 ::wxBG_STYLE_TRANSPARENT is not going to work. If it returns @true,
1855 setting transparent style should normally succeed.
1857 Notice that this function would typically be called on the parent of a
1858 window you want to set transparent background style for as the window
1859 for which this method is called must be fully created.
1862 If not @NULL, a reason message is provided if transparency is not
1865 @return @true if background transparency is supported.
1869 virtual bool IsTransparentBackgroundSupported(wxString
*reason
= NULL
) const;
1872 Sets the font for this window. This function should not be called for the
1873 parent window if you don't want its font to be inherited by its children,
1874 use SetOwnFont() instead in this case and see InheritAttributes() for more
1877 Please notice that the given font is not automatically used for
1878 wxPaintDC objects associated with this window, you need to
1879 call wxDC::SetFont too. However this font is used by
1880 any standard controls for drawing their text as well as by
1884 Font to associate with this window, pass
1885 wxNullFont to reset to the default font.
1887 @return @true if the font was really changed, @false if it was already set
1888 to this font and nothing was done.
1890 @see GetFont(), InheritAttributes()
1892 virtual bool SetFont(const wxFont
& font
);
1895 Sets the foreground colour of the window.
1897 The meaning of foreground colour varies according to the window class;
1898 it may be the text colour or other colour, or it may not be used at
1899 all. Additionally, not all native controls support changing their
1900 foreground colour so this method may change their colour only partially
1903 Please see InheritAttributes() for explanation of the difference between
1904 this method and SetOwnForegroundColour().
1907 The colour to be used as the foreground colour; pass
1908 wxNullColour to reset to the default colour.
1910 @return @true if the colour was really changed, @false if it was already set
1911 to this colour and nothing was done.
1913 @see GetForegroundColour(), SetBackgroundColour(),
1914 GetBackgroundColour(), ShouldInheritColours()
1916 virtual bool SetForegroundColour(const wxColour
& colour
);
1919 Sets the background colour of the window but prevents it from being inherited
1920 by the children of this window.
1922 @see SetBackgroundColour(), InheritAttributes()
1924 void SetOwnBackgroundColour(const wxColour
& colour
);
1926 bool InheritsBackgroundColour() const;
1927 bool UseBgCol() const;
1930 Sets the font of the window but prevents it from being inherited by the
1931 children of this window.
1933 @see SetFont(), InheritAttributes()
1935 void SetOwnFont(const wxFont
& font
);
1938 Sets the foreground colour of the window but prevents it from being inherited
1939 by the children of this window.
1941 @see SetForegroundColour(), InheritAttributes()
1943 void SetOwnForegroundColour(const wxColour
& colour
);
1946 @deprecated use wxDC::SetPalette instead.
1948 void SetPalette(const wxPalette
& pal
);
1951 Return @true from here to allow the colours of this window to be changed by
1952 InheritAttributes(). Returning @false forbids inheriting them from the parent window.
1954 The base class version returns @false, but this method is overridden in
1955 wxControl where it returns @true.
1957 virtual bool ShouldInheritColours() const;
1960 This function tells a window if it should use the system's "theme" code
1961 to draw the windows' background instead of its own background drawing
1962 code. This does not always have any effect since the underlying platform
1963 obviously needs to support the notion of themes in user defined windows.
1964 One such platform is GTK+ where windows can have (very colourful) backgrounds
1965 defined by a user's selected theme.
1967 Dialogs, notebook pages and the status bar have this flag set to @true
1968 by default so that the default look and feel is simulated best.
1970 virtual void SetThemeEnabled(bool enable
);
1974 virtual bool GetThemeEnabled() const;
1977 Returns @true if the system supports transparent windows and calling
1978 SetTransparent() may succeed. If this function returns @false, transparent
1979 windows are definitely not supported by the current system.
1981 virtual bool CanSetTransparent();
1984 Set the transparency of the window. If the system supports transparent windows,
1985 returns @true, otherwise returns @false and the window remains fully opaque.
1986 See also CanSetTransparent().
1988 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1989 fully transparent window and 255 to the fully opaque one. The constants
1990 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1992 virtual bool SetTransparent(wxByte alpha
);
1998 @name Event-handling functions
2000 wxWindow allows you to build a (sort of) stack of event handlers which
2001 can be used to override the window's own event handling.
2006 Returns the event handler for this window.
2007 By default, the window is its own event handler.
2009 @see SetEventHandler(), PushEventHandler(),
2010 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
2012 wxEvtHandler
* GetEventHandler() const;
2015 This function will generate the appropriate call to Navigate() if the key
2016 event is one normally used for keyboard navigation and return @true in this case.
2018 @return Returns @true if the key pressed was for navigation and was
2019 handled, @false otherwise.
2023 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
2028 GetEventHandler()->SafelyProcessEvent(event);
2031 @see ProcessWindowEvent()
2033 bool HandleWindowEvent(wxEvent
& event
) const;
2036 Convenient wrapper for ProcessEvent().
2038 This is the same as writing @code GetEventHandler()->ProcessEvent(event);
2039 @endcode but more convenient. Notice that ProcessEvent() itself can't
2040 be called for wxWindow objects as it ignores the event handlers
2041 associated with the window; use this function instead.
2043 bool ProcessWindowEvent(wxEvent
& event
);
2046 Wrapper for wxEvtHandler::ProcessEventLocally().
2048 This method is similar to ProcessWindowEvent() but can be used to
2049 search for the event handler only in this window and any event handlers
2050 pushed on top of it. Unlike ProcessWindowEvent() it won't propagate the
2051 event upwards. But it will use the validator and event handlers
2052 associated with this window, if any.
2056 bool ProcessWindowEventLocally(wxEvent
& event
);
2059 Removes and returns the top-most event handler on the event handler stack.
2061 E.g. in the case of:
2062 @image html overview_events_winstack.png
2063 when calling @c W->PopEventHandler(), the event handler @c A will be
2064 removed and @c B will be the first handler of the stack.
2066 Note that it's an error to call this function when no event handlers
2067 were pushed on this window (i.e. when the window itself is its only
2070 @param deleteHandler
2071 If this is @true, the handler will be deleted after it is removed
2072 (and the returned value will be @NULL).
2074 @see @ref overview_events_processing
2076 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
2079 Pushes this event handler onto the event stack for the window.
2081 An event handler is an object that is capable of processing the events sent
2082 to a window. By default, the window is its own event handler, but an application
2083 may wish to substitute another, for example to allow central implementation
2084 of event-handling for a variety of different window classes.
2086 wxWindow::PushEventHandler allows an application to set up a @e stack
2087 of event handlers, where an event not handled by one event handler is
2088 handed to the next one in the chain.
2090 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
2093 W->PushEventHandler(A);
2094 W->PushEventHandler(B);
2096 you will end up with the following situation:
2097 @image html overview_events_winstack.png
2099 Note that you can use wxWindow::PopEventHandler to remove the event handler.
2102 Specifies the handler to be pushed.
2103 It must not be part of a wxEvtHandler chain; an assert will fail
2104 if it's not unlinked (see wxEvtHandler::IsUnlinked).
2106 @see @ref overview_events_processing
2108 void PushEventHandler(wxEvtHandler
* handler
);
2111 Find the given @a handler in the windows event handler stack and
2112 removes (but does not delete) it from the stack.
2114 See wxEvtHandler::Unlink() for more info.
2117 The event handler to remove, must be non-@NULL and
2118 must be present in this windows event handlers stack.
2120 @return Returns @true if it was found and @false otherwise (this also
2121 results in an assert failure so this function should
2122 only be called when the handler is supposed to be there).
2124 @see PushEventHandler(), PopEventHandler()
2126 bool RemoveEventHandler(wxEvtHandler
* handler
);
2129 Sets the event handler for this window.
2131 Note that if you use this function you may want to use as the "next" handler
2132 of @a handler the window itself; in this way when @a handler doesn't process
2133 an event, the window itself will have a chance to do it.
2136 Specifies the handler to be set. Cannot be @NULL.
2138 @see @ref overview_events_processing
2140 void SetEventHandler(wxEvtHandler
* handler
);
2143 wxWindows cannot be used to form event handler chains; this function
2144 thus will assert when called.
2146 Note that instead you can use PushEventHandler() or SetEventHandler() to
2147 implement a stack of event handlers to override wxWindow's own
2148 event handling mechanism.
2150 virtual void SetNextHandler(wxEvtHandler
* handler
);
2153 wxWindows cannot be used to form event handler chains; this function
2154 thus will assert when called.
2156 Note that instead you can use PushEventHandler() or SetEventHandler() to
2157 implement a stack of event handlers to override wxWindow's own
2158 event handling mechanism.
2160 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
2167 @name Window styles functions
2172 Returns the extra style bits for the window.
2174 long GetExtraStyle() const;
2177 Gets the window style that was passed to the constructor or Create()
2178 method. GetWindowStyle() is another name for the same function.
2180 virtual long GetWindowStyleFlag() const;
2183 See GetWindowStyleFlag() for more info.
2185 long GetWindowStyle() const;
2188 Returns @true if the window has the given @a exFlag bit set in its
2191 @see SetExtraStyle()
2193 bool HasExtraStyle(int exFlag
) const;
2196 Returns @true if the window has the given @a flag bit set.
2198 bool HasFlag(int flag
) const;
2201 Sets the extra style bits for the window.
2202 The currently defined extra style bits are reported in the class
2205 virtual void SetExtraStyle(long exStyle
);
2208 Sets the style of the window. Please note that some styles cannot be changed
2209 after the window creation and that Refresh() might need to be called
2210 after changing the others for the change to take place immediately.
2212 See @ref overview_windowstyles "Window styles" for more information about flags.
2214 @see GetWindowStyleFlag()
2216 virtual void SetWindowStyleFlag(long style
);
2219 See SetWindowStyleFlag() for more info.
2221 void SetWindowStyle(long style
);
2224 Turns the given @a flag on if it's currently turned off and vice versa.
2225 This function cannot be used if the value of the flag is 0 (which is often
2226 the case for default flags).
2228 Also, please notice that not all styles can be changed after the control
2231 @return Returns @true if the style was turned on by this function, @false
2232 if it was switched off.
2234 @see SetWindowStyleFlag(), HasFlag()
2236 bool ToggleWindowStyle(int flag
);
2242 @name Tab order functions
2247 Moves this window in the tab navigation order after the specified @e win.
2248 This means that when the user presses @c TAB key on that other window,
2249 the focus switches to this window.
2251 Default tab order is the same as creation order, this function and
2252 MoveBeforeInTabOrder() allow to change
2253 it after creating all the windows.
2256 A sibling of this window which should precede it in tab order,
2259 void MoveAfterInTabOrder(wxWindow
* win
);
2262 Same as MoveAfterInTabOrder() except that it inserts this window just
2263 before @a win instead of putting it right after it.
2265 void MoveBeforeInTabOrder(wxWindow
* win
);
2268 Performs a keyboard navigation action starting from this window.
2269 This method is equivalent to calling NavigateIn() method on the
2273 A combination of wxNavigationKeyEvent::IsForward and
2274 wxNavigationKeyEvent::WinChange.
2276 @return Returns @true if the focus was moved to another window or @false
2279 @remarks You may wish to call this from a text control custom keypress
2280 handler to do the default navigation behaviour for the
2281 tab key, since the standard default behaviour for a
2282 multiline text control with the wxTE_PROCESS_TAB style
2283 is to insert a tab and not navigate to the next
2284 control. See also wxNavigationKeyEvent and
2285 HandleAsNavigationKey.
2287 bool Navigate(int flags
= wxNavigationKeyEvent::IsForward
);
2290 Performs a keyboard navigation action inside this window.
2291 See Navigate() for more information.
2293 bool NavigateIn(int flags
= wxNavigationKeyEvent::IsForward
);
2300 @name Z order functions
2305 Lowers the window to the bottom of the window hierarchy (Z-order).
2308 This function only works for wxTopLevelWindow-derived classes.
2312 virtual void Lower();
2315 Raises the window to the top of the window hierarchy (Z-order).
2317 Notice that this function only requests the window manager to raise
2318 this window to the top of Z-order. Depending on its configuration, the
2319 window manager may raise the window, not do it at all or indicate that
2320 a window requested to be raised in some other way, e.g. by flashing its
2321 icon if it is minimized.
2324 This function only works for wxTopLevelWindow-derived classes.
2328 virtual void Raise();
2334 @name Window status functions
2340 Equivalent to calling wxWindow::Show(@false).
2345 This function hides a window, like Hide(), but using a special visual
2348 The parameters of this function are the same as for ShowWithEffect(),
2349 please see their description there.
2353 virtual bool HideWithEffect(wxShowEffect effect
,
2354 unsigned int timeout
= 0);
2356 Returns @true if the window is enabled, i.e. if it accepts user input,
2359 Notice that this method can return @false even if this window itself hadn't
2360 been explicitly disabled when one of its parent windows is disabled.
2361 To get the intrinsic status of this window, use IsThisEnabled()
2365 bool IsEnabled() const;
2368 Returns @true if the given point or rectangle area has been exposed since the
2369 last repaint. Call this in an paint event handler to optimize redrawing by
2370 only redrawing those areas, which have been exposed.
2372 bool IsExposed(int x
, int y
) const;
2377 bool IsExposed(wxPoint
& pt
) const;
2382 bool IsExposed(int x
, int y
, int w
, int h
) const;
2387 bool IsExposed(wxRect
& rect
) const;
2389 Returns @true if the window is shown, @false if it has been hidden.
2391 @see IsShownOnScreen()
2393 virtual bool IsShown() const;
2396 Returns @true if the window is physically visible on the screen, i.e. it
2397 is shown and all its parents up to the toplevel window are shown as well.
2401 virtual bool IsShownOnScreen() const;
2404 Disables the window. Same as @ref Enable() Enable(@false).
2406 @return Returns @true if the window has been disabled, @false if it had
2407 been already disabled before the call to this function.
2412 Enable or disable the window for user input. Note that when a parent window is
2413 disabled, all of its children are disabled as well and they are reenabled again
2417 If @true, enables the window for input. If @false, disables the window.
2419 @return Returns @true if the window has been enabled or disabled, @false
2420 if nothing was done, i.e. if the window had already
2421 been in the specified state.
2423 @see IsEnabled(), Disable(), wxRadioBox::Enable
2425 virtual bool Enable(bool enable
= true);
2428 Shows or hides the window. You may need to call Raise()
2429 for a top level window if you want to bring it to top, although this is not
2430 needed if Show() is called immediately after the frame creation.
2432 Notice that the default state of newly created top level windows is hidden
2433 (to allow you to create their contents without flicker) unlike for
2434 all the other, not derived from wxTopLevelWindow, windows that
2435 are by default created in the shown state.
2438 If @true displays the window. Otherwise, hides it.
2440 @return @true if the window has been shown or hidden or @false if nothing
2441 was done because it already was in the requested state.
2443 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2445 virtual bool Show(bool show
= true);
2448 This function shows a window, like Show(), but using a special visual
2455 The @a timeout parameter specifies the time of the animation, in
2456 milliseconds. If the default value of 0 is used, the default
2457 animation time for the current platform is used.
2459 @note Currently this function is only implemented in wxMSW and wxOSX
2460 (for wxTopLevelWindows only in Carbon version and for any kind of
2461 windows in Cocoa) and does the same thing as Show() in the other
2466 @see HideWithEffect()
2468 virtual bool ShowWithEffect(wxShowEffect effect
,
2469 unsigned int timeout
= 0);
2475 @name Context-sensitive help functions
2480 Gets the help text to be used as context-sensitive help for this window.
2481 Note that the text is actually stored by the current wxHelpProvider
2482 implementation, and not in the window object itself.
2484 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2486 wxString
GetHelpText() const;
2489 Sets the help text to be used as context-sensitive help for this window.
2490 Note that the text is actually stored by the current wxHelpProvider
2491 implementation, and not in the window object itself.
2493 @see GetHelpText(), wxHelpProvider::AddHelp()
2495 void SetHelpText(const wxString
& helpText
);
2498 Gets the help text to be used as context-sensitive help for this window.
2499 This method should be overridden if the help message depends on the position
2500 inside the window, otherwise GetHelpText() can be used.
2503 Coordinates of the mouse at the moment of help event emission.
2505 Help event origin, see also wxHelpEvent::GetOrigin.
2507 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
2508 wxHelpEvent::Origin origin
) const;
2511 Get the associated tooltip or @NULL if none.
2513 wxToolTip
* GetToolTip() const;
2516 Get the text of the associated tooltip or empty string if none.
2518 wxString
GetToolTipText() const;
2521 Attach a tooltip to the window.
2523 wxToolTip pointer can be @NULL in the overload taking the pointer,
2524 meaning to unset any existing tooltips; however UnsetToolTip() provides
2525 a more readable alternative to this operation.
2527 Notice that these methods are always available, even if wxWidgets was
2528 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2531 @see GetToolTip(), wxToolTip
2533 void SetToolTip(const wxString
& tipString
);
2538 void SetToolTip(wxToolTip
* tip
);
2541 Unset any existing tooltip.
2547 void UnsetToolTip();
2553 @name Popup/context menu functions
2558 This function shows a popup menu at the given position in this window and
2559 returns the selected id.
2561 It can be more convenient than the general purpose PopupMenu() function
2562 for simple menus proposing a choice in a list of strings to the user.
2564 Notice that to avoid unexpected conflicts between the (usually
2565 consecutive range of) ids used by the menu passed to this function and
2566 the existing EVT_UPDATE_UI() handlers, this function temporarily
2567 disables UI updates for the window, so you need to manually disable
2568 (or toggle or ...) any items which should be disabled in the menu
2571 The parameter @a menu is the menu to show.
2572 The parameter @a pos (or the parameters @a x and @a y) is the
2573 position at which to show the menu in client coordinates.
2574 It is recommended to not explicitly specify coordinates when
2575 calling this method in response to mouse click, because some of
2576 the ports (namely, wxGTK) can do a better job of positioning
2577 the menu in that case.
2580 The selected menu item id or @c wxID_NONE if none selected or an
2585 int GetPopupMenuSelectionFromUser(wxMenu
& menu
,
2586 const wxPoint
& pos
= wxDefaultPosition
);
2591 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
2594 Pops up the given menu at the specified coordinates, relative to this
2595 window, and returns control when the user has dismissed the menu.
2597 If a menu item is selected, the corresponding menu event is generated and will be
2598 processed as usual. If coordinates are not specified, the current mouse
2599 cursor position is used.
2601 @a menu is the menu to pop up.
2603 The position where the menu will appear can be specified either as a
2604 wxPoint @a pos or by two integers (@a x and @a y).
2606 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2607 ensure that the menu items are in the correct state.
2608 The menu does not get deleted by the window.
2609 It is recommended to not explicitly specify coordinates when
2610 calling PopupMenu in response to mouse click, because some of
2611 the ports (namely, wxGTK) can do a better job of positioning
2612 the menu in that case.
2616 bool PopupMenu(wxMenu
* menu
,
2617 const wxPoint
& pos
= wxDefaultPosition
);
2622 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
2633 Returns a pointer to the current validator for the window, or @NULL if
2636 virtual wxValidator
* GetValidator();
2639 Deletes the current validator (if any) and sets the window validator, having
2640 called wxValidator::Clone to create a new validator of this type.
2642 virtual void SetValidator(const wxValidator
& validator
);
2645 Transfers values from child controls to data areas specified by their
2646 validators. Returns @false if a transfer failed.
2648 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2649 the method will also call TransferDataFromWindow() of all child windows.
2651 @see TransferDataToWindow(), wxValidator, Validate()
2653 virtual bool TransferDataFromWindow();
2656 Transfers values to child controls from data areas specified by their
2659 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2660 the method will also call TransferDataToWindow() of all child windows.
2662 @return Returns @false if a transfer failed.
2664 @see TransferDataFromWindow(), wxValidator, Validate()
2666 virtual bool TransferDataToWindow();
2669 Validates the current values of the child controls using their validators.
2670 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2671 the method will also call Validate() of all child windows.
2673 @return Returns @false if any of the validations failed.
2675 @see TransferDataFromWindow(), TransferDataToWindow(),
2678 virtual bool Validate();
2684 @name wxWindow properties functions
2689 Returns the identifier of the window.
2691 @remarks Each window has an integer identifier. If the application
2692 has not provided one (or the default wxID_ANY) a unique
2693 identifier with a negative value will be generated.
2695 @see SetId(), @ref overview_windowids
2697 wxWindowID
GetId() const;
2700 Generic way of getting a label from any window, for
2701 identification purposes.
2703 @remarks The interpretation of this function differs from class to class.
2704 For frames and dialogs, the value returned is the
2705 title. For buttons or static text controls, it is the
2706 button text. This function can be useful for
2707 meta-programs (such as testing tools or special-needs
2708 access programs) which need to identify windows by name.
2710 virtual wxString
GetLabel() const;
2713 Returns the layout direction for this window,
2714 Note that @c wxLayout_Default is returned if layout direction is not supported.
2716 virtual wxLayoutDirection
GetLayoutDirection() const;
2719 Mirror coordinates for RTL layout if this window uses it and if the
2720 mirroring is not done automatically like Win32.
2722 virtual wxCoord
AdjustForLayoutDirection(wxCoord x
,
2724 wxCoord widthTotal
) const;
2727 Returns the window's name.
2729 @remarks This name is not guaranteed to be unique; it is up to the
2730 programmer to supply an appropriate name in the window
2731 constructor or via SetName().
2735 virtual wxString
GetName() const;
2738 Returns the value previously passed to SetWindowVariant().
2740 wxWindowVariant
GetWindowVariant() const;
2743 Sets the identifier of the window.
2745 @remarks Each window has an integer identifier. If the application has
2746 not provided one, an identifier will be generated.
2747 Normally, the identifier should be provided on creation
2748 and should not be modified subsequently.
2750 @see GetId(), @ref overview_windowids
2752 void SetId(wxWindowID winid
);
2755 Sets the window's label.
2762 virtual void SetLabel(const wxString
& label
);
2765 Sets the layout direction for this window.
2767 virtual void SetLayoutDirection(wxLayoutDirection dir
);
2770 Sets the window's name.
2773 A name to set for the window.
2777 virtual void SetName(const wxString
& name
);
2780 This function can be called under all platforms but only does anything under
2781 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2782 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2784 By default the controls use the normal size, of course, but this function can
2785 be used to change this.
2787 void SetWindowVariant(wxWindowVariant variant
);
2790 Gets the accelerator table for this window. See wxAcceleratorTable.
2792 wxAcceleratorTable
* GetAcceleratorTable();
2795 Returns the accessible object for this window, if any.
2796 See also wxAccessible.
2798 wxAccessible
* GetAccessible();
2801 Sets the accelerator table for this window. See wxAcceleratorTable.
2803 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
2806 Sets the accessible for this window. Any existing accessible for this window
2807 will be deleted first, if not identical to @e accessible.
2808 See also wxAccessible.
2810 void SetAccessible(wxAccessible
* accessible
);
2816 @name Window deletion functions
2821 This function simply generates a wxCloseEvent whose handler usually tries
2822 to close the window. It doesn't close the window itself, however.
2825 @false if the window's close handler should be able to veto the destruction
2826 of this window, @true if it cannot.
2828 @return @true if the event was handled and not vetoed, @false otherwise.
2830 @remarks Close calls the close handler for the window, providing an
2831 opportunity for the window to choose whether to destroy
2832 the window. Usually it is only used with the top level
2833 windows (wxFrame and wxDialog classes) as the others
2834 are not supposed to have any special OnClose() logic.
2835 The close handler should check whether the window is being deleted
2836 forcibly, using wxCloseEvent::CanVeto, in which case it should
2837 destroy the window using wxWindow::Destroy.
2838 Note that calling Close does not guarantee that the window will
2839 be destroyed; but it provides a way to simulate a manual close
2840 of a window, which may or may not be implemented by destroying
2841 the window. The default implementation of wxDialog::OnCloseWindow
2842 does not necessarily delete the dialog, since it will simply
2843 simulate an wxID_CANCEL event which is handled by the appropriate
2844 button event handler and may do anything at all.
2845 To guarantee that the window will be destroyed, call
2846 wxWindow::Destroy instead
2848 @see @ref overview_windowdeletion "Window Deletion Overview",
2849 Destroy(), wxCloseEvent
2851 bool Close(bool force
= false);
2854 Destroys the window safely. Use this function instead of the delete operator,
2855 since different window classes can be destroyed differently. Frames and dialogs
2856 are not destroyed immediately when this function is called -- they are added
2857 to a list of windows to be deleted on idle time, when all the window's events
2858 have been processed. This prevents problems with events being sent to
2859 non-existent windows.
2861 @return @true if the window has either been successfully deleted, or it
2862 has been added to the list of windows pending real deletion.
2864 virtual bool Destroy();
2867 Returns true if this window is in process of being destroyed.
2869 Top level windows are not deleted immediately but are rather
2870 scheduled for later destruction to give them time to process any
2871 pending messages; see Destroy() description.
2873 This function returns @true if this window, or one of its parent
2874 windows, is scheduled for destruction and can be useful to avoid
2875 manipulating it as it's usually useless to do something with a window
2876 which is on the point of disappearing anyhow.
2878 bool IsBeingDeleted() const;
2885 @name Drag and drop functions
2890 Returns the associated drop target, which may be @NULL.
2892 @see SetDropTarget(), @ref overview_dnd
2894 virtual wxDropTarget
* GetDropTarget() const;
2897 Associates a drop target with this window.
2898 If the window already has a drop target, it is deleted.
2900 @see GetDropTarget(), @ref overview_dnd
2902 virtual void SetDropTarget(wxDropTarget
* target
);
2905 Enables or disables eligibility for drop file events (OnDropFiles).
2908 If @true, the window is eligible for drop file events.
2909 If @false, the window will not accept drop file events.
2911 @remarks Windows only until version 2.8.9, available on all platforms
2912 since 2.8.10. Cannot be used together with SetDropTarget() on
2913 non-Windows platforms.
2915 @see SetDropTarget()
2917 virtual void DragAcceptFiles(bool accept
);
2923 @name Constraints, sizers and window layout functions
2928 Returns the sizer of which this window is a member, if any, otherwise @NULL.
2930 wxSizer
* GetContainingSizer() const;
2933 Returns the sizer associated with the window by a previous call to
2934 SetSizer(), or @NULL.
2936 wxSizer
* GetSizer() const;
2939 Sets the window to have the given layout sizer.
2941 The window will then own the object, and will take care of its deletion.
2942 If an existing layout constraints object is already owned by the
2943 window, it will be deleted if the @a deleteOld parameter is @true.
2945 Note that this function will also call SetAutoLayout() implicitly with @true
2946 parameter if the @a sizer is non-@NULL and @false otherwise so that the
2947 sizer will be effectively used to layout the window children whenever
2951 The sizer to set. Pass @NULL to disassociate and conditionally delete
2952 the window's sizer. See below.
2954 If @true (the default), this will delete any pre-existing sizer.
2955 Pass @false if you wish to handle deleting the old sizer yourself
2956 but remember to do it yourself in this case to avoid memory leaks.
2958 @remarks SetSizer enables and disables Layout automatically.
2960 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2963 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2964 window size to the size needed to accommodate all sizer elements and sets the
2965 size hints which, if this window is a top level one, prevent the user from
2966 resizing it to be less than this minimal size.
2968 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2971 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2973 wxLayoutConstraints
* GetConstraints() const;
2976 Sets the window to have the given layout constraints. The window
2977 will then own the object, and will take care of its deletion.
2978 If an existing layout constraints object is already owned by the
2979 window, it will be deleted.
2982 The constraints to set. Pass @NULL to disassociate and delete the window's
2985 @remarks You must call SetAutoLayout() to tell a window to use
2986 the constraints automatically in OnSize; otherwise, you
2987 must override OnSize and call Layout() explicitly. When
2988 setting both a wxLayoutConstraints and a wxSizer, only
2989 the sizer will have effect.
2991 void SetConstraints(wxLayoutConstraints
* constraints
);
2994 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2997 This function does not get called automatically when the window is resized
2998 because lots of windows deriving from wxWindow does not need this functionality.
2999 If you want to have Layout() called automatically, you should derive
3000 from wxPanel (see wxPanel::Layout).
3002 @see @ref overview_windowsizing
3004 virtual bool Layout();
3007 Determines whether the Layout() function will be called automatically
3008 when the window is resized.
3010 This method is called implicitly by SetSizer() but if you use SetConstraints()
3011 you should call it manually or otherwise the window layout won't be correctly
3012 updated when its size changes.
3015 Set this to @true if you wish the Layout() function to be called
3016 automatically when the window is resized.
3018 @see SetSizer(), SetConstraints()
3020 void SetAutoLayout(bool autoLayout
);
3022 bool GetAutoLayout() const;
3029 @name Mouse functions
3034 Directs all mouse input to this window.
3035 Call ReleaseMouse() to release the capture.
3037 Note that wxWidgets maintains the stack of windows having captured the mouse
3038 and when the mouse is released the capture returns to the window which had had
3039 captured it previously and it is only really released if there were no previous
3040 window. In particular, this means that you must release the mouse as many times
3041 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
3043 Any application which captures the mouse in the beginning of some operation
3044 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
3045 the event. The event handler must not recapture mouse.
3047 @see ReleaseMouse(), wxMouseCaptureLostEvent
3049 void CaptureMouse();
3052 Returns the caret() associated with the window.
3054 wxCaret
* GetCaret() const;
3057 Return the cursor associated with this window.
3061 const wxCursor
& GetCursor() const;
3064 Returns @true if this window has the current mouse capture.
3066 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
3067 wxMouseCaptureChangedEvent
3069 virtual bool HasCapture() const;
3072 Releases mouse input captured with CaptureMouse().
3074 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
3075 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3077 void ReleaseMouse();
3080 Sets the caret() associated with the window.
3082 void SetCaret(wxCaret
* caret
);
3085 Sets the window's cursor. Notice that the window cursor also sets it for the
3086 children of the window implicitly.
3088 The @a cursor may be @c wxNullCursor in which case the window cursor will
3089 be reset back to default.
3092 Specifies the cursor that the window should normally display.
3094 @see ::wxSetCursor, wxCursor
3096 virtual bool SetCursor(const wxCursor
& cursor
);
3099 Moves the pointer to the given position on the window.
3101 @note Apple Human Interface Guidelines forbid moving the mouse cursor
3102 programmatically so you should avoid using this function in Mac
3103 applications (and probably avoid using it under the other
3104 platforms without good reason as well).
3107 The new x position for the cursor.
3109 The new y position for the cursor.
3111 virtual void WarpPointer(int x
, int y
);
3119 @name Miscellaneous functions
3123 wxHitTest
HitTest(wxCoord x
, wxCoord y
) const;
3124 wxHitTest
HitTest(const wxPoint
& pt
) const;
3127 Get the window border style from the given flags: this is different from
3128 simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to
3129 translate wxBORDER_DEFAULT to something reasonable
3131 wxBorder
GetBorder(long flags
) const;
3134 Get border for the flags of this window
3136 wxBorder
GetBorder() const;
3140 Does the window-specific updating after processing the update event.
3141 This function is called by UpdateWindowUI() in order to check return
3142 values in the wxUpdateUIEvent and act appropriately.
3143 For example, to allow frame and dialog title updating, wxWidgets
3144 implements this function as follows:
3147 // do the window-specific processing after processing the update event
3148 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
3150 if ( event.GetSetEnabled() )
3151 Enable(event.GetEnabled());
3153 if ( event.GetSetText() )
3155 if ( event.GetText() != GetTitle() )
3156 SetTitle(event.GetText());
3161 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
3164 Returns the platform-specific handle of the physical window.
3165 Cast it to an appropriate handle, such as @b HWND for Windows,
3166 @b Widget for Motif or @b GtkWidget for GTK.
3169 This method will return an integer in wxPerl.
3172 virtual WXWidget
GetHandle() const;
3175 This method should be overridden to return @true if this window has
3176 multiple pages. All standard class with multiple pages such as
3177 wxNotebook, wxListbook and wxTreebook already override it to return @true
3178 and user-defined classes with similar behaviour should also do so, to
3179 allow the library to handle such windows appropriately.
3181 virtual bool HasMultiplePages() const;
3184 This function is (or should be, in case of custom controls) called during
3185 window creation to intelligently set up the window visual attributes, that is
3186 the font and the foreground and background colours.
3188 By "intelligently" the following is meant: by default, all windows use their
3189 own @ref GetClassDefaultAttributes() default attributes.
3190 However if some of the parents attributes are explicitly (that is, using
3191 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
3192 attribute hadn't been explicitly set for this window itself, then this
3193 window takes the same value as used by the parent.
3194 In addition, if the window overrides ShouldInheritColours() to return @false,
3195 the colours will not be changed no matter what and only the font might.
3197 This rather complicated logic is necessary in order to accommodate the
3198 different usage scenarios. The most common one is when all default attributes
3199 are used and in this case, nothing should be inherited as in modern GUIs
3200 different controls use different fonts (and colours) than their siblings so
3201 they can't inherit the same value from the parent. However it was also deemed
3202 desirable to allow to simply change the attributes of all children at once by
3203 just changing the font or colour of their common parent, hence in this case we
3204 do inherit the parents attributes.
3206 virtual void InheritAttributes();
3209 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
3210 to the dialog via validators.
3212 virtual void InitDialog();
3215 Returns @true if the window contents is double-buffered by the system, i.e. if
3216 any drawing done on the window is really done on a temporary backing surface
3217 and transferred to the screen all at once later.
3221 virtual bool IsDoubleBuffered() const;
3224 Turn on or off double buffering of the window if the system supports it.
3226 void SetDoubleBuffered(bool on
);
3229 Returns @true if the window is retained, @false otherwise.
3231 @remarks Retained windows are only available on X platforms.
3233 virtual bool IsRetained() const;
3236 Returns @true if this window is intrinsically enabled, @false otherwise,
3237 i.e. if @ref Enable() Enable(@false) had been called. This method is
3238 mostly used for wxWidgets itself, user code should normally use
3239 IsEnabled() instead.
3241 bool IsThisEnabled() const;
3244 Returns @true if the given window is a top-level one. Currently all frames and
3245 dialogs are considered to be top-level windows (even if they have a parent
3248 virtual bool IsTopLevel() const;
3252 This virtual function is normally only used internally, but
3253 sometimes an application may need it to implement functionality
3254 that should not be disabled by an application defining an OnIdle
3255 handler in a derived class.
3257 This function may be used to do delayed painting, for example,
3258 and most implementations call UpdateWindowUI()
3259 in order to send update events to the window in idle time.
3261 virtual void OnInternalIdle();
3264 Send idle event to window and all subwindows. Returns true if more idle
3267 virtual bool SendIdleEvents(wxIdleEvent
& event
);
3270 Registers a system wide hotkey. Every time the user presses the hotkey
3271 registered here, this window will receive a hotkey event.
3273 It will receive the event even if the application is in the background
3274 and does not have the input focus because the user is working with some
3278 Numeric identifier of the hotkey. For applications this must be between 0
3279 and 0xBFFF. If this function is called from a shared DLL, it must be a
3280 system wide unique identifier between 0xC000 and 0xFFFF.
3281 This is a MSW specific detail.
3283 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
3284 or wxMOD_WIN specifying the modifier keys that have to be pressed along
3286 @param virtualKeyCode
3287 The virtual key code of the hotkey.
3289 @return @true if the hotkey was registered successfully. @false if some
3290 other application already registered a hotkey with this
3291 modifier/virtualKeyCode combination.
3293 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
3294 event. This function is currently only implemented
3295 under Windows. It is used in the Windows CE port for
3296 detecting hardware button presses.
3298 @see UnregisterHotKey()
3300 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
3301 int virtualKeyCode
);
3304 Unregisters a system wide hotkey.
3307 Numeric identifier of the hotkey. Must be the same id that was passed to
3310 @return @true if the hotkey was unregistered successfully, @false if the
3313 @remarks This function is currently only implemented under MSW.
3315 @see RegisterHotKey()
3317 virtual bool UnregisterHotKey(int hotkeyId
);
3320 This function sends one or more wxUpdateUIEvent to the window.
3321 The particular implementation depends on the window; for example a
3322 wxToolBar will send an update UI event for each toolbar button,
3323 and a wxFrame will send an update UI event for each menubar menu item.
3325 You can call this function from your application to ensure that your
3326 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
3327 are concerned). This may be necessary if you have called
3328 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
3329 the overhead that wxWidgets incurs by sending update UI events in idle time.
3330 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
3332 If you are calling this function from an OnInternalIdle or OnIdle
3333 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
3334 this tells the window to only update the UI elements that need
3335 to be updated in idle time. Some windows update their elements
3336 only when necessary, for example when a menu is about to be shown.
3337 The following is an example of how to call UpdateWindowUI from
3341 void MyWindow::OnInternalIdle()
3343 if (wxUpdateUIEvent::CanUpdate(this))
3344 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
3348 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
3350 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
3355 // NOTE: static functions must have their own group or Doxygen will screw
3356 // up the ordering of the member groups
3359 @name Miscellaneous static functions
3364 Returns the default font and colours which are used by the control.
3366 This is useful if you want to use the same font or colour in your own control
3367 as in a standard control -- which is a much better idea than hard coding specific
3368 colours or fonts which might look completely out of place on the users
3369 system, especially if it uses themes.
3371 The @a variant parameter is only relevant under Mac currently and is
3372 ignore under other platforms. Under Mac, it will change the size of the
3373 returned font. See SetWindowVariant() for more about this.
3375 This static method is "overridden" in many derived classes and so calling,
3376 for example, wxButton::GetClassDefaultAttributes() will typically
3377 return the values appropriate for a button which will be normally different
3378 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
3380 The @c wxVisualAttributes structure has at least the fields
3381 @c font, @c colFg and @c colBg. All of them may be invalid
3382 if it was not possible to determine the default control appearance or,
3383 especially for the background colour, if the field doesn't make sense as is
3384 the case for @c colBg for the controls with themed background.
3386 @see InheritAttributes()
3388 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
3391 Finds the window or control which currently has the keyboard focus.
3393 @remarks Note that this is a static function, so it can be called without
3394 needing a wxWindow pointer.
3396 @see SetFocus(), HasFocus()
3398 static wxWindow
* FindFocus();
3401 Find the first window with the given @e id.
3403 If @a parent is @NULL, the search will start from all top-level frames
3404 and dialog boxes; if non-@NULL, the search will be limited to the given
3406 The search is recursive in both cases.
3410 @return Window with the given @a id or @NULL if not found.
3412 static wxWindow
* FindWindowById(long id
, const wxWindow
* parent
= 0);
3415 Find a window by its label.
3417 Depending on the type of window, the label may be a window title
3418 or panel item label. If @a parent is @NULL, the search will start from all
3419 top-level frames and dialog boxes; if non-@NULL, the search will be
3420 limited to the given window hierarchy.
3421 The search is recursive in both cases.
3425 @return Window with the given @a label or @NULL if not found.
3427 static wxWindow
* FindWindowByLabel(const wxString
& label
,
3428 const wxWindow
* parent
= 0);
3431 Find a window by its name (as given in a window constructor or Create()
3434 If @a parent is @NULL, the search will start from all top-level frames
3435 and dialog boxes; if non-@NULL, the search will be limited to the given
3438 The search is recursive in both cases. If no window with such name is found,
3439 FindWindowByLabel() is called.
3443 @return Window with the given @a name or @NULL if not found.
3445 static wxWindow
* FindWindowByName(const wxString
& name
,
3446 const wxWindow
* parent
= 0);
3449 Returns the currently captured window.
3451 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
3452 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3454 static wxWindow
* GetCapture();
3457 Create a new ID or range of IDs that are not currently in use.
3458 The IDs will be reserved until assigned to a wxWindow ID
3459 or unreserved with UnreserveControlId().
3461 See @ref overview_windowids for more information.
3464 The number of sequential IDs to reserve.
3466 @return Returns the ID or the first ID of the range (i.e. the most negative),
3467 or wxID_NONE if the specified number of identifiers couldn't be allocated.
3469 @see UnreserveControlId(), wxIdManager,
3470 @ref overview_windowids
3472 static wxWindowID
NewControlId(int count
= 1);
3475 Unreserve an ID or range of IDs that was reserved by NewControlId().
3476 See @ref overview_windowids for more information.
3479 The starting ID of the range of IDs to unreserve.
3481 The number of sequential IDs to unreserve.
3483 @see NewControlId(), wxIdManager, @ref overview_windowids
3485 static void UnreserveControlId(wxWindowID id
, int count
= 1);
3497 Specifies the direction for the centring. May be wxHORIZONTAL,
3498 wxVERTICAL or wxBOTH. It may also include the wxCENTRE_ON_SCREEN
3501 @remarks This function is not meant to be called directly by user code,
3502 but via Centre, Center, CentreOnParent, or CenterOnParent.
3503 This function can be overridden to fine-tune centring behaviour.
3505 virtual void DoCentre(int direction
);
3508 Implementation of GetBestSize() that can be overridden.
3510 Notice that it is usually more convenient to override
3511 DoGetBestClientSize() rather than this method itself as you need to
3512 explicitly account for the window borders size if you do the latter.
3514 The default implementation of this function is designed for use in container
3515 windows, such as wxPanel, and works something like this:
3516 -# If the window has a sizer then it is used to calculate the best size.
3517 -# Otherwise if the window has layout constraints then those are used to
3518 calculate the best size.
3519 -# Otherwise if the window has children then the best size is set to be large
3520 enough to show all the children.
3521 -# Otherwise if there are no children then the window's minimal size will be
3522 used as its best size.
3523 -# Otherwise if there is no minimal size set, then the current size is used
3526 @see @ref overview_windowsizing
3528 virtual wxSize
DoGetBestSize() const;
3531 Override this method to return the best size for a custom control.
3533 A typical implementation of this method should compute the minimal size
3534 needed to fully display the control contents taking into account the
3537 The default implementation simply returns ::wxDefaultSize and
3538 GetBestSize() returns an arbitrary hardcoded size for the window, so
3539 you must override it when implementing a custom window class.
3541 @see @ref overview_windowsizing
3545 virtual wxSize
DoGetBestClientSize() const;
3548 Override this method to implement height-for-width best size
3551 Return the height needed to fully display the control contents if its
3552 width is fixed to the given value. Custom classes implementing
3553 wrapping should override this method and return the height
3554 corresponding to the number of lines needed to lay out the control
3555 contents at this width.
3557 Currently this method is not used by wxWidgets yet, however it is
3558 planned that it will be used by the new sizer classes implementing
3559 height-for-width layout strategy in the future.
3561 Notice that implementing this method or even implementing both it and
3562 DoGetBestClientWidth() doesn't replace overriding DoGetBestClientSize(),
3563 i.e. you still need to implement the latter as well in order to provide
3564 the best size when neither width nor height are constrained.
3566 By default returns ::wxDefaultCoord meaning that the vertical component
3567 of DoGetBestClientSize() return value should be used.
3571 virtual int DoGetBestClientHeight(int width
) const;
3574 Override this method to implement width-for-height best size
3577 This method is exactly the same as DoGetBestClientHeight() except that
3578 it determines the width assuming the height is fixed instead of vice
3583 virtual int DoGetBestClientWidth(int height
) const;
3586 Sets the initial window size if none is given (i.e. at least one of the
3587 components of the size passed to ctor/Create() is wxDefaultCoord).
3588 @deprecated Use SetInitialSize() instead.
3590 virtual void SetInitialBestSize(const wxSize
& size
);
3593 Generate wxWindowDestroyEvent for this window.
3595 This is called by the window itself when it is being destroyed and
3596 usually there is no need to call it but see wxWindowDestroyEvent for
3597 explanations of when you might want to do it.
3599 void SendDestroyEvent();
3602 This function is public in wxEvtHandler but protected in wxWindow
3603 because for wxWindows you should always call ProcessEvent() on the
3604 pointer returned by GetEventHandler() and not on the wxWindow object
3607 For convenience, a ProcessWindowEvent() method is provided as a synonym
3608 for @code GetEventHandler()->ProcessEvent() @endcode
3610 Note that it's still possible to call these functions directly on the
3611 wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
3612 create subtle bugs when windows with event handlers pushed on them are
3615 This holds also for all other wxEvtHandler functions.
3617 virtual bool ProcessEvent(wxEvent
& event
);
3621 See ProcessEvent() for more info about why you shouldn't use this function
3622 and the reason for making this function protected in wxWindow.
3624 bool SafelyProcessEvent(wxEvent
& event
);
3625 virtual void QueueEvent(wxEvent
*event
);
3626 virtual void AddPendingEvent(const wxEvent
& event
);
3627 void ProcessPendingEvents();
3628 bool ProcessThreadEvent(const wxEvent
& event
);
3634 // ============================================================================
3635 // Global functions/macros
3636 // ============================================================================
3638 /** @addtogroup group_funcmacro_misc */
3642 Find the deepest window at the mouse pointer position, returning the window
3643 and current pointer position in screen coordinates.
3645 @header{wx/window.h}
3647 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
3650 Gets the currently active window (implemented for MSW and GTK only
3651 currently, always returns @NULL in the other ports).
3653 @header{wx/window.h}
3655 wxWindow
* wxGetActiveWindow();
3658 Returns the first top level parent of the given window, or in other words,
3659 the frame or dialog containing it, or @NULL.
3661 @header{wx/window.h}
3663 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);