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