1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 Background styles. See wxWindow::SetBackgroundStyle().
13 enum wxBackgroundStyle
15 /// Use the default background, as determined by
16 /// the system or the current theme.
19 /// Use a solid colour for the background, this style is set automatically if you call
20 /// SetBackgroundColour() so you only need to set it explicitly if you had
21 /// changed the background style to something else before.
24 /// Don't draw the background at all, it's supposed that it is drawn by
25 /// the user-defined erase background event handler.
26 /// This style should be used to avoid flicker when the background is entirely
30 /// The background is (partially) transparent,this style is automatically set if you call
31 /// SetTransparent() which is used to set the transparency level.
32 wxBG_STYLE_TRANSPARENT
37 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
41 /// Roll window to the left
42 wxSHOW_EFFECT_ROLL_TO_LEFT
,
44 /// Roll window to the right
45 wxSHOW_EFFECT_ROLL_TO_RIGHT
,
47 /// Roll window to the top
48 wxSHOW_EFFECT_ROLL_TO_TOP
,
50 /// Roll window to the bottom
51 wxSHOW_EFFECT_ROLL_TO_BOTTOM
,
53 /// Slide window to the left
54 wxSHOW_EFFECT_SLIDE_TO_LEFT
,
56 /// Slide window to the right
57 wxSHOW_EFFECT_SLIDE_TO_RIGHT
,
59 /// Slide window to the top
60 wxSHOW_EFFECT_SLIDE_TO_TOP
,
62 /// Slide window to the bottom
63 wxSHOW_EFFECT_SLIDE_TO_BOTTOM
,
65 /// Fade in or out effect
68 /// Expanding or collapsing effect
73 Different window variants, on platforms like eg mac uses different
78 wxWINDOW_VARIANT_NORMAL
, //!< Normal size
79 wxWINDOW_VARIANT_SMALL
, //!< Smaller size (about 25 % smaller than normal)
80 wxWINDOW_VARIANT_MINI
, //!< Mini size (about 33 % smaller than normal)
81 wxWINDOW_VARIANT_LARGE
, //!< Large size (about 25 % larger than normal)
87 Flags which can be used in wxWindow::UpdateWindowUI().
93 wxUPDATE_UI_FROMIDLE
/**< Invoked from On(Internal)Idle */
100 wxWindow is the base class for all windows and represents any visible object
101 om screen. All controls, top level windows and so on are windows. Sizers and
102 device contexts are not, however, as they don't appear on screen themselves.
104 Please note that all children of the window will be deleted automatically by
105 the destructor before the window itself is deleted which means that you don't
106 have to worry about deleting them manually. Please see the @ref
107 overview_windowdeletion "window deletion overview" for more information.
109 Also note that in this, and many others, wxWidgets classes some
110 @c GetXXX() methods may be overloaded (as, for example,
111 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
112 are non-virtual because having multiple virtual functions with the same name
113 results in a virtual function name hiding at the derived class level (in
114 English, this means that the derived class has to override all overloaded
115 variants if it overrides any of them). To allow overriding them in the derived
116 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
117 and all @c GetXXX() ones are forwarded to it, so overriding the former
118 changes the behaviour of the latter.
121 @style{wxBORDER_DEFAULT}
122 The window class will decide the kind of border to show, if any.
123 @style{wxBORDER_SIMPLE}
124 Displays a thin border around the window. wxSIMPLE_BORDER is the
125 old name for this style.
126 @style{wxBORDER_SUNKEN}
127 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
129 @style{wxBORDER_RAISED}
130 Displays a raised border. wxRAISED_BORDER is the old name for this
132 @style{wxBORDER_STATIC}
133 Displays a border suitable for a static control. wxSTATIC_BORDER
134 is the old name for this style. Windows only.
135 @style{wxBORDER_THEME}
136 Displays a native border suitable for a control, on the current
137 platform. On Windows XP or Vista, this will be a themed border; on
138 most other platforms a sunken border will be used. For more
139 information for themed borders on Windows, please see Themed
141 @style{wxBORDER_NONE}
142 Displays no border, overriding the default border style for the
143 window. wxNO_BORDER is the old name for this style.
144 @style{wxBORDER_DOUBLE}
145 This style is obsolete and should not be used.
146 @style{wxTRANSPARENT_WINDOW}
147 The window is transparent, that is, it will not receive paint
148 events. Windows only.
149 @style{wxTAB_TRAVERSAL}
150 Use this to enable tab traversal for non-dialog windows.
151 @style{wxWANTS_CHARS}
152 Use this to indicate that the window wants to get all char/key
153 events for all keys - even for keys like TAB or ENTER which are
154 usually used for dialog navigation and which wouldn't be generated
155 without this style. If you need to use this style in order to get
156 the arrows or etc., but would still like to have normal keyboard
157 navigation take place, you should call Navigate in response to the
158 key events for Tab and Shift-Tab.
159 @style{wxNO_FULL_REPAINT_ON_RESIZE}
160 On Windows, this style used to disable repainting the window
161 completely when its size is changed. Since this behaviour is now
162 the default, the style is now obsolete and no longer has an effect.
164 Use this style to enable a vertical scrollbar. Notice that this
165 style cannot be used with native controls which don't support
166 scrollbars nor with top-level windows in most ports.
168 Use this style to enable a horizontal scrollbar. The same
169 limitations as for wxVSCROLL apply to this style.
170 @style{wxALWAYS_SHOW_SB}
171 If a window has scrollbars, disable them instead of hiding them
172 when they are not needed (i.e. when the size of the window is big
173 enough to not require the scrollbars to navigate it). This style is
174 currently implemented for wxMSW, wxGTK and wxUniversal and does
175 nothing on the other platforms.
176 @style{wxCLIP_CHILDREN}
177 Use this style to eliminate flicker caused by the background being
178 repainted, then children being painted over them. Windows only.
179 @style{wxFULL_REPAINT_ON_RESIZE}
180 Use this style to force a complete redraw of the window whenever it
181 is resized instead of redrawing just the part of the window
182 affected by resizing. Note that this was the behaviour by default
183 before 2.5.1 release and that if you experience redraw problems
184 with code which previously used to work you may want to try this.
185 Currently this style applies on GTK+ 2 and Windows only, and full
186 repainting is always done on other platforms.
189 @beginExtraStyleTable
190 @style{wxWS_EX_VALIDATE_RECURSIVELY}
191 By default, Validate/TransferDataTo/FromWindow() only work on
192 direct children of the window (compatible behaviour). Set this flag
193 to make them recursively descend into all subwindows.
194 @style{wxWS_EX_BLOCK_EVENTS}
195 wxCommandEvents and the objects of the derived classes are
196 forwarded to the parent window and so on recursively by default.
197 Using this flag for the given window allows to block this
198 propagation at this window, i.e. prevent the events from being
199 propagated further upwards. Dialogs have this flag on by default
200 for the reasons explained in the @ref overview_eventhandling "Event Handling Overview".
201 @style{wxWS_EX_TRANSIENT}
202 Don't use this window as an implicit parent for the other windows:
203 this must be used with transient windows as otherwise there is the
204 risk of creating a dialog/frame with this window as a parent which
205 would lead to a crash if the parent is destroyed before the child.
206 @style{wxWS_EX_CONTEXTHELP}
207 Under Windows, puts a query button on the caption. When pressed,
208 Windows will go into a context-sensitive help mode and wxWidgets
209 will send a wxEVT_HELP event if the user clicked on an application window.
210 This style cannot be used (because of the underlying native behaviour)
211 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
212 are automatically turned off if this one is used.
213 @style{wxWS_EX_PROCESS_IDLE}
214 This window should always process idle events, even if the mode set
215 by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
216 @style{wxWS_EX_PROCESS_UI_UPDATES}
217 This window should always process UI update events, even if the
218 mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED.
224 @see @ref overview_eventhandling "Event handling overview",
225 @ref overview_windowsizing "Window sizing overview"
227 class wxWindow
: public wxEvtHandler
236 Constructs a window, which can be a child of a frame, dialog or any other
240 Pointer to a parent window.
242 Window identifier. If wxID_ANY, will automatically create an identifier.
244 Window position. wxDefaultPosition indicates that wxWidgets
245 should generate a default position for the window.
246 If using the wxWindow class directly, supply an actual position.
248 Window size. wxDefaultSize indicates that wxWidgets should generate
249 a default size for the window. If no suitable size can be found, the
250 window will be sized to 20x20 pixels so that the window is visible but
251 obviously not correctly sized.
253 Window style. For generic window styles, please see wxWindow.
257 wxWindow(wxWindow
* parent
, wxWindowID id
,
258 const wxPoint
& pos
= wxDefaultPosition
,
259 const wxSize
& size
= wxDefaultSize
,
261 const wxString
& name
= wxPanelNameStr
);
266 Deletes all sub-windows, then deletes itself. Instead of using
267 the @b delete operator explicitly, you should normally use Destroy()
268 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
270 @see @ref overview_windowdeletion "Window Deletion Overview",
271 Destroy(), wxCloseEvent
277 @name Focus functions
279 See also the static function FindFocus().
284 This method may be overridden in the derived classes to return @false to
285 indicate that this control doesn't accept input at all (i.e. behaves like
286 e.g. wxStaticText) and so doesn't need focus.
288 @see AcceptsFocusFromKeyboard()
290 virtual bool AcceptsFocus() const;
293 This method may be overridden in the derived classes to return @false to
294 indicate that while this control can, in principle, have focus if the user
295 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
296 when using the keyboard.
298 virtual bool AcceptsFocusFromKeyboard() const;
301 Overridden to indicate wehter this window or one of its children accepts
302 focus. Usually it's the same as AcceptsFocus() but is overridden for
305 virtual bool AcceptsFocusRecursively() const;
308 Returns @true if the window (or in case of composite controls, its main
309 child window) has focus.
313 virtual bool HasFocus() const;
316 This method is only implemented by ports which have support for
317 native TAB traversal (such as GTK+ 2.0).
319 It is called by wxWidgets' container control code to give the native
320 system a hint when doing TAB traversal. A call to this does not disable
321 or change the effect of programmatically calling SetFocus().
323 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
325 virtual void SetCanFocus(bool canFocus
);
328 This sets the window to receive keyboard input.
330 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
331 wxPanel::SetFocusIgnoringChildren
333 virtual void SetFocus();
336 This function is called by wxWidgets keyboard navigation code when the user
337 gives the focus to this window from keyboard (e.g. using @c TAB key).
339 By default this method simply calls SetFocus() but
340 can be overridden to do something in addition to this in the derived classes.
342 virtual void SetFocusFromKbd();
348 @name Child management functions
353 Adds a child window. This is called automatically by window creation
354 functions so should not be required by the application programmer.
355 Notice that this function is mostly internal to wxWidgets and shouldn't be
356 called by the user code.
361 virtual void AddChild(wxWindow
* child
);
364 Destroys all children of a window. Called automatically by the destructor.
366 bool DestroyChildren();
369 Find a child of this window, by @a id.
370 May return @a this if it matches itself.
372 wxWindow
* FindWindow(long id
) const;
375 Find a child of this window, by name.
376 May return @a this if it matches itself.
378 wxWindow
* FindWindow(const wxString
& name
) const;
381 Returns a reference to the list of the window's children. @c wxWindowList
382 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
384 wxWindowList
& GetChildren();
389 const wxWindowList
& GetChildren() const;
392 Removes a child window.
394 This is called automatically by window deletion functions so should not
395 be required by the application programmer.
396 Notice that this function is mostly internal to wxWidgets and shouldn't be
397 called by the user code.
400 Child window to remove.
402 virtual void RemoveChild(wxWindow
* child
);
408 @name Sibling and parent management functions
413 Returns the grandparent of a window, or @NULL if there isn't one.
415 wxWindow
* GetGrandParent() const;
418 Returns the next window after this one among the parent children or @NULL
419 if this window is the last child.
423 @see GetPrevSibling()
425 wxWindow
* GetNextSibling() const;
428 Returns the parent of the window, or @NULL if there is no parent.
430 wxWindow
* GetParent() const;
433 Returns the previous window before this one among the parent children or @c
434 @NULL if this window is the first child.
438 @see GetNextSibling()
440 wxWindow
* GetPrevSibling() const;
442 Reparents the window, i.e the window will be removed from its
443 current parent window (e.g. a non-standard toolbar in a wxFrame)
444 and then re-inserted into another.
449 virtual bool Reparent(wxWindow
* newParent
);
455 @name Scrolling and scrollbars functions
460 Call this function to force one or both scrollbars to be always shown, even if
461 the window is big enough to show its entire contents without scrolling.
466 Whether the horizontal scroll bar should always be visible.
468 Whether the vertical scroll bar should always be visible.
470 @remarks This function is currently only implemented under Mac/Carbon.
472 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
475 Returns the built-in scrollbar position.
477 @see See SetScrollbar()
479 virtual int GetScrollPos(int orientation
) const;
482 Returns the built-in scrollbar range.
486 virtual int GetScrollRange(int orientation
) const;
489 Returns the built-in scrollbar thumb size.
493 virtual int GetScrollThumb(int orientation
) const;
496 Returns @true if this window has a scroll bar for this orientation.
499 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
501 bool HasScrollbar(int orient
) const;
504 Return whether a scrollbar is always shown.
507 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
509 @see AlwaysShowScrollbars()
511 virtual bool IsScrollbarAlwaysShown(int orient
) const;
514 Scrolls the window by the given number of lines down (if @a lines is
517 @return Returns @true if the window was scrolled, @false if it was already
518 on top/bottom and nothing was done.
520 @remarks This function is currently only implemented under MSW and
521 wxTextCtrl under wxGTK (it also works for wxScrolled classes
522 under all platforms).
526 virtual bool ScrollLines(int lines
);
529 Scrolls the window by the given number of pages down (if @a pages is
532 @return Returns @true if the window was scrolled, @false if it was already
533 on top/bottom and nothing was done.
535 @remarks This function is currently only implemented under MSW and wxGTK.
539 virtual bool ScrollPages(int pages
);
542 Physically scrolls the pixels in the window and move child windows accordingly.
545 Amount to scroll horizontally.
547 Amount to scroll vertically.
549 Rectangle to scroll, if it is @NULL, the whole window is
550 scrolled (this is always the case under wxGTK which doesn't support this
553 @remarks Note that you can often use wxScrolled instead of using this
556 virtual void ScrollWindow(int dx
, int dy
,
557 const wxRect
* rect
= NULL
);
560 Same as #ScrollLines (-1).
565 Same as #ScrollLines (1).
570 Same as #ScrollPages (-1).
575 Same as #ScrollPages (1).
580 Sets the position of one of the built-in scrollbars.
583 Determines the scrollbar whose position is to be set.
584 May be wxHORIZONTAL or wxVERTICAL.
586 Position in scroll units.
588 @true to redraw the scrollbar, @false otherwise.
590 @remarks This function does not directly affect the contents of the
591 window: it is up to the application to take note of
592 scrollbar attributes and redraw contents accordingly.
594 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
597 virtual void SetScrollPos(int orientation
, int pos
,
598 bool refresh
= true);
601 Sets the scrollbar properties of a built-in scrollbar.
604 Determines the scrollbar whose page size is to be set.
605 May be wxHORIZONTAL or wxVERTICAL.
607 The position of the scrollbar in scroll units.
609 The size of the thumb, or visible portion of the scrollbar, in scroll units.
611 The maximum position of the scrollbar. Value of -1 can be used to
612 ask for the scrollbar to be shown but in the disabled state: this
613 can be used to avoid removing the scrollbar even when it is not
614 needed (currently this is only implemented in wxMSW port).
616 @true to redraw the scrollbar, @false otherwise.
619 Let's say you wish to display 50 lines of text, using the same font.
620 The window is sized so that you can only see 16 lines at a time.
623 SetScrollbar(wxVERTICAL, 0, 16, 50);
625 Note that with the window at this size, the thumb position can never
626 go above 50 minus 16, or 34. You can determine how many lines are
627 currently visible by dividing the current view size by the character
629 When defining your own scrollbar behaviour, you will always need
630 to recalculate the scrollbar settings when the window size changes.
631 You could therefore put your scrollbar calculations and SetScrollbar
632 call into a function named AdjustScrollbars, which can be called
633 initially and also from your wxSizeEvent handler function.
635 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
637 virtual void SetScrollbar(int orientation
, int position
,
638 int thumbSize
, int range
,
639 bool refresh
= true);
644 @name Sizing functions
646 See also the protected functions DoGetBestSize() and SetInitialBestSize().
651 Sets the cached best size value.
653 void CacheBestSize(const wxSize
& size
) const;
656 Converts client area size @a size to corresponding window size.
658 In other words, the returned value is what would GetSize() return if this
659 window had client area of given size. Components with wxDefaultCoord
660 value are left unchanged. Note that the conversion is not always
661 exact, it assumes that non-client area doesn't change and so doesn't
662 take into account things like menu bar (un)wrapping or (dis)appearance
667 @see WindowToClientSize()
669 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
672 Converts window size @a size to corresponding client area size
673 In other words, the returned value is what would GetClientSize() return if
674 this window had given window size. Components with wxDefaultCoord value
677 Note that the conversion is not always exact, it assumes that
678 non-client area doesn't change and so doesn't take into account things
679 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
683 @see ClientToWindowSize()
685 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
688 Sizes the window so that it fits around its subwindows.
690 This function won't do anything if there are no subwindows and will only really
691 work correctly if sizers are used for the subwindows layout.
693 Also, if the window has exactly one subwindow it is better (faster and the result
694 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
698 window->SetClientSize(child->GetSize());
701 instead of calling Fit().
703 @see @ref overview_windowsizing
708 Similar to Fit(), but sizes the interior (virtual) size of a window.
710 Mainly useful with scrolled windows to reset scrollbars after sizing
711 changes that do not trigger a size event, and/or scrolled windows without
712 an interior sizer. This function similarly won't do anything if there are
715 virtual void FitInside();
718 This functions returns the best acceptable minimal size for the window.
720 For example, for a static control, it will be the minimal size such that the
721 control label is not truncated. For windows containing subwindows (typically
722 wxPanel), the size returned by this function will be the same as the size
723 the window would have had after calling Fit().
725 wxSize
GetBestSize() const;
728 Returns the size of the window 'client area' in pixels.
730 The client area is the area which may be drawn on by the programmer,
731 excluding title bar, border, scrollbars, etc.
732 Note that if this window is a top-level one and it is currently minimized, the
733 return size is empty (both width and height are 0).
735 @see GetSize(), GetVirtualSize()
737 void GetClientSize(int* width
, int* height
) const;
742 wxSize
GetClientSize() const;
745 Merges the window's best size into the min size and returns the result.
746 This is the value used by sizers to determine the appropriate
747 ammount of space to allocate for the widget.
749 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
751 wxSize
GetEffectiveMinSize() const;
754 Returns the maximum size of window's client area.
756 This is an indication to the sizer layout mechanism that this is the maximum
757 possible size as well as the upper bound on window's size settable using
762 virtual wxSize
GetMaxClientSize() const;
765 Returns the maximum size of the window.
767 This is an indication to the sizer layout mechanism that this is the maximum
768 possible size as well as the upper bound on window's size settable using SetSize().
770 @see GetMaxClientSize()
772 virtual wxSize
GetMaxSize() const;
775 Returns the minimum size of window's client area, an indication to the sizer
776 layout mechanism that this is the minimum required size of its client area.
778 It normally just returns the value set by SetMinClientSize(), but it can be
779 overridden to do the calculation on demand.
783 virtual wxSize
GetMinClientSize() const;
786 Returns the minimum size of the window, an indication to the sizer layout
787 mechanism that this is the minimum required size.
789 This method normally just returns the value set by SetMinSize(), but it
790 can be overridden to do the calculation on demand.
792 @see GetMinClientSize()
794 virtual wxSize
GetMinSize() const;
797 Returns the size of the entire window in pixels, including title bar, border,
800 Note that if this window is a top-level one and it is currently minimized, the
801 returned size is the restored window size, not the size of the window icon.
804 Receives the window width.
806 Receives the window height.
808 @see GetClientSize(), GetVirtualSize()
810 void GetSize(int* width
, int* height
) const;
813 See the GetSize(int*,int*) overload for more info.
815 wxSize
GetSize() const;
818 This gets the virtual size of the window in pixels.
819 By default it returns the client size of the window, but after a call to
820 SetVirtualSize() it will return the size set with that method.
822 wxSize
GetVirtualSize() const;
825 Like the other GetVirtualSize() overload but uses pointers instead.
828 Receives the window virtual width.
830 Receives the window virtual height.
832 void GetVirtualSize(int* width
, int* height
) const;
835 Returns the size of the left/right and top/bottom borders of this window in x
836 and y components of the result respectively.
838 virtual wxSize
GetWindowBorderSize() const;
841 Resets the cached best size value so it will be recalculated the next time it
844 void InvalidateBestSize();
846 Posts a size event to the window.
848 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
850 void PostSizeEvent();
853 Posts a size event to the parent of this window.
855 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
858 void PostSizeEventToParent();
861 This function sends a dummy @ref wxSizeEvent "size event" to
862 the window allowing it to re-layout its children positions.
864 It is sometimes useful to call this function after adding or deleting a
865 children after the frame creation or if a child size changes. Note that
866 if the frame is using either sizers or constraints for the children
867 layout, it is enough to call wxWindow::Layout() directly and this
868 function should not be used in this case.
870 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
871 the event, i.e. schedules it for later processing, instead of
872 dispatching it directly. You can also use PostSizeEvent() as a more
873 readable equivalent of calling this function with this flag.
876 May include @c wxSEND_EVENT_POST. Default value is 0.
878 virtual void SendSizeEvent(int flags
= 0);
881 Safe wrapper for GetParent()->SendSizeEvent().
883 This function simply checks that the window has a valid parent which is
884 not in process of being deleted and calls SendSizeEvent() on it. It is
885 used internally by windows such as toolbars changes to whose state
886 should result in parent re-layout (e.g. when a toolbar is added to the
887 top of the window, all the other windows must be shifted down).
889 @see PostSizeEventToParent()
892 See description of this parameter in SendSizeEvent() documentation.
894 void SendSizeEventToParent(int flags
= 0);
897 This sets the size of the window client area in pixels.
899 Using this function to size a window tends to be more device-independent
900 than SetSize(), since the application need not worry about what dimensions
901 the border or title bar have when trying to fit the window around panel
904 virtual void SetClientSize(int width
, int height
);
909 virtual void SetClientSize(const wxSize
& size
);
912 This normally does not need to be called by user code.
913 It is called when a window is added to a sizer, and is used so the window
914 can remove itself from the sizer when it is destroyed.
916 void SetContainingSizer(wxSizer
* sizer
);
919 A @e smart SetSize that will fill in default size components with the
920 window's @e best size values.
922 Also sets the window's minsize to the value passed in for use with sizers.
923 This means that if a full or partial size is passed to this function then
924 the sizers will use that size instead of the results of GetBestSize() to
925 determine the minimum needs of the window for layout.
927 Most controls will use this to set their initial size, and their min
928 size to the passed in value (if any.)
930 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
931 @ref overview_windowsizing
933 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
936 Sets the maximum client size of the window, to indicate to the sizer
937 layout mechanism that this is the maximum possible size of its client area.
941 virtual void SetMaxClientSize(const wxSize
& size
);
944 Sets the maximum size of the window, to indicate to the sizer layout mechanism
945 that this is the maximum possible size.
947 @see SetMaxClientSize()
949 virtual void SetMaxSize(const wxSize
& size
);
952 Sets the minimum client size of the window, to indicate to the sizer
953 layout mechanism that this is the minimum required size of window's client
956 You may need to call this if you change the window size after
957 construction and before adding to its parent sizer.
959 Note, that just as with SetMinSize(), calling this method doesn't
960 prevent the program from explicitly making the window smaller than the
965 virtual void SetMinClientSize(const wxSize
& size
);
968 Sets the minimum size of the window, to indicate to the sizer layout
969 mechanism that this is the minimum required size.
971 You may need to call this if you change the window size after
972 construction and before adding to its parent sizer.
974 Notice that calling this method doesn't prevent the program from making
975 the window explicitly smaller than the specified size by calling
976 SetSize(), it just ensures that it won't become smaller than this size
977 during the automatic layout.
979 @see SetMinClientSize()
981 virtual void SetMinSize(const wxSize
& size
);
984 Sets the size of the window in pixels.
987 Required x position in pixels, or wxDefaultCoord to indicate that the
988 existing value should be used.
990 Required y position in pixels, or wxDefaultCoord to indicate that the
991 existing value should be used.
993 Required width in pixels, or wxDefaultCoord to indicate that the existing
994 value should be used.
996 Required height position in pixels, or wxDefaultCoord to indicate that the
997 existing value should be used.
999 Indicates the interpretation of other parameters.
1000 It is a bit list of the following:
1001 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
1002 a wxWidgets-supplied default width.
1003 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
1004 a wxWidgets-supplied default height.
1005 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1006 a wxWidgets-supplied default size.
1007 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1008 if wxDefaultCoord values are supplied.
1009 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1010 wxDefaultCoord) to be interpreted as real
1011 dimensions, not default values.
1012 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1013 already the same as the parameters of this function,
1014 nothing is done. but with this flag a window resize may
1015 be forced even in this case (supported in wx 2.6.2 and
1016 later and only implemented for MSW and ignored elsewhere
1019 @remarks This overload sets the position and optionally size, of the window.
1020 Parameters may be wxDefaultCoord to indicate either that a default
1021 should be supplied by wxWidgets, or that the current value of the
1022 dimension should be used.
1026 void SetSize(int x
, int y
, int width
, int height
,
1027 int sizeFlags
= wxSIZE_AUTO
);
1030 Sets the size of the window in pixels.
1031 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1033 @remarks This form must be used with non-default width and height values.
1037 virtual void SetSize(const wxRect
& rect
);
1042 virtual void SetSize(const wxSize
& size
);
1047 virtual void SetSize(int width
, int height
);
1050 Use of this function for windows which are not toplevel windows
1051 (such as wxDialog or wxFrame) is discouraged.
1052 Please use SetMinSize() and SetMaxSize() instead.
1054 @see wxTopLevelWindow::SetSizeHints
1056 void SetSizeHints( const wxSize
& minSize
,
1057 const wxSize
& maxSize
=wxDefaultSize
,
1058 const wxSize
& incSize
=wxDefaultSize
);
1061 Sets the virtual size of the window in pixels.
1063 void SetVirtualSize(int width
, int height
);
1068 void SetVirtualSize(const wxSize
& size
);
1074 @name Positioning functions
1079 A synonym for Centre().
1081 void Center(int dir
= wxBOTH
);
1084 A synonym for CentreOnParent().
1086 void CenterOnParent(int dir
= wxBOTH
);
1092 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1093 or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
1094 if you want to center the window on the entire screen and not on its
1097 @remarks If the window is a top level one (i.e. doesn't have a parent),
1098 it will be centered relative to the screen anyhow.
1102 void Centre(int direction
= wxBOTH
);
1105 Centres the window on its parent. This is a more readable synonym for Centre().
1108 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
1111 @remarks This methods provides for a way to center top level windows over
1112 their parents instead of the entire screen. If there
1113 is no parent or if the window is not a top level
1114 window, then behaviour is the same as Centre().
1116 @see wxTopLevelWindow::CentreOnScreen
1118 void CentreOnParent(int direction
= wxBOTH
);
1120 This gets the position of the window in pixels, relative to the parent window
1121 for the child windows or relative to the display origin for the top level windows.
1124 Receives the x position of the window if non-@NULL.
1126 Receives the y position of the window if non-@NULL.
1128 @see GetScreenPosition()
1130 void GetPosition(int* x
, int* y
) const;
1133 This gets the position of the window in pixels, relative to the parent window
1134 for the child windows or relative to the display origin for the top level windows.
1136 @see GetScreenPosition()
1138 wxPoint
GetPosition() const;
1141 Returns the position and size of the window as a wxRect object.
1143 @see GetScreenRect()
1145 wxRect
GetRect() const;
1148 Returns the window position in screen coordinates, whether the window is a
1149 child window or a top level one.
1152 Receives the x position of the window on the screen if non-@NULL.
1154 Receives the y position of the window on the screen if non-@NULL.
1158 void GetScreenPosition(int* x
, int* y
) const;
1161 Returns the window position in screen coordinates, whether the window is a
1162 child window or a top level one.
1166 wxPoint
GetScreenPosition() const;
1169 Returns the position and size of the window on the screen as a wxRect object.
1173 wxRect
GetScreenRect() const;
1176 Moves the window to the given position.
1179 Required x position.
1181 Required y position.
1183 See SetSize() for more info about this parameter.
1185 @remarks Implementations of SetSize can also implicitly implement the
1186 Move() function, which is defined in the base wxWindow class as the call:
1188 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1193 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1196 Moves the window to the given position.
1199 wxPoint object representing the position.
1201 See SetSize() for more info about this parameter.
1203 @remarks Implementations of SetSize() can also implicitly implement the
1204 Move() function, which is defined in the base wxWindow class as the call:
1206 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1211 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1217 @name Coordinate conversion functions
1222 Converts to screen coordinates from coordinates relative to this window.
1225 A pointer to a integer value for the x coordinate. Pass the client
1226 coordinate in, and a screen coordinate will be passed out.
1228 A pointer to a integer value for the y coordinate. Pass the client
1229 coordinate in, and a screen coordinate will be passed out.
1232 In place of a single overloaded method name, wxPython implements the following methods:
1233 - ClientToScreen(point): Accepts and returns a wxPoint
1234 - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
1237 void ClientToScreen(int* x
, int* y
) const;
1240 Converts to screen coordinates from coordinates relative to this window.
1243 The client position for the second form of the function.
1245 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
1248 Converts a point or size from dialog units to pixels.
1250 For the x dimension, the dialog units are multiplied by the average character
1251 width and then divided by 4.
1252 For the y dimension, the dialog units are multiplied by the average character
1253 height and then divided by 8.
1255 @remarks Dialog units are used for maintaining a dialog's proportions
1256 even if the font changes.
1257 You can also use these functions programmatically.
1258 A convenience macro is defined:
1260 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1263 @see ConvertPixelsToDialog()
1265 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
);
1270 wxSize
ConvertDialogToPixels(const wxSize
& sz
);
1273 Converts a point or size from pixels to dialog units.
1275 For the x dimension, the pixels are multiplied by 4 and then divided by the
1276 average character width.
1277 For the y dimension, the pixels are multiplied by 8 and then divided by the
1278 average character height.
1280 @remarks Dialog units are used for maintaining a dialog's proportions
1281 even if the font changes.
1283 @see ConvertDialogToPixels()
1285 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
);
1290 wxSize
ConvertPixelsToDialog(const wxSize
& sz
);
1293 Converts from screen to client window coordinates.
1296 Stores the screen x coordinate and receives the client x coordinate.
1298 Stores the screen x coordinate and receives the client x coordinate.
1300 void ScreenToClient(int* x
, int* y
) const;
1303 Converts from screen to client window coordinates.
1306 The screen position.
1308 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1314 @name Drawing-related functions
1319 Clears the window by filling it with the current background colour. Does not
1320 cause an erase background event to be generated.
1322 virtual void ClearBackground();
1325 Freezes the window or, in other words, prevents any updates from taking
1326 place on screen, the window is not redrawn at all.
1328 Thaw() must be called to reenable window redrawing. Calls to these two
1329 functions may be nested but to ensure that the window is properly
1330 repainted again, you must thaw it exactly as many times as you froze it.
1332 If the window has any children, they are recursively frozen too.
1334 This method is useful for visual appearance optimization (for example,
1335 it is a good idea to use it before doing many large text insertions in
1336 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1337 platforms nor for all controls so it is mostly just a hint to wxWidgets
1338 and not a mandatory directive.
1340 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1345 Reenables window updating after a previous call to Freeze().
1347 To really thaw the control, it must be called exactly the same number
1348 of times as Freeze().
1350 If the window has any children, they are recursively thawn too.
1352 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1357 Returns @true if the window is currently frozen by a call to Freeze().
1359 @see Freeze(), Thaw()
1361 bool IsFrozen() const;
1364 Returns the background colour of the window.
1366 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1368 wxColour
GetBackgroundColour() const;
1371 Returns the background style of the window.
1372 The background style can be one of the wxBackgroundStyle.
1374 @see SetBackgroundColour(), GetForegroundColour(),
1375 SetBackgroundStyle(), SetTransparent()
1377 virtual wxBackgroundStyle
GetBackgroundStyle() const;
1379 Returns the character height for this window.
1381 virtual int GetCharHeight() const;
1384 Returns the average character width for this window.
1386 virtual int GetCharWidth() const;
1389 Currently this is the same as calling
1390 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1392 One advantage of using this function compared to the static version is that
1393 the call is automatically dispatched to the correct class (as usual with
1394 virtual functions) and you don't have to specify the class name explicitly.
1396 The other one is that in the future this function could return different
1397 results, for example it might return a different font for an "Ok" button
1398 than for a generic button if the users GUI is configured to show such buttons
1399 in bold font. Of course, the down side is that it is impossible to call this
1400 function without actually having an object to apply it to whereas the static
1401 version can be used without having to create an object first.
1403 virtual wxVisualAttributes
GetDefaultAttributes() const;
1406 Returns the font for this window.
1410 wxFont
GetFont() const;
1413 Returns the foreground colour of the window.
1415 @remarks The interpretation of foreground colour is open to
1416 interpretation according to the window class; it may be
1417 the text colour or other colour, or it may not be used at all.
1419 @see SetForegroundColour(), SetBackgroundColour(),
1420 GetBackgroundColour()
1422 wxColour
GetForegroundColour() const;
1425 Gets the dimensions of the string as it would be drawn on the
1426 window with the currently selected font.
1428 The text extent is returned in @a w and @a h pointers.
1431 String whose extent is to be measured.
1433 Return value for width.
1435 Return value for height.
1437 Return value for descent (optional).
1438 @param externalLeading
1439 Return value for external leading (optional).
1441 Font to use instead of the current window font (optional).
1443 virtual void GetTextExtent(const wxString
& string
, int* w
, int* h
,
1444 int* descent
= NULL
,
1445 int* externalLeading
= NULL
,
1446 const wxFont
* font
= NULL
) const;
1449 Gets the dimensions of the string as it would be drawn on the
1450 window with the currently selected font.
1452 wxSize
GetTextExtent(const wxString
& string
) const;
1455 Returns the region specifying which parts of the window have been damaged.
1456 Should only be called within an wxPaintEvent handler.
1458 @see wxRegion, wxRegionIterator
1460 const wxRegion
& GetUpdateRegion() const;
1463 Returns @true if this window background is transparent (as, for example,
1464 for wxStaticText) and should show the parent window background.
1466 This method is mostly used internally by the library itself and you normally
1467 shouldn't have to call it. You may, however, have to override it in your
1468 wxWindow-derived class to ensure that background is painted correctly.
1470 virtual bool HasTransparentBackground();
1473 Causes this window, and all of its children recursively (except under wxGTK1
1474 where this is not implemented), to be repainted. Note that repainting doesn't
1475 happen immediately but only during the next event loop iteration, if you need
1476 to update the window immediately you should use Update() instead.
1478 @param eraseBackground
1479 If @true, the background will be erased.
1481 If non-@NULL, only the given rectangle will be treated as damaged.
1485 virtual void Refresh(bool eraseBackground
= true,
1486 const wxRect
* rect
= NULL
);
1489 Redraws the contents of the given rectangle: only the area inside it will be
1492 This is the same as Refresh() but has a nicer syntax as it can be called
1493 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1495 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1498 Calling this method immediately repaints the invalidated area of the window and
1499 all of its children recursively while this would usually only happen when the
1500 flow of control returns to the event loop.
1502 Notice that this function doesn't invalidate any area of the window so
1503 nothing happens if nothing has been invalidated (i.e. marked as requiring
1504 a redraw). Use Refresh() first if you want to immediately redraw the
1505 window unconditionally.
1507 virtual void Update();
1510 Sets the background colour of the window.
1511 Please see InheritAttributes() for explanation of the difference between
1512 this method and SetOwnBackgroundColour().
1515 The colour to be used as the background colour, pass
1516 wxNullColour to reset to the default colour.
1518 @remarks The background colour is usually painted by the default
1519 wxEraseEvent event handler function under Windows and
1520 automatically under GTK.
1521 Note that setting the background colour does not cause an
1522 immediate refresh, so you may wish to call wxWindow::ClearBackground
1523 or wxWindow::Refresh after calling this function.
1524 Using this function will disable attempts to use themes for
1525 this window, if the system supports them. Use with care since
1526 usually the themes represent the appearance chosen by the user
1527 to be used for all applications on the system.
1529 @see GetBackgroundColour(), SetForegroundColour(),
1530 GetForegroundColour(), ClearBackground(),
1531 Refresh(), wxEraseEvent
1533 virtual bool SetBackgroundColour(const wxColour
& colour
);
1536 Sets the background style of the window. see GetBackgroundStyle() for
1537 the description of the possible style values.
1539 @see SetBackgroundColour(), GetForegroundColour(),
1542 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
1545 Sets the font for this window. This function should not be called for the
1546 parent window if you don't want its font to be inherited by its children,
1547 use SetOwnFont() instead in this case and see InheritAttributes() for more
1550 Please notice that the given font is not automatically used for
1551 wxPaintDC objects associated with this window, you need to
1552 call wxDC::SetFont too. However this font is used by
1553 any standard controls for drawing their text as well as by
1557 Font to associate with this window, pass
1558 wxNullFont to reset to the default font.
1560 @return @true if the want was really changed, @false if it was already set
1561 to this font and so nothing was done.
1563 @see GetFont(), InheritAttributes()
1565 virtual bool SetFont(const wxFont
& font
);
1568 Sets the foreground colour of the window.
1569 Please see InheritAttributes() for explanation of the difference between
1570 this method and SetOwnForegroundColour().
1573 The colour to be used as the foreground colour, pass
1574 wxNullColour to reset to the default colour.
1576 @remarks The interpretation of foreground colour is open to
1577 interpretation according to the window class; it may be
1578 the text colour or other colour, or it may not be used at all.
1580 @see GetForegroundColour(), SetBackgroundColour(),
1581 GetBackgroundColour(), ShouldInheritColours()
1583 virtual bool SetForegroundColour(const wxColour
& colour
);
1586 Sets the background colour of the window but prevents it from being inherited
1587 by the children of this window.
1589 @see SetBackgroundColour(), InheritAttributes()
1591 void SetOwnBackgroundColour(const wxColour
& colour
);
1594 Sets the font of the window but prevents it from being inherited by the
1595 children of this window.
1597 @see SetFont(), InheritAttributes()
1599 void SetOwnFont(const wxFont
& font
);
1602 Sets the foreground colour of the window but prevents it from being inherited
1603 by the children of this window.
1605 @see SetForegroundColour(), InheritAttributes()
1607 void SetOwnForegroundColour(const wxColour
& colour
);
1610 @deprecated use wxDC::SetPalette instead.
1612 void SetPalette(const wxPalette
& pal
);
1615 Return @true from here to allow the colours of this window to be changed by
1616 InheritAttributes(), returning @false forbids inheriting them from the parent window.
1618 The base class version returns @false, but this method is overridden in
1619 wxControl where it returns @true.
1621 virtual bool ShouldInheritColours() const;
1624 This function tells a window if it should use the system's "theme" code
1625 to draw the windows' background instead if its own background drawing
1626 code. This does not always have any effect since the underlying platform
1627 obviously needs to support the notion of themes in user defined windows.
1628 One such platform is GTK+ where windows can have (very colourful) backgrounds
1629 defined by a user's selected theme.
1631 Dialogs, notebook pages and the status bar have this flag set to @true
1632 by default so that the default look and feel is simulated best.
1634 virtual void SetThemeEnabled(bool enable
);
1637 Returns @true if the system supports transparent windows and calling
1638 SetTransparent() may succeed. If this function returns @false, transparent
1639 windows are definitely not supported by the current system.
1641 virtual bool CanSetTransparent();
1644 Set the transparency of the window. If the system supports transparent windows,
1645 returns @true, otherwise returns @false and the window remains fully opaque.
1646 See also CanSetTransparent().
1648 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
1649 fully transparent window and 255 to the fully opaque one. The constants
1650 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
1652 virtual bool SetTransparent(wxByte alpha
);
1658 @name Event-handling functions
1663 Returns the event handler for this window.
1664 By default, the window is its own event handler.
1666 @see SetEventHandler(), PushEventHandler(),
1667 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1669 wxEvtHandler
* GetEventHandler() const;
1672 This function will generate the appropriate call to
1673 Navigate() if the key event is one normally used for
1674 keyboard navigation and return @true in this case.
1676 @return Returns @true if the key pressed was for navigation and was
1677 handled, @false otherwise.
1681 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
1686 GetEventHandler()->SafelyProcessEvent(event);
1689 bool HandleWindowEvent(wxEvent
& event
) const;
1692 Removes and returns the top-most event handler on the event handler stack.
1694 @param deleteHandler
1695 If this is @true, the handler will be deleted after it is removed.
1696 The default value is @false.
1698 @see SetEventHandler(), GetEventHandler(),
1699 PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1701 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
1704 Pushes this event handler onto the event stack for the window.
1707 Specifies the handler to be pushed.
1709 @remarks An event handler is an object that is capable of processing the
1710 events sent to a window. By default, the window is its
1711 own event handler, but an application may wish to
1712 substitute another, for example to allow central
1713 implementation of event-handling for a variety of
1714 different window classes.
1715 wxWindow::PushEventHandler allows an application to set up a
1716 chain of event handlers, where an event not handled by one event
1717 handler is handed to the next one in the chain.
1718 Use wxWindow::PopEventHandler to remove the event handler.
1720 @see SetEventHandler(), GetEventHandler(),
1721 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1723 void PushEventHandler(wxEvtHandler
* handler
);
1726 Find the given @a handler in the windows event handler chain and remove
1727 (but not delete) it from it.
1730 The event handler to remove, must be non-@NULL and
1731 must be present in this windows event handlers chain
1733 @return Returns @true if it was found and @false otherwise (this also
1734 results in an assert failure so this function should
1735 only be called when the handler is supposed to be there).
1737 @see PushEventHandler(), PopEventHandler()
1739 bool RemoveEventHandler(wxEvtHandler
* handler
);
1742 Sets the event handler for this window.
1745 Specifies the handler to be set.
1747 @remarks An event handler is an object that is capable of processing the
1748 events sent to a window. By default, the window is its
1749 own event handler, but an application may wish to
1750 substitute another, for example to allow central
1751 implementation of event-handling for a variety of
1752 different window classes.
1753 It is usually better to use wxWindow::PushEventHandler since
1754 this sets up a chain of event handlers, where an event not
1755 handled by one event handler is handed to the next one in the chain.
1757 @see GetEventHandler(), PushEventHandler(),
1758 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1760 void SetEventHandler(wxEvtHandler
* handler
);
1766 @name Window styles functions
1771 Returns the extra style bits for the window.
1773 long GetExtraStyle() const;
1776 Gets the window style that was passed to the constructor or Create()
1777 method. GetWindowStyle() is another name for the same function.
1779 virtual long GetWindowStyleFlag() const;
1782 See GetWindowStyleFlag() for more info.
1784 long GetWindowStyle() const;
1787 Returns @true if the window has the given @a exFlag bit set in its
1790 @see SetExtraStyle()
1792 bool HasExtraStyle(int exFlag
) const;
1795 Returns @true if the window has the given @a flag bit set.
1797 bool HasFlag(int flag
) const;
1800 Sets the extra style bits for the window.
1801 The currently defined extra style bits are reported in the class
1804 virtual void SetExtraStyle(long exStyle
);
1807 Sets the style of the window. Please note that some styles cannot be changed
1808 after the window creation and that Refresh() might need to be be called
1809 after changing the others for the change to take place immediately.
1811 See @ref overview_windowstyles "Window styles" for more information about flags.
1813 @see GetWindowStyleFlag()
1815 virtual void SetWindowStyleFlag(long style
);
1818 See SetWindowStyleFlag() for more info.
1820 void SetWindowStyle(long style
);
1823 Turns the given @a flag on if it's currently turned off and vice versa.
1824 This function cannot be used if the value of the flag is 0 (which is often
1825 the case for default flags).
1827 Also, please notice that not all styles can be changed after the control
1830 @return Returns @true if the style was turned on by this function, @false
1831 if it was switched off.
1833 @see SetWindowStyleFlag(), HasFlag()
1835 bool ToggleWindowStyle(int flag
);
1841 @name Tab order functions
1846 Moves this window in the tab navigation order after the specified @e win.
1847 This means that when the user presses @c TAB key on that other window,
1848 the focus switches to this window.
1850 Default tab order is the same as creation order, this function and
1851 MoveBeforeInTabOrder() allow to change
1852 it after creating all the windows.
1855 A sibling of this window which should precede it in tab order,
1858 void MoveAfterInTabOrder(wxWindow
* win
);
1861 Same as MoveAfterInTabOrder() except that it inserts this window just
1862 before @a win instead of putting it right after it.
1864 void MoveBeforeInTabOrder(wxWindow
* win
);
1867 Performs a keyboard navigation action starting from this window.
1868 This method is equivalent to calling NavigateIn() method on the
1872 A combination of wxNavigationKeyEvent::IsForward and
1873 wxNavigationKeyEvent::WinChange.
1875 @return Returns @true if the focus was moved to another window or @false
1878 @remarks You may wish to call this from a text control custom keypress
1879 handler to do the default navigation behaviour for the
1880 tab key, since the standard default behaviour for a
1881 multiline text control with the wxTE_PROCESS_TAB style
1882 is to insert a tab and not navigate to the next
1883 control. See also wxNavigationKeyEvent and
1884 HandleAsNavigationKey.
1886 bool Navigate(int flags
= IsForward
);
1889 Performs a keyboard navigation action inside this window.
1890 See Navigate() for more information.
1892 bool NavigateIn(int flags
= IsForward
);
1899 @name Z order functions
1904 Lowers the window to the bottom of the window hierarchy (Z-order).
1907 This function only works for wxTopLevelWindow-derived classes.
1911 virtual void Lower();
1914 Raises the window to the top of the window hierarchy (Z-order).
1917 This function only works for wxTopLevelWindow-derived classes.
1921 virtual void Raise();
1927 @name Window status functions
1933 Equivalent to calling wxWindow::Show(@false).
1938 This function hides a window, like Hide(), but using a special visual
1941 The parameters of this function are the same as for ShowWithEffect(),
1942 please see their description there.
1946 virtual bool HideWithEffect(wxShowEffect effect
,
1947 unsigned int timeout
= 0);
1949 Returns @true if the window is enabled, i.e. if it accepts user input,
1952 Notice that this method can return @false even if this window itself hadn't
1953 been explicitly disabled when one of its parent windows is disabled.
1954 To get the intrinsic status of this window, use IsThisEnabled()
1958 bool IsEnabled() const;
1961 Returns @true if the given point or rectangle area has been exposed since the
1962 last repaint. Call this in an paint event handler to optimize redrawing by
1963 only redrawing those areas, which have been exposed.
1965 bool IsExposed(int x
, int y
) const;
1970 bool IsExposed(wxPoint
& pt
) const;
1975 bool IsExposed(int x
, int y
, int w
, int h
) const;
1980 bool IsExposed(wxRect
& rect
) const;
1982 Returns @true if the window is shown, @false if it has been hidden.
1984 @see IsShownOnScreen()
1986 virtual bool IsShown() const;
1989 Returns @true if the window is physically visible on the screen, i.e. it
1990 is shown and all its parents up to the toplevel window are shown as well.
1994 virtual bool IsShownOnScreen() const;
1997 Disables the window. Same as @ref Enable() Enable(@false).
1999 @return Returns @true if the window has been disabled, @false if it had
2000 been already disabled before the call to this function.
2005 Enable or disable the window for user input. Note that when a parent window is
2006 disabled, all of its children are disabled as well and they are reenabled again
2010 If @true, enables the window for input. If @false, disables the window.
2012 @return Returns @true if the window has been enabled or disabled, @false
2013 if nothing was done, i.e. if the window had already
2014 been in the specified state.
2016 @see IsEnabled(), Disable(), wxRadioBox::Enable
2018 virtual bool Enable(bool enable
= true);
2021 Shows or hides the window. You may need to call Raise()
2022 for a top level window if you want to bring it to top, although this is not
2023 needed if Show() is called immediately after the frame creation.
2026 If @true displays the window. Otherwise, hides it.
2028 @return @true if the window has been shown or hidden or @false if nothing
2029 was done because it already was in the requested state.
2031 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2033 virtual bool Show(bool show
= true);
2036 This function shows a window, like Show(), but using a special visual
2043 The @a timeout parameter specifies the time of the animation, in
2044 milliseconds. If the default value of 0 is used, the default
2045 animation time for the current platform is used.
2047 @note Currently this function is only implemented in wxMSW and does the
2048 same thing as Show() in the other ports.
2052 @see HideWithEffect()
2054 virtual bool ShowWithEffect(wxShowEffect effect
,
2055 unsigned int timeout
= 0);
2061 @name Context-sensitive help functions
2066 Gets the help text to be used as context-sensitive help for this window.
2067 Note that the text is actually stored by the current wxHelpProvider
2068 implementation, and not in the window object itself.
2070 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2072 wxString
GetHelpText() const;
2075 Sets the help text to be used as context-sensitive help for this window.
2076 Note that the text is actually stored by the current wxHelpProvider
2077 implementation, and not in the window object itself.
2079 @see GetHelpText(), wxHelpProvider::AddHelp()
2081 void SetHelpText(const wxString
& helpText
);
2084 Gets the help text to be used as context-sensitive help for this window.
2085 This method should be overridden if the help message depends on the position
2086 inside the window, otherwise GetHelpText() can be used.
2089 Coordinates of the mouse at the moment of help event emission.
2091 Help event origin, see also wxHelpEvent::GetOrigin.
2093 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
2094 wxHelpEvent
::Origin origin
) const;
2097 Get the associated tooltip or @NULL if none.
2099 wxToolTip
* GetToolTip() const;
2102 Attach a tooltip to the window.
2104 wxToolTip pointer can be @NULL in the overload taking the pointer,
2105 meaning to unset any existing tooltips, however UnsetToolTip() provides
2106 a more readable alternative to this operation.
2108 Notice that these methods are always available, even if wxWidgets was
2109 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2112 @see GetToolTip(), wxToolTip
2114 void SetToolTip(const wxString
& tip
);
2119 void SetToolTip(wxToolTip
* tip
);
2122 Unset any existing tooltip.
2128 void UnsetToolTip();
2134 @name Popup/context menu functions
2139 This function shows a popup menu at the given position in this window and
2140 returns the selected id.
2142 It can be more convenient than the general purpose PopupMenu() function
2143 for simple menus proposing a choice in a list of strings to the user.
2145 Notice that to avoid unexpected conflicts between the (usually
2146 consecutive range of) ids used by the menu passed to this function and
2147 the existing EVT_UPDATE_UI() handlers, this function temporarily
2148 disables UI updates for the window, so you need to manually disable
2149 (or toggle or ...) any items which should be disabled in the menu
2152 The parameter @a menu is the menu to show.
2153 The parameter @a pos (or the parameters @a x and @a y) is the
2154 position at which to show the menu in client coordinates.
2157 The selected menu item id or @c wxID_NONE if none selected or an
2162 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, const wxPoint
& pos
);
2167 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
2170 Pops up the given menu at the specified coordinates, relative to this
2171 window, and returns control when the user has dismissed the menu.
2173 If a menu item is selected, the corresponding menu event is generated and will be
2174 processed as usually. If the coordinates are not specified, current mouse
2175 cursor position is used.
2177 @a menu is the menu to pop up.
2179 The position where the menu will appear can be specified either as a
2180 wxPoint @a pos or by two integers (@a x and @a y).
2182 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2183 ensure that the menu items are in the correct state.
2184 The menu does not get deleted by the window.
2185 It is recommended to not explicitly specify coordinates when
2186 calling PopupMenu in response to mouse click, because some of
2187 the ports (namely, wxGTK) can do a better job of positioning
2188 the menu in that case.
2192 bool PopupMenu(wxMenu
* menu
,
2193 const wxPoint
& pos
= wxDefaultPosition
);
2198 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
2209 Returns a pointer to the current validator for the window, or @NULL if
2212 virtual wxValidator
* GetValidator();
2215 Deletes the current validator (if any) and sets the window validator, having
2216 called wxValidator::Clone to create a new validator of this type.
2218 virtual void SetValidator(const wxValidator
& validator
);
2221 Transfers values from child controls to data areas specified by their
2222 validators. Returns @false if a transfer failed.
2224 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2225 the method will also call TransferDataFromWindow() of all child windows.
2227 @see TransferDataToWindow(), wxValidator, Validate()
2229 virtual bool TransferDataFromWindow();
2232 Transfers values to child controls from data areas specified by their
2235 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2236 the method will also call TransferDataToWindow() of all child windows.
2238 @return Returns @false if a transfer failed.
2240 @see TransferDataFromWindow(), wxValidator, Validate()
2242 virtual bool TransferDataToWindow();
2245 Validates the current values of the child controls using their validators.
2246 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2247 the method will also call Validate() of all child windows.
2249 @return Returns @false if any of the validations failed.
2251 @see TransferDataFromWindow(), TransferDataToWindow(),
2254 virtual bool Validate();
2260 @name wxWindow properties functions
2265 Returns the identifier of the window.
2267 @remarks Each window has an integer identifier. If the application
2268 has not provided one (or the default wxID_ANY) an unique
2269 identifier with a negative value will be generated.
2271 @see SetId(), @ref overview_windowids
2273 wxWindowID
GetId() const;
2276 Generic way of getting a label from any window, for
2277 identification purposes.
2279 @remarks The interpretation of this function differs from class to class.
2280 For frames and dialogs, the value returned is the
2281 title. For buttons or static text controls, it is the
2282 button text. This function can be useful for
2283 meta-programs (such as testing tools or special-needs
2284 access programs) which need to identify windows by name.
2286 virtual wxString
GetLabel() const;
2289 Returns the window's name.
2291 @remarks This name is not guaranteed to be unique; it is up to the
2292 programmer to supply an appropriate name in the window
2293 constructor or via SetName().
2297 virtual wxString
GetName() const;
2300 Returns the value previously passed to SetWindowVariant().
2302 wxWindowVariant
GetWindowVariant() const;
2305 Sets the identifier of the window.
2307 @remarks Each window has an integer identifier. If the application has
2308 not provided one, an identifier will be generated.
2309 Normally, the identifier should be provided on creation
2310 and should not be modified subsequently.
2312 @see GetId(), @ref overview_windowids
2314 void SetId(wxWindowID winid
);
2317 Sets the window's label.
2324 virtual void SetLabel(const wxString
& label
);
2327 Sets the window's name.
2330 A name to set for the window.
2334 virtual void SetName(const wxString
& name
);
2337 This function can be called under all platforms but only does anything under
2338 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2339 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2341 By default the controls use the normal size, of course, but this function can
2342 be used to change this.
2344 void SetWindowVariant(wxWindowVariant variant
);
2348 Gets the accelerator table for this window. See wxAcceleratorTable.
2350 wxAcceleratorTable
* GetAcceleratorTable();
2353 Returns the accessible object for this window, if any.
2354 See also wxAccessible.
2356 wxAccessible
* GetAccessible();
2359 Sets the accelerator table for this window. See wxAcceleratorTable.
2361 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
2364 Sets the accessible for this window. Any existing accessible for this window
2365 will be deleted first, if not identical to @e accessible.
2366 See also wxAccessible.
2368 void SetAccessible(wxAccessible
* accessible
);
2374 @name Window deletion functions
2379 This function simply generates a wxCloseEvent whose handler usually tries
2380 to close the window. It doesn't close the window itself, however.
2383 @false if the window's close handler should be able to veto the destruction
2384 of this window, @true if it cannot.
2386 @remarks Close calls the close handler for the window, providing an
2387 opportunity for the window to choose whether to destroy
2388 the window. Usually it is only used with the top level
2389 windows (wxFrame and wxDialog classes) as the others
2390 are not supposed to have any special OnClose() logic.
2391 The close handler should check whether the window is being deleted
2392 forcibly, using wxCloseEvent::CanVeto, in which case it should
2393 destroy the window using wxWindow::Destroy.
2394 Note that calling Close does not guarantee that the window will
2395 be destroyed; but it provides a way to simulate a manual close
2396 of a window, which may or may not be implemented by destroying
2397 the window. The default implementation of wxDialog::OnCloseWindow
2398 does not necessarily delete the dialog, since it will simply
2399 simulate an wxID_CANCEL event which is handled by the appropriate
2400 button event handler and may do anything at all.
2401 To guarantee that the window will be destroyed, call
2402 wxWindow::Destroy instead
2404 @see @ref overview_windowdeletion "Window Deletion Overview",
2405 Destroy(), wxCloseEvent
2407 bool Close(bool force
= false);
2410 Destroys the window safely. Use this function instead of the delete operator,
2411 since different window classes can be destroyed differently. Frames and dialogs
2412 are not destroyed immediately when this function is called -- they are added
2413 to a list of windows to be deleted on idle time, when all the window's events
2414 have been processed. This prevents problems with events being sent to
2415 non-existent windows.
2417 @return @true if the window has either been successfully deleted, or it
2418 has been added to the list of windows pending real deletion.
2420 virtual bool Destroy();
2423 Returns true if this window is in process of being destroyed.
2425 The top level windows are not deleted immediately but are rather
2426 scheduled for later destruction to give them time to process any
2427 pending messages, see Destroy() description.
2429 This function returns @true if this window, or one of its parent
2430 windows, is scheduled for destruction and can be useful to avoid
2431 manipulating it as it's usually useless to do something with a window
2432 which is on the point of disappearing anyhow.
2434 bool IsBeingDeleted() const;
2441 @name Drag and drop functions
2446 Returns the associated drop target, which may be @NULL.
2448 @see SetDropTarget(), @ref overview_dnd
2450 virtual wxDropTarget
* GetDropTarget() const;
2453 Associates a drop target with this window.
2454 If the window already has a drop target, it is deleted.
2456 @see GetDropTarget(), @ref overview_dnd
2458 virtual void SetDropTarget(wxDropTarget
* target
);
2461 Enables or disables eligibility for drop file events (OnDropFiles).
2464 If @true, the window is eligible for drop file events.
2465 If @false, the window will not accept drop file events.
2467 @remarks Windows only until version 2.8.9, available on all platforms
2468 since 2.8.10. Cannot be used together with SetDropTarget() on
2469 non-Windows platforms.
2471 @see SetDropTarget()
2473 virtual void DragAcceptFiles(bool accept
);
2479 @name Constraints, sizers and window layouting functions
2484 Return the sizer that this window is a member of, if any, otherwise @NULL.
2486 wxSizer
* GetContainingSizer() const;
2489 Return the sizer associated with the window by a previous call to
2490 SetSizer() or @NULL.
2492 wxSizer
* GetSizer() const;
2495 Sets the window to have the given layout sizer.
2496 The window will then own the object, and will take care of its deletion.
2497 If an existing layout constraints object is already owned by the
2498 window, it will be deleted if the deleteOld parameter is @true.
2500 Note that this function will also call SetAutoLayout() implicitly with @true
2501 parameter if the @a sizer is non-@NULL and @false otherwise.
2504 The sizer to set. Pass @NULL to disassociate and conditionally delete
2505 the window's sizer. See below.
2507 If @true (the default), this will delete any pre-existing sizer.
2508 Pass @false if you wish to handle deleting the old sizer yourself.
2510 @remarks SetSizer enables and disables Layout automatically.
2512 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2515 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2516 window size to the size needed to accommodate all sizer elements and sets the
2517 size hints which, if this window is a top level one, prevent the user from
2518 resizing it to be less than this minimial size.
2520 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2523 Returns a pointer to the window's layout constraints, or @NULL if there are none.
2525 wxLayoutConstraints
* GetConstraints() const;
2528 Sets the window to have the given layout constraints. The window
2529 will then own the object, and will take care of its deletion.
2530 If an existing layout constraints object is already owned by the
2531 window, it will be deleted.
2534 The constraints to set. Pass @NULL to disassociate and delete the window's
2537 @remarks You must call SetAutoLayout() to tell a window to use
2538 the constraints automatically in OnSize; otherwise, you
2539 must override OnSize and call Layout() explicitly. When
2540 setting both a wxLayoutConstraints and a wxSizer, only
2541 the sizer will have effect.
2543 void SetConstraints(wxLayoutConstraints
* constraints
);
2547 Invokes the constraint-based layout algorithm or the sizer-based algorithm
2550 This function does not get called automatically when the window is resized
2551 because lots of windows deriving from wxWindow does not need this functionality.
2552 If you want to have Layout() called automatically, you should derive
2553 from wxPanel (see wxPanel::Layout).
2555 @see @ref overview_windowsizing
2557 virtual bool Layout();
2560 Determines whether the Layout() function will be called automatically
2561 when the window is resized. Please note that this only happens for the
2562 windows usually used to contain children, namely wxPanel and wxTopLevelWindow
2563 (and the classes deriving from them).
2565 This method is called implicitly by SetSizer() but if you use SetConstraints()
2566 you should call it manually or otherwise the window layout won't be correctly
2567 updated when its size changes.
2570 Set this to @true if you wish the Layout() function to be
2571 called automatically when the window is resized
2572 (really happens only if you derive from wxPanel or wxTopLevelWindow).
2574 @see SetConstraints()
2576 void SetAutoLayout(bool autoLayout
);
2583 @name Mouse functions
2588 Directs all mouse input to this window.
2589 Call ReleaseMouse() to release the capture.
2591 Note that wxWidgets maintains the stack of windows having captured the mouse
2592 and when the mouse is released the capture returns to the window which had had
2593 captured it previously and it is only really released if there were no previous
2594 window. In particular, this means that you must release the mouse as many times
2595 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
2597 Any application which captures the mouse in the beginning of some operation
2598 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
2599 the event. The event handler must not recapture mouse.
2601 @see ReleaseMouse(), wxMouseCaptureLostEvent
2603 void CaptureMouse();
2606 Returns the caret() associated with the window.
2608 wxCaret
* GetCaret() const;
2611 Return the cursor associated with this window.
2615 const wxCursor
& GetCursor() const;
2618 Returns @true if this window has the current mouse capture.
2620 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
2621 wxMouseCaptureChangedEvent
2623 virtual bool HasCapture() const;
2626 Releases mouse input captured with CaptureMouse().
2628 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
2629 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2631 void ReleaseMouse();
2634 Sets the caret() associated with the window.
2636 void SetCaret(wxCaret
* caret
);
2639 Sets the window's cursor. Notice that the window cursor also sets it for the
2640 children of the window implicitly.
2642 The @a cursor may be @c wxNullCursor in which case the window cursor will
2643 be reset back to default.
2646 Specifies the cursor that the window should normally display.
2648 @see ::wxSetCursor, wxCursor
2650 virtual bool SetCursor(const wxCursor
& cursor
);
2653 Moves the pointer to the given position on the window.
2655 @note This function is not supported under Mac because Apple Human
2656 Interface Guidelines forbid moving the mouse cursor programmatically.
2659 The new x position for the cursor.
2661 The new y position for the cursor.
2663 virtual void WarpPointer(int x
, int y
);
2671 @name Miscellaneous functions
2676 Does the window-specific updating after processing the update event.
2677 This function is called by UpdateWindowUI() in order to check return
2678 values in the wxUpdateUIEvent and act appropriately.
2679 For example, to allow frame and dialog title updating, wxWidgets
2680 implements this function as follows:
2683 // do the window-specific processing after processing the update event
2684 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
2686 if ( event.GetSetEnabled() )
2687 Enable(event.GetEnabled());
2689 if ( event.GetSetText() )
2691 if ( event.GetText() != GetTitle() )
2692 SetTitle(event.GetText());
2697 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
2700 Returns the platform-specific handle of the physical window.
2701 Cast it to an appropriate handle, such as @b HWND for Windows,
2702 @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
2704 virtual WXWidget
GetHandle() const;
2707 This method should be overridden to return @true if this window has
2708 multiple pages. All standard class with multiple pages such as
2709 wxNotebook, wxListbook and wxTreebook already override it to return @true
2710 and user-defined classes with similar behaviour should do it as well to
2711 allow the library to handle such windows appropriately.
2713 virtual bool HasMultiplePages() const;
2716 This function is (or should be, in case of custom controls) called during
2717 window creation to intelligently set up the window visual attributes, that is
2718 the font and the foreground and background colours.
2720 By "intelligently" the following is meant: by default, all windows use their
2721 own @ref GetClassDefaultAttributes() default attributes.
2722 However if some of the parents attributes are explicitly (that is, using
2723 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
2724 attribute hadn't been explicitly set for this window itself, then this
2725 window takes the same value as used by the parent.
2726 In addition, if the window overrides ShouldInheritColours() to return @false,
2727 the colours will not be changed no matter what and only the font might.
2729 This rather complicated logic is necessary in order to accommodate the
2730 different usage scenarios. The most common one is when all default attributes
2731 are used and in this case, nothing should be inherited as in modern GUIs
2732 different controls use different fonts (and colours) than their siblings so
2733 they can't inherit the same value from the parent. However it was also deemed
2734 desirable to allow to simply change the attributes of all children at once by
2735 just changing the font or colour of their common parent, hence in this case we
2736 do inherit the parents attributes.
2738 virtual void InheritAttributes();
2741 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
2742 to the dialog via validators.
2744 virtual void InitDialog();
2747 Returns @true if the window contents is double-buffered by the system, i.e. if
2748 any drawing done on the window is really done on a temporary backing surface
2749 and transferred to the screen all at once later.
2753 virtual bool IsDoubleBuffered() const;
2756 Returns @true if the window is retained, @false otherwise.
2758 @remarks Retained windows are only available on X platforms.
2760 virtual bool IsRetained() const;
2763 Returns @true if this window is intrinsically enabled, @false otherwise,
2764 i.e. if @ref Enable() Enable(@false) had been called. This method is
2765 mostly used for wxWidgets itself, user code should normally use
2766 IsEnabled() instead.
2768 bool IsThisEnabled() const;
2771 Returns @true if the given window is a top-level one. Currently all frames and
2772 dialogs are considered to be top-level windows (even if they have a parent
2775 virtual bool IsTopLevel() const;
2778 Disables all other windows in the application so that
2779 the user can only interact with this window.
2782 If @true, this call disables all other windows in the application so that
2783 the user can only interact with this window. If @false, the effect is
2786 virtual void MakeModal(bool modal
= true);
2789 This virtual function is normally only used internally, but
2790 sometimes an application may need it to implement functionality
2791 that should not be disabled by an application defining an OnIdle
2792 handler in a derived class.
2794 This function may be used to do delayed painting, for example,
2795 and most implementations call UpdateWindowUI()
2796 in order to send update events to the window in idle time.
2798 virtual void OnInternalIdle();
2801 Registers a system wide hotkey. Every time the user presses the hotkey
2802 registered here, this window will receive a hotkey event.
2804 It will receive the event even if the application is in the background
2805 and does not have the input focus because the user is working with some
2809 Numeric identifier of the hotkey. For applications this must be between 0
2810 and 0xBFFF. If this function is called from a shared DLL, it must be a
2811 system wide unique identifier between 0xC000 and 0xFFFF.
2812 This is a MSW specific detail.
2814 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
2815 or wxMOD_WIN specifying the modifier keys that have to be pressed along
2817 @param virtualKeyCode
2818 The virtual key code of the hotkey.
2820 @return @true if the hotkey was registered successfully. @false if some
2821 other application already registered a hotkey with this
2822 modifier/virtualKeyCode combination.
2824 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
2825 event. This function is currently only implemented
2826 under Windows. It is used in the Windows CE port for
2827 detecting hardware button presses.
2829 @see UnregisterHotKey()
2831 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
2832 int virtualKeyCode
);
2835 Unregisters a system wide hotkey.
2838 Numeric identifier of the hotkey. Must be the same id that was passed to
2841 @return @true if the hotkey was unregistered successfully, @false if the
2844 @remarks This function is currently only implemented under MSW.
2846 @see RegisterHotKey()
2848 virtual bool UnregisterHotKey(int hotkeyId
);
2851 This function sends one or more wxUpdateUIEvent to the window.
2852 The particular implementation depends on the window; for example a
2853 wxToolBar will send an update UI event for each toolbar button,
2854 and a wxFrame will send an update UI event for each menubar menu item.
2856 You can call this function from your application to ensure that your
2857 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
2858 are concerned). This may be necessary if you have called
2859 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
2860 the overhead that wxWidgets incurs by sending update UI events in idle time.
2861 @a flags should be a bitlist of one or more of the wxUpdateUI enumeration.
2863 If you are calling this function from an OnInternalIdle or OnIdle
2864 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
2865 this tells the window to only update the UI elements that need
2866 to be updated in idle time. Some windows update their elements
2867 only when necessary, for example when a menu is about to be shown.
2868 The following is an example of how to call UpdateWindowUI from
2872 void MyWindow::OnInternalIdle()
2874 if (wxUpdateUIEvent::CanUpdate(this))
2875 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
2879 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
2881 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
2886 // NOTE: static functions must have their own group or Doxygen will screw
2887 // up the ordering of the member groups
2890 @name Miscellaneous static functions
2895 Returns the default font and colours which are used by the control.
2897 This is useful if you want to use the same font or colour in your own control
2898 as in a standard control -- which is a much better idea than hard coding specific
2899 colours or fonts which might look completely out of place on the users
2900 system, especially if it uses themes.
2902 The @a variant parameter is only relevant under Mac currently and is
2903 ignore under other platforms. Under Mac, it will change the size of the
2904 returned font. See SetWindowVariant() for more about this.
2906 This static method is "overridden" in many derived classes and so calling,
2907 for example, wxButton::GetClassDefaultAttributes() will typically
2908 return the values appropriate for a button which will be normally different
2909 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
2911 The @c wxVisualAttributes structure has at least the fields
2912 @c font, @c colFg and @c colBg. All of them may be invalid
2913 if it was not possible to determine the default control appearance or,
2914 especially for the background colour, if the field doesn't make sense as is
2915 the case for @c colBg for the controls with themed background.
2917 @see InheritAttributes()
2919 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
2922 Finds the window or control which currently has the keyboard focus.
2924 @remarks Note that this is a static function, so it can be called without
2925 needing a wxWindow pointer.
2927 @see SetFocus(), HasFocus()
2929 static wxWindow
* FindFocus();
2932 Find the first window with the given @e id.
2934 If @a parent is @NULL, the search will start from all top-level frames
2935 and dialog boxes; if non-@NULL, the search will be limited to the given
2937 The search is recursive in both cases.
2941 static wxWindow
* FindWindowById(long id
, const wxWindow
* parent
= 0);
2944 Find a window by its label.
2946 Depending on the type of window, the label may be a window title
2947 or panel item label. If @a parent is @NULL, the search will start from all
2948 top-level frames and dialog boxes; if non-@NULL, the search will be
2949 limited to the given window hierarchy.
2950 The search is recursive in both cases.
2954 static wxWindow
* FindWindowByLabel(const wxString
& label
,
2955 const wxWindow
* parent
= 0);
2958 Find a window by its name (as given in a window constructor or Create()
2961 If @a parent is @NULL, the search will start from all top-level frames
2962 and dialog boxes; if non-@NULL, the search will be limited to the given
2965 The search is recursive in both cases. If no window with such name is found,
2966 FindWindowByLabel() is called.
2970 static wxWindow
* FindWindowByName(const wxString
& name
,
2971 const wxWindow
* parent
= 0);
2974 Returns the currently captured window.
2976 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
2977 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
2979 static wxWindow
* GetCapture();
2982 Create a new ID or range of IDs that are not currently in use.
2983 The IDs will be reserved until assigned to a wxWindow ID
2984 or unreserved with UnreserveControlId().
2986 See @ref overview_windowids for more information.
2989 The number of sequential IDs to reserve.
2991 @return Returns the ID or the first ID of the range, or wxID_NONE if the
2992 specified number of identifiers couldn't be allocated.
2994 @see UnreserveControlId(), wxIdManager,
2995 @ref overview_windowids
2997 static wxWindowID
NewControlId(int count
= 1);
3000 Unreserve an ID or range of IDs that was reserved by NewControlId().
3001 See @ref overview_windowids for more information.
3004 The starting ID of the range of IDs to unreserve.
3006 The number of sequential IDs to unreserve.
3008 @see NewControlId(), wxIdManager, @ref overview_windowids
3010 static void UnreserveControlId(wxWindowID id
, int count
= 1);
3019 Gets the size which best suits the window: for a control, it would be
3020 the minimal size which doesn't truncate the control, for a panel - the
3021 same size as it would have after a call to Fit().
3023 The default implementation of this function is designed for use in container
3024 windows, such as wxPanel, and works something like this:
3025 -# If the window has a sizer then it is used to calculate the best size.
3026 -# Otherwise if the window has layout constraints then those are used to
3027 calculate the best size.
3028 -# Otherwise if the window has children then the best size is set to be large
3029 enough to show all the children.
3030 -# Otherwise if there are no children then the window's minimal size will be
3031 used as its best size.
3032 -# Otherwise if there is no minimal size set, then the current size is used
3035 @see @ref overview_windowsizing
3037 virtual wxSize
DoGetBestSize() const;
3041 Sets the initial window size if none is given (i.e. at least one of the
3042 components of the size passed to ctor/Create() is wxDefaultCoord).
3043 @deprecated @todo provide deprecation description
3045 virtual void SetInitialBestSize(const wxSize
& size
);
3048 Generate wxWindowDestroyEvent for this window.
3050 This is called by the window itself when it is being destroyed and
3051 usually there is no need to call it but see wxWindowDestroyEvent for
3052 explanations of when you might want to do it.
3054 void SendDestroyEvent();
3059 // ============================================================================
3060 // Global functions/macros
3061 // ============================================================================
3063 /** @addtogroup group_funcmacro_misc */
3067 Find the deepest window at the mouse pointer position, returning the window
3068 and current pointer position in screen coordinates.
3070 @header{wx/window.h}
3072 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
3075 Gets the currently active window (implemented for MSW and GTK only
3076 currently, always returns @NULL in the other ports).
3078 @header{wx/window.h}
3080 wxWindow
* wxGetActiveWindow();
3083 Returns the first top level parent of the given window, or in other words,
3084 the frame or dialog containing it, or @NULL.
3086 @header{wx/window.h}
3088 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);