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::SetMaxSize}\label{wxtoplevelwindowsetmaxsize}
 284
 285 \func{void}{SetMaxSize}{\param{const wxSize\& }{size}}
 286
 287 A simpler interface for setting the size hints than
 288 \helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
 289
 290 \membersection{wxTopLevelWindow::SetMinSize}\label{wxtoplevelwindowsetminsize}
 291
 292 \func{void}{SetMinSize}{\param{const wxSize\& }{size}}
 293
 294 A simpler interface for setting the size hints than
 295 \helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
 296
 297 \membersection{wxTopLevelWindow::SetSizeHints}\label{wxtoplevelwindowsetsizehints}
 298
 299 \func{virtual void}{SetSizeHints}{\param{int}{ minW}, \param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1},
 300  \param{int}{ incW=-1}, \param{int}{ incH=-1}}
 301
 302 \func{void}{SetSizeHints}{\param{const wxSize\&}{ minSize},
 303 \param{const wxSize\&}{ maxSize=wxDefaultSize}, \param{const wxSize\&}{ incSize=wxDefaultSize}}
 304
 305 Allows specification of minimum and maximum window sizes, and window size increments.
 306 If a pair of values is not set (or set to -1), the default values will be used.
 307
 308 \docparam{incW}{Specifies the increment for sizing the width (GTK/Motif/Xt only).}
 309
 310 \docparam{incH}{Specifies the increment for sizing the height (GTK/Motif/Xt only).}
 311
 312 \docparam{incSize}{Increment size (GTK/Motif/Xt only).}
 313
 314 \wxheading{Remarks}
 315
 316 If this function is called, the user will not be able to size the window outside
 317 the given bounds. The resizing increments are only significant under GTK, Motif or Xt.
 318
 319
 320 \membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
 321
 322 \func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 323
 324 Sets action or menu activated by pressing right hardware button on the smart phones.
 325 Unavailable on full keyboard machines.
 326
 327 \wxheading{Parameters}
 328
 329 \docparam{id}{Identifier for this button.}
 330
 331 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 332
 333 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 334
 335 \wxheading{See also}
 336
 337 \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
 338
 339
 340 \membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
 341
 342 \func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
 343
 344 If the platform supports it, sets the shape of the window to that
 345 depicted by {\it region}.  The system will not display or
 346 respond to any mouse event for the pixels that lie outside of the
 347 region.  To reset the window to the normal rectangular shape simply
 348 call {\it SetShape} again with an empty region.  Returns true if the
 349 operation is successful.
 350
 351
 352 \membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
 353
 354 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
 355
 356 Sets the window title.
 357
 358 \wxheading{Parameters}
 359
 360 \docparam{title}{The window title.}
 361
 362 \wxheading{See also}
 363
 364 \helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
 365
 366
 367 \membersection{wxTopLevelWindow::SetTransparent}\label{wxtoplevelwindowsettransparent}
 368
 369 \func{virtual bool}{SetTransparent}{\param{int }{ alpha}}
 370
 371 If the platform supports it will set the window to be translucent
 372
 373 \wxheading{Parameters}
 374
 375 \docparam{alpha}{Determines how opaque or transparent the window will
 376   be, if the platform supports the opreration.  A value of 0 sets the
 377   window to be fully transparent, and a value of 255 sets the window
 378   to be fully opaque.}
 379
 380 Returns \true if the transparency was successfully changed.
 381
 382
 383
 384 \membersection{wxTopLevelWindow::ShouldPreventAppExit}\label{wxtoplevelwindowshouldpreventappexit}
 385
 386 \constfunc{virtual bool}{ShouldPreventAppExit}{\void}
 387
 388 This virtual function is not meant to be called directly but can be overridden
 389 to return \false (it returns \true by default) to allow the application to
 390 close even if this, presumably not very important, window is still opened.
 391 By default, the application stays alive as long as there are any open top level
 392 windows.
 393
 394
 395 \membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
 396
 397 \func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
 398
 399 Depending on the value of {\it show} parameter the window is either shown full
 400 screen or restored to its normal state. {\it style} is a bit list containing
 401 some or all of the following values, which indicate what elements of the window
 402 to hide in full-screen mode:
 403
 404 \begin{itemize}\itemsep=0pt
 405 \item wxFULLSCREEN\_NOMENUBAR
 406 \item wxFULLSCREEN\_NOTOOLBAR
 407 \item wxFULLSCREEN\_NOSTATUSBAR
 408 \item wxFULLSCREEN\_NOBORDER
 409 \item wxFULLSCREEN\_NOCAPTION
 410 \item wxFULLSCREEN\_ALL (all of the above)
 411 \end{itemize}
 412
 413 This function has not been tested with MDI frames.
 414
 415 Note that showing a window full screen also actually
 416 \helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
 417
 418 \wxheading{See also}
 419
 420 \helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}
 421
 422
 423 \membersection{wxTopLevelWindow::UseNativeDecorations}\label{wxtoplevelwindowusenativedecorations}
 424
 425 \func{void}{UseNativeDecorations}{\param{bool }{native = \true}}
 426
 427 \bftt{This method is specific to wxUniversal port}
 428
 429 Use native or custom-drawn decorations for this window only. Notice that to
 430 have any effect this method must be called before really creating the window,
 431 i.e. two step creation must be used:
 432 \begin{verbatim}
 433     MyFrame *frame = new MyFrame;           // use default ctor
 434     frame->UseNativeDecorations(false);     // change from default "true"
 435     frame->Create(parent, title, ...);      // really create the frame
 436 \end{verbatim}
 437
 438 \wxheading{See also}
 439
 440 \helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault},\\
 441 \helpref{IsUsingNativeDecorations}{wxtoplevelwindowisusingnativedecorations}
 442
 443
 444 \membersection{wxTopLevelWindow::UseNativeDecorationsByDefault}\label{wxtoplevelwindowusenativedecorationsbydefault}
 445
 446 \func{void}{UseNativeDecorationsByDefault}{\param{bool }{native = \true}}
 447
 448 \bftt{This method is specific to wxUniversal port}
 449
 450 Top level windows in wxUniversal port can use either system-provided window
 451 decorations (i.e. title bar and various icons, buttons and menus in it) or draw
 452 the decorations themselves. By default the system decorations are used if they
 453 are available, but this method can be called with \arg{native} set to \false to
 454 change this for all windows created after this point.
 455
 456 Also note that if \texttt{WXDECOR} environment variable is set, then custom
 457 decorations are used by default and so it may make sense to call this method
 458 with default argument if the application can't use custom decorations at all
 459 for some reason.
 460
 461 \wxheading{See also}
 462
 463 \helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations}
 464