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