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 accordingly 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{Remarks}
 140
 141 This function only works under Windows.
 142
 143 \wxheading{See also}
 144
 145 \helpref{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
 146
 147
 148 \membersection{wxTopLevelWindow::RequestUserAttention}\label{wxtoplevelwindowrequestuserattention}
 149
 150 \func{void}{RequestUserAttention}{\param{int }{flags = wxUSER\_ATTENTION\_INFO}}
 151
 152 Use a system-dependent way to attract users attention to the window when it is
 153 in background.
 154
 155 \arg{flags} may have the value of either \texttt{wxUSER\_ATTENTION\_INFO}
 156 (default) or \texttt{wxUSER\_ATTENTION\_ERROR} which results in a more drastic
 157 action. When in doubt, use the default value.
 158
 159 Note that this function should normally be only used when the application is
 160 not already in foreground.
 161
 162 This function is currently implemented for Win32 where it flashes the
 163 window icon in the taskbar, and for wxGTK with task bars supporting it.
 164
 165
 166 \membersection{wxTopLevelWindow::SetIcon}\label{wxtoplevelwindowseticon}
 167
 168 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
 169
 170 Sets the icon for this window.
 171
 172 \wxheading{Parameters}
 173
 174 \docparam{icon}{The icon to associate with this window.}
 175
 176 \wxheading{Remarks}
 177
 178 The window takes a `copy' of {\it icon}, but since it uses reference
 179 counting, the copy is very quick. It is safe to delete {\it icon} after
 180 calling this function.
 181
 182 See also \helpref{wxIcon}{wxicon}.
 183
 184
 185 \membersection{wxTopLevelWindow::SetIcons}\label{wxtoplevelwindowseticons}
 186
 187 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
 188
 189 Sets several icons of different sizes for this window: this allows to use
 190 different icons for different situations (e.g. task switching bar, taskbar,
 191 window title bar) instead of scaling, with possibly bad looking results, the
 192 only icon set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
 193
 194 \wxheading{Parameters}
 195
 196 \docparam{icons}{The icons to associate with this window.}
 197
 198 \wxheading{See also}
 199
 200 \helpref{wxIconBundle}{wxiconbundle}.
 201
 202
 203 \membersection{wxTopLevelWindow::SetLeftMenu}\label{wxtoplevelwindowsetleftmenu}
 204
 205 \func{void}{SetLeftMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 206
 207 Sets action or menu activated by pressing left hardware button on the smart phones.
 208 Unavailable on full keyboard machines.
 209
 210 \wxheading{Parameters}
 211
 212 \docparam{id}{Identifier for this button.}
 213
 214 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 215
 216 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 217
 218 \wxheading{See also}
 219
 220 \helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}.
 221
 222
 223 \membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
 224
 225 \func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
 226
 227 Sets action or menu activated by pressing right hardware button on the smart phones.
 228 Unavailable on full keyboard machines.
 229
 230 \wxheading{Parameters}
 231
 232 \docparam{id}{Identifier for this button.}
 233
 234 \docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
 235
 236 \docparam{subMenu}{The menu to be opened after pressing this hardware button.}
 237
 238 \wxheading{See also}
 239
 240 \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
 241
 242
 243 \membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
 244
 245 \func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
 246
 247 If the platform supports it, sets the shape of the window to that
 248 depicted by {\it region}.  The system will not display or
 249 respond to any mouse event for the pixels that lie outside of the
 250 region.  To reset the window to the normal rectangular shape simply
 251 call {\it SetShape} again with an empty region.  Returns true if the
 252 operation is successful.
 253
 254
 255 \membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
 256
 257 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
 258
 259 Sets the window title.
 260
 261 \wxheading{Parameters}
 262
 263 \docparam{title}{The window title.}
 264
 265 \wxheading{See also}
 266
 267 \helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
 268
 269
 270 \membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
 271
 272 \func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
 273
 274 Depending on the value of {\it show} parameter the window is either shown full
 275 screen or restored to its normal state. {\it style} is a bit list containing
 276 some or all of the following values, which indicate what elements of the window
 277 to hide in full-screen mode:
 278
 279 \begin{itemize}\itemsep=0pt
 280 \item wxFULLSCREEN\_NOMENUBAR
 281 \item wxFULLSCREEN\_NOTOOLBAR
 282 \item wxFULLSCREEN\_NOSTATUSBAR
 283 \item wxFULLSCREEN\_NOBORDER
 284 \item wxFULLSCREEN\_NOCAPTION
 285 \item wxFULLSCREEN\_ALL (all of the above)
 286 \end{itemize}
 287
 288 This function has not been tested with MDI frames.
 289
 290 Note that showing a window full screen also actually
 291 \helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
 292
 293 \wxheading{See also}
 294
 295 \helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}