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