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