1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxTopLevelWindow documentation
4 %% Author: Vadim Zeitlin
6 %% Created: 2004-09-07 (partly extracted from frame.tex)
8 %% Copyright: (c) 2004 Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxTopLevelWindow
}}\label{wxtoplevelwindow
}
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.
19 \wxheading{Derived from
}
21 \helpref{wxWindow
}{wxwindow
}\\
22 \helpref{wxEvtHandler
}{wxevthandler
}\\
23 \helpref{wxObject
}{wxobject
}
25 \wxheading{Include files
}
30 \latexignore{\rtfignore{\wxheading{Members
}}}
33 \membersection{wxTopLevelWindow::GetIcon
}\label{wxtoplevelwindowgeticon
}
35 \constfunc{const wxIcon\&
}{GetIcon
}{\void}
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
}.
42 \helpref{GetIcons
}{wxtoplevelwindowgeticons
}
45 \membersection{wxTopLevelWindow::GetIcons
}\label{wxtoplevelwindowgeticons
}
47 \constfunc{const wxIconBundle\&
}{GetIcons
}{\void}
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.
53 Use
\helpref{GetIcon
}{wxtoplevelwindowgeticon
} to get the main icon of the
58 \helpref{wxIconBundle
}{wxiconbundle
}
61 \membersection{wxTopLevelWindow::GetTitle
}\label{wxtoplevelwindowgettitle
}
63 \constfunc{wxString
}{GetTitle
}{\void}
65 Gets a string containing the window title.
69 \helpref{wxTopLevelWindow::SetTitle
}{wxtoplevelwindowsettitle
}
72 \membersection{wxTopLevelWindow::HandleSettingChange
}\label{wxtoplevelwindowhandlesettingchange
}
74 \func{virtual bool
}{HandleSettingChange
}{\param{WXWPARAM
}{ wParam
},
\param{WXLPARAM
}{ lParam
}}
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
81 \membersection{wxTopLevelWindow::IsActive
}\label{wxtoplevelwindowisactive
}
83 \constfunc{bool
}{IsActive
}{\void}
85 Returns
\true if this window is currently active, i.e. if the user is currently
89 \membersection{wxTopLevelWindow::Iconize
}\label{wxtoplevelwindowiconize
}
91 \func{void
}{Iconize
}{\param{bool
}{ iconize
}}
93 Iconizes or restores the window.
95 \wxheading{Parameters
}
97 \docparam{iconize
}{If
\true, iconizes the window; if
\false, shows and restores it.
}
101 \helpref{wxTopLevelWindow::IsIconized
}{wxtoplevelwindowisiconized
},
\helpref{wxTopLevelWindow::Maximize
}{wxtoplevelwindowmaximize
}.
104 \membersection{wxTopLevelWindow::IsFullScreen
}\label{wxtoplevelwindowisfullscreen
}
106 \func{bool
}{IsFullScreen
}{\void}
108 Returns
\true if the window is in fullscreen mode.
112 \helpref{wxTopLevelWindow::ShowFullScreen
}{wxtoplevelwindowshowfullscreen
}
115 \membersection{wxTopLevelWindow::IsIconized
}\label{wxtoplevelwindowisiconized
}
117 \constfunc{bool
}{IsIconized
}{\void}
119 Returns
\true if the window is iconized.
122 \membersection{wxTopLevelWindow::IsMaximized
}\label{wxtoplevelwindowismaximized
}
124 \constfunc{bool
}{IsMaximized
}{\void}
126 Returns
\true if the window is maximized.
129 \membersection{wxTopLevelWindow::Maximize
}\label{wxtoplevelwindowmaximize
}
131 \func{void
}{Maximize
}{\param{bool
}{maximize
}}
133 Maximizes or restores the window.
135 \wxheading{Parameters
}
137 \docparam{maximize
}{If
\true, maximizes the window, otherwise it restores it.
}
141 This function only works under Windows.
145 \helpref{wxTopLevelWindow::Iconize
}{wxtoplevelwindowiconize
}
148 \membersection{wxTopLevelWindow::RequestUserAttention
}\label{wxtoplevelwindowrequestuserattention
}
150 \func{void
}{RequestUserAttention
}{\param{int
}{flags = wxUSER
\_ATTENTION\_INFO}}
152 Use a system-dependent way to attract users attention to the window when it is
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.
159 Note that this function should normally be only used when the application is
160 not already in foreground.
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.
166 \membersection{wxTopLevelWindow::SetIcon
}\label{wxtoplevelwindowseticon
}
168 \func{void
}{SetIcon
}{\param{const wxIcon\&
}{icon
}}
170 Sets the icon for this window.
172 \wxheading{Parameters
}
174 \docparam{icon
}{The icon to associate with this window.
}
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.
182 See also
\helpref{wxIcon
}{wxicon
}.
185 \membersection{wxTopLevelWindow::SetIcons
}\label{wxtoplevelwindowseticons
}
187 \func{void
}{SetIcons
}{\param{const wxIconBundle\&
}{icons
}}
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
}.
194 \wxheading{Parameters
}
196 \docparam{icons
}{The icons to associate with this window.
}
200 \helpref{wxIconBundle
}{wxiconbundle
}.
203 \membersection{wxTopLevelWindow::SetLeftMenu
}\label{wxtoplevelwindowsetleftmenu
}
205 \func{void
}{SetLeftMenu
}{\param{int
}{ id = wxID
\_ANY},
\param{const wxString\&
}{ label = wxEmptyString
},
\param{wxMenu *
}{ subMenu = NULL
}}
207 Sets action or menu activated by pressing left hardware button on the smart phones.
208 Unavailable on full keyboard machines.
210 \wxheading{Parameters
}
212 \docparam{id
}{Identifier for this button.
}
214 \docparam{label
}{Text to be displayed on the screen area dedicated to this hardware button.
}
216 \docparam{subMenu
}{The menu to be opened after pressing this hardware button.
}
220 \helpref{wxTopLevelWindow::SetRightMenu
}{wxtoplevelwindowsetrightmenu
}.
223 \membersection{wxTopLevelWindow::SetRightMenu
}\label{wxtoplevelwindowsetrightmenu
}
225 \func{void
}{SetRightMenu
}{\param{int
}{ id = wxID
\_ANY},
\param{const wxString\&
}{ label = wxEmptyString
},
\param{wxMenu *
}{ subMenu = NULL
}}
227 Sets action or menu activated by pressing right hardware button on the smart phones.
228 Unavailable on full keyboard machines.
230 \wxheading{Parameters
}
232 \docparam{id
}{Identifier for this button.
}
234 \docparam{label
}{Text to be displayed on the screen area dedicated to this hardware button.
}
236 \docparam{subMenu
}{The menu to be opened after pressing this hardware button.
}
240 \helpref{wxTopLevelWindow::SetLeftMenu
}{wxtoplevelwindowsetleftmenu
}.
243 \membersection{wxTopLevelWindow::SetShape
}\label{wxtoplevelwindowsetshape
}
245 \func{bool
}{SetShape
}{\param{const wxRegion\&
}{ region
}}
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.
255 \membersection{wxTopLevelWindow::SetTitle
}\label{wxtoplevelwindowsettitle
}
257 \func{virtual void
}{SetTitle
}{\param{const wxString\&
}{ title
}}
259 Sets the window title.
261 \wxheading{Parameters
}
263 \docparam{title
}{The window title.
}
267 \helpref{wxTopLevelWindow::GetTitle
}{wxtoplevelwindowgettitle
}
270 \membersection{wxTopLevelWindow::ShowFullScreen
}\label{wxtoplevelwindowshowfullscreen
}
272 \func{bool
}{ShowFullScreen
}{\param{bool
}{ show
},
\param{long
}{ style = wxFULLSCREEN
\_ALL}}
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:
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)
288 This function has not been tested with MDI frames.
290 Note that showing a window full screen also actually
291 \helpref{Show()s
}{wxwindowshow
} if it hadn't been shown yet.
295 \helpref{wxTopLevelWindow::IsFullScreen
}{wxtoplevelwindowisfullscreen
}