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