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