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::GetDefaultItem}\label{wxtoplevelwindowgetdefaultitem}
  44
  45 \constfunc{wxWindow *}{GetDefaultItem}{\void}
  46
  47 Returns a pointer to the button which is the default for this window, or \NULL.
  48 The default button is the one activated by pressing the Enter key.
  49
  50
  51 \membersection{wxTopLevelWindow::GetIcon}\label{wxtoplevelwindowgeticon}
  52
  53 \constfunc{const wxIcon\&}{GetIcon}{\void}
  54
  55 Returns the standard icon of the window. The icon will be invalid if it hadn't
  56 been previously set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
  57
  58 \wxheading{See also}
  59
  60 \helpref{GetIcons}{wxtoplevelwindowgeticons}
  61
  62
  63 \membersection{wxTopLevelWindow::GetIcons}\label{wxtoplevelwindowgeticons}
  64
  65 \constfunc{const wxIconBundle\&}{GetIcons}{\void}
  66
  67 Returns all icons associated with the window, there will be none of them if
  68 neither \helpref{SetIcon}{wxtoplevelwindowseticon} nor
  69 \helpref{SetIcons}{wxtoplevelwindowseticons} had been called before.
  70
  71 Use \helpref{GetIcon}{wxtoplevelwindowgeticon} to get the main icon of the
  72 window.
  73
  74 \wxheading{See also}
  75
  76 \helpref{wxIconBundle}{wxiconbundle}
  77
  78
  79 \membersection{wxTopLevelWindow::GetTitle}\label{wxtoplevelwindowgettitle}
  80
  81 \constfunc{wxString}{GetTitle}{\void}
  82
  83 Gets a string containing the window title.
  84
  85 \wxheading{See also}
  86
  87 \helpref{wxTopLevelWindow::SetTitle}{wxtoplevelwindowsettitle}
  88
  89
  90 \membersection{wxTopLevelWindow::HandleSettingChange}\label{wxtoplevelwindowhandlesettingchange}
  91
  92 \func{virtual bool}{HandleSettingChange}{\param{WXWPARAM}{ wParam}, \param{WXLPARAM}{ lParam}}
  93
  94 Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel) area and resize
  95 window accordingly. Override this if you want to avoid resizing or do additional
  96 operations.
  97
  98
  99 \membersection{wxTopLevelWindow::IsActive}\label{wxtoplevelwindowisactive}
 100
 101 \constfunc{bool}{IsActive}{\void}
 102
 103 Returns \true if this window is currently active, i.e. if the user is currently
 104 working with it.
 105
 106
 107 \membersection{wxTopLevelWindow::IsAlwaysMaximized}\label{wxtoplevelwindowisalwaysmaximized}
 108
 109 \constfunc{virtual bool}{IsAlwaysMaximized}{\void}
 110
 111 Returns \true if this window is expected to be always maximized, either due to platform policy
 112 or due to local policy regarding particular class.
 113
 114
 115 \membersection{wxTopLevelWindow::Iconize}\label{wxtoplevelwindowiconize}
 116
 117 \func{void}{Iconize}{\param{bool}{ iconize}}
 118
 119 Iconizes or restores the window.
 120
 121 \wxheading{Parameters}
 122
 123 \docparam{iconize}{If \true, iconizes the window; if \false, shows and restores it.}
 124
 125 \wxheading{See also}
 126
 127 \helpref{wxTopLevelWindow::IsIconized}{wxtoplevelwindowisiconized}, \helpref{wxTopLevelWindow::Maximize}{wxtoplevelwindowmaximize}.
 128
 129
 130 \membersection{wxTopLevelWindow::IsFullScreen}\label{wxtoplevelwindowisfullscreen}
 131
 132 \func{bool}{IsFullScreen}{\void}
 133
 134 Returns \true if the window is in fullscreen mode.
 135
 136 \wxheading{See also}
 137
 138 \helpref{wxTopLevelWindow::ShowFullScreen}{wxtoplevelwindowshowfullscreen}
 139
 140
 141 \membersection{wxTopLevelWindow::IsIconized}\label{wxtoplevelwindowisiconized}
 142
 143 \constfunc{bool}{IsIconized}{\void}
 144
 145 Returns \true if the window is iconized.
 146
 147
 148 \membersection{wxTopLevelWindow::IsMaximized}\label{wxtoplevelwindowismaximized}
 149
 150 \constfunc{bool}{IsMaximized}{\void}
 151
 152 Returns \true if the window is maximized.
 153
 154
 155 \membersection{wxTopLevelWindow::Maximize}\label{wxtoplevelwindowmaximize}
 156
 157 \func{void}{Maximize}{\param{bool }{maximize}}
 158
 159 Maximizes or restores the window.
 160
 161 \wxheading{Parameters}
 162
 163 \docparam{maximize}{If \true, maximizes the window, otherwise it restores it.}
 164
 165 \wxheading{See also}
 166
 167 \helpref{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
 168
 169
 170 \membersection{wxTopLevelWindow::RequestUserAttention}\label{wxtoplevelwindowrequestuserattention}
 171
 172 \func{void}{RequestUserAttention}{\param{int }{flags = wxUSER\_ATTENTION\_INFO}}
 173
 174 Use a system-dependent way to attract users attention to the window when it is
 175 in background.
 176
 177 \arg{flags} may have the value of either \texttt{wxUSER\_ATTENTION\_INFO}
 178 (default) or \texttt{wxUSER\_ATTENTION\_ERROR} which results in a more drastic
 179 action. When in doubt, use the default value.
 180
 181 Note that this function should normally be only used when the application is
 182 not already in foreground.
 183
 184 This function is currently implemented for Win32 where it flashes the
 185 window icon in the taskbar, and for wxGTK with task bars supporting it.
 186
 187
 188 \membersection{wxTopLevelWindow::SetDefaultItem}\label{wxtoplevelwindowsetdefaultitem}
 189
 190 \func{void}{SetDefaultItem}{\param{wxWindow }{*win}}
 191
 192 Changes the default item for the panel, usually \arg{win} is a button.
 193
 194 \wxheading{See also}
 195
 196 \helpref{GetDefaultItem}{wxtoplevelwindowgetdefaultitem}
 197
 198
 199 \membersection{wxTopLevelWindow::SetIcon}\label{wxtoplevelwindowseticon}
 200
 201 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
 202
 203 Sets the icon for this window.
 204
 205 \wxheading{Parameters}
 206
 207 \docparam{icon}{The icon to associate with this window.}
 208
 209 \wxheading{Remarks}
 210
 211 The window takes a `copy' of {\it icon}, but since it uses reference
 212 counting, the copy is very quick. It is safe to delete {\it icon} after
 213 calling this function.
 214
 215 See also \helpref{wxIcon}{wxicon}.
 216
 217
 218 \membersection{wxTopLevelWindow::SetIcons}\label{wxtoplevelwindowseticons}
 219
 220 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
 221
 222 Sets several icons of different sizes for this window: this allows to use
 223 different icons for different situations (e.g. task switching bar, taskbar,
 224 window title bar) instead of scaling, with possibly bad looking results, the
 225 only icon set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
 226
 227 \wxheading{Parameters}
 228
 229 \docparam{icons}{The icons to associate with this window.}
 230
 231 \wxheading{See also}
 232
 233 \helpref{wxIconBundle}{wxiconbundle}.
 234
 235
 236 \membersection{wxTopLevelWindow::SetLeftMenu}\label{wxtoplevelwindowsetleftmenu}
 237
 238 \func{void}{SetLeftMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 239
 240 Sets action or menu activated by pressing left hardware button on the smart phones.
 241 Unavailable on full keyboard machines.
 242
 243 \wxheading{Parameters}
 244
 245 \docparam{id}{Identifier for this button.}
 246
 247 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 248
 249 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 250
 251 \wxheading{See also}
 252
 253 \helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}.
 254
 255
 256 \membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
 257
 258 \func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 259
 260 Sets action or menu activated by pressing right hardware button on the smart phones.
 261 Unavailable on full keyboard machines.
 262
 263 \wxheading{Parameters}
 264
 265 \docparam{id}{Identifier for this button.}
 266
 267 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 268
 269 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 270
 271 \wxheading{See also}
 272
 273 \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
 274
 275
 276 \membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
 277
 278 \func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
 279
 280 If the platform supports it, sets the shape of the window to that
 281 depicted by {\it region}.  The system will not display or
 282 respond to any mouse event for the pixels that lie outside of the
 283 region.  To reset the window to the normal rectangular shape simply
 284 call {\it SetShape} again with an empty region.  Returns true if the
 285 operation is successful.
 286
 287
 288 \membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
 289
 290 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
 291
 292 Sets the window title.
 293
 294 \wxheading{Parameters}
 295
 296 \docparam{title}{The window title.}
 297
 298 \wxheading{See also}
 299
 300 \helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
 301
 302
 303 \membersection{wxTopLevelWindow::SetTransparent}\label{wxtoplevelwindowsettransparent}
 304
 305 \func{virtual bool}{SetTransparent}{\param{int }{ alpha}}
 306
 307 If the platform supports it will set the window to be translucent
 308
 309 \wxheading{Parameters}
 310
 311 \docparam{alpha}{Determines how opaque or transparent the window will
 312   be, if the platform supports the opreration.  A value of 0 sets the
 313   window to be fully transparent, and a value of 255 sets the window
 314   to be fully opaque.}
 315
 316 Returns \true if the transparency was successfully changed.
 317
 318
 319
 320 \membersection{wxTopLevelWindow::ShouldPreventAppExit}\label{wxtoplevelwindowshouldpreventappexit}
 321
 322 \constfunc{virtual bool}{ShouldPreventAppExit}{\void}
 323
 324 This virtual function is not meant to be called directly but can be overridden
 325 to return \false (it returns \true by default) to allow the application to
 326 close even if this, presumably not very important, window is still opened.
 327 By default, the application stays alive as long as there are any open top level
 328 windows.
 329
 330
 331 \membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
 332
 333 \func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
 334
 335 Depending on the value of {\it show} parameter the window is either shown full
 336 screen or restored to its normal state. {\it style} is a bit list containing
 337 some or all of the following values, which indicate what elements of the window
 338 to hide in full-screen mode:
 339
 340 \begin{itemize}\itemsep=0pt
 341 \item wxFULLSCREEN\_NOMENUBAR
 342 \item wxFULLSCREEN\_NOTOOLBAR
 343 \item wxFULLSCREEN\_NOSTATUSBAR
 344 \item wxFULLSCREEN\_NOBORDER
 345 \item wxFULLSCREEN\_NOCAPTION
 346 \item wxFULLSCREEN\_ALL (all of the above)
 347 \end{itemize}
 348
 349 This function has not been tested with MDI frames.
 350
 351 Note that showing a window full screen also actually
 352 \helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
 353
 354 \wxheading{See also}
 355
 356 \helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}