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