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), no constraints 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 (only taken into account under X11-based
 340 ports such as wxGTK/wxMotif/wxX11).}
 341
 342 \wxheading{Remarks}
 343
 344 Notice that this function not only prevents the user from resizing the window
 345 outside the given bounds but it also prevents the program itself from doing it
 346 using \helpref{SetSize}{wxwindowsetsize}.
 347
 348
 349 \membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
 350
 351 \func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 352
 353 Sets action or menu activated by pressing right hardware button on the smart phones.
 354 Unavailable on full keyboard machines.
 355
 356 \wxheading{Parameters}
 357
 358 \docparam{id}{Identifier for this button.}
 359
 360 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 361
 362 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 363
 364 \wxheading{See also}
 365
 366 \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
 367
 368
 369 \membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
 370
 371 \func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
 372
 373 If the platform supports it, sets the shape of the window to that
 374 depicted by {\it region}.  The system will not display or
 375 respond to any mouse event for the pixels that lie outside of the
 376 region.  To reset the window to the normal rectangular shape simply
 377 call {\it SetShape} again with an empty region.  Returns true if the
 378 operation is successful.
 379
 380
 381 \membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
 382
 383 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
 384
 385 Sets the window title.
 386
 387 \wxheading{Parameters}
 388
 389 \docparam{title}{The window title.}
 390
 391 \wxheading{See also}
 392
 393 \helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
 394
 395
 396 \membersection{wxTopLevelWindow::SetTransparent}\label{wxtoplevelwindowsettransparent}
 397
 398 \func{virtual bool}{SetTransparent}{\param{int }{ alpha}}
 399
 400 If the platform supports it will set the window to be translucent
 401
 402 \wxheading{Parameters}
 403
 404 \docparam{alpha}{Determines how opaque or transparent the window will
 405   be, if the platform supports the opreration.  A value of 0 sets the
 406   window to be fully transparent, and a value of 255 sets the window
 407   to be fully opaque.}
 408
 409 Returns \true if the transparency was successfully changed.
 410
 411
 412
 413 \membersection{wxTopLevelWindow::ShouldPreventAppExit}\label{wxtoplevelwindowshouldpreventappexit}
 414
 415 \constfunc{virtual bool}{ShouldPreventAppExit}{\void}
 416
 417 This virtual function is not meant to be called directly but can be overridden
 418 to return \false (it returns \true by default) to allow the application to
 419 close even if this, presumably not very important, window is still opened.
 420 By default, the application stays alive as long as there are any open top level
 421 windows.
 422
 423
 424 \membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
 425
 426 \func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
 427
 428 Depending on the value of {\it show} parameter the window is either shown full
 429 screen or restored to its normal state. {\it style} is a bit list containing
 430 some or all of the following values, which indicate what elements of the window
 431 to hide in full-screen mode:
 432
 433 \begin{itemize}\itemsep=0pt
 434 \item wxFULLSCREEN\_NOMENUBAR
 435 \item wxFULLSCREEN\_NOTOOLBAR
 436 \item wxFULLSCREEN\_NOSTATUSBAR
 437 \item wxFULLSCREEN\_NOBORDER
 438 \item wxFULLSCREEN\_NOCAPTION
 439 \item wxFULLSCREEN\_ALL (all of the above)
 440 \end{itemize}
 441
 442 This function has not been tested with MDI frames.
 443
 444 Note that showing a window full screen also actually
 445 \helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
 446
 447 \wxheading{See also}
 448
 449 \helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}
 450
 451
 452 \membersection{wxTopLevelWindow::UseNativeDecorations}\label{wxtoplevelwindowusenativedecorations}
 453
 454 \func{void}{UseNativeDecorations}{\param{bool }{native = \true}}
 455
 456 \bftt{This method is specific to wxUniversal port}
 457
 458 Use native or custom-drawn decorations for this window only. Notice that to
 459 have any effect this method must be called before really creating the window,
 460 i.e. two step creation must be used:
 461 \begin{verbatim}
 462     MyFrame *frame = new MyFrame;           // use default ctor
 463     frame->UseNativeDecorations(false);     // change from default "true"
 464     frame->Create(parent, title, ...);      // really create the frame
 465 \end{verbatim}
 466
 467 \wxheading{See also}
 468
 469 \helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault},\\
 470 \helpref{IsUsingNativeDecorations}{wxtoplevelwindowisusingnativedecorations}
 471
 472
 473 \membersection{wxTopLevelWindow::UseNativeDecorationsByDefault}\label{wxtoplevelwindowusenativedecorationsbydefault}
 474
 475 \func{void}{UseNativeDecorationsByDefault}{\param{bool }{native = \true}}
 476
 477 \bftt{This method is specific to wxUniversal port}
 478
 479 Top level windows in wxUniversal port can use either system-provided window
 480 decorations (i.e. title bar and various icons, buttons and menus in it) or draw
 481 the decorations themselves. By default the system decorations are used if they
 482 are available, but this method can be called with \arg{native} set to \false to
 483 change this for all windows created after this point.
 484
 485 Also note that if \texttt{WXDECOR} environment variable is set, then custom
 486 decorations are used by default and so it may make sense to call this method
 487 with default argument if the application can't use custom decorations at all
 488 for some reason.
 489
 490 \wxheading{See also}
 491
 492 \helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations}
 493