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