a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
469 lines
15 KiB
TeX
469 lines
15 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: tlw.tex
|
|
%% Purpose: wxTopLevelWindow documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 2004-09-07 (partly extracted from frame.tex)
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 2004 Vadim Zeitlin
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxTopLevelWindow}}\label{wxtoplevelwindow}
|
|
|
|
wxTopLevelWindow is a common base class for \helpref{wxDialog}{wxdialog} and
|
|
\helpref{wxFrame}{wxframe}. It is an abstract base class meaning that you never
|
|
work with objects of this class directly, but all of its methods are also
|
|
applicable for the two classes above.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxWindow}{wxwindow}\\
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/toplevel.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxCore}{librarieslist}
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxTopLevelWindow::CanSetTransparent}\label{wxtoplevelwindowcansettransparent}
|
|
|
|
\func{virtual bool}{CanSetTransparent}{\void}
|
|
|
|
Returns \true if the platform supports making the window translucent.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::SetTransparent}{wxtoplevelwindowsettransparent}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::EnableCloseButton}\label{wxtoplevelenableclosebutton}
|
|
|
|
\func{bool}{EnableCloseButton}{\param{bool}{ enable = true}}
|
|
|
|
Enables or disables the Close button (most often in the right
|
|
upper corner of a dialog) and the Close entry of the system
|
|
menu (most often in the left upper corner of the dialog).
|
|
Currently only implemented for wxMSW and wxGTK. Returns
|
|
true if operation was successful. This may be wrong on
|
|
X11 (including GTK+) where the window manager may not support
|
|
this operation and there is no way to find out.
|
|
|
|
\membersection{wxTopLevelWindow::GetDefaultItem}\label{wxtoplevelwindowgetdefaultitem}
|
|
|
|
\constfunc{wxWindow *}{GetDefaultItem}{\void}
|
|
|
|
Returns a pointer to the button which is the default for this window, or \NULL.
|
|
The default button is the one activated by pressing the Enter key.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::GetIcon}\label{wxtoplevelwindowgeticon}
|
|
|
|
\constfunc{const wxIcon\&}{GetIcon}{\void}
|
|
|
|
Returns the standard icon of the window. The icon will be invalid if it hadn't
|
|
been previously set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{GetIcons}{wxtoplevelwindowgeticons}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::GetIcons}\label{wxtoplevelwindowgeticons}
|
|
|
|
\constfunc{const wxIconBundle\&}{GetIcons}{\void}
|
|
|
|
Returns all icons associated with the window, there will be none of them if
|
|
neither \helpref{SetIcon}{wxtoplevelwindowseticon} nor
|
|
\helpref{SetIcons}{wxtoplevelwindowseticons} had been called before.
|
|
|
|
Use \helpref{GetIcon}{wxtoplevelwindowgeticon} to get the main icon of the
|
|
window.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxIconBundle}{wxiconbundle}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::GetTitle}\label{wxtoplevelwindowgettitle}
|
|
|
|
\constfunc{wxString}{GetTitle}{\void}
|
|
|
|
Gets a string containing the window title.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::SetTitle}{wxtoplevelwindowsettitle}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::HandleSettingChange}\label{wxtoplevelwindowhandlesettingchange}
|
|
|
|
\func{virtual bool}{HandleSettingChange}{\param{WXWPARAM}{ wParam}, \param{WXLPARAM}{ lParam}}
|
|
|
|
Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel) area and resize
|
|
window accordingly. Override this if you want to avoid resizing or do additional
|
|
operations.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsActive}\label{wxtoplevelwindowisactive}
|
|
|
|
\constfunc{bool}{IsActive}{\void}
|
|
|
|
Returns \true if this window is currently active, i.e. if the user is currently
|
|
working with it.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsAlwaysMaximized}\label{wxtoplevelwindowisalwaysmaximized}
|
|
|
|
\constfunc{virtual bool}{IsAlwaysMaximized}{\void}
|
|
|
|
Returns \true if this window is expected to be always maximized, either due to platform policy
|
|
or due to local policy regarding particular class.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::Iconize}\label{wxtoplevelwindowiconize}
|
|
|
|
\func{void}{Iconize}{\param{bool}{ iconize}}
|
|
|
|
Iconizes or restores the window.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{iconize}{If \true, iconizes the window; if \false, shows and restores it.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::IsIconized}{wxtoplevelwindowisiconized}, \helpref{wxTopLevelWindow::Maximize}{wxtoplevelwindowmaximize}.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsFullScreen}\label{wxtoplevelwindowisfullscreen}
|
|
|
|
\func{bool}{IsFullScreen}{\void}
|
|
|
|
Returns \true if the window is in fullscreen mode.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::ShowFullScreen}{wxtoplevelwindowshowfullscreen}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsIconized}\label{wxtoplevelwindowisiconized}
|
|
|
|
\constfunc{bool}{IsIconized}{\void}
|
|
|
|
Returns \true if the window is iconized.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsMaximized}\label{wxtoplevelwindowismaximized}
|
|
|
|
\constfunc{bool}{IsMaximized}{\void}
|
|
|
|
Returns \true if the window is maximized.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::IsUsingNativeDecorations}\label{wxtoplevelwindowisusingnativedecorations}
|
|
|
|
\constfunc{bool}{IsUsingNativeDecorations}{\void}
|
|
|
|
\bftt{This method is specific to wxUniversal port}
|
|
|
|
Returns \true if this window is using native decorations, \false if we draw
|
|
them ourselves.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations},\\
|
|
\helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::Maximize}\label{wxtoplevelwindowmaximize}
|
|
|
|
\func{void}{Maximize}{\param{bool }{maximize}}
|
|
|
|
Maximizes or restores the window.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{maximize}{If \true, maximizes the window, otherwise it restores it.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::RequestUserAttention}\label{wxtoplevelwindowrequestuserattention}
|
|
|
|
\func{void}{RequestUserAttention}{\param{int }{flags = wxUSER\_ATTENTION\_INFO}}
|
|
|
|
Use a system-dependent way to attract users attention to the window when it is
|
|
in background.
|
|
|
|
\arg{flags} may have the value of either \texttt{wxUSER\_ATTENTION\_INFO}
|
|
(default) or \texttt{wxUSER\_ATTENTION\_ERROR} which results in a more drastic
|
|
action. When in doubt, use the default value.
|
|
|
|
Note that this function should normally be only used when the application is
|
|
not already in foreground.
|
|
|
|
This function is currently implemented for Win32 where it flashes the
|
|
window icon in the taskbar, and for wxGTK with task bars supporting it.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetDefaultItem}\label{wxtoplevelwindowsetdefaultitem}
|
|
|
|
\func{void}{SetDefaultItem}{\param{wxWindow }{*win}}
|
|
|
|
Changes the default item for the panel, usually \arg{win} is a button.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{GetDefaultItem}{wxtoplevelwindowgetdefaultitem}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetIcon}\label{wxtoplevelwindowseticon}
|
|
|
|
\func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
|
|
|
|
Sets the icon for this window.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{icon}{The icon to associate with this window.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
The window takes a `copy' of {\it icon}, but since it uses reference
|
|
counting, the copy is very quick. It is safe to delete {\it icon} after
|
|
calling this function.
|
|
|
|
See also \helpref{wxIcon}{wxicon}.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetIcons}\label{wxtoplevelwindowseticons}
|
|
|
|
\func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
|
|
|
|
Sets several icons of different sizes for this window: this allows to use
|
|
different icons for different situations (e.g. task switching bar, taskbar,
|
|
window title bar) instead of scaling, with possibly bad looking results, the
|
|
only icon set by \helpref{SetIcon}{wxtoplevelwindowseticon}.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{icons}{The icons to associate with this window.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxIconBundle}{wxiconbundle}.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetLeftMenu}\label{wxtoplevelwindowsetleftmenu}
|
|
|
|
\func{void}{SetLeftMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
|
|
|
|
Sets action or menu activated by pressing left hardware button on the smart phones.
|
|
Unavailable on full keyboard machines.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{Identifier for this button.}
|
|
|
|
\docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
|
|
|
|
\docparam{subMenu}{The menu to be opened after pressing this hardware button.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetMaxSize}\label{wxtoplevelwindowsetmaxsize}
|
|
|
|
\func{void}{SetMaxSize}{\param{const wxSize\& }{size}}
|
|
|
|
A simpler interface for setting the size hints than
|
|
\helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
|
|
|
|
\membersection{wxTopLevelWindow::SetMinSize}\label{wxtoplevelwindowsetminsize}
|
|
|
|
\func{void}{SetMinSize}{\param{const wxSize\& }{size}}
|
|
|
|
A simpler interface for setting the size hints than
|
|
\helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
|
|
|
|
\membersection{wxTopLevelWindow::SetSizeHints}\label{wxtoplevelwindowsetsizehints}
|
|
|
|
\func{virtual void}{SetSizeHints}{\param{int}{ minW}, \param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1},
|
|
\param{int}{ incW=-1}, \param{int}{ incH=-1}}
|
|
|
|
\func{void}{SetSizeHints}{\param{const wxSize\&}{ minSize},
|
|
\param{const wxSize\&}{ maxSize=wxDefaultSize}, \param{const wxSize\&}{ incSize=wxDefaultSize}}
|
|
|
|
Allows specification of minimum and maximum window sizes, and window size increments.
|
|
If a pair of values is not set (or set to -1), the default values will be used.
|
|
|
|
\docparam{incW}{Specifies the increment for sizing the width (GTK/Motif/Xt only).}
|
|
|
|
\docparam{incH}{Specifies the increment for sizing the height (GTK/Motif/Xt only).}
|
|
|
|
\docparam{incSize}{Increment size (GTK/Motif/Xt only).}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
If this function is called, the user will not be able to size the window outside
|
|
the given bounds. The resizing increments are only significant under GTK, Motif or Xt.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetRightMenu}\label{wxtoplevelwindowsetrightmenu}
|
|
|
|
\func{void}{SetRightMenu}{\param{int}{ id = wxID\_ANY}, \param{const wxString\&}{ label = wxEmptyString}, \param{wxMenu *}{ subMenu = NULL}}
|
|
|
|
Sets action or menu activated by pressing right hardware button on the smart phones.
|
|
Unavailable on full keyboard machines.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{Identifier for this button.}
|
|
|
|
\docparam{label}{Text to be displayed on the screen area dedicated to this hardware button.}
|
|
|
|
\docparam{subMenu}{The menu to be opened after pressing this hardware button.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetShape}\label{wxtoplevelwindowsetshape}
|
|
|
|
\func{bool}{SetShape}{\param{const wxRegion\&}{ region}}
|
|
|
|
If the platform supports it, sets the shape of the window to that
|
|
depicted by {\it region}. The system will not display or
|
|
respond to any mouse event for the pixels that lie outside of the
|
|
region. To reset the window to the normal rectangular shape simply
|
|
call {\it SetShape} again with an empty region. Returns true if the
|
|
operation is successful.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetTitle}\label{wxtoplevelwindowsettitle}
|
|
|
|
\func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
|
|
|
|
Sets the window title.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{title}{The window title.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::GetTitle}{wxtoplevelwindowgettitle}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::SetTransparent}\label{wxtoplevelwindowsettransparent}
|
|
|
|
\func{virtual bool}{SetTransparent}{\param{int }{ alpha}}
|
|
|
|
If the platform supports it will set the window to be translucent
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{alpha}{Determines how opaque or transparent the window will
|
|
be, if the platform supports the opreration. A value of 0 sets the
|
|
window to be fully transparent, and a value of 255 sets the window
|
|
to be fully opaque.}
|
|
|
|
Returns \true if the transparency was successfully changed.
|
|
|
|
|
|
|
|
\membersection{wxTopLevelWindow::ShouldPreventAppExit}\label{wxtoplevelwindowshouldpreventappexit}
|
|
|
|
\constfunc{virtual bool}{ShouldPreventAppExit}{\void}
|
|
|
|
This virtual function is not meant to be called directly but can be overridden
|
|
to return \false (it returns \true by default) to allow the application to
|
|
close even if this, presumably not very important, window is still opened.
|
|
By default, the application stays alive as long as there are any open top level
|
|
windows.
|
|
|
|
|
|
\membersection{wxTopLevelWindow::ShowFullScreen}\label{wxtoplevelwindowshowfullscreen}
|
|
|
|
\func{bool}{ShowFullScreen}{\param{bool}{ show}, \param{long}{ style = wxFULLSCREEN\_ALL}}
|
|
|
|
Depending on the value of {\it show} parameter the window is either shown full
|
|
screen or restored to its normal state. {\it style} is a bit list containing
|
|
some or all of the following values, which indicate what elements of the window
|
|
to hide in full-screen mode:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item wxFULLSCREEN\_NOMENUBAR
|
|
\item wxFULLSCREEN\_NOTOOLBAR
|
|
\item wxFULLSCREEN\_NOSTATUSBAR
|
|
\item wxFULLSCREEN\_NOBORDER
|
|
\item wxFULLSCREEN\_NOCAPTION
|
|
\item wxFULLSCREEN\_ALL (all of the above)
|
|
\end{itemize}
|
|
|
|
This function has not been tested with MDI frames.
|
|
|
|
Note that showing a window full screen also actually
|
|
\helpref{Show()s}{wxwindowshow} if it hadn't been shown yet.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTopLevelWindow::IsFullScreen}{wxtoplevelwindowisfullscreen}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::UseNativeDecorations}\label{wxtoplevelwindowusenativedecorations}
|
|
|
|
\func{void}{UseNativeDecorations}{\param{bool }{native = \true}}
|
|
|
|
\bftt{This method is specific to wxUniversal port}
|
|
|
|
Use native or custom-drawn decorations for this window only. Notice that to
|
|
have any effect this method must be called before really creating the window,
|
|
i.e. two step creation must be used:
|
|
\begin{verbatim}
|
|
MyFrame *frame = new MyFrame; // use default ctor
|
|
frame->UseNativeDecorations(false); // change from default "true"
|
|
frame->Create(parent, title, ...); // really create the frame
|
|
\end{verbatim}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{UseNativeDecorationsByDefault}{wxtoplevelwindowusenativedecorationsbydefault},\\
|
|
\helpref{IsUsingNativeDecorations}{wxtoplevelwindowisusingnativedecorations}
|
|
|
|
|
|
\membersection{wxTopLevelWindow::UseNativeDecorationsByDefault}\label{wxtoplevelwindowusenativedecorationsbydefault}
|
|
|
|
\func{void}{UseNativeDecorationsByDefault}{\param{bool }{native = \true}}
|
|
|
|
\bftt{This method is specific to wxUniversal port}
|
|
|
|
Top level windows in wxUniversal port can use either system-provided window
|
|
decorations (i.e. title bar and various icons, buttons and menus in it) or draw
|
|
the decorations themselves. By default the system decorations are used if they
|
|
are available, but this method can be called with \arg{native} set to \false to
|
|
change this for all windows created after this point.
|
|
|
|
Also note that if \texttt{WXDECOR} environment variable is set, then custom
|
|
decorations are used by default and so it may make sense to call this method
|
|
with default argument if the application can't use custom decorations at all
|
|
for some reason.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{UseNativeDecorations}{wxtoplevelwindowusenativedecorations}
|
|
|