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