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