1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
15 /// Roll window to the left
16 wxSHOW_EFFECT_ROLL_TO_LEFT
,
18 /// Roll window to the right
19 wxSHOW_EFFECT_ROLL_TO_RIGHT
,
21 /// Roll window to the top
22 wxSHOW_EFFECT_ROLL_TO_TOP
,
24 /// Roll window to the bottom
25 wxSHOW_EFFECT_ROLL_TO_BOTTOM
,
27 /// Slide window to the left
28 wxSHOW_EFFECT_SLIDE_TO_LEFT
,
30 /// Slide window to the right
31 wxSHOW_EFFECT_SLIDE_TO_RIGHT
,
33 /// Slide window to the top
34 wxSHOW_EFFECT_SLIDE_TO_TOP
,
36 /// Slide window to the bottom
37 wxSHOW_EFFECT_SLIDE_TO_BOTTOM
,
39 /// Fade in or out effect
42 /// Expanding or collapsing effect
47 Different window variants, on platforms like eg mac uses different
52 wxWINDOW_VARIANT_NORMAL
, //!< Normal size
53 wxWINDOW_VARIANT_SMALL
, //!< Smaller size (about 25 % smaller than normal)
54 wxWINDOW_VARIANT_MINI
, //!< Mini size (about 33 % smaller than normal)
55 wxWINDOW_VARIANT_LARGE
, //!< Large size (about 25 % larger than normal)
63 wxWindow is the base class for all windows and represents any visible object
64 om screen. All controls, top level windows and so on are windows. Sizers and
65 device contexts are not, however, as they don't appear on screen themselves.
67 Please note that all children of the window will be deleted automatically by
68 the destructor before the window itself is deleted which means that you don't
69 have to worry about deleting them manually. Please see the @ref
70 overview_windowdeletion "window deletion overview" for more information.
72 Also note that in this, and many others, wxWidgets classes some
73 @c GetXXX() methods may be overloaded (as, for example,
74 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
75 are non-virtual because having multiple virtual functions with the same name
76 results in a virtual function name hiding at the derived class level (in
77 English, this means that the derived class has to override all overloaded
78 variants if it overrides any of them). To allow overriding them in the derived
79 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
80 and all @c GetXXX() ones are forwarded to it, so overriding the former
81 changes the behaviour of the latter.
84 @style{wxBORDER_DEFAULT}
85 The window class will decide the kind of border to show, if any.
86 @style{wxBORDER_SIMPLE}
87 Displays a thin border around the window. wxSIMPLE_BORDER is the
88 old name for this style.
89 @style{wxBORDER_SUNKEN}
90 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
92 @style{wxBORDER_RAISED}
93 Displays a raised border. wxRAISED_BORDER is the old name for this
95 @style{wxBORDER_STATIC}
96 Displays a border suitable for a static control. wxSTATIC_BORDER
97 is the old name for this style. Windows only.
98 @style{wxBORDER_THEME}
99 Displays a native border suitable for a control, on the current
100 platform. On Windows XP or Vista, this will be a themed border; on
101 most other platforms a sunken border will be used. For more
102 information for themed borders on Windows, please see Themed
104 @style{wxBORDER_NONE}
105 Displays no border, overriding the default border style for the
106 window. wxNO_BORDER is the old name for this style.
107 @style{wxBORDER_DOUBLE}
108 This style is obsolete and should not be used.
109 @style{wxTRANSPARENT_WINDOW}
110 The window is transparent, that is, it will not receive paint
111 events. Windows only.
112 @style{wxTAB_TRAVERSAL}
113 Use this to enable tab traversal for non-dialog windows.
114 @style{wxWANTS_CHARS}
115 Use this to indicate that the window wants to get all char/key
116 events for all keys - even for keys like TAB or ENTER which are
117 usually used for dialog navigation and which wouldn't be generated
118 without this style. If you need to use this style in order to get
119 the arrows or etc., but would still like to have normal keyboard
120 navigation take place, you should call Navigate in response to the
121 key events for Tab and Shift-Tab.
122 @style{wxNO_FULL_REPAINT_ON_RESIZE}
123 On Windows, this style used to disable repainting the window
124 completely when its size is changed. Since this behaviour is now
125 the default, the style is now obsolete and no longer has an effect.
127 Use this style to enable a vertical scrollbar. Notice that this
128 style cannot be used with native controls which don't support
129 scrollbars nor with top-level windows in most ports.
131 Use this style to enable a horizontal scrollbar. The same
132 limitations as for wxVSCROLL apply to this style.
133 @style{wxALWAYS_SHOW_SB}
134 If a window has scrollbars, disable them instead of hiding them
135 when they are not needed (i.e. when the size of the window is big
136 enough to not require the scrollbars to navigate it). This style is
137 currently implemented for wxMSW, wxGTK and wxUniversal and does
138 nothing on the other platforms.
139 @style{wxCLIP_CHILDREN}
140 Use this style to eliminate flicker caused by the background being
141 repainted, then children being painted over them. Windows only.
142 @style{wxFULL_REPAINT_ON_RESIZE}
143 Use this style to force a complete redraw of the window whenever it
144 is resized instead of redrawing just the part of the window
145 affected by resizing. Note that this was the behaviour by default
146 before 2.5.1 release and that if you experience redraw problems
147 with code which previously used to work you may want to try this.
148 Currently this style applies on GTK+ 2 and Windows only, and full
149 repainting is always done on other platforms.
152 @beginExtraStyleTable
153 @style{wxWS_EX_VALIDATE_RECURSIVELY}
154 By default, Validate/TransferDataTo/FromWindow() only work on
155 direct children of the window (compatible behaviour). Set this flag
156 to make them recursively descend into all subwindows.
157 @style{wxWS_EX_BLOCK_EVENTS}
158 wxCommandEvents and the objects of the derived classes are
159 forwarded to the parent window and so on recursively by default.
160 Using this flag for the given window allows to block this
161 propagation at this window, i.e. prevent the events from being
162 propagated further upwards. Dialogs have this flag on by default
163 for the reasons explained in the @ref overview_eventhandling "Event Handling Overview".
164 @style{wxWS_EX_TRANSIENT}
165 Don't use this window as an implicit parent for the other windows:
166 this must be used with transient windows as otherwise there is the
167 risk of creating a dialog/frame with this window as a parent which
168 would lead to a crash if the parent is destroyed before the child.
169 @style{wxWS_EX_CONTEXTHELP}
170 Under Windows, puts a query button on the caption. When pressed,
171 Windows will go into a context-sensitive help mode and wxWidgets
172 will send a wxEVT_HELP event if the user clicked on an application window.
173 This style cannot be used (because of the underlying native behaviour)
174 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
175 are automatically turned off if this one is used.
176 @style{wxWS_EX_PROCESS_IDLE}
177 This window should always process idle events, even if the mode set
178 by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
179 @style{wxWS_EX_PROCESS_UI_UPDATES}
180 This window should always process UI update events, even if the
181 mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED.
187 @see @ref overview_eventhandling "Event handling overview",
188 @ref overview_windowsizing "Window sizing overview"
190 class wxWindow
: public wxEvtHandler
199 Constructs a window, which can be a child of a frame, dialog or any other
203 Pointer to a parent window.
205 Window identifier. If wxID_ANY, will automatically create an identifier.
207 Window position. wxDefaultPosition indicates that wxWidgets
208 should generate a default position for the window.
209 If using the wxWindow class directly, supply an actual position.
211 Window size. wxDefaultSize indicates that wxWidgets should generate
212 a default size for the window. If no suitable size can be found, the
213 window will be sized to 20x20 pixels so that the window is visible but
214 obviously not correctly sized.
216 Window style. For generic window styles, please see wxWindow.
220 wxWindow(wxWindow
* parent
, wxWindowID id
,
221 const wxPoint
& pos
= wxDefaultPosition
,
222 const wxSize
& size
= wxDefaultSize
,
224 const wxString
& name
= wxPanelNameStr
);
229 Deletes all sub-windows, then deletes itself. Instead of using
230 the @b delete operator explicitly, you should normally use Destroy()
231 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
233 @see @ref overview_windowdeletion "Window Deletion Overview",
234 Destroy(), wxCloseEvent
240 @name Focus functions
242 See also the static function FindFocus().
247 This method may be overridden in the derived classes to return @false to
248 indicate that this control doesn't accept input at all (i.e. behaves like
249 e.g. wxStaticText) and so doesn't need focus.
251 @see AcceptsFocusFromKeyboard()
253 virtual bool AcceptsFocus() const;
256 This method may be overridden in the derived classes to return @false to
257 indicate that while this control can, in principle, have focus if the user
258 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
259 when using the keyboard.
261 virtual bool AcceptsFocusFromKeyboard() const;
264 Overridden to indicate wehter this window or one of its children accepts
265 focus. Usually it's the same as AcceptsFocus() but is overridden for
268 virtual bool AcceptsFocusRecursively() const;
271 Returns @true if the window (or in case of composite controls, its main
272 child window) has focus.
276 virtual bool HasFocus() const;
279 This method is only implemented by ports which have support for
280 native TAB traversal (such as GTK+ 2.0).
282 It is called by wxWidgets' container control code to give the native
283 system a hint when doing TAB traversal. A call to this does not disable
284 or change the effect of programmatically calling SetFocus().
286 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
288 virtual void SetCanFocus(bool canFocus
);
291 This sets the window to receive keyboard input.
293 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
294 wxPanel::SetFocusIgnoringChildren
296 virtual void SetFocus();
299 This function is called by wxWidgets keyboard navigation code when the user
300 gives the focus to this window from keyboard (e.g. using @c TAB key).
302 By default this method simply calls SetFocus() but
303 can be overridden to do something in addition to this in the derived classes.
305 virtual void SetFocusFromKbd();
311 @name Child management functions
316 Adds a child window. This is called automatically by window creation
317 functions so should not be required by the application programmer.
318 Notice that this function is mostly internal to wxWidgets and shouldn't be
319 called by the user code.
324 virtual void AddChild(wxWindow
* child
);
327 Destroys all children of a window. Called automatically by the destructor.
329 bool DestroyChildren();
332 Find a child of this window, by @a id.
333 May return @a this if it matches itself.
335 wxWindow
* FindWindow(long id
) const;
338 Find a child of this window, by name.
339 May return @a this if it matches itself.
341 wxWindow
* FindWindow(const wxString
& name
) const;
344 Returns a reference to the list of the window's children. @c wxWindowList
345 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
347 wxWindowList
& GetChildren();
352 const wxWindowList
& GetChildren() const;
355 Removes a child window.
357 This is called automatically by window deletion functions so should not
358 be required by the application programmer.
359 Notice that this function is mostly internal to wxWidgets and shouldn't be
360 called by the user code.
363 Child window to remove.
365 virtual void RemoveChild(wxWindow
* child
);
371 @name Sibling and parent management functions
376 Returns the grandparent of a window, or @NULL if there isn't one.
378 wxWindow
* GetGrandParent() const;
381 Returns the next window after this one among the parent children or @NULL
382 if this window is the last child.
386 @see GetPrevSibling()
388 wxWindow
* GetNextSibling() const;
391 Returns the parent of the window, or @NULL if there is no parent.
393 wxWindow
* GetParent() const;
396 Returns the previous window before this one among the parent children or @c
397 @NULL if this window is the first child.
401 @see GetNextSibling()
403 wxWindow
* GetPrevSibling() const;
405 Reparents the window, i.e the window will be removed from its
406 current parent window (e.g. a non-standard toolbar in a wxFrame)
407 and then re-inserted into another.
412 virtual bool Reparent(wxWindow
* newParent
);
418 @name Scrolling and scrollbars functions
423 Call this function to force one or both scrollbars to be always shown, even if
424 the window is big enough to show its entire contents without scrolling.
429 Whether the horizontal scroll bar should always be visible.
431 Whether the vertical scroll bar should always be visible.
433 @remarks This function is currently only implemented under Mac/Carbon.
435 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
438 Returns the built-in scrollbar position.
440 @see See SetScrollbar()
442 virtual int GetScrollPos(int orientation
) const;
445 Returns the built-in scrollbar range.
449 virtual int GetScrollRange(int orientation
) const;
452 Returns the built-in scrollbar thumb size.
456 virtual int GetScrollThumb(int orientation
) const;
459 Returns @true if this window has a scroll bar for this orientation.
462 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
464 bool HasScrollbar(int orient
) const;
467 Return whether a scrollbar is always shown.
470 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
472 @see AlwaysShowScrollbars()
474 virtual bool IsScrollbarAlwaysShown(int orient
) const;
477 Scrolls the window by the given number of lines down (if @a lines is
480 @return Returns @true if the window was scrolled, @false if it was already
481 on top/bottom and nothing was done.
483 @remarks This function is currently only implemented under MSW and
484 wxTextCtrl under wxGTK (it also works for wxScrolled classes
485 under all platforms).
489 virtual bool ScrollLines(int lines
);
492 Scrolls the window by the given number of pages down (if @a pages is
495 @return Returns @true if the window was scrolled, @false if it was already
496 on top/bottom and nothing was done.
498 @remarks This function is currently only implemented under MSW and wxGTK.
502 virtual bool ScrollPages(int pages
);
505 Physically scrolls the pixels in the window and move child windows accordingly.
508 Amount to scroll horizontally.
510 Amount to scroll vertically.
512 Rectangle to scroll, if it is @NULL, the whole window is
513 scrolled (this is always the case under wxGTK which doesn't support this
516 @remarks Note that you can often use wxScrolled instead of using this
519 virtual void ScrollWindow(int dx
, int dy
,
520 const wxRect
* rect
= NULL
);
523 Same as #ScrollLines (-1).
528 Same as #ScrollLines (1).
533 Same as #ScrollPages (-1).
538 Same as #ScrollPages (1).
543 Sets the position of one of the built-in scrollbars.
546 Determines the scrollbar whose position is to be set.
547 May be wxHORIZONTAL or wxVERTICAL.
549 Position in scroll units.
551 @true to redraw the scrollbar, @false otherwise.
553 @remarks This function does not directly affect the contents of the
554 window: it is up to the application to take note of
555 scrollbar attributes and redraw contents accordingly.
557 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
560 virtual void SetScrollPos(int orientation
, int pos
,
561 bool refresh
= true);
564 Sets the scrollbar properties of a built-in scrollbar.
567 Determines the scrollbar whose page size is to be set.
568 May be wxHORIZONTAL or wxVERTICAL.
570 The position of the scrollbar in scroll units.
572 The size of the thumb, or visible portion of the scrollbar, in scroll units.
574 The maximum position of the scrollbar. Value of -1 can be used to
575 ask for the scrollbar to be shown but in the disabled state: this
576 can be used to avoid removing the scrollbar even when it is not
577 needed (currently this is only implemented in wxMSW port).
579 @true to redraw the scrollbar, @false otherwise.
582 Let's say you wish to display 50 lines of text, using the same font.
583 The window is sized so that you can only see 16 lines at a time.
586 SetScrollbar(wxVERTICAL, 0, 16, 50);
588 Note that with the window at this size, the thumb position can never
589 go above 50 minus 16, or 34. You can determine how many lines are
590 currently visible by dividing the current view size by the character
592 When defining your own scrollbar behaviour, you will always need
593 to recalculate the scrollbar settings when the window size changes.
594 You could therefore put your scrollbar calculations and SetScrollbar
595 call into a function named AdjustScrollbars, which can be called
596 initially and also from your wxSizeEvent handler function.
598 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
600 virtual void SetScrollbar(int orientation
, int position
,
601 int thumbSize
, int range
,
602 bool refresh
= true);
607 @name Sizing functions
609 See also the protected functions DoGetBestSize() and SetInitialBestSize().
614 Sets the cached best size value.
616 void CacheBestSize(const wxSize
& size
) const;
619 Converts client area size @a size to corresponding window size.
621 In other words, the returned value is what would GetSize() return if this
622 window had client area of given size. Components with wxDefaultCoord
623 value are left unchanged. Note that the conversion is not always
624 exact, it assumes that non-client area doesn't change and so doesn't
625 take into account things like menu bar (un)wrapping or (dis)appearance
630 @see WindowToClientSize()
632 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
635 Converts window size @a size to corresponding client area size
636 In other words, the returned value is what would GetClientSize() return if
637 this window had given window size. Components with wxDefaultCoord value
640 Note that the conversion is not always exact, it assumes that
641 non-client area doesn't change and so doesn't take into account things
642 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
646 @see ClientToWindowSize()
648 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
651 Sizes the window so that it fits around its subwindows.
653 This function won't do anything if there are no subwindows and will only really
654 work correctly if sizers are used for the subwindows layout.
656 Also, if the window has exactly one subwindow it is better (faster and the result
657 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
661 window->SetClientSize(child->GetSize());
664 instead of calling Fit().
666 @see @ref overview_windowsizing
671 Similar to Fit(), but sizes the interior (virtual) size of a window.
673 Mainly useful with scrolled windows to reset scrollbars after sizing
674 changes that do not trigger a size event, and/or scrolled windows without
675 an interior sizer. This function similarly won't do anything if there are
678 virtual void FitInside();
681 This functions returns the best acceptable minimal size for the window.
683 For example, for a static control, it will be the minimal size such that the
684 control label is not truncated. For windows containing subwindows (typically
685 wxPanel), the size returned by this function will be the same as the size
686 the window would have had after calling Fit().
688 wxSize
GetBestSize() const;
691 Returns the size of the window 'client area' in pixels.
693 The client area is the area which may be drawn on by the programmer,
694 excluding title bar, border, scrollbars, etc.
695 Note that if this window is a top-level one and it is currently minimized, the
696 return size is empty (both width and height are 0).
698 @see GetSize(), GetVirtualSize()
700 void GetClientSize(int* width
, int* height
) const;
705 wxSize
GetClientSize() const;
708 Merges the window's best size into the min size and returns the result.
709 This is the value used by sizers to determine the appropriate
710 ammount of space to allocate for the widget.
712 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
714 wxSize
GetEffectiveMinSize() const;
717 Returns the maximum size of window's client area.
719 This is an indication to the sizer layout mechanism that this is the maximum
720 possible size as well as the upper bound on window's size settable using
725 virtual wxSize
GetMaxClientSize() const;
728 Returns the maximum size of the window.
730 This is an indication to the sizer layout mechanism that this is the maximum
731 possible size as well as the upper bound on window's size settable using SetSize().
733 @see GetMaxClientSize()
735 virtual wxSize
GetMaxSize() const;
738 Returns the minimum size of window's client area, an indication to the sizer
739 layout mechanism that this is the minimum required size of its client area.
741 It normally just returns the value set by SetMinClientSize(), but it can be
742 overridden to do the calculation on demand.
746 virtual wxSize
GetMinClientSize() const;
749 Returns the minimum size of the window, an indication to the sizer layout
750 mechanism that this is the minimum required size.
752 This method normally just returns the value set by SetMinSize(), but it
753 can be overridden to do the calculation on demand.
755 @see GetMinClientSize()
757 virtual wxSize
GetMinSize() const;
760 Returns the size of the entire window in pixels, including title bar, border,
763 Note that if this window is a top-level one and it is currently minimized, the
764 returned size is the restored window size, not the size of the window icon.
767 Receives the window width.
769 Receives the window height.
771 @see GetClientSize(), GetVirtualSize()
773 void GetSize(int* width
, int* height
) const;
776 See the GetSize(int*,int*) overload for more info.
778 wxSize
GetSize() const;
781 This gets the virtual size of the window in pixels.
782 By default it returns the client size of the window, but after a call to
783 SetVirtualSize() it will return the size set with that method.
785 wxSize
GetVirtualSize() const;
788 Like the other GetVirtualSize() overload but uses pointers instead.
791 Receives the window virtual width.
793 Receives the window virtual height.
795 void GetVirtualSize(int* width
, int* height
) const;
798 Returns the size of the left/right and top/bottom borders of this window in x
799 and y components of the result respectively.
801 virtual wxSize
GetWindowBorderSize() const;
804 Resets the cached best size value so it will be recalculated the next time it
807 void InvalidateBestSize();
809 Posts a size event to the window.
811 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
813 void PostSizeEvent();
816 Posts a size event to the parent of this window.
818 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
821 void PostSizeEventToParent();
824 This function sends a dummy @ref wxSizeEvent "size event" to
825 the window allowing it to re-layout its children positions.
827 It is sometimes useful to call this function after adding or deleting a
828 children after the frame creation or if a child size changes. Note that
829 if the frame is using either sizers or constraints for the children
830 layout, it is enough to call wxWindow::Layout() directly and this
831 function should not be used in this case.
833 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
834 the event, i.e. schedules it for later processing, instead of
835 dispatching it directly. You can also use PostSizeEvent() as a more
836 readable equivalent of calling this function with this flag.
839 May include @c wxSEND_EVENT_POST. Default value is 0.
841 virtual void SendSizeEvent(int flags
= 0);
844 Safe wrapper for GetParent()->SendSizeEvent().
846 This function simply checks that the window has a valid parent which is
847 not in process of being deleted and calls SendSizeEvent() on it. It is
848 used internally by windows such as toolbars changes to whose state
849 should result in parent re-layout (e.g. when a toolbar is added to the
850 top of the window, all the other windows must be shifted down).
852 @see PostSizeEventToParent()
855 See description of this parameter in SendSizeEvent() documentation.
857 void SendSizeEventToParent(int flags
= 0);
860 This sets the size of the window client area in pixels.
862 Using this function to size a window tends to be more device-independent
863 than SetSize(), since the application need not worry about what dimensions
864 the border or title bar have when trying to fit the window around panel
867 virtual void SetClientSize(int width
, int height
);
872 virtual void SetClientSize(const wxSize
& size
);
875 This normally does not need to be called by user code.
876 It is called when a window is added to a sizer, and is used so the window
877 can remove itself from the sizer when it is destroyed.
879 void SetContainingSizer(wxSizer
* sizer
);
882 A @e smart SetSize that will fill in default size components with the
883 window's @e best size values.
885 Also sets the window's minsize to the value passed in for use with sizers.
886 This means that if a full or partial size is passed to this function then
887 the sizers will use that size instead of the results of GetBestSize() to
888 determine the minimum needs of the window for layout.
890 Most controls will use this to set their initial size, and their min
891 size to the passed in value (if any.)
893 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
894 @ref overview_windowsizing
896 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
899 Sets the maximum client size of the window, to indicate to the sizer
900 layout mechanism that this is the maximum possible size of its client area.
904 virtual void SetMaxClientSize(const wxSize
& size
);
907 Sets the maximum size of the window, to indicate to the sizer layout mechanism
908 that this is the maximum possible size.
910 @see SetMaxClientSize()
912 virtual void SetMaxSize(const wxSize
& size
);
915 Sets the minimum client size of the window, to indicate to the sizer
916 layout mechanism that this is the minimum required size of window's client
919 You may need to call this if you change the window size after
920 construction and before adding to its parent sizer.
922 Note, that just as with SetMinSize(), calling this method doesn't
923 prevent the program from explicitly making the window smaller than the
928 virtual void SetMinClientSize(const wxSize
& size
);
931 Sets the minimum size of the window, to indicate to the sizer layout
932 mechanism that this is the minimum required size.
934 You may need to call this if you change the window size after
935 construction and before adding to its parent sizer.
937 Notice that calling this method doesn't prevent the program from making
938 the window explicitly smaller than the specified size by calling
939 SetSize(), it just ensures that it won't become smaller than this size
940 during the automatic layout.
942 @see SetMinClientSize()
944 virtual void SetMinSize(const wxSize
& size
);
947 Sets the size of the window in pixels.
950 Required x position in pixels, or wxDefaultCoord to indicate that the
951 existing value should be used.
953 Required y position in pixels, or wxDefaultCoord to indicate that the
954 existing value should be used.
956 Required width in pixels, or wxDefaultCoord to indicate that the existing
957 value should be used.
959 Required height position in pixels, or wxDefaultCoord to indicate that the
960 existing value should be used.
962 Indicates the interpretation of other parameters.
963 It is a bit list of the following:
964 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
965 a wxWidgets-supplied default width.
966 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
967 a wxWidgets-supplied default height.
968 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
969 a wxWidgets-supplied default size.
970 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
971 if wxDefaultCoord values are supplied.
972 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
973 wxDefaultCoord) to be interpreted as real
974 dimensions, not default values.
975 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
976 already the same as the parameters of this function,
977 nothing is done. but with this flag a window resize may
978 be forced even in this case (supported in wx 2.6.2 and
979 later and only implemented for MSW and ignored elsewhere
982 @remarks This overload sets the position and optionally size, of the window.
983 Parameters may be wxDefaultCoord to indicate either that a default
984 should be supplied by wxWidgets, or that the current value of the
985 dimension should be used.
989 void SetSize(int x
, int y
, int width
, int height
,
990 int sizeFlags
= wxSIZE_AUTO
);
993 Sets the size of the window in pixels.
994 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
996 @remarks This form must be used with non-default width and height values.
1000 virtual void SetSize(const wxRect
& rect
);
1005 virtual void SetSize(const wxSize
& size
);
1010 virtual void SetSize(int width
, int height
);
1013 Use of this function for windows which are not toplevel windows
1014 (such as wxDialog or wxFrame) is discouraged.
1015 Please use SetMinSize() and SetMaxSize() instead.
1017 @see wxTopLevelWindow::SetSizeHints
1019 void SetSizeHints( const wxSize
& minSize
,
1020 const wxSize
& maxSize
=wxDefaultSize
,
1021 const wxSize
& incSize
=wxDefaultSize
);
1024 Sets the virtual size of the window in pixels.
1026 void SetVirtualSize(int width
, int height
);
1031 void SetVirtualSize(const wxSize
& size
);
1037 @name Positioning functions
1042 A synonym for Centre().
1044 void Center(int dir
= wxBOTH
);
1047 A synonym for CentreOnParent().
1049 void CenterOnParent(int dir
= wxBOTH
);
1055 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1056 or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
1057 if you want to center the window on the entire screen and not on its
1060 @remarks If the window is a top level one (i.e. doesn't have a parent),
1061 it will be centered relative to the screen anyhow.
1065 void Centre(int direction
= wxBOTH
);
1068 Centres the window on its parent. This is a more readable synonym for Centre().
1071 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1074 @remarks This methods provides for a way to center top level windows over
1075 their parents instead of the entire screen. If there
1076 is no parent or if the window is not a top level
1077 window, then behaviour is the same as Centre().
1079 @see wxTopLevelWindow::CentreOnScreen
1081 void CentreOnParent(int direction
= wxBOTH
);
1083 This gets the position of the window in pixels, relative to the parent window
1084 for the child windows or relative to the display origin for the top level windows.
1087 Receives the x position of the window if non-@NULL.
1089 Receives the y position of the window if non-@NULL.
1091 @see GetScreenPosition()
1093 void GetPosition(int* x
, int* y
) const;
1096 This gets the position of the window in pixels, relative to the parent window
1097 for the child windows or relative to the display origin for the top level windows.
1099 @see GetScreenPosition()
1101 wxPoint
GetPosition() const;
1104 Returns the position and size of the window as a wxRect object.
1106 @see GetScreenRect()
1108 wxRect
GetRect() const;
1111 Returns the window position in screen coordinates, whether the window is a
1112 child window or a top level one.
1115 Receives the x position of the window on the screen if non-@NULL.
1117 Receives the y position of the window on the screen if non-@NULL.
1121 void GetScreenPosition(int* x
, int* y
) const;
1124 Returns the window position in screen coordinates, whether the window is a
1125 child window or a top level one.
1129 wxPoint
GetScreenPosition() const;
1132 Returns the position and size of the window on the screen as a wxRect object.
1136 wxRect
GetScreenRect() const;
1139 Moves the window to the given position.
1142 Required x position.
1144 Required y position.
1146 See SetSize() for more info about this parameter.
1148 @remarks Implementations of SetSize can also implicitly implement the
1149 Move() function, which is defined in the base wxWindow class as the call:
1151 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1156 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1159 Moves the window to the given position.
1162 wxPoint object representing the position.
1164 See SetSize() for more info about this parameter.
1166 @remarks Implementations of SetSize() can also implicitly implement the
1167 Move() function, which is defined in the base wxWindow class as the call:
1169 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1174 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1180 @name Coordinate conversion functions
1185 Converts to screen coordinates from coordinates relative to this window.
1188 A pointer to a integer value for the x coordinate. Pass the client
1189 coordinate in, and a screen coordinate will be passed out.
1191 A pointer to a integer value for the y coordinate. Pass the client
1192 coordinate in, and a screen coordinate will be passed out.
1195 In place of a single overloaded method name, wxPython implements the following methods:
1196 - ClientToScreen(point): Accepts and returns a wxPoint
1197 - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
1200 void ClientToScreen(int* x
, int* y
) const;
1203 Converts to screen coordinates from coordinates relative to this window.
1206 The client position for the second form of the function.
1208 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
1211 Converts a point or size from dialog units to pixels.
1213 For the x dimension, the dialog units are multiplied by the average character
1214 width and then divided by 4.
1215 For the y dimension, the dialog units are multiplied by the average character
1216 height and then divided by 8.
1218 @remarks Dialog units are used for maintaining a dialog's proportions
1219 even if the font changes.
1220 You can also use these functions programmatically.
1221 A convenience macro is defined:
1223 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1226 @see ConvertPixelsToDialog()
1228 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
);
1233 wxSize
ConvertDialogToPixels(const wxSize
& sz
);
1236 Converts a point or size from pixels to dialog units.
1238 For the x dimension, the pixels are multiplied by 4 and then divided by the
1239 average character width.
1240 For the y dimension, the pixels are multiplied by 8 and then divided by the
1241 average character height.
1243 @remarks Dialog units are used for maintaining a dialog's proportions
1244 even if the font changes.
1246 @see ConvertDialogToPixels()
1248 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
);
1253 wxSize
ConvertPixelsToDialog(const wxSize
& sz
);
1256 Converts from screen to client window coordinates.
1259 Stores the screen x coordinate and receives the client x coordinate.
1261 Stores the screen x coordinate and receives the client x coordinate.
1263 void ScreenToClient(int* x
, int* y
) const;
1266 Converts from screen to client window coordinates.
1269 The screen position.
1271 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1277 @name Drawing-related functions
1282 Clears the window by filling it with the current background colour. Does not
1283 cause an erase background event to be generated.
1285 virtual void ClearBackground();
1288 Freezes the window or, in other words, prevents any updates from taking
1289 place on screen, the window is not redrawn at all.
1291 Thaw() must be called to reenable window redrawing. Calls to these two
1292 functions may be nested but to ensure that the window is properly
1293 repainted again, you must thaw it exactly as many times as you froze it.
1295 If the window has any children, they are recursively frozen too.
1297 This method is useful for visual appearance optimization (for example,
1298 it is a good idea to use it before doing many large text insertions in
1299 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1300 platforms nor for all controls so it is mostly just a hint to wxWidgets
1301 and not a mandatory directive.
1303 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1308 Reenables window updating after a previous call to Freeze().
1310 To really thaw the control, it must be called exactly the same number
1311 of times as Freeze().
1313 If the window has any children, they are recursively thawn too.
1315 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1320 Returns @true if the window is currently frozen by a call to Freeze().
1322 @see Freeze(), Thaw()
1324 bool IsFrozen() const;
1327 Returns the background colour of the window.
1329 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1331 wxColour
GetBackgroundColour() const;
1334 Returns the background style of the window.
1335 The background style can be one of the wxBackgroundStyle.
1337 @see SetBackgroundColour(), GetForegroundColour(),
1338 SetBackgroundStyle(), SetTransparent()
1340 virtual wxBackgroundStyle
GetBackgroundStyle() const;
1342 Returns the character height for this window.
1344 virtual int GetCharHeight() const;
1347 Returns the average character width for this window.
1349 virtual int GetCharWidth() const;
1352 Currently this is the same as calling
1353 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1355 One advantage of using this function compared to the static version is that
1356 the call is automatically dispatched to the correct class (as usual with
1357 virtual functions) and you don't have to specify the class name explicitly.
1359 The other one is that in the future this function could return different
1360 results, for example it might return a different font for an "Ok" button
1361 than for a generic button if the users GUI is configured to show such buttons
1362 in bold font. Of course, the down side is that it is impossible to call this
1363 function without actually having an object to apply it to whereas the static
1364 version can be used without having to create an object first.
1366 virtual wxVisualAttributes
GetDefaultAttributes() const;
1369 Returns the font for this window.
1373 wxFont
GetFont() const;
1376 Returns the foreground colour of the window.
1378 @remarks The interpretation of foreground colour is open to
1379 interpretation according to the window class; it may be
1380 the text colour or other colour, or it may not be used at all.
1382 @see SetForegroundColour(), SetBackgroundColour(),
1383 GetBackgroundColour()
1385 wxColour
GetForegroundColour() const;
1388 Gets the dimensions of the string as it would be drawn on the
1389 window with the currently selected font.
1391 The text extent is returned in @a w and @a h pointers.
1394 String whose extent is to be measured.
1396 Return value for width.
1398 Return value for height.
1400 Return value for descent (optional).
1401 @param externalLeading
1402 Return value for external leading (optional).
1404 Font to use instead of the current window font (optional).
1406 virtual void GetTextExtent(const wxString
& string
, int* w
, int* h
,
1407 int* descent
= NULL
,
1408 int* externalLeading
= NULL
,
1409 const wxFont
* font
= NULL
) const;
1412 Gets the dimensions of the string as it would be drawn on the
1413 window with the currently selected font.
1415 wxSize
GetTextExtent(const wxString
& string
) const;
1418 Returns the region specifying which parts of the window have been damaged.
1419 Should only be called within an wxPaintEvent handler.
1421 @see wxRegion, wxRegionIterator
1423 const wxRegion
& GetUpdateRegion() const;
1426 Returns @true if this window background is transparent (as, for example,
1427 for wxStaticText) and should show the parent window background.
1429 This method is mostly used internally by the library itself and you normally
1430 shouldn't have to call it. You may, however, have to override it in your
1431 wxWindow-derived class to ensure that background is painted correctly.
1433 virtual bool HasTransparentBackground();
1436 Causes this window, and all of its children recursively (except under wxGTK1
1437 where this is not implemented), to be repainted. Note that repainting doesn't
1438 happen immediately but only during the next event loop iteration, if you need
1439 to update the window immediately you should use Update() instead.
1441 @param eraseBackground
1442 If @true, the background will be erased.
1444 If non-@NULL, only the given rectangle will be treated as damaged.
1448 virtual void Refresh(bool eraseBackground
= true,
1449 const wxRect
* rect
= NULL
);
1452 Redraws the contents of the given rectangle: only the area inside it will be
1455 This is the same as Refresh() but has a nicer syntax as it can be called
1456 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1458 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1461 Calling this method immediately repaints the invalidated area of the window and
1462 all of its children recursively while this would usually only happen when the
1463 flow of control returns to the event loop.
1465 Notice that this function doesn't invalidate any area of the window so
1466 nothing happens if nothing has been invalidated (i.e. marked as requiring
1467 a redraw). Use Refresh() first if you want to immediately redraw the
1468 window unconditionally.
1470 virtual void Update();
1473 Sets the background colour of the window.
1474 Please see InheritAttributes() for explanation of the difference between
1475 this method and SetOwnBackgroundColour().
1478 The colour to be used as the background colour, pass
1479 wxNullColour to reset to the default colour.
1481 @remarks The background colour is usually painted by the default
1482 wxEraseEvent event handler function under Windows and
1483 automatically under GTK.
1484 Note that setting the background colour does not cause an
1485 immediate refresh, so you may wish to call wxWindow::ClearBackground
1486 or wxWindow::Refresh after calling this function.
1487 Using this function will disable attempts to use themes for
1488 this window, if the system supports them. Use with care since
1489 usually the themes represent the appearance chosen by the user
1490 to be used for all applications on the system.
1492 @see GetBackgroundColour(), SetForegroundColour(),
1493 GetForegroundColour(), ClearBackground(),
1494 Refresh(), wxEraseEvent
1496 virtual bool SetBackgroundColour(const wxColour
& colour
);
1499 Sets the background style of the window. see GetBackgroundStyle() for
1500 the description of the possible style values.
1502 @see SetBackgroundColour(), GetForegroundColour(),
1505 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
1508 Sets the font for this window. This function should not be called for the
1509 parent window if you don't want its font to be inherited by its children,
1510 use SetOwnFont() instead in this case and see InheritAttributes() for more
1513 Please notice that the given font is not automatically used for
1514 wxPaintDC objects associated with this window, you need to
1515 call wxDC::SetFont too. However this font is used by
1516 any standard controls for drawing their text as well as by
1520 Font to associate with this window, pass
1521 wxNullFont to reset to the default font.
1523 @return @true if the want was really changed, @false if it was already set
1524 to this font and so nothing was done.
1526 @see GetFont(), InheritAttributes()
1528 virtual bool SetFont(const wxFont
& font
);
1531 Sets the foreground colour of the window.
1532 Please see InheritAttributes() for explanation of the difference between
1533 this method and SetOwnForegroundColour().
1536 The colour to be used as the foreground colour, pass
1537 wxNullColour to reset to the default colour.
1539 @remarks The interpretation of foreground colour is open to
1540 interpretation according to the window class; it may be
1541 the text colour or other colour, or it may not be used at all.
1543 @see GetForegroundColour(), SetBackgroundColour(),
1544 GetBackgroundColour(), ShouldInheritColours()
1546 virtual bool SetForegroundColour(const wxColour
& colour
);
1549 Sets the background colour of the window but prevents it from being inherited
1550 by the children of this window.
1552 @see SetBackgroundColour(), InheritAttributes()
1554 void SetOwnBackgroundColour(const wxColour
& colour
);
1557 Sets the font of the window but prevents it from being inherited by the
1558 children of this window.
1560 @see SetFont(), InheritAttributes()
1562 void SetOwnFont(const wxFont
& font
);
1565 Sets the foreground colour of the window but prevents it from being inherited
1566 by the children of this window.
1568 @see SetForegroundColour(), InheritAttributes()
1570 void SetOwnForegroundColour(const wxColour
& colour
);
1573 @deprecated use wxDC::SetPalette instead.
1575 void SetPalette(const wxPalette
& pal
);
1578 Return @true from here to allow the colours of this window to be changed by
1579 InheritAttributes(), returning @false forbids inheriting them from the parent window.
1581 The base class version returns @false, but this method is overridden in
1582 wxControl where it returns @true.
1584 virtual bool ShouldInheritColours() const;
1587 This function tells a window if it should use the system's "theme" code
1588 to draw the windows' background instead if its own background drawing
1589 code. This does not always have any effect since the underlying platform
1590 obviously needs to support the notion of themes in user defined windows.
1591 One such platform is GTK+ where windows can have (very colourful) backgrounds
1592 defined by a user's selected theme.
1594 Dialogs, notebook pages and the status bar have this flag set to @true
1595 by default so that the default look and feel is simulated best.
1597 virtual void SetThemeEnabled(bool enable
);
1600 Returns @true if the system supports transparent windows and calling
1601 SetTransparent() may succeed. If this function returns @false, transparent
1602 windows are definitely not supported by the current system.
1604 virtual bool CanSetTransparent();
1607 Set the transparency of the window. If the system supports transparent windows,
1608 returns @true, otherwise returns @false and the window remains fully opaque.
1609 See also CanSetTransparent().
1611 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1612 fully transparent window and 255 to the fully opaque one. The constants
1613 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1615 virtual bool SetTransparent(wxByte alpha
);
1621 @name Event-handling functions
1623 wxWindow allows you to build a (sort of) stack of event handlers which
1624 can be used to override the window's own event handling.
1629 Returns the event handler for this window.
1630 By default, the window is its own event handler.
1632 @see SetEventHandler(), PushEventHandler(),
1633 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1635 wxEvtHandler
* GetEventHandler() const;
1638 This function will generate the appropriate call to Navigate() if the key
1639 event is one normally used for keyboard navigation and return @true in this case.
1641 @return Returns @true if the key pressed was for navigation and was
1642 handled, @false otherwise.
1646 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
1651 GetEventHandler()->SafelyProcessEvent(event);
1654 bool HandleWindowEvent(wxEvent
& event
) const;
1657 Removes and returns the top-most event handler on the event handler stack.
1659 E.g. in the case of:
1660 @image html overview_eventhandling_winstack.png
1661 when calling @c W->PopEventHandler(), the event handler @c A will be
1662 removed and @c B will be the first handler of the stack.
1664 Note that it's an error to call this function when no event handlers
1665 were pushed on this window (i.e. when the window itself is its only
1668 @param deleteHandler
1669 If this is @true, the handler will be deleted after it is removed
1670 (and the returned value will be @NULL).
1672 @see @ref overview_eventhandling_processing
1674 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
1677 Pushes this event handler onto the event stack for the window.
1679 An event handler is an object that is capable of processing the events sent
1680 to a window. By default, the window is its own event handler, but an application
1681 may wish to substitute another, for example to allow central implementation
1682 of event-handling for a variety of different window classes.
1684 wxWindow::PushEventHandler allows an application to set up a @e stack
1685 of event handlers, where an event not handled by one event handler is
1686 handed to the next one in the chain.
1688 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
1691 W->PushEventHandler(A);
1692 W->PushEventHandler(B);
1694 you will end up with the following situation:
1695 @image html overview_eventhandling_winstack.png
1697 Note that you can use wxWindow::PopEventHandler to remove the event handler.
1700 Specifies the handler to be pushed.
1701 It must not be part of a wxEvtHandler chain; an assert will fail
1702 if it's not unlinked (see wxEvtHandler::IsUnlinked).
1704 @see @ref overview_eventhandling_processing
1706 void PushEventHandler(wxEvtHandler
* handler
);
1709 Find the given @a handler in the windows event handler stack and unlinks
1710 (but not delete) it. See wxEvtHandler::Unlink() for more info.
1713 The event handler to remove, must be non-@NULL and
1714 must be present in this windows event handlers stack.
1716 @return Returns @true if it was found and @false otherwise (this also
1717 results in an assert failure so this function should
1718 only be called when the handler is supposed to be there).
1720 @see PushEventHandler(), PopEventHandler()
1722 bool RemoveEventHandler(wxEvtHandler
* handler
);
1725 Sets the event handler for this window.
1727 Note that if you use this function you may want to use as the "next" handler
1728 of @a handler the window itself; in this way when @a handler doesn't process
1729 an event, the window itself will have a chance to do it.
1732 Specifies the handler to be set. Cannot be @NULL.
1734 @see @ref overview_eventhandling_processing
1736 void SetEventHandler(wxEvtHandler
* handler
);
1739 wxWindows cannot be used to form event handler chains; this function
1740 thus will assert when called.
1742 Note that instead you can use PushEventHandler() or SetEventHandler() to
1743 implement a stack of event handlers to override wxWindow's own
1744 event handling mechanism.
1746 virtual void SetNextHandler(wxEvtHandler
* handler
);
1749 wxWindows cannot be used to form event handler chains; this function
1750 thus will assert when called.
1752 Note that instead you can use PushEventHandler() or SetEventHandler() to
1753 implement a stack of event handlers to override wxWindow's own
1754 event handling mechanism.
1756 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
1763 @name Window styles functions
1768 Returns the extra style bits for the window.
1770 long GetExtraStyle() const;
1773 Gets the window style that was passed to the constructor or Create()
1774 method. GetWindowStyle() is another name for the same function.
1776 virtual long GetWindowStyleFlag() const;
1779 See GetWindowStyleFlag() for more info.
1781 long GetWindowStyle() const;
1784 Returns @true if the window has the given @a exFlag bit set in its
1787 @see SetExtraStyle()
1789 bool HasExtraStyle(int exFlag
) const;
1792 Returns @true if the window has the given @a flag bit set.
1794 bool HasFlag(int flag
) const;
1797 Sets the extra style bits for the window.
1798 The currently defined extra style bits are reported in the class
1801 virtual void SetExtraStyle(long exStyle
);
1804 Sets the style of the window. Please note that some styles cannot be changed
1805 after the window creation and that Refresh() might need to be be called
1806 after changing the others for the change to take place immediately.
1808 See @ref overview_windowstyles "Window styles" for more information about flags.
1810 @see GetWindowStyleFlag()
1812 virtual void SetWindowStyleFlag(long style
);
1815 See SetWindowStyleFlag() for more info.
1817 void SetWindowStyle(long style
);
1820 Turns the given @a flag on if it's currently turned off and vice versa.
1821 This function cannot be used if the value of the flag is 0 (which is often
1822 the case for default flags).
1824 Also, please notice that not all styles can be changed after the control
1827 @return Returns @true if the style was turned on by this function, @false
1828 if it was switched off.
1830 @see SetWindowStyleFlag(), HasFlag()
1832 bool ToggleWindowStyle(int flag
);
1838 @name Tab order functions
1843 Moves this window in the tab navigation order after the specified @e win.
1844 This means that when the user presses @c TAB key on that other window,
1845 the focus switches to this window.
1847 Default tab order is the same as creation order, this function and
1848 MoveBeforeInTabOrder() allow to change
1849 it after creating all the windows.
1852 A sibling of this window which should precede it in tab order,
1855 void MoveAfterInTabOrder(wxWindow
* win
);
1858 Same as MoveAfterInTabOrder() except that it inserts this window just
1859 before @a win instead of putting it right after it.
1861 void MoveBeforeInTabOrder(wxWindow
* win
);
1864 Performs a keyboard navigation action starting from this window.
1865 This method is equivalent to calling NavigateIn() method on the
1869 A combination of wxNavigationKeyEvent::IsForward and
1870 wxNavigationKeyEvent::WinChange.
1872 @return Returns @true if the focus was moved to another window or @false
1875 @remarks You may wish to call this from a text control custom keypress
1876 handler to do the default navigation behaviour for the
1877 tab key, since the standard default behaviour for a
1878 multiline text control with the wxTE_PROCESS_TAB style
1879 is to insert a tab and not navigate to the next
1880 control. See also wxNavigationKeyEvent and
1881 HandleAsNavigationKey.
1883 bool Navigate(int flags
= IsForward
);
1886 Performs a keyboard navigation action inside this window.
1887 See Navigate() for more information.
1889 bool NavigateIn(int flags
= IsForward
);
1896 @name Z order functions
1901 Lowers the window to the bottom of the window hierarchy (Z-order).
1904 This function only works for wxTopLevelWindow-derived classes.
1908 virtual void Lower();
1911 Raises the window to the top of the window hierarchy (Z-order).
1914 This function only works for wxTopLevelWindow-derived classes.
1918 virtual void Raise();
1924 @name Window status functions
1930 Equivalent to calling wxWindow::Show(@false).
1935 This function hides a window, like Hide(), but using a special visual
1938 The parameters of this function are the same as for ShowWithEffect(),
1939 please see their description there.
1943 virtual bool HideWithEffect(wxShowEffect effect
,
1944 unsigned int timeout
= 0);
1946 Returns @true if the window is enabled, i.e. if it accepts user input,
1949 Notice that this method can return @false even if this window itself hadn't
1950 been explicitly disabled when one of its parent windows is disabled.
1951 To get the intrinsic status of this window, use IsThisEnabled()
1955 bool IsEnabled() const;
1958 Returns @true if the given point or rectangle area has been exposed since the
1959 last repaint. Call this in an paint event handler to optimize redrawing by
1960 only redrawing those areas, which have been exposed.
1962 bool IsExposed(int x
, int y
) const;
1967 bool IsExposed(wxPoint
& pt
) const;
1972 bool IsExposed(int x
, int y
, int w
, int h
) const;
1977 bool IsExposed(wxRect
& rect
) const;
1979 Returns @true if the window is shown, @false if it has been hidden.
1981 @see IsShownOnScreen()
1983 virtual bool IsShown() const;
1986 Returns @true if the window is physically visible on the screen, i.e. it
1987 is shown and all its parents up to the toplevel window are shown as well.
1991 virtual bool IsShownOnScreen() const;
1994 Disables the window. Same as @ref Enable() Enable(@false).
1996 @return Returns @true if the window has been disabled, @false if it had
1997 been already disabled before the call to this function.
2002 Enable or disable the window for user input. Note that when a parent window is
2003 disabled, all of its children are disabled as well and they are reenabled again
2007 If @true, enables the window for input. If @false, disables the window.
2009 @return Returns @true if the window has been enabled or disabled, @false
2010 if nothing was done, i.e. if the window had already
2011 been in the specified state.
2013 @see IsEnabled(), Disable(), wxRadioBox::Enable
2015 virtual bool Enable(bool enable
= true);
2018 Shows or hides the window. You may need to call Raise()
2019 for a top level window if you want to bring it to top, although this is not
2020 needed if Show() is called immediately after the frame creation.
2023 If @true displays the window. Otherwise, hides it.
2025 @return @true if the window has been shown or hidden or @false if nothing
2026 was done because it already was in the requested state.
2028 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2030 virtual bool Show(bool show
= true);
2033 This function shows a window, like Show(), but using a special visual
2040 The @a timeout parameter specifies the time of the animation, in
2041 milliseconds. If the default value of 0 is used, the default
2042 animation time for the current platform is used.
2044 @note Currently this function is only implemented in wxMSW and does the
2045 same thing as Show() in the other ports.
2049 @see HideWithEffect()
2051 virtual bool ShowWithEffect(wxShowEffect effect
,
2052 unsigned int timeout
= 0);
2058 @name Context-sensitive help functions
2063 Gets the help text to be used as context-sensitive help for this window.
2064 Note that the text is actually stored by the current wxHelpProvider
2065 implementation, and not in the window object itself.
2067 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2069 wxString
GetHelpText() const;
2072 Sets the help text to be used as context-sensitive help for this window.
2073 Note that the text is actually stored by the current wxHelpProvider
2074 implementation, and not in the window object itself.
2076 @see GetHelpText(), wxHelpProvider::AddHelp()
2078 void SetHelpText(const wxString
& helpText
);
2081 Gets the help text to be used as context-sensitive help for this window.
2082 This method should be overridden if the help message depends on the position
2083 inside the window, otherwise GetHelpText() can be used.
2086 Coordinates of the mouse at the moment of help event emission.
2088 Help event origin, see also wxHelpEvent::GetOrigin.
2090 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
2091 wxHelpEvent
::Origin origin
) const;
2094 Get the associated tooltip or @NULL if none.
2096 wxToolTip
* GetToolTip() const;
2099 Attach a tooltip to the window.
2101 wxToolTip pointer can be @NULL in the overload taking the pointer,
2102 meaning to unset any existing tooltips, however UnsetToolTip() provides
2103 a more readable alternative to this operation.
2105 Notice that these methods are always available, even if wxWidgets was
2106 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2109 @see GetToolTip(), wxToolTip
2111 void SetToolTip(const wxString
& tip
);
2116 void SetToolTip(wxToolTip
* tip
);
2119 Unset any existing tooltip.
2125 void UnsetToolTip();
2131 @name Popup/context menu functions
2136 This function shows a popup menu at the given position in this window and
2137 returns the selected id.
2139 It can be more convenient than the general purpose PopupMenu() function
2140 for simple menus proposing a choice in a list of strings to the user.
2142 Notice that to avoid unexpected conflicts between the (usually
2143 consecutive range of) ids used by the menu passed to this function and
2144 the existing EVT_UPDATE_UI() handlers, this function temporarily
2145 disables UI updates for the window, so you need to manually disable
2146 (or toggle or ...) any items which should be disabled in the menu
2149 The parameter @a menu is the menu to show.
2150 The parameter @a pos (or the parameters @a x and @a y) is the
2151 position at which to show the menu in client coordinates.
2154 The selected menu item id or @c wxID_NONE if none selected or an
2159 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, const wxPoint
& pos
);
2164 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
2167 Pops up the given menu at the specified coordinates, relative to this
2168 window, and returns control when the user has dismissed the menu.
2170 If a menu item is selected, the corresponding menu event is generated and will be
2171 processed as usually. If the coordinates are not specified, current mouse
2172 cursor position is used.
2174 @a menu is the menu to pop up.
2176 The position where the menu will appear can be specified either as a
2177 wxPoint @a pos or by two integers (@a x and @a y).
2179 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2180 ensure that the menu items are in the correct state.
2181 The menu does not get deleted by the window.
2182 It is recommended to not explicitly specify coordinates when
2183 calling PopupMenu in response to mouse click, because some of
2184 the ports (namely, wxGTK) can do a better job of positioning
2185 the menu in that case.
2189 bool PopupMenu(wxMenu
* menu
,
2190 const wxPoint
& pos
= wxDefaultPosition
);
2195 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
2206 Returns a pointer to the current validator for the window, or @NULL if
2209 virtual wxValidator
* GetValidator();
2212 Deletes the current validator (if any) and sets the window validator, having
2213 called wxValidator::Clone to create a new validator of this type.
2215 virtual void SetValidator(const wxValidator
& validator
);
2218 Transfers values from child controls to data areas specified by their
2219 validators. Returns @false if a transfer failed.
2221 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2222 the method will also call TransferDataFromWindow() of all child windows.
2224 @see TransferDataToWindow(), wxValidator, Validate()
2226 virtual bool TransferDataFromWindow();
2229 Transfers values to child controls from data areas specified by their
2232 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2233 the method will also call TransferDataToWindow() of all child windows.
2235 @return Returns @false if a transfer failed.
2237 @see TransferDataFromWindow(), wxValidator, Validate()
2239 virtual bool TransferDataToWindow();
2242 Validates the current values of the child controls using their validators.
2243 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2244 the method will also call Validate() of all child windows.
2246 @return Returns @false if any of the validations failed.
2248 @see TransferDataFromWindow(), TransferDataToWindow(),
2251 virtual bool Validate();
2257 @name wxWindow properties functions
2262 Returns the identifier of the window.
2264 @remarks Each window has an integer identifier. If the application
2265 has not provided one (or the default wxID_ANY) an unique
2266 identifier with a negative value will be generated.
2268 @see SetId(), @ref overview_windowids
2270 wxWindowID
GetId() const;
2273 Generic way of getting a label from any window, for
2274 identification purposes.
2276 @remarks The interpretation of this function differs from class to class.
2277 For frames and dialogs, the value returned is the
2278 title. For buttons or static text controls, it is the
2279 button text. This function can be useful for
2280 meta-programs (such as testing tools or special-needs
2281 access programs) which need to identify windows by name.
2283 virtual wxString
GetLabel() const;
2286 Returns the window's name.
2288 @remarks This name is not guaranteed to be unique; it is up to the
2289 programmer to supply an appropriate name in the window
2290 constructor or via SetName().
2294 virtual wxString
GetName() const;
2297 Returns the value previously passed to SetWindowVariant().
2299 wxWindowVariant
GetWindowVariant() const;
2302 Sets the identifier of the window.
2304 @remarks Each window has an integer identifier. If the application has
2305 not provided one, an identifier will be generated.
2306 Normally, the identifier should be provided on creation
2307 and should not be modified subsequently.
2309 @see GetId(), @ref overview_windowids
2311 void SetId(wxWindowID winid
);
2314 Sets the window's label.
2321 virtual void SetLabel(const wxString
& label
);
2324 Sets the window's name.
2327 A name to set for the window.
2331 virtual void SetName(const wxString
& name
);
2334 This function can be called under all platforms but only does anything under
2335 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2336 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2338 By default the controls use the normal size, of course, but this function can
2339 be used to change this.
2341 void SetWindowVariant(wxWindowVariant variant
);
2345 Gets the accelerator table for this window. See wxAcceleratorTable.
2347 wxAcceleratorTable
* GetAcceleratorTable();
2350 Returns the accessible object for this window, if any.
2351 See also wxAccessible.
2353 wxAccessible
* GetAccessible();
2356 Sets the accelerator table for this window. See wxAcceleratorTable.
2358 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
2361 Sets the accessible for this window. Any existing accessible for this window
2362 will be deleted first, if not identical to @e accessible.
2363 See also wxAccessible.
2365 void SetAccessible(wxAccessible
* accessible
);
2371 @name Window deletion functions
2376 This function simply generates a wxCloseEvent whose handler usually tries
2377 to close the window. It doesn't close the window itself, however.
2380 @false if the window's close handler should be able to veto the destruction
2381 of this window, @true if it cannot.
2383 @remarks Close calls the close handler for the window, providing an
2384 opportunity for the window to choose whether to destroy
2385 the window. Usually it is only used with the top level
2386 windows (wxFrame and wxDialog classes) as the others
2387 are not supposed to have any special OnClose() logic.
2388 The close handler should check whether the window is being deleted
2389 forcibly, using wxCloseEvent::CanVeto, in which case it should
2390 destroy the window using wxWindow::Destroy.
2391 Note that calling Close does not guarantee that the window will
2392 be destroyed; but it provides a way to simulate a manual close
2393 of a window, which may or may not be implemented by destroying
2394 the window. The default implementation of wxDialog::OnCloseWindow
2395 does not necessarily delete the dialog, since it will simply
2396 simulate an wxID_CANCEL event which is handled by the appropriate
2397 button event handler and may do anything at all.
2398 To guarantee that the window will be destroyed, call
2399 wxWindow::Destroy instead
2401 @see @ref overview_windowdeletion "Window Deletion Overview",
2402 Destroy(), wxCloseEvent
2404 bool Close(bool force
= false);
2407 Destroys the window safely. Use this function instead of the delete operator,
2408 since different window classes can be destroyed differently. Frames and dialogs
2409 are not destroyed immediately when this function is called -- they are added
2410 to a list of windows to be deleted on idle time, when all the window's events
2411 have been processed. This prevents problems with events being sent to
2412 non-existent windows.
2414 @return @true if the window has either been successfully deleted, or it
2415 has been added to the list of windows pending real deletion.
2417 virtual bool Destroy();
2420 Returns true if this window is in process of being destroyed.
2422 The top level windows are not deleted immediately but are rather
2423 scheduled for later destruction to give them time to process any
2424 pending messages, see Destroy() description.
2426 This function returns @true if this window, or one of its parent
2427 windows, is scheduled for destruction and can be useful to avoid
2428 manipulating it as it's usually useless to do something with a window
2429 which is on the point of disappearing anyhow.
2431 bool IsBeingDeleted() const;
2438 @name Drag and drop functions
2443 Returns the associated drop target, which may be @NULL.
2445 @see SetDropTarget(), @ref overview_dnd
2447 virtual wxDropTarget
* GetDropTarget() const;
2450 Associates a drop target with this window.
2451 If the window already has a drop target, it is deleted.
2453 @see GetDropTarget(), @ref overview_dnd
2455 virtual void SetDropTarget(wxDropTarget
* target
);
2458 Enables or disables eligibility for drop file events (OnDropFiles).
2461 If @true, the window is eligible for drop file events.
2462 If @false, the window will not accept drop file events.
2464 @remarks Windows only until version 2.8.9, available on all platforms
2465 since 2.8.10. Cannot be used together with SetDropTarget() on
2466 non-Windows platforms.
2468 @see SetDropTarget()
2470 virtual void DragAcceptFiles(bool accept
);
2476 @name Constraints, sizers and window layouting functions
2481 Return the sizer that this window is a member of, if any, otherwise @NULL.
2483 wxSizer
* GetContainingSizer() const;
2486 Return the sizer associated with the window by a previous call to
2487 SetSizer() or @NULL.
2489 wxSizer
* GetSizer() const;
2492 Sets the window to have the given layout sizer.
2493 The window will then own the object, and will take care of its deletion.
2494 If an existing layout constraints object is already owned by the
2495 window, it will be deleted if the deleteOld parameter is @true.
2497 Note that this function will also call SetAutoLayout() implicitly with @true
2498 parameter if the @a sizer is non-@NULL and @false otherwise.
2501 The sizer to set. Pass @NULL to disassociate and conditionally delete
2502 the window's sizer. See below.
2504 If @true (the default), this will delete any pre-existing sizer.
2505 Pass @false if you wish to handle deleting the old sizer yourself.
2507 @remarks SetSizer enables and disables Layout automatically.
2509 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2512 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2513 window size to the size needed to accommodate all sizer elements and sets the
2514 size hints which, if this window is a top level one, prevent the user from
2515 resizing it to be less than this minimial size.
2517 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2520 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2522 wxLayoutConstraints
* GetConstraints() const;
2525 Sets the window to have the given layout constraints. The window
2526 will then own the object, and will take care of its deletion.
2527 If an existing layout constraints object is already owned by the
2528 window, it will be deleted.
2531 The constraints to set. Pass @NULL to disassociate and delete the window's
2534 @remarks You must call SetAutoLayout() to tell a window to use
2535 the constraints automatically in OnSize; otherwise, you
2536 must override OnSize and call Layout() explicitly. When
2537 setting both a wxLayoutConstraints and a wxSizer, only
2538 the sizer will have effect.
2540 void SetConstraints(wxLayoutConstraints
* constraints
);
2544 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2547 This function does not get called automatically when the window is resized
2548 because lots of windows deriving from wxWindow does not need this functionality.
2549 If you want to have Layout() called automatically, you should derive
2550 from wxPanel (see wxPanel::Layout).
2552 @see @ref overview_windowsizing
2554 virtual bool Layout();
2557 Determines whether the Layout() function will be called automatically
2558 when the window is resized. Please note that this only happens for the
2559 windows usually used to contain children, namely wxPanel and wxTopLevelWindow
2560 (and the classes deriving from them).
2562 This method is called implicitly by SetSizer() but if you use SetConstraints()
2563 you should call it manually or otherwise the window layout won't be correctly
2564 updated when its size changes.
2567 Set this to @true if you wish the Layout() function to be
2568 called automatically when the window is resized
2569 (really happens only if you derive from wxPanel or wxTopLevelWindow).
2571 @see SetConstraints()
2573 void SetAutoLayout(bool autoLayout
);
2580 @name Mouse functions
2585 Directs all mouse input to this window.
2586 Call ReleaseMouse() to release the capture.
2588 Note that wxWidgets maintains the stack of windows having captured the mouse
2589 and when the mouse is released the capture returns to the window which had had
2590 captured it previously and it is only really released if there were no previous
2591 window. In particular, this means that you must release the mouse as many times
2592 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
2594 Any application which captures the mouse in the beginning of some operation
2595 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
2596 the event. The event handler must not recapture mouse.
2598 @see ReleaseMouse(), wxMouseCaptureLostEvent
2600 void CaptureMouse();
2603 Returns the caret() associated with the window.
2605 wxCaret
* GetCaret() const;
2608 Return the cursor associated with this window.
2612 const wxCursor
& GetCursor() const;
2615 Returns @true if this window has the current mouse capture.
2617 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
2618 wxMouseCaptureChangedEvent
2620 virtual bool HasCapture() const;
2623 Releases mouse input captured with CaptureMouse().
2625 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
2626 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2628 void ReleaseMouse();
2631 Sets the caret() associated with the window.
2633 void SetCaret(wxCaret
* caret
);
2636 Sets the window's cursor. Notice that the window cursor also sets it for the
2637 children of the window implicitly.
2639 The @a cursor may be @c wxNullCursor in which case the window cursor will
2640 be reset back to default.
2643 Specifies the cursor that the window should normally display.
2645 @see ::wxSetCursor, wxCursor
2647 virtual bool SetCursor(const wxCursor
& cursor
);
2650 Moves the pointer to the given position on the window.
2652 @note This function is not supported under Mac because Apple Human
2653 Interface Guidelines forbid moving the mouse cursor programmatically.
2656 The new x position for the cursor.
2658 The new y position for the cursor.
2660 virtual void WarpPointer(int x
, int y
);
2668 @name Miscellaneous functions
2673 Does the window-specific updating after processing the update event.
2674 This function is called by UpdateWindowUI() in order to check return
2675 values in the wxUpdateUIEvent and act appropriately.
2676 For example, to allow frame and dialog title updating, wxWidgets
2677 implements this function as follows:
2680 // do the window-specific processing after processing the update event
2681 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
2683 if ( event.GetSetEnabled() )
2684 Enable(event.GetEnabled());
2686 if ( event.GetSetText() )
2688 if ( event.GetText() != GetTitle() )
2689 SetTitle(event.GetText());
2694 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
2697 Returns the platform-specific handle of the physical window.
2698 Cast it to an appropriate handle, such as @b HWND for Windows,
2699 @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
2701 virtual WXWidget
GetHandle() const;
2704 This method should be overridden to return @true if this window has
2705 multiple pages. All standard class with multiple pages such as
2706 wxNotebook, wxListbook and wxTreebook already override it to return @true
2707 and user-defined classes with similar behaviour should do it as well to
2708 allow the library to handle such windows appropriately.
2710 virtual bool HasMultiplePages() const;
2713 This function is (or should be, in case of custom controls) called during
2714 window creation to intelligently set up the window visual attributes, that is
2715 the font and the foreground and background colours.
2717 By "intelligently" the following is meant: by default, all windows use their
2718 own @ref GetClassDefaultAttributes() default attributes.
2719 However if some of the parents attributes are explicitly (that is, using
2720 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
2721 attribute hadn't been explicitly set for this window itself, then this
2722 window takes the same value as used by the parent.
2723 In addition, if the window overrides ShouldInheritColours() to return @false,
2724 the colours will not be changed no matter what and only the font might.
2726 This rather complicated logic is necessary in order to accommodate the
2727 different usage scenarios. The most common one is when all default attributes
2728 are used and in this case, nothing should be inherited as in modern GUIs
2729 different controls use different fonts (and colours) than their siblings so
2730 they can't inherit the same value from the parent. However it was also deemed
2731 desirable to allow to simply change the attributes of all children at once by
2732 just changing the font or colour of their common parent, hence in this case we
2733 do inherit the parents attributes.
2735 virtual void InheritAttributes();
2738 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
2739 to the dialog via validators.
2741 virtual void InitDialog();
2744 Returns @true if the window contents is double-buffered by the system, i.e. if
2745 any drawing done on the window is really done on a temporary backing surface
2746 and transferred to the screen all at once later.
2750 virtual bool IsDoubleBuffered() const;
2753 Returns @true if the window is retained, @false otherwise.
2755 @remarks Retained windows are only available on X platforms.
2757 virtual bool IsRetained() const;
2760 Returns @true if this window is intrinsically enabled, @false otherwise,
2761 i.e. if @ref Enable() Enable(@false) had been called. This method is
2762 mostly used for wxWidgets itself, user code should normally use
2763 IsEnabled() instead.
2765 bool IsThisEnabled() const;
2768 Returns @true if the given window is a top-level one. Currently all frames and
2769 dialogs are considered to be top-level windows (even if they have a parent
2772 virtual bool IsTopLevel() const;
2775 Disables all other windows in the application so that
2776 the user can only interact with this window.
2779 If @true, this call disables all other windows in the application so that
2780 the user can only interact with this window. If @false, the effect is
2783 virtual void MakeModal(bool modal
= true);
2786 This virtual function is normally only used internally, but
2787 sometimes an application may need it to implement functionality
2788 that should not be disabled by an application defining an OnIdle
2789 handler in a derived class.
2791 This function may be used to do delayed painting, for example,
2792 and most implementations call UpdateWindowUI()
2793 in order to send update events to the window in idle time.
2795 virtual void OnInternalIdle();
2798 Registers a system wide hotkey. Every time the user presses the hotkey
2799 registered here, this window will receive a hotkey event.
2801 It will receive the event even if the application is in the background
2802 and does not have the input focus because the user is working with some
2806 Numeric identifier of the hotkey. For applications this must be between 0
2807 and 0xBFFF. If this function is called from a shared DLL, it must be a
2808 system wide unique identifier between 0xC000 and 0xFFFF.
2809 This is a MSW specific detail.
2811 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
2812 or wxMOD_WIN specifying the modifier keys that have to be pressed along
2814 @param virtualKeyCode
2815 The virtual key code of the hotkey.
2817 @return @true if the hotkey was registered successfully. @false if some
2818 other application already registered a hotkey with this
2819 modifier/virtualKeyCode combination.
2821 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
2822 event. This function is currently only implemented
2823 under Windows. It is used in the Windows CE port for
2824 detecting hardware button presses.
2826 @see UnregisterHotKey()
2828 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
2829 int virtualKeyCode
);
2832 Unregisters a system wide hotkey.
2835 Numeric identifier of the hotkey. Must be the same id that was passed to
2838 @return @true if the hotkey was unregistered successfully, @false if the
2841 @remarks This function is currently only implemented under MSW.
2843 @see RegisterHotKey()
2845 virtual bool UnregisterHotKey(int hotkeyId
);
2848 This function sends one or more wxUpdateUIEvent to the window.
2849 The particular implementation depends on the window; for example a
2850 wxToolBar will send an update UI event for each toolbar button,
2851 and a wxFrame will send an update UI event for each menubar menu item.
2853 You can call this function from your application to ensure that your
2854 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
2855 are concerned). This may be necessary if you have called
2856 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
2857 the overhead that wxWidgets incurs by sending update UI events in idle time.
2858 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
2860 If you are calling this function from an OnInternalIdle or OnIdle
2861 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
2862 this tells the window to only update the UI elements that need
2863 to be updated in idle time. Some windows update their elements
2864 only when necessary, for example when a menu is about to be shown.
2865 The following is an example of how to call UpdateWindowUI from
2869 void MyWindow::OnInternalIdle()
2871 if (wxUpdateUIEvent::CanUpdate(this))
2872 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
2876 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
2878 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
2883 // NOTE: static functions must have their own group or Doxygen will screw
2884 // up the ordering of the member groups
2887 @name Miscellaneous static functions
2892 Returns the default font and colours which are used by the control.
2894 This is useful if you want to use the same font or colour in your own control
2895 as in a standard control -- which is a much better idea than hard coding specific
2896 colours or fonts which might look completely out of place on the users
2897 system, especially if it uses themes.
2899 The @a variant parameter is only relevant under Mac currently and is
2900 ignore under other platforms. Under Mac, it will change the size of the
2901 returned font. See SetWindowVariant() for more about this.
2903 This static method is "overridden" in many derived classes and so calling,
2904 for example, wxButton::GetClassDefaultAttributes() will typically
2905 return the values appropriate for a button which will be normally different
2906 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
2908 The @c wxVisualAttributes structure has at least the fields
2909 @c font, @c colFg and @c colBg. All of them may be invalid
2910 if it was not possible to determine the default control appearance or,
2911 especially for the background colour, if the field doesn't make sense as is
2912 the case for @c colBg for the controls with themed background.
2914 @see InheritAttributes()
2916 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
2919 Finds the window or control which currently has the keyboard focus.
2921 @remarks Note that this is a static function, so it can be called without
2922 needing a wxWindow pointer.
2924 @see SetFocus(), HasFocus()
2926 static wxWindow
* FindFocus();
2929 Find the first window with the given @e id.
2931 If @a parent is @NULL, the search will start from all top-level frames
2932 and dialog boxes; if non-@NULL, the search will be limited to the given
2934 The search is recursive in both cases.
2938 static wxWindow
* FindWindowById(long id
, const wxWindow
* parent
= 0);
2941 Find a window by its label.
2943 Depending on the type of window, the label may be a window title
2944 or panel item label. If @a parent is @NULL, the search will start from all
2945 top-level frames and dialog boxes; if non-@NULL, the search will be
2946 limited to the given window hierarchy.
2947 The search is recursive in both cases.
2951 static wxWindow
* FindWindowByLabel(const wxString
& label
,
2952 const wxWindow
* parent
= 0);
2955 Find a window by its name (as given in a window constructor or Create()
2958 If @a parent is @NULL, the search will start from all top-level frames
2959 and dialog boxes; if non-@NULL, the search will be limited to the given
2962 The search is recursive in both cases. If no window with such name is found,
2963 FindWindowByLabel() is called.
2967 static wxWindow
* FindWindowByName(const wxString
& name
,
2968 const wxWindow
* parent
= 0);
2971 Returns the currently captured window.
2973 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
2974 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2976 static wxWindow
* GetCapture();
2979 Create a new ID or range of IDs that are not currently in use.
2980 The IDs will be reserved until assigned to a wxWindow ID
2981 or unreserved with UnreserveControlId().
2983 See @ref overview_windowids for more information.
2986 The number of sequential IDs to reserve.
2988 @return Returns the ID or the first ID of the range, or wxID_NONE if the
2989 specified number of identifiers couldn't be allocated.
2991 @see UnreserveControlId(), wxIdManager,
2992 @ref overview_windowids
2994 static wxWindowID
NewControlId(int count
= 1);
2997 Unreserve an ID or range of IDs that was reserved by NewControlId().
2998 See @ref overview_windowids for more information.
3001 The starting ID of the range of IDs to unreserve.
3003 The number of sequential IDs to unreserve.
3005 @see NewControlId(), wxIdManager, @ref overview_windowids
3007 static void UnreserveControlId(wxWindowID id
, int count
= 1);
3016 Gets the size which best suits the window: for a control, it would be
3017 the minimal size which doesn't truncate the control, for a panel - the
3018 same size as it would have after a call to Fit().
3020 The default implementation of this function is designed for use in container
3021 windows, such as wxPanel, and works something like this:
3022 -# If the window has a sizer then it is used to calculate the best size.
3023 -# Otherwise if the window has layout constraints then those are used to
3024 calculate the best size.
3025 -# Otherwise if the window has children then the best size is set to be large
3026 enough to show all the children.
3027 -# Otherwise if there are no children then the window's minimal size will be
3028 used as its best size.
3029 -# Otherwise if there is no minimal size set, then the current size is used
3032 @see @ref overview_windowsizing
3034 virtual wxSize
DoGetBestSize() const;
3038 Sets the initial window size if none is given (i.e. at least one of the
3039 components of the size passed to ctor/Create() is wxDefaultCoord).
3040 @deprecated @todo provide deprecation description
3042 virtual void SetInitialBestSize(const wxSize
& size
);
3045 Generate wxWindowDestroyEvent for this window.
3047 This is called by the window itself when it is being destroyed and
3048 usually there is no need to call it but see wxWindowDestroyEvent for
3049 explanations of when you might want to do it.
3051 void SendDestroyEvent();
3055 This function is public in wxEvtHandler but is protected in wxWindow because
3056 for wxWindows you should always use this function on the pointer returned
3057 by GetEventHandler() and not on the wxWindow object itself.
3059 Note that it's still possible to call these functions directly on the
3060 wxWindow object (e.g. downcasting it to wxEvtHandler) but doing that
3061 will create subtle bugs when windows with event handlers pushed on them
3064 virtual bool ProcessEvent(wxEvent
& event
);
3065 bool SafelyProcessEvent(wxEvent
& event
);
3066 virtual void QueueEvent(wxEvent
*event
);
3067 virtual void AddPendingEvent(const wxEvent
& event
);
3068 void ProcessPendingEvents();
3069 bool ProcessThreadEvent(const wxEvent
& event
);
3075 // ============================================================================
3076 // Global functions/macros
3077 // ============================================================================
3079 /** @addtogroup group_funcmacro_misc */
3083 Find the deepest window at the mouse pointer position, returning the window
3084 and current pointer position in screen coordinates.
3086 @header{wx/window.h}
3088 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
3091 Gets the currently active window (implemented for MSW and GTK only
3092 currently, always returns @NULL in the other ports).
3094 @header{wx/window.h}
3096 wxWindow
* wxGetActiveWindow();
3099 Returns the first top level parent of the given window, or in other words,
3100 the frame or dialog containing it, or @NULL.
3102 @header{wx/window.h}
3104 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);