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