]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/tlw.tex
cleanup
[wxWidgets.git] / docs / latex / wx / tlw.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: tlw.tex
3 %% Purpose: wxTopLevelWindow documentation
4 %% Author: Vadim Zeitlin
5 %% Modified by:
6 %% Created: 2004-09-07 (partly extracted from frame.tex)
7 %% RCS-ID: $Id$
8 %% Copyright: (c) 2004 Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxTopLevelWindow}}\label{wxtoplevelwindow}
13
14 wxTopLevelWindow is a common base class for \helpref{wxDialog}{wxdialog} and
15 \helpref{wxFrame}{wxframe}. It is an abstract base class meaning that you never
16 work with objects of this class directly, but all of its methods are also
17 applicable for the two classes above.
18
19 \wxheading{Derived from}
20
21 \helpref{wxWindow}{wxwindow}\\
22 \helpref{wxEvtHandler}{wxevthandler}\\
23 \helpref{wxObject}{wxobject}
24
25 \wxheading{Include files}
26
27 <wx/toplevel.h>
28
29 \wxheading{Library}
30
31 \helpref{wxCore}{librarieslist}
32
33
34 \latexignore{\rtfignore{\wxheading{Members}}}
35
36 \membersection{wxTopLevelWindow::CanSetTransparent}\label{wxtoplevelwindowcansettransparent}
37
38 \func{virtual bool}{CanSetTransparent}{\void}
39
40 Returns \true if the platform supports making the window translucent.
41
42 \wxheading{See also}
43
44 \helpref{wxTopLevelWindow::SetTransparent}{wxtoplevelwindowsettransparent}
45
46
47 \membersection{wxTopLevelWindow::EnableCloseButton}\label{wxtoplevelenableclosebutton}
48
49 \func{bool}{EnableCloseButton}{\param{bool}{ enable = true}}
50
51 Enables or disables the Close button (most often in the right
52 upper corner of a dialog) and the Close entry of the system
53 menu (most often in the left upper corner of the dialog).
54 Currently only implemented for wxMSW and wxGTK. Returns
55 true if operation was successful. This may be wrong on
56 X11 (including GTK+) where the window manager may not support
57 this operation and there is no way to find out.
58
59 \membersection{wxTopLevelWindow::GetDefaultItem}\label{wxtoplevelwindowgetdefaultitem}
60
61 \constfunc{wxWindow *}{GetDefaultItem}{\void}
62
63 Returns a pointer to the button which is the default for this window, or \NULL.
64 The default button is the one activated by pressing the Enter key.
65
66
67 \membersection{wxTopLevelWindow::GetIcon}\label{wxtoplevelwindowgeticon}
68
69 \constfunc{const wxIcon\&}{GetIcon}{\void}
70
71 Returns the standard icon of the window. The icon will be invalid if it hadn't
72 been previously set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
73
74 \wxheading{See also}
75
76 \helpref{GetIcons}{wxtoplevelwindowgeticons}
77
78
79 \membersection{wxTopLevelWindow::GetIcons}\label{wxtoplevelwindowgeticons}
80
81 \constfunc{const wxIconBundle\&}{GetIcons}{\void}
82
83 Returns all icons associated with the window, there will be none of them if
84 neither \helpref{SetIcon}{wxtoplevelwindowseticon} nor
85 \helpref{SetIcons}{wxtoplevelwindowseticons} had been called before.
86
87 Use \helpref{GetIcon}{wxtoplevelwindowgeticon} to get the main icon of the
88 window.
89
90 \wxheading{See also}
91
92 \helpref{wxIconBundle}{wxiconbundle}
93
94
95 \membersection{wxTopLevelWindow::GetTitle}\label{wxtoplevelwindowgettitle}
96
97 \constfunc{wxString}{GetTitle}{\void}
98
99 Gets a string containing the window title.
100
101 \wxheading{See also}
102
103 \helpref{wxTopLevelWindow::SetTitle}{wxtoplevelwindowsettitle}
104
105
106 \membersection{wxTopLevelWindow::HandleSettingChange}\label{wxtoplevelwindowhandlesettingchange}
107
108 \func{virtual bool}{HandleSettingChange}{\param{WXWPARAM}{ wParam}, \param{WXLPARAM}{ lParam}}
109
110 Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel) area and resize
111 window accordingly. Override this if you want to avoid resizing or do additional
112 operations.
113
114
115 \membersection{wxTopLevelWindow::IsActive}\label{wxtoplevelwindowisactive}
116
117 \constfunc{bool}{IsActive}{\void}
118
119 Returns \true if this window is currently active, i.e. if the user is currently
120 working with it.
121
122
123 \membersection{wxTopLevelWindow::IsAlwaysMaximized}\label{wxtoplevelwindowisalwaysmaximized}
124
125 \constfunc{virtual bool}{IsAlwaysMaximized}{\void}
126
127 Returns \true if this window is expected to be always maximized, either due to platform policy
128 or due to local policy regarding particular class.
129
130
131 \membersection{wxTopLevelWindow::Iconize}\label{wxtoplevelwindowiconize}
132
133 \func{void}{Iconize}{\param{bool}{ iconize}}
134
135 Iconizes or restores the window.
136
137 \wxheading{Parameters}
138
139 \docparam{iconize}{If \true, iconizes the window; if \false, shows and restores it.}
140
141 \wxheading{See also}
142
143 \helpref{wxTopLevelWindow::IsIconized}{wxtoplevelwindowisiconized}, \helpref{wxTopLevelWindow::Maximize}{wxtoplevelwindowmaximize}.
144
145
146 \membersection{wxTopLevelWindow::IsFullScreen}\label{wxtoplevelwindowisfullscreen}
147
148 \func{bool}{IsFullScreen}{\void}
149
150 Returns \true if the window is in fullscreen mode.
151
152 \wxheading{See also}
153
154 \helpref{wxTopLevelWindow::ShowFullScreen}{wxtoplevelwindowshowfullscreen}
155
156
157 \membersection{wxTopLevelWindow::IsIconized}\label{wxtoplevelwindowisiconized}
158
159 \constfunc{bool}{IsIconized}{\void}
160
161 Returns \true if the window is iconized.
162
163
164 \membersection{wxTopLevelWindow::IsMaximized}\label{wxtoplevelwindowismaximized}
165
166 \constfunc{bool}{IsMaximized}{\void}
167
168 Returns \true if the window is maximized.
169
170
171 \membersection{wxTopLevelWindow::IsUsingNativeDecorations}\label{wxtoplevelwindowisusingnativedecorations}
172
173 \constfunc{bool}{IsUsingNativeDecorations}{\void}
174
175 \bftt{This method is specific to wxUniversal port}
176
177 Returns \true if this window is using native decorations, \false if we draw
178 them ourselves.
179
180 \wxheading{See also}
181
182 \helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations},\\
183 \helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault}
184
185
186 \membersection{wxTopLevelWindow::Maximize}\label{wxtoplevelwindowmaximize}
187
188 \func{void}{Maximize}{\param{bool }{maximize}}
189
190 Maximizes or restores the window.
191
192 \wxheading{Parameters}
193
194 \docparam{maximize}{If \true, maximizes the window, otherwise it restores it.}
195
196 \wxheading{See also}
197
198 \helpref{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
199
200
201 \membersection{wxTopLevelWindow::RequestUserAttention}\label{wxtoplevelwindowrequestuserattention}
202
203 \func{void}{RequestUserAttention}{\param{int }{flags = wxUSER\_ATTENTION\_INFO}}
204
205 Use a system-dependent way to attract users attention to the window when it is
206 in background.
207
208 \arg{flags} may have the value of either \texttt{wxUSER\_ATTENTION\_INFO}
209 (default) or \texttt{wxUSER\_ATTENTION\_ERROR} which results in a more drastic
210 action. When in doubt, use the default value.
211
212 Note that this function should normally be only used when the application is
213 not already in foreground.
214
215 This function is currently implemented for Win32 where it flashes the
216 window icon in the taskbar, and for wxGTK with task bars supporting it.
217
218
219 \membersection{wxTopLevelWindow::SetDefaultItem}\label{wxtoplevelwindowsetdefaultitem}
220
221 \func{void}{SetDefaultItem}{\param{wxWindow }{*win}}
222
223 Changes the default item for the panel, usually \arg{win} is a button.
224
225 \wxheading{See also}
226
227 \helpref{GetDefaultItem}{wxtoplevelwindowgetdefaultitem}
228
229
230 \membersection{wxTopLevelWindow::SetIcon}\label{wxtoplevelwindowseticon}
231
232 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
233
234 Sets the icon for this window.
235
236 \wxheading{Parameters}
237
238 \docparam{icon}{The icon to associate with this window.}
239
240 \wxheading{Remarks}
241
242 The window takes a `copy' of {\it icon}, but since it uses reference
243 counting, the copy is very quick. It is safe to delete {\it icon} after
244 calling this function.
245
246 See also \helpref{wxIcon}{wxicon}.
247
248
249 \membersection{wxTopLevelWindow::SetIcons}\label{wxtoplevelwindowseticons}
250
251 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
252
253 Sets several icons of different sizes for this window: this allows to use
254 different icons for different situations (e.g. task switching bar, taskbar,
255 window title bar) instead of scaling, with possibly bad looking results, the
256 only icon set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
257
258 \wxheading{Parameters}
259
260 \docparam{icons}{The icons to associate with this window.}
261
262 \wxheading{See also}
263
264 \helpref{wxIconBundle}{wxiconbundle}.
265
266
267 \membersection{wxTopLevelWindow::SetLeftMenu}\label{wxtoplevelwindowsetleftmenu}
268
269 \func{void}{SetLeftMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
270
271 Sets action or menu activated by pressing left hardware button on the smart phones.
272 Unavailable on full keyboard machines.
273
274 \wxheading{Parameters}
275
276 \docparam{id}{Identifier for this button.}
277
278 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
279
280 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
281
282 \wxheading{See also}
283
284 \helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}.
285
286
287 \membersection{wxTopLevelWindow::SetMaxSize}\label{wxtoplevelwindowsetmaxsize}
288
289 \func{void}{SetMaxSize}{\param{const wxSize\& }{size}}
290
291 A simpler interface for setting the size hints than
292 \helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
293
294 \membersection{wxTopLevelWindow::SetMinSize}\label{wxtoplevelwindowsetminsize}
295
296 \func{void}{SetMinSize}{\param{const wxSize\& }{size}}
297
298 A simpler interface for setting the size hints than
299 \helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
300
301 \membersection{wxTopLevelWindow::SetSizeHints}\label{wxtoplevelwindowsetsizehints}
302
303 \func{virtual void}{SetSizeHints}{\param{int}{ minW}, \param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1},
304 \param{int}{ incW=-1}, \param{int}{ incH=-1}}
305
306 \func{void}{SetSizeHints}{\param{const wxSize\&}{ minSize},
307 \param{const wxSize\&}{ maxSize=wxDefaultSize}, \param{const wxSize\&}{ incSize=wxDefaultSize}}
308
309 Allows specification of minimum and maximum window sizes, and window size increments.
310 If a pair of values is not set (or set to -1), the default values will be used.
311
312 \docparam{incW}{Specifies the increment for sizing the width (GTK/Motif/Xt only).}
313
314 \docparam{incH}{Specifies the increment for sizing the height (GTK/Motif/Xt only).}
315
316 \docparam{incSize}{Increment size (GTK/Motif/Xt only).}
317
318 \wxheading{Remarks}
319
320 If this function is called, the user will not be able to size the window outside
321 the given bounds. The resizing increments are only significant under GTK, Motif or Xt.
322
323
324 \membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
325
326 \func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
327
328 Sets action or menu activated by pressing right hardware button on the smart phones.
329 Unavailable on full keyboard machines.
330
331 \wxheading{Parameters}
332
333 \docparam{id}{Identifier for this button.}
334
335 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
336
337 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
338
339 \wxheading{See also}
340
341 \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
342
343
344 \membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
345
346 \func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
347
348 If the platform supports it, sets the shape of the window to that
349 depicted by {\it region}. The system will not display or
350 respond to any mouse event for the pixels that lie outside of the
351 region. To reset the window to the normal rectangular shape simply
352 call {\it SetShape} again with an empty region. Returns true if the
353 operation is successful.
354
355
356 \membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
357
358 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
359
360 Sets the window title.
361
362 \wxheading{Parameters}
363
364 \docparam{title}{The window title.}
365
366 \wxheading{See also}
367
368 \helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
369
370
371 \membersection{wxTopLevelWindow::SetTransparent}\label{wxtoplevelwindowsettransparent}
372
373 \func{virtual bool}{SetTransparent}{\param{int }{ alpha}}
374
375 If the platform supports it will set the window to be translucent
376
377 \wxheading{Parameters}
378
379 \docparam{alpha}{Determines how opaque or transparent the window will
380 be, if the platform supports the opreration. A value of 0 sets the
381 window to be fully transparent, and a value of 255 sets the window
382 to be fully opaque.}
383
384 Returns \true if the transparency was successfully changed.
385
386
387
388 \membersection{wxTopLevelWindow::ShouldPreventAppExit}\label{wxtoplevelwindowshouldpreventappexit}
389
390 \constfunc{virtual bool}{ShouldPreventAppExit}{\void}
391
392 This virtual function is not meant to be called directly but can be overridden
393 to return \false (it returns \true by default) to allow the application to
394 close even if this, presumably not very important, window is still opened.
395 By default, the application stays alive as long as there are any open top level
396 windows.
397
398
399 \membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
400
401 \func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
402
403 Depending on the value of {\it show} parameter the window is either shown full
404 screen or restored to its normal state. {\it style} is a bit list containing
405 some or all of the following values, which indicate what elements of the window
406 to hide in full-screen mode:
407
408 \begin{itemize}\itemsep=0pt
409 \item wxFULLSCREEN\_NOMENUBAR
410 \item wxFULLSCREEN\_NOTOOLBAR
411 \item wxFULLSCREEN\_NOSTATUSBAR
412 \item wxFULLSCREEN\_NOBORDER
413 \item wxFULLSCREEN\_NOCAPTION
414 \item wxFULLSCREEN\_ALL (all of the above)
415 \end{itemize}
416
417 This function has not been tested with MDI frames.
418
419 Note that showing a window full screen also actually
420 \helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
421
422 \wxheading{See also}
423
424 \helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}
425
426
427 \membersection{wxTopLevelWindow::UseNativeDecorations}\label{wxtoplevelwindowusenativedecorations}
428
429 \func{void}{UseNativeDecorations}{\param{bool }{native = \true}}
430
431 \bftt{This method is specific to wxUniversal port}
432
433 Use native or custom-drawn decorations for this window only. Notice that to
434 have any effect this method must be called before really creating the window,
435 i.e. two step creation must be used:
436 \begin{verbatim}
437 MyFrame *frame = new MyFrame; // use default ctor
438 frame->UseNativeDecorations(false); // change from default "true"
439 frame->Create(parent, title, ...); // really create the frame
440 \end{verbatim}
441
442 \wxheading{See also}
443
444 \helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault},\\
445 \helpref{IsUsingNativeDecorations}{wxtoplevelwindowisusingnativedecorations}
446
447
448 \membersection{wxTopLevelWindow::UseNativeDecorationsByDefault}\label{wxtoplevelwindowusenativedecorationsbydefault}
449
450 \func{void}{UseNativeDecorationsByDefault}{\param{bool }{native = \true}}
451
452 \bftt{This method is specific to wxUniversal port}
453
454 Top level windows in wxUniversal port can use either system-provided window
455 decorations (i.e. title bar and various icons, buttons and menus in it) or draw
456 the decorations themselves. By default the system decorations are used if they
457 are available, but this method can be called with \arg{native} set to \false to
458 change this for all windows created after this point.
459
460 Also note that if \texttt{WXDECOR} environment variable is set, then custom
461 decorations are used by default and so it may make sense to call this method
462 with default argument if the application can't use custom decorations at all
463 for some reason.
464
465 \wxheading{See also}
466
467 \helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations}
468