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