]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/window.h
support for iPhone callbacks
[wxWidgets.git] / interface / wx / window.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: window.h
3// Purpose: interface of wxWindow
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows licence
7/////////////////////////////////////////////////////////////////////////////
8
9
10/**
11 Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
12*/
13enum wxShowEffect
14{
15 /**
16 No effect, equivalent to normal wxWindow::Show() or Hide() call.
17
18 @since 2.9.1
19 */
20 wxSHOW_EFFECT_NONE,
21
22 /// Roll window to the left
23 wxSHOW_EFFECT_ROLL_TO_LEFT,
24
25 /// Roll window to the right
26 wxSHOW_EFFECT_ROLL_TO_RIGHT,
27
28 /// Roll window to the top
29 wxSHOW_EFFECT_ROLL_TO_TOP,
30
31 /// Roll window to the bottom
32 wxSHOW_EFFECT_ROLL_TO_BOTTOM,
33
34 /// Slide window to the left
35 wxSHOW_EFFECT_SLIDE_TO_LEFT,
36
37 /// Slide window to the right
38 wxSHOW_EFFECT_SLIDE_TO_RIGHT,
39
40 /// Slide window to the top
41 wxSHOW_EFFECT_SLIDE_TO_TOP,
42
43 /// Slide window to the bottom
44 wxSHOW_EFFECT_SLIDE_TO_BOTTOM,
45
46 /// Fade in or out effect
47 wxSHOW_EFFECT_BLEND,
48
49 /// Expanding or collapsing effect
50 wxSHOW_EFFECT_EXPAND,
51
52 wxSHOW_EFFECT_MAX
53};
54
55
56/**
57 flags for SendSizeEvent()
58*/
59enum
60{
61 wxSEND_EVENT_POST = 1
62};
63
64
65
66
67/**
68 Struct containing all the visual attributes of a control.
69*/
70struct wxVisualAttributes
71{
72 /// The font used for control label/text inside it.
73 wxFont font;
74
75 /// The foreground colour.
76 wxColour colFg;
77
78 /**
79 The background colour.
80
81 May be wxNullColour if the controls background colour is not solid.
82 */
83 wxColour colBg;
84};
85
86
87/**
88 Different window variants, on platforms like eg mac uses different
89 rendering sizes.
90*/
91enum wxWindowVariant
92{
93 wxWINDOW_VARIANT_NORMAL, //!< Normal size
94 wxWINDOW_VARIANT_SMALL, //!< Smaller size (about 25 % smaller than normal)
95 wxWINDOW_VARIANT_MINI, //!< Mini size (about 33 % smaller than normal)
96 wxWINDOW_VARIANT_LARGE, //!< Large size (about 25 % larger than normal)
97 wxWINDOW_VARIANT_MAX
98};
99
100
101/**
102 @class wxWindow
103
104 wxWindow is the base class for all windows and represents any visible object
105 on screen. All controls, top level windows and so on are windows. Sizers and
106 device contexts are not, however, as they don't appear on screen themselves.
107
108 Please note that all children of the window will be deleted automatically by
109 the destructor before the window itself is deleted which means that you don't
110 have to worry about deleting them manually. Please see the @ref
111 overview_windowdeletion "window deletion overview" for more information.
112
113 Also note that in this, and many others, wxWidgets classes some
114 @c GetXXX() methods may be overloaded (as, for example,
115 wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
116 are non-virtual because having multiple virtual functions with the same name
117 results in a virtual function name hiding at the derived class level (in
118 English, this means that the derived class has to override all overloaded
119 variants if it overrides any of them). To allow overriding them in the derived
120 class, wxWidgets uses a unique protected virtual @c DoGetXXX() method
121 and all @c GetXXX() ones are forwarded to it, so overriding the former
122 changes the behaviour of the latter.
123
124 @beginStyleTable
125 @style{wxBORDER_DEFAULT}
126 The window class will decide the kind of border to show, if any.
127 @style{wxBORDER_SIMPLE}
128 Displays a thin border around the window. wxSIMPLE_BORDER is the
129 old name for this style.
130 @style{wxBORDER_SUNKEN}
131 Displays a sunken border. wxSUNKEN_BORDER is the old name for this
132 style.
133 @style{wxBORDER_RAISED}
134 Displays a raised border. wxRAISED_BORDER is the old name for this
135 style.
136 @style{wxBORDER_STATIC}
137 Displays a border suitable for a static control. wxSTATIC_BORDER
138 is the old name for this style. Windows only.
139 @style{wxBORDER_THEME}
140 Displays a native border suitable for a control, on the current
141 platform. On Windows XP or Vista, this will be a themed border; on
142 most other platforms a sunken border will be used. For more
143 information for themed borders on Windows, please see Themed
144 borders on Windows.
145 @style{wxBORDER_NONE}
146 Displays no border, overriding the default border style for the
147 window. wxNO_BORDER is the old name for this style.
148 @style{wxBORDER_DOUBLE}
149 This style is obsolete and should not be used.
150 @style{wxTRANSPARENT_WINDOW}
151 The window is transparent, that is, it will not receive paint
152 events. Windows only.
153 @style{wxTAB_TRAVERSAL}
154 Use this to enable tab traversal for non-dialog windows.
155 @style{wxWANTS_CHARS}
156 Use this to indicate that the window wants to get all char/key
157 events for all keys - even for keys like TAB or ENTER which are
158 usually used for dialog navigation and which wouldn't be generated
159 without this style. If you need to use this style in order to get
160 the arrows or etc., but would still like to have normal keyboard
161 navigation take place, you should call Navigate in response to the
162 key events for Tab and Shift-Tab.
163 @style{wxNO_FULL_REPAINT_ON_RESIZE}
164 On Windows, this style used to disable repainting the window
165 completely when its size is changed. Since this behaviour is now
166 the default, the style is now obsolete and no longer has an effect.
167 @style{wxVSCROLL}
168 Use this style to enable a vertical scrollbar. Notice that this
169 style cannot be used with native controls which don't support
170 scrollbars nor with top-level windows in most ports.
171 @style{wxHSCROLL}
172 Use this style to enable a horizontal scrollbar. The same
173 limitations as for wxVSCROLL apply to this style.
174 @style{wxALWAYS_SHOW_SB}
175 If a window has scrollbars, disable them instead of hiding them
176 when they are not needed (i.e. when the size of the window is big
177 enough to not require the scrollbars to navigate it). This style is
178 currently implemented for wxMSW, wxGTK and wxUniversal and does
179 nothing on the other platforms.
180 @style{wxCLIP_CHILDREN}
181 Use this style to eliminate flicker caused by the background being
182 repainted, then children being painted over them. Windows only.
183 @style{wxFULL_REPAINT_ON_RESIZE}
184 Use this style to force a complete redraw of the window whenever it
185 is resized instead of redrawing just the part of the window
186 affected by resizing. Note that this was the behaviour by default
187 before 2.5.1 release and that if you experience redraw problems
188 with code which previously used to work you may want to try this.
189 Currently this style applies on GTK+ 2 and Windows only, and full
190 repainting is always done on other platforms.
191 @endStyleTable
192
193 @beginExtraStyleTable
194 @style{wxWS_EX_VALIDATE_RECURSIVELY}
195 By default, wxWindow::Validate(), wxWindow::TransferDataTo() and
196 wxWindow::TransferDataFromWindow() only work on
197 direct children of the window (compatible behaviour).
198 Set this flag to make them recursively descend into all subwindows.
199 @style{wxWS_EX_BLOCK_EVENTS}
200 wxCommandEvents and the objects of the derived classes are
201 forwarded to the parent window and so on recursively by default.
202 Using this flag for the given window allows to block this
203 propagation at this window, i.e. prevent the events from being
204 propagated further upwards. Dialogs have this flag on by default
205 for the reasons explained in the @ref overview_events.
206 @style{wxWS_EX_TRANSIENT}
207 Don't use this window as an implicit parent for the other windows:
208 this must be used with transient windows as otherwise there is the
209 risk of creating a dialog/frame with this window as a parent, which
210 would lead to a crash if the parent were destroyed before the child.
211 @style{wxWS_EX_CONTEXTHELP}
212 Under Windows, puts a query button on the caption. When pressed,
213 Windows will go into a context-sensitive help mode and wxWidgets
214 will send a @c wxEVT_HELP event if the user clicked on an application window.
215 This style cannot be used (because of the underlying native behaviour)
216 together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
217 are automatically turned off if this one is used.
218 @style{wxWS_EX_PROCESS_IDLE}
219 This window should always process idle events, even if the mode set
220 by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED.
221 @style{wxWS_EX_PROCESS_UI_UPDATES}
222 This window should always process UI update events, even if the
223 mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED.
224 @endExtraStyleTable
225
226 @beginEventEmissionTable
227 @event{EVT_ACTIVATE(id, func)}
228 Process a @c wxEVT_ACTIVATE event. See wxActivateEvent.
229 @event{EVT_CHILD_FOCUS(func)}
230 Process a @c wxEVT_CHILD_FOCUS event. See wxChildFocusEvent.
231 @event{EVT_CONTEXT_MENU(func)}
232 A right click (or other context menu command depending on platform) has been detected.
233 See wxContextMenuEvent.
234 @event{EVT_HELP(id, func)}
235 Process a @c wxEVT_HELP event. See wxHelpEvent.
236 @event{EVT_HELP_RANGE(id1, id2, func)}
237 Process a @c wxEVT_HELP event for a range of ids. See wxHelpEvent.
238 @event{EVT_DROP_FILES(func)}
239 Process a @c wxEVT_DROP_FILES event. See wxDropFilesEvent.
240 @event{EVT_ERASE_BACKGROUND(func)}
241 Process a @c wxEVT_ERASE_BACKGROUND event. See wxEraseEvent.
242 @event{EVT_SET_FOCUS(func)}
243 Process a @c wxEVT_SET_FOCUS event. See wxFocusEvent.
244 @event{EVT_KILL_FOCUS(func)}
245 Process a @c wxEVT_KILL_FOCUS event. See wxFocusEvent.
246 @event{EVT_IDLE(func)}
247 Process a @c wxEVT_IDLE event. See wxIdleEvent.
248 @event{EVT_JOY_*(func)}
249 Processes joystick events. See wxJoystickEvent.
250 @event{EVT_KEY_DOWN(func)}
251 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
252 See wxKeyEvent.
253 @event{EVT_KEY_UP(func)}
254 Process a @c wxEVT_KEY_UP event (any key has been released).
255 See wxKeyEvent.
256 @event{EVT_CHAR(func)}
257 Process a @c wxEVT_CHAR event.
258 See wxKeyEvent.
259 @event{EVT_CHAR_HOOK(func)}
260 Process a @c wxEVT_CHAR_HOOK event.
261 See wxKeyEvent.
262 @event{EVT_MOUSE_CAPTURE_LOST(func)}
263 Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
264 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
265 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. See wxMouseCaptureChangedEvent.
266 @event{EVT_MOUSE_*(func)}
267 See wxMouseEvent.
268 @event{EVT_PAINT(func)}
269 Process a @c wxEVT_PAINT event. See wxPaintEvent.
270 @event{EVT_POWER_*(func)}
271 The system power state changed. See wxPowerEvent.
272 @event{EVT_SCROLLWIN_*(func)}
273 Process scroll events. See wxScrollWinEvent.
274 @event{EVT_SET_CURSOR(func)}
275 Process a @c wxEVT_SET_CURSOR event. See wxSetCursorEvent.
276 @event{EVT_SIZE(func)}
277 Process a @c wxEVT_SIZE event. See wxSizeEvent.
278 @event{EVT_SYS_COLOUR_CHANGED(func)}
279 Process a @c wxEVT_SYS_COLOUR_CHANGED event. See wxSysColourChangedEvent.
280 @endEventTable
281
282 @library{wxcore}
283 @category{miscwnd}
284
285 @see @ref overview_events, @ref overview_windowsizing
286*/
287class wxWindow : public wxEvtHandler
288{
289public:
290 /**
291 Default constructor
292 */
293 wxWindow();
294
295 /**
296 Constructs a window, which can be a child of a frame, dialog or any other
297 non-control window.
298
299 @param parent
300 Pointer to a parent window.
301 @param id
302 Window identifier. If wxID_ANY, will automatically create an identifier.
303 @param pos
304 Window position. wxDefaultPosition indicates that wxWidgets
305 should generate a default position for the window.
306 If using the wxWindow class directly, supply an actual position.
307 @param size
308 Window size. wxDefaultSize indicates that wxWidgets should generate
309 a default size for the window. If no suitable size can be found, the
310 window will be sized to 20x20 pixels so that the window is visible but
311 obviously not correctly sized.
312 @param style
313 Window style. For generic window styles, please see wxWindow.
314 @param name
315 Window name.
316 */
317 wxWindow(wxWindow* parent, wxWindowID id,
318 const wxPoint& pos = wxDefaultPosition,
319 const wxSize& size = wxDefaultSize,
320 long style = 0,
321 const wxString& name = wxPanelNameStr);
322
323 /**
324 Destructor.
325
326 Deletes all sub-windows, then deletes itself. Instead of using
327 the @b delete operator explicitly, you should normally use Destroy()
328 so that wxWidgets can delete a window only when it is safe to do so, in idle time.
329
330 @see @ref overview_windowdeletion "Window Deletion Overview",
331 Destroy(), wxCloseEvent
332 */
333 virtual ~wxWindow();
334
335
336 bool Create(wxWindow *parent,
337 wxWindowID id,
338 const wxPoint& pos = wxDefaultPosition,
339 const wxSize& size = wxDefaultSize,
340 long style = 0,
341 const wxString& name = wxPanelNameStr);
342
343 /**
344 @name Focus functions
345
346 See also the static function FindFocus().
347 */
348 //@{
349
350 /**
351 This method may be overridden in the derived classes to return @false to
352 indicate that this control doesn't accept input at all (i.e.\ behaves like
353 e.g.\ wxStaticText) and so doesn't need focus.
354
355 @see AcceptsFocusFromKeyboard()
356 */
357 virtual bool AcceptsFocus() const;
358
359 /**
360 This method may be overridden in the derived classes to return @false to
361 indicate that while this control can, in principle, have focus if the user
362 clicks it with the mouse, it shouldn't be included in the TAB traversal chain
363 when using the keyboard.
364 */
365 virtual bool AcceptsFocusFromKeyboard() const;
366
367 /**
368 Overridden to indicate whether this window or one of its children accepts
369 focus. Usually it's the same as AcceptsFocus() but is overridden for
370 container windows.
371 */
372 virtual bool AcceptsFocusRecursively() const;
373
374 /**
375 Can this window itself have focus?
376 */
377 bool IsFocusable() const;
378
379 /**
380 Can this window have focus right now?
381
382 If this method returns true, it means that calling SetFocus() will
383 put focus either to this window or one of its children, if you need
384 to know whether this window accepts focus itself, use IsFocusable()
385 */
386 bool CanAcceptFocus() const;
387
388 /**
389 Can this window be assigned focus from keyboard right now?
390 */
391 bool CanAcceptFocusFromKeyboard() const;
392
393
394 /**
395 Returns @true if the window (or in case of composite controls, its main
396 child window) has focus.
397
398 @since 2.9.0
399
400 @see FindFocus()
401 */
402 virtual bool HasFocus() const;
403
404 /**
405 This method is only implemented by ports which have support for
406 native TAB traversal (such as GTK+ 2.0).
407
408 It is called by wxWidgets' container control code to give the native
409 system a hint when doing TAB traversal. A call to this does not disable
410 or change the effect of programmatically calling SetFocus().
411
412 @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
413 */
414 virtual void SetCanFocus(bool canFocus);
415
416 /**
417 This sets the window to receive keyboard input.
418
419 @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
420 wxPanel::SetFocusIgnoringChildren
421 */
422 virtual void SetFocus();
423
424 /**
425 This function is called by wxWidgets keyboard navigation code when the user
426 gives the focus to this window from keyboard (e.g. using @c TAB key).
427
428 By default this method simply calls SetFocus() but
429 can be overridden to do something in addition to this in the derived classes.
430 */
431 virtual void SetFocusFromKbd();
432
433 //@}
434
435
436 /**
437 @name Child management functions
438 */
439 //@{
440
441 /**
442 Adds a child window. This is called automatically by window creation
443 functions so should not be required by the application programmer.
444 Notice that this function is mostly internal to wxWidgets and shouldn't be
445 called by the user code.
446
447 @param child
448 Child window to add.
449 */
450 virtual void AddChild(wxWindow* child);
451
452 /**
453 Destroys all children of a window. Called automatically by the destructor.
454 */
455 bool DestroyChildren();
456
457 /**
458 Find a child of this window, by @a id.
459 May return @a this if it matches itself.
460 */
461 wxWindow* FindWindow(long id) const;
462
463 /**
464 Find a child of this window, by name.
465 May return @a this if it matches itself.
466 */
467 wxWindow* FindWindow(const wxString& name) const;
468
469 /**
470 Returns a reference to the list of the window's children. @c wxWindowList
471 is a type-safe wxList-like class whose elements are of type @c wxWindow*.
472 */
473 wxWindowList& GetChildren();
474
475 /**
476 @overload
477 */
478 const wxWindowList& GetChildren() const;
479
480 /**
481 Removes a child window.
482
483 This is called automatically by window deletion functions so should not
484 be required by the application programmer.
485 Notice that this function is mostly internal to wxWidgets and shouldn't be
486 called by the user code.
487
488 @param child
489 Child window to remove.
490 */
491 virtual void RemoveChild(wxWindow* child);
492
493 //@}
494
495
496 /**
497 @name Sibling and parent management functions
498 */
499 //@{
500
501 /**
502 Returns the grandparent of a window, or @NULL if there isn't one.
503 */
504 wxWindow* GetGrandParent() const;
505
506 /**
507 Returns the next window after this one among the parent's children or @NULL
508 if this window is the last child.
509
510 @since 2.8.8
511
512 @see GetPrevSibling()
513 */
514 wxWindow* GetNextSibling() const;
515
516 /**
517 Returns the parent of the window, or @NULL if there is no parent.
518 */
519 wxWindow* GetParent() const;
520
521 /**
522 Returns the previous window before this one among the parent's children or @c
523 @NULL if this window is the first child.
524
525 @since 2.8.8
526
527 @see GetNextSibling()
528 */
529 wxWindow* GetPrevSibling() const;
530
531 /**
532 Check if the specified window is a descendant of this one.
533
534 Returns @true if the window is a descendant (i.e. a child or
535 grand-child or grand-grand-child or ...) of this one.
536
537 Notice that a window can never be a descendant of another one if they
538 are in different top level windows, i.e. a child of a wxDialog is not
539 considered to be a descendant of dialogs parent wxFrame.
540
541 @param win Any window, possible @NULL (@false is always returned then).
542
543 @since 2.9.4
544 */
545 bool IsDescendant(wxWindowBase* win) const;
546
547 /**
548 Reparents the window, i.e.\ the window will be removed from its
549 current parent window (e.g. a non-standard toolbar in a wxFrame)
550 and then re-inserted into another.
551
552 Notice that currently you need to explicitly call
553 wxNotebook::RemovePage() before reparenting a notebook page.
554
555 @param newParent
556 New parent.
557 */
558 virtual bool Reparent(wxWindow* newParent);
559
560 //@}
561
562
563 /**
564 @name Scrolling and scrollbars functions
565
566 Note that these methods don't work with native controls which don't use
567 wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
568 */
569 //@{
570
571 /**
572 Call this function to force one or both scrollbars to be always shown, even if
573 the window is big enough to show its entire contents without scrolling.
574
575 @since 2.9.0
576
577 @param hflag
578 Whether the horizontal scroll bar should always be visible.
579 @param vflag
580 Whether the vertical scroll bar should always be visible.
581
582 @remarks This function is currently only implemented under Mac/Carbon.
583 */
584 virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
585
586 /**
587 Returns the built-in scrollbar position.
588
589 @see SetScrollbar()
590 */
591 virtual int GetScrollPos(int orientation) const;
592
593 /**
594 Returns the built-in scrollbar range.
595
596 @see SetScrollbar()
597 */
598 virtual int GetScrollRange(int orientation) const;
599
600 /**
601 Returns the built-in scrollbar thumb size.
602
603 @see SetScrollbar()
604 */
605 virtual int GetScrollThumb(int orientation) const;
606
607 /**
608 Returns @true if this window can have a scroll bar in this orientation.
609
610 @param orient
611 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
612
613 @since 2.9.1
614 */
615 bool CanScroll(int orient) const;
616
617 /**
618 Returns @true if this window currently has a scroll bar for this
619 orientation.
620
621 This method may return @false even when CanScroll() for the same
622 orientation returns @true, but if CanScroll() returns @false, i.e.
623 scrolling in this direction is not enabled at all, HasScrollbar()
624 always returns @false as well.
625
626 @param orient
627 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
628 */
629 bool HasScrollbar(int orient) const;
630
631 /**
632 Return whether a scrollbar is always shown.
633
634 @param orient
635 Orientation to check, either wxHORIZONTAL or wxVERTICAL.
636
637 @see AlwaysShowScrollbars()
638 */
639 virtual bool IsScrollbarAlwaysShown(int orient) const;
640
641 /**
642 Scrolls the window by the given number of lines down (if @a lines is
643 positive) or up.
644
645 @return Returns @true if the window was scrolled, @false if it was already
646 on top/bottom and nothing was done.
647
648 @remarks This function is currently only implemented under MSW and
649 wxTextCtrl under wxGTK (it also works for wxScrolled classes
650 under all platforms).
651
652 @see ScrollPages()
653 */
654 virtual bool ScrollLines(int lines);
655
656 /**
657 Scrolls the window by the given number of pages down (if @a pages is
658 positive) or up.
659
660 @return Returns @true if the window was scrolled, @false if it was already
661 on top/bottom and nothing was done.
662
663 @remarks This function is currently only implemented under MSW and wxGTK.
664
665 @see ScrollLines()
666 */
667 virtual bool ScrollPages(int pages);
668
669 /**
670 Physically scrolls the pixels in the window and move child windows accordingly.
671
672 @param dx
673 Amount to scroll horizontally.
674 @param dy
675 Amount to scroll vertically.
676 @param rect
677 Rectangle to scroll, if it is @NULL, the whole window is
678 scrolled (this is always the case under wxGTK which doesn't support this
679 parameter)
680
681 @remarks Note that you can often use wxScrolled instead of using this
682 function directly.
683 */
684 virtual void ScrollWindow(int dx, int dy,
685 const wxRect* rect = NULL);
686
687 /**
688 Same as #ScrollLines (-1).
689 */
690 bool LineUp();
691
692 /**
693 Same as #ScrollLines (1).
694 */
695 bool LineDown();
696
697 /**
698 Same as #ScrollPages (-1).
699 */
700 bool PageUp();
701
702 /**
703 Same as #ScrollPages (1).
704 */
705 bool PageDown();
706
707 /**
708 Sets the position of one of the built-in scrollbars.
709
710 @param orientation
711 Determines the scrollbar whose position is to be set.
712 May be wxHORIZONTAL or wxVERTICAL.
713 @param pos
714 Position in scroll units.
715 @param refresh
716 @true to redraw the scrollbar, @false otherwise.
717
718 @remarks This function does not directly affect the contents of the
719 window: it is up to the application to take note of
720 scrollbar attributes and redraw contents accordingly.
721
722 @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
723 wxScrolled
724 */
725 virtual void SetScrollPos(int orientation, int pos,
726 bool refresh = true);
727
728 /**
729 Sets the scrollbar properties of a built-in scrollbar.
730
731 @param orientation
732 Determines the scrollbar whose page size is to be set.
733 May be wxHORIZONTAL or wxVERTICAL.
734 @param position
735 The position of the scrollbar in scroll units.
736 @param thumbSize
737 The size of the thumb, or visible portion of the scrollbar, in scroll units.
738 @param range
739 The maximum position of the scrollbar. Value of -1 can be used to
740 ask for the scrollbar to be shown but in the disabled state: this
741 can be used to avoid removing the scrollbar even when it is not
742 needed (currently this is only implemented in wxMSW port).
743 @param refresh
744 @true to redraw the scrollbar, @false otherwise.
745
746 @remarks
747 Let's say you wish to display 50 lines of text, using the same font.
748 The window is sized so that you can only see 16 lines at a time.
749 You would use:
750 @code
751 SetScrollbar(wxVERTICAL, 0, 16, 50);
752 @endcode
753 Note that with the window at this size, the thumb position can never
754 go above 50 minus 16, or 34. You can determine how many lines are
755 currently visible by dividing the current view size by the character
756 height in pixels.
757 When defining your own scrollbar behaviour, you will always need
758 to recalculate the scrollbar settings when the window size changes.
759 You could therefore put your scrollbar calculations and SetScrollbar
760 call into a function named AdjustScrollbars, which can be called
761 initially and also from your wxSizeEvent handler function.
762
763 @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
764 */
765 virtual void SetScrollbar(int orientation, int position,
766 int thumbSize, int range,
767 bool refresh = true);
768 //@}
769
770
771 /**
772 @name Sizing functions
773
774 See also the protected functions DoGetBestSize() and
775 DoGetBestClientSize().
776 */
777 //@{
778
779 /**
780 Helper for ensuring EndRepositioningChildren() is called correctly.
781
782 This class wraps the calls to BeginRepositioningChildren() and
783 EndRepositioningChildren() by performing the former in its constructor
784 and the latter in its destructor if, and only if, the first call
785 returned @true. This is the simplest way to call these methods and if
786 this class is created as a local variable, it also ensures that
787 EndRepositioningChildren() is correctly called (or not) on scope exit,
788 so its use instead of calling these methods manually is highly
789 recommended.
790
791 @since 2.9.5
792 */
793 class ChildrenRepositioningGuard
794 {
795 public:
796 /**
797 Constructor calls wxWindow::BeginRepositioningChildren().
798
799 @param win The window to call BeginRepositioningChildren() on. If
800 it is @NULL, nothing is done.
801 */
802 explicit ChildrenRepositioningGuard(wxWindow* win);
803
804 /**
805 Destructor calls wxWindow::EndRepositioningChildren() if necessary.
806
807 EndRepositioningChildren() is called only if a valid window was
808 passed to the constructor and if BeginRepositioningChildren()
809 returned @true.
810 */
811 ~ChildrenRepositioningGuard();
812 };
813
814 /**
815 Prepare for changing positions of multiple child windows.
816
817 This method should be called before changing positions of multiple
818 child windows to reduce flicker and, in MSW case, even avoid display
819 corruption in some cases. It is used internally by wxWidgets and called
820 automatically when the window size changes but it can also be useful to
821 call it from outside of the library if a repositioning involving
822 multiple children is done without changing the window size.
823
824 If this method returns @true, then EndRepositioningChildren() must be
825 called after setting all children positions. Use
826 ChildrenRepositioningGuard class to ensure that this requirement is
827 satisfied.
828
829 @since 2.9.5
830 */
831 bool BeginRepositioningChildren();
832
833 /**
834 Fix child window positions after setting all of them at once.
835
836 This method must be called if and only if the previous call to
837 BeginRepositioningChildren() returned @true.
838
839 @since 2.9.5
840 */
841 void EndRepositioningChildren();
842
843 /**
844 Sets the cached best size value.
845
846 @see GetBestSize()
847 */
848 void CacheBestSize(const wxSize& size) const;
849
850 /**
851 Converts client area size @a size to corresponding window size.
852
853 In other words, the returned value is what would GetSize() return if this
854 window had client area of given size. Components with wxDefaultCoord
855 value are left unchanged. Note that the conversion is not always
856 exact, it assumes that non-client area doesn't change and so doesn't
857 take into account things like menu bar (un)wrapping or (dis)appearance
858 of the scrollbars.
859
860 @since 2.8.8
861
862 @see WindowToClientSize()
863 */
864 virtual wxSize ClientToWindowSize(const wxSize& size) const;
865
866 /**
867 Converts window size @a size to corresponding client area size
868 In other words, the returned value is what would GetClientSize() return if
869 this window had given window size. Components with wxDefaultCoord value
870 are left unchanged.
871
872 Note that the conversion is not always exact, it assumes that
873 non-client area doesn't change and so doesn't take into account things
874 like menu bar (un)wrapping or (dis)appearance of the scrollbars.
875
876 @since 2.8.8
877
878 @see ClientToWindowSize()
879 */
880 virtual wxSize WindowToClientSize(const wxSize& size) const;
881
882 /**
883 Sizes the window so that it fits around its subwindows.
884
885 This function won't do anything if there are no subwindows and will only really
886 work correctly if sizers are used for the subwindows layout.
887
888 Also, if the window has exactly one subwindow it is better (faster and the result
889 is more precise as Fit() adds some margin to account for fuzziness of its calculations)
890 to call:
891
892 @code
893 window->SetClientSize(child->GetSize());
894 @endcode
895
896 instead of calling Fit().
897
898 @see @ref overview_windowsizing
899 */
900 virtual void Fit();
901
902 /**
903 Similar to Fit(), but sizes the interior (virtual) size of a window.
904
905 Mainly useful with scrolled windows to reset scrollbars after sizing
906 changes that do not trigger a size event, and/or scrolled windows without
907 an interior sizer. This function similarly won't do anything if there are
908 no subwindows.
909 */
910 virtual void FitInside();
911
912 /**
913 This functions returns the best acceptable minimal size for the window.
914
915 For example, for a static control, it will be the minimal size such that the
916 control label is not truncated. For windows containing subwindows (typically
917 wxPanel), the size returned by this function will be the same as the size
918 the window would have had after calling Fit().
919
920 Override virtual DoGetBestSize() or, better, because it's usually more
921 convenient, DoGetBestClientSize() when writing your own custom window
922 class to change the value returned by this public non-virtual method.
923
924 Notice that the best size respects the minimal and maximal size
925 explicitly set for the window, if any. So even if some window believes
926 that it needs 200 pixels horizontally, calling SetMaxSize() with a
927 width of 100 would ensure that GetBestSize() returns the width of at
928 most 100 pixels.
929
930 @see CacheBestSize(), @ref overview_windowsizing
931 */
932 wxSize GetBestSize() const;
933
934 /**
935 Returns the best height needed by this window if it had the given width.
936
937 @see DoGetBestClientHeight()
938
939 @since 2.9.4
940 */
941 int GetBestHeight(int width) const;
942
943 /**
944 Returns the best width needed by this window if it had the given height.
945
946 @see DoGetBestClientWidth()
947
948 @since 2.9.4
949 */
950 int GetBestWidth(int height) const;
951
952 /**
953 Returns the size of the window 'client area' in pixels.
954
955 The client area is the area which may be drawn on by the programmer,
956 excluding title bar, border, scrollbars, etc.
957 Note that if this window is a top-level one and it is currently minimized, the
958 return size is empty (both width and height are 0).
959
960 @beginWxPerlOnly
961 In wxPerl this method takes no parameters and returns
962 a 2-element list (width, height).
963 @endWxPerlOnly
964
965 @see GetSize(), GetVirtualSize()
966 */
967 void GetClientSize(int* width, int* height) const;
968
969 /**
970 @overload
971 */
972 wxSize GetClientSize() const;
973
974 /**
975 Merges the window's best size into the min size and returns the result.
976 This is the value used by sizers to determine the appropriate
977 amount of space to allocate for the widget.
978
979 This is the method called by a wxSizer when it queries the size
980 of a window or control.
981
982 @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
983 */
984 virtual wxSize GetEffectiveMinSize() const;
985
986 /**
987 Returns the maximum size of window's client area.
988
989 This is an indication to the sizer layout mechanism that this is the maximum
990 possible size as well as the upper bound on window's size settable using
991 SetClientSize().
992
993 @see GetMaxSize(), @ref overview_windowsizing
994 */
995 virtual wxSize GetMaxClientSize() const;
996
997 /**
998 Returns the maximum size of the window.
999
1000 This is an indication to the sizer layout mechanism that this is the maximum
1001 possible size as well as the upper bound on window's size settable using SetSize().
1002
1003 @see GetMaxClientSize(), @ref overview_windowsizing
1004 */
1005 virtual wxSize GetMaxSize() const;
1006
1007 /**
1008 Returns the minimum size of window's client area, an indication to the sizer
1009 layout mechanism that this is the minimum required size of its client area.
1010
1011 It normally just returns the value set by SetMinClientSize(), but it can be
1012 overridden to do the calculation on demand.
1013
1014 @see GetMinSize(), @ref overview_windowsizing
1015 */
1016 virtual wxSize GetMinClientSize() const;
1017
1018 /**
1019 Returns the minimum size of the window, an indication to the sizer layout
1020 mechanism that this is the minimum required size.
1021
1022 This method normally just returns the value set by SetMinSize(), but it
1023 can be overridden to do the calculation on demand.
1024
1025 @see GetMinClientSize(), @ref overview_windowsizing
1026 */
1027 virtual wxSize GetMinSize() const;
1028
1029 /**
1030 Returns the horizontal component of window minimal size.
1031
1032 The returned value is wxDefaultCoord if the minimal width was not set.
1033
1034 @see GetMinSize()
1035 */
1036 int GetMinWidth() const;
1037
1038 /**
1039 Returns the vertical component of window minimal size.
1040
1041 The returned value is wxDefaultCoord if the minimal height was not set.
1042
1043 @see GetMinSize()
1044 */
1045 int GetMinHeight() const;
1046
1047 /**
1048 Returns the horizontal component of window maximal size.
1049
1050 The returned value is wxDefaultCoord if the maximal width was not set.
1051
1052 @see GetMaxSize()
1053 */
1054 int GetMaxWidth() const;
1055
1056 /**
1057 Returns the vertical component of window maximal size.
1058
1059 The returned value is wxDefaultCoord if the maximal width was not set.
1060
1061 @see GetMaxSize()
1062 */
1063 int GetMaxHeight() const;
1064
1065 /**
1066 Returns the size of the entire window in pixels, including title bar, border,
1067 scrollbars, etc.
1068
1069 Note that if this window is a top-level one and it is currently minimized, the
1070 returned size is the restored window size, not the size of the window icon.
1071
1072 @param width
1073 Receives the window width.
1074 @param height
1075 Receives the window height.
1076
1077 @beginWxPerlOnly
1078 In wxPerl this method is implemented as GetSizeWH() returning
1079 a 2-element list (width, height).
1080 @endWxPerlOnly
1081
1082 @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
1083 */
1084 void GetSize(int* width, int* height) const;
1085
1086 /**
1087 See the GetSize(int*,int*) overload for more info.
1088 */
1089 wxSize GetSize() const;
1090
1091 /**
1092 This gets the virtual size of the window in pixels.
1093 By default it returns the client size of the window, but after a call to
1094 SetVirtualSize() it will return the size set with that method.
1095
1096 @see @ref overview_windowsizing
1097 */
1098 wxSize GetVirtualSize() const;
1099
1100 /**
1101 Like the other GetVirtualSize() overload but uses pointers instead.
1102
1103 @param width
1104 Receives the window virtual width.
1105 @param height
1106 Receives the window virtual height.
1107 */
1108 void GetVirtualSize(int* width, int* height) const;
1109
1110 /**
1111 Return the largest of ClientSize and BestSize (as determined
1112 by a sizer, interior children, or other means)
1113 */
1114 virtual wxSize GetBestVirtualSize() const;
1115
1116 /**
1117 Returns the magnification of the backing store of this window, eg 2.0
1118 for a window on a retina screen.
1119
1120 @since 2.9.5
1121 */
1122 virtual double GetContentScaleFactor() const;
1123
1124 /**
1125 Returns the size of the left/right and top/bottom borders of this window in x
1126 and y components of the result respectively.
1127 */
1128 virtual wxSize GetWindowBorderSize() const;
1129
1130 /**
1131 wxSizer and friends use this to give a chance to a component to recalc
1132 its min size once one of the final size components is known. Override
1133 this function when that is useful (such as for wxStaticText which can
1134 stretch over several lines). Parameter availableOtherDir
1135 tells the item how much more space there is available in the opposite
1136 direction (-1 if unknown).
1137 */
1138 virtual bool
1139 InformFirstDirection(int direction,
1140 int size,
1141 int availableOtherDir);
1142
1143 /**
1144 Resets the cached best size value so it will be recalculated the next time it
1145 is needed.
1146
1147 @see CacheBestSize()
1148 */
1149 void InvalidateBestSize();
1150
1151 /**
1152 Posts a size event to the window.
1153
1154 This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
1155 */
1156 void PostSizeEvent();
1157
1158 /**
1159 Posts a size event to the parent of this window.
1160
1161 This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
1162 argument.
1163 */
1164 void PostSizeEventToParent();
1165
1166 /**
1167 This function sends a dummy @ref wxSizeEvent "size event" to
1168 the window allowing it to re-layout its children positions.
1169
1170 It is sometimes useful to call this function after adding or deleting a
1171 children after the frame creation or if a child size changes. Note that
1172 if the frame is using either sizers or constraints for the children
1173 layout, it is enough to call wxWindow::Layout() directly and this
1174 function should not be used in this case.
1175
1176 If @a flags includes @c wxSEND_EVENT_POST value, this function posts
1177 the event, i.e. schedules it for later processing, instead of
1178 dispatching it directly. You can also use PostSizeEvent() as a more
1179 readable equivalent of calling this function with this flag.
1180
1181 @param flags
1182 May include @c wxSEND_EVENT_POST. Default value is 0.
1183 */
1184 virtual void SendSizeEvent(int flags = 0);
1185
1186 /**
1187 Safe wrapper for GetParent()->SendSizeEvent().
1188
1189 This function simply checks that the window has a valid parent which is
1190 not in process of being deleted and calls SendSizeEvent() on it. It is
1191 used internally by windows such as toolbars changes to whose state
1192 should result in parent re-layout (e.g. when a toolbar is added to the
1193 top of the window, all the other windows must be shifted down).
1194
1195 @see PostSizeEventToParent()
1196
1197 @param flags
1198 See description of this parameter in SendSizeEvent() documentation.
1199 */
1200 void SendSizeEventToParent(int flags = 0);
1201
1202 /**
1203 This sets the size of the window client area in pixels.
1204
1205 Using this function to size a window tends to be more device-independent
1206 than SetSize(), since the application need not worry about what dimensions
1207 the border or title bar have when trying to fit the window around panel
1208 items, for example.
1209
1210 @see @ref overview_windowsizing
1211 */
1212 void SetClientSize(int width, int height);
1213
1214 /**
1215 @overload
1216 */
1217 void SetClientSize(const wxSize& size);
1218
1219 /**
1220 @overload
1221 */
1222 void SetClientSize(const wxRect& rect);
1223
1224 /**
1225 This normally does not need to be called by user code.
1226 It is called when a window is added to a sizer, and is used so the window
1227 can remove itself from the sizer when it is destroyed.
1228 */
1229 void SetContainingSizer(wxSizer* sizer);
1230
1231 /**
1232 A @e smart SetSize that will fill in default size components with the
1233 window's @e best size values.
1234
1235 Also sets the window's minsize to the value passed in for use with sizers.
1236 This means that if a full or partial size is passed to this function then
1237 the sizers will use that size instead of the results of GetBestSize() to
1238 determine the minimum needs of the window for layout.
1239
1240 Most controls will use this to set their initial size, and their min
1241 size to the passed in value (if any.)
1242
1243 @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
1244 @ref overview_windowsizing
1245 */
1246 void SetInitialSize(const wxSize& size = wxDefaultSize);
1247
1248 /**
1249 Sets the maximum client size of the window, to indicate to the sizer
1250 layout mechanism that this is the maximum possible size of its client area.
1251
1252 Note that this method is just a shortcut for:
1253 @code
1254 SetMaxSize(ClientToWindowSize(size));
1255 @endcode
1256
1257 @see SetMaxSize(), @ref overview_windowsizing
1258 */
1259 virtual void SetMaxClientSize(const wxSize& size);
1260
1261 /**
1262 Sets the maximum size of the window, to indicate to the sizer layout mechanism
1263 that this is the maximum possible size.
1264
1265 @see SetMaxClientSize(), @ref overview_windowsizing
1266 */
1267 virtual void SetMaxSize(const wxSize& size);
1268
1269 /**
1270 Sets the minimum client size of the window, to indicate to the sizer
1271 layout mechanism that this is the minimum required size of window's client
1272 area.
1273
1274 You may need to call this if you change the window size after
1275 construction and before adding to its parent sizer.
1276
1277 Note, that just as with SetMinSize(), calling this method doesn't
1278 prevent the program from explicitly making the window smaller than the
1279 specified size.
1280
1281 Note that this method is just a shortcut for:
1282 @code
1283 SetMinSize(ClientToWindowSize(size));
1284 @endcode
1285
1286 @see SetMinSize(), @ref overview_windowsizing
1287 */
1288 virtual void SetMinClientSize(const wxSize& size);
1289
1290 /**
1291 Sets the minimum size of the window, to indicate to the sizer layout
1292 mechanism that this is the minimum required size.
1293
1294 You may need to call this if you change the window size after
1295 construction and before adding to its parent sizer.
1296
1297 Notice that calling this method doesn't prevent the program from making
1298 the window explicitly smaller than the specified size by calling
1299 SetSize(), it just ensures that it won't become smaller than this size
1300 during the automatic layout.
1301
1302 @see SetMinClientSize(), @ref overview_windowsizing
1303 */
1304 virtual void SetMinSize(const wxSize& size);
1305
1306 /**
1307 Sets the size of the window in pixels.
1308
1309 @param x
1310 Required x position in pixels, or wxDefaultCoord to indicate that the
1311 existing value should be used.
1312 @param y
1313 Required y position in pixels, or wxDefaultCoord to indicate that the
1314 existing value should be used.
1315 @param width
1316 Required width in pixels, or wxDefaultCoord to indicate that the existing
1317 value should be used.
1318 @param height
1319 Required height position in pixels, or wxDefaultCoord to indicate that the
1320 existing value should be used.
1321 @param sizeFlags
1322 Indicates the interpretation of other parameters.
1323 It is a bit list of the following:
1324 - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
1325 a wxWidgets-supplied default width.
1326 - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
1327 a wxWidgets-supplied default height.
1328 - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
1329 a wxWidgets-supplied default size.
1330 - @c wxSIZE_USE_EXISTING: existing dimensions should be used
1331 if wxDefaultCoord values are supplied.
1332 - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
1333 wxDefaultCoord) to be interpreted as real
1334 dimensions, not default values.
1335 - @c wxSIZE_FORCE: normally, if the position and the size of the window are
1336 already the same as the parameters of this function,
1337 nothing is done. but with this flag a window resize may
1338 be forced even in this case (supported in wx 2.6.2 and
1339 later and only implemented for MSW and ignored elsewhere
1340 currently).
1341
1342 @remarks This overload sets the position and optionally size, of the window.
1343 Parameters may be wxDefaultCoord to indicate either that a default
1344 should be supplied by wxWidgets, or that the current value of the
1345 dimension should be used.
1346
1347 @see Move(), @ref overview_windowsizing
1348 */
1349 void SetSize(int x, int y, int width, int height,
1350 int sizeFlags = wxSIZE_AUTO);
1351
1352 /**
1353 Sets the size of the window in pixels.
1354 The size is specified using a wxRect, wxSize or by a couple of @c int objects.
1355
1356 @remarks This form must be used with non-default width and height values.
1357
1358 @see Move(), @ref overview_windowsizing
1359 */
1360 void SetSize(const wxRect& rect);
1361
1362 /**
1363 @overload
1364 */
1365 void SetSize(const wxSize& size);
1366
1367 /**
1368 @overload
1369 */
1370 void SetSize(int width, int height);
1371
1372 /**
1373 Use of this function for windows which are not toplevel windows
1374 (such as wxDialog or wxFrame) is discouraged.
1375 Please use SetMinSize() and SetMaxSize() instead.
1376
1377 @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
1378 */
1379 virtual void SetSizeHints( const wxSize& minSize,
1380 const wxSize& maxSize=wxDefaultSize,
1381 const wxSize& incSize=wxDefaultSize);
1382 virtual void SetSizeHints( int minW, int minH,
1383 int maxW = -1, int maxH = -1,
1384 int incW = -1, int incH = -1 );
1385
1386 /**
1387 Sets the virtual size of the window in pixels.
1388
1389 @see @ref overview_windowsizing
1390 */
1391 void SetVirtualSize(int width, int height);
1392
1393 /**
1394 @overload
1395 */
1396 void SetVirtualSize(const wxSize& size);
1397
1398 //@}
1399
1400
1401 /**
1402 @name Positioning functions
1403 */
1404 //@{
1405
1406 /**
1407 A synonym for Centre().
1408 */
1409 void Center(int dir = wxBOTH);
1410
1411 /**
1412 A synonym for CentreOnParent().
1413 */
1414 void CenterOnParent(int dir = wxBOTH);
1415
1416 /**
1417 Centres the window.
1418
1419 @param direction
1420 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1421 or wxBOTH. It may also include the wxCENTRE_ON_SCREEN flag
1422 if you want to centre the window on the entire screen and not on its
1423 parent window.
1424
1425 @remarks If the window is a top level one (i.e. doesn't have a parent),
1426 it will be centred relative to the screen anyhow.
1427
1428 @see Center()
1429 */
1430 void Centre(int direction = wxBOTH);
1431
1432 /**
1433 Centres the window on its parent. This is a more readable synonym for Centre().
1434
1435 @param direction
1436 Specifies the direction for the centring. May be wxHORIZONTAL, wxVERTICAL
1437 or wxBOTH.
1438
1439 @remarks This methods provides for a way to centre top level windows over
1440 their parents instead of the entire screen. If there
1441 is no parent or if the window is not a top level
1442 window, then behaviour is the same as Centre().
1443
1444 @see wxTopLevelWindow::CentreOnScreen
1445 */
1446 void CentreOnParent(int direction = wxBOTH);
1447
1448 /**
1449 This gets the position of the window in pixels, relative to the parent window
1450 for the child windows or relative to the display origin for the top level windows.
1451
1452 @param x
1453 Receives the x position of the window if non-@NULL.
1454 @param y
1455 Receives the y position of the window if non-@NULL.
1456
1457 @beginWxPerlOnly
1458 In wxPerl this method is implemented as GetPositionXY() returning
1459 a 2-element list (x, y).
1460 @endWxPerlOnly
1461
1462 @see GetScreenPosition()
1463 */
1464 void GetPosition(int* x, int* y) const;
1465
1466 /**
1467 This gets the position of the window in pixels, relative to the parent window
1468 for the child windows or relative to the display origin for the top level windows.
1469
1470 @see GetScreenPosition()
1471 */
1472 wxPoint GetPosition() const;
1473
1474 /**
1475 Returns the position and size of the window as a wxRect object.
1476
1477 @see GetScreenRect()
1478 */
1479 wxRect GetRect() const;
1480
1481 /**
1482 Returns the window position in screen coordinates, whether the window is a
1483 child window or a top level one.
1484
1485 @param x
1486 Receives the x position of the window on the screen if non-@NULL.
1487 @param y
1488 Receives the y position of the window on the screen if non-@NULL.
1489
1490 @see GetPosition()
1491 */
1492 void GetScreenPosition(int* x, int* y) const;
1493
1494 /**
1495 Returns the window position in screen coordinates, whether the window is a
1496 child window or a top level one.
1497
1498 @see GetPosition()
1499 */
1500 wxPoint GetScreenPosition() const;
1501
1502 /**
1503 Returns the position and size of the window on the screen as a wxRect object.
1504
1505 @see GetRect()
1506 */
1507 wxRect GetScreenRect() const;
1508
1509 /**
1510 Get the origin of the client area of the window relative to the
1511 window top left corner (the client area may be shifted because of
1512 the borders, scrollbars, other decorations...)
1513 */
1514 virtual wxPoint GetClientAreaOrigin() const;
1515
1516 /**
1517 Get the client rectangle in window (i.e.\ client) coordinates
1518 */
1519 wxRect GetClientRect() const;
1520
1521
1522
1523 /**
1524 Moves the window to the given position.
1525
1526 @param x
1527 Required x position.
1528 @param y
1529 Required y position.
1530 @param flags
1531 See SetSize() for more info about this parameter.
1532
1533 @remarks Implementations of SetSize can also implicitly implement the
1534 Move() function, which is defined in the base wxWindow class as the call:
1535 @code
1536 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1537 @endcode
1538
1539 @see SetSize()
1540 */
1541 void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);
1542
1543 /**
1544 Moves the window to the given position.
1545
1546 @param pt
1547 wxPoint object representing the position.
1548 @param flags
1549 See SetSize() for more info about this parameter.
1550
1551 @remarks Implementations of SetSize() can also implicitly implement the
1552 Move() function, which is defined in the base wxWindow class as the call:
1553 @code
1554 SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
1555 @endcode
1556
1557 @see SetSize()
1558 */
1559 void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
1560
1561 void SetPosition(const wxPoint& pt);
1562
1563 //@}
1564
1565
1566 /**
1567 @name Coordinate conversion functions
1568 */
1569 //@{
1570
1571 /**
1572 Converts to screen coordinates from coordinates relative to this window.
1573
1574 @param x
1575 A pointer to a integer value for the x coordinate. Pass the client
1576 coordinate in, and a screen coordinate will be passed out.
1577 @param y
1578 A pointer to a integer value for the y coordinate. Pass the client
1579 coordinate in, and a screen coordinate will be passed out.
1580
1581 @beginWxPerlOnly
1582 In wxPerl this method returns a 2-element list instead of
1583 modifying its parameters.
1584 @endWxPerlOnly
1585 */
1586 void ClientToScreen(int* x, int* y) const;
1587
1588 /**
1589 Converts to screen coordinates from coordinates relative to this window.
1590
1591 @param pt
1592 The client position for the second form of the function.
1593 */
1594 wxPoint ClientToScreen(const wxPoint& pt) const;
1595
1596 /**
1597 Converts a point or size from dialog units to pixels.
1598
1599 For the x dimension, the dialog units are multiplied by the average character
1600 width and then divided by 4.
1601 For the y dimension, the dialog units are multiplied by the average character
1602 height and then divided by 8.
1603
1604 @remarks Dialog units are used for maintaining a dialog's proportions
1605 even if the font changes.
1606 You can also use these functions programmatically.
1607 A convenience macro is defined:
1608 @code
1609 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
1610 @endcode
1611
1612 @see ConvertPixelsToDialog()
1613 */
1614 wxPoint ConvertDialogToPixels(const wxPoint& pt) const;
1615
1616 /**
1617 @overload
1618 */
1619 wxSize ConvertDialogToPixels(const wxSize& sz) const;
1620
1621 /**
1622 Converts a point or size from pixels to dialog units.
1623
1624 For the x dimension, the pixels are multiplied by 4 and then divided by the
1625 average character width.
1626 For the y dimension, the pixels are multiplied by 8 and then divided by the
1627 average character height.
1628
1629 @remarks Dialog units are used for maintaining a dialog's proportions
1630 even if the font changes.
1631
1632 @see ConvertDialogToPixels()
1633 */
1634 wxPoint ConvertPixelsToDialog(const wxPoint& pt) const;
1635
1636 /**
1637 @overload
1638 */
1639 wxSize ConvertPixelsToDialog(const wxSize& sz) const;
1640
1641 /**
1642 Converts from screen to client window coordinates.
1643
1644 @param x
1645 Stores the screen x coordinate and receives the client x coordinate.
1646 @param y
1647 Stores the screen x coordinate and receives the client x coordinate.
1648 */
1649 void ScreenToClient(int* x, int* y) const;
1650
1651 /**
1652 Converts from screen to client window coordinates.
1653
1654 @param pt
1655 The screen position.
1656 */
1657 wxPoint ScreenToClient(const wxPoint& pt) const;
1658
1659 //@}
1660
1661
1662 /**
1663 @name Drawing-related functions
1664 */
1665 //@{
1666
1667 /**
1668 Clears the window by filling it with the current background colour.
1669
1670 Does not cause an erase background event to be generated.
1671
1672 Notice that this uses wxClientDC to draw on the window and the results
1673 of doing it while also drawing on wxPaintDC for this window are
1674 undefined. Hence this method shouldn't be used from EVT_PAINT handlers,
1675 just use wxDC::Clear() on the wxPaintDC you already use there instead.
1676 */
1677 virtual void ClearBackground();
1678
1679 /**
1680 Freezes the window or, in other words, prevents any updates from taking
1681 place on screen, the window is not redrawn at all.
1682
1683 Thaw() must be called to reenable window redrawing. Calls to these two
1684 functions may be nested but to ensure that the window is properly
1685 repainted again, you must thaw it exactly as many times as you froze it.
1686
1687 If the window has any children, they are recursively frozen too.
1688
1689 This method is useful for visual appearance optimization (for example,
1690 it is a good idea to use it before doing many large text insertions in
1691 a row into a wxTextCtrl under wxGTK) but is not implemented on all
1692 platforms nor for all controls so it is mostly just a hint to wxWidgets
1693 and not a mandatory directive.
1694
1695 @see wxWindowUpdateLocker, Thaw(), IsFrozen()
1696 */
1697 void Freeze();
1698
1699 /**
1700 Re-enables window updating after a previous call to Freeze().
1701
1702 To really thaw the control, it must be called exactly the same number
1703 of times as Freeze().
1704
1705 If the window has any children, they are recursively thawed too.
1706
1707 @see wxWindowUpdateLocker, Freeze(), IsFrozen()
1708 */
1709 void Thaw();
1710
1711 /**
1712 Returns @true if the window is currently frozen by a call to Freeze().
1713
1714 @see Freeze(), Thaw()
1715 */
1716 bool IsFrozen() const;
1717
1718 /**
1719 Returns the background colour of the window.
1720
1721 @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
1722 */
1723 wxColour GetBackgroundColour() const;
1724
1725 /**
1726 Returns the background style of the window.
1727
1728 @see SetBackgroundColour(), GetForegroundColour(),
1729 SetBackgroundStyle(), SetTransparent()
1730 */
1731 virtual wxBackgroundStyle GetBackgroundStyle() const;
1732
1733 /**
1734 Returns the character height for this window.
1735 */
1736 virtual int GetCharHeight() const;
1737
1738 /**
1739 Returns the average character width for this window.
1740 */
1741 virtual int GetCharWidth() const;
1742
1743 /**
1744 Currently this is the same as calling
1745 wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
1746
1747 One advantage of using this function compared to the static version is that
1748 the call is automatically dispatched to the correct class (as usual with
1749 virtual functions) and you don't have to specify the class name explicitly.
1750
1751 The other one is that in the future this function could return different
1752 results, for example it might return a different font for an "Ok" button
1753 than for a generic button if the users GUI is configured to show such buttons
1754 in bold font. Of course, the down side is that it is impossible to call this
1755 function without actually having an object to apply it to whereas the static
1756 version can be used without having to create an object first.
1757 */
1758 virtual wxVisualAttributes GetDefaultAttributes() const;
1759
1760 /**
1761 Returns the font for this window.
1762
1763 @see SetFont()
1764 */
1765 wxFont GetFont() const;
1766
1767 /**
1768 Returns the foreground colour of the window.
1769
1770 @remarks The meaning of foreground colour varies according to the window class;
1771 it may be the text colour or other colour, or it may not be used at all.
1772
1773 @see SetForegroundColour(), SetBackgroundColour(),
1774 GetBackgroundColour()
1775 */
1776 wxColour GetForegroundColour() const;
1777
1778 /**
1779 Gets the dimensions of the string as it would be drawn on the
1780 window with the currently selected font.
1781
1782 The text extent is returned in the @a w and @a h pointers.
1783
1784 @param string
1785 String whose extent is to be measured.
1786 @param w
1787 Return value for width.
1788 @param h
1789 Return value for height.
1790 @param descent
1791 Return value for descent (optional).
1792 @param externalLeading
1793 Return value for external leading (optional).
1794 @param font
1795 Font to use instead of the current window font (optional).
1796
1797 @beginWxPerlOnly
1798 In wxPerl this method takes only the @a string and optionally
1799 @a font parameters, and returns a 4-element list
1800 (x, y, descent, externalLeading).
1801 @endWxPerlOnly
1802 */
1803 void GetTextExtent(const wxString& string,
1804 int* w, int* h,
1805 int* descent = NULL,
1806 int* externalLeading = NULL,
1807 const wxFont* font = NULL) const;
1808
1809 /**
1810 Gets the dimensions of the string as it would be drawn on the
1811 window with the currently selected font.
1812 */
1813 wxSize GetTextExtent(const wxString& string) const;
1814
1815 /**
1816 Returns the region specifying which parts of the window have been damaged.
1817 Should only be called within an wxPaintEvent handler.
1818
1819 @see wxRegion, wxRegionIterator
1820 */
1821 const wxRegion& GetUpdateRegion() const;
1822
1823 /**
1824 Get the update rectangle bounding box in client coords
1825 */
1826 wxRect GetUpdateClientRect() const;
1827
1828 /**
1829 Returns @true if this window background is transparent (as, for example,
1830 for wxStaticText) and should show the parent window background.
1831
1832 This method is mostly used internally by the library itself and you normally
1833 shouldn't have to call it. You may, however, have to override it in your
1834 wxWindow-derived class to ensure that background is painted correctly.
1835 */
1836 virtual bool HasTransparentBackground();
1837
1838 /**
1839 Causes this window, and all of its children recursively (except under wxGTK1
1840 where this is not implemented), to be repainted. Note that repainting doesn't
1841 happen immediately but only during the next event loop iteration, if you need
1842 to update the window immediately you should use Update() instead.
1843
1844 @param eraseBackground
1845 If @true, the background will be erased.
1846 @param rect
1847 If non-@NULL, only the given rectangle will be treated as damaged.
1848
1849 @see RefreshRect()
1850 */
1851 virtual void Refresh(bool eraseBackground = true,
1852 const wxRect* rect = NULL);
1853
1854 /**
1855 Redraws the contents of the given rectangle: only the area inside it will be
1856 repainted.
1857
1858 This is the same as Refresh() but has a nicer syntax as it can be called
1859 with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
1860 */
1861 void RefreshRect(const wxRect& rect, bool eraseBackground = true);
1862
1863 /**
1864 Calling this method immediately repaints the invalidated area of the window and
1865 all of its children recursively (this normally only happens when the
1866 flow of control returns to the event loop).
1867
1868 Notice that this function doesn't invalidate any area of the window so
1869 nothing happens if nothing has been invalidated (i.e. marked as requiring
1870 a redraw). Use Refresh() first if you want to immediately redraw the
1871 window unconditionally.
1872 */
1873 virtual void Update();
1874
1875 /**
1876 Sets the background colour of the window.
1877
1878 Notice that as with SetForegroundColour(), setting the background
1879 colour of a native control may not affect the entire control and could
1880 be not supported at all depending on the control and platform.
1881
1882 Please see InheritAttributes() for explanation of the difference between
1883 this method and SetOwnBackgroundColour().
1884
1885 @param colour
1886 The colour to be used as the background colour; pass
1887 wxNullColour to reset to the default colour.
1888 Note that you may want to use wxSystemSettings::GetColour() to retrieve
1889 a suitable colour to use rather than setting an hard-coded one.
1890
1891 @remarks The background colour is usually painted by the default
1892 wxEraseEvent event handler function under Windows and
1893 automatically under GTK.
1894 Note that setting the background colour does not cause an
1895 immediate refresh, so you may wish to call wxWindow::ClearBackground
1896 or wxWindow::Refresh after calling this function.
1897 Using this function will disable attempts to use themes for
1898 this window, if the system supports them. Use with care since
1899 usually the themes represent the appearance chosen by the user
1900 to be used for all applications on the system.
1901
1902 @return @true if the colour was really changed, @false if it was already set
1903 to this colour and nothing was done.
1904
1905 @see GetBackgroundColour(), SetForegroundColour(),
1906 GetForegroundColour(), ClearBackground(),
1907 Refresh(), wxEraseEvent, wxSystemSettings
1908 */
1909 virtual bool SetBackgroundColour(const wxColour& colour);
1910
1911 /**
1912 Sets the background style of the window.
1913
1914 The default background style is @c wxBG_STYLE_ERASE which indicates that
1915 the window background may be erased in @c EVT_ERASE_BACKGROUND handler.
1916 This is a safe, compatibility default; however you may want to change it
1917 to @c wxBG_STYLE_SYSTEM if you don't define any erase background event
1918 handlers at all, to avoid unnecessary generation of erase background
1919 events and always let system erase the background. And you should
1920 change the background style to @c wxBG_STYLE_PAINT if you define an
1921 @c EVT_PAINT handler which completely overwrites the window background as
1922 in this case erasing it previously, either in @c EVT_ERASE_BACKGROUND
1923 handler or in the system default handler, would result in flicker as
1924 the background pixels will be repainted twice every time the window is
1925 redrawn. Do ensure that the background is entirely erased by your
1926 @c EVT_PAINT handler in this case however as otherwise garbage may be left
1927 on screen.
1928
1929 Notice that in previous versions of wxWidgets a common way to work
1930 around the above mentioned flickering problem was to define an empty
1931 @c EVT_ERASE_BACKGROUND handler. Setting background style to
1932 @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
1933 problem.
1934
1935
1936 Under wxGTK and wxOSX, you can use ::wxBG_STYLE_TRANSPARENT to obtain
1937 full transparency of the window background. Note that wxGTK supports
1938 this only since GTK 2.12 with a compositing manager enabled, call
1939 IsTransparentBackgroundSupported() to check whether this is the case.
1940
1941 Also, on order for @c SetBackgroundStyle(wxBG_STYLE_TRANSPARENT) to
1942 work, it must be called before Create(). If you're using your own
1943 wxWindow-derived class you should write your code in the following way:
1944 @code
1945 class MyWidget : public wxWindow
1946 {
1947 public:
1948 MyWidget(wxWindow* parent, ...)
1949 : wxWindow() // Use default ctor here!
1950 {
1951 // Do this first:
1952 SetBackgroundStyle(wxBG_STYLE_TRANSPARENT);
1953
1954 // And really create the window afterwards:
1955 Create(parent, ...);
1956 }
1957 };
1958 @endcode
1959
1960 @see SetBackgroundColour(), GetForegroundColour(),
1961 SetTransparent(), IsTransparentBackgroundSupported()
1962 */
1963 virtual bool SetBackgroundStyle(wxBackgroundStyle style);
1964
1965 /**
1966 Checks whether using transparent background might work.
1967
1968 If this function returns @false, calling SetBackgroundStyle() with
1969 ::wxBG_STYLE_TRANSPARENT is not going to work. If it returns @true,
1970 setting transparent style should normally succeed.
1971
1972 Notice that this function would typically be called on the parent of a
1973 window you want to set transparent background style for as the window
1974 for which this method is called must be fully created.
1975
1976 @param reason
1977 If not @NULL, a reason message is provided if transparency is not
1978 supported.
1979
1980 @return @true if background transparency is supported.
1981
1982 @since 2.9.4
1983 */
1984 virtual bool IsTransparentBackgroundSupported(wxString *reason = NULL) const;
1985
1986 /**
1987 Sets the font for this window. This function should not be called for the
1988 parent window if you don't want its font to be inherited by its children,
1989 use SetOwnFont() instead in this case and see InheritAttributes() for more
1990 explanations.
1991
1992 Please notice that the given font is not automatically used for
1993 wxPaintDC objects associated with this window, you need to
1994 call wxDC::SetFont too. However this font is used by
1995 any standard controls for drawing their text as well as by
1996 GetTextExtent().
1997
1998 @param font
1999 Font to associate with this window, pass
2000 wxNullFont to reset to the default font.
2001
2002 @return @true if the font was really changed, @false if it was already set
2003 to this font and nothing was done.
2004
2005 @see GetFont(), InheritAttributes()
2006 */
2007 virtual bool SetFont(const wxFont& font);
2008
2009 /**
2010 Sets the foreground colour of the window.
2011
2012 The meaning of foreground colour varies according to the window class;
2013 it may be the text colour or other colour, or it may not be used at
2014 all. Additionally, not all native controls support changing their
2015 foreground colour so this method may change their colour only partially
2016 or even not at all.
2017
2018 Please see InheritAttributes() for explanation of the difference between
2019 this method and SetOwnForegroundColour().
2020
2021 @param colour
2022 The colour to be used as the foreground colour; pass
2023 wxNullColour to reset to the default colour.
2024
2025 @return @true if the colour was really changed, @false if it was already set
2026 to this colour and nothing was done.
2027
2028 @see GetForegroundColour(), SetBackgroundColour(),
2029 GetBackgroundColour(), ShouldInheritColours()
2030 */
2031 virtual bool SetForegroundColour(const wxColour& colour);
2032
2033 /**
2034 Sets the background colour of the window but prevents it from being inherited
2035 by the children of this window.
2036
2037 @see SetBackgroundColour(), InheritAttributes()
2038 */
2039 void SetOwnBackgroundColour(const wxColour& colour);
2040
2041 /**
2042 Return @true if this window inherits the background colour from its parent.
2043
2044 @see SetOwnBackgroundColour(), InheritAttributes()
2045 */
2046 bool InheritsBackgroundColour() const;
2047
2048 /**
2049 Return @true if a background colour has been set for this window.
2050 */
2051 bool UseBgCol() const;
2052
2053 /**
2054 Sets the font of the window but prevents it from being inherited by the
2055 children of this window.
2056
2057 @see SetFont(), InheritAttributes()
2058 */
2059 void SetOwnFont(const wxFont& font);
2060
2061 /**
2062 Sets the foreground colour of the window but prevents it from being inherited
2063 by the children of this window.
2064
2065 @see SetForegroundColour(), InheritAttributes()
2066 */
2067 void SetOwnForegroundColour(const wxColour& colour);
2068
2069 /**
2070 @deprecated use wxDC::SetPalette instead.
2071 */
2072 void SetPalette(const wxPalette& pal);
2073
2074 /**
2075 Return @true from here to allow the colours of this window to be changed by
2076 InheritAttributes(). Returning @false forbids inheriting them from the parent window.
2077
2078 The base class version returns @false, but this method is overridden in
2079 wxControl where it returns @true.
2080 */
2081 virtual bool ShouldInheritColours() const;
2082
2083 /**
2084 This function tells a window if it should use the system's "theme" code
2085 to draw the windows' background instead of its own background drawing
2086 code. This does not always have any effect since the underlying platform
2087 obviously needs to support the notion of themes in user defined windows.
2088 One such platform is GTK+ where windows can have (very colourful) backgrounds
2089 defined by a user's selected theme.
2090
2091 Dialogs, notebook pages and the status bar have this flag set to @true
2092 by default so that the default look and feel is simulated best.
2093 */
2094 virtual void SetThemeEnabled(bool enable);
2095
2096 /**
2097 */
2098 virtual bool GetThemeEnabled() const;
2099
2100 /**
2101 Returns @true if the system supports transparent windows and calling
2102 SetTransparent() may succeed. If this function returns @false, transparent
2103 windows are definitely not supported by the current system.
2104 */
2105 virtual bool CanSetTransparent();
2106
2107 /**
2108 Set the transparency of the window. If the system supports transparent windows,
2109 returns @true, otherwise returns @false and the window remains fully opaque.
2110 See also CanSetTransparent().
2111
2112 The parameter @a alpha is in the range 0..255 where 0 corresponds to a
2113 fully transparent window and 255 to the fully opaque one. The constants
2114 @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
2115 */
2116 virtual bool SetTransparent(wxByte alpha);
2117
2118 //@}
2119
2120
2121 /**
2122 @name Event-handling functions
2123
2124 wxWindow allows you to build a (sort of) stack of event handlers which
2125 can be used to override the window's own event handling.
2126 */
2127 //@{
2128
2129 /**
2130 Returns the event handler for this window.
2131 By default, the window is its own event handler.
2132
2133 @see SetEventHandler(), PushEventHandler(),
2134 PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
2135 */
2136 wxEvtHandler* GetEventHandler() const;
2137
2138 /**
2139 This function will generate the appropriate call to Navigate() if the key
2140 event is one normally used for keyboard navigation and return @true in this case.
2141
2142 @return Returns @true if the key pressed was for navigation and was
2143 handled, @false otherwise.
2144
2145 @see Navigate()
2146 */
2147 bool HandleAsNavigationKey(const wxKeyEvent& event);
2148
2149 /**
2150 Shorthand for:
2151 @code
2152 GetEventHandler()->SafelyProcessEvent(event);
2153 @endcode
2154
2155 @see ProcessWindowEvent()
2156 */
2157 bool HandleWindowEvent(wxEvent& event) const;
2158
2159 /**
2160 Convenient wrapper for ProcessEvent().
2161
2162 This is the same as writing @code GetEventHandler()->ProcessEvent(event);
2163 @endcode but more convenient. Notice that ProcessEvent() itself can't
2164 be called for wxWindow objects as it ignores the event handlers
2165 associated with the window; use this function instead.
2166 */
2167 bool ProcessWindowEvent(wxEvent& event);
2168
2169 /**
2170 Wrapper for wxEvtHandler::ProcessEventLocally().
2171
2172 This method is similar to ProcessWindowEvent() but can be used to
2173 search for the event handler only in this window and any event handlers
2174 pushed on top of it. Unlike ProcessWindowEvent() it won't propagate the
2175 event upwards. But it will use the validator and event handlers
2176 associated with this window, if any.
2177
2178 @since 2.9.1
2179 */
2180 bool ProcessWindowEventLocally(wxEvent& event);
2181
2182 /**
2183 Removes and returns the top-most event handler on the event handler stack.
2184
2185 E.g. in the case of:
2186 @image html overview_events_winstack.png
2187 when calling @c W->PopEventHandler(), the event handler @c A will be
2188 removed and @c B will be the first handler of the stack.
2189
2190 Note that it's an error to call this function when no event handlers
2191 were pushed on this window (i.e. when the window itself is its only
2192 event handler).
2193
2194 @param deleteHandler
2195 If this is @true, the handler will be deleted after it is removed
2196 (and the returned value will be @NULL).
2197
2198 @see @ref overview_events_processing
2199 */
2200 wxEvtHandler* PopEventHandler(bool deleteHandler = false);
2201
2202 /**
2203 Pushes this event handler onto the event stack for the window.
2204
2205 An event handler is an object that is capable of processing the events sent
2206 to a window. By default, the window is its own event handler, but an application
2207 may wish to substitute another, for example to allow central implementation
2208 of event-handling for a variety of different window classes.
2209
2210 wxWindow::PushEventHandler allows an application to set up a @e stack
2211 of event handlers, where an event not handled by one event handler is
2212 handed to the next one in the chain.
2213
2214 E.g. if you have two event handlers @c A and @c B and a wxWindow instance
2215 @c W and you call:
2216 @code
2217 W->PushEventHandler(A);
2218 W->PushEventHandler(B);
2219 @endcode
2220 you will end up with the following situation:
2221 @image html overview_events_winstack.png
2222
2223 Note that you can use wxWindow::PopEventHandler to remove the event handler.
2224
2225 @param handler
2226 Specifies the handler to be pushed.
2227 It must not be part of a wxEvtHandler chain; an assert will fail
2228 if it's not unlinked (see wxEvtHandler::IsUnlinked).
2229
2230 @see @ref overview_events_processing
2231 */
2232 void PushEventHandler(wxEvtHandler* handler);
2233
2234 /**
2235 Find the given @a handler in the windows event handler stack and
2236 removes (but does not delete) it from the stack.
2237
2238 See wxEvtHandler::Unlink() for more info.
2239
2240 @param handler
2241 The event handler to remove, must be non-@NULL and
2242 must be present in this windows event handlers stack.
2243
2244 @return Returns @true if it was found and @false otherwise (this also
2245 results in an assert failure so this function should
2246 only be called when the handler is supposed to be there).
2247
2248 @see PushEventHandler(), PopEventHandler()
2249 */
2250 bool RemoveEventHandler(wxEvtHandler* handler);
2251
2252 /**
2253 Sets the event handler for this window.
2254
2255 Note that if you use this function you may want to use as the "next" handler
2256 of @a handler the window itself; in this way when @a handler doesn't process
2257 an event, the window itself will have a chance to do it.
2258
2259 @param handler
2260 Specifies the handler to be set. Cannot be @NULL.
2261
2262 @see @ref overview_events_processing
2263 */
2264 void SetEventHandler(wxEvtHandler* handler);
2265
2266 /**
2267 wxWindows cannot be used to form event handler chains; this function
2268 thus will assert when called.
2269
2270 Note that instead you can use PushEventHandler() or SetEventHandler() to
2271 implement a stack of event handlers to override wxWindow's own
2272 event handling mechanism.
2273 */
2274 virtual void SetNextHandler(wxEvtHandler* handler);
2275
2276 /**
2277 wxWindows cannot be used to form event handler chains; this function
2278 thus will assert when called.
2279
2280 Note that instead you can use PushEventHandler() or SetEventHandler() to
2281 implement a stack of event handlers to override wxWindow's own
2282 event handling mechanism.
2283 */
2284 virtual void SetPreviousHandler(wxEvtHandler* handler);
2285
2286 //@}
2287
2288
2289
2290 /**
2291 @name Window styles functions
2292 */
2293 //@{
2294
2295 /**
2296 Returns the extra style bits for the window.
2297 */
2298 long GetExtraStyle() const;
2299
2300 /**
2301 Gets the window style that was passed to the constructor or Create()
2302 method. GetWindowStyle() is another name for the same function.
2303 */
2304 virtual long GetWindowStyleFlag() const;
2305
2306 /**
2307 See GetWindowStyleFlag() for more info.
2308 */
2309 long GetWindowStyle() const;
2310
2311 /**
2312 Returns @true if the window has the given @a exFlag bit set in its
2313 extra styles.
2314
2315 @see SetExtraStyle()
2316 */
2317 bool HasExtraStyle(int exFlag) const;
2318
2319 /**
2320 Returns @true if the window has the given @a flag bit set.
2321 */
2322 bool HasFlag(int flag) const;
2323
2324 /**
2325 Sets the extra style bits for the window.
2326 The currently defined extra style bits are reported in the class
2327 description.
2328 */
2329 virtual void SetExtraStyle(long exStyle);
2330
2331 /**
2332 Sets the style of the window. Please note that some styles cannot be changed
2333 after the window creation and that Refresh() might need to be called
2334 after changing the others for the change to take place immediately.
2335
2336 See @ref overview_windowstyles "Window styles" for more information about flags.
2337
2338 @see GetWindowStyleFlag()
2339 */
2340 virtual void SetWindowStyleFlag(long style);
2341
2342 /**
2343 See SetWindowStyleFlag() for more info.
2344 */
2345 void SetWindowStyle(long style);
2346
2347 /**
2348 Turns the given @a flag on if it's currently turned off and vice versa.
2349 This function cannot be used if the value of the flag is 0 (which is often
2350 the case for default flags).
2351
2352 Also, please notice that not all styles can be changed after the control
2353 creation.
2354
2355 @return Returns @true if the style was turned on by this function, @false
2356 if it was switched off.
2357
2358 @see SetWindowStyleFlag(), HasFlag()
2359 */
2360 bool ToggleWindowStyle(int flag);
2361
2362 //@}
2363
2364
2365 /**
2366 @name Tab order functions
2367 */
2368 //@{
2369
2370 /**
2371 Moves this window in the tab navigation order after the specified @e win.
2372 This means that when the user presses @c TAB key on that other window,
2373 the focus switches to this window.
2374
2375 Default tab order is the same as creation order, this function and
2376 MoveBeforeInTabOrder() allow to change
2377 it after creating all the windows.
2378
2379 @param win
2380 A sibling of this window which should precede it in tab order,
2381 must not be @NULL
2382 */
2383 void MoveAfterInTabOrder(wxWindow* win);
2384
2385 /**
2386 Same as MoveAfterInTabOrder() except that it inserts this window just
2387 before @a win instead of putting it right after it.
2388 */
2389 void MoveBeforeInTabOrder(wxWindow* win);
2390
2391 /**
2392 Performs a keyboard navigation action starting from this window.
2393 This method is equivalent to calling NavigateIn() method on the
2394 parent window.
2395
2396 @param flags
2397 A combination of wxNavigationKeyEvent::IsForward and
2398 wxNavigationKeyEvent::WinChange.
2399
2400 @return Returns @true if the focus was moved to another window or @false
2401 if nothing changed.
2402
2403 @remarks You may wish to call this from a text control custom keypress
2404 handler to do the default navigation behaviour for the
2405 tab key, since the standard default behaviour for a
2406 multiline text control with the wxTE_PROCESS_TAB style
2407 is to insert a tab and not navigate to the next
2408 control. See also wxNavigationKeyEvent and
2409 HandleAsNavigationKey.
2410 */
2411 bool Navigate(int flags = wxNavigationKeyEvent::IsForward);
2412
2413 /**
2414 Performs a keyboard navigation action inside this window.
2415 See Navigate() for more information.
2416 */
2417 bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward);
2418
2419 //@}
2420
2421
2422
2423 /**
2424 @name Z order functions
2425 */
2426 //@{
2427
2428 /**
2429 Lowers the window to the bottom of the window hierarchy (Z-order).
2430
2431 @remarks
2432 This function only works for wxTopLevelWindow-derived classes.
2433
2434 @see Raise()
2435 */
2436 virtual void Lower();
2437
2438 /**
2439 Raises the window to the top of the window hierarchy (Z-order).
2440
2441 Notice that this function only requests the window manager to raise
2442 this window to the top of Z-order. Depending on its configuration, the
2443 window manager may raise the window, not do it at all or indicate that
2444 a window requested to be raised in some other way, e.g. by flashing its
2445 icon if it is minimized.
2446
2447 @remarks
2448 This function only works for wxTopLevelWindow-derived classes.
2449
2450 @see Lower()
2451 */
2452 virtual void Raise();
2453
2454 //@}
2455
2456
2457 /**
2458 @name Window status functions
2459 */
2460 //@{
2461
2462
2463 /**
2464 Equivalent to calling wxWindow::Show(@false).
2465 */
2466 bool Hide();
2467
2468 /**
2469 This function hides a window, like Hide(), but using a special visual
2470 effect if possible.
2471
2472 The parameters of this function are the same as for ShowWithEffect(),
2473 please see their description there.
2474
2475 @since 2.9.0
2476 */
2477 virtual bool HideWithEffect(wxShowEffect effect,
2478 unsigned int timeout = 0);
2479 /**
2480 Returns @true if the window is enabled, i.e.\ if it accepts user input,
2481 @false otherwise.
2482
2483 Notice that this method can return @false even if this window itself hadn't
2484 been explicitly disabled when one of its parent windows is disabled.
2485 To get the intrinsic status of this window, use IsThisEnabled()
2486
2487 @see Enable()
2488 */
2489 bool IsEnabled() const;
2490
2491 /**
2492 Returns @true if the given point or rectangle area has been exposed since the
2493 last repaint. Call this in an paint event handler to optimize redrawing by
2494 only redrawing those areas, which have been exposed.
2495 */
2496 bool IsExposed(int x, int y) const;
2497
2498 /**
2499 @overload
2500 */
2501 bool IsExposed(wxPoint& pt) const;
2502
2503 /**
2504 @overload
2505 */
2506 bool IsExposed(int x, int y, int w, int h) const;
2507
2508 /**
2509 @overload
2510 */
2511 bool IsExposed(wxRect& rect) const;
2512 /**
2513 Returns @true if the window is shown, @false if it has been hidden.
2514
2515 @see IsShownOnScreen()
2516 */
2517 virtual bool IsShown() const;
2518
2519 /**
2520 Returns @true if the window is physically visible on the screen, i.e.\ it
2521 is shown and all its parents up to the toplevel window are shown as well.
2522
2523 @see IsShown()
2524 */
2525 virtual bool IsShownOnScreen() const;
2526
2527 /**
2528 Disables the window. Same as @ref Enable() Enable(@false).
2529
2530 @return Returns @true if the window has been disabled, @false if it had
2531 been already disabled before the call to this function.
2532 */
2533 bool Disable();
2534
2535 /**
2536 Enable or disable the window for user input. Note that when a parent window is
2537 disabled, all of its children are disabled as well and they are reenabled again
2538 when the parent is.
2539
2540 @param enable
2541 If @true, enables the window for input. If @false, disables the window.
2542
2543 @return Returns @true if the window has been enabled or disabled, @false
2544 if nothing was done, i.e. if the window had already
2545 been in the specified state.
2546
2547 @see IsEnabled(), Disable(), wxRadioBox::Enable
2548 */
2549 virtual bool Enable(bool enable = true);
2550
2551 /**
2552 Shows or hides the window. You may need to call Raise()
2553 for a top level window if you want to bring it to top, although this is not
2554 needed if Show() is called immediately after the frame creation.
2555
2556 Notice that the default state of newly created top level windows is hidden
2557 (to allow you to create their contents without flicker) unlike for
2558 all the other, not derived from wxTopLevelWindow, windows that
2559 are by default created in the shown state.
2560
2561 @param show
2562 If @true displays the window. Otherwise, hides it.
2563
2564 @return @true if the window has been shown or hidden or @false if nothing
2565 was done because it already was in the requested state.
2566
2567 @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
2568 */
2569 virtual bool Show(bool show = true);
2570
2571 /**
2572 This function shows a window, like Show(), but using a special visual
2573 effect if possible.
2574
2575 @param effect
2576 The effect to use.
2577
2578 @param timeout
2579 The @a timeout parameter specifies the time of the animation, in
2580 milliseconds. If the default value of 0 is used, the default
2581 animation time for the current platform is used.
2582
2583 @note Currently this function is only implemented in wxMSW and wxOSX
2584 (for wxTopLevelWindows only in Carbon version and for any kind of
2585 windows in Cocoa) and does the same thing as Show() in the other
2586 ports.
2587
2588 @since 2.9.0
2589
2590 @see HideWithEffect()
2591 */
2592 virtual bool ShowWithEffect(wxShowEffect effect,
2593 unsigned int timeout = 0);
2594
2595 //@}
2596
2597
2598 /**
2599 @name Context-sensitive help functions
2600 */
2601 //@{
2602
2603 /**
2604 Gets the help text to be used as context-sensitive help for this window.
2605 Note that the text is actually stored by the current wxHelpProvider
2606 implementation, and not in the window object itself.
2607
2608 @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
2609 */
2610 wxString GetHelpText() const;
2611
2612 /**
2613 Sets the help text to be used as context-sensitive help for this window.
2614 Note that the text is actually stored by the current wxHelpProvider
2615 implementation, and not in the window object itself.
2616
2617 @see GetHelpText(), wxHelpProvider::AddHelp()
2618 */
2619 void SetHelpText(const wxString& helpText);
2620
2621 /**
2622 Gets the help text to be used as context-sensitive help for this window.
2623 This method should be overridden if the help message depends on the position
2624 inside the window, otherwise GetHelpText() can be used.
2625
2626 @param point
2627 Coordinates of the mouse at the moment of help event emission.
2628 @param origin
2629 Help event origin, see also wxHelpEvent::GetOrigin.
2630 */
2631 virtual wxString GetHelpTextAtPoint(const wxPoint& point,
2632 wxHelpEvent::Origin origin) const;
2633
2634 /**
2635 Get the associated tooltip or @NULL if none.
2636 */
2637 wxToolTip* GetToolTip() const;
2638
2639 /**
2640 Get the text of the associated tooltip or empty string if none.
2641 */
2642 wxString GetToolTipText() const;
2643
2644 /**
2645 Attach a tooltip to the window.
2646
2647 wxToolTip pointer can be @NULL in the overload taking the pointer,
2648 meaning to unset any existing tooltips; however UnsetToolTip() provides
2649 a more readable alternative to this operation.
2650
2651 Notice that these methods are always available, even if wxWidgets was
2652 compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
2653 case.
2654
2655 @see GetToolTip(), wxToolTip
2656 */
2657 void SetToolTip(const wxString& tipString);
2658
2659 /**
2660 @overload
2661 */
2662 void SetToolTip(wxToolTip* tip);
2663
2664 /**
2665 Unset any existing tooltip.
2666
2667 @since 2.9.0
2668
2669 @see SetToolTip()
2670 */
2671 void UnsetToolTip();
2672
2673 //@}
2674
2675
2676 /**
2677 @name Popup/context menu functions
2678 */
2679 //@{
2680
2681 /**
2682 This function shows a popup menu at the given position in this window and
2683 returns the selected id.
2684
2685 It can be more convenient than the general purpose PopupMenu() function
2686 for simple menus proposing a choice in a list of strings to the user.
2687
2688 Notice that to avoid unexpected conflicts between the (usually
2689 consecutive range of) ids used by the menu passed to this function and
2690 the existing EVT_UPDATE_UI() handlers, this function temporarily
2691 disables UI updates for the window, so you need to manually disable
2692 (or toggle or ...) any items which should be disabled in the menu
2693 before showing it.
2694
2695 The parameter @a menu is the menu to show.
2696 The parameter @a pos (or the parameters @a x and @a y) is the
2697 position at which to show the menu in client coordinates.
2698 It is recommended to not explicitly specify coordinates when
2699 calling this method in response to mouse click, because some of
2700 the ports (namely, wxGTK) can do a better job of positioning
2701 the menu in that case.
2702
2703 @return
2704 The selected menu item id or @c wxID_NONE if none selected or an
2705 error occurred.
2706
2707 @since 2.9.0
2708 */
2709 int GetPopupMenuSelectionFromUser(wxMenu& menu,
2710 const wxPoint& pos = wxDefaultPosition);
2711
2712 /**
2713 @overload
2714 */
2715 int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
2716
2717 /**
2718 Pops up the given menu at the specified coordinates, relative to this
2719 window, and returns control when the user has dismissed the menu.
2720
2721 If a menu item is selected, the corresponding menu event is generated and will be
2722 processed as usual. If coordinates are not specified, the current mouse
2723 cursor position is used.
2724
2725 @a menu is the menu to pop up.
2726
2727 The position where the menu will appear can be specified either as a
2728 wxPoint @a pos or by two integers (@a x and @a y).
2729
2730 @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
2731 ensure that the menu items are in the correct state.
2732 The menu does not get deleted by the window.
2733 It is recommended to not explicitly specify coordinates when
2734 calling PopupMenu in response to mouse click, because some of
2735 the ports (namely, wxGTK) can do a better job of positioning
2736 the menu in that case.
2737
2738 @see wxMenu
2739 */
2740 bool PopupMenu(wxMenu* menu,
2741 const wxPoint& pos = wxDefaultPosition);
2742
2743 /**
2744 @overload
2745 */
2746 bool PopupMenu(wxMenu* menu, int x, int y);
2747
2748 //@}
2749
2750
2751 /**
2752 Validator functions
2753 */
2754 //@{
2755
2756 /**
2757 Returns a pointer to the current validator for the window, or @NULL if
2758 there is none.
2759 */
2760 virtual wxValidator* GetValidator();
2761
2762 /**
2763 Deletes the current validator (if any) and sets the window validator, having
2764 called wxValidator::Clone to create a new validator of this type.
2765 */
2766 virtual void SetValidator(const wxValidator& validator);
2767
2768 /**
2769 Transfers values from child controls to data areas specified by their
2770 validators. Returns @false if a transfer failed.
2771
2772 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2773 the method will also call TransferDataFromWindow() of all child windows.
2774
2775 @see TransferDataToWindow(), wxValidator, Validate()
2776 */
2777 virtual bool TransferDataFromWindow();
2778
2779 /**
2780 Transfers values to child controls from data areas specified by their
2781 validators.
2782
2783 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2784 the method will also call TransferDataToWindow() of all child windows.
2785
2786 @return Returns @false if a transfer failed.
2787
2788 @see TransferDataFromWindow(), wxValidator, Validate()
2789 */
2790 virtual bool TransferDataToWindow();
2791
2792 /**
2793 Validates the current values of the child controls using their validators.
2794 If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
2795 the method will also call Validate() of all child windows.
2796
2797 @return Returns @false if any of the validations failed.
2798
2799 @see TransferDataFromWindow(), TransferDataToWindow(),
2800 wxValidator
2801 */
2802 virtual bool Validate();
2803
2804 //@}
2805
2806
2807 /**
2808 @name wxWindow properties functions
2809 */
2810 //@{
2811
2812 /**
2813 Returns the identifier of the window.
2814
2815 @remarks Each window has an integer identifier. If the application
2816 has not provided one (or the default wxID_ANY) a unique
2817 identifier with a negative value will be generated.
2818
2819 @see SetId(), @ref overview_windowids
2820 */
2821 wxWindowID GetId() const;
2822
2823 /**
2824 Generic way of getting a label from any window, for
2825 identification purposes.
2826
2827 @remarks The interpretation of this function differs from class to class.
2828 For frames and dialogs, the value returned is the
2829 title. For buttons or static text controls, it is the
2830 button text. This function can be useful for
2831 meta-programs (such as testing tools or special-needs
2832 access programs) which need to identify windows by name.
2833 */
2834 virtual wxString GetLabel() const;
2835
2836 /**
2837 Returns the layout direction for this window,
2838 Note that @c wxLayout_Default is returned if layout direction is not supported.
2839 */
2840 virtual wxLayoutDirection GetLayoutDirection() const;
2841
2842 /**
2843 Mirror coordinates for RTL layout if this window uses it and if the
2844 mirroring is not done automatically like Win32.
2845 */
2846 virtual wxCoord AdjustForLayoutDirection(wxCoord x,
2847 wxCoord width,
2848 wxCoord widthTotal) const;
2849
2850 /**
2851 Returns the window's name.
2852
2853 @remarks This name is not guaranteed to be unique; it is up to the
2854 programmer to supply an appropriate name in the window
2855 constructor or via SetName().
2856
2857 @see SetName()
2858 */
2859 virtual wxString GetName() const;
2860
2861 /**
2862 Returns the value previously passed to SetWindowVariant().
2863 */
2864 wxWindowVariant GetWindowVariant() const;
2865
2866 /**
2867 Sets the identifier of the window.
2868
2869 @remarks Each window has an integer identifier. If the application has
2870 not provided one, an identifier will be generated.
2871 Normally, the identifier should be provided on creation
2872 and should not be modified subsequently.
2873
2874 @see GetId(), @ref overview_windowids
2875 */
2876 void SetId(wxWindowID winid);
2877
2878 /**
2879 Sets the window's label.
2880
2881 @param label
2882 The window label.
2883
2884 @see GetLabel()
2885 */
2886 virtual void SetLabel(const wxString& label);
2887
2888 /**
2889 Sets the layout direction for this window.
2890 */
2891 virtual void SetLayoutDirection(wxLayoutDirection dir);
2892
2893 /**
2894 Sets the window's name.
2895
2896 @param name
2897 A name to set for the window.
2898
2899 @see GetName()
2900 */
2901 virtual void SetName(const wxString& name);
2902
2903 /**
2904 This function can be called under all platforms but only does anything under
2905 Mac OS X 10.3+ currently. Under this system, each of the standard control can
2906 exist in several sizes which correspond to the elements of wxWindowVariant enum.
2907
2908 By default the controls use the normal size, of course, but this function can
2909 be used to change this.
2910 */
2911 void SetWindowVariant(wxWindowVariant variant);
2912
2913 /**
2914 Gets the accelerator table for this window. See wxAcceleratorTable.
2915 */
2916 wxAcceleratorTable* GetAcceleratorTable();
2917
2918 /**
2919 Returns the accessible object for this window, if any.
2920 See also wxAccessible.
2921 */
2922 wxAccessible* GetAccessible();
2923
2924 /**
2925 Sets the accelerator table for this window. See wxAcceleratorTable.
2926 */
2927 virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
2928
2929 /**
2930 Sets the accessible for this window. Any existing accessible for this window
2931 will be deleted first, if not identical to @e accessible.
2932 See also wxAccessible.
2933 */
2934 void SetAccessible(wxAccessible* accessible);
2935
2936 //@}
2937
2938
2939 /**
2940 @name Window deletion functions
2941 */
2942 //@{
2943
2944 /**
2945 This function simply generates a wxCloseEvent whose handler usually tries
2946 to close the window. It doesn't close the window itself, however.
2947
2948 @param force
2949 @false if the window's close handler should be able to veto the destruction
2950 of this window, @true if it cannot.
2951
2952 @return @true if the event was handled and not vetoed, @false otherwise.
2953
2954 @remarks Close calls the close handler for the window, providing an
2955 opportunity for the window to choose whether to destroy
2956 the window. Usually it is only used with the top level
2957 windows (wxFrame and wxDialog classes) as the others
2958 are not supposed to have any special OnClose() logic.
2959 The close handler should check whether the window is being deleted
2960 forcibly, using wxCloseEvent::CanVeto, in which case it should
2961 destroy the window using wxWindow::Destroy.
2962 Note that calling Close does not guarantee that the window will
2963 be destroyed; but it provides a way to simulate a manual close
2964 of a window, which may or may not be implemented by destroying
2965 the window. The default implementation of wxDialog::OnCloseWindow
2966 does not necessarily delete the dialog, since it will simply
2967 simulate an wxID_CANCEL event which is handled by the appropriate
2968 button event handler and may do anything at all.
2969 To guarantee that the window will be destroyed, call
2970 wxWindow::Destroy instead
2971
2972 @see @ref overview_windowdeletion "Window Deletion Overview",
2973 Destroy(), wxCloseEvent
2974 */
2975 bool Close(bool force = false);
2976
2977 /**
2978 Destroys the window safely. Use this function instead of the delete operator,
2979 since different window classes can be destroyed differently. Frames and dialogs
2980 are not destroyed immediately when this function is called -- they are added
2981 to a list of windows to be deleted on idle time, when all the window's events
2982 have been processed. This prevents problems with events being sent to
2983 non-existent windows.
2984
2985 @return @true if the window has either been successfully deleted, or it
2986 has been added to the list of windows pending real deletion.
2987 */
2988 virtual bool Destroy();
2989
2990 /**
2991 Returns true if this window is in process of being destroyed.
2992
2993 Top level windows are not deleted immediately but are rather
2994 scheduled for later destruction to give them time to process any
2995 pending messages; see Destroy() description.
2996
2997 This function returns @true if this window, or one of its parent
2998 windows, is scheduled for destruction and can be useful to avoid
2999 manipulating it as it's usually useless to do something with a window
3000 which is on the point of disappearing anyhow.
3001 */
3002 bool IsBeingDeleted() const;
3003
3004 //@}
3005
3006
3007
3008 /**
3009 @name Drag and drop functions
3010 */
3011 //@{
3012
3013 /**
3014 Returns the associated drop target, which may be @NULL.
3015
3016 @see SetDropTarget(), @ref overview_dnd
3017 */
3018 virtual wxDropTarget* GetDropTarget() const;
3019
3020 /**
3021 Associates a drop target with this window.
3022 If the window already has a drop target, it is deleted.
3023
3024 @see GetDropTarget(), @ref overview_dnd
3025 */
3026 virtual void SetDropTarget(wxDropTarget* target);
3027
3028 /**
3029 Enables or disables eligibility for drop file events (OnDropFiles).
3030
3031 @param accept
3032 If @true, the window is eligible for drop file events.
3033 If @false, the window will not accept drop file events.
3034
3035 @remarks Windows only until version 2.8.9, available on all platforms
3036 since 2.8.10. Cannot be used together with SetDropTarget() on
3037 non-Windows platforms.
3038
3039 @see SetDropTarget()
3040 */
3041 virtual void DragAcceptFiles(bool accept);
3042
3043 //@}
3044
3045
3046 /**
3047 @name Constraints, sizers and window layout functions
3048 */
3049 //@{
3050
3051 /**
3052 Returns the sizer of which this window is a member, if any, otherwise @NULL.
3053 */
3054 wxSizer* GetContainingSizer() const;
3055
3056 /**
3057 Returns the sizer associated with the window by a previous call to
3058 SetSizer(), or @NULL.
3059 */
3060 wxSizer* GetSizer() const;
3061
3062 /**
3063 Sets the window to have the given layout sizer.
3064
3065 The window will then own the object, and will take care of its deletion.
3066 If an existing layout constraints object is already owned by the
3067 window, it will be deleted if the @a deleteOld parameter is @true.
3068
3069 Note that this function will also call SetAutoLayout() implicitly with @true
3070 parameter if the @a sizer is non-@NULL and @false otherwise so that the
3071 sizer will be effectively used to layout the window children whenever
3072 it is resized.
3073
3074 @param sizer
3075 The sizer to set. Pass @NULL to disassociate and conditionally delete
3076 the window's sizer. See below.
3077 @param deleteOld
3078 If @true (the default), this will delete any pre-existing sizer.
3079 Pass @false if you wish to handle deleting the old sizer yourself
3080 but remember to do it yourself in this case to avoid memory leaks.
3081
3082 @remarks SetSizer enables and disables Layout automatically.
3083 */
3084 void SetSizer(wxSizer* sizer, bool deleteOld = true);
3085
3086 /**
3087 This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
3088 window size to the size needed to accommodate all sizer elements and sets the
3089 size hints which, if this window is a top level one, prevent the user from
3090 resizing it to be less than this minimal size.
3091 */
3092 void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
3093
3094 /**
3095 Returns a pointer to the window's layout constraints, or @NULL if there are none.
3096 */
3097 wxLayoutConstraints* GetConstraints() const;
3098
3099 /**
3100 Sets the window to have the given layout constraints. The window
3101 will then own the object, and will take care of its deletion.
3102 If an existing layout constraints object is already owned by the
3103 window, it will be deleted.
3104
3105 @param constraints
3106 The constraints to set. Pass @NULL to disassociate and delete the window's
3107 constraints.
3108
3109 @remarks You must call SetAutoLayout() to tell a window to use
3110 the constraints automatically in OnSize; otherwise, you
3111 must override OnSize and call Layout() explicitly. When
3112 setting both a wxLayoutConstraints and a wxSizer, only
3113 the sizer will have effect.
3114 */
3115 void SetConstraints(wxLayoutConstraints* constraints);
3116
3117 /**
3118 Invokes the constraint-based layout algorithm or the sizer-based algorithm
3119 for this window.
3120
3121 This function does not get called automatically when the window is resized
3122 because lots of windows deriving from wxWindow does not need this functionality.
3123 If you want to have Layout() called automatically, you should derive
3124 from wxPanel (see wxPanel::Layout).
3125
3126 @see @ref overview_windowsizing
3127 */
3128 virtual bool Layout();
3129
3130 /**
3131 Determines whether the Layout() function will be called automatically
3132 when the window is resized.
3133
3134 This method is called implicitly by SetSizer() but if you use SetConstraints()
3135 you should call it manually or otherwise the window layout won't be correctly
3136 updated when its size changes.
3137
3138 @param autoLayout
3139 Set this to @true if you wish the Layout() function to be called
3140 automatically when the window is resized.
3141
3142 @see SetSizer(), SetConstraints()
3143 */
3144 void SetAutoLayout(bool autoLayout);
3145
3146 bool GetAutoLayout() const;
3147
3148 //@}
3149
3150
3151
3152 /**
3153 @name Mouse functions
3154 */
3155 //@{
3156
3157 /**
3158 Directs all mouse input to this window.
3159 Call ReleaseMouse() to release the capture.
3160
3161 Note that wxWidgets maintains the stack of windows having captured the mouse
3162 and when the mouse is released the capture returns to the window which had had
3163 captured it previously and it is only really released if there were no previous
3164 window. In particular, this means that you must release the mouse as many times
3165 as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
3166
3167 Any application which captures the mouse in the beginning of some operation
3168 must handle wxMouseCaptureLostEvent and cancel this operation when it receives
3169 the event. The event handler must not recapture mouse.
3170
3171 @see ReleaseMouse(), wxMouseCaptureLostEvent
3172 */
3173 void CaptureMouse();
3174
3175 /**
3176 Returns the caret() associated with the window.
3177 */
3178 wxCaret* GetCaret() const;
3179
3180 /**
3181 Return the cursor associated with this window.
3182
3183 @see SetCursor()
3184 */
3185 const wxCursor& GetCursor() const;
3186
3187 /**
3188 Returns @true if this window has the current mouse capture.
3189
3190 @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
3191 wxMouseCaptureChangedEvent
3192 */
3193 virtual bool HasCapture() const;
3194
3195 /**
3196 Releases mouse input captured with CaptureMouse().
3197
3198 @see CaptureMouse(), HasCapture(), ReleaseMouse(),
3199 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3200 */
3201 void ReleaseMouse();
3202
3203 /**
3204 Sets the caret() associated with the window.
3205 */
3206 void SetCaret(wxCaret* caret);
3207
3208 /**
3209 Sets the window's cursor. Notice that the window cursor also sets it for the
3210 children of the window implicitly.
3211
3212 The @a cursor may be @c wxNullCursor in which case the window cursor will
3213 be reset back to default.
3214
3215 @param cursor
3216 Specifies the cursor that the window should normally display.
3217
3218 @see ::wxSetCursor, wxCursor
3219 */
3220 virtual bool SetCursor(const wxCursor& cursor);
3221
3222 /**
3223 Moves the pointer to the given position on the window.
3224
3225 @note Apple Human Interface Guidelines forbid moving the mouse cursor
3226 programmatically so you should avoid using this function in Mac
3227 applications (and probably avoid using it under the other
3228 platforms without good reason as well).
3229
3230 @param x
3231 The new x position for the cursor.
3232 @param y
3233 The new y position for the cursor.
3234 */
3235 virtual void WarpPointer(int x, int y);
3236
3237 //@}
3238
3239
3240
3241
3242 /**
3243 @name Miscellaneous functions
3244 */
3245 //@{
3246
3247 wxHitTest HitTest(wxCoord x, wxCoord y) const;
3248 wxHitTest HitTest(const wxPoint& pt) const;
3249
3250 /**
3251 Get the window border style from the given flags: this is different from
3252 simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to
3253 translate wxBORDER_DEFAULT to something reasonable
3254 */
3255 wxBorder GetBorder(long flags) const;
3256
3257 /**
3258 Get border for the flags of this window
3259 */
3260 wxBorder GetBorder() const;
3261
3262
3263 /**
3264 Does the window-specific updating after processing the update event.
3265 This function is called by UpdateWindowUI() in order to check return
3266 values in the wxUpdateUIEvent and act appropriately.
3267 For example, to allow frame and dialog title updating, wxWidgets
3268 implements this function as follows:
3269
3270 @code
3271 // do the window-specific processing after processing the update event
3272 void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
3273 {
3274 if ( event.GetSetEnabled() )
3275 Enable(event.GetEnabled());
3276
3277 if ( event.GetSetText() )
3278 {
3279 if ( event.GetText() != GetTitle() )
3280 SetTitle(event.GetText());
3281 }
3282 }
3283 @endcode
3284 */
3285 virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
3286
3287 /**
3288 Returns the platform-specific handle of the physical window.
3289 Cast it to an appropriate handle, such as @b HWND for Windows,
3290 @b Widget for Motif or @b GtkWidget for GTK.
3291
3292 @beginWxPerlOnly
3293 This method will return an integer in wxPerl.
3294 @endWxPerlOnly
3295 */
3296 virtual WXWidget GetHandle() const;
3297
3298 /**
3299 This method should be overridden to return @true if this window has
3300 multiple pages. All standard class with multiple pages such as
3301 wxNotebook, wxListbook and wxTreebook already override it to return @true
3302 and user-defined classes with similar behaviour should also do so, to
3303 allow the library to handle such windows appropriately.
3304 */
3305 virtual bool HasMultiplePages() const;
3306
3307 /**
3308 This function is (or should be, in case of custom controls) called during
3309 window creation to intelligently set up the window visual attributes, that is
3310 the font and the foreground and background colours.
3311
3312 By "intelligently" the following is meant: by default, all windows use their
3313 own @ref GetClassDefaultAttributes() default attributes.
3314 However if some of the parents attributes are explicitly (that is, using
3315 SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
3316 attribute hadn't been explicitly set for this window itself, then this
3317 window takes the same value as used by the parent.
3318 In addition, if the window overrides ShouldInheritColours() to return @false,
3319 the colours will not be changed no matter what and only the font might.
3320
3321 This rather complicated logic is necessary in order to accommodate the
3322 different usage scenarios. The most common one is when all default attributes
3323 are used and in this case, nothing should be inherited as in modern GUIs
3324 different controls use different fonts (and colours) than their siblings so
3325 they can't inherit the same value from the parent. However it was also deemed
3326 desirable to allow to simply change the attributes of all children at once by
3327 just changing the font or colour of their common parent, hence in this case we
3328 do inherit the parents attributes.
3329 */
3330 virtual void InheritAttributes();
3331
3332 /**
3333 Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
3334 to the dialog via validators.
3335 */
3336 virtual void InitDialog();
3337
3338 /**
3339 Returns @true if the window contents is double-buffered by the system, i.e.\ if
3340 any drawing done on the window is really done on a temporary backing surface
3341 and transferred to the screen all at once later.
3342
3343 @see wxBufferedDC
3344 */
3345 virtual bool IsDoubleBuffered() const;
3346
3347 /**
3348 Turn on or off double buffering of the window if the system supports it.
3349 */
3350 void SetDoubleBuffered(bool on);
3351
3352 /**
3353 Returns @true if the window is retained, @false otherwise.
3354
3355 @remarks Retained windows are only available on X platforms.
3356 */
3357 virtual bool IsRetained() const;
3358
3359 /**
3360 Returns @true if this window is intrinsically enabled, @false otherwise,
3361 i.e.\ if @ref Enable() Enable(@false) had been called. This method is
3362 mostly used for wxWidgets itself, user code should normally use
3363 IsEnabled() instead.
3364 */
3365 bool IsThisEnabled() const;
3366
3367 /**
3368 Returns @true if the given window is a top-level one. Currently all frames and
3369 dialogs are considered to be top-level windows (even if they have a parent
3370 window).
3371 */
3372 virtual bool IsTopLevel() const;
3373
3374
3375 /**
3376 This virtual function is normally only used internally, but
3377 sometimes an application may need it to implement functionality
3378 that should not be disabled by an application defining an OnIdle
3379 handler in a derived class.
3380
3381 This function may be used to do delayed painting, for example,
3382 and most implementations call UpdateWindowUI()
3383 in order to send update events to the window in idle time.
3384 */
3385 virtual void OnInternalIdle();
3386
3387 /**
3388 Send idle event to window and all subwindows. Returns true if more idle
3389 time is requested.
3390 */
3391 virtual bool SendIdleEvents(wxIdleEvent& event);
3392
3393 /**
3394 Registers a system wide hotkey. Every time the user presses the hotkey
3395 registered here, this window will receive a hotkey event.
3396
3397 It will receive the event even if the application is in the background
3398 and does not have the input focus because the user is working with some
3399 other application.
3400
3401 @param hotkeyId
3402 Numeric identifier of the hotkey. For applications this must be between 0
3403 and 0xBFFF. If this function is called from a shared DLL, it must be a
3404 system wide unique identifier between 0xC000 and 0xFFFF.
3405 This is a MSW specific detail.
3406 @param modifiers
3407 A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
3408 or wxMOD_WIN specifying the modifier keys that have to be pressed along
3409 with the key.
3410 @param virtualKeyCode
3411 The virtual key code of the hotkey.
3412
3413 @return @true if the hotkey was registered successfully. @false if some
3414 other application already registered a hotkey with this
3415 modifier/virtualKeyCode combination.
3416
3417 @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
3418 event. This function is currently only implemented
3419 under Windows. It is used in the Windows CE port for
3420 detecting hardware button presses.
3421
3422 @see UnregisterHotKey()
3423 */
3424 virtual bool RegisterHotKey(int hotkeyId, int modifiers,
3425 int virtualKeyCode);
3426
3427 /**
3428 Unregisters a system wide hotkey.
3429
3430 @param hotkeyId
3431 Numeric identifier of the hotkey. Must be the same id that was passed to
3432 RegisterHotKey().
3433
3434 @return @true if the hotkey was unregistered successfully, @false if the
3435 id was invalid.
3436
3437 @remarks This function is currently only implemented under MSW.
3438
3439 @see RegisterHotKey()
3440 */
3441 virtual bool UnregisterHotKey(int hotkeyId);
3442
3443 /**
3444 This function sends one or more wxUpdateUIEvent to the window.
3445 The particular implementation depends on the window; for example a
3446 wxToolBar will send an update UI event for each toolbar button,
3447 and a wxFrame will send an update UI event for each menubar menu item.
3448
3449 You can call this function from your application to ensure that your
3450 UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
3451 are concerned). This may be necessary if you have called
3452 wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
3453 the overhead that wxWidgets incurs by sending update UI events in idle time.
3454 @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
3455
3456 If you are calling this function from an OnInternalIdle or OnIdle
3457 function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
3458 this tells the window to only update the UI elements that need
3459 to be updated in idle time. Some windows update their elements
3460 only when necessary, for example when a menu is about to be shown.
3461 The following is an example of how to call UpdateWindowUI from
3462 an idle function.
3463
3464 @code
3465 void MyWindow::OnInternalIdle()
3466 {
3467 if (wxUpdateUIEvent::CanUpdate(this))
3468 UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
3469 }
3470 @endcode
3471
3472 @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle()
3473 */
3474 virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE);
3475
3476 //@}
3477
3478
3479 // NOTE: static functions must have their own group or Doxygen will screw
3480 // up the ordering of the member groups
3481
3482 /**
3483 @name Miscellaneous static functions
3484 */
3485 //@{
3486
3487 /**
3488 Returns the default font and colours which are used by the control.
3489
3490 This is useful if you want to use the same font or colour in your own control
3491 as in a standard control -- which is a much better idea than hard coding specific
3492 colours or fonts which might look completely out of place on the users
3493 system, especially if it uses themes.
3494
3495 The @a variant parameter is only relevant under Mac currently and is
3496 ignore under other platforms. Under Mac, it will change the size of the
3497 returned font. See SetWindowVariant() for more about this.
3498
3499 This static method is "overridden" in many derived classes and so calling,
3500 for example, wxButton::GetClassDefaultAttributes() will typically
3501 return the values appropriate for a button which will be normally different
3502 from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
3503
3504 The @c wxVisualAttributes structure has at least the fields
3505 @c font, @c colFg and @c colBg. All of them may be invalid
3506 if it was not possible to determine the default control appearance or,
3507 especially for the background colour, if the field doesn't make sense as is
3508 the case for @c colBg for the controls with themed background.
3509
3510 @see InheritAttributes()
3511 */
3512 static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
3513
3514 /**
3515 Finds the window or control which currently has the keyboard focus.
3516
3517 @remarks Note that this is a static function, so it can be called without
3518 needing a wxWindow pointer.
3519
3520 @see SetFocus(), HasFocus()
3521 */
3522 static wxWindow* FindFocus();
3523
3524 /**
3525 Find the first window with the given @e id.
3526
3527 If @a parent is @NULL, the search will start from all top-level frames
3528 and dialog boxes; if non-@NULL, the search will be limited to the given
3529 window hierarchy.
3530 The search is recursive in both cases.
3531
3532 @see FindWindow()
3533
3534 @return Window with the given @a id or @NULL if not found.
3535 */
3536 static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
3537
3538 /**
3539 Find a window by its label.
3540
3541 Depending on the type of window, the label may be a window title
3542 or panel item label. If @a parent is @NULL, the search will start from all
3543 top-level frames and dialog boxes; if non-@NULL, the search will be
3544 limited to the given window hierarchy.
3545 The search is recursive in both cases.
3546
3547 @see FindWindow()
3548
3549 @return Window with the given @a label or @NULL if not found.
3550 */
3551 static wxWindow* FindWindowByLabel(const wxString& label,
3552 const wxWindow* parent = 0);
3553
3554 /**
3555 Find a window by its name (as given in a window constructor or Create()
3556 function call).
3557
3558 If @a parent is @NULL, the search will start from all top-level frames
3559 and dialog boxes; if non-@NULL, the search will be limited to the given
3560 window hierarchy.
3561
3562 The search is recursive in both cases. If no window with such name is found,
3563 FindWindowByLabel() is called.
3564
3565 @see FindWindow()
3566
3567 @return Window with the given @a name or @NULL if not found.
3568 */
3569 static wxWindow* FindWindowByName(const wxString& name,
3570 const wxWindow* parent = 0);
3571
3572 /**
3573 Returns the currently captured window.
3574
3575 @see HasCapture(), CaptureMouse(), ReleaseMouse(),
3576 wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
3577 */
3578 static wxWindow* GetCapture();
3579
3580 /**
3581 Create a new ID or range of IDs that are not currently in use.
3582 The IDs will be reserved until assigned to a wxWindow ID
3583 or unreserved with UnreserveControlId().
3584
3585 See @ref overview_windowids for more information.
3586
3587 @param count
3588 The number of sequential IDs to reserve.
3589
3590 @return Returns the ID or the first ID of the range (i.e. the most negative),
3591 or wxID_NONE if the specified number of identifiers couldn't be allocated.
3592
3593 @see UnreserveControlId(), wxIdManager,
3594 @ref overview_windowids
3595 */
3596 static wxWindowID NewControlId(int count = 1);
3597
3598 /**
3599 Unreserve an ID or range of IDs that was reserved by NewControlId().
3600 See @ref overview_windowids for more information.
3601
3602 @param id
3603 The starting ID of the range of IDs to unreserve.
3604 @param count
3605 The number of sequential IDs to unreserve.
3606
3607 @see NewControlId(), wxIdManager, @ref overview_windowids
3608 */
3609 static void UnreserveControlId(wxWindowID id, int count = 1);
3610
3611 //@}
3612
3613
3614
3615protected:
3616
3617 /**
3618 Centres the window.
3619
3620 @param direction
3621 Specifies the direction for the centring. May be wxHORIZONTAL,
3622 wxVERTICAL or wxBOTH. It may also include the wxCENTRE_ON_SCREEN
3623 flag.
3624
3625 @remarks This function is not meant to be called directly by user code,
3626 but via Centre, Center, CentreOnParent, or CenterOnParent.
3627 This function can be overridden to fine-tune centring behaviour.
3628 */
3629 virtual void DoCentre(int direction);
3630
3631 /**
3632 Implementation of GetBestSize() that can be overridden.
3633
3634 Notice that it is usually more convenient to override
3635 DoGetBestClientSize() rather than this method itself as you need to
3636 explicitly account for the window borders size if you do the latter.
3637
3638 The default implementation of this function is designed for use in container
3639 windows, such as wxPanel, and works something like this:
3640 -# If the window has a sizer then it is used to calculate the best size.
3641 -# Otherwise if the window has layout constraints then those are used to
3642 calculate the best size.
3643 -# Otherwise if the window has children then the best size is set to be large
3644 enough to show all the children.
3645 -# Otherwise if there are no children then the window's minimal size will be
3646 used as its best size.
3647 -# Otherwise if there is no minimal size set, then the current size is used
3648 for the best size.
3649
3650 @see @ref overview_windowsizing
3651 */
3652 virtual wxSize DoGetBestSize() const;
3653
3654 /**
3655 Override this method to return the best size for a custom control.
3656
3657 A typical implementation of this method should compute the minimal size
3658 needed to fully display the control contents taking into account the
3659 current font size.
3660
3661 The default implementation simply returns ::wxDefaultSize and
3662 GetBestSize() returns an arbitrary hardcoded size for the window, so
3663 you must override it when implementing a custom window class.
3664
3665 Notice that the best size returned by this function is cached
3666 internally, so if anything that results in the best size changing (e.g.
3667 change to the control contents) happens, you need to call
3668 InvalidateBestSize() to notify wxWidgets about it.
3669
3670 @see @ref overview_windowsizing
3671
3672 @since 2.9.0
3673 */
3674 virtual wxSize DoGetBestClientSize() const;
3675
3676 /**
3677 Override this method to implement height-for-width best size
3678 calculation.
3679
3680 Return the height needed to fully display the control contents if its
3681 width is fixed to the given value. Custom classes implementing
3682 wrapping should override this method and return the height
3683 corresponding to the number of lines needed to lay out the control
3684 contents at this width.
3685
3686 Currently this method is not used by wxWidgets yet, however it is
3687 planned that it will be used by the new sizer classes implementing
3688 height-for-width layout strategy in the future.
3689
3690 Notice that implementing this method or even implementing both it and
3691 DoGetBestClientWidth() doesn't replace overriding DoGetBestClientSize(),
3692 i.e. you still need to implement the latter as well in order to provide
3693 the best size when neither width nor height are constrained.
3694
3695 By default returns ::wxDefaultCoord meaning that the vertical component
3696 of DoGetBestClientSize() return value should be used.
3697
3698 @since 2.9.4
3699 */
3700 virtual int DoGetBestClientHeight(int width) const;
3701
3702 /**
3703 Override this method to implement width-for-height best size
3704 calculation.
3705
3706 This method is exactly the same as DoGetBestClientHeight() except that
3707 it determines the width assuming the height is fixed instead of vice
3708 versa.
3709
3710 @since 2.9.4
3711 */
3712 virtual int DoGetBestClientWidth(int height) const;
3713
3714 /**
3715 Sets the initial window size if none is given (i.e.\ at least one of the
3716 components of the size passed to ctor/Create() is wxDefaultCoord).
3717 @deprecated Use SetInitialSize() instead.
3718 */
3719 virtual void SetInitialBestSize(const wxSize& size);
3720
3721 /**
3722 Generate wxWindowDestroyEvent for this window.
3723
3724 This is called by the window itself when it is being destroyed and
3725 usually there is no need to call it but see wxWindowDestroyEvent for
3726 explanations of when you might want to do it.
3727 */
3728 void SendDestroyEvent();
3729
3730 /**
3731 This function is public in wxEvtHandler but protected in wxWindow
3732 because for wxWindows you should always call ProcessEvent() on the
3733 pointer returned by GetEventHandler() and not on the wxWindow object
3734 itself.
3735
3736 For convenience, a ProcessWindowEvent() method is provided as a synonym
3737 for @code GetEventHandler()->ProcessEvent() @endcode
3738
3739 Note that it's still possible to call these functions directly on the
3740 wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
3741 create subtle bugs when windows with event handlers pushed on them are
3742 involved.
3743
3744 This holds also for all other wxEvtHandler functions.
3745 */
3746 virtual bool ProcessEvent(wxEvent& event);
3747
3748 //@{
3749 /**
3750 See ProcessEvent() for more info about why you shouldn't use this function
3751 and the reason for making this function protected in wxWindow.
3752 */
3753 bool SafelyProcessEvent(wxEvent& event);
3754 virtual void QueueEvent(wxEvent *event);
3755 virtual void AddPendingEvent(const wxEvent& event);
3756 void ProcessPendingEvents();
3757 bool ProcessThreadEvent(const wxEvent& event);
3758 //@}
3759};
3760
3761
3762
3763// ============================================================================
3764// Global functions/macros
3765// ============================================================================
3766
3767/** @addtogroup group_funcmacro_misc */
3768//@{
3769
3770/**
3771 Find the deepest window at the mouse pointer position, returning the window
3772 and current pointer position in screen coordinates.
3773
3774 @header{wx/window.h}
3775*/
3776wxWindow* wxFindWindowAtPointer(wxPoint& pt);
3777
3778/**
3779 Gets the currently active window (implemented for MSW and GTK only
3780 currently, always returns @NULL in the other ports).
3781
3782 @header{wx/window.h}
3783*/
3784wxWindow* wxGetActiveWindow();
3785
3786/**
3787 Returns the first top level parent of the given window, or in other words,
3788 the frame or dialog containing it, or @NULL.
3789
3790 @header{wx/window.h}
3791*/
3792wxWindow* wxGetTopLevelParent(wxWindow* window);
3793
3794//@}
3795