X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2dab56e91e68dfc14e6bc0a8e45a664e4a323fc8..1648d51bcb7633efde873b986b4a9e2af005f119:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index b78c4eb1dd..fa07aa81b9 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -35,8 +35,6 @@ for this style. } \twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control. Windows only. } \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint events. Windows only.} -\twocolitem{\windowstyle{wxNO\_3D}}{Prevents the children of this window taking on 3D styles, even though -the application-wide policy is for 3D controls. Windows only.} \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.} \twocolitem{\windowstyle{wxWANTS\_CHARS}}{Use this to indicate that the window wants to get all char events - even for keys like TAB or ENTER which are @@ -48,12 +46,41 @@ new window area manually if you use this style. Currently only has an effect for Windows.} \twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar.} \twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar.} +\twocolitem{\windowstyle{wxALWAYS\_SHOW\_SB}}{If a window has scrollbars, +disable them instead of hiding them when they are not needed (i.e. when the +size of the window is big enough to not require the scrollbars to navigate it). +This style is currently only implemented for wxMSW and wxUniversal and does +nothing on the other platforms.} \twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being repainted, then children being painted over them. Windows only.} \end{twocollist} See also \helpref{window styles overview}{windowstyles}. +\wxheading{Extra window styles} + +The following are extra styles, set using \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle}. + +\twocolwidtha{5cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{wxWS\_EX\_VALIDATE\_RECURSIVELY}}{By default, Validate/TransferDataTo/FromWindow() +only work on direct children of the window (compatible behaviour). Set this flag to make them recursively +descend into all subwindows.} +\twocolitem{\windowstyle{wxWS\_EX\_BLOCK\_EVENTS}}{wxCommandEvents and the objects of the derived classes are forwarded to the +parent window and so on recursively by default. Using this flag for the +given window allows to block this propagation at this window, i.e. prevent +the events from being propagated further upwards. Dialogs have this +flag on by default.} +\twocolitem{\windowstyle{wxWS\_EX\_TRANSIENT}}{Don't use this window as an implicit parent for the other windows: this must +be used with transient windows as otherwise there is the risk of creating a +dialog/frame with this window as a parent which would lead to a crash if the +parent is destroyed before the child.} +\twocolitem{\windowstyle{wxWS\_EX\_PROCESS\_IDLE}}{This window should always process idle events, even +if the mode set by \helpref{wxIdleEvent::SetMode}{wxidleeventsetmode} is wxIDLE\_PROCESS\_SPECIFIED.} +\twocolitem{\windowstyle{wxWS\_EX\_PROCESS\_UI\_UPDATES}}{This window should always process UI update events, +even if the mode set by \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} is wxUPDATE\_UI\_PROCESS\_SPECIFIED.} +\end{twocollist} + \wxheading{See also} \helpref{Event handling overview}{eventhandlingoverview} @@ -405,6 +432,31 @@ Disables the window, same as \helpref{Enable({\tt false})}{wxwindowenable}. Returns {\tt true} if the window has been disabled, {\tt false} if it had been already disabled before the call to this function. +\membersection{wxWindow::DoUpdateWindowUI}\label{wxwindowdoupdatewindowui} + +\func{virtual void}{DoUpdateWindowUI}{\param{wxUpdateUIEvent\&}{ event}} + +Does the window-specific updating after processing the update event. +This function is called by \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} +in order to check return values in the \helpref{wxUpdateUIEvent}{wxupdateuievent} and +act appropriately. For example, to allow frame and dialog title updating, wxWindows +implements this function as follows: + +\begin{verbatim} +// do the window-specific processing after processing the update event +void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) +{ + if ( event.GetSetEnabled() ) + Enable(event.GetEnabled()); + + if ( event.GetSetText() ) + { + if ( event.GetText() != GetTitle() ) + SetTitle(event.GetText()); + } +} +\end{verbatim} + \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles} \func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}} @@ -522,7 +574,16 @@ The search is recursive in both cases. \func{virtual void}{Fit}{\void} Sizes the window so that it fits around its subwindows. This function won't do -anything if there are no subwindows. +anything if there are no subwindows and will only really work correctly if the +sizers are used for the subwindows layout. Also, if the window has exactly one +subwindow it is better (faster and the result is more precise as Fit adds some +margin to account for fuzziness of its calculations) to call + +\begin{verbatim} + window->SetClientSize(child->GetSize()); +\end{verbatim} + +instead of calling Fit. \membersection{wxWindow::FitInside}\label{wxwindowfitinside} @@ -975,6 +1036,12 @@ Gets the window's title. Applicable only to frames and dialogs. \helpref{wxWindow::SetTitle}{wxwindowsettitle} +\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip} + +\constfunc{wxToolTip*}{GetToolTip}{\void} + +Get the associated tooltip or NULL if none. + \membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion} \constfunc{virtual wxRegion}{GetUpdateRegion}{\void} @@ -1052,7 +1119,7 @@ Returns {\tt true} if the window is enabled for input, {\tt false} otherwise. \helpref{wxWindow::Enable}{wxwindowenable} -\membersection{wxWindow:IsExposed}\label{wxwindowisexposed} +\membersection{wxWindow::IsExposed}\label{wxwindowisexposed} \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}} @@ -1108,6 +1175,14 @@ for this window. See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}: when auto layout is on, this function gets called automatically when the window is resized. +\membersection{wxWindow::LineDown}\label{wxwindowlinedown} + +This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(1)$. + +\membersection{wxWindow::LineUp}\label{wxwindowlineup} + +This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(-1)$. + \membersection{wxWindow::Lower}\label{wxwindowlower} \func{void}{Lower}{\void} @@ -1658,6 +1733,27 @@ implements the following methods:\par %% \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp %% \helpref{Event handling overview}{eventhandlingoverview} +\membersection{wxWindow::OnInternalIdle}\label{wxwindowoninternalidle} + +\func{virtual void}{OnInternalIdle}{\void} + +This virtual function is normally only used internally, but +sometimes an application may need it to implement functionality +that should not be disabled by an application defining an OnIdle +handler in a derived class. + +This function may be used to do delayed painting, for example, +and most implementations call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} +in order to send update events to the window in idle time. + +\membersection{wxWindow::PageDown}\label{wxwindowpagedown} + +This is just a wrapper for \helpref{ScrollPages()}{wxwindowscrollpages}$(1)$. + +\membersection{wxWindow::PageUp}\label{wxwindowpageup} + +This is just a wrapper for \helpref{ScrollPages()}{wxwindowscrollpages}$(-1)$. + \membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler} \constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = {\tt false}}} @@ -1783,6 +1879,39 @@ repainted. This is the same as \helpref{Refresh}{wxwindowrefresh} but has a nicer syntax. +\membersection{wxWindow::RegisterHotKey}\label{wxwindowregisterhotkey} + +\func{bool}{RegisterHotKey}{\param{int}{ hotkeyId}, \param{int}{ modifiers}, \param{int}{ virtualKeyCode}} + +Registers a system wide hotkey. Every time the user presses the hotkey registered here, this window +will receive a hotkey event. It will receive the event even if the application is in the background +and does not have the input focus because the user is working with some other application. + +\wxheading{Parameters} + +\docparam{hotkeyId}{Numeric identifier of the hotkey. For applications this must be between 0 and 0xBFFF. If +this function is called from a shared DLL, it must be a system wide unique identifier between 0xC000 and 0xFFFF. +This is a MSW specific detail.} + +\docparam{modifiers}{A bitwise combination of {\tt wxMOD\_SHIFT}, {\tt wxMOD\_CONTROL}, {\tt wxMOD\_ALT} +or {\tt wxMOD\_WIN} specifying the modifier keys that have to be pressed along with the key.} + +\docparam{virtualKeyCode}{The virtual key code of the hotkey.} + +\wxheading{Return value} + +{\tt true} if the hotkey was registered successfully. {\tt false} if some other application already registered a +hotkey with this modifier/virtualKeyCode combination. + +\wxheading{Remarks} + +Use EVT\_HOTKEY(hotkeyId, fnc) in the event table to capture the event. +This function is currently only implemented under MSW. + +\wxheading{See also} + +\helpref{wxWindow::UnregisterHotKey}{wxwindowunregisterhotkey} + \membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse} \func{virtual void}{ReleaseMouse}{\void} @@ -2576,13 +2705,6 @@ defined by a user's selected theme. Dialogs, notebook pages and the status bar have this flag set to true by default so that the default look and feel is simulated best. -\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator} - -\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}} - -Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to -create a new validator of this type. - \membersection{wxWindow::SetToolTip}\label{wxwindowsettooltip} \func{void}{SetToolTip}{\param{const wxString\& }{tip}} @@ -2592,15 +2714,14 @@ create a new validator of this type. Attach a tooltip to the window. See also: \helpref{GetToolTip}{wxwindowgettooltip}, - \helpref{wxToolTip}{wxtooltip} - + \helpref{wxToolTip}{wxtooltip} -\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip} - -\constfunc{wxToolTip*}{GetToolTip}{\void} +\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator} -Get the associated tooltip or NULL if none. +\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}} +Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to +create a new validator of this type. \membersection{wxWindow::SetVirtualSize}\label{wxwindowsetvirtualsize} @@ -2610,7 +2731,6 @@ Get the associated tooltip or NULL if none. Sets the virtual size of the window in pixels. - \membersection{wxWindow::SetVirtualSizeHints}\label{wxwindowsetvirtualsizehints} \func{virtual void}{SetVirtualSizeHints}{\param{int}{ minW},\param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}} @@ -2715,6 +2835,28 @@ Returns {\tt false} if a transfer failed. \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::Validate}{wxwindowvalidate} +\membersection{wxWindow::UnregisterHotKey}\label{wxwindowunregisterhotkey} + +\func{bool}{UnregisterHotKey}{\param{int}{ hotkeyId}} + +Unregisters a system wide hotkey. + +\wxheading{Parameters} + +\docparam{hotkeyId}{Numeric identifier of the hotkey. Must be the same id that was passed to RegisterHotKey.} + +\wxheading{Return value} + +{\tt true} if the hotkey was unregistered successfully, {\tt false} if the id was invalid. + +\wxheading{Remarks} + +This function is currently only implemented under MSW. + +\wxheading{See also} + +\helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey} + \membersection{wxWindow::Update}\label{wxwindowupdate} \func{virtual void}{Update}{\void} @@ -2726,6 +2868,54 @@ nothing if the window hadn't been already repainted. Use \helpref{Refresh}{wxwindowrefresh} first if you want to immediately redraw the window unconditionally. +\membersection{wxWindow::UpdateWindowUI}\label{wxwindowupdatewindowui} + +\func{virtual void}{UpdateWindowUI}{\param{long}{ flags = wxUPDATE_UI_NONE}} + +This function sends \helpref{wxUpdateUIEvents}{wxupdateuievent} to +the window. The particular implementation depends on the window; for +example a wxToolBar will send an update UI event for each toolbar button, +and a wxFrame will send an update UI event for each menubar menu item. +You can call this function from your application to ensure that your +UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers +are concerned). This may be necessary if you have called +\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} or +\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval} to +limit the overhead that wxWindows incurs by sending update UI events in idle time. + +{\it flags} should be a bitlist of one or more of the following values. + +\begin{verbatim} +enum wxUpdateUI +{ + wxUPDATE_UI_NONE = 0x0000, // No particular value + wxUPDATE_UI_RECURSE = 0x0001, // Call the function for descendants + wxUPDATE_UI_FROMIDLE = 0x0002 // Invoked from On(Internal)Idle +}; +\end{verbatim} + +If you are calling this function from an OnInternalIdle or OnIdle +function, make sure you pass the wxUPDATE\_UI\_FROMIDLE flag, since +this tells the window to only update the UI elements that need +to be updated in idle time. Some windows update their elements +only when necessary, for example when a menu is about to be shown. +The following is an example of how to call UpdateWindowUI from +an idle function. + +\begin{verbatim} +void MyWindow::OnInternalIdle() +{ + if (wxUpdateUIEvent::CanUpdate(this)) + UpdateWindowUI(wxUPDATE_UI_FROMIDLE); +} +\end{verbatim} + +\wxheading{See also} + +\helpref{wxUpdateUIEvent}{wxupdateuievent}, +\helpref{wxWindow::DoUpdateWindowUI}{wxwindowdoupdatewindowui}, +\helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle} + \membersection{wxWindow::Validate}\label{wxwindowvalidate} \func{virtual bool}{Validate}{\void}