X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/aa4b42f0b79eb9fc43eec9b8a23b790ca6b00fce..8b0f8432d72fc44aa7247ab1c19c04103323feea:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index 4ae3e95a97..1b3c6f172b 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} @@ -115,6 +142,9 @@ can delete a window only when it is safe to do so, in idle time. Adds a child window. This is called automatically by window creation functions so should not be required by the application programmer. +Notice that this function is mostly internal to wxWindows and shouldn't be +called by the user code. + \wxheading{Parameters} \docparam{child}{Child window to add.} @@ -218,9 +248,9 @@ or {\tt wxBOTH}.} \helpref{wxWindow::CentreOnParent}{wxwindowcenteronparent} -\membersection{wxWindow::Clear}\label{wxwindowclear} +\membersection{wxWindow::ClearBackground}\label{wxwindowclearbackground} -\func{void}{Clear}{\void} +\func{void}{ClearBackground}{\void} Clears the window by filling it with the current background colour. Does not cause an erase background event to be generated. @@ -396,7 +426,7 @@ Destroys all children of a window. Called automatically by the destructor. \membersection{wxWindow::Disable}\label{wxwindowdisable} -\func{void}{Disable}{\void} +\func{bool}{Disable}{\void} Disables the window, same as \helpref{Enable({\tt false})}{wxwindowenable}. @@ -405,6 +435,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 +577,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} @@ -1672,6 +1736,19 @@ 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)$. @@ -1805,6 +1882,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} @@ -1825,6 +1935,9 @@ Releases mouse input captured with \helpref{wxWindow::CaptureMouse}{wxwindowcapt Removes a child window. This is called automatically by window deletion functions so should not be required by the application programmer. +Notice that this function is mostly internal to wxWindows and shouldn't be +called by the user code. + \wxheading{Parameters} \docparam{child}{Child window to remove.} @@ -2005,11 +2118,11 @@ The background colour is usually painted by the default\rtfsp under Windows and automatically under GTK. Note that setting the background colour does not cause an immediate refresh, so you -may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after +may wish to call \helpref{wxWindow::ClearBackground}{wxwindowclearbackground} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after calling this function. -Use this function with care under GTK as the new appearance of the window might -not look equally well when used with "Themes", i.e GTK's ability to change its +Use this function with care under GTK+ as the new appearance of the window might +not look equally well when used with "Themes", i.e GTK+'s ability to change its look as the user wishes with run-time loadable modules. \wxheading{See also} @@ -2017,7 +2130,7 @@ look as the user wishes with run-time loadable modules. \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp -\helpref{wxWindow::Clear}{wxwindowclear},\rtfsp +\helpref{wxWindow::ClearBackground}{wxwindowclearbackground},\rtfsp \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp \helpref{wxEraseEvent}{wxeraseevent} @@ -2728,6 +2841,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} @@ -2739,6 +2874,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}