X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/834ed994704d4c8207b2e692fb05dd28ebdb4559..d67c33888f65e236adedd65ffbd978607eadc9d5:/docs/latex/wx/tlw.tex

diff --git a/docs/latex/wx/tlw.tex b/docs/latex/wx/tlw.tex
index b511d7db4b..c40594c21c 100644
--- a/docs/latex/wx/tlw.tex
+++ b/docs/latex/wx/tlw.tex
@@ -6,19 +6,91 @@
 %% Created:     2004-09-07 (partly extracted from frame.tex)
 %% RCS-ID:      $Id$
 %% Copyright:   (c) 2004 Vadim Zeitlin
-%% License:     wxWidgets license
+%% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxTopLevelWindow}}\label{wxtoplevelwindow}
 
-wxTopLevelWindow is a common base class for \helpref{wxDialog}{wxdialog} and 
-\helpref{wxTopLevelWindow}{wxtoplevelwindow}. It is an abstract base class meaning that you never
+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}
 
@@ -26,7 +98,34 @@ applicable for the two classes above.
 
 Gets a string containing the window title.
 
-See \helpref{wxTopLevelWindow::SetTitle}{wxtoplevelwindowsettitle}.
+\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}
@@ -69,6 +168,21 @@ Returns \true if the window is iconized.
 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}}
@@ -79,13 +193,38 @@ Maximizes or restores the window.
 
 \docparam{maximize}{If \true, maximizes the window, otherwise it restores it.}
 
-\wxheading{Remarks}
+\wxheading{See also}
+
+\helpref{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
+
+
+\membersection{wxTopLevelWindow::RequestUserAttention}\label{wxtoplevelwindowrequestuserattention}
+
+\func{void}{RequestUserAttention}{\param{int }{flags = wxUSER\_ATTENTION\_INFO}}
 
-This function only works under Windows.
+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{wxTopLevelWindow::Iconize}{wxtoplevelwindowiconize}
+\helpref{GetDefaultItem}{wxtoplevelwindowgetdefaultitem}
 
 
 \membersection{wxTopLevelWindow::SetIcon}\label{wxtoplevelwindowseticon}
@@ -111,13 +250,95 @@ See also \helpref{wxIcon}{wxicon}.
 
 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
 
-Sets the icons for this window.
+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.}
 
-See also \helpref{wxIconBundle}{wxiconbundle}.
+\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}
@@ -128,7 +349,7 @@ 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
+call {\it SetShape} again with an empty region.  Returns true if the
 operation is successful.
 
 
@@ -147,6 +368,34 @@ Sets the window title.
 \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}}
@@ -174,3 +423,46 @@ Note that showing a window full screen also actually
 
 \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}
+
