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