]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/window.tex
compile fixes for EMX
[wxWidgets.git] / docs / latex / wx / window.tex
1 \section{\class{wxWindow}}\label{wxwindow}
2
3 wxWindow is the base class for all windows. Any
4 children of the window will be deleted automatically by the destructor
5 before the window itself is deleted.
6
7 \wxheading{Derived from}
8
9 \helpref{wxEvtHandler}{wxevthandler}\\
10 \helpref{wxObject}{wxobject}
11
12 \wxheading{Include files}
13
14 <wx/window.h>
15
16 \wxheading{Window styles}
17
18 The following styles can apply to all windows, although they will not always make sense for a particular
19 window class.
20
21 \twocolwidtha{5cm}%
22 \begin{twocollist}\itemsep=0pt
23 \twocolitem{\windowstyle{wxSIMPLE\_BORDER}}{Displays a thin border around the window. wxBORDER is the old name
24 for this style. Windows only. }
25 \twocolitem{\windowstyle{wxDOUBLE\_BORDER}}{Displays a double border. Windows only.}
26 \twocolitem{\windowstyle{wxSUNKEN\_BORDER}}{Displays a sunken border.}
27 \twocolitem{\windowstyle{wxRAISED\_BORDER}}{Displays a raised border.}
28 \twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control. Windows only. }
29 \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint
30 events. Windows only.}
31 \twocolitem{\windowstyle{wxNO\_3D}}{Prevents the children of this window taking on 3D styles, even though
32 the application-wide policy is for 3D controls. Windows only.}
33 \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.}
34 \twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar. (Still used?) }
35 \twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar. (Still used?) }
36 \twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being
37 repainted, then children being painted over them. Windows only.}
38 \end{twocollist}
39
40 See also \helpref{window styles overview}{windowstyles}.
41
42 \wxheading{See also}
43
44 \helpref{Event handling overview}{eventhandlingoverview}
45
46 \latexignore{\rtfignore{\wxheading{Members}}}
47
48 \membersection{wxWindow::wxWindow}
49
50 \func{}{wxWindow}{\void}
51
52 Default constructor.
53
54 \func{}{wxWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},
55 \param{const wxPoint\& }{pos = wxDefaultPosition},
56 \param{const wxSize\& }{size = wxDefaultSize},
57 \param{long }{style = 0},
58 \param{const wxString\& }{name = wxPanelNameStr}}
59
60 Constructs a window, which can be a child of a frame, dialog or any other non-control window.
61
62 \wxheading{Parameters}
63
64 \docparam{parent}{Pointer to a parent window.}
65
66 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
67
68 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWindows
69 should generate a default position for the window. If using the wxWindow class directly, supply
70 an actual position.}
71
72 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWindows
73 should generate a default size for the window. If no suitable size can be found, the
74 window will be sized to 20x20 pixels so that the window is visible but obviously not
75 correctly sized. }
76
77 \docparam{style}{Window style. For generic window styles, please see \helpref{wxWindow}{wxwindow}.}
78
79 \docparam{name}{Window name.}
80
81 \membersection{wxWindow::\destruct{wxWindow}}
82
83 \func{}{\destruct{wxWindow}}{\void}
84
85 Destructor. Deletes all subwindows, then deletes itself. Instead of using
86 the {\bf delete} operator explicitly, you should normally
87 use \helpref{wxWindow::Destroy}{wxwindowdestroy} so that wxWindows
88 can delete a window only when it is safe to do so, in idle time.
89
90 \wxheading{See also}
91
92 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp
93 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
94 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
95 \helpref{wxCloseEvent}{wxcloseevent}
96
97 \membersection{wxWindow::AddChild}
98
99 \func{virtual void}{AddChild}{\param{wxWindow* }{child}}
100
101 Adds a child window. This is called automatically by window creation
102 functions so should not be required by the application programmer.
103
104 \wxheading{Parameters}
105
106 \docparam{child}{Child window to add.}
107
108 \membersection{wxWindow::CaptureMouse}\label{wxwindowcapturemouse}
109
110 \func{virtual void}{CaptureMouse}{\void}
111
112 Directs all mouse input to this window. Call \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse} to
113 release the capture.
114
115 \wxheading{See also}
116
117 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse}
118
119 \membersection{wxWindow::Center}\label{wxwindowcenter}
120
121 \func{void}{Center}{\param{int}{ direction}}
122
123 A synonym for \helpref{Centre}{wxwindowcentre}.
124
125 \membersection{wxWindow::CenterOnParent}\label{wxwindowcenteronparent}
126
127 \func{void}{CenterOnParent}{\param{int}{ direction}}
128
129 A synonym for \helpref{CentreOnParent}{wxwindowcentreonparent}.
130
131 \membersection{wxWindow::Centre}\label{wxwindowcentre}
132
133 \func{void}{Centre}{\param{int}{ direction = wxHORIZONTAL}}
134
135 Centres the window.
136
137 \wxheading{Parameters}
138
139 \docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp
140 or {\tt wxBOTH}. It may also include {\tt wxCENTRE\_ON\_SCREEN} flag
141 if you want to center the window on the entire screen and not on its
142 parent window.}
143
144 The flag {\tt wxCENTRE\_FRAME} is obsolete and should not be used any longer.
145
146 \wxheading{Remarks}
147
148 If the window is a top level one (i.e. doesn't have a parent), it will be
149 centered relative to the screen anyhow.
150
151 \wxheading{See also}
152
153 \helpref{wxWindow::Center}{wxwindowcenter}
154
155 \membersection{wxWindow::CentreOnParent}\label{wxwindowcentreonparent}
156
157 \func{void}{CentreOnParent}{\param{int}{ direction = wxHORIZONTAL}}
158
159 Centres the window.
160
161 \wxheading{Parameters}
162
163 \docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp
164 or {\tt wxBOTH}.}
165
166 \wxheading{Remarks}
167
168 This methods provides for a way to center top level windows over their
169 parents instead of the entire screen. If there is no parent or if the
170 window is not a top level window, then behaviour is the same as
171 \helpref{wxWindow::Centre}{wxwindowcentre}.
172
173 \wxheading{See also}
174
175 \helpref{wxWindow::CenterOnParent}{wxwindowcenteronparent}
176
177 \membersection{wxWindow::Clear}\label{wxwindowclear}
178
179 \func{void}{Clear}{\void}
180
181 Clears the window by filling it with the current background colour. Does not
182 cause an erase background event to be generated.
183
184 \membersection{wxWindow::ClientToScreen}
185
186 \constfunc{virtual void}{ClientToScreen}{\param{int* }{x}, \param{int* }{y}}
187
188 \constfunc{virtual wxPoint}{ClientToScreen}{\param{const wxPoint\&}{ pt}}
189
190 Converts to screen coordinates from coordinates relative to this window.
191
192 \docparam{x}{A pointer to a integer value for the x coordinate. Pass the client coordinate in, and
193 a screen coordinate will be passed out.}
194
195 \docparam{y}{A pointer to a integer value for the y coordinate. Pass the client coordinate in, and
196 a screen coordinate will be passed out.}
197
198 \docparam{pt}{The client position for the second form of the function.}
199
200 \pythonnote{In place of a single overloaded method name, wxPython
201 implements the following methods:\par
202 \indented{2cm}{\begin{twocollist}
203 \twocolitem{\bf{ClientToScreen(point)}}{Accepts and returns a wxPoint}
204 \twocolitem{\bf{ClientToScreenXY(x, y)}}{Returns a 2-tuple, (x, y)}
205 \end{twocollist}}
206 }
207
208
209 \membersection{wxWindow::Close}\label{wxwindowclose}
210
211 \func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}
212
213 The purpose of this call is to provide a safer way of destroying a window than using
214 the {\it delete} operator.
215
216 \wxheading{Parameters}
217
218 \docparam{force}{FALSE if the window's close handler should be able to veto the destruction
219 of this window, TRUE if it cannot.}
220
221 \wxheading{Remarks}
222
223 Close calls the \helpref{close handler}{wxcloseevent} for the window, providing an opportunity for the window to
224 choose whether to destroy the window.
225
226 The close handler should check whether the window is being deleted forcibly,
227 using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}, in which case it should
228 destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
229
230 Applies to managed windows (wxFrame and wxDialog classes) only.
231
232 {\it Note} that calling Close does not guarantee that the window will be destroyed; but it
233 provides a way to simulate a manual close of a window, which may or may not be implemented by
234 destroying the window. The default implementation of wxDialog::OnCloseWindow does not
235 necessarily delete the dialog, since it will simply simulate an wxID\_CANCEL event which
236 itself only hides the dialog.
237
238 To guarantee that the window will be destroyed, call \helpref{wxWindow::Destroy}{wxwindowdestroy} instead.
239
240 \wxheading{See also}
241
242 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp
243 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
244 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
245 \helpref{wxCloseEvent}{wxcloseevent}
246
247 \membersection{wxWindow::ConvertDialogToPixels}\label{wxwindowconvertdialogtopixels}
248
249 \func{wxPoint}{ConvertDialogToPixels}{\param{const wxPoint\&}{ pt}}
250
251 \func{wxSize}{ConvertDialogToPixels}{\param{const wxSize\&}{ sz}}
252
253 Converts a point or size from dialog units to pixels.
254
255 For the x dimension, the dialog units are multiplied by the average character width
256 and then divided by 4.
257
258 For the y dimension, the dialog units are multiplied by the average character height
259 and then divided by 8.
260
261 \wxheading{Remarks}
262
263 Dialog units are used for maintaining a dialog's proportions even if the font changes.
264 Dialogs created using Dialog Editor optionally use dialog units.
265
266 You can also use these functions programmatically. A convenience macro is defined:
267
268 {\small
269 \begin{verbatim}
270 #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
271 \end{verbatim}
272 }
273
274 \wxheading{See also}
275
276 \helpref{wxWindow::ConvertPixelsToDialog}{wxwindowconvertpixelstodialog}
277
278 \pythonnote{In place of a single overloaded method name, wxPython
279 implements the following methods:\par
280 \indented{2cm}{\begin{twocollist}
281 \twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
282 \twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
283 \end{twocollist}}
284
285 Additionally, the following helper functions are defined:\par
286 \indented{2cm}{\begin{twocollist}
287 \twocolitem{\bf{wxDLG\_PNT(win, point)}}{Converts a wxPoint from dialog
288 units to pixels}
289 \twocolitem{\bf{wxDLG\_SZE(win, size)}}{Converts a wxSize from dialog
290 units to pixels}
291 \end{twocollist}}
292 }
293
294
295 \membersection{wxWindow::ConvertPixelsToDialog}\label{wxwindowconvertpixelstodialog}
296
297 \func{wxPoint}{ConvertPixelsToDialog}{\param{const wxPoint\&}{ pt}}
298
299 \func{wxSize}{ConvertPixelsToDialog}{\param{const wxSize\&}{ sz}}
300
301 Converts a point or size from pixels to dialog units.
302
303 For the x dimension, the pixels are multiplied by 4 and then divided by the average
304 character width.
305
306 For the y dimension, the pixels are multipled by 8 and then divided by the average
307 character height.
308
309 \wxheading{Remarks}
310
311 Dialog units are used for maintaining a dialog's proportions even if the font changes.
312 Dialogs created using Dialog Editor optionally use dialog units.
313
314 \wxheading{See also}
315
316 \helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels}
317
318
319 \pythonnote{In place of a single overloaded method name, wxPython
320 implements the following methods:\par
321 \indented{2cm}{\begin{twocollist}
322 \twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
323 \twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
324 \end{twocollist}}
325 }
326
327 \membersection{wxWindow::Destroy}\label{wxwindowdestroy}
328
329 \func{virtual bool}{Destroy}{\void}
330
331 Destroys the window safely. Use this function instead of the delete operator, since
332 different window classes can be destroyed differently. Frames and dialogs
333 are not destroyed immediately when this function is called - they are added
334 to a list of windows to be deleted on idle time, when all the window's events
335 have been processed. This prevents problems with events being sent to non-existant
336 windows.
337
338 \wxheading{Return value}
339
340 TRUE if the window has either been successfully deleted, or it has been added
341 to the list of windows pending real deletion.
342
343 \membersection{wxWindow::DestroyChildren}
344
345 \func{virtual void}{DestroyChildren}{\void}
346
347 Destroys all children of a window. Called automatically by the destructor.
348
349 \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles}
350
351 \func{virtual void}{DragAcceptFiles}{\param{const bool}{ accept}}
352
353 Enables or disables elibility for drop file events (OnDropFiles).
354
355 \wxheading{Parameters}
356
357 \docparam{accept}{If TRUE, the window is eligible for drop file events. If FALSE, the window
358 will not accept drop file events.}
359
360 \wxheading{Remarks}
361
362 Windows only.
363
364 \wxheading{See also}
365
366 \helpref{wxWindow::OnDropFiles}{wxwindowondropfiles}
367
368 \membersection{wxWindow::Enable}\label{wxwindowenable}
369
370 \func{virtual void}{Enable}{\param{const bool}{ enable}}
371
372 Enable or disable the window for user input.
373
374 \wxheading{Parameters}
375
376 \docparam{enable}{If TRUE, enables the window for input. If FALSE, disables the window.}
377
378 \wxheading{See also}
379
380 \helpref{wxWindow::IsEnabled}{wxwindowisenabled}
381
382 \membersection{wxWindow::FindFocus}\label{wxwindowfindfocus}
383
384 \func{static wxWindow*}{FindFocus}{\void}
385
386 Finds the window or control which currently has the keyboard focus.
387
388 \wxheading{Remarks}
389
390 Note that this is a static function, so it can be called without needing a wxWindow pointer.
391
392 \wxheading{See also}
393
394 \helpref{wxWindow::SetFocus}{wxwindowsetfocus}
395
396 \membersection{wxWindow::FindWindow}\label{wxwindowfindwindow}
397
398 \func{wxWindow*}{FindWindow}{\param{long}{ id}}
399
400 Find a child of this window, by identifier.
401
402 \func{wxWindow*}{FindWindow}{\param{const wxString\&}{ name}}
403
404 Find a child of this window, by name.
405
406 \pythonnote{In place of a single overloaded method name, wxPython
407 implements the following methods:\par
408 \indented{2cm}{\begin{twocollist}
409 \twocolitem{\bf{FindWindowById(id)}}{Accepts an integer}
410 \twocolitem{\bf{FindWindowByName(name)}}{Accepts a string}
411 \end{twocollist}}
412 }
413
414 \membersection{wxWindow::Fit}\label{wxwindowfit}
415
416 \func{virtual void}{Fit}{\void}
417
418 Sizes the window so that it fits around its subwindows.
419
420 \membersection{wxWindow::GetBackgroundColour}\label{wxwindowgetbackgroundcolour}
421
422 \constfunc{virtual wxColour}{GetBackgroundColour}{\void}
423
424 Returns the background colour of the window.
425
426 \wxheading{See also}
427
428 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
429 \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp
430 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
431 \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground}
432
433 \membersection{wxWindow::GetCharHeight}
434
435 \constfunc{virtual int}{GetCharHeight}{\void}
436
437 Returns the character height for this window.
438
439 \membersection{wxWindow::GetCharWidth}
440
441 \constfunc{virtual int}{GetCharWidth}{\void}
442
443 Returns the average character width for this window.
444
445 \membersection{wxWindow::GetChildren}
446
447 \func{wxList\&}{GetChildren}{\void}
448
449 Returns a reference to the list of the window's children.
450
451 \membersection{wxWindow::GetClientSize}\label{wxwindowgetclientsize}
452
453 \constfunc{virtual void}{GetClientSize}{\param{int* }{width}, \param{int* }{height}}
454
455 \constfunc{virtual wxSize}{GetClientSize}{\void}
456
457 This gets the size of the window `client area' in pixels. The client area is the
458 area which may be drawn on by the programmer, excluding title bar, border etc.
459
460 \wxheading{Parameters}
461
462 \docparam{width}{Receives the client width in pixels.}
463
464 \docparam{height}{Receives the client height in pixels.}
465
466 \pythonnote{In place of a single overloaded method name, wxPython
467 implements the following methods:\par
468 \indented{2cm}{\begin{twocollist}
469 \twocolitem{\bf{wxGetClientSizeTuple()}}{Returns a 2-tuple of (width, height)}
470 \twocolitem{\bf{wxGetClientSize()}}{Returns a wxSize object}
471 \end{twocollist}}
472 }
473
474 \membersection{wxWindow::GetConstraints}\label{wxwindowgetconstraints}
475
476 \constfunc{wxLayoutConstraints*}{GetConstraints}{\void}
477
478 Returns a pointer to the window's layout constraints, or NULL if there are none.
479
480 \membersection{wxWindow::GetDefaultItem}\label{wxwindowgetdefaultitem}
481
482 \constfunc{wxButton*}{GetDefaultItem}{\void}
483
484 Returns a pointer to the button which is the default for this window, or NULL.
485
486 \membersection{wxWindow::GetDropTarget}\label{wxwindowgetdroptarget}
487
488 \constfunc{wxDropTarget*}{GetDropTarget}{\void}
489
490 Returns the associated drop target, which may be NULL.
491
492 \wxheading{See also}
493
494 \helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget},
495 \helpref{Drag and drop overview}{wxdndoverview}
496
497 \membersection{wxWindow::GetEventHandler}\label{wxwindowgeteventhandler}
498
499 \constfunc{wxEvtHandler*}{GetEventHandler}{\void}
500
501 Returns the event handler for this window. By default, the window is its
502 own event handler.
503
504 \wxheading{See also}
505
506 \helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp
507 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
508 \helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp
509 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp
510 \helpref{wxEvtHandler}{wxevthandler}\rtfsp
511
512 \membersection{wxWindow::GetFont}\label{wxwindowgetfont}
513
514 \constfunc{wxFont\&}{GetFont}{\void}
515
516 Returns a reference to the font for this window.
517
518 \wxheading{See also}
519
520 \helpref{wxWindow::SetFont}{wxwindowsetfont}
521
522 \membersection{wxWindow::GetForegroundColour}\label{wxwindowgetforegroundcolour}
523
524 \func{virtual wxColour}{GetForegroundColour}{\void}
525
526 Returns the foreground colour of the window.
527
528 \wxheading{Remarks}
529
530 The interpretation of foreground colour is open to interpretation according
531 to the window class; it may be the text colour or other colour, or it may not
532 be used at all.
533
534 \wxheading{See also}
535
536 \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp
537 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
538 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour}
539
540 \membersection{wxWindow::GetGrandParent}
541
542 \constfunc{wxWindow*}{GetGrandParent}{\void}
543
544 Returns the grandparent of a window, or NULL if there isn't one.
545
546 \membersection{wxWindow::GetHandle}
547
548 \constfunc{void*}{GetHandle}{\void}
549
550 Returns the platform-specific handle of the physical window. Cast it to an appropriate
551 handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif or {\bf GtkWidget} for GTK.
552
553 \membersection{wxWindow::GetId}\label{wxwindowgetid}
554
555 \constfunc{int}{GetId}{\void}
556
557 Returns the identifier of the window.
558
559 \wxheading{Remarks}
560
561 Each window has an integer identifier. If the application has not provided one
562 (or the default Id -1) an unique identifier with a negative value will be generated.
563
564 \wxheading{See also}
565
566 \helpref{wxWindow::SetId}{wxwindowsetid}\rtfsp
567 \helpref{Window identifiers}{windowids}
568
569 \membersection{wxWindow::GetPosition}
570
571 \constfunc{virtual void}{GetPosition}{\param{int* }{x}, \param{int* }{y}}
572
573 This gets the position of the window in pixels, relative to the parent window or
574 if no parent, relative to the whole display.
575
576 \wxheading{Parameters}
577
578 \docparam{x}{Receives the x position of the window.}
579
580 \docparam{y}{Receives the y position of the window.}
581
582 \pythonnote{In place of a single overloaded method name, wxPython
583 implements the following methods:\par
584 \indented{2cm}{\begin{twocollist}
585 \twocolitem{\bf{GetPosition()}}{Returns a wxPoint}
586 \twocolitem{\bf{GetPositionTuple()}}{Returns a tuple (x, y)}
587 \end{twocollist}}
588 }
589
590 \membersection{wxWindow::GetLabel}
591
592 \constfunc{virtual wxString }{GetLabel}{\void}
593
594 Generic way of getting a label from any window, for
595 identification purposes.
596
597 \wxheading{Remarks}
598
599 The interpretation of this function differs from class to class.
600 For frames and dialogs, the value returned is the title. For buttons or static text controls, it is
601 the button text. This function can be useful for meta-programs (such as testing
602 tools or special-needs access programs) which need to identify windows
603 by name.
604
605 \membersection{wxWindow::GetName}\label{wxwindowgetname}
606
607 \constfunc{virtual wxString }{GetName}{\void}
608
609 Returns the window's name.
610
611 \wxheading{Remarks}
612
613 This name is not guaranteed to be unique; it is up to the programmer to supply an appropriate
614 name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetname}.
615
616 \wxheading{See also}
617
618 \helpref{wxWindow::SetName}{wxwindowsetname}
619
620 \membersection{wxWindow::GetParent}
621
622 \constfunc{virtual wxWindow*}{GetParent}{\void}
623
624 Returns the parent of the window, or NULL if there is no parent.
625
626 \membersection{wxWindow::GetRect}\label{wxwindowgetrect}
627
628 \constfunc{virtual wxRect}{GetRect}{\void}
629
630 Returns the size and position of the window as a \helpref{wxRect}{wxrect} object.
631
632 \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb}
633
634 \func{virtual int}{GetScrollThumb}{\param{int }{orientation}}
635
636 Returns the built-in scrollbar thumb size.
637
638 \wxheading{See also}
639
640 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
641
642 \membersection{wxWindow::GetScrollPos}\label{wxwindowgetscrollpos}
643
644 \func{virtual int}{GetScrollPos}{\param{int }{orientation}}
645
646 Returns the built-in scrollbar position.
647
648 \wxheading{See also}
649
650 See \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
651
652 \membersection{wxWindow::GetScrollRange}\label{wxwindowgetscrollrange}
653
654 \func{virtual int}{GetScrollRange}{\param{int }{orientation}}
655
656 Returns the built-in scrollbar range.
657
658 \wxheading{See also}
659
660 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
661
662 \membersection{wxWindow::GetSize}\label{wxwindowgetsize}
663
664 \constfunc{virtual void}{GetSize}{\param{int* }{width}, \param{int* }{height}}
665
666 \constfunc{virtual wxSize}{GetSize}{\void}
667
668 This gets the size of the entire window in pixels.
669
670 \wxheading{Parameters}
671
672 \docparam{width}{Receives the window width.}
673
674 \docparam{height}{Receives the window height.}
675
676 \pythonnote{In place of a single overloaded method name, wxPython
677 implements the following methods:\par
678 \indented{2cm}{\begin{twocollist}
679 \twocolitem{\bf{GetSize()}}{Returns a wxSize}
680 \twocolitem{\bf{GetSizeTuple()}}{Returns a 2-tuple (width, height)}
681 \end{twocollist}}
682 }
683
684 \membersection{wxWindow::GetTextExtent}
685
686 \constfunc{virtual void}{GetTextExtent}{\param{const wxString\& }{string}, \param{int* }{x}, \param{int* }{y},
687 \param{int* }{descent = NULL}, \param{int* }{externalLeading = NULL},
688 \param{const wxFont* }{font = NULL}, \param{const bool}{ use16 = FALSE}}
689
690 Gets the dimensions of the string as it would be drawn on the
691 window with the currently selected font.
692
693 \wxheading{Parameters}
694
695 \docparam{string}{String whose extent is to be measured.}
696
697 \docparam{x}{Return value for width.}
698
699 \docparam{y}{Return value for height.}
700
701 \docparam{descent}{Return value for descent (optional).}
702
703 \docparam{externalLeading}{Return value for external leading (optional).}
704
705 \docparam{font}{Font to use instead of the current window font (optional).}
706
707 \docparam{use16}{If TRUE, {\it string} contains 16-bit characters. The default is FALSE.}
708
709
710 \pythonnote{In place of a single overloaded method name, wxPython
711 implements the following methods:\par
712 \indented{2cm}{\begin{twocollist}
713 \twocolitem{\bf{GetTextExtent(string)}}{Returns a 2-tuple, (width, height)}
714 \twocolitem{\bf{GetFullTextExtent(string, font=NULL)}}{Returns a
715 4-tuple, (width, height, descent, externalLeading) }
716 \end{twocollist}}
717 }
718
719
720 \membersection{wxWindow::GetTitle}\label{wxwindowgettitle}
721
722 \func{virtual wxString}{GetTitle}{\void}
723
724 Gets the window's title. Applicable only to frames and dialogs.
725
726 \wxheading{See also}
727
728 \helpref{wxWindow::SetTitle}{wxwindowsettitle}
729
730 \membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion}
731
732 \constfunc{virtual wxRegion}{GetUpdateRegion}{\void}
733
734 Returns the region specifying which parts of the window have been damaged. Should
735 only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler.
736
737 \wxheading{See also}
738
739 \helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint}
740
741 \membersection{wxWindow::GetValidator}\label{wxwindowgetvalidator}
742
743 \constfunc{wxValidator*}{GetValidator}{\void}
744
745 Returns a pointer to the current validator for the window, or NULL if there is none.
746
747 \membersection{wxWindow::GetWindowStyleFlag}
748
749 \constfunc{long}{GetWindowStyleFlag}{\void}
750
751 Gets the window style that was passed to the consructor or {\bf Create} member.
752 {\bf GetWindowStyle} is synonymous.
753
754 \membersection{wxWindow::InitDialog}\label{wxwindowinitdialog}
755
756 \func{void}{InitDialog}{\void}
757
758 Sends an \helpref{wxWindow::OnInitDialog}{wxwindowoninitdialog} event, which
759 in turn transfers data to the dialog via validators.
760
761 \wxheading{See also}
762
763 \helpref{wxWindow::OnInitDialog}{wxwindowoninitdialog}
764
765 \membersection{wxWindow::IsEnabled}\label{wxwindowisenabled}
766
767 \constfunc{virtual bool}{IsEnabled}{\void}
768
769 Returns TRUE if the window is enabled for input, FALSE otherwise.
770
771 \wxheading{See also}
772
773 \helpref{wxWindow::Enable}{wxwindowenable}
774
775 \membersection{wxWindow:IsExposed}\label{wxwindowisexposed}
776
777 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
778
779 \constfunc{bool}{IsExposed}{\param{wxPoint }{&pt}}
780
781 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}, \param{int }{w}, \param{int }{h}}
782
783 \constfunc{bool}{IsExposed}{\param{wxRect }{&rect}}
784
785 Returns TRUE if the given point or rectange area has been exposed since the
786 last repaint. Call this in an paint event handler to optimize redrawing by
787 only redrawing those area, which have been exposed.
788
789 \membersection{wxWindow::IsRetained}\label{wxwindowisretained}
790
791 \constfunc{virtual bool}{IsRetained}{\void}
792
793 Returns TRUE if the window is retained, FALSE otherwise.
794
795 \wxheading{Remarks}
796
797 Retained windows are only available on X platforms.
798
799 \membersection{wxWindow::IsShown}\label{wxwindowisshown}
800
801 \constfunc{virtual bool}{IsShown}{\void}
802
803 Returns TRUE if the window is shown, FALSE if it has been hidden.
804
805 \membersection{wxWindow::IsTopLevel}\label{wxwindowistoplevel}
806
807 \constfunc{bool}{IsTopLevel}{\void}
808
809 Returns TRUE if the given window is a top-level one. Currently all frames and
810 dialogs are considered to be top-level windows (even if they have a parent
811 window).
812
813 \membersection{wxWindow::Layout}\label{wxwindowlayout}
814
815 \func{void}{Layout}{\void}
816
817 Invokes the constraint-based layout algorithm or the sizer-based algorithm
818 for this window.
819
820 See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when
821 this function gets called automatically using auto layout.
822
823 \membersection{wxWindow::LoadFromResource}\label{wxwindowloadfromresource}
824
825 \func{virtual bool}{LoadFromResource}{\param{wxWindow* }{parent},\rtfsp
826 \param{const wxString\& }{resourceName}, \param{const wxResourceTable* }{resourceTable = NULL}}
827
828 Loads a panel or dialog from a resource file.
829
830 \wxheading{Parameters}
831
832 \docparam{parent}{Parent window.}
833
834 \docparam{resourceName}{The name of the resource to load.}
835
836 \docparam{resourceTable}{The resource table to load it from. If this is NULL, the
837 default resource table will be used.}
838
839 \wxheading{Return value}
840
841 TRUE if the operation succeeded, otherwise FALSE.
842
843 \membersection{wxWindow::Lower}\label{wxwindowlower}
844
845 \func{void}{Lower}{\void}
846
847 Lowers the window to the bottom of the window hierarchy if it is a managed window (dialog
848 or frame).
849
850 \membersection{wxWindow::MakeModal}\label{wxwindowmakemodal}
851
852 \func{virtual void}{MakeModal}{\param{const bool }{flag}}
853
854 Disables all other windows in the application so that
855 the user can only interact with this window. (This function
856 is not implemented anywhere).
857
858 \wxheading{Parameters}
859
860 \docparam{flag}{If TRUE, this call disables all other windows in the application so that
861 the user can only interact with this window. If FALSE, the effect is reversed.}
862
863 \membersection{wxWindow::Move}\label{wxwindowmove}
864
865 \func{void}{Move}{\param{int}{ x}, \param{int}{ y}}
866
867 \func{void}{Move}{\param{const wxPoint\&}{ pt}}
868
869 Moves the window to the given position.
870
871 \wxheading{Parameters}
872
873 \docparam{x}{Required x position.}
874
875 \docparam{y}{Required y position.}
876
877 \docparam{pt}{\helpref{wxPoint}{wxpoint} object representing the position.}
878
879 \wxheading{Remarks}
880
881 Implementations of SetSize can also implicitly implement the
882 wxWindow::Move function, which is defined in the base wxWindow class
883 as the call:
884
885 \begin{verbatim}
886 SetSize(x, y, -1, -1, wxSIZE_USE_EXISTING);
887 \end{verbatim}
888
889 \wxheading{See also}
890
891 \helpref{wxWindow::SetSize}{wxwindowsetsize}
892
893 \pythonnote{In place of a single overloaded method name, wxPython
894 implements the following methods:\par
895 \indented{2cm}{\begin{twocollist}
896 \twocolitem{\bf{Move(point)}}{Accepts a wxPoint}
897 \twocolitem{\bf{MoveXY(x, y)}}{Accepts a pair of integers}
898 \end{twocollist}}
899 }
900
901 \membersection{wxWindow::OnActivate}\label{wxwindowonactivate}
902
903 \func{void}{OnActivate}{\param{wxActivateEvent\&}{ event}}
904
905 Called when a window is activated or deactivated.
906
907 \wxheading{Parameters}
908
909 \docparam{event}{Object containing activation information.}
910
911 \wxheading{Remarks}
912
913 If the window is being activated, \helpref{wxActivateEvent::GetActive}{wxactivateeventgetactive} returns TRUE,
914 otherwise it returns FALSE (it is being deactivated).
915
916 \wxheading{See also}
917
918 \helpref{wxActivateEvent}{wxactivateevent},\rtfsp
919 \helpref{Event handling overview}{eventhandlingoverview}
920
921 \membersection{wxWindow::OnChar}\label{wxwindowonchar}
922
923 \func{void}{OnChar}{\param{wxKeyEvent\&}{ event}}
924
925 Called when the user has pressed a key that is not a modifier (SHIFT, CONTROL or ALT).
926
927 \wxheading{Parameters}
928
929 \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for
930 details about this class.}
931
932 \wxheading{Remarks}
933
934 This member function is called in response to a keypress. To intercept this event,
935 use the EVT\_CHAR macro in an event table definition. Your {\bf OnChar} handler may call this
936 default function to achieve default keypress functionality.
937
938 Note that the ASCII values do not have explicit key codes: they are passed as ASCII
939 values.
940
941 Note that not all keypresses can be intercepted this way. If you wish to intercept modifier
942 keypresses, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or
943 \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}.
944
945 Most, but not all, windows allow keypresses to be intercepted.
946
947 \wxheading{See also}
948
949 \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp
950 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp
951 \helpref{Event handling overview}{eventhandlingoverview}
952
953 \membersection{wxWindow::OnCharHook}\label{wxwindowoncharhook}
954
955 \func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
956
957 This member is called to allow the window to intercept keyboard events
958 before they are processed by child windows.
959
960 \wxheading{Parameters}
961
962 \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for
963 details about this class.}
964
965 \wxheading{Remarks}
966
967 This member function is called in response to a keypress, if the window is active. To intercept this event,
968 use the EVT\_CHAR\_HOOK macro in an event table definition. If you do not process a particular
969 keypress, call \helpref{wxEvent::Skip}{wxeventskip} to allow default processing.
970
971 An example of using this function is in the implementation of escape-character processing for wxDialog,
972 where pressing ESC dismisses the dialog by {\bf OnCharHook} 'forging' a cancel button press event.
973
974 Note that the ASCII values do not have explicit key codes: they are passed as ASCII
975 values.
976
977 This function is only relevant to top-level windows (frames and dialogs), and under
978 Windows only. Under GTK the normal EVT\_CHAR\_ event has the functionality, i.e.
979 you can intercepts it and if you don't call \helpref{wxEvent::Skip}{wxeventskip}
980 the window won't get the event.
981
982 \wxheading{See also}
983
984 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp
985 \helpref{wxApp::OnCharHook}{wxapponcharhook},\rtfsp
986 \helpref{Event handling overview}{eventhandlingoverview}
987
988 \membersection{wxWindow::OnCommand}\label{wxwindowoncommand}
989
990 \func{virtual void}{OnCommand}{\param{wxEvtHandler\& }{object}, \param{wxCommandEvent\& }{event}}
991
992 This virtual member function is called if the control does not handle the command event.
993
994 \wxheading{Parameters}
995
996 \docparam{object}{Object receiving the command event.}
997
998 \docparam{event}{Command event}
999
1000 \wxheading{Remarks}
1001
1002 This virtual function is provided mainly for backward compatibility. You can also intercept commands
1003 from child controls by using an event table, with identifiers or identifier ranges to identify
1004 the control(s) in question.
1005
1006 \wxheading{See also}
1007
1008 \helpref{wxCommandEvent}{wxcommandevent},\rtfsp
1009 \helpref{Event handling overview}{eventhandlingoverview}
1010
1011 \membersection{wxWindow::OnClose}\label{wxwindowonclose}
1012
1013 \func{virtual bool}{OnClose}{\void}
1014
1015 Called when the user has tried to close a a frame
1016 or dialog box using the window manager (X) or system menu (Windows).
1017
1018 {\bf Note:} This is an obsolete function.
1019 It is superceded by the \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} event
1020 handler.
1021
1022 \wxheading{Return value}
1023
1024 If TRUE is returned by OnClose, the window will be deleted by the system, otherwise the
1025 attempt will be ignored. Do not delete the window from within this handler, although
1026 you may delete other windows.
1027
1028 \wxheading{See also}
1029
1030 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp
1031 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
1032 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
1033 \helpref{wxCloseEvent}{wxcloseevent}
1034
1035 \membersection{wxWindow::OnCloseWindow}\label{wxwindowonclosewindow}
1036
1037 \func{void}{OnCloseWindow}{\param{wxCloseEvent\& }{event}}
1038
1039 This is an event handler function called when the user has tried to close a a frame
1040 or dialog box using the window manager (X) or system menu (Windows). It is
1041 called via the \helpref{wxWindow::Close}{wxwindowclose} function, so
1042 that the application can also invoke the handler programmatically.
1043
1044 Use the EVT\_CLOSE event table macro to handle close events.
1045
1046 You should check whether the application is forcing the deletion of the window
1047 using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
1048 destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
1049 If not, it is up to you whether you respond by destroying the window.
1050
1051 (Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of
1052 the window is required, test for the negative of CanVeto. If CanVeto returns FALSE,
1053 it is not possible to skip window deletion.)
1054
1055 If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to
1056 let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function
1057 to return TRUE or FALSE depending on whether the close instruction was honoured or not.
1058
1059 \wxheading{Remarks}
1060
1061 The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains
1062 for backward compatibility with earlier versions of wxWindows. The
1063 default {\bf OnCloseWindow} handler for wxFrame and wxDialog will call {\bf OnClose},
1064 destroying the window if it returns TRUE or if the close is being forced.
1065
1066 \wxheading{See also}
1067
1068 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp
1069 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
1070 \helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp
1071 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
1072 \helpref{wxCloseEvent}{wxcloseevent},\rtfsp
1073 \helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession},\rtfsp
1074 \helpref{wxApp::OnEndSession}{wxapponendsession}
1075
1076 \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles}
1077
1078 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\&}{ event}}
1079
1080 Called when files have been dragged from the file manager to the window.
1081
1082 \wxheading{Parameters}
1083
1084 \docparam{event}{Drop files event. For more information, see \helpref{wxDropFilesEvent}{wxdropfilesevent}.}
1085
1086 \wxheading{Remarks}
1087
1088 The window must have previously been enabled for dropping by calling
1089 \rtfsp\helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles}.
1090
1091 This event is only generated under Windows.
1092
1093 To intercept this event, use the EVT\_DROP\_FILES macro in an event table definition.
1094
1095 \wxheading{See also}
1096
1097 \helpref{wxDropFilesEvent}{wxdropfilesevent}, \helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles},\rtfsp
1098 \helpref{Event handling overview}{eventhandlingoverview}
1099
1100 \membersection{wxWindow::OnEraseBackground}\label{wxwindowonerasebackground}
1101
1102 \func{void}{OnEraseBackground}{\param{wxEraseEvent\&}{ event}}
1103
1104 Called when the background of the window needs to be erased.
1105
1106 \wxheading{Parameters}
1107
1108 \docparam{event}{Erase background event. For more information, see \helpref{wxEraseEvent}{wxeraseevent}.}
1109
1110 \wxheading{Remarks}
1111
1112 This event is only generated under Windows. It is therefore recommended that
1113 you set the text background colour explicitly in order to prevent flicker.
1114 The default background colour under GTK is grey.
1115
1116 To intercept this event, use the EVT\_ERASE\_BACKGROUND macro in an event table definition.
1117
1118 \wxheading{See also}
1119
1120 \helpref{wxEraseEvent}{wxeraseevent}, \helpref{Event handling overview}{eventhandlingoverview}
1121
1122 \membersection{wxWindow::OnKeyDown}\label{wxwindowonkeydown}
1123
1124 \func{void}{OnKeyDown}{\param{wxKeyEvent\&}{ event}}
1125
1126 Called when the user has pressed a key, before it is translated into an ASCII value using other
1127 modifier keys that might be pressed at the same time.
1128
1129 \wxheading{Parameters}
1130
1131 \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for
1132 details about this class.}
1133
1134 \wxheading{Remarks}
1135
1136 This member function is called in response to a key down event. To intercept this event,
1137 use the EVT\_KEY\_DOWN macro in an event table definition. Your {\bf OnKeyDown} handler may call this
1138 default function to achieve default keypress functionality.
1139
1140 Note that not all keypresses can be intercepted this way. If you wish to intercept special
1141 keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or
1142 \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}.
1143
1144 Most, but not all, windows allow keypresses to be intercepted.
1145
1146 \wxheading{See also}
1147
1148 \helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp
1149 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp
1150 \helpref{Event handling overview}{eventhandlingoverview}
1151
1152 \membersection{wxWindow::OnKeyUp}\label{wxwindowonkeyup}
1153
1154 \func{void}{OnKeyUp}{\param{wxKeyEvent\&}{ event}}
1155
1156 Called when the user has released a key.
1157
1158 \wxheading{Parameters}
1159
1160 \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for
1161 details about this class.}
1162
1163 \wxheading{Remarks}
1164
1165 This member function is called in response to a key up event. To intercept this event,
1166 use the EVT\_KEY\_UP macro in an event table definition. Your {\bf OnKeyUp} handler may call this
1167 default function to achieve default keypress functionality.
1168
1169 Note that not all keypresses can be intercepted this way. If you wish to intercept special
1170 keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or
1171 \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}.
1172
1173 Most, but not all, windows allow key up events to be intercepted.
1174
1175 \wxheading{See also}
1176
1177 \helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown},\rtfsp
1178 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp
1179 \helpref{Event handling overview}{eventhandlingoverview}
1180
1181 \membersection{wxWindow::OnKillFocus}\label{wxwindowonkillfocus}
1182
1183 \func{void}{OnKillFocus}{\param{wxFocusEvent\& }{event}}
1184
1185 Called when a window's focus is being killed.
1186
1187 \wxheading{Parameters}
1188
1189 \docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.}
1190
1191 \wxheading{Remarks}
1192
1193 To intercept this event, use the macro EVT\_KILL\_FOCUS in an event table definition.
1194
1195 Most, but not all, windows respond to this event.
1196
1197 \wxheading{See also}
1198
1199 \helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnSetFocus}{wxwindowonsetfocus},\rtfsp
1200 \helpref{Event handling overview}{eventhandlingoverview}
1201
1202 \membersection{wxWindow::OnIdle}\label{wxwindowonidle}
1203
1204 \func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
1205
1206 Provide this member function for any processing which needs to be done
1207 when the application is idle.
1208
1209 \wxheading{See also}
1210
1211 \helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxIdleEvent}{wxidleevent}
1212
1213 \membersection{wxWindow::OnInitDialog}\label{wxwindowoninitdialog}
1214
1215 \func{void}{OnInitDialog}{\param{wxInitDialogEvent\&}{ event}}
1216
1217 Default handler for the wxEVT\_INIT\_DIALOG event. Calls \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
1218
1219 \wxheading{Parameters}
1220
1221 \docparam{event}{Dialog initialisation event.}
1222
1223 \wxheading{Remarks}
1224
1225 Gives the window the default behaviour of transferring data to child controls via
1226 the validator that each control has.
1227
1228 \wxheading{See also}
1229
1230 \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}
1231
1232 \membersection{wxWindow::OnMenuCommand}\label{wxwindowonmenucommand}
1233
1234 \func{void}{OnMenuCommand}{\param{wxCommandEvent\& }{event}}
1235
1236 Called when a menu command is received from a menu bar.
1237
1238 \wxheading{Parameters}
1239
1240 \docparam{event}{The menu command event. For more information, see \helpref{wxCommandEvent}{wxcommandevent}.}
1241
1242 \wxheading{Remarks}
1243
1244 A function with this name doesn't actually exist; you can choose any member function to receive
1245 menu command events, using the EVT\_COMMAND macro for individual commands or EVT\_COMMAND\_RANGE for
1246 a range of commands.
1247
1248 \wxheading{See also}
1249
1250 \helpref{wxCommandEvent}{wxcommandevent},\rtfsp
1251 \helpref{wxWindow::OnMenuHighlight}{wxwindowonmenuhighlight},\rtfsp
1252 \helpref{Event handling overview}{eventhandlingoverview}
1253
1254 \membersection{wxWindow::OnMenuHighlight}\label{wxwindowonmenuhighlight}
1255
1256 \func{void}{OnMenuHighlight}{\param{wxMenuEvent\& }{event}}
1257
1258 Called when a menu select is received from a menu bar: that is, the
1259 mouse cursor is over a menu item, but the left mouse button has not been
1260 pressed.
1261
1262 \wxheading{Parameters}
1263
1264 \docparam{event}{The menu highlight event. For more information, see \helpref{wxMenuEvent}{wxmenuevent}.}
1265
1266 \wxheading{Remarks}
1267
1268 You can choose any member function to receive
1269 menu select events, using the EVT\_MENU\_HIGHLIGHT macro for individual menu items or EVT\_MENU\_HIGHLIGHT\_ALL macro
1270 for all menu items.
1271
1272 The default implementation for \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays help
1273 text in the first field of the status bar.
1274
1275 This function was known as {\bf OnMenuSelect} in earlier versions of wxWindows, but this was confusing
1276 since a selection is normally a left-click action.
1277
1278 \wxheading{See also}
1279
1280 \helpref{wxMenuEvent}{wxmenuevent},\rtfsp
1281 \helpref{wxWindow::OnMenuCommand}{wxwindowonmenucommand},\rtfsp
1282 \helpref{Event handling overview}{eventhandlingoverview}
1283
1284
1285 \membersection{wxWindow::OnMouseEvent}\label{wxwindowonmouseevent}
1286
1287 \func{void}{OnMouseEvent}{\param{wxMouseEvent\&}{ event}}
1288
1289 Called when the user has initiated an event with the
1290 mouse.
1291
1292 \wxheading{Parameters}
1293
1294 \docparam{event}{The mouse event. See \helpref{wxMouseEvent}{wxmouseevent} for
1295 more details.}
1296
1297 \wxheading{Remarks}
1298
1299 Most, but not all, windows respond to this event.
1300
1301 To intercept this event, use the EVT\_MOUSE\_EVENTS macro in an event table definition, or individual
1302 mouse event macros such as EVT\_LEFT\_DOWN.
1303
1304 \wxheading{See also}
1305
1306 \helpref{wxMouseEvent}{wxmouseevent},\rtfsp
1307 \helpref{Event handling overview}{eventhandlingoverview}
1308
1309 \membersection{wxWindow::OnMove}\label{wxwindowonmove}
1310
1311 \func{void}{OnMove}{\param{wxMoveEvent\& }{event}}
1312
1313 Called when a window is moved.
1314
1315 \wxheading{Parameters}
1316
1317 \docparam{event}{The move event. For more information, see \helpref{wxMoveEvent}{wxmoveevent}.}
1318
1319 \wxheading{Remarks}
1320
1321 Use the EVT\_MOVE macro to intercept move events.
1322
1323 \wxheading{Remarks}
1324
1325 Not currently implemented.
1326
1327 \wxheading{See also}
1328
1329 \helpref{wxMoveEvent}{wxmoveevent},\rtfsp
1330 \helpref{wxFrame::OnSize}{wxframeonsize},\rtfsp
1331 \helpref{Event handling overview}{eventhandlingoverview}
1332
1333 \membersection{wxWindow::OnPaint}\label{wxwindowonpaint}
1334
1335 \func{void}{OnPaint}{\param{wxPaintEvent\& }{event}}
1336
1337 Sent to the event handler when the window must be refreshed.
1338
1339 \wxheading{Parameters}
1340
1341 \docparam{event}{Paint event. For more information, see \helpref{wxPaintEvent}{wxpaintevent}.}
1342
1343 \wxheading{Remarks}
1344
1345 Use the EVT\_PAINT macro in an event table definition to intercept paint events.
1346
1347 In a paint event handler, the application should always create a \helpref{wxPaintDC}{wxpaintdc} object.
1348
1349 For example:
1350
1351 \small{%
1352 \begin{verbatim}
1353 void MyWindow::OnPaint(wxPaintEvent& event)
1354 {
1355 wxPaintDC dc(this);
1356
1357 DrawMyDocument(dc);
1358 }
1359 \end{verbatim}
1360 }%
1361
1362 You can optimize painting by retrieving the rectangles
1363 that have been damaged and only repainting these. The rectangles are in
1364 terms of the client area, and are unscrolled, so you will need to do
1365 some calculations using the current view position to obtain logical,
1366 scrolled units.
1367
1368 Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} class:
1369
1370 {\small%
1371 \begin{verbatim}
1372 // Called when window needs to be repainted.
1373 void MyWindow::OnPaint(wxPaintEvent& event)
1374 {
1375 wxPaintDC dc(this);
1376
1377 // Find Out where the window is scrolled to
1378 int vbX,vbY; // Top left corner of client
1379 ViewStart(&vbX,&vbY);
1380
1381 int vX,vY,vW,vH; // Dimensions of client area in pixels
1382 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
1383
1384 while (upd)
1385 {
1386 vX = upd.GetX();
1387 vY = upd.GetY();
1388 vW = upd.GetW();
1389 vH = upd.GetH();
1390
1391 // Alternatively we can do this:
1392 // wxRect rect;
1393 // upd.GetRect(&rect);
1394
1395 // Repaint this rectangle
1396 ...some code...
1397
1398 upd ++ ;
1399 }
1400 }
1401 \end{verbatim}
1402 }%
1403
1404 \wxheading{See also}
1405
1406 \helpref{wxPaintEvent}{wxpaintevent},\rtfsp
1407 \helpref{wxPaintDC}{wxpaintdc},\rtfsp
1408 \helpref{Event handling overview}{eventhandlingoverview}
1409
1410 \membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
1411
1412 \func{void}{OnScroll}{\param{wxScrollWinEvent\& }{event}}
1413
1414 Called when a scroll window event is received from one of the window's built-in scrollbars.
1415
1416 \wxheading{Parameters}
1417
1418 \docparam{event}{Command event. Retrieve the new scroll position by
1419 calling \helpref{wxScrollEvent::GetPosition}{wxscrolleventgetposition}, and the
1420 scrollbar orientation by calling \helpref{wxScrollEvent::GetOrientation}{wxscrolleventgetorientation}.}
1421
1422 \wxheading{Remarks}
1423
1424 Note that it is not possible to distinguish between horizontal and vertical scrollbars
1425 until the function is executing (you can't have one function for vertical, another
1426 for horizontal events).
1427
1428 \wxheading{See also}
1429
1430 \helpref{wxScrollWinEvent}{wxscrollwinevent},\rtfsp
1431 \helpref{Event handling overview}{eventhandlingoverview}
1432
1433 \membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus}
1434
1435 \func{void}{OnSetFocus}{\param{wxFocusEvent\& }{event}}
1436
1437 Called when a window's focus is being set.
1438
1439 \wxheading{Parameters}
1440
1441 \docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.}
1442
1443 \wxheading{Remarks}
1444
1445 To intercept this event, use the macro EVT\_SET\_FOCUS in an event table definition.
1446
1447 Most, but not all, windows respond to this event.
1448
1449 \wxheading{See also}
1450
1451 \helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnKillFocus}{wxwindowonkillfocus},\rtfsp
1452 \helpref{Event handling overview}{eventhandlingoverview}
1453
1454 \membersection{wxWindow::OnSize}\label{wxwindowonsize}
1455
1456 \func{void}{OnSize}{\param{wxSizeEvent\& }{event}}
1457
1458 Called when the window has been resized.
1459
1460 \wxheading{Parameters}
1461
1462 \docparam{event}{Size event. For more information, see \helpref{wxSizeEvent}{wxsizeevent}.}
1463
1464 \wxheading{Remarks}
1465
1466 You may wish to use this for frames to resize their child windows as appropriate.
1467
1468 Note that the size passed is of
1469 the whole window: call \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize} for the area which may be
1470 used by the application.
1471
1472 \wxheading{See also}
1473
1474 \helpref{wxSizeEvent}{wxsizeevent},\rtfsp
1475 \helpref{Event handling overview}{eventhandlingoverview}
1476
1477 \membersection{wxWindow::OnSysColourChanged}\label{wxwindowonsyscolourchanged}
1478
1479 \func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}}
1480
1481 Called when the user has changed the system colours. Windows only.
1482
1483 \wxheading{Parameters}
1484
1485 \docparam{event}{System colour change event. For more information, see \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}.}
1486
1487 \wxheading{See also}
1488
1489 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp
1490 \helpref{Event handling overview}{eventhandlingoverview}
1491
1492 \membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler}
1493
1494 \constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = FALSE}}
1495
1496 Removes and returns the top-most event handler on the event handler stack.
1497
1498 \wxheading{Parameters}
1499
1500 \docparam{deleteHandler}{If this is TRUE, the handler will be deleted after it is removed. The
1501 default value is FALSE.}
1502
1503 \wxheading{See also}
1504
1505 \helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp
1506 \helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp
1507 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
1508 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp
1509 \helpref{wxEvtHandler}{wxevthandler}\rtfsp
1510
1511 \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu}
1512
1513 \func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint& }{pos}}
1514
1515 \func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}}
1516
1517 Pops up the given menu at the specified coordinates, relative to this
1518 window, and returns control when the user has dismissed the menu. If a
1519 menu item is selected, the corresponding menu event is generated and will be
1520 processed as usually.
1521
1522 \wxheading{Parameters}
1523
1524 \docparam{menu}{Menu to pop up.}
1525
1526 \docparam{pos}{The position where the menu will appear.}
1527
1528 \docparam{x}{Required x position for the menu to appear.}
1529
1530 \docparam{y}{Required y position for the menu to appear.}
1531
1532 \wxheading{See also}
1533
1534 \helpref{wxMenu}{wxmenu}
1535
1536 \wxheading{Remarks}
1537
1538 Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called
1539 to ensure that the menu items are in the correct state. The menu does not get deleted
1540 by the window.
1541
1542 \pythonnote{In place of a single overloaded method name, wxPython
1543 implements the following methods:\par
1544 \indented{2cm}{\begin{twocollist}
1545 \twocolitem{\bf{PopupMenu(menu, point)}}{Specifies position with a wxPoint}
1546 \twocolitem{\bf{PopupMenuXY(menu, x, y)}}{Specifies position with two integers (x, y)}
1547 \end{twocollist}}
1548 }
1549
1550 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
1551
1552 \func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}}
1553
1554 Pushes this event handler onto the event stack for the window.
1555
1556 \wxheading{Parameters}
1557
1558 \docparam{handler}{Specifies the handler to be pushed.}
1559
1560 \wxheading{Remarks}
1561
1562 An event handler is an object that is capable of processing the events
1563 sent to a window. By default, the window is its own event handler, but
1564 an application may wish to substitute another, for example to allow
1565 central implementation of event-handling for a variety of different
1566 window classes.
1567
1568 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} allows
1569 an application to set up a chain of event handlers, where an event not handled by one event handler is
1570 handed to the next one in the chain. Use \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} to
1571 remove the event handler.
1572
1573 \wxheading{See also}
1574
1575 \helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp
1576 \helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp
1577 \helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp
1578 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp
1579 \helpref{wxEvtHandler}{wxevthandler}
1580
1581 \membersection{wxWindow::Raise}\label{wxwindowraise}
1582
1583 \func{void}{Raise}{\void}
1584
1585 Raises the window to the top of the window hierarchy if it is a managed window (dialog
1586 or frame).
1587
1588 \membersection{wxWindow::Refresh}\label{wxwindowrefresh}
1589
1590 \func{virtual void}{Refresh}{\param{const bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect
1591 = NULL}}
1592
1593 Causes a message or event to be generated to repaint the
1594 window.
1595
1596 \wxheading{Parameters}
1597
1598 \docparam{eraseBackground}{If TRUE, the background will be
1599 erased.}
1600
1601 \docparam{rect}{If non-NULL, only the given rectangle will
1602 be treated as damaged.}
1603
1604 \membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse}
1605
1606 \func{virtual void}{ReleaseMouse}{\void}
1607
1608 Releases mouse input captured with \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}.
1609
1610 \wxheading{See also}
1611
1612 \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}
1613
1614 \membersection{wxWindow::RemoveChild}\label{wxwindowremovechild}
1615
1616 \func{virtual void}{RemoveChild}{\param{wxWindow* }{child}}
1617
1618 Removes a child window. This is called automatically by window deletion
1619 functions so should not be required by the application programmer.
1620
1621 \wxheading{Parameters}
1622
1623 \docparam{child}{Child window to remove.}
1624
1625 \membersection{wxWindow::Reparent}\label{wxwindowreparent}
1626
1627 \func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}}
1628
1629 Reparents the window, i.e the window will be removed from its
1630 current parent window (e.g. a non-standard toolbar in a wxFrame)
1631 and then re-inserted into another (e.g. a wxMiniFrame for a
1632 floating toolbar). Available on Windows and GTK+.
1633
1634 \wxheading{Parameters}
1635
1636 \docparam{newParent}{New parent.}
1637
1638 \membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient}
1639
1640 \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}}
1641
1642 \constfunc{virtual wxPoint}{ScreenToClient}{\param{const wxPoint\& }{pt}}
1643
1644 Converts from screen to client window coordinates.
1645
1646 \wxheading{Parameters}
1647
1648 \docparam{x}{Stores the screen x coordinate and receives the client x coordinate.}
1649
1650 \docparam{y}{Stores the screen x coordinate and receives the client x coordinate.}
1651
1652 \docparam{pt}{The screen position for the second form of the function.}
1653
1654 \pythonnote{In place of a single overloaded method name, wxPython
1655 implements the following methods:\par
1656 \indented{2cm}{\begin{twocollist}
1657 \twocolitem{\bf{ScreenToClient(point)}}{Accepts and returns a wxPoint}
1658 \twocolitem{\bf{ScreenToClientXY(x, y)}}{Returns a 2-tuple, (x, y)}
1659 \end{twocollist}}
1660 }
1661
1662
1663 \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow}
1664
1665 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}
1666
1667 Physically scrolls the pixels in the window and move child windows accordingly.
1668
1669 \wxheading{Parameters}
1670
1671 \docparam{dx}{Amount to scroll horizontally.}
1672
1673 \docparam{dy}{Amount to scroll vertically.}
1674
1675 \docparam{rect}{Rectangle to invalidate. If this is NULL, the whole window is invalidated. If you
1676 pass a rectangle corresponding to the area of the window exposed by the scroll, your painting handler
1677 can optimise painting by checking for the invalidated region. This paramter is ignored under GTK,
1678 instead the regions to be invalidated are calculated automatically. }
1679
1680 \wxheading{Remarks}
1681
1682 Use this function to optimise your scrolling implementations, to minimise the area that must be
1683 redrawn. Note that it is rarely required to call this function from a user program.
1684
1685 \membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable}
1686
1687 \func{virtual void}{SetAcceleratorTable}{\param{const wxAcceleratorTable\&}{ accel}}
1688
1689 Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}.
1690
1691 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
1692
1693 \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
1694
1695 Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will
1696 be called automatically when the window is resized. Use in connection with
1697 \helpref{wxWindow::SetSizer}{wxwindowsetsizer} and
1698 \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints} for layouting subwindows.
1699
1700 \wxheading{Parameters}
1701
1702 \docparam{autoLayout}{Set this to TRUE if you wish the Layout function to be called
1703 from within wxWindow::OnSize functions.}
1704
1705 \wxheading{Remarks}
1706
1707 Note that this function is actually disabled for wxWindow and only indirectly
1708 takes affect for children of wxDialog, wxFrame, wxNotebook and wxSplitterWindow.
1709
1710 \wxheading{See also}
1711
1712 \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}
1713
1714 \membersection{wxWindow::SetBackgroundColour}\label{wxwindowsetbackgroundcolour}
1715
1716 \func{virtual void}{SetBackgroundColour}{\param{const wxColour\& }{colour}}
1717
1718 Sets the background colour of the window.
1719
1720 \wxheading{Parameters}
1721
1722 \docparam{colour}{The colour to be used as the background colour.}
1723
1724 \wxheading{Remarks}
1725
1726 The background colour is usually painted by the default\rtfsp
1727 \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} event handler function
1728 under Windows and automatically under GTK.
1729
1730 Note that setting the background colour does not cause an immediate refresh, so you
1731 may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after
1732 calling this function.
1733
1734 Note that when using this functions under GTK, you will disable the so called "themes",
1735 i.e. the user chosen apperance of windows and controls, including the themes of
1736 their parent windows.
1737
1738 \wxheading{See also}
1739
1740 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp
1741 \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp
1742 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
1743 \helpref{wxWindow::Clear}{wxwindowclear},\rtfsp
1744 \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp
1745 \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground}
1746
1747 \membersection{wxWindow::SetClientSize}\label{wxwindowsetclientsize}
1748
1749 \func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}}
1750
1751 \func{virtual void}{SetClientSize}{\param{const wxSize\&}{ size}}
1752
1753 This sets the size of the window client area in pixels. Using this function to size a window
1754 tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not
1755 worry about what dimensions the border or title bar have when trying to fit the window
1756 around panel items, for example.
1757
1758 \wxheading{Parameters}
1759
1760 \docparam{width}{The required client area width.}
1761
1762 \docparam{height}{The required client area height.}
1763
1764 \docparam{size}{The required client size.}
1765
1766 \pythonnote{In place of a single overloaded method name, wxPython
1767 implements the following methods:\par
1768 \indented{2cm}{\begin{twocollist}
1769 \twocolitem{\bf{SetClientSize(size)}}{Accepts a wxSize}
1770 \twocolitem{\bf{SetClientSizeWH(width, height)}}{}
1771 \end{twocollist}}
1772 }
1773
1774 \membersection{wxWindow::SetCursor}\label{wxwindowsetcursor}
1775
1776 \func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}}
1777
1778 Sets the window's cursor. Notice that setting the cursor for this window does
1779 not set it for its children so you'll need to explicitly call SetCursor() for
1780 them too if you need it.
1781
1782 \wxheading{Parameters}
1783
1784 \docparam{cursor}{Specifies the cursor that the window should normally display.}
1785
1786 \wxheading{See also}
1787
1788 \helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor}
1789
1790 \membersection{wxWindow::SetEventHandler}\label{wxwindowseteventhandler}
1791
1792 \func{void}{SetEventHandler}{\param{wxEvtHandler* }{handler}}
1793
1794 Sets the event handler for this window.
1795
1796 \wxheading{Parameters}
1797
1798 \docparam{handler}{Specifies the handler to be set.}
1799
1800 \wxheading{Remarks}
1801
1802 An event handler is an object that is capable of processing the events
1803 sent to a window. By default, the window is its own event handler, but
1804 an application may wish to substitute another, for example to allow
1805 central implementation of event-handling for a variety of different
1806 window classes.
1807
1808 It is usually better to use \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} since
1809 this sets up a chain of event handlers, where an event not handled by one event handler is
1810 handed to the next one in the chain.
1811
1812 \wxheading{See also}
1813
1814 \helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp
1815 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
1816 \helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp
1817 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp
1818 \helpref{wxEvtHandler}{wxevthandler}
1819
1820 \membersection{wxWindow::SetConstraints}\label{wxwindowsetconstraints}
1821
1822 \func{void}{SetConstraints}{\param{wxLayoutConstraints* }{constraints}}
1823
1824 Sets the window to have the given layout constraints. The window
1825 will then own the object, and will take care of its deletion.
1826 If an existing layout constraints object is already owned by the
1827 window, it will be deleted.
1828
1829 \wxheading{Parameters}
1830
1831 \docparam{constraints}{The constraints to set. Pass NULL to disassociate and delete the window's
1832 constraints.}
1833
1834 \wxheading{Remarks}
1835
1836 You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use
1837 the constraints automatically in OnSize; otherwise, you must override OnSize and call Layout()
1838 explicitly. When setting both a wxLayoutConstraints and a \helpref{wxSizer}{wxsizer}, only the
1839 sizer will have effect.
1840
1841 \membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget}
1842
1843 \func{void}{SetDropTarget}{\param{wxDropTarget*}{ target}}
1844
1845 Associates a drop target with this window.
1846
1847 If the window already has a drop target, it is deleted.
1848
1849 \wxheading{See also}
1850
1851 \helpref{wxWindow::GetDropTarget}{wxwindowgetdroptarget},
1852 \helpref{Drag and drop overview}{wxdndoverview}
1853
1854 \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus}
1855
1856 \func{virtual void}{SetFocus}{\void}
1857
1858 This sets the window to receive keyboard input.
1859
1860 \membersection{wxWindow::SetFont}\label{wxwindowsetfont}
1861
1862 \func{void}{SetFont}{\param{const wxFont\& }{font}}
1863
1864 Sets the font for this window.
1865
1866 \wxheading{Parameters}
1867
1868 \docparam{font}{Font to associate with this window.}
1869
1870 \wxheading{See also}
1871
1872 \helpref{wxWindow::GetFont}{wxwindowgetfont}
1873
1874 \membersection{wxWindow::SetForegroundColour}\label{wxwindowsetforegroundcolour}
1875
1876 \func{virtual void}{SetForegroundColour}{\param{const wxColour\& }{colour}}
1877
1878 Sets the foreground colour of the window.
1879
1880 \wxheading{Parameters}
1881
1882 \docparam{colour}{The colour to be used as the foreground colour.}
1883
1884 \wxheading{Remarks}
1885
1886 The interpretation of foreground colour is open to interpretation according
1887 to the window class; it may be the text colour or other colour, or it may not
1888 be used at all.
1889
1890 Note that when using this functions under GTK, you will disable the so called "themes",
1891 i.e. the user chosen apperance of windows and controls, including the themes of
1892 their parent windows.
1893
1894 \wxheading{See also}
1895
1896 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
1897 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
1898 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour}
1899
1900 \membersection{wxWindow::SetId}\label{wxwindowsetid}
1901
1902 \func{void}{SetId}{\param{int}{ id}}
1903
1904 Sets the identifier of the window.
1905
1906 \wxheading{Remarks}
1907
1908 Each window has an integer identifier. If the application has not provided one,
1909 an identifier will be generated. Normally, the identifier should be provided
1910 on creation and should not be modified subsequently.
1911
1912 \wxheading{See also}
1913
1914 \helpref{wxWindow::GetId}{wxwindowgetid},\rtfsp
1915 \helpref{Window identifiers}{windowids}
1916
1917 \membersection{wxWindow::SetName}\label{wxwindowsetname}
1918
1919 \func{virtual void}{SetName}{\param{const wxString\& }{name}}
1920
1921 Sets the window's name.
1922
1923 \wxheading{Parameters}
1924
1925 \docparam{name}{A name to set for the window.}
1926
1927 \wxheading{See also}
1928
1929 \helpref{wxWindow::GetName}{wxwindowgetname}
1930
1931 \membersection{wxWindow::SetPalette}\label{wxwindowsetpalette}
1932
1933 \func{virtual void}{SetPalette}{\param{wxPalette* }{palette}}
1934
1935 Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead.
1936
1937 \membersection{wxWindow::SetScrollbar}\label{wxwindowsetscrollbar}
1938
1939 \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp
1940 \param{int }{thumbSize}, \param{int }{range},\rtfsp
1941 \param{const bool }{refresh = TRUE}}
1942
1943 Sets the scrollbar properties of a built-in scrollbar.
1944
1945 \wxheading{Parameters}
1946
1947 \docparam{orientation}{Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL or wxVERTICAL.}
1948
1949 \docparam{position}{The position of the scrollbar in scroll units.}
1950
1951 \docparam{thumbSize}{The size of the thumb, or visible portion of the scrollbar, in scroll units.}
1952
1953 \docparam{range}{The maximum position of the scrollbar.}
1954
1955 \docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.}
1956
1957 \wxheading{Remarks}
1958
1959 Let's say you wish to display 50 lines of text, using the same font.
1960 The window is sized so that you can only see 16 lines at a time.
1961
1962 You would use:
1963
1964 {\small%
1965 \begin{verbatim}
1966 SetScrollbar(wxVERTICAL, 0, 16, 50);
1967 \end{verbatim}
1968 }
1969
1970 Note that with the window at this size, the thumb position can never go
1971 above 50 minus 16, or 34.
1972
1973 You can determine how many lines are currently visible by dividing the current view
1974 size by the character height in pixels.
1975
1976 When defining your own scrollbar behaviour, you will always need to recalculate
1977 the scrollbar settings when the window size changes. You could therefore put your
1978 scrollbar calculations and SetScrollbar
1979 call into a function named AdjustScrollbars, which can be called initially and also
1980 from your \helpref{wxWindow::OnSize}{wxwindowonsize} event handler function.
1981
1982 \wxheading{See also}
1983
1984 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
1985 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
1986
1987 \begin{comment}
1988 \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage}
1989
1990 \func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{const bool }{refresh = TRUE}}
1991
1992 Sets the page size of one of the built-in scrollbars.
1993
1994 \wxheading{Parameters}
1995
1996 \docparam{orientation}{Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL or wxVERTICAL.}
1997
1998 \docparam{pageSize}{Page size in scroll units.}
1999
2000 \docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.}
2001
2002 \wxheading{Remarks}
2003
2004 The page size of a scrollbar is the number of scroll units that the scroll thumb travels when you
2005 click on the area above/left of or below/right of the thumb. Normally you will want a whole visible
2006 page to be scrolled, i.e. the size of the current view (perhaps the window client size). This
2007 value has to be adjusted when the window is resized, since the page size will have changed.
2008
2009 In addition to specifying how far the scroll thumb travels when paging, in Motif and some versions of Windows
2010 the thumb changes size to reflect the page size relative to the length of the document. When the
2011 document size is only slightly bigger than the current view (window) size, almost all of the scrollbar
2012 will be taken up by the thumb. When the two values become the same, the scrollbar will (on some systems)
2013 disappear.
2014
2015 Currently, this function should be called before SetPageRange, because of a quirk in the Windows
2016 handling of pages and ranges.
2017
2018 \wxheading{See also}
2019
2020 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp
2021 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
2022 \helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp
2023 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
2024 \end{comment}
2025
2026 \membersection{wxWindow::SetScrollPos}\label{wxwindowsetscrollpos}
2027
2028 \func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{const bool }{refresh = TRUE}}
2029
2030 Sets the position of one of the built-in scrollbars.
2031
2032 \wxheading{Parameters}
2033
2034 \docparam{orientation}{Determines the scrollbar whose position is to be set. May be wxHORIZONTAL or wxVERTICAL.}
2035
2036 \docparam{pos}{Position in scroll units.}
2037
2038 \docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.}
2039
2040 \wxheading{Remarks}
2041
2042 This function does not directly affect the contents of the window: it is up to the
2043 application to take note of scrollbar attributes and redraw contents accordingly.
2044
2045 \wxheading{See also}
2046
2047 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar},\rtfsp
2048 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
2049 \helpref{wxWindow::GetScrollThumb}{wxwindowgetscrollthumb},\rtfsp
2050 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
2051
2052 \begin{comment}
2053 \membersection{wxWindow::SetScrollRange}\label{wxwindowsetscrollrange}
2054
2055 \func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{const bool }{refresh = TRUE}}
2056
2057 Sets the range of one of the built-in scrollbars.
2058
2059 \wxheading{Parameters}
2060
2061 \docparam{orientation}{Determines the scrollbar whose range is to be set. May be wxHORIZONTAL or wxVERTICAL.}
2062
2063 \docparam{range}{Scroll range.}
2064
2065 \docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.}
2066
2067 \wxheading{Remarks}
2068
2069 The range of a scrollbar is the number of steps that the thumb may travel, rather than the total
2070 object length of the scrollbar. If you are implementing a scrolling window, for example, you
2071 would adjust the scroll range when the window is resized, by subtracting the window view size from the
2072 total virtual window size. When the two sizes are the same (all the window is visible), the range goes to zero
2073 and usually the scrollbar will be automatically hidden.
2074
2075 \wxheading{See also}
2076
2077 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp
2078 \helpref{wxWindow::SetScrollPage}{wxwindowsetscrollpage},\rtfsp
2079 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
2080 \helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp
2081 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
2082 \end{comment}
2083
2084 \membersection{wxWindow::SetSize}\label{wxwindowsetsize}
2085
2086 \func{virtual void}{SetSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height},
2087 \param{int}{ sizeFlags = wxSIZE\_AUTO}}
2088
2089 \func{virtual void}{SetSize}{\param{const wxRect\&}{ rect}}
2090
2091 Sets the size and position of the window in pixels.
2092
2093 \func{virtual void}{SetSize}{\param{int}{ width}, \param{int}{ height}}
2094
2095 \func{virtual void}{SetSize}{\param{const wxSize\&}{ size}}
2096
2097 Sets the size of the window in pixels.
2098
2099 \wxheading{Parameters}
2100
2101 \docparam{x}{Required x position in pixels, or -1 to indicate that the existing
2102 value should be used.}
2103
2104 \docparam{y}{Required y position in pixels, or -1 to indicate that the existing
2105 value should be used.}
2106
2107 \docparam{width}{Required width in pixels, or -1 to indicate that the existing
2108 value should be used.}
2109
2110 \docparam{height}{Required height position in pixels, or -1 to indicate that the existing
2111 value should be used.}
2112
2113 \docparam{size}{\helpref{wxSize}{wxsize} object for setting the size.}
2114
2115 \docparam{rect}{\helpref{wxRect}{wxrect} object for setting the position and size.}
2116
2117 \docparam{sizeFlags}{Indicates the interpretation of other parameters. It is a bit list of the following:
2118
2119 {\bf wxSIZE\_AUTO\_WIDTH}: a -1 width value is taken to indicate
2120 a wxWindows-supplied default width.\\
2121 {\bf wxSIZE\_AUTO\_HEIGHT}: a -1 height value is taken to indicate
2122 a wxWindows-supplied default width.\\
2123 {\bf wxSIZE\_AUTO}: -1 size values are taken to indicate
2124 a wxWindows-supplied default size.\\
2125 {\bf wxSIZE\_USE\_EXISTING}: existing dimensions should be used
2126 if -1 values are supplied.\\
2127 {\bf wxSIZE\_ALLOW\_MINUS\_ONE}: allow dimensions of -1 and less to be interpreted
2128 as real dimensions, not default values.
2129 }
2130
2131 \wxheading{Remarks}
2132
2133 The second form is a convenience for calling the first form with default
2134 x and y parameters, and must be used with non-default width and height values.
2135
2136 The first form sets the position and optionally size, of the window.
2137 Parameters may be -1 to indicate either that a default should be supplied
2138 by wxWindows, or that the current value of the dimension should be used.
2139
2140 \wxheading{See also}
2141
2142 \helpref{wxWindow::Move}{wxwindowmove}
2143
2144 \pythonnote{In place of a single overloaded method name, wxPython
2145 implements the following methods:\par
2146 \indented{2cm}{\begin{twocollist}
2147 \twocolitem{\bf{SetDimensions(x, y, width, height, sizeFlags=wxSIZE_AUTO)}}{}
2148 \twocolitem{\bf{SetSize(size)}}{}
2149 \twocolitem{\bf{SetPosition(point)}}{}
2150 \end{twocollist}}
2151 }
2152
2153 \membersection{wxWindow::SetSizeHints}\label{wxwindowsetsizehints}
2154
2155 \func{virtual void}{SetSizeHints}{\param{int}{ minW=-1}, \param{int}{ minH=-1}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1},
2156 \param{int}{ incW=-1}, \param{int}{ incH=-1}}
2157
2158 Allows specification of minimum and maximum window sizes, and window size increments.
2159 If a pair of values is not set (or set to -1), the default values will be used.
2160
2161 \wxheading{Parameters}
2162
2163 \docparam{minW}{Specifies the minimum width allowable.}
2164
2165 \docparam{minH}{Specifies the minimum height allowable.}
2166
2167 \docparam{maxW}{Specifies the maximum width allowable.}
2168
2169 \docparam{maxH}{Specifies the maximum height allowable.}
2170
2171 \docparam{incW}{Specifies the increment for sizing the width (Motif/Xt only).}
2172
2173 \docparam{incH}{Specifies the increment for sizing the height (Motif/Xt only).}
2174
2175 \wxheading{Remarks}
2176
2177 If this function is called, the user will not be able to size the window outside the
2178 given bounds.
2179
2180 The resizing increments are only significant under Motif or Xt.
2181
2182 \membersection{wxWindow::SetSizer}\label{wxwindowsetsizer}
2183
2184 \func{void}{SetSizer}{\param{wxSizer* }{sizer}}
2185
2186 Sets the window to have the given layout sizer. The window
2187 will then own the object, and will take care of its deletion.
2188 If an existing layout constraints object is already owned by the
2189 window, it will be deleted.
2190
2191 \wxheading{Parameters}
2192
2193 \docparam{sizer}{The sizer to set. Pass NULL to disassociate and delete the window's
2194 sizer.}
2195
2196 \wxheading{Remarks}
2197
2198 You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use
2199 the sizer automatically in OnSize; otherwise, you must override OnSize and call Layout()
2200 explicitly. When setting both a wxSizer and a \helpref{wxLayoutConstraints}{wxlayoutconstraints},
2201 only the sizer will have effect.
2202
2203 \membersection{wxWindow::SetTitle}\label{wxwindowsettitle}
2204
2205 \func{virtual void}{SetTitle}{\param{const wxString\& }{title}}
2206
2207 Sets the window's title. Applicable only to frames and dialogs.
2208
2209 \wxheading{Parameters}
2210
2211 \docparam{title}{The window's title.}
2212
2213 \wxheading{See also}
2214
2215 \helpref{wxWindow::GetTitle}{wxwindowgettitle}
2216
2217 \membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
2218
2219 \func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
2220
2221 Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to
2222 create a new validator of this type.
2223
2224 \membersection{wxWindow::Show}\label{wxwindowshow}
2225
2226 \func{virtual bool}{Show}{\param{const bool}{ show}}
2227
2228 Shows or hides the window.
2229
2230 \wxheading{Parameters}
2231
2232 \docparam{show}{If TRUE, displays the window and brings it to the front. Otherwise,
2233 hides the window.}
2234
2235 \wxheading{See also}
2236
2237 \helpref{wxWindow::IsShown}{wxwindowisshown}
2238
2239 \membersection{wxWindow::TransferDataFromWindow}\label{wxwindowtransferdatafromwindow}
2240
2241 \func{virtual bool}{TransferDataFromWindow}{\void}
2242
2243 Transfers values from child controls to data areas specified by their validators. Returns
2244 FALSE if a transfer failed.
2245
2246 \wxheading{See also}
2247
2248 \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow},\rtfsp
2249 \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::Validate}{wxwindowvalidate}
2250
2251 \membersection{wxWindow::TransferDataToWindow}\label{wxwindowtransferdatatowindow}
2252
2253 \func{virtual bool}{TransferDataToWindow}{\void}
2254
2255 Transfers values to child controls from data areas specified by their validators.
2256
2257 \wxheading{Return value}
2258
2259 Returns FALSE if a transfer failed.
2260
2261 \wxheading{See also}
2262
2263 \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp
2264 \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::Validate}{wxwindowvalidate}
2265
2266 \membersection{wxWindow::Validate}\label{wxwindowvalidate}
2267
2268 \func{virtual bool}{Validate}{\void}
2269
2270 Validates the current values of the child controls using their validators.
2271
2272 \wxheading{Return value}
2273
2274 Returns FALSE if any of the validations failed.
2275
2276 \wxheading{See also}
2277
2278 \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp
2279 \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp
2280 \helpref{wxValidator}{wxvalidator}
2281
2282 \membersection{wxWindow::WarpPointer}\label{wxwindowwarppointer}
2283
2284 \func{void}{WarpPointer}{\param{int}{ x}, \param{int}{ y}}
2285
2286 Moves the pointer to the given position on the window.
2287
2288 \wxheading{Parameters}
2289
2290 \docparam{x}{The new x position for the cursor.}
2291
2292 \docparam{y}{The new y position for the cursor.}
2293