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