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