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