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