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