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