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