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