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 together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so
211 these two styles are automatically turned of if this one is used.
212 @style{wxWS_EX_PROCESS_IDLE}
213 This window should always process idle events, even if the mode set
214 by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
215 @style{wxWS_EX_PROCESS_UI_UPDATES}
216 This window should always process UI update events, even if the
217 mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED.
223 @see @ref overview_eventhandling "Event handling overview",
224 @ref overview_windowsizing "Window sizing overview"
226 class wxWindow
: public wxEvtHandler
235 Constructs a window, which can be a child of a frame, dialog or any other
239 Pointer to a parent window.
241 Window identifier. If wxID_ANY, will automatically create an identifier.
243 Window position. wxDefaultPosition indicates that wxWidgets
244 should generate a default position for the window.
245 If using the wxWindow class directly, supply an actual position.
247 Window size. wxDefaultSize indicates that wxWidgets should generate
248 a default size for the window. If no suitable size can be found, the
249 window will be sized to 20x20 pixels so that the window is visible but
250 obviously not correctly sized.
252 Window style. For generic window styles, please see wxWindow.
256 wxWindow(wxWindow
* parent
, wxWindowID id
,
257 const wxPoint
& pos
= wxDefaultPosition
,
258 const wxSize
& size
= wxDefaultSize
,
260 const wxString
& name
= wxPanelNameStr
);
265 Deletes all sub-windows, then deletes itself. Instead of using
266 the @b delete operator explicitly, you should normally use Destroy()
267 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
269 @see @ref overview_windowdeletion "Window Deletion Overview",
270 Destroy(), wxCloseEvent
275 This method may be overridden in the derived classes to return @false to
276 indicate that this control doesn't accept input at all (i.e. behaves like
277 e.g. wxStaticText) and so doesn't need focus.
279 @see AcceptsFocusFromKeyboard()
281 virtual bool AcceptsFocus() const;
284 This method may be overridden in the derived classes to return @false to
285 indicate that while this control can, in principle, have focus if the user
286 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
287 when using the keyboard.
289 virtual bool AcceptsFocusFromKeyboard() const;
292 Overridden to indicate wehter this window or one of its children accepts
293 focus. Usually it's the same as AcceptsFocus() but is overridden for
296 virtual bool AcceptsFocusRecursively() const;
299 Adds a child window. This is called automatically by window creation
300 functions so should not be required by the application programmer.
301 Notice that this function is mostly internal to wxWidgets and shouldn't be
302 called by the user code.
307 virtual void AddChild(wxWindow
* child
);
310 Call this function to force one or both scrollbars to be always shown, even if
311 the window is big enough to show its entire contents without scrolling.
316 Whether the horizontal scroll bar should always be visible.
318 Whether the vertical scroll bar should always be visible.
320 @remarks This function is currently only implemented under Mac/Carbon.
322 virtual void AlwaysShowScrollbars(bool hflag
= true, bool vflag
= true);
325 Sets the cached best size value.
327 void CacheBestSize(const wxSize
& size
) const;
330 Returns @true if the system supports transparent windows and calling
331 SetTransparent() may succeed. If this function returns @false, transparent
332 windows are definitely not supported by the current system.
334 virtual bool CanSetTransparent();
337 Directs all mouse input to this window.
338 Call ReleaseMouse() to release the capture.
340 Note that wxWidgets maintains the stack of windows having captured the mouse
341 and when the mouse is released the capture returns to the window which had had
342 captured it previously and it is only really released if there were no previous
343 window. In particular, this means that you must release the mouse as many times
344 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
346 Any application which captures the mouse in the beginning of some operation
347 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
348 the event. The event handler must not recapture mouse.
350 @see ReleaseMouse(), wxMouseCaptureLostEvent
355 A synonym for Centre().
357 void Center(int dir
= wxBOTH
);
360 A synonym for CentreOnParent().
362 void CenterOnParent(int dir
= wxBOTH
);
368 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
369 or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
370 if you want to center the window on the entire screen and not on its
373 @remarks If the window is a top level one (i.e. doesn't have a parent),
374 it will be centered relative to the screen anyhow.
378 void Centre(int direction
= wxBOTH
);
381 Centres the window on its parent. This is a more readable synonym for Centre().
384 Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
387 @remarks This methods provides for a way to center top level windows over
388 their parents instead of the entire screen. If there
389 is no parent or if the window is not a top level
390 window, then behaviour is the same as Centre().
392 @see wxTopLevelWindow::CentreOnScreen
394 void CentreOnParent(int direction
= wxBOTH
);
397 Clears the window by filling it with the current background colour. Does not
398 cause an erase background event to be generated.
400 virtual void ClearBackground();
403 Converts to screen coordinates from coordinates relative to this window.
406 A pointer to a integer value for the x coordinate. Pass the client
407 coordinate in, and a screen coordinate will be passed out.
409 A pointer to a integer value for the y coordinate. Pass the client
410 coordinate in, and a screen coordinate will be passed out.
413 In place of a single overloaded method name, wxPython implements the following methods:
414 - ClientToScreen(point): Accepts and returns a wxPoint
415 - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
418 void ClientToScreen(int* x
, int* y
) const;
421 Converts to screen coordinates from coordinates relative to this window.
424 The client position for the second form of the function.
426 wxPoint
ClientToScreen(const wxPoint
& pt
) const;
429 Converts client area size @a size to corresponding window size.
431 In other words, the returned value is what would GetSize() return if this
432 window had client area of given size. Components with wxDefaultCoord
433 value are left unchanged. Note that the conversion is not always
434 exact, it assumes that non-client area doesn't change and so doesn't
435 take into account things like menu bar (un)wrapping or (dis)appearance
440 @see WindowToClientSize()
442 virtual wxSize
ClientToWindowSize(const wxSize
& size
) const;
445 Converts window size @a size to corresponding client area size
446 In other words, the returned value is what would GetClientSize() return if
447 this window had given window size. Components with wxDefaultCoord value
450 Note that the conversion is not always exact, it assumes that
451 non-client area doesn't change and so doesn't take into account things
452 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
456 @see ClientToWindowSize()
458 virtual wxSize
WindowToClientSize(const wxSize
& size
) const;
461 This function simply generates a wxCloseEvent whose handler usually tries
462 to close the window. It doesn't close the window itself, however.
465 @false if the window's close handler should be able to veto the destruction
466 of this window, @true if it cannot.
468 @remarks Close calls the close handler for the window, providing an
469 opportunity for the window to choose whether to destroy
470 the window. Usually it is only used with the top level
471 windows (wxFrame and wxDialog classes) as the others
472 are not supposed to have any special OnClose() logic.
473 The close handler should check whether the window is being deleted
474 forcibly, using wxCloseEvent::CanVeto, in which case it should
475 destroy the window using wxWindow::Destroy.
476 Note that calling Close does not guarantee that the window will
477 be destroyed; but it provides a way to simulate a manual close
478 of a window, which may or may not be implemented by destroying
479 the window. The default implementation of wxDialog::OnCloseWindow
480 does not necessarily delete the dialog, since it will simply
481 simulate an wxID_CANCEL event which is handled by the appropriate
482 button event handler and may do anything at all.
483 To guarantee that the window will be destroyed, call
484 wxWindow::Destroy instead
486 @see @ref overview_windowdeletion "Window Deletion Overview",
487 Destroy(), wxCloseEvent
489 bool Close(bool force
= false);
493 Converts a point or size from dialog units to pixels.
495 For the x dimension, the dialog units are multiplied by the average character
496 width and then divided by 4.
497 For the y dimension, the dialog units are multiplied by the average character
498 height and then divided by 8.
500 @remarks Dialog units are used for maintaining a dialog's proportions
501 even if the font changes.
502 You can also use these functions programmatically.
503 A convenience macro is defined:
505 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
508 @see ConvertPixelsToDialog()
510 wxPoint
ConvertDialogToPixels(const wxPoint
& pt
);
511 wxSize
ConvertDialogToPixels(const wxSize
& sz
);
516 Converts a point or size from pixels to dialog units.
518 For the x dimension, the pixels are multiplied by 4 and then divided by the
519 average character width.
520 For the y dimension, the pixels are multiplied by 8 and then divided by the
521 average character height.
523 @remarks Dialog units are used for maintaining a dialog's proportions
524 even if the font changes.
526 @see ConvertDialogToPixels()
528 wxPoint
ConvertPixelsToDialog(const wxPoint
& pt
);
529 wxSize
ConvertPixelsToDialog(const wxSize
& sz
);
533 Destroys the window safely. Use this function instead of the delete operator,
534 since different window classes can be destroyed differently. Frames and dialogs
535 are not destroyed immediately when this function is called -- they are added
536 to a list of windows to be deleted on idle time, when all the window's events
537 have been processed. This prevents problems with events being sent to
538 non-existent windows.
540 @return @true if the window has either been successfully deleted, or it
541 has been added to the list of windows pending real deletion.
543 virtual bool Destroy();
546 Destroys all children of a window. Called automatically by the destructor.
548 bool DestroyChildren();
551 Returns true if this window is in process of being destroyed.
553 The top level windows are not deleted immediately but are rather
554 scheduled for later destruction to give them time to process any
555 pending messages, see Destroy() description.
557 This function returns @true if this window, or one of its parent
558 windows, is scheduled for destruction and can be useful to avoid
559 manipulating it as it's usually useless to do something with a window
560 which is on the point of disappearing anyhow.
562 bool IsBeingDeleted() const;
565 Disables the window. Same as @ref Enable() Enable(@false).
567 @return Returns @true if the window has been disabled, @false if it had
568 been already disabled before the call to this function.
573 Does the window-specific updating after processing the update event.
574 This function is called by UpdateWindowUI() in order to check return
575 values in the wxUpdateUIEvent and act appropriately.
576 For example, to allow frame and dialog title updating, wxWidgets
577 implements this function as follows:
580 // do the window-specific processing after processing the update event
581 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
583 if ( event.GetSetEnabled() )
584 Enable(event.GetEnabled());
586 if ( event.GetSetText() )
588 if ( event.GetText() != GetTitle() )
589 SetTitle(event.GetText());
594 virtual void DoUpdateWindowUI(wxUpdateUIEvent
& event
);
597 Enables or disables eligibility for drop file events (OnDropFiles).
600 If @true, the window is eligible for drop file events.
601 If @false, the window will not accept drop file events.
603 @remarks Windows only.
605 virtual void DragAcceptFiles(bool accept
);
608 Enable or disable the window for user input. Note that when a parent window is
609 disabled, all of its children are disabled as well and they are reenabled again
613 If @true, enables the window for input. If @false, disables the window.
615 @return Returns @true if the window has been enabled or disabled, @false
616 if nothing was done, i.e. if the window had already
617 been in the specified state.
619 @see IsEnabled(), Disable(), wxRadioBox::Enable
621 virtual bool Enable(bool enable
= true);
624 Finds the window or control which currently has the keyboard focus.
626 @remarks Note that this is a static function, so it can be called without
627 needing a wxWindow pointer.
629 @see SetFocus(), HasFocus()
631 static wxWindow
* FindFocus();
634 Find a child of this window, by @a id.
635 May return @a this if it matches itself.
637 wxWindow
* FindWindow(long id
) const;
640 Find a child of this window, by name.
641 May return @a this if it matches itself.
643 wxWindow
* FindWindow(const wxString
& name
) const;
646 Find the first window with the given @e id.
648 If @a parent is @NULL, the search will start from all top-level frames
649 and dialog boxes; if non-@NULL, the search will be limited to the given
651 The search is recursive in both cases.
655 static wxWindow
* FindWindowById(long id
, wxWindow
* parent
= NULL
);
658 Find a window by its label.
660 Depending on the type of window, the label may be a window title
661 or panel item label. If @a parent is @NULL, the search will start from all
662 top-level frames and dialog boxes; if non-@NULL, the search will be
663 limited to the given window hierarchy.
664 The search is recursive in both cases.
668 static wxWindow
* FindWindowByLabel(const wxString
& label
,
669 wxWindow
* parent
= NULL
);
672 Find a window by its name (as given in a window constructor or @b Create
675 If @a parent is @NULL, the search will start from all top-level frames
676 and dialog boxes; if non-@NULL, the search will be limited to the given
679 The search is recursive in both cases. If no window with such name is found,
680 FindWindowByLabel() is called.
684 static wxWindow
* FindWindowByName(const wxString
& name
,
685 wxWindow
* parent
= NULL
);
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 Freezes the window or, in other words, prevents any updates from taking
719 place on screen, the window is not redrawn at all.
721 Thaw() must be called to reenable window redrawing. Calls to these two
722 functions may be nested but to ensure that the window is properly
723 repainted again, you must thaw it exactly as many times as you froze it.
725 If the window has any children, they are recursively frozen too.
727 This method is useful for visual appearance optimization (for example,
728 it is a good idea to use it before doing many large text insertions in
729 a row into a wxTextCtrl under wxGTK) but is not implemented on all
730 platforms nor for all controls so it is mostly just a hint to wxWidgets
731 and not a mandatory directive.
733 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
738 Gets the accelerator table for this window. See wxAcceleratorTable.
740 wxAcceleratorTable
* GetAcceleratorTable();
743 Returns the accessible object for this window, if any.
744 See also wxAccessible.
746 wxAccessible
* GetAccessible();
749 Returns the background colour of the window.
751 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
753 wxColour
GetBackgroundColour() const;
756 Returns the background style of the window.
757 The background style can be one of the wxBackgroundStyle.
759 @see SetBackgroundColour(), GetForegroundColour(),
760 SetBackgroundStyle(), SetTransparent()
762 virtual wxBackgroundStyle
GetBackgroundStyle() const;
765 This functions returns the best acceptable minimal size for the window.
767 For example, for a static control, it will be the minimal size such that the
768 control label is not truncated. For windows containing subwindows (typically
769 wxPanel), the size returned by this function will be the same as the size
770 the window would have had after calling Fit().
772 wxSize
GetBestSize() const;
775 Returns the currently captured window.
777 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
778 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
780 static wxWindow
* GetCapture();
783 Returns the caret() associated with the window.
785 wxCaret
* GetCaret() const;
788 Returns the character height for this window.
790 virtual int GetCharHeight() const;
793 Returns the average character width for this window.
795 virtual int GetCharWidth() const;
799 Returns a reference to the list of the window's children. @c wxWindowList
800 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
802 wxWindowList
& GetChildren();
803 const wxWindowList
& GetChildren() const;
807 Returns the default font and colours which are used by the control.
809 This is useful if you want to use the same font or colour in your own control
810 as in a standard control -- which is a much better idea than hard coding specific
811 colours or fonts which might look completely out of place on the users
812 system, especially if it uses themes.
814 The @a variant parameter is only relevant under Mac currently and is
815 ignore under other platforms. Under Mac, it will change the size of the
816 returned font. See SetWindowVariant() for more about this.
818 This static method is "overridden" in many derived classes and so calling,
819 for example, wxButton::GetClassDefaultAttributes() will typically
820 return the values appropriate for a button which will be normally different
821 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
823 The @c wxVisualAttributes structure has at least the fields
824 @c font, @c colFg and @c colBg. All of them may be invalid
825 if it was not possible to determine the default control appearance or,
826 especially for the background colour, if the field doesn't make sense as is
827 the case for @c colBg for the controls with themed background.
829 @see InheritAttributes()
831 static wxVisualAttributes
GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
835 Returns the size of the window 'client area' in pixels.
837 The client area is the area which may be drawn on by the programmer,
838 excluding title bar, border, scrollbars, etc.
839 Note that if this window is a top-level one and it is currently minimized, the
840 return size is empty (both width and height are 0).
842 @see GetSize(), GetVirtualSize()
844 void GetClientSize(int* width
, int* height
) const;
845 wxSize
GetClientSize() const;
849 Returns a pointer to the window's layout constraints, or @NULL if there are none.
851 wxLayoutConstraints
* GetConstraints() const;
854 Return the sizer that this window is a member of, if any, otherwise @NULL.
856 wxSizer
* GetContainingSizer() const;
859 Return the cursor associated with this window.
863 const wxCursor
& GetCursor() const;
866 Currently this is the same as calling
867 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
869 One advantage of using this function compared to the static version is that
870 the call is automatically dispatched to the correct class (as usual with
871 virtual functions) and you don't have to specify the class name explicitly.
873 The other one is that in the future this function could return different
874 results, for example it might return a different font for an "Ok" button
875 than for a generic button if the users GUI is configured to show such buttons
876 in bold font. Of course, the down side is that it is impossible to call this
877 function without actually having an object to apply it to whereas the static
878 version can be used without having to create an object first.
880 virtual wxVisualAttributes
GetDefaultAttributes() const;
883 Returns the associated drop target, which may be @NULL.
885 @see SetDropTarget(), @ref overview_dnd
887 virtual wxDropTarget
* GetDropTarget() const;
890 Merges the window's best size into the min size and returns the result.
891 This is the value used by sizers to determine the appropriate
892 ammount of space to allocate for the widget.
894 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
896 wxSize
GetEffectiveMinSize() const;
899 Returns the event handler for this window.
900 By default, the window is its own event handler.
902 @see SetEventHandler(), PushEventHandler(),
903 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
905 wxEvtHandler
* GetEventHandler() const;
908 Returns the extra style bits for the window.
910 long GetExtraStyle() const;
913 Returns the font for this window.
917 wxFont
GetFont() const;
920 Returns the foreground colour of the window.
922 @remarks The interpretation of foreground colour is open to
923 interpretation according to the window class; it may be
924 the text colour or other colour, or it may not be used at all.
926 @see SetForegroundColour(), SetBackgroundColour(),
927 GetBackgroundColour()
929 wxColour
GetForegroundColour() const;
932 Returns the grandparent of a window, or @NULL if there isn't one.
934 wxWindow
* GetGrandParent() const;
937 Returns the platform-specific handle of the physical window.
938 Cast it to an appropriate handle, such as @b HWND for Windows,
939 @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
941 virtual WXWidget
GetHandle() const;
944 Gets the help text to be used as context-sensitive help for this window.
945 Note that the text is actually stored by the current wxHelpProvider
946 implementation, and not in the window object itself.
948 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
950 wxString
GetHelpText() const;
953 Gets the help text to be used as context-sensitive help for this window.
954 This method should be overridden if the help message depends on the position
955 inside the window, otherwise GetHelpText() can be used.
958 Coordinates of the mouse at the moment of help event emission.
960 Help event origin, see also wxHelpEvent::GetOrigin.
962 virtual wxString
GetHelpTextAtPoint(const wxPoint
& point
,
963 wxHelpEvent::Origin origin
) const;
966 Returns the identifier of the window.
968 @remarks Each window has an integer identifier. If the application
969 has not provided one (or the default wxID_ANY) an unique
970 identifier with a negative value will be generated.
972 @see SetId(), @ref overview_windowids
974 wxWindowID
GetId() const;
977 Generic way of getting a label from any window, for
978 identification purposes.
980 @remarks The interpretation of this function differs from class to class.
981 For frames and dialogs, the value returned is the
982 title. For buttons or static text controls, it is the
983 button text. This function can be useful for
984 meta-programs (such as testing tools or special-needs
985 access programs) which need to identify windows by name.
987 virtual wxString
GetLabel() const;
990 Returns the maximum size of window's client area.
992 This is an indication to the sizer layout mechanism that this is the maximum
993 possible size as well as the upper bound on window's size settable using
998 virtual wxSize
GetMaxClientSize() const;
1001 Returns the maximum size of the window.
1003 This is an indication to the sizer layout mechanism that this is the maximum
1004 possible size as well as the upper bound on window's size settable using SetSize().
1006 @see GetMaxClientSize()
1008 virtual wxSize
GetMaxSize() const;
1011 Returns the minimum size of window's client area, an indication to the sizer
1012 layout mechanism that this is the minimum required size of its client area.
1014 It normally just returns the value set by SetMinClientSize(), but it can be
1015 overridden to do the calculation on demand.
1019 virtual wxSize
GetMinClientSize() const;
1022 Returns the minimum size of the window, an indication to the sizer layout
1023 mechanism that this is the minimum required size.
1025 This method normally just returns the value set by SetMinSize(), but it
1026 can be overridden to do the calculation on demand.
1028 @see GetMinClientSize()
1030 virtual wxSize
GetMinSize() const;
1033 Returns the window's name.
1035 @remarks This name is not guaranteed to be unique; it is up to the
1036 programmer to supply an appropriate name in the window
1037 constructor or via SetName().
1041 virtual wxString
GetName() const;
1044 Returns the next window after this one among the parent children or @NULL
1045 if this window is the last child.
1049 @see GetPrevSibling()
1051 wxWindow
* GetNextSibling() const;
1054 Returns the parent of the window, or @NULL if there is no parent.
1056 wxWindow
* GetParent() const;
1059 This function shows a popup menu at the given position in this window and
1060 returns the selected id. It can be more convenient than the general purpose
1061 PopupMenu() function for simple menus proposing a choice in a list of
1062 strings to the user.
1067 The position at which to show the menu in client coordinates
1069 @return The selected menu item id or wxID_NONE if none selected or an
1072 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, const wxPoint
& pos
);
1075 See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload.
1076 This overload differs only because it takes two integers for the
1077 menu position instead of a wxPoint.
1079 int GetPopupMenuSelectionFromUser(wxMenu
& menu
, int x
, int y
);
1082 This gets the position of the window in pixels, relative to the parent window
1083 for the child windows or relative to the display origin for the top level windows.
1086 Receives the x position of the window if non-@NULL.
1088 Receives the y position of the window if non-@NULL.
1090 @see GetScreenPosition()
1092 void GetPosition(int* x
, int* y
) const;
1095 This gets the position of the window in pixels, relative to the parent window
1096 for the child windows or relative to the display origin for the top level windows.
1098 @see GetScreenPosition()
1100 wxPoint
GetPosition() const;
1103 Returns the previous window before this one among the parent children or @c
1104 @NULL if this window is the first child.
1108 @see GetNextSibling()
1110 wxWindow
* GetPrevSibling() const;
1113 Returns the position and size of the window as a wxRect object.
1115 @see GetScreenRect()
1117 wxRect
GetRect() const;
1120 Returns the window position in screen coordinates, whether the window is a
1121 child window or a top level one.
1124 Receives the x position of the window on the screen if non-@NULL.
1126 Receives the y position of the window on the screen if non-@NULL.
1130 void GetScreenPosition(int* x
, int* y
) const;
1133 Returns the window position in screen coordinates, whether the window is a
1134 child window or a top level one.
1138 wxPoint
GetScreenPosition() const;
1141 Returns the position and size of the window on the screen as a wxRect object.
1145 wxRect
GetScreenRect() const;
1148 Returns the built-in scrollbar position.
1150 @see See SetScrollbar()
1152 virtual int GetScrollPos(int orientation
) const;
1155 Returns the built-in scrollbar range.
1159 virtual int GetScrollRange(int orientation
) const;
1162 Returns the built-in scrollbar thumb size.
1166 virtual int GetScrollThumb(int orientation
) const;
1169 Returns the size of the entire window in pixels, including title bar, border,
1172 Note that if this window is a top-level one and it is currently minimized, the
1173 returned size is the restored window size, not the size of the window icon.
1176 Receives the window width.
1178 Receives the window height.
1180 @see GetClientSize(), GetVirtualSize()
1182 void GetSize(int* width
, int* height
) const;
1185 See the GetSize(int*,int*) overload for more info.
1187 wxSize
GetSize() const;
1190 Return the sizer associated with the window by a previous call to
1191 SetSizer() or @NULL.
1193 wxSizer
* GetSizer() const;
1196 Gets the dimensions of the string as it would be drawn on the
1197 window with the currently selected font.
1199 The text extent is returned in @a w and @a h pointers.
1202 String whose extent is to be measured.
1204 Return value for width.
1206 Return value for height.
1208 Return value for descent (optional).
1209 @param externalLeading
1210 Return value for external leading (optional).
1212 Font to use instead of the current window font (optional).
1214 virtual void GetTextExtent(const wxString
& string
, int* w
, int* h
,
1215 int* descent
= NULL
,
1216 int* externalLeading
= NULL
,
1217 const wxFont
* font
= NULL
) const;
1220 Gets the dimensions of the string as it would be drawn on the
1221 window with the currently selected font.
1223 wxSize
GetTextExtent(const wxString
& string
) const;
1226 Get the associated tooltip or @NULL if none.
1228 wxToolTip
* GetToolTip() const;
1231 Returns the region specifying which parts of the window have been damaged.
1232 Should only be called within an wxPaintEvent handler.
1234 @see wxRegion, wxRegionIterator
1236 const wxRegion
& GetUpdateRegion() const;
1239 Returns a pointer to the current validator for the window, or @NULL if
1242 virtual wxValidator
* GetValidator();
1246 This gets the virtual size of the window in pixels.
1247 By default it returns the client size of the window, but after a call to
1248 SetVirtualSize() it will return the size set with that method.
1250 wxSize
GetVirtualSize() const;
1253 Like the other GetVirtualSize() overload but uses pointers instead.
1256 Receives the window virtual width.
1258 Receives the window virtual height.
1260 void GetVirtualSize(int* width
, int* height
) const;
1264 Returns the size of the left/right and top/bottom borders of this window in x
1265 and y components of the result respectively.
1267 virtual wxSize
GetWindowBorderSize() const;
1270 Gets the window style that was passed to the constructor or @b Create
1271 method. @b GetWindowStyle() is another name for the same function.
1273 virtual long GetWindowStyleFlag() const;
1276 Returns the value previously passed to SetWindowVariant().
1278 wxWindowVariant
GetWindowVariant() const;
1281 This function will generate the appropriate call to
1282 Navigate() if the key event is one normally used for
1283 keyboard navigation and return @true in this case.
1285 @return Returns @true if the key pressed was for navigation and was
1286 handled, @false otherwise.
1290 bool HandleAsNavigationKey(const wxKeyEvent
& event
);
1295 GetEventHandler()->SafelyProcessEvent(event);
1298 bool HandleWindowEvent(wxEvent
& event
) const;
1301 Returns @true if this window has the current mouse capture.
1303 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
1304 wxMouseCaptureChangedEvent
1306 virtual bool HasCapture() const;
1309 Returns @true if the window has the given @a exFlag bit set in its
1312 @see SetExtraStyle()
1314 bool HasExtraStyle(int exFlag
) const;
1317 Returns @true if the window has the given @a flag bit set.
1319 bool HasFlag(int flag
) const;
1322 Returns @true if the window (or in case of composite controls, its main
1323 child window) has focus.
1327 virtual bool HasFocus() const;
1330 This method should be overridden to return @true if this window has
1331 multiple pages. All standard class with multiple pages such as
1332 wxNotebook, wxListbook and wxTreebook already override it to return @true
1333 and user-defined classes with similar behaviour should do it as well to
1334 allow the library to handle such windows appropriately.
1336 virtual bool HasMultiplePages() const;
1339 Returns @true if this window has a scroll bar for this orientation.
1342 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
1344 bool HasScrollbar(int orient
) const;
1347 Returns @true if this window background is transparent (as, for example,
1348 for wxStaticText) and should show the parent window background.
1350 This method is mostly used internally by the library itself and you normally
1351 shouldn't have to call it. You may, however, have to override it in your
1352 wxWindow-derived class to ensure that background is painted correctly.
1354 virtual bool HasTransparentBackground();
1357 Equivalent to calling wxWindow::Show(@false).
1362 This function hides a window, like Hide(), but using a special visual
1365 The parameters of this function are the same as for ShowWithEffect(),
1366 please see their description there.
1370 virtual bool HideWithEffect(wxShowEffect effect
,
1371 unsigned int timeout
= 0);
1374 This function is (or should be, in case of custom controls) called during
1375 window creation to intelligently set up the window visual attributes, that is
1376 the font and the foreground and background colours.
1378 By "intelligently" the following is meant: by default, all windows use their
1379 own @ref GetClassDefaultAttributes() default attributes.
1380 However if some of the parents attributes are explicitly (that is, using
1381 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
1382 attribute hadn't been explicitly set for this window itself, then this
1383 window takes the same value as used by the parent.
1384 In addition, if the window overrides ShouldInheritColours() to return @false,
1385 the colours will not be changed no matter what and only the font might.
1387 This rather complicated logic is necessary in order to accommodate the
1388 different usage scenarios. The most common one is when all default attributes
1389 are used and in this case, nothing should be inherited as in modern GUIs
1390 different controls use different fonts (and colours) than their siblings so
1391 they can't inherit the same value from the parent. However it was also deemed
1392 desirable to allow to simply change the attributes of all children at once by
1393 just changing the font or colour of their common parent, hence in this case we
1394 do inherit the parents attributes.
1396 virtual void InheritAttributes();
1399 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
1400 to the dialog via validators.
1402 virtual void InitDialog();
1405 Resets the cached best size value so it will be recalculated the next time it
1408 void InvalidateBestSize();
1411 Returns @true if the window contents is double-buffered by the system, i.e. if
1412 any drawing done on the window is really done on a temporary backing surface
1413 and transferred to the screen all at once later.
1417 virtual bool IsDoubleBuffered() const;
1420 Returns @true if the window is enabled, i.e. if it accepts user input,
1423 Notice that this method can return @false even if this window itself hadn't
1424 been explicitly disabled when one of its parent windows is disabled.
1425 To get the intrinsic status of this window, use IsThisEnabled()
1429 bool IsEnabled() const;
1433 Returns @true if the given point or rectangle area has been exposed since the
1434 last repaint. Call this in an paint event handler to optimize redrawing by
1435 only redrawing those areas, which have been exposed.
1437 bool IsExposed(int x
, int y
) const;
1438 const bool IsExposed(wxPoint amp
;pt
) const;
1439 const bool IsExposed(int x
, int y
, int w
, int h
) const;
1440 const bool IsExposed(wxRect amp
;rect
) const;
1444 Returns @true if the window is currently frozen by a call to Freeze().
1446 @see Freeze(), Thaw()
1448 bool IsFrozen() const;
1451 Returns @true if the window is retained, @false otherwise.
1453 @remarks Retained windows are only available on X platforms.
1455 virtual bool IsRetained() const;
1458 Return whether a scrollbar is always shown.
1461 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
1463 @see AlwaysShowScrollbars()
1465 virtual bool IsScrollbarAlwaysShown(int orient
) const;
1468 Returns @true if the window is shown, @false if it has been hidden.
1470 @see IsShownOnScreen()
1472 virtual bool IsShown() const;
1475 Returns @true if the window is physically visible on the screen, i.e. it
1476 is shown and all its parents up to the toplevel window are shown as well.
1480 virtual bool IsShownOnScreen() const;
1483 Returns @true if this window is intrinsically enabled, @false otherwise,
1484 i.e. if @ref Enable() Enable(@false) had been called. This method is
1485 mostly used for wxWidgets itself, user code should normally use
1486 IsEnabled() instead.
1488 bool IsThisEnabled() const;
1491 Returns @true if the given window is a top-level one. Currently all frames and
1492 dialogs are considered to be top-level windows (even if they have a parent
1495 virtual bool IsTopLevel() const;
1498 Invokes the constraint-based layout algorithm or the sizer-based algorithm
1501 See SetAutoLayout(): when auto layout is on, this function gets called automatically
1502 when the window is resized.
1504 @see @ref overview_windowsizing
1506 virtual bool Layout();
1509 Lowers the window to the bottom of the window hierarchy (Z-order).
1513 virtual void Lower();
1516 Disables all other windows in the application so that
1517 the user can only interact with this window.
1520 If @true, this call disables all other windows in the application so that
1521 the user can only interact with this window. If @false, the effect is
1524 virtual void MakeModal(bool modal
= true);
1527 Moves the window to the given position.
1530 Required x position.
1532 Required y position.
1534 See SetSize() for more info about this parameter.
1536 @remarks Implementations of SetSize can also implicitly implement the
1537 Move() function, which is defined in the base wxWindow class as the call:
1539 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1544 void Move(int x
, int y
, int flags
= wxSIZE_USE_EXISTING
);
1547 Moves the window to the given position.
1550 wxPoint object representing the position.
1552 See SetSize() for more info about this parameter.
1554 @remarks Implementations of SetSize() can also implicitly implement the
1555 Move() function, which is defined in the base wxWindow class as the call:
1557 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1562 void Move(const wxPoint
& pt
, int flags
= wxSIZE_USE_EXISTING
);
1565 Moves this window in the tab navigation order after the specified @e win.
1566 This means that when the user presses @c TAB key on that other window,
1567 the focus switches to this window.
1569 Default tab order is the same as creation order, this function and
1570 MoveBeforeInTabOrder() allow to change
1571 it after creating all the windows.
1574 A sibling of this window which should precede it in tab order,
1577 void MoveAfterInTabOrder(wxWindow
* win
);
1580 Same as MoveAfterInTabOrder() except that it inserts this window just
1581 before @a win instead of putting it right after it.
1583 void MoveBeforeInTabOrder(wxWindow
* win
);
1586 Performs a keyboard navigation action starting from this window.
1587 This method is equivalent to calling NavigateIn() method on the
1591 A combination of wxNavigationKeyEvent::IsForward and
1592 wxNavigationKeyEvent::WinChange.
1594 @return Returns @true if the focus was moved to another window or @false
1597 @remarks You may wish to call this from a text control custom keypress
1598 handler to do the default navigation behaviour for the
1599 tab key, since the standard default behaviour for a
1600 multiline text control with the wxTE_PROCESS_TAB style
1601 is to insert a tab and not navigate to the next
1602 control. See also wxNavigationKeyEvent and
1603 HandleAsNavigationKey.
1605 bool Navigate(int flags
= IsForward
);
1608 Performs a keyboard navigation action inside this window.
1609 See Navigate() for more information.
1611 bool NavigateIn(int flags
= IsForward
);
1614 Create a new ID or range of IDs that are not currently in use.
1615 The IDs will be reserved until assigned to a wxWindow ID
1616 or unreserved with UnreserveControlId().
1618 See @ref overview_windowids for more information.
1621 The number of sequential IDs to reserve.
1623 @return Returns the ID or the first ID of the range, or wxID_NONE if the
1624 specified number of identifiers couldn't be allocated.
1626 @see UnreserveControlId(), wxIdManager,
1627 @ref overview_windowids
1629 static wxWindowID
NewControlId(int count
= 1);
1632 This virtual function is normally only used internally, but
1633 sometimes an application may need it to implement functionality
1634 that should not be disabled by an application defining an OnIdle
1635 handler in a derived class.
1637 This function may be used to do delayed painting, for example,
1638 and most implementations call UpdateWindowUI()
1639 in order to send update events to the window in idle time.
1641 virtual void OnInternalIdle();
1644 Same as #ScrollLines (-1).
1649 Same as #ScrollLines (1).
1654 Same as #ScrollPages (-1).
1659 Same as #ScrollPages (1).
1665 Removes and returns the top-most event handler on the event handler stack.
1667 @param deleteHandler
1668 If this is @true, the handler will be deleted after it is removed.
1669 The default value is @false.
1671 @see SetEventHandler(), GetEventHandler(),
1672 PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1674 wxEvtHandler
* PopEventHandler(bool deleteHandler
= false);
1678 Pops up the given menu at the specified coordinates, relative to this
1679 window, and returns control when the user has dismissed the menu.
1681 If a menu item is selected, the corresponding menu event is generated and will be
1682 processed as usually. If the coordinates are not specified, current mouse
1683 cursor position is used.
1685 @a menu is the menu to pop up.
1687 The position where the menu will appear can be specified either as a
1688 wxPoint @a pos or by two integers (@a x and @a y).
1690 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
1691 ensure that the menu items are in the correct state.
1692 The menu does not get deleted by the window.
1693 It is recommended to not explicitly specify coordinates when
1694 calling PopupMenu in response to mouse click, because some of
1695 the ports (namely, wxGTK) can do a better job of positioning
1696 the menu in that case.
1700 bool PopupMenu(wxMenu
* menu
,
1701 const wxPoint
& pos
= wxDefaultPosition
);
1702 bool PopupMenu(wxMenu
* menu
, int x
, int y
);
1706 Posts a size event to the window.
1708 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
1710 void PostSizeEvent();
1713 Posts a size event to the parent of this window.
1715 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
1718 void PostSizeEventToParent();
1721 Pushes this event handler onto the event stack for the window.
1724 Specifies the handler to be pushed.
1726 @remarks An event handler is an object that is capable of processing the
1727 events sent to a window. By default, the window is its
1728 own event handler, but an application may wish to
1729 substitute another, for example to allow central
1730 implementation of event-handling for a variety of
1731 different window classes.
1732 wxWindow::PushEventHandler allows an application to set up a
1733 chain of event handlers, where an event not handled by one event
1734 handler is handed to the next one in the chain.
1735 Use wxWindow::PopEventHandler to remove the event handler.
1737 @see SetEventHandler(), GetEventHandler(),
1738 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
1740 void PushEventHandler(wxEvtHandler
* handler
);
1743 Raises the window to the top of the window hierarchy (Z-order).
1744 In current version of wxWidgets this works both for managed and child windows.
1748 virtual void Raise();
1751 Causes this window, and all of its children recursively (except under wxGTK1
1752 where this is not implemented), to be repainted. Note that repainting doesn't
1753 happen immediately but only during the next event loop iteration, if you need
1754 to update the window immediately you should use Update() instead.
1756 @param eraseBackground
1757 If @true, the background will be erased.
1759 If non-@NULL, only the given rectangle will be treated as damaged.
1763 virtual void Refresh(bool eraseBackground
= true,
1764 const wxRect
* rect
= NULL
);
1767 Redraws the contents of the given rectangle: only the area inside it will be
1770 This is the same as Refresh() but has a nicer syntax as it can be called
1771 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1773 void RefreshRect(const wxRect
& rect
, bool eraseBackground
= true);
1776 Registers a system wide hotkey. Every time the user presses the hotkey
1777 registered here, this window will receive a hotkey event.
1779 It will receive the event even if the application is in the background
1780 and does not have the input focus because the user is working with some
1784 Numeric identifier of the hotkey. For applications this must be between 0
1785 and 0xBFFF. If this function is called from a shared DLL, it must be a
1786 system wide unique identifier between 0xC000 and 0xFFFF.
1787 This is a MSW specific detail.
1789 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
1790 or wxMOD_WIN specifying the modifier keys that have to be pressed along
1792 @param virtualKeyCode
1793 The virtual key code of the hotkey.
1795 @return @true if the hotkey was registered successfully. @false if some
1796 other application already registered a hotkey with this
1797 modifier/virtualKeyCode combination.
1799 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
1800 event. This function is currently only implemented
1801 under Windows. It is used in the Windows CE port for
1802 detecting hardware button presses.
1804 @see UnregisterHotKey()
1806 virtual bool RegisterHotKey(int hotkeyId
, int modifiers
,
1807 int virtualKeyCode
);
1810 Releases mouse input captured with CaptureMouse().
1812 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
1813 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
1815 void ReleaseMouse();
1818 Removes a child window.
1820 This is called automatically by window deletion functions so should not
1821 be required by the application programmer.
1822 Notice that this function is mostly internal to wxWidgets and shouldn't be
1823 called by the user code.
1826 Child window to remove.
1828 virtual void RemoveChild(wxWindow
* child
);
1831 Find the given @a handler in the windows event handler chain and remove
1832 (but not delete) it from it.
1835 The event handler to remove, must be non-@NULL and
1836 must be present in this windows event handlers chain
1838 @return Returns @true if it was found and @false otherwise (this also
1839 results in an assert failure so this function should
1840 only be called when the handler is supposed to be there).
1842 @see PushEventHandler(), PopEventHandler()
1844 bool RemoveEventHandler(wxEvtHandler
* handler
);
1847 Reparents the window, i.e the window will be removed from its
1848 current parent window (e.g. a non-standard toolbar in a wxFrame)
1849 and then re-inserted into another.
1854 virtual bool Reparent(wxWindow
* newParent
);
1857 Converts from screen to client window coordinates.
1860 Stores the screen x coordinate and receives the client x coordinate.
1862 Stores the screen x coordinate and receives the client x coordinate.
1864 void ScreenToClient(int* x
, int* y
) const;
1867 Converts from screen to client window coordinates.
1870 The screen position.
1872 wxPoint
ScreenToClient(const wxPoint
& pt
) const;
1875 Scrolls the window by the given number of lines down (if @a lines is
1878 @return Returns @true if the window was scrolled, @false if it was already
1879 on top/bottom and nothing was done.
1881 @remarks This function is currently only implemented under MSW and
1882 wxTextCtrl under wxGTK (it also works for wxScrolled classes
1883 under all platforms).
1887 virtual bool ScrollLines(int lines
);
1890 Scrolls the window by the given number of pages down (if @a pages is
1893 @return Returns @true if the window was scrolled, @false if it was already
1894 on top/bottom and nothing was done.
1896 @remarks This function is currently only implemented under MSW and wxGTK.
1900 virtual bool ScrollPages(int pages
);
1903 Physically scrolls the pixels in the window and move child windows accordingly.
1906 Amount to scroll horizontally.
1908 Amount to scroll vertically.
1910 Rectangle to scroll, if it is @NULL, the whole window is
1911 scrolled (this is always the case under wxGTK which doesn't support this
1914 @remarks Note that you can often use wxScrolled instead of using this
1917 virtual void ScrollWindow(int dx
, int dy
,
1918 const wxRect
* rect
= NULL
);
1921 This function sends a dummy @ref wxSizeEvent "size event" to
1922 the window allowing it to re-layout its children positions.
1924 It is sometimes useful to call this function after adding or deleting a
1925 children after the frame creation or if a child size changes. Note that
1926 if the frame is using either sizers or constraints for the children
1927 layout, it is enough to call wxWindow::Layout() directly and this
1928 function should not be used in this case.
1930 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
1931 the event, i.e. schedules it for later processing, instead of
1932 dispatching it directly. You can also use PostSizeEvent() as a more
1933 readable equivalent of calling this function with this flag.
1936 May include @c wxSEND_EVENT_POST. Default value is 0.
1938 virtual void SendSizeEvent(int flags
= 0);
1941 Safe wrapper for GetParent()->SendSizeEvent().
1943 This function simply checks that the window has a valid parent which is
1944 not in process of being deleted and calls SendSizeEvent() on it. It is
1945 used internally by windows such as toolbars changes to whose state
1946 should result in parent re-layout (e.g. when a toolbar is added to the
1947 top of the window, all the other windows must be shifted down).
1949 @see PostSizeEventToParent()
1952 See description of this parameter in SendSizeEvent() documentation.
1954 void SendSizeEventToParent(int flags
= 0);
1957 Sets the accelerator table for this window. See wxAcceleratorTable.
1959 virtual void SetAcceleratorTable(const wxAcceleratorTable
& accel
);
1962 Sets the accessible for this window. Any existing accessible for this window
1963 will be deleted first, if not identical to @e accessible.
1964 See also wxAccessible.
1966 void SetAccessible(wxAccessible
* accessible
);
1969 Determines whether the Layout() function will be called automatically
1970 when the window is resized. Please note that this only happens for the
1971 windows usually used to contain children, namely wxPanel and wxTopLevelWindow
1972 (and the classes deriving from them).
1974 This method is called implicitly by SetSizer() but if you use SetConstraints()
1975 you should call it manually or otherwise the window layout won't be correctly
1976 updated when its size changes.
1979 Set this to @true if you wish the Layout function to be
1980 called automatically when the window is resized.
1982 @see SetConstraints()
1984 void SetAutoLayout(bool autoLayout
);
1987 Sets the background colour of the window.
1988 Please see InheritAttributes() for explanation of the difference between
1989 this method and SetOwnBackgroundColour().
1992 The colour to be used as the background colour, pass
1993 wxNullColour to reset to the default colour.
1995 @remarks The background colour is usually painted by the default
1996 wxEraseEvent event handler function under Windows and
1997 automatically under GTK.
1998 Note that setting the background colour does not cause an
1999 immediate refresh, so you may wish to call wxWindow::ClearBackground
2000 or wxWindow::Refresh after calling this function.
2001 Using this function will disable attempts to use themes for
2002 this window, if the system supports them. Use with care since
2003 usually the themes represent the appearance chosen by the user
2004 to be used for all applications on the system.
2006 @see GetBackgroundColour(), SetForegroundColour(),
2007 GetForegroundColour(), ClearBackground(),
2008 Refresh(), wxEraseEvent
2010 virtual bool SetBackgroundColour(const wxColour
& colour
);
2013 Sets the background style of the window. see GetBackgroundStyle() for
2014 the description of the possible style values.
2016 @see SetBackgroundColour(), GetForegroundColour(),
2019 virtual bool SetBackgroundStyle(wxBackgroundStyle style
);
2022 This method is only implemented by ports which have support for
2023 native TAB traversal (such as GTK+ 2.0).
2025 It is called by wxWidgets' container control code to give the native
2026 system a hint when doing TAB traversal. A call to this does not disable
2027 or change the effect of programmatically calling SetFocus().
2029 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
2031 virtual void SetCanFocus(bool canFocus
);
2034 Sets the caret() associated with the window.
2036 void SetCaret(wxCaret
* caret
);
2040 This sets the size of the window client area in pixels.
2042 Using this function to size a window tends to be more device-independent
2043 than SetSize(), since the application need not worry about what dimensions
2044 the border or title bar have when trying to fit the window around panel
2047 virtual void SetClientSize(int width
, int height
);
2048 virtual void SetClientSize(const wxSize
& size
);
2052 Sets the window to have the given layout constraints. The window
2053 will then own the object, and will take care of its deletion.
2054 If an existing layout constraints object is already owned by the
2055 window, it will be deleted.
2058 The constraints to set. Pass @NULL to disassociate and delete the window's
2061 @remarks You must call SetAutoLayout() to tell a window to use
2062 the constraints automatically in OnSize; otherwise, you
2063 must override OnSize and call Layout() explicitly. When
2064 setting both a wxLayoutConstraints and a wxSizer, only
2065 the sizer will have effect.
2067 void SetConstraints(wxLayoutConstraints
* constraints
);
2070 This normally does not need to be called by user code.
2071 It is called when a window is added to a sizer, and is used so the window
2072 can remove itself from the sizer when it is destroyed.
2074 void SetContainingSizer(wxSizer
* sizer
);
2077 Sets the window's cursor. Notice that the window cursor also sets it for the
2078 children of the window implicitly.
2080 The @a cursor may be @c wxNullCursor in which case the window cursor will
2081 be reset back to default.
2084 Specifies the cursor that the window should normally display.
2086 @see ::wxSetCursor, wxCursor
2088 virtual bool SetCursor(const wxCursor
& cursor
);
2091 Associates a drop target with this window.
2092 If the window already has a drop target, it is deleted.
2094 @see GetDropTarget(), @ref overview_dnd
2096 virtual void SetDropTarget(wxDropTarget
* target
);
2099 Sets the event handler for this window.
2102 Specifies the handler to be set.
2104 @remarks An event handler is an object that is capable of processing the
2105 events sent to a window. By default, the window is its
2106 own event handler, but an application may wish to
2107 substitute another, for example to allow central
2108 implementation of event-handling for a variety of
2109 different window classes.
2110 It is usually better to use wxWindow::PushEventHandler since
2111 this sets up a chain of event handlers, where an event not
2112 handled by one event handler is handed to the next one in the chain.
2114 @see GetEventHandler(), PushEventHandler(),
2115 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
2117 void SetEventHandler(wxEvtHandler
* handler
);
2120 Sets the extra style bits for the window.
2121 The currently defined extra style bits are reported in the class
2124 virtual void SetExtraStyle(long exStyle
);
2127 This sets the window to receive keyboard input.
2129 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
2130 wxPanel::SetFocusIgnoringChildren
2132 virtual void SetFocus();
2135 This function is called by wxWidgets keyboard navigation code when the user
2136 gives the focus to this window from keyboard (e.g. using @c TAB key).
2138 By default this method simply calls SetFocus() but
2139 can be overridden to do something in addition to this in the derived classes.
2141 virtual void SetFocusFromKbd();
2144 Sets the font for this window. This function should not be called for the
2145 parent window if you don't want its font to be inherited by its children,
2146 use SetOwnFont() instead in this case and see InheritAttributes() for more
2149 Please notice that the given font is not automatically used for
2150 wxPaintDC objects associated with this window, you need to
2151 call wxDC::SetFont too. However this font is used by
2152 any standard controls for drawing their text as well as by
2156 Font to associate with this window, pass
2157 wxNullFont to reset to the default font.
2159 @return @true if the want was really changed, @false if it was already set
2160 to this font and so nothing was done.
2162 @see GetFont(), InheritAttributes()
2164 virtual bool SetFont(const wxFont
& font
);
2167 Sets the foreground colour of the window.
2168 Please see InheritAttributes() for explanation of the difference between
2169 this method and SetOwnForegroundColour().
2172 The colour to be used as the foreground colour, pass
2173 wxNullColour to reset to the default colour.
2175 @remarks The interpretation of foreground colour is open to
2176 interpretation according to the window class; it may be
2177 the text colour or other colour, or it may not be used at all.
2179 @see GetForegroundColour(), SetBackgroundColour(),
2180 GetBackgroundColour(), ShouldInheritColours()
2182 virtual bool SetForegroundColour(const wxColour
& colour
);
2185 Sets the help text to be used as context-sensitive help for this window.
2186 Note that the text is actually stored by the current wxHelpProvider
2187 implementation, and not in the window object itself.
2189 @see GetHelpText(), wxHelpProvider::AddHelp()
2191 void SetHelpText(const wxString
& helpText
);
2194 Sets the identifier of the window.
2196 @remarks Each window has an integer identifier. If the application has
2197 not provided one, an identifier will be generated.
2198 Normally, the identifier should be provided on creation
2199 and should not be modified subsequently.
2201 @see GetId(), @ref overview_windowids
2203 void SetId(wxWindowID winid
);
2206 A @e smart SetSize that will fill in default size components with the
2207 window's @e best size values.
2209 Also sets the window's minsize to the value passed in for use with sizers.
2210 This means that if a full or partial size is passed to this function then
2211 the sizers will use that size instead of the results of GetBestSize() to
2212 determine the minimum needs of the window for layout.
2214 Most controls will use this to set their initial size, and their min
2215 size to the passed in value (if any.)
2217 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
2218 @ref overview_windowsizing
2220 void SetInitialSize(const wxSize
& size
= wxDefaultSize
);
2223 Sets the window's label.
2230 virtual void SetLabel(const wxString
& label
);
2233 Sets the maximum client size of the window, to indicate to the sizer
2234 layout mechanism that this is the maximum possible size of its client area.
2238 virtual void SetMaxClientSize(const wxSize
& size
);
2241 Sets the maximum size of the window, to indicate to the sizer layout mechanism
2242 that this is the maximum possible size.
2244 @see SetMaxClientSize()
2246 virtual void SetMaxSize(const wxSize
& size
);
2249 Sets the minimum client size of the window, to indicate to the sizer
2250 layout mechanism that this is the minimum required size of window's client
2253 You may need to call this if you change the window size after
2254 construction and before adding to its parent sizer.
2256 Note, that just as with SetMinSize(), calling this method doesn't
2257 prevent the program from explicitly making the window smaller than the
2262 virtual void SetMinClientSize(const wxSize
& size
);
2265 Sets the minimum size of the window, to indicate to the sizer layout
2266 mechanism that this is the minimum required size.
2268 You may need to call this if you change the window size after
2269 construction and before adding to its parent sizer.
2271 Notice that calling this method doesn't prevent the program from making
2272 the window explicitly smaller than the specified size by calling
2273 SetSize(), it just ensures that it won't become smaller than this size
2274 during the automatic layout.
2276 @see SetMinClientSize()
2278 virtual void SetMinSize(const wxSize
& size
);
2281 Sets the window's name.
2284 A name to set for the window.
2288 virtual void SetName(const wxString
& name
);
2291 Sets the background colour of the window but prevents it from being inherited
2292 by the children of this window.
2294 @see SetBackgroundColour(), InheritAttributes()
2296 void SetOwnBackgroundColour(const wxColour
& colour
);
2299 Sets the font of the window but prevents it from being inherited by the
2300 children of this window.
2302 @see SetFont(), InheritAttributes()
2304 void SetOwnFont(const wxFont
& font
);
2307 Sets the foreground colour of the window but prevents it from being inherited
2308 by the children of this window.
2310 @see SetForegroundColour(), InheritAttributes()
2312 void SetOwnForegroundColour(const wxColour
& colour
);
2315 @deprecated use wxDC::SetPalette instead.
2317 void SetPalette(const wxPalette
& pal
);
2320 Sets the position of one of the built-in scrollbars.
2323 Determines the scrollbar whose position is to be set.
2324 May be wxHORIZONTAL or wxVERTICAL.
2326 Position in scroll units.
2328 @true to redraw the scrollbar, @false otherwise.
2330 @remarks This function does not directly affect the contents of the
2331 window: it is up to the application to take note of
2332 scrollbar attributes and redraw contents accordingly.
2334 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
2337 virtual void SetScrollPos(int orientation
, int pos
,
2338 bool refresh
= true);
2341 Sets the scrollbar properties of a built-in scrollbar.
2344 Determines the scrollbar whose page size is to be set.
2345 May be wxHORIZONTAL or wxVERTICAL.
2347 The position of the scrollbar in scroll units.
2349 The size of the thumb, or visible portion of the scrollbar, in scroll units.
2351 The maximum position of the scrollbar.
2353 @true to redraw the scrollbar, @false otherwise.
2356 Let's say you wish to display 50 lines of text, using the same font.
2357 The window is sized so that you can only see 16 lines at a time.
2360 SetScrollbar(wxVERTICAL, 0, 16, 50);
2362 Note that with the window at this size, the thumb position can never
2363 go above 50 minus 16, or 34. You can determine how many lines are
2364 currently visible by dividing the current view size by the character
2366 When defining your own scrollbar behaviour, you will always need
2367 to recalculate the scrollbar settings when the window size changes.
2368 You could therefore put your scrollbar calculations and SetScrollbar
2369 call into a function named AdjustScrollbars, which can be called
2370 initially and also from your wxSizeEvent handler function.
2372 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
2374 virtual void SetScrollbar(int orientation
, int position
,
2375 int thumbSize
, int range
,
2376 bool refresh
= true);
2379 Sets the size of the window in pixels.
2382 Required x position in pixels, or wxDefaultCoord to indicate that the
2383 existing value should be used.
2385 Required y position in pixels, or wxDefaultCoord to indicate that the
2386 existing value should be used.
2388 Required width in pixels, or wxDefaultCoord to indicate that the existing
2389 value should be used.
2391 Required height position in pixels, or wxDefaultCoord to indicate that the
2392 existing value should be used.
2394 Indicates the interpretation of other parameters.
2395 It is a bit list of the following:
2396 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
2397 a wxWidgets-supplied default width.
2398 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
2399 a wxWidgets-supplied default height.
2400 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
2401 a wxWidgets-supplied default size.
2402 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
2403 if wxDefaultCoord values are supplied.
2404 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
2405 wxDefaultCoord) to be interpreted as real
2406 dimensions, not default values.
2407 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
2408 already the same as the parameters of this function,
2409 nothing is done. but with this flag a window resize may
2410 be forced even in this case (supported in wx 2.6.2 and
2411 later and only implemented for MSW and ignored elsewhere
2414 @remarks This overload sets the position and optionally size, of the window.
2415 Parameters may be wxDefaultCoord to indicate either that a default
2416 should be supplied by wxWidgets, or that the current value of the
2417 dimension should be used.
2421 void SetSize(int x
, int y
, int width
, int height
,
2422 int sizeFlags
= wxSIZE_AUTO
);
2426 Sets the size of the window in pixels.
2427 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
2429 @remarks This form must be used with non-default width and height values.
2433 virtual void SetSize(const wxRect
& rect
);
2434 virtual void SetSize(const wxSize
& size
);
2435 virtual void SetSize(int width
, int height
);
2439 Sets the window to have the given layout sizer.
2440 The window will then own the object, and will take care of its deletion.
2441 If an existing layout constraints object is already owned by the
2442 window, it will be deleted if the deleteOld parameter is @true.
2444 Note that this function will also call SetAutoLayout() implicitly with @true
2445 parameter if the @a sizer is non-@NULL and @false otherwise.
2448 The sizer to set. Pass @NULL to disassociate and conditionally delete
2449 the window's sizer. See below.
2451 If @true (the default), this will delete any pre-existing sizer.
2452 Pass @false if you wish to handle deleting the old sizer yourself.
2454 @remarks SetSizer enables and disables Layout automatically.
2456 void SetSizer(wxSizer
* sizer
, bool deleteOld
= true);
2459 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
2460 window size to the size needed to accommodate all sizer elements and sets the
2461 size hints which, if this window is a top level one, prevent the user from
2462 resizing it to be less than this minimial size.
2464 void SetSizerAndFit(wxSizer
* sizer
, bool deleteOld
= true);
2467 This function tells a window if it should use the system's "theme" code
2468 to draw the windows' background instead if its own background drawing
2469 code. This does not always have any effect since the underlying platform
2470 obviously needs to support the notion of themes in user defined windows.
2471 One such platform is GTK+ where windows can have (very colourful) backgrounds
2472 defined by a user's selected theme.
2474 Dialogs, notebook pages and the status bar have this flag set to @true
2475 by default so that the default look and feel is simulated best.
2477 virtual void SetThemeEnabled(bool enable
);
2481 Attach a tooltip to the window.
2483 wxToolTip pointer can be @NULL in the overload taking the pointer,
2484 meaning to unset any existing tooltips, however UnsetToolTip() provides
2485 a more readable alternative to this operation.
2487 Notice that these methods are always available, even if wxWidgets was
2488 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2491 @see GetToolTip(), wxToolTip
2493 void SetToolTip(const wxString
& tip
);
2494 void SetToolTip(wxToolTip
* tip
);
2498 Set the transparency of the window. If the system supports transparent windows,
2499 returns @true, otherwise returns @false and the window remains fully opaque.
2500 See also CanSetTransparent().
2502 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
2503 fully transparent window and 255 to the fully opaque one. The constants
2504 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
2506 virtual bool SetTransparent(wxByte alpha
);
2509 Deletes the current validator (if any) and sets the window validator, having
2510 called wxValidator::Clone to create a new validator of this type.
2512 virtual void SetValidator(const wxValidator
& validator
);
2516 Sets the virtual size of the window in pixels.
2518 void SetVirtualSize(int width
, int height
);
2519 void SetVirtualSize(const wxSize
& size
);
2523 Identical to SetWindowStyleFlag().
2525 void SetWindowStyle(long style
);
2528 Sets the style of the window. Please note that some styles cannot be changed
2529 after the window creation and that Refresh() might need to be be called
2530 after changing the others for the change to take place immediately.
2532 See @ref overview_windowstyles "Window styles" for more information about flags.
2534 @see GetWindowStyleFlag()
2536 virtual void SetWindowStyleFlag(long style
);
2539 This function can be called under all platforms but only does anything under
2540 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2541 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2543 By default the controls use the normal size, of course, but this function can
2544 be used to change this.
2546 void SetWindowVariant(wxWindowVariant variant
);
2549 Return @true from here to allow the colours of this window to be changed by
2550 InheritAttributes(), returning @false forbids inheriting them from the parent window.
2552 The base class version returns @false, but this method is overridden in
2553 wxControl where it returns @true.
2555 virtual bool ShouldInheritColours() const;
2558 Shows or hides the window. You may need to call Raise()
2559 for a top level window if you want to bring it to top, although this is not
2560 needed if Show() is called immediately after the frame creation.
2563 If @true displays the window. Otherwise, hides it.
2565 @return @true if the window has been shown or hidden or @false if nothing
2566 was done because it already was in the requested state.
2568 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2570 virtual bool Show(bool show
= true);
2573 This function shows a window, like Show(), but using a special visual
2580 The @a timeout parameter specifies the time of the animation, in
2581 milliseconds. If the default value of 0 is used, the default
2582 animation time for the current platform is used.
2584 @note Currently this function is only implemented in wxMSW and does the
2585 same thing as Show() in the other ports.
2589 @see HideWithEffect()
2591 virtual bool ShowWithEffect(wxShowEffect effect
,
2592 unsigned int timeout
= 0);
2595 Reenables window updating after a previous call to Freeze().
2597 To really thaw the control, it must be called exactly the same number
2598 of times as Freeze().
2600 If the window has any children, they are recursively thawn too.
2602 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
2607 Turns the given @a flag on if it's currently turned off and vice versa.
2608 This function cannot be used if the value of the flag is 0 (which is often
2609 the case for default flags).
2611 Also, please notice that not all styles can be changed after the control
2614 @return Returns @true if the style was turned on by this function, @false
2615 if it was switched off.
2617 @see SetWindowStyleFlag(), HasFlag()
2619 bool ToggleWindowStyle(int flag
);
2622 Transfers values from child controls to data areas specified by their
2623 validators. Returns @false if a transfer failed.
2625 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2626 the method will also call TransferDataFromWindow() of all child windows.
2628 @see TransferDataToWindow(), wxValidator, Validate()
2630 virtual bool TransferDataFromWindow();
2633 Transfers values to child controls from data areas specified by their
2636 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2637 the method will also call TransferDataToWindow() of all child windows.
2639 @return Returns @false if a transfer failed.
2641 @see TransferDataFromWindow(), wxValidator, Validate()
2643 virtual bool TransferDataToWindow();
2646 Unregisters a system wide hotkey.
2649 Numeric identifier of the hotkey. Must be the same id that was passed to
2652 @return @true if the hotkey was unregistered successfully, @false if the
2655 @remarks This function is currently only implemented under MSW.
2657 @see RegisterHotKey()
2659 virtual bool UnregisterHotKey(int hotkeyId
);
2662 Unreserve an ID or range of IDs that was reserved by NewControlId().
2663 See @ref overview_windowids for more information.
2666 The starting ID of the range of IDs to unreserve.
2668 The number of sequential IDs to unreserve.
2670 @see NewControlId(), wxIdManager, @ref overview_windowids
2672 static void UnreserveControlId(wxWindowID id
, int count
= 1);
2675 Unset any existing tooltip.
2681 void UnsetToolTip();
2684 Calling this method immediately repaints the invalidated area of the window and
2685 all of its children recursively while this would usually only happen when the
2686 flow of control returns to the event loop.
2688 Notice that this function doesn't invalidate any area of the window so
2689 nothing happens if nothing has been invalidated (i.e. marked as requiring
2690 a redraw). Use Refresh() first if you want to immediately redraw the
2691 window unconditionally.
2693 virtual void Update();
2696 This function sends one or more wxUpdateUIEvent to the window.
2697 The particular implementation depends on the window; for example a
2698 wxToolBar will send an update UI event for each toolbar button,
2699 and a wxFrame will send an update UI event for each menubar menu item.
2701 You can call this function from your application to ensure that your
2702 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
2703 are concerned). This may be necessary if you have called
2704 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
2705 the overhead that wxWidgets incurs by sending update UI events in idle time.
2706 @a flags should be a bitlist of one or more of the wxUpdateUI enumeration.
2708 If you are calling this function from an OnInternalIdle or OnIdle
2709 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
2710 this tells the window to only update the UI elements that need
2711 to be updated in idle time. Some windows update their elements
2712 only when necessary, for example when a menu is about to be shown.
2713 The following is an example of how to call UpdateWindowUI from
2717 void MyWindow::OnInternalIdle()
2719 if (wxUpdateUIEvent::CanUpdate(this))
2720 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
2724 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
2726 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
);
2729 Validates the current values of the child controls using their validators.
2730 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2731 the method will also call Validate() of all child windows.
2733 @return Returns @false if any of the validations failed.
2735 @see TransferDataFromWindow(), TransferDataToWindow(),
2738 virtual bool Validate();
2741 Moves the pointer to the given position on the window.
2743 @note This function is not supported under Mac because Apple Human
2744 Interface Guidelines forbid moving the mouse cursor programmatically.
2747 The new x position for the cursor.
2749 The new y position for the cursor.
2751 virtual void WarpPointer(int x
, int y
);
2757 Gets the size which best suits the window: for a control, it would be
2758 the minimal size which doesn't truncate the control, for a panel - the
2759 same size as it would have after a call to Fit().
2761 The default implementation of this function is designed for use in container
2762 windows, such as wxPanel, and works something like this:
2763 -# If the window has a sizer then it is used to calculate the best size.
2764 -# Otherwise if the window has layout constraints then those are used to
2765 calculate the best size.
2766 -# Otherwise if the window has children then the best size is set to be large
2767 enough to show all the children.
2768 -# Otherwise if there are no children then the window's minimal size will be
2769 used as its best size.
2770 -# Otherwise if there is no minimal size set, then the current size is used
2773 @see @ref overview_windowsizing
2775 virtual wxSize
DoGetBestSize() const;
2779 Sets the initial window size if none is given (i.e. at least one of the
2780 components of the size passed to ctor/Create() is wxDefaultCoord).
2781 @deprecated @todo provide deprecation description
2783 virtual void SetInitialBestSize(const wxSize
& size
);
2788 // ============================================================================
2789 // Global functions/macros
2790 // ============================================================================
2792 /** @ingroup group_funcmacro_misc */
2796 Find the deepest window at the mouse pointer position, returning the window
2797 and current pointer position in screen coordinates.
2799 @header{wx/window.h}
2801 wxWindow
* wxFindWindowAtPointer(wxPoint
& pt
);
2804 Gets the currently active window (implemented for MSW and GTK only
2805 currently, always returns @NULL in the other ports).
2807 @header{wx/window.h}
2809 wxWindow
* wxGetActiveWindow();
2812 Returns the first top level parent of the given window, or in other words,
2813 the frame or dialog containing it, or @NULL.
2815 @header{wx/window.h}
2817 wxWindow
* wxGetTopLevelParent(wxWindow
* window
);