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