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
56 Struct containing all the visual attributes of a control.
58 struct wxVisualAttributes
60 /// The font used for control label/text inside it.
63 /// The foreground colour.
67 The background colour.
69 May be wxNullColour if the controls background colour is not solid.
76 Different window variants, on platforms like eg mac uses different
81 wxWINDOW_VARIANT_NORMAL
, //!< Normal size
82 wxWINDOW_VARIANT_SMALL
, //!< Smaller size (about 25 % smaller than normal)
83 wxWINDOW_VARIANT_MINI
, //!< Mini size (about 33 % smaller than normal)
84 wxWINDOW_VARIANT_LARGE
, //!< Large size (about 25 % larger than normal)
92 wxWindow is the base class for all windows and represents any visible object
93 on screen. All controls, top level windows and so on are windows. Sizers and
94 device contexts are not, however, as they don't appear on screen themselves.
96 Please note that all children of the window will be deleted automatically by
97 the destructor before the window itself is deleted which means that you don't
98 have to worry about deleting them manually. Please see the @ref
99 overview_windowdeletion "window deletion overview" for more information.
101 Also note that in this, and many others, wxWidgets classes some
102 @c GetXXX() methods may be overloaded (as, for example,
103 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
104 are non-virtual because having multiple virtual functions with the same name
105 results in a virtual function name hiding at the derived class level (in
106 English, this means that the derived class has to override all overloaded
107 variants if it overrides any of them). To allow overriding them in the derived
108 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
109 and all @c GetXXX() ones are forwarded to it, so overriding the former
110 changes the behaviour of the latter.
113 @style{wxBORDER_DEFAULT}
114 The window class will decide the kind of border to show, if any.
115 @style{wxBORDER_SIMPLE}
116 Displays a thin border around the window. wxSIMPLE_BORDER is the
117 old name for this style.
118 @style{wxBORDER_SUNKEN}
119 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
121 @style{wxBORDER_RAISED}
122 Displays a raised border. wxRAISED_BORDER is the old name for this
124 @style{wxBORDER_STATIC}
125 Displays a border suitable for a static control. wxSTATIC_BORDER
126 is the old name for this style. Windows only.
127 @style{wxBORDER_THEME}
128 Displays a native border suitable for a control, on the current
129 platform. On Windows XP or Vista, this will be a themed border; on
130 most other platforms a sunken border will be used. For more
131 information for themed borders on Windows, please see Themed
133 @style{wxBORDER_NONE}
134 Displays no border, overriding the default border style for the
135 window. wxNO_BORDER is the old name for this style.
136 @style{wxBORDER_DOUBLE}
137 This style is obsolete and should not be used.
138 @style{wxTRANSPARENT_WINDOW}
139 The window is transparent, that is, it will not receive paint
140 events. Windows only.
141 @style{wxTAB_TRAVERSAL}
142 Use this to enable tab traversal for non-dialog windows.
143 @style{wxWANTS_CHARS}
144 Use this to indicate that the window wants to get all char/key
145 events for all keys - even for keys like TAB or ENTER which are
146 usually used for dialog navigation and which wouldn't be generated
147 without this style. If you need to use this style in order to get
148 the arrows or etc., but would still like to have normal keyboard
149 navigation take place, you should call Navigate in response to the
150 key events for Tab and Shift-Tab.
151 @style{wxNO_FULL_REPAINT_ON_RESIZE}
152 On Windows, this style used to disable repainting the window
153 completely when its size is changed. Since this behaviour is now
154 the default, the style is now obsolete and no longer has an effect.
156 Use this style to enable a vertical scrollbar. Notice that this
157 style cannot be used with native controls which don't support
158 scrollbars nor with top-level windows in most ports.
160 Use this style to enable a horizontal scrollbar. The same
161 limitations as for wxVSCROLL apply to this style.
162 @style{wxALWAYS_SHOW_SB}
163 If a window has scrollbars, disable them instead of hiding them
164 when they are not needed (i.e. when the size of the window is big
165 enough to not require the scrollbars to navigate it). This style is
166 currently implemented for wxMSW, wxGTK and wxUniversal and does
167 nothing on the other platforms.
168 @style{wxCLIP_CHILDREN}
169 Use this style to eliminate flicker caused by the background being
170 repainted, then children being painted over them. Windows only.
171 @style{wxFULL_REPAINT_ON_RESIZE}
172 Use this style to force a complete redraw of the window whenever it
173 is resized instead of redrawing just the part of the window
174 affected by resizing. Note that this was the behaviour by default
175 before 2.5.1 release and that if you experience redraw problems
176 with code which previously used to work you may want to try this.
177 Currently this style applies on GTK+ 2 and Windows only, and full
178 repainting is always done on other platforms.
181 @beginExtraStyleTable
182 @style{wxWS_EX_VALIDATE_RECURSIVELY}
183 By default, wxWindow::Validate(), wxWindow::TransferDataTo() and
184 wxWindow::TransferDataFromWindow() only work on
185 direct children of the window (compatible behaviour).
186 Set this flag to make them recursively descend into all subwindows.
187 @style{wxWS_EX_BLOCK_EVENTS}
188 wxCommandEvents and the objects of the derived classes are
189 forwarded to the parent window and so on recursively by default.
190 Using this flag for the given window allows to block this
191 propagation at this window, i.e. prevent the events from being
192 propagated further upwards. Dialogs have this flag on by default
193 for the reasons explained in the @ref overview_events.
194 @style{wxWS_EX_TRANSIENT}
195 Don't use this window as an implicit parent for the other windows:
196 this must be used with transient windows as otherwise there is the
197 risk of creating a dialog/frame with this window as a parent, which
198 would lead to a crash if the parent were destroyed before the child.
199 @style{wxWS_EX_CONTEXTHELP}
200 Under Windows, puts a query button on the caption. When pressed,
201 Windows will go into a context-sensitive help mode and wxWidgets
202 will send a @c wxEVT_HELP event if the user clicked on an application window.
203 This style cannot be used (because of the underlying native behaviour)
204 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
205 are automatically turned off if this one is used.
206 @style{wxWS_EX_PROCESS_IDLE}
207 This window should always process idle events, even if the mode set
208 by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED.
209 @style{wxWS_EX_PROCESS_UI_UPDATES}
210 This window should always process UI update events, even if the
211 mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED.
214 @beginEventEmissionTable
215 @event{EVT_ACTIVATE(id, func)}
216 Process a @c wxEVT_ACTIVATE event. See wxActivateEvent.
217 @event{EVT_CHILD_FOCUS(func)}
218 Process a @c wxEVT_CHILD_FOCUS event. See wxChildFocusEvent.
219 @event{EVT_CONTEXT_MENU(func)}
220 A right click (or other context menu command depending on platform) has been detected.
221 See wxContextMenuEvent.
222 @event{EVT_HELP(id, func)}
223 Process a @c wxEVT_HELP event. See wxHelpEvent.
224 @event{EVT_HELP_RANGE(id1, id2, func)}
225 Process a @c wxEVT_HELP event for a range of ids. See wxHelpEvent.
226 @event{EVT_DROP_FILES(func)}
227 Process a @c wxEVT_DROP_FILES event. See wxDropFilesEvent.
228 @event{EVT_ERASE_BACKGROUND(func)}
229 Process a @c wxEVT_ERASE_BACKGROUND event. See wxEraseEvent.
230 @event{EVT_SET_FOCUS(func)}
231 Process a @c wxEVT_SET_FOCUS event. See wxFocusEvent.
232 @event{EVT_KILL_FOCUS(func)}
233 Process a @c wxEVT_KILL_FOCUS event. See wxFocusEvent.
234 @event{EVT_IDLE(func)}
235 Process a @c wxEVT_IDLE event. See wxIdleEvent.
236 @event{EVT_JOY_*(func)}
237 Processes joystick events. See wxJoystickEvent.
238 @event{EVT_KEY_DOWN(func)}
239 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
241 @event{EVT_KEY_UP(func)}
242 Process a @c wxEVT_KEY_UP event (any key has been released).
244 @event{EVT_CHAR(func)}
245 Process a @c wxEVT_CHAR event.
247 @event{EVT_CHAR_HOOK(func)}
248 Process a @c wxEVT_CHAR_HOOK event.
250 @event{EVT_MOUSE_CAPTURE_LOST(func)}
251 Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
252 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
253 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. See wxMouseCaptureChangedEvent.
254 @event{EVT_MOUSE_*(func)}
256 @event{EVT_PAINT(func)}
257 Process a @c wxEVT_PAINT event. See wxPaintEvent.
258 @event{EVT_POWER_*(func)}
259 The system power state changed. See wxPowerEvent.
260 @event{EVT_SCROLLWIN_*(func)}
261 Process scroll events. See wxScrollWinEvent.
262 @event{EVT_SET_CURSOR(func)}
263 Process a @c wxEVT_SET_CURSOR event. See wxSetCursorEvent.
264 @event{EVT_SIZE(func)}
265 Process a @c wxEVT_SIZE event. See wxSizeEvent.
266 @event{EVT_SYS_COLOUR_CHANGED(func)}
267 Process a @c wxEVT_SYS_COLOUR_CHANGED event. See wxSysColourChangedEvent.
273 @see @ref overview_events, @ref overview_windowsizing
275 class wxWindow
: public wxEvtHandler
284 Constructs a window, which can be a child of a frame, dialog or any other
288 Pointer to a parent window.
290 Window identifier. If wxID_ANY, will automatically create an identifier.
292 Window position. wxDefaultPosition indicates that wxWidgets
293 should generate a default position for the window.
294 If using the wxWindow class directly, supply an actual position.
296 Window size. wxDefaultSize indicates that wxWidgets should generate
297 a default size for the window. If no suitable size can be found, the
298 window will be sized to 20x20 pixels so that the window is visible but
299 obviously not correctly sized.
301 Window style. For generic window styles, please see wxWindow.
305 wxWindow(wxWindow
* parent
, wxWindowID id
,
306 const wxPoint
& pos
= wxDefaultPosition
,
307 const wxSize
& size
= wxDefaultSize
,
309 const wxString
& name
= wxPanelNameStr
);
314 Deletes all sub-windows, then deletes itself. Instead of using
315 the @b delete operator explicitly, you should normally use Destroy()
316 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
318 @see @ref overview_windowdeletion "Window Deletion Overview",
319 Destroy(), wxCloseEvent
324 bool Create(wxWindow
*parent
,
326 const wxPoint
& pos
= wxDefaultPosition
,
327 const wxSize
& size
= wxDefaultSize
,
329 const wxString
& name
= wxPanelNameStr
);
332 @name Focus functions
334 See also the static function FindFocus().
339 This method may be overridden in the derived classes to return @false to
340 indicate that this control doesn't accept input at all (i.e. behaves like
341 e.g. wxStaticText) and so doesn't need focus.
343 @see AcceptsFocusFromKeyboard()
345 virtual bool AcceptsFocus() const;
348 This method may be overridden in the derived classes to return @false to
349 indicate that while this control can, in principle, have focus if the user
350 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
351 when using the keyboard.
353 virtual bool AcceptsFocusFromKeyboard() const;
356 Overridden to indicate whether this window or one of its children accepts
357 focus. Usually it's the same as AcceptsFocus() but is overridden for
360 virtual bool AcceptsFocusRecursively() const;
363 Returns @true if the window (or in case of composite controls, its main
364 child window) has focus.
368 virtual bool HasFocus() const;
371 This method is only implemented by ports which have support for
372 native TAB traversal (such as GTK+ 2.0).
374 It is called by wxWidgets' container control code to give the native
375 system a hint when doing TAB traversal. A call to this does not disable
376 or change the effect of programmatically calling SetFocus().
378 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
380 virtual void SetCanFocus(bool canFocus
);
383 This sets the window to receive keyboard input.
385 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
386 wxPanel::SetFocusIgnoringChildren
388 virtual void SetFocus();
391 This function is called by wxWidgets keyboard navigation code when the user
392 gives the focus to this window from keyboard (e.g. using @c TAB key).
394 By default this method simply calls SetFocus() but
395 can be overridden to do something in addition to this in the derived classes.
397 virtual void SetFocusFromKbd();
403 @name Child management functions
408 Adds a child window. This is called automatically by window creation
409 functions so should not be required by the application programmer.
410 Notice that this function is mostly internal to wxWidgets and shouldn't be
411 called by the user code.
416 virtual void AddChild(wxWindow
* child
);
419 Destroys all children of a window. Called automatically by the destructor.
421 bool DestroyChildren();
424 Find a child of this window, by @a id.
425 May return @a this if it matches itself.
427 wxWindow
* FindWindow(long id
) const;
430 Find a child of this window, by name.
431 May return @a this if it matches itself.
433 wxWindow
* FindWindow(const wxString
& name
) const;
436 Returns a reference to the list of the window's children. @c wxWindowList
437 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
439 wxWindowList
& GetChildren();
444 const wxWindowList
& GetChildren() const;
447 Removes a child window.
449 This is called automatically by window deletion functions so should not
450 be required by the application programmer.
451 Notice that this function is mostly internal to wxWidgets and shouldn't be
452 called by the user code.
455 Child window to remove.
457 virtual void RemoveChild(wxWindow
* child
);
463 @name Sibling and parent management functions
468 Returns the grandparent of a window, or @NULL if there isn't one.
470 wxWindow
* GetGrandParent() const;
473 Returns the next window after this one among the parent's children or @NULL
474 if this window is the last child.
478 @see GetPrevSibling()
480 wxWindow
* GetNextSibling() const;
483 Returns the parent of the window, or @NULL if there is no parent.
485 wxWindow
* GetParent() const;
488 Returns the previous window before this one among the parent's children or @c
489 @NULL if this window is the first child.
493 @see GetNextSibling()
495 wxWindow
* GetPrevSibling() const;
498 Check if the specified window is a descendant of this one.
500 Returns @true if the window is a descendant (i.e. a child or
501 grand-child or grand-grand-child or ...) of this one.
503 Notice that a window can never be a descendant of another one if they
504 are in different top level windows, i.e. a child of a wxDialog is not
505 considered to be a descendant of dialogs parent wxFrame.
507 @param win Any window, possible @NULL (@false is always returned then).
511 bool IsDescendant(wxWindowBase
* win
) const;
514 Reparents the window, i.e. the window will be removed from its
515 current parent window (e.g. a non-standard toolbar in a wxFrame)
516 and then re-inserted into another.
518 Notice that currently you need to explicitly call
519 wxNotebook::RemovePage() before reparenting a notebook page.
524 virtual bool Reparent(wxWindow
* newParent
);
530 @name Scrolling and scrollbars functions
532 Note that these methods don't work with native controls which don't use
533 wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
538 Call this function to force one or both scrollbars to be always shown, even if
539 the window is big enough to show its entire contents without scrolling.
544 Whether the horizontal scroll bar should always be visible.
546 Whether the vertical scroll bar should always be visible.
548 @remarks This function is currently only implemented under Mac/Carbon.
550 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
553 Returns the built-in scrollbar position.
557 virtual int GetScrollPos(int orientation
) const;
560 Returns the built-in scrollbar range.
564 virtual int GetScrollRange(int orientation
) const;
567 Returns the built-in scrollbar thumb size.
571 virtual int GetScrollThumb(int orientation
) const;
574 Returns @true if this window can have a scroll bar in this orientation.
577 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
581 bool CanScroll(int orient
) const;
584 Returns @true if this window currently has a scroll bar for this
587 This method may return @false even when CanScroll() for the same
588 orientation returns @true, but if CanScroll() returns @false, i.e.
589 scrolling in this direction is not enabled at all, HasScrollbar()
590 always returns @false as well.
593 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
595 bool HasScrollbar(int orient
) const;
598 Return whether a scrollbar is always shown.
601 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
603 @see AlwaysShowScrollbars()
605 virtual bool IsScrollbarAlwaysShown(int orient
) const;
608 Scrolls the window by the given number of lines down (if @a lines is
611 @return Returns @true if the window was scrolled, @false if it was already
612 on top/bottom and nothing was done.
614 @remarks This function is currently only implemented under MSW and
615 wxTextCtrl under wxGTK (it also works for wxScrolled classes
616 under all platforms).
620 virtual bool ScrollLines(int lines
);
623 Scrolls the window by the given number of pages down (if @a pages is
626 @return Returns @true if the window was scrolled, @false if it was already
627 on top/bottom and nothing was done.
629 @remarks This function is currently only implemented under MSW and wxGTK.
633 virtual bool ScrollPages(int pages
);
636 Physically scrolls the pixels in the window and move child windows accordingly.
639 Amount to scroll horizontally.
641 Amount to scroll vertically.
643 Rectangle to scroll, if it is @NULL, the whole window is
644 scrolled (this is always the case under wxGTK which doesn't support this
647 @remarks Note that you can often use wxScrolled instead of using this
650 virtual void ScrollWindow(int dx
, int dy
,
651 const wxRect
* rect
= NULL
);
654 Same as #ScrollLines (-1).
659 Same as #ScrollLines (1).
664 Same as #ScrollPages (-1).
669 Same as #ScrollPages (1).
674 Sets the position of one of the built-in scrollbars.
677 Determines the scrollbar whose position is to be set.
678 May be wxHORIZONTAL or wxVERTICAL.
680 Position in scroll units.
682 @true to redraw the scrollbar, @false otherwise.
684 @remarks This function does not directly affect the contents of the
685 window: it is up to the application to take note of
686 scrollbar attributes and redraw contents accordingly.
688 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
691 virtual void SetScrollPos(int orientation
, int pos
,
692 bool refresh
= true);
695 Sets the scrollbar properties of a built-in scrollbar.
698 Determines the scrollbar whose page size is to be set.
699 May be wxHORIZONTAL or wxVERTICAL.
701 The position of the scrollbar in scroll units.
703 The size of the thumb, or visible portion of the scrollbar, in scroll units.
705 The maximum position of the scrollbar. Value of -1 can be used to
706 ask for the scrollbar to be shown but in the disabled state: this
707 can be used to avoid removing the scrollbar even when it is not
708 needed (currently this is only implemented in wxMSW port).
710 @true to redraw the scrollbar, @false otherwise.
713 Let's say you wish to display 50 lines of text, using the same font.
714 The window is sized so that you can only see 16 lines at a time.
717 SetScrollbar(wxVERTICAL, 0, 16, 50);
719 Note that with the window at this size, the thumb position can never
720 go above 50 minus 16, or 34. You can determine how many lines are
721 currently visible by dividing the current view size by the character
723 When defining your own scrollbar behaviour, you will always need
724 to recalculate the scrollbar settings when the window size changes.
725 You could therefore put your scrollbar calculations and SetScrollbar
726 call into a function named AdjustScrollbars, which can be called
727 initially and also from your wxSizeEvent handler function.
729 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
731 virtual void SetScrollbar(int orientation
, int position
,
732 int thumbSize
, int range
,
733 bool refresh
= true);
738 @name Sizing functions
740 See also the protected functions DoGetBestSize() and
741 DoGetBestClientSize().
746 Sets the cached best size value.
750 void CacheBestSize(const wxSize
& size
) const;
753 Converts client area size @a size to corresponding window size.
755 In other words, the returned value is what would GetSize() return if this
756 window had client area of given size. Components with wxDefaultCoord
757 value are left unchanged. Note that the conversion is not always
758 exact, it assumes that non-client area doesn't change and so doesn't
759 take into account things like menu bar (un)wrapping or (dis)appearance
764 @see WindowToClientSize()
766 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
769 Converts window size @a size to corresponding client area size
770 In other words, the returned value is what would GetClientSize() return if
771 this window had given window size. Components with wxDefaultCoord value
774 Note that the conversion is not always exact, it assumes that
775 non-client area doesn't change and so doesn't take into account things
776 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
780 @see ClientToWindowSize()
782 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
785 Sizes the window so that it fits around its subwindows.
787 This function won't do anything if there are no subwindows and will only really
788 work correctly if sizers are used for the subwindows layout.
790 Also, if the window has exactly one subwindow it is better (faster and the result
791 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
795 window->SetClientSize(child->GetSize());
798 instead of calling Fit().
800 @see @ref overview_windowsizing
805 Similar to Fit(), but sizes the interior (virtual) size of a window.
807 Mainly useful with scrolled windows to reset scrollbars after sizing
808 changes that do not trigger a size event, and/or scrolled windows without
809 an interior sizer. This function similarly won't do anything if there are
812 virtual void FitInside();
815 This functions returns the best acceptable minimal size for the window.
817 For example, for a static control, it will be the minimal size such that the
818 control label is not truncated. For windows containing subwindows (typically
819 wxPanel), the size returned by this function will be the same as the size
820 the window would have had after calling Fit().
822 Override virtual DoGetBestSize() or, better, because it's usually more
823 convenient, DoGetBestClientSize() when writing your own custom window
824 class to change the value returned by this public non-virtual method.
826 @see CacheBestSize(), @ref overview_windowsizing
828 wxSize
GetBestSize() const;
831 Returns the size of the window 'client area' in pixels.
833 The client area is the area which may be drawn on by the programmer,
834 excluding title bar, border, scrollbars, etc.
835 Note that if this window is a top-level one and it is currently minimized, the
836 return size is empty (both width and height are 0).
839 In wxPerl this method takes no parameters and returns
840 a 2-element list (width, height).
843 @see GetSize(), GetVirtualSize()
845 void GetClientSize(int* width
, int* height
) const;
850 wxSize
GetClientSize() const;
853 Merges the window's best size into the min size and returns the result.
854 This is the value used by sizers to determine the appropriate
855 amount of space to allocate for the widget.
857 This is the method called by a wxSizer when it queries the size
858 of a window or control.
860 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
862 virtual wxSize
GetEffectiveMinSize() const;
865 Returns the maximum size of window's client area.
867 This is an indication to the sizer layout mechanism that this is the maximum
868 possible size as well as the upper bound on window's size settable using
871 @see GetMaxSize(), @ref overview_windowsizing
873 virtual wxSize
GetMaxClientSize() const;
876 Returns the maximum size of the window.
878 This is an indication to the sizer layout mechanism that this is the maximum
879 possible size as well as the upper bound on window's size settable using SetSize().
881 @see GetMaxClientSize(), @ref overview_windowsizing
883 virtual wxSize
GetMaxSize() const;
886 Returns the minimum size of window's client area, an indication to the sizer
887 layout mechanism that this is the minimum required size of its client area.
889 It normally just returns the value set by SetMinClientSize(), but it can be
890 overridden to do the calculation on demand.
892 @see GetMinSize(), @ref overview_windowsizing
894 virtual wxSize
GetMinClientSize() const;
897 Returns the minimum size of the window, an indication to the sizer layout
898 mechanism that this is the minimum required size.
900 This method normally just returns the value set by SetMinSize(), but it
901 can be overridden to do the calculation on demand.
903 @see GetMinClientSize(), @ref overview_windowsizing
905 virtual wxSize
GetMinSize() const;
907 int GetMinWidth() const;
908 int GetMinHeight() const;
909 int GetMaxWidth() const;
910 int GetMaxHeight() const;
913 Returns the size of the entire window in pixels, including title bar, border,
916 Note that if this window is a top-level one and it is currently minimized, the
917 returned size is the restored window size, not the size of the window icon.
920 Receives the window width.
922 Receives the window height.
925 In wxPerl this method is implemented as GetSizeWH() returning
926 a 2-element list (width, height).
929 @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
931 void GetSize(int* width
, int* height
) const;
934 See the GetSize(int*,int*) overload for more info.
936 wxSize
GetSize() const;
939 This gets the virtual size of the window in pixels.
940 By default it returns the client size of the window, but after a call to
941 SetVirtualSize() it will return the size set with that method.
943 @see @ref overview_windowsizing
945 wxSize
GetVirtualSize() const;
948 Like the other GetVirtualSize() overload but uses pointers instead.
951 Receives the window virtual width.
953 Receives the window virtual height.
955 void GetVirtualSize(int* width
, int* height
) const;
958 Return the largest of ClientSize and BestSize (as determined
959 by a sizer, interior children, or other means)
961 virtual wxSize
GetBestVirtualSize() const;
964 Returns the size of the left/right and top/bottom borders of this window in x
965 and y components of the result respectively.
967 virtual wxSize
GetWindowBorderSize() const;
970 wxSizer and friends use this to give a chance to a component to recalc
971 its min size once one of the final size components is known. Override
972 this function when that is useful (such as for wxStaticText which can
973 stretch over several lines). Parameter availableOtherDir
974 tells the item how much more space there is available in the opposite
975 direction (-1 if unknown).
978 InformFirstDirection(int direction
,
980 int availableOtherDir
);
983 Resets the cached best size value so it will be recalculated the next time it
988 void InvalidateBestSize();
991 Posts a size event to the window.
993 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
995 void PostSizeEvent();
998 Posts a size event to the parent of this window.
1000 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
1003 void PostSizeEventToParent();
1006 This function sends a dummy @ref wxSizeEvent "size event" to
1007 the window allowing it to re-layout its children positions.
1009 It is sometimes useful to call this function after adding or deleting a
1010 children after the frame creation or if a child size changes. Note that
1011 if the frame is using either sizers or constraints for the children
1012 layout, it is enough to call wxWindow::Layout() directly and this
1013 function should not be used in this case.
1015 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
1016 the event, i.e. schedules it for later processing, instead of
1017 dispatching it directly. You can also use PostSizeEvent() as a more
1018 readable equivalent of calling this function with this flag.
1021 May include @c wxSEND_EVENT_POST. Default value is 0.
1023 virtual void SendSizeEvent(int flags
= 0);
1026 Safe wrapper for GetParent()->SendSizeEvent().
1028 This function simply checks that the window has a valid parent which is
1029 not in process of being deleted and calls SendSizeEvent() on it. It is
1030 used internally by windows such as toolbars changes to whose state
1031 should result in parent re-layout (e.g. when a toolbar is added to the
1032 top of the window, all the other windows must be shifted down).
1034 @see PostSizeEventToParent()
1037 See description of this parameter in SendSizeEvent() documentation.
1039 void SendSizeEventToParent(int flags
= 0);
1042 This sets the size of the window client area in pixels.
1044 Using this function to size a window tends to be more device-independent
1045 than SetSize(), since the application need not worry about what dimensions
1046 the border or title bar have when trying to fit the window around panel
1049 @see @ref overview_windowsizing
1051 void SetClientSize(int width
, int height
);
1056 void SetClientSize(const wxSize
& size
);
1061 void SetClientSize(const wxRect
& rect
);
1064 This normally does not need to be called by user code.
1065 It is called when a window is added to a sizer, and is used so the window
1066 can remove itself from the sizer when it is destroyed.
1068 void SetContainingSizer(wxSizer
* sizer
);
1071 A @e smart SetSize that will fill in default size components with the
1072 window's @e best size values.
1074 Also sets the window's minsize to the value passed in for use with sizers.
1075 This means that if a full or partial size is passed to this function then
1076 the sizers will use that size instead of the results of GetBestSize() to
1077 determine the minimum needs of the window for layout.
1079 Most controls will use this to set their initial size, and their min
1080 size to the passed in value (if any.)
1082 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
1083 @ref overview_windowsizing
1085 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
1088 Sets the maximum client size of the window, to indicate to the sizer
1089 layout mechanism that this is the maximum possible size of its client area.
1091 Note that this method is just a shortcut for:
1093 SetMaxSize(ClientToWindowSize(size));
1096 @see SetMaxSize(), @ref overview_windowsizing
1098 virtual void SetMaxClientSize(const wxSize
& size
);
1101 Sets the maximum size of the window, to indicate to the sizer layout mechanism
1102 that this is the maximum possible size.
1104 @see SetMaxClientSize(), @ref overview_windowsizing
1106 virtual void SetMaxSize(const wxSize
& size
);
1109 Sets the minimum client size of the window, to indicate to the sizer
1110 layout mechanism that this is the minimum required size of window's client
1113 You may need to call this if you change the window size after
1114 construction and before adding to its parent sizer.
1116 Note, that just as with SetMinSize(), calling this method doesn't
1117 prevent the program from explicitly making the window smaller than the
1120 Note that this method is just a shortcut for:
1122 SetMinSize(ClientToWindowSize(size));
1125 @see SetMinSize(), @ref overview_windowsizing
1127 virtual void SetMinClientSize(const wxSize
& size
);
1130 Sets the minimum size of the window, to indicate to the sizer layout
1131 mechanism that this is the minimum required size.
1133 You may need to call this if you change the window size after
1134 construction and before adding to its parent sizer.
1136 Notice that calling this method doesn't prevent the program from making
1137 the window explicitly smaller than the specified size by calling
1138 SetSize(), it just ensures that it won't become smaller than this size
1139 during the automatic layout.
1141 @see SetMinClientSize(), @ref overview_windowsizing
1143 virtual void SetMinSize(const wxSize
& size
);
1146 Sets the size of the window in pixels.
1149 Required x position in pixels, or wxDefaultCoord to indicate that the
1150 existing value should be used.
1152 Required y position in pixels, or wxDefaultCoord to indicate that the
1153 existing value should be used.
1155 Required width in pixels, or wxDefaultCoord to indicate that the existing
1156 value should be used.
1158 Required height position in pixels, or wxDefaultCoord to indicate that the
1159 existing value should be used.
1161 Indicates the interpretation of other parameters.
1162 It is a bit list of the following:
1163 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
1164 a wxWidgets-supplied default width.
1165 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
1166 a wxWidgets-supplied default height.
1167 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1168 a wxWidgets-supplied default size.
1169 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1170 if wxDefaultCoord values are supplied.
1171 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1172 wxDefaultCoord) to be interpreted as real
1173 dimensions, not default values.
1174 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1175 already the same as the parameters of this function,
1176 nothing is done. but with this flag a window resize may
1177 be forced even in this case (supported in wx 2.6.2 and
1178 later and only implemented for MSW and ignored elsewhere
1181 @remarks This overload sets the position and optionally size, of the window.
1182 Parameters may be wxDefaultCoord to indicate either that a default
1183 should be supplied by wxWidgets, or that the current value of the
1184 dimension should be used.
1186 @see Move(), @ref overview_windowsizing
1188 void SetSize(int x
, int y
, int width
, int height
,
1189 int sizeFlags
= wxSIZE_AUTO
);
1192 Sets the size of the window in pixels.
1193 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1195 @remarks This form must be used with non-default width and height values.
1197 @see Move(), @ref overview_windowsizing
1199 void SetSize(const wxRect
& rect
);
1204 void SetSize(const wxSize
& size
);
1209 void SetSize(int width
, int height
);
1212 Use of this function for windows which are not toplevel windows
1213 (such as wxDialog or wxFrame) is discouraged.
1214 Please use SetMinSize() and SetMaxSize() instead.
1216 @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
1218 virtual void SetSizeHints( const wxSize
& minSize
,
1219 const wxSize
& maxSize
=wxDefaultSize
,
1220 const wxSize
& incSize
=wxDefaultSize
);
1221 virtual void SetSizeHints( int minW
, int minH
,
1222 int maxW
= -1, int maxH
= -1,
1223 int incW
= -1, int incH
= -1 );
1226 Sets the virtual size of the window in pixels.
1228 @see @ref overview_windowsizing
1230 void SetVirtualSize(int width
, int height
);
1235 void SetVirtualSize(const wxSize
& size
);
1241 @name Positioning functions
1246 A synonym for Centre().
1248 void Center(int dir
= wxBOTH
);
1251 A synonym for CentreOnParent().
1253 void CenterOnParent(int dir
= wxBOTH
);
1259 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1260 or wxBOTH. It may also include the wxCENTRE_ON_SCREEN flag
1261 if you want to centre the window on the entire screen and not on its
1264 @remarks If the window is a top level one (i.e. doesn't have a parent),
1265 it will be centred relative to the screen anyhow.
1269 void Centre(int direction
= wxBOTH
);
1272 Centres the window on its parent. This is a more readable synonym for Centre().
1275 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1278 @remarks This methods provides for a way to centre top level windows over
1279 their parents instead of the entire screen. If there
1280 is no parent or if the window is not a top level
1281 window, then behaviour is the same as Centre().
1283 @see wxTopLevelWindow::CentreOnScreen
1285 void CentreOnParent(int direction
= wxBOTH
);
1288 This gets the position of the window in pixels, relative to the parent window
1289 for the child windows or relative to the display origin for the top level windows.
1292 Receives the x position of the window if non-@NULL.
1294 Receives the y position of the window if non-@NULL.
1297 In wxPerl this method is implemented as GetPositionXY() returning
1298 a 2-element list (x, y).
1301 @see GetScreenPosition()
1303 void GetPosition(int* x
, int* y
) const;
1306 This gets the position of the window in pixels, relative to the parent window
1307 for the child windows or relative to the display origin for the top level windows.
1309 @see GetScreenPosition()
1311 wxPoint
GetPosition() const;
1314 Returns the position and size of the window as a wxRect object.
1316 @see GetScreenRect()
1318 wxRect
GetRect() const;
1321 Returns the window position in screen coordinates, whether the window is a
1322 child window or a top level one.
1325 Receives the x position of the window on the screen if non-@NULL.
1327 Receives the y position of the window on the screen if non-@NULL.
1331 void GetScreenPosition(int* x
, int* y
) const;
1334 Returns the window position in screen coordinates, whether the window is a
1335 child window or a top level one.
1339 wxPoint
GetScreenPosition() const;
1342 Returns the position and size of the window on the screen as a wxRect object.
1346 wxRect
GetScreenRect() const;
1349 Get the origin of the client area of the window relative to the
1350 window top left corner (the client area may be shifted because of
1351 the borders, scrollbars, other decorations...)
1353 virtual wxPoint
GetClientAreaOrigin() const;
1356 Get the client rectangle in window (i.e. client) coordinates
1358 wxRect
GetClientRect() const;
1363 Moves the window to the given position.
1366 Required x position.
1368 Required y position.
1370 See SetSize() for more info about this parameter.
1372 @remarks Implementations of SetSize can also implicitly implement the
1373 Move() function, which is defined in the base wxWindow class as the call:
1375 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1380 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1383 Moves the window to the given position.
1386 wxPoint object representing the position.
1388 See SetSize() for more info about this parameter.
1390 @remarks Implementations of SetSize() can also implicitly implement the
1391 Move() function, which is defined in the base wxWindow class as the call:
1393 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1398 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1400 void SetPosition(const wxPoint
& pt
);
1406 @name Coordinate conversion functions
1411 Converts to screen coordinates from coordinates relative to this window.
1414 A pointer to a integer value for the x coordinate. Pass the client
1415 coordinate in, and a screen coordinate will be passed out.
1417 A pointer to a integer value for the y coordinate. Pass the client
1418 coordinate in, and a screen coordinate will be passed out.
1421 In wxPerl this method returns a 2-element list instead of
1422 modifying its parameters.
1425 void ClientToScreen(int* x
, int* y
) const;
1428 Converts to screen coordinates from coordinates relative to this window.
1431 The client position for the second form of the function.
1433 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
1436 Converts a point or size from dialog units to pixels.
1438 For the x dimension, the dialog units are multiplied by the average character
1439 width and then divided by 4.
1440 For the y dimension, the dialog units are multiplied by the average character
1441 height and then divided by 8.
1443 @remarks Dialog units are used for maintaining a dialog's proportions
1444 even if the font changes.
1445 You can also use these functions programmatically.
1446 A convenience macro is defined:
1448 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1451 @see ConvertPixelsToDialog()
1453 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
) const;
1458 wxSize
ConvertDialogToPixels(const wxSize
& sz
) const;
1461 Converts a point or size from pixels to dialog units.
1463 For the x dimension, the pixels are multiplied by 4 and then divided by the
1464 average character width.
1465 For the y dimension, the pixels are multiplied by 8 and then divided by the
1466 average character height.
1468 @remarks Dialog units are used for maintaining a dialog's proportions
1469 even if the font changes.
1471 @see ConvertDialogToPixels()
1473 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
) const;
1478 wxSize
ConvertPixelsToDialog(const wxSize
& sz
) const;
1481 Converts from screen to client window coordinates.
1484 Stores the screen x coordinate and receives the client x coordinate.
1486 Stores the screen x coordinate and receives the client x coordinate.
1488 void ScreenToClient(int* x
, int* y
) const;
1491 Converts from screen to client window coordinates.
1494 The screen position.
1496 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1502 @name Drawing-related functions
1507 Clears the window by filling it with the current background colour.
1509 Does not cause an erase background event to be generated.
1511 Notice that this uses wxClientDC to draw on the window and the results
1512 of doing it while also drawing on wxPaintDC for this window are
1513 undefined. Hence this method shouldn't be used from EVT_PAINT handlers,
1514 just use wxDC::Clear() on the wxPaintDC you already use there instead.
1516 virtual void ClearBackground();
1519 Freezes the window or, in other words, prevents any updates from taking
1520 place on screen, the window is not redrawn at all.
1522 Thaw() must be called to reenable window redrawing. Calls to these two
1523 functions may be nested but to ensure that the window is properly
1524 repainted again, you must thaw it exactly as many times as you froze it.
1526 If the window has any children, they are recursively frozen too.
1528 This method is useful for visual appearance optimization (for example,
1529 it is a good idea to use it before doing many large text insertions in
1530 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1531 platforms nor for all controls so it is mostly just a hint to wxWidgets
1532 and not a mandatory directive.
1534 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1539 Re-enables window updating after a previous call to Freeze().
1541 To really thaw the control, it must be called exactly the same number
1542 of times as Freeze().
1544 If the window has any children, they are recursively thawed too.
1546 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1551 Returns @true if the window is currently frozen by a call to Freeze().
1553 @see Freeze(), Thaw()
1555 bool IsFrozen() const;
1558 Returns the background colour of the window.
1560 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1562 wxColour
GetBackgroundColour() const;
1565 Returns the background style of the window.
1567 @see SetBackgroundColour(), GetForegroundColour(),
1568 SetBackgroundStyle(), SetTransparent()
1570 virtual wxBackgroundStyle
GetBackgroundStyle() const;
1573 Returns the character height for this window.
1575 virtual int GetCharHeight() const;
1578 Returns the average character width for this window.
1580 virtual int GetCharWidth() const;
1583 Currently this is the same as calling
1584 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1586 One advantage of using this function compared to the static version is that
1587 the call is automatically dispatched to the correct class (as usual with
1588 virtual functions) and you don't have to specify the class name explicitly.
1590 The other one is that in the future this function could return different
1591 results, for example it might return a different font for an "Ok" button
1592 than for a generic button if the users GUI is configured to show such buttons
1593 in bold font. Of course, the down side is that it is impossible to call this
1594 function without actually having an object to apply it to whereas the static
1595 version can be used without having to create an object first.
1597 virtual wxVisualAttributes
GetDefaultAttributes() const;
1600 Returns the font for this window.
1604 wxFont
GetFont() const;
1607 Returns the foreground colour of the window.
1609 @remarks The meaning of foreground colour varies according to the window class;
1610 it may be the text colour or other colour, or it may not be used at all.
1612 @see SetForegroundColour(), SetBackgroundColour(),
1613 GetBackgroundColour()
1615 wxColour
GetForegroundColour() const;
1618 Gets the dimensions of the string as it would be drawn on the
1619 window with the currently selected font.
1621 The text extent is returned in the @a w and @a h pointers.
1624 String whose extent is to be measured.
1626 Return value for width.
1628 Return value for height.
1630 Return value for descent (optional).
1631 @param externalLeading
1632 Return value for external leading (optional).
1634 Font to use instead of the current window font (optional).
1637 In wxPerl this method takes only the @a string and optionally
1638 @a font parameters, and returns a 4-element list
1639 (x, y, descent, externalLeading).
1642 void GetTextExtent(const wxString
& string
,
1644 int* descent
= NULL
,
1645 int* externalLeading
= NULL
,
1646 const wxFont
* font
= NULL
) const;
1649 Gets the dimensions of the string as it would be drawn on the
1650 window with the currently selected font.
1652 wxSize
GetTextExtent(const wxString
& string
) const;
1655 Returns the region specifying which parts of the window have been damaged.
1656 Should only be called within an wxPaintEvent handler.
1658 @see wxRegion, wxRegionIterator
1660 const wxRegion
& GetUpdateRegion() const;
1663 Get the update rectangle bounding box in client coords
1665 wxRect
GetUpdateClientRect() const;
1668 Returns @true if this window background is transparent (as, for example,
1669 for wxStaticText) and should show the parent window background.
1671 This method is mostly used internally by the library itself and you normally
1672 shouldn't have to call it. You may, however, have to override it in your
1673 wxWindow-derived class to ensure that background is painted correctly.
1675 virtual bool HasTransparentBackground();
1678 Causes this window, and all of its children recursively (except under wxGTK1
1679 where this is not implemented), to be repainted. Note that repainting doesn't
1680 happen immediately but only during the next event loop iteration, if you need
1681 to update the window immediately you should use Update() instead.
1683 @param eraseBackground
1684 If @true, the background will be erased.
1686 If non-@NULL, only the given rectangle will be treated as damaged.
1690 virtual void Refresh(bool eraseBackground
= true,
1691 const wxRect
* rect
= NULL
);
1694 Redraws the contents of the given rectangle: only the area inside it will be
1697 This is the same as Refresh() but has a nicer syntax as it can be called
1698 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1700 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1703 Calling this method immediately repaints the invalidated area of the window and
1704 all of its children recursively (this normally only happens when the
1705 flow of control returns to the event loop).
1707 Notice that this function doesn't invalidate any area of the window so
1708 nothing happens if nothing has been invalidated (i.e. marked as requiring
1709 a redraw). Use Refresh() first if you want to immediately redraw the
1710 window unconditionally.
1712 virtual void Update();
1715 Sets the background colour of the window.
1717 Notice that as with SetForegroundColour(), setting the background
1718 colour of a native control may not affect the entire control and could
1719 be not supported at all depending on the control and platform.
1721 Please see InheritAttributes() for explanation of the difference between
1722 this method and SetOwnBackgroundColour().
1725 The colour to be used as the background colour; pass
1726 wxNullColour to reset to the default colour.
1727 Note that you may want to use wxSystemSettings::GetColour() to retrieve
1728 a suitable colour to use rather than setting an hard-coded one.
1730 @remarks The background colour is usually painted by the default
1731 wxEraseEvent event handler function under Windows and
1732 automatically under GTK.
1733 Note that setting the background colour does not cause an
1734 immediate refresh, so you may wish to call wxWindow::ClearBackground
1735 or wxWindow::Refresh after calling this function.
1736 Using this function will disable attempts to use themes for
1737 this window, if the system supports them. Use with care since
1738 usually the themes represent the appearance chosen by the user
1739 to be used for all applications on the system.
1741 @return @true if the colour was really changed, @false if it was already set
1742 to this colour and nothing was done.
1744 @see GetBackgroundColour(), SetForegroundColour(),
1745 GetForegroundColour(), ClearBackground(),
1746 Refresh(), wxEraseEvent, wxSystemSettings
1748 virtual bool SetBackgroundColour(const wxColour
& colour
);
1751 Sets the background style of the window.
1753 The default background style is @c wxBG_STYLE_ERASE which indicates that
1754 the window background may be erased in @c EVT_ERASE_BACKGROUND handler.
1755 This is a safe, compatibility default; however you may want to change it
1756 to @c wxBG_STYLE_SYSTEM if you don't define any erase background event
1757 handlers at all, to avoid unnecessary generation of erase background
1758 events and always let system erase the background. And you should
1759 change the background style to @c wxBG_STYLE_PAINT if you define an
1760 @c EVT_PAINT handler which completely overwrites the window background as
1761 in this case erasing it previously, either in @c EVT_ERASE_BACKGROUND
1762 handler or in the system default handler, would result in flicker as
1763 the background pixels will be repainted twice every time the window is
1764 redrawn. Do ensure that the background is entirely erased by your
1765 @c EVT_PAINT handler in this case however as otherwise garbage may be left
1768 Notice that in previous versions of wxWidgets a common way to work
1769 around the above mentioned flickering problem was to define an empty
1770 @c EVT_ERASE_BACKGROUND handler. Setting background style to
1771 @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
1775 Under wxGTK and wxOSX, you can use ::wxBG_STYLE_TRANSPARENT to obtain
1776 full transparency of the window background. Note that wxGTK supports
1777 this only since GTK 2.12 with a compositing manager enabled, call
1778 IsTransparentBackgroundSupported() to check whether this is the case.
1780 Also, on order for @c SetBackgroundStyle(wxBG_STYLE_TRANSPARENT) to
1781 work, it must be called before Create(). If you're using your own
1782 wxWindow-derived class you should write your code in the following way:
1784 class MyWidget : public wxWindow
1787 MyWidget(wxWindow* parent, ...)
1788 : wxWindow() // Use default ctor here!
1791 SetBackgroundStyle(wxBG_STYLE_TRANSPARENT);
1793 // And really create the window afterwards:
1794 Create(parent, ...);
1799 @see SetBackgroundColour(), GetForegroundColour(),
1800 SetTransparent(), IsTransparentBackgroundSupported()
1802 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
1805 Checks whether using transparent background might work.
1807 If this function returns @false, calling SetBackgroundStyle() with
1808 ::wxBG_STYLE_TRANSPARENT is not going to work. If it returns @true,
1809 setting transparent style should normally succeed.
1811 Notice that this function would typically be called on the parent of a
1812 window you want to set transparent background style for as the window
1813 for which this method is called must be fully created.
1816 If not @NULL, a reason message is provided if transparency is not
1819 @return @true if background transparency is supported.
1823 virtual bool IsTransparentBackgroundSupported(wxString
*reason
= NULL
) const;
1826 Sets the font for this window. This function should not be called for the
1827 parent window if you don't want its font to be inherited by its children,
1828 use SetOwnFont() instead in this case and see InheritAttributes() for more
1831 Please notice that the given font is not automatically used for
1832 wxPaintDC objects associated with this window, you need to
1833 call wxDC::SetFont too. However this font is used by
1834 any standard controls for drawing their text as well as by
1838 Font to associate with this window, pass
1839 wxNullFont to reset to the default font.
1841 @return @true if the font was really changed, @false if it was already set
1842 to this font and nothing was done.
1844 @see GetFont(), InheritAttributes()
1846 virtual bool SetFont(const wxFont
& font
);
1849 Sets the foreground colour of the window.
1851 The meaning of foreground colour varies according to the window class;
1852 it may be the text colour or other colour, or it may not be used at
1853 all. Additionally, not all native controls support changing their
1854 foreground colour so this method may change their colour only partially
1857 Please see InheritAttributes() for explanation of the difference between
1858 this method and SetOwnForegroundColour().
1861 The colour to be used as the foreground colour; pass
1862 wxNullColour to reset to the default colour.
1864 @return @true if the colour was really changed, @false if it was already set
1865 to this colour and nothing was done.
1867 @see GetForegroundColour(), SetBackgroundColour(),
1868 GetBackgroundColour(), ShouldInheritColours()
1870 virtual bool SetForegroundColour(const wxColour
& colour
);
1873 Sets the background colour of the window but prevents it from being inherited
1874 by the children of this window.
1876 @see SetBackgroundColour(), InheritAttributes()
1878 void SetOwnBackgroundColour(const wxColour
& colour
);
1881 Sets the font of the window but prevents it from being inherited by the
1882 children of this window.
1884 @see SetFont(), InheritAttributes()
1886 void SetOwnFont(const wxFont
& font
);
1889 Sets the foreground colour of the window but prevents it from being inherited
1890 by the children of this window.
1892 @see SetForegroundColour(), InheritAttributes()
1894 void SetOwnForegroundColour(const wxColour
& colour
);
1897 @deprecated use wxDC::SetPalette instead.
1899 void SetPalette(const wxPalette
& pal
);
1902 Return @true from here to allow the colours of this window to be changed by
1903 InheritAttributes(). Returning @false forbids inheriting them from the parent window.
1905 The base class version returns @false, but this method is overridden in
1906 wxControl where it returns @true.
1908 virtual bool ShouldInheritColours() const;
1911 This function tells a window if it should use the system's "theme" code
1912 to draw the windows' background instead of its own background drawing
1913 code. This does not always have any effect since the underlying platform
1914 obviously needs to support the notion of themes in user defined windows.
1915 One such platform is GTK+ where windows can have (very colourful) backgrounds
1916 defined by a user's selected theme.
1918 Dialogs, notebook pages and the status bar have this flag set to @true
1919 by default so that the default look and feel is simulated best.
1921 virtual void SetThemeEnabled(bool enable
);
1925 virtual bool GetThemeEnabled() const;
1928 Returns @true if the system supports transparent windows and calling
1929 SetTransparent() may succeed. If this function returns @false, transparent
1930 windows are definitely not supported by the current system.
1932 virtual bool CanSetTransparent();
1935 Set the transparency of the window. If the system supports transparent windows,
1936 returns @true, otherwise returns @false and the window remains fully opaque.
1937 See also CanSetTransparent().
1939 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1940 fully transparent window and 255 to the fully opaque one. The constants
1941 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1943 virtual bool SetTransparent(wxByte alpha
);
1949 @name Event-handling functions
1951 wxWindow allows you to build a (sort of) stack of event handlers which
1952 can be used to override the window's own event handling.
1957 Returns the event handler for this window.
1958 By default, the window is its own event handler.
1960 @see SetEventHandler(), PushEventHandler(),
1961 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1963 wxEvtHandler
* GetEventHandler() const;
1966 This function will generate the appropriate call to Navigate() if the key
1967 event is one normally used for keyboard navigation and return @true in this case.
1969 @return Returns @true if the key pressed was for navigation and was
1970 handled, @false otherwise.
1974 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
1979 GetEventHandler()->SafelyProcessEvent(event);
1982 @see ProcessWindowEvent()
1984 bool HandleWindowEvent(wxEvent
& event
) const;
1987 Convenient wrapper for ProcessEvent().
1989 This is the same as writing @code GetEventHandler()->ProcessEvent(event);
1990 @endcode but more convenient. Notice that ProcessEvent() itself can't
1991 be called for wxWindow objects as it ignores the event handlers
1992 associated with the window; use this function instead.
1994 bool ProcessWindowEvent(wxEvent
& event
);
1997 Wrapper for wxEvtHandler::ProcessEventLocally().
1999 This method is similar to ProcessWindowEvent() but can be used to
2000 search for the event handler only in this window and any event handlers
2001 pushed on top of it. Unlike ProcessWindowEvent() it won't propagate the
2002 event upwards. But it will use the validator and event handlers
2003 associated with this window, if any.
2007 bool ProcessWindowEventLocally(wxEvent
& event
);
2010 Removes and returns the top-most event handler on the event handler stack.
2012 E.g. in the case of:
2013 @image html overview_events_winstack.png
2014 when calling @c W->PopEventHandler(), the event handler @c A will be
2015 removed and @c B will be the first handler of the stack.
2017 Note that it's an error to call this function when no event handlers
2018 were pushed on this window (i.e. when the window itself is its only
2021 @param deleteHandler
2022 If this is @true, the handler will be deleted after it is removed
2023 (and the returned value will be @NULL).
2025 @see @ref overview_events_processing
2027 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
2030 Pushes this event handler onto the event stack for the window.
2032 An event handler is an object that is capable of processing the events sent
2033 to a window. By default, the window is its own event handler, but an application
2034 may wish to substitute another, for example to allow central implementation
2035 of event-handling for a variety of different window classes.
2037 wxWindow::PushEventHandler allows an application to set up a @e stack
2038 of event handlers, where an event not handled by one event handler is
2039 handed to the next one in the chain.
2041 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
2044 W->PushEventHandler(A);
2045 W->PushEventHandler(B);
2047 you will end up with the following situation:
2048 @image html overview_events_winstack.png
2050 Note that you can use wxWindow::PopEventHandler to remove the event handler.
2053 Specifies the handler to be pushed.
2054 It must not be part of a wxEvtHandler chain; an assert will fail
2055 if it's not unlinked (see wxEvtHandler::IsUnlinked).
2057 @see @ref overview_events_processing
2059 void PushEventHandler(wxEvtHandler
* handler
);
2062 Find the given @a handler in the windows event handler stack and
2063 removes (but does not delete) it from the stack.
2065 See wxEvtHandler::Unlink() for more info.
2068 The event handler to remove, must be non-@NULL and
2069 must be present in this windows event handlers stack.
2071 @return Returns @true if it was found and @false otherwise (this also
2072 results in an assert failure so this function should
2073 only be called when the handler is supposed to be there).
2075 @see PushEventHandler(), PopEventHandler()
2077 bool RemoveEventHandler(wxEvtHandler
* handler
);
2080 Sets the event handler for this window.
2082 Note that if you use this function you may want to use as the "next" handler
2083 of @a handler the window itself; in this way when @a handler doesn't process
2084 an event, the window itself will have a chance to do it.
2087 Specifies the handler to be set. Cannot be @NULL.
2089 @see @ref overview_events_processing
2091 void SetEventHandler(wxEvtHandler
* handler
);
2094 wxWindows cannot be used to form event handler chains; this function
2095 thus will assert when called.
2097 Note that instead you can use PushEventHandler() or SetEventHandler() to
2098 implement a stack of event handlers to override wxWindow's own
2099 event handling mechanism.
2101 virtual void SetNextHandler(wxEvtHandler
* handler
);
2104 wxWindows cannot be used to form event handler chains; this function
2105 thus will assert when called.
2107 Note that instead you can use PushEventHandler() or SetEventHandler() to
2108 implement a stack of event handlers to override wxWindow's own
2109 event handling mechanism.
2111 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
2118 @name Window styles functions
2123 Returns the extra style bits for the window.
2125 long GetExtraStyle() const;
2128 Gets the window style that was passed to the constructor or Create()
2129 method. GetWindowStyle() is another name for the same function.
2131 virtual long GetWindowStyleFlag() const;
2134 See GetWindowStyleFlag() for more info.
2136 long GetWindowStyle() const;
2139 Returns @true if the window has the given @a exFlag bit set in its
2142 @see SetExtraStyle()
2144 bool HasExtraStyle(int exFlag
) const;
2147 Returns @true if the window has the given @a flag bit set.
2149 bool HasFlag(int flag
) const;
2152 Sets the extra style bits for the window.
2153 The currently defined extra style bits are reported in the class
2156 virtual void SetExtraStyle(long exStyle
);
2159 Sets the style of the window. Please note that some styles cannot be changed
2160 after the window creation and that Refresh() might need to be called
2161 after changing the others for the change to take place immediately.
2163 See @ref overview_windowstyles "Window styles" for more information about flags.
2165 @see GetWindowStyleFlag()
2167 virtual void SetWindowStyleFlag(long style
);
2170 See SetWindowStyleFlag() for more info.
2172 void SetWindowStyle(long style
);
2175 Turns the given @a flag on if it's currently turned off and vice versa.
2176 This function cannot be used if the value of the flag is 0 (which is often
2177 the case for default flags).
2179 Also, please notice that not all styles can be changed after the control
2182 @return Returns @true if the style was turned on by this function, @false
2183 if it was switched off.
2185 @see SetWindowStyleFlag(), HasFlag()
2187 bool ToggleWindowStyle(int flag
);
2193 @name Tab order functions
2198 Moves this window in the tab navigation order after the specified @e win.
2199 This means that when the user presses @c TAB key on that other window,
2200 the focus switches to this window.
2202 Default tab order is the same as creation order, this function and
2203 MoveBeforeInTabOrder() allow to change
2204 it after creating all the windows.
2207 A sibling of this window which should precede it in tab order,
2210 void MoveAfterInTabOrder(wxWindow
* win
);
2213 Same as MoveAfterInTabOrder() except that it inserts this window just
2214 before @a win instead of putting it right after it.
2216 void MoveBeforeInTabOrder(wxWindow
* win
);
2219 Performs a keyboard navigation action starting from this window.
2220 This method is equivalent to calling NavigateIn() method on the
2224 A combination of wxNavigationKeyEvent::IsForward and
2225 wxNavigationKeyEvent::WinChange.
2227 @return Returns @true if the focus was moved to another window or @false
2230 @remarks You may wish to call this from a text control custom keypress
2231 handler to do the default navigation behaviour for the
2232 tab key, since the standard default behaviour for a
2233 multiline text control with the wxTE_PROCESS_TAB style
2234 is to insert a tab and not navigate to the next
2235 control. See also wxNavigationKeyEvent and
2236 HandleAsNavigationKey.
2238 bool Navigate(int flags
= wxNavigationKeyEvent
::IsForward
);
2241 Performs a keyboard navigation action inside this window.
2242 See Navigate() for more information.
2244 bool NavigateIn(int flags
= wxNavigationKeyEvent
::IsForward
);
2251 @name Z order functions
2256 Lowers the window to the bottom of the window hierarchy (Z-order).
2259 This function only works for wxTopLevelWindow-derived classes.
2263 virtual void Lower();
2266 Raises the window to the top of the window hierarchy (Z-order).
2268 Notice that this function only requests the window manager to raise
2269 this window to the top of Z-order. Depending on its configuration, the
2270 window manager may raise the window, not do it at all or indicate that
2271 a window requested to be raised in some other way, e.g. by flashing its
2272 icon if it is minimized.
2275 This function only works for wxTopLevelWindow-derived classes.
2279 virtual void Raise();
2285 @name Window status functions
2291 Equivalent to calling wxWindow::Show(@false).
2296 This function hides a window, like Hide(), but using a special visual
2299 The parameters of this function are the same as for ShowWithEffect(),
2300 please see their description there.
2304 virtual bool HideWithEffect(wxShowEffect effect
,
2305 unsigned int timeout
= 0);
2307 Returns @true if the window is enabled, i.e. if it accepts user input,
2310 Notice that this method can return @false even if this window itself hadn't
2311 been explicitly disabled when one of its parent windows is disabled.
2312 To get the intrinsic status of this window, use IsThisEnabled()
2316 bool IsEnabled() const;
2319 Returns @true if the given point or rectangle area has been exposed since the
2320 last repaint. Call this in an paint event handler to optimize redrawing by
2321 only redrawing those areas, which have been exposed.
2323 bool IsExposed(int x
, int y
) const;
2328 bool IsExposed(wxPoint
& pt
) const;
2333 bool IsExposed(int x
, int y
, int w
, int h
) const;
2338 bool IsExposed(wxRect
& rect
) const;
2340 Returns @true if the window is shown, @false if it has been hidden.
2342 @see IsShownOnScreen()
2344 virtual bool IsShown() const;
2347 Returns @true if the window is physically visible on the screen, i.e. it
2348 is shown and all its parents up to the toplevel window are shown as well.
2352 virtual bool IsShownOnScreen() const;
2355 Disables the window. Same as @ref Enable() Enable(@false).
2357 @return Returns @true if the window has been disabled, @false if it had
2358 been already disabled before the call to this function.
2363 Enable or disable the window for user input. Note that when a parent window is
2364 disabled, all of its children are disabled as well and they are reenabled again
2368 If @true, enables the window for input. If @false, disables the window.
2370 @return Returns @true if the window has been enabled or disabled, @false
2371 if nothing was done, i.e. if the window had already
2372 been in the specified state.
2374 @see IsEnabled(), Disable(), wxRadioBox::Enable
2376 virtual bool Enable(bool enable
= true);
2379 Shows or hides the window. You may need to call Raise()
2380 for a top level window if you want to bring it to top, although this is not
2381 needed if Show() is called immediately after the frame creation.
2383 Notice that the default state of newly created top level windows is hidden
2384 (to allow you to create their contents without flicker) unlike for
2385 all the other, not derived from wxTopLevelWindow, windows that
2386 are by default created in the shown state.
2389 If @true displays the window. Otherwise, hides it.
2391 @return @true if the window has been shown or hidden or @false if nothing
2392 was done because it already was in the requested state.
2394 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2396 virtual bool Show(bool show
= true);
2399 This function shows a window, like Show(), but using a special visual
2406 The @a timeout parameter specifies the time of the animation, in
2407 milliseconds. If the default value of 0 is used, the default
2408 animation time for the current platform is used.
2410 @note Currently this function is only implemented in wxMSW and wxOSX
2411 (for wxTopLevelWindows only in Carbon version and for any kind of
2412 windows in Cocoa) and does the same thing as Show() in the other
2417 @see HideWithEffect()
2419 virtual bool ShowWithEffect(wxShowEffect effect
,
2420 unsigned int timeout
= 0);
2426 @name Context-sensitive help functions
2431 Gets the help text to be used as context-sensitive help for this window.
2432 Note that the text is actually stored by the current wxHelpProvider
2433 implementation, and not in the window object itself.
2435 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2437 wxString
GetHelpText() const;
2440 Sets the help text to be used as context-sensitive help for this window.
2441 Note that the text is actually stored by the current wxHelpProvider
2442 implementation, and not in the window object itself.
2444 @see GetHelpText(), wxHelpProvider::AddHelp()
2446 void SetHelpText(const wxString
& helpText
);
2449 Gets the help text to be used as context-sensitive help for this window.
2450 This method should be overridden if the help message depends on the position
2451 inside the window, otherwise GetHelpText() can be used.
2454 Coordinates of the mouse at the moment of help event emission.
2456 Help event origin, see also wxHelpEvent::GetOrigin.
2458 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
2459 wxHelpEvent
::Origin origin
) const;
2462 Get the associated tooltip or @NULL if none.
2464 wxToolTip
* GetToolTip() const;
2467 Get the text of the associated tooltip or empty string if none.
2469 wxString
GetToolTipText() const;
2472 Attach a tooltip to the window.
2474 wxToolTip pointer can be @NULL in the overload taking the pointer,
2475 meaning to unset any existing tooltips; however UnsetToolTip() provides
2476 a more readable alternative to this operation.
2478 Notice that these methods are always available, even if wxWidgets was
2479 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2482 @see GetToolTip(), wxToolTip
2484 void SetToolTip(const wxString
& tipString
);
2489 void SetToolTip(wxToolTip
* tip
);
2492 Unset any existing tooltip.
2498 void UnsetToolTip();
2504 @name Popup/context menu functions
2509 This function shows a popup menu at the given position in this window and
2510 returns the selected id.
2512 It can be more convenient than the general purpose PopupMenu() function
2513 for simple menus proposing a choice in a list of strings to the user.
2515 Notice that to avoid unexpected conflicts between the (usually
2516 consecutive range of) ids used by the menu passed to this function and
2517 the existing EVT_UPDATE_UI() handlers, this function temporarily
2518 disables UI updates for the window, so you need to manually disable
2519 (or toggle or ...) any items which should be disabled in the menu
2522 The parameter @a menu is the menu to show.
2523 The parameter @a pos (or the parameters @a x and @a y) is the
2524 position at which to show the menu in client coordinates.
2525 It is recommended to not explicitly specify coordinates when
2526 calling this method in response to mouse click, because some of
2527 the ports (namely, wxGTK) can do a better job of positioning
2528 the menu in that case.
2531 The selected menu item id or @c wxID_NONE if none selected or an
2536 int GetPopupMenuSelectionFromUser(wxMenu
& menu
,
2537 const wxPoint
& pos
= wxDefaultPosition
);
2542 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
2545 Pops up the given menu at the specified coordinates, relative to this
2546 window, and returns control when the user has dismissed the menu.
2548 If a menu item is selected, the corresponding menu event is generated and will be
2549 processed as usual. If coordinates are not specified, the current mouse
2550 cursor position is used.
2552 @a menu is the menu to pop up.
2554 The position where the menu will appear can be specified either as a
2555 wxPoint @a pos or by two integers (@a x and @a y).
2557 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2558 ensure that the menu items are in the correct state.
2559 The menu does not get deleted by the window.
2560 It is recommended to not explicitly specify coordinates when
2561 calling PopupMenu in response to mouse click, because some of
2562 the ports (namely, wxGTK) can do a better job of positioning
2563 the menu in that case.
2567 bool PopupMenu(wxMenu
* menu
,
2568 const wxPoint
& pos
= wxDefaultPosition
);
2573 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
2584 Returns a pointer to the current validator for the window, or @NULL if
2587 virtual wxValidator
* GetValidator();
2590 Deletes the current validator (if any) and sets the window validator, having
2591 called wxValidator::Clone to create a new validator of this type.
2593 virtual void SetValidator(const wxValidator
& validator
);
2596 Transfers values from child controls to data areas specified by their
2597 validators. Returns @false if a transfer failed.
2599 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2600 the method will also call TransferDataFromWindow() of all child windows.
2602 @see TransferDataToWindow(), wxValidator, Validate()
2604 virtual bool TransferDataFromWindow();
2607 Transfers values to child controls from data areas specified by their
2610 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2611 the method will also call TransferDataToWindow() of all child windows.
2613 @return Returns @false if a transfer failed.
2615 @see TransferDataFromWindow(), wxValidator, Validate()
2617 virtual bool TransferDataToWindow();
2620 Validates the current values of the child controls using their validators.
2621 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2622 the method will also call Validate() of all child windows.
2624 @return Returns @false if any of the validations failed.
2626 @see TransferDataFromWindow(), TransferDataToWindow(),
2629 virtual bool Validate();
2635 @name wxWindow properties functions
2640 Returns the identifier of the window.
2642 @remarks Each window has an integer identifier. If the application
2643 has not provided one (or the default wxID_ANY) a unique
2644 identifier with a negative value will be generated.
2646 @see SetId(), @ref overview_windowids
2648 wxWindowID
GetId() const;
2651 Generic way of getting a label from any window, for
2652 identification purposes.
2654 @remarks The interpretation of this function differs from class to class.
2655 For frames and dialogs, the value returned is the
2656 title. For buttons or static text controls, it is the
2657 button text. This function can be useful for
2658 meta-programs (such as testing tools or special-needs
2659 access programs) which need to identify windows by name.
2661 virtual wxString
GetLabel() const;
2664 Returns the layout direction for this window,
2665 Note that @c wxLayout_Default is returned if layout direction is not supported.
2667 virtual wxLayoutDirection
GetLayoutDirection() const;
2670 Returns the window's name.
2672 @remarks This name is not guaranteed to be unique; it is up to the
2673 programmer to supply an appropriate name in the window
2674 constructor or via SetName().
2678 virtual wxString
GetName() const;
2681 Returns the value previously passed to SetWindowVariant().
2683 wxWindowVariant
GetWindowVariant() const;
2686 Sets the identifier of the window.
2688 @remarks Each window has an integer identifier. If the application has
2689 not provided one, an identifier will be generated.
2690 Normally, the identifier should be provided on creation
2691 and should not be modified subsequently.
2693 @see GetId(), @ref overview_windowids
2695 void SetId(wxWindowID winid
);
2698 Sets the window's label.
2705 virtual void SetLabel(const wxString
& label
);
2708 Sets the layout direction for this window.
2710 virtual void SetLayoutDirection(wxLayoutDirection dir
);
2713 Sets the window's name.
2716 A name to set for the window.
2720 virtual void SetName(const wxString
& name
);
2723 This function can be called under all platforms but only does anything under
2724 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2725 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2727 By default the controls use the normal size, of course, but this function can
2728 be used to change this.
2730 void SetWindowVariant(wxWindowVariant variant
);
2733 Gets the accelerator table for this window. See wxAcceleratorTable.
2735 wxAcceleratorTable
* GetAcceleratorTable();
2738 Returns the accessible object for this window, if any.
2739 See also wxAccessible.
2741 wxAccessible
* GetAccessible();
2744 Sets the accelerator table for this window. See wxAcceleratorTable.
2746 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
2749 Sets the accessible for this window. Any existing accessible for this window
2750 will be deleted first, if not identical to @e accessible.
2751 See also wxAccessible.
2753 void SetAccessible(wxAccessible
* accessible
);
2759 @name Window deletion functions
2764 This function simply generates a wxCloseEvent whose handler usually tries
2765 to close the window. It doesn't close the window itself, however.
2768 @false if the window's close handler should be able to veto the destruction
2769 of this window, @true if it cannot.
2771 @remarks Close calls the close handler for the window, providing an
2772 opportunity for the window to choose whether to destroy
2773 the window. Usually it is only used with the top level
2774 windows (wxFrame and wxDialog classes) as the others
2775 are not supposed to have any special OnClose() logic.
2776 The close handler should check whether the window is being deleted
2777 forcibly, using wxCloseEvent::CanVeto, in which case it should
2778 destroy the window using wxWindow::Destroy.
2779 Note that calling Close does not guarantee that the window will
2780 be destroyed; but it provides a way to simulate a manual close
2781 of a window, which may or may not be implemented by destroying
2782 the window. The default implementation of wxDialog::OnCloseWindow
2783 does not necessarily delete the dialog, since it will simply
2784 simulate an wxID_CANCEL event which is handled by the appropriate
2785 button event handler and may do anything at all.
2786 To guarantee that the window will be destroyed, call
2787 wxWindow::Destroy instead
2789 @see @ref overview_windowdeletion "Window Deletion Overview",
2790 Destroy(), wxCloseEvent
2792 bool Close(bool force
= false);
2795 Destroys the window safely. Use this function instead of the delete operator,
2796 since different window classes can be destroyed differently. Frames and dialogs
2797 are not destroyed immediately when this function is called -- they are added
2798 to a list of windows to be deleted on idle time, when all the window's events
2799 have been processed. This prevents problems with events being sent to
2800 non-existent windows.
2802 @return @true if the window has either been successfully deleted, or it
2803 has been added to the list of windows pending real deletion.
2805 virtual bool Destroy();
2808 Returns true if this window is in process of being destroyed.
2810 Top level windows are not deleted immediately but are rather
2811 scheduled for later destruction to give them time to process any
2812 pending messages; see Destroy() description.
2814 This function returns @true if this window, or one of its parent
2815 windows, is scheduled for destruction and can be useful to avoid
2816 manipulating it as it's usually useless to do something with a window
2817 which is on the point of disappearing anyhow.
2819 bool IsBeingDeleted() const;
2826 @name Drag and drop functions
2831 Returns the associated drop target, which may be @NULL.
2833 @see SetDropTarget(), @ref overview_dnd
2835 virtual wxDropTarget
* GetDropTarget() const;
2838 Associates a drop target with this window.
2839 If the window already has a drop target, it is deleted.
2841 @see GetDropTarget(), @ref overview_dnd
2843 virtual void SetDropTarget(wxDropTarget
* target
);
2846 Enables or disables eligibility for drop file events (OnDropFiles).
2849 If @true, the window is eligible for drop file events.
2850 If @false, the window will not accept drop file events.
2852 @remarks Windows only until version 2.8.9, available on all platforms
2853 since 2.8.10. Cannot be used together with SetDropTarget() on
2854 non-Windows platforms.
2856 @see SetDropTarget()
2858 virtual void DragAcceptFiles(bool accept
);
2864 @name Constraints, sizers and window layout functions
2869 Returns the sizer of which this window is a member, if any, otherwise @NULL.
2871 wxSizer
* GetContainingSizer() const;
2874 Returns the sizer associated with the window by a previous call to
2875 SetSizer(), or @NULL.
2877 wxSizer
* GetSizer() const;
2880 Sets the window to have the given layout sizer.
2882 The window will then own the object, and will take care of its deletion.
2883 If an existing layout constraints object is already owned by the
2884 window, it will be deleted if the @a deleteOld parameter is @true.
2886 Note that this function will also call SetAutoLayout() implicitly with @true
2887 parameter if the @a sizer is non-@NULL and @false otherwise so that the
2888 sizer will be effectively used to layout the window children whenever
2892 The sizer to set. Pass @NULL to disassociate and conditionally delete
2893 the window's sizer. See below.
2895 If @true (the default), this will delete any pre-existing sizer.
2896 Pass @false if you wish to handle deleting the old sizer yourself
2897 but remember to do it yourself in this case to avoid memory leaks.
2899 @remarks SetSizer enables and disables Layout automatically.
2901 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2904 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2905 window size to the size needed to accommodate all sizer elements and sets the
2906 size hints which, if this window is a top level one, prevent the user from
2907 resizing it to be less than this minimal size.
2909 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2912 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2914 wxLayoutConstraints
* GetConstraints() const;
2917 Sets the window to have the given layout constraints. The window
2918 will then own the object, and will take care of its deletion.
2919 If an existing layout constraints object is already owned by the
2920 window, it will be deleted.
2923 The constraints to set. Pass @NULL to disassociate and delete the window's
2926 @remarks You must call SetAutoLayout() to tell a window to use
2927 the constraints automatically in OnSize; otherwise, you
2928 must override OnSize and call Layout() explicitly. When
2929 setting both a wxLayoutConstraints and a wxSizer, only
2930 the sizer will have effect.
2932 void SetConstraints(wxLayoutConstraints
* constraints
);
2935 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2938 This function does not get called automatically when the window is resized
2939 because lots of windows deriving from wxWindow does not need this functionality.
2940 If you want to have Layout() called automatically, you should derive
2941 from wxPanel (see wxPanel::Layout).
2943 @see @ref overview_windowsizing
2945 virtual bool Layout();
2948 Determines whether the Layout() function will be called automatically
2949 when the window is resized.
2951 This method is called implicitly by SetSizer() but if you use SetConstraints()
2952 you should call it manually or otherwise the window layout won't be correctly
2953 updated when its size changes.
2956 Set this to @true if you wish the Layout() function to be called
2957 automatically when the window is resized.
2959 @see SetSizer(), SetConstraints()
2961 void SetAutoLayout(bool autoLayout
);
2963 bool GetAutoLayout() const;
2970 @name Mouse functions
2975 Directs all mouse input to this window.
2976 Call ReleaseMouse() to release the capture.
2978 Note that wxWidgets maintains the stack of windows having captured the mouse
2979 and when the mouse is released the capture returns to the window which had had
2980 captured it previously and it is only really released if there were no previous
2981 window. In particular, this means that you must release the mouse as many times
2982 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
2984 Any application which captures the mouse in the beginning of some operation
2985 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
2986 the event. The event handler must not recapture mouse.
2988 @see ReleaseMouse(), wxMouseCaptureLostEvent
2990 void CaptureMouse();
2993 Returns the caret() associated with the window.
2995 wxCaret
* GetCaret() const;
2998 Return the cursor associated with this window.
3002 const wxCursor
& GetCursor() const;
3005 Returns @true if this window has the current mouse capture.
3007 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
3008 wxMouseCaptureChangedEvent
3010 virtual bool HasCapture() const;
3013 Releases mouse input captured with CaptureMouse().
3015 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
3016 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3018 void ReleaseMouse();
3021 Sets the caret() associated with the window.
3023 void SetCaret(wxCaret
* caret
);
3026 Sets the window's cursor. Notice that the window cursor also sets it for the
3027 children of the window implicitly.
3029 The @a cursor may be @c wxNullCursor in which case the window cursor will
3030 be reset back to default.
3033 Specifies the cursor that the window should normally display.
3035 @see ::wxSetCursor, wxCursor
3037 virtual bool SetCursor(const wxCursor
& cursor
);
3040 Moves the pointer to the given position on the window.
3042 @note Apple Human Interface Guidelines forbid moving the mouse cursor
3043 programmatically so you should avoid using this function in Mac
3044 applications (and probably avoid using it under the other
3045 platforms without good reason as well).
3048 The new x position for the cursor.
3050 The new y position for the cursor.
3052 virtual void WarpPointer(int x
, int y
);
3060 @name Miscellaneous functions
3064 wxHitTest
HitTest(wxCoord x
, wxCoord y
) const;
3065 wxHitTest
HitTest(const wxPoint
& pt
) const;
3068 Get the window border style from the given flags: this is different from
3069 simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to
3070 translate wxBORDER_DEFAULT to something reasonable
3072 wxBorder
GetBorder(long flags
) const;
3075 Get border for the flags of this window
3077 wxBorder
GetBorder() const;
3081 Does the window-specific updating after processing the update event.
3082 This function is called by UpdateWindowUI() in order to check return
3083 values in the wxUpdateUIEvent and act appropriately.
3084 For example, to allow frame and dialog title updating, wxWidgets
3085 implements this function as follows:
3088 // do the window-specific processing after processing the update event
3089 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
3091 if ( event.GetSetEnabled() )
3092 Enable(event.GetEnabled());
3094 if ( event.GetSetText() )
3096 if ( event.GetText() != GetTitle() )
3097 SetTitle(event.GetText());
3102 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
3105 Returns the platform-specific handle of the physical window.
3106 Cast it to an appropriate handle, such as @b HWND for Windows,
3107 @b Widget for Motif or @b GtkWidget for GTK.
3110 This method will return an integer in wxPerl.
3113 virtual WXWidget
GetHandle() const;
3116 This method should be overridden to return @true if this window has
3117 multiple pages. All standard class with multiple pages such as
3118 wxNotebook, wxListbook and wxTreebook already override it to return @true
3119 and user-defined classes with similar behaviour should also do so, to
3120 allow the library to handle such windows appropriately.
3122 virtual bool HasMultiplePages() const;
3125 This function is (or should be, in case of custom controls) called during
3126 window creation to intelligently set up the window visual attributes, that is
3127 the font and the foreground and background colours.
3129 By "intelligently" the following is meant: by default, all windows use their
3130 own @ref GetClassDefaultAttributes() default attributes.
3131 However if some of the parents attributes are explicitly (that is, using
3132 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
3133 attribute hadn't been explicitly set for this window itself, then this
3134 window takes the same value as used by the parent.
3135 In addition, if the window overrides ShouldInheritColours() to return @false,
3136 the colours will not be changed no matter what and only the font might.
3138 This rather complicated logic is necessary in order to accommodate the
3139 different usage scenarios. The most common one is when all default attributes
3140 are used and in this case, nothing should be inherited as in modern GUIs
3141 different controls use different fonts (and colours) than their siblings so
3142 they can't inherit the same value from the parent. However it was also deemed
3143 desirable to allow to simply change the attributes of all children at once by
3144 just changing the font or colour of their common parent, hence in this case we
3145 do inherit the parents attributes.
3147 virtual void InheritAttributes();
3150 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
3151 to the dialog via validators.
3153 virtual void InitDialog();
3156 Returns @true if the window contents is double-buffered by the system, i.e. if
3157 any drawing done on the window is really done on a temporary backing surface
3158 and transferred to the screen all at once later.
3162 virtual bool IsDoubleBuffered() const;
3165 Turn on or off double buffering of the window if the system supports it.
3167 void SetDoubleBuffered(bool on
);
3170 Returns @true if the window is retained, @false otherwise.
3172 @remarks Retained windows are only available on X platforms.
3174 virtual bool IsRetained() const;
3177 Returns @true if this window is intrinsically enabled, @false otherwise,
3178 i.e. if @ref Enable() Enable(@false) had been called. This method is
3179 mostly used for wxWidgets itself, user code should normally use
3180 IsEnabled() instead.
3182 bool IsThisEnabled() const;
3185 Returns @true if the given window is a top-level one. Currently all frames and
3186 dialogs are considered to be top-level windows (even if they have a parent
3189 virtual bool IsTopLevel() const;
3193 This virtual function is normally only used internally, but
3194 sometimes an application may need it to implement functionality
3195 that should not be disabled by an application defining an OnIdle
3196 handler in a derived class.
3198 This function may be used to do delayed painting, for example,
3199 and most implementations call UpdateWindowUI()
3200 in order to send update events to the window in idle time.
3202 virtual void OnInternalIdle();
3205 Registers a system wide hotkey. Every time the user presses the hotkey
3206 registered here, this window will receive a hotkey event.
3208 It will receive the event even if the application is in the background
3209 and does not have the input focus because the user is working with some
3213 Numeric identifier of the hotkey. For applications this must be between 0
3214 and 0xBFFF. If this function is called from a shared DLL, it must be a
3215 system wide unique identifier between 0xC000 and 0xFFFF.
3216 This is a MSW specific detail.
3218 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
3219 or wxMOD_WIN specifying the modifier keys that have to be pressed along
3221 @param virtualKeyCode
3222 The virtual key code of the hotkey.
3224 @return @true if the hotkey was registered successfully. @false if some
3225 other application already registered a hotkey with this
3226 modifier/virtualKeyCode combination.
3228 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
3229 event. This function is currently only implemented
3230 under Windows. It is used in the Windows CE port for
3231 detecting hardware button presses.
3233 @see UnregisterHotKey()
3235 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
3236 int virtualKeyCode
);
3239 Unregisters a system wide hotkey.
3242 Numeric identifier of the hotkey. Must be the same id that was passed to
3245 @return @true if the hotkey was unregistered successfully, @false if the
3248 @remarks This function is currently only implemented under MSW.
3250 @see RegisterHotKey()
3252 virtual bool UnregisterHotKey(int hotkeyId
);
3255 This function sends one or more wxUpdateUIEvent to the window.
3256 The particular implementation depends on the window; for example a
3257 wxToolBar will send an update UI event for each toolbar button,
3258 and a wxFrame will send an update UI event for each menubar menu item.
3260 You can call this function from your application to ensure that your
3261 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
3262 are concerned). This may be necessary if you have called
3263 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
3264 the overhead that wxWidgets incurs by sending update UI events in idle time.
3265 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
3267 If you are calling this function from an OnInternalIdle or OnIdle
3268 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
3269 this tells the window to only update the UI elements that need
3270 to be updated in idle time. Some windows update their elements
3271 only when necessary, for example when a menu is about to be shown.
3272 The following is an example of how to call UpdateWindowUI from
3276 void MyWindow::OnInternalIdle()
3278 if (wxUpdateUIEvent::CanUpdate(this))
3279 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
3283 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
3285 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
3290 // NOTE: static functions must have their own group or Doxygen will screw
3291 // up the ordering of the member groups
3294 @name Miscellaneous static functions
3299 Returns the default font and colours which are used by the control.
3301 This is useful if you want to use the same font or colour in your own control
3302 as in a standard control -- which is a much better idea than hard coding specific
3303 colours or fonts which might look completely out of place on the users
3304 system, especially if it uses themes.
3306 The @a variant parameter is only relevant under Mac currently and is
3307 ignore under other platforms. Under Mac, it will change the size of the
3308 returned font. See SetWindowVariant() for more about this.
3310 This static method is "overridden" in many derived classes and so calling,
3311 for example, wxButton::GetClassDefaultAttributes() will typically
3312 return the values appropriate for a button which will be normally different
3313 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
3315 The @c wxVisualAttributes structure has at least the fields
3316 @c font, @c colFg and @c colBg. All of them may be invalid
3317 if it was not possible to determine the default control appearance or,
3318 especially for the background colour, if the field doesn't make sense as is
3319 the case for @c colBg for the controls with themed background.
3321 @see InheritAttributes()
3323 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
3326 Finds the window or control which currently has the keyboard focus.
3328 @remarks Note that this is a static function, so it can be called without
3329 needing a wxWindow pointer.
3331 @see SetFocus(), HasFocus()
3333 static wxWindow
* FindFocus();
3336 Find the first window with the given @e id.
3338 If @a parent is @NULL, the search will start from all top-level frames
3339 and dialog boxes; if non-@NULL, the search will be limited to the given
3341 The search is recursive in both cases.
3345 @return Window with the given @a id or @NULL if not found.
3347 static wxWindow
* FindWindowById(long id
, const wxWindow
* parent
= 0);
3350 Find a window by its label.
3352 Depending on the type of window, the label may be a window title
3353 or panel item label. If @a parent is @NULL, the search will start from all
3354 top-level frames and dialog boxes; if non-@NULL, the search will be
3355 limited to the given window hierarchy.
3356 The search is recursive in both cases.
3360 @return Window with the given @a label or @NULL if not found.
3362 static wxWindow
* FindWindowByLabel(const wxString
& label
,
3363 const wxWindow
* parent
= 0);
3366 Find a window by its name (as given in a window constructor or Create()
3369 If @a parent is @NULL, the search will start from all top-level frames
3370 and dialog boxes; if non-@NULL, the search will be limited to the given
3373 The search is recursive in both cases. If no window with such name is found,
3374 FindWindowByLabel() is called.
3378 @return Window with the given @a name or @NULL if not found.
3380 static wxWindow
* FindWindowByName(const wxString
& name
,
3381 const wxWindow
* parent
= 0);
3384 Returns the currently captured window.
3386 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
3387 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3389 static wxWindow
* GetCapture();
3392 Create a new ID or range of IDs that are not currently in use.
3393 The IDs will be reserved until assigned to a wxWindow ID
3394 or unreserved with UnreserveControlId().
3396 See @ref overview_windowids for more information.
3399 The number of sequential IDs to reserve.
3401 @return Returns the ID or the first ID of the range (i.e. the most negative),
3402 or wxID_NONE if the specified number of identifiers couldn't be allocated.
3404 @see UnreserveControlId(), wxIdManager,
3405 @ref overview_windowids
3407 static wxWindowID
NewControlId(int count
= 1);
3410 Unreserve an ID or range of IDs that was reserved by NewControlId().
3411 See @ref overview_windowids for more information.
3414 The starting ID of the range of IDs to unreserve.
3416 The number of sequential IDs to unreserve.
3418 @see NewControlId(), wxIdManager, @ref overview_windowids
3420 static void UnreserveControlId(wxWindowID id
, int count
= 1);
3432 Specifies the direction for the centring. May be wxHORIZONTAL,
3433 wxVERTICAL or wxBOTH. It may also include the wxCENTRE_ON_SCREEN
3436 @remarks This function is not meant to be called directly by user code,
3437 but via Centre, Center, CentreOnParent, or CenterOnParent.
3438 This function can be overridden to fine-tune centring behaviour.
3440 virtual void DoCentre(int direction
);
3443 Implementation of GetBestSize() that can be overridden.
3445 Notice that it is usually more convenient to override
3446 DoGetBestClientSize() rather than this method itself as you need to
3447 explicitly account for the window borders size if you do the latter.
3449 The default implementation of this function is designed for use in container
3450 windows, such as wxPanel, and works something like this:
3451 -# If the window has a sizer then it is used to calculate the best size.
3452 -# Otherwise if the window has layout constraints then those are used to
3453 calculate the best size.
3454 -# Otherwise if the window has children then the best size is set to be large
3455 enough to show all the children.
3456 -# Otherwise if there are no children then the window's minimal size will be
3457 used as its best size.
3458 -# Otherwise if there is no minimal size set, then the current size is used
3461 @see @ref overview_windowsizing
3463 virtual wxSize
DoGetBestSize() const;
3466 Override this method to return the best size for a custom control.
3468 A typical implementation of this method should compute the minimal size
3469 needed to fully display the control contents taking into account the
3472 The default implementation simply returns ::wxDefaultSize and
3473 GetBestSize() returns an arbitrary hardcoded size for the window, so
3474 you must override it when implementing a custom window class.
3476 @see @ref overview_windowsizing
3480 virtual wxSize
DoGetBestClientSize() const;
3484 Sets the initial window size if none is given (i.e. at least one of the
3485 components of the size passed to ctor/Create() is wxDefaultCoord).
3486 @deprecated Use SetInitialSize() instead.
3488 virtual void SetInitialBestSize(const wxSize
& size
);
3491 Generate wxWindowDestroyEvent for this window.
3493 This is called by the window itself when it is being destroyed and
3494 usually there is no need to call it but see wxWindowDestroyEvent for
3495 explanations of when you might want to do it.
3497 void SendDestroyEvent();
3500 This function is public in wxEvtHandler but protected in wxWindow
3501 because for wxWindows you should always call ProcessEvent() on the
3502 pointer returned by GetEventHandler() and not on the wxWindow object
3505 For convenience, a ProcessWindowEvent() method is provided as a synonym
3506 for @code GetEventHandler()->ProcessEvent() @endcode
3508 Note that it's still possible to call these functions directly on the
3509 wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
3510 create subtle bugs when windows with event handlers pushed on them are
3513 This holds also for all other wxEvtHandler functions.
3515 virtual bool ProcessEvent(wxEvent
& event
);
3519 See ProcessEvent() for more info about why you shouldn't use this function
3520 and the reason for making this function protected in wxWindow.
3522 bool SafelyProcessEvent(wxEvent
& event
);
3523 virtual void QueueEvent(wxEvent
*event
);
3524 virtual void AddPendingEvent(const wxEvent
& event
);
3525 void ProcessPendingEvents();
3526 bool ProcessThreadEvent(const wxEvent
& event
);
3532 // ============================================================================
3533 // Global functions/macros
3534 // ============================================================================
3536 /** @addtogroup group_funcmacro_misc */
3540 Find the deepest window at the mouse pointer position, returning the window
3541 and current pointer position in screen coordinates.
3543 @header{wx/window.h}
3545 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
3548 Gets the currently active window (implemented for MSW and GTK only
3549 currently, always returns @NULL in the other ports).
3551 @header{wx/window.h}
3553 wxWindow
* wxGetActiveWindow();
3556 Returns the first top level parent of the given window, or in other words,
3557 the frame or dialog containing it, or @NULL.
3559 @header{wx/window.h}
3561 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);