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