X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4f24cbbd3dbbf3eb45225b36044c41e76b1e5eef..e64cadcb8b6bed94e76e855dcb9a59bcbef28d26:/interface/wx/window.h diff --git a/interface/wx/window.h b/interface/wx/window.h index cbb1e4e8d0..d2fe5d73a4 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -7,32 +7,6 @@ ///////////////////////////////////////////////////////////////////////////// -/** - Background styles. See wxWindow::SetBackgroundStyle(). -*/ -enum wxBackgroundStyle -{ - /// Use the default background, as determined by - /// the system or the current theme. - wxBG_STYLE_SYSTEM, - - /// Use a solid colour for the background, this style is set automatically if you call - /// SetBackgroundColour() so you only need to set it explicitly if you had - /// changed the background style to something else before. - wxBG_STYLE_COLOUR, - - /// Don't draw the background at all, it's supposed that it is drawn by - /// the user-defined erase background event handler. - /// This style should be used to avoid flicker when the background is entirely - /// custom-drawn. - wxBG_STYLE_CUSTOM, - - /// The background is (partially) transparent,this style is automatically set if you call - /// SetTransparent() which is used to set the transparency level. - wxBG_STYLE_TRANSPARENT -}; - - /** Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect(). */ @@ -83,17 +57,6 @@ enum wxWindowVariant }; -/** - Flags which can be used in wxWindow::UpdateWindowUI(). -*/ -enum wxUpdateUI -{ - wxUPDATE_UI_NONE, - wxUPDATE_UI_RECURSE, - wxUPDATE_UI_FROMIDLE /**< Invoked from On(Internal)Idle */ -}; - - /** @class wxWindow @@ -207,8 +170,9 @@ enum wxUpdateUI Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an application window. - This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so - these two styles are automatically turned of if this one is used. + This style cannot be used (because of the underlying native behaviour) + together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles + are automatically turned off if this one is used. @style{wxWS_EX_PROCESS_IDLE} This window should always process idle events, even if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. @@ -271,6 +235,14 @@ public: */ virtual ~wxWindow(); + + /** + @name Focus functions + + See also the static function FindFocus(). + */ + //@{ + /** This method may be overridden in the derived classes to return @false to indicate that this control doesn't accept input at all (i.e. behaves like @@ -295,6 +267,51 @@ public: */ virtual bool AcceptsFocusRecursively() const; + /** + Returns @true if the window (or in case of composite controls, its main + child window) has focus. + + @see FindFocus() + */ + virtual bool HasFocus() const; + + /** + This method is only implemented by ports which have support for + native TAB traversal (such as GTK+ 2.0). + + It is called by wxWidgets' container control code to give the native + system a hint when doing TAB traversal. A call to this does not disable + or change the effect of programmatically calling SetFocus(). + + @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + */ + virtual void SetCanFocus(bool canFocus); + + /** + This sets the window to receive keyboard input. + + @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, + wxPanel::SetFocusIgnoringChildren + */ + virtual void SetFocus(); + + /** + This function is called by wxWidgets keyboard navigation code when the user + gives the focus to this window from keyboard (e.g. using @c TAB key). + + By default this method simply calls SetFocus() but + can be overridden to do something in addition to this in the derived classes. + */ + virtual void SetFocusFromKbd(); + + //@} + + + /** + @name Child management functions + */ + //@{ + /** Adds a child window. This is called automatically by window creation functions so should not be required by the application programmer. @@ -307,894 +324,1097 @@ public: virtual void AddChild(wxWindow* child); /** - Call this function to force one or both scrollbars to be always shown, even if - the window is big enough to show its entire contents without scrolling. - - @since 2.9.0 - - @param hflag - Whether the horizontal scroll bar should always be visible. - @param vflag - Whether the vertical scroll bar should always be visible. + Destroys all children of a window. Called automatically by the destructor. + */ + bool DestroyChildren(); - @remarks This function is currently only implemented under Mac/Carbon. + /** + Find a child of this window, by @a id. + May return @a this if it matches itself. */ - virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); + wxWindow* FindWindow(long id) const; /** - Sets the cached best size value. + Find a child of this window, by name. + May return @a this if it matches itself. */ - void CacheBestSize(const wxSize& size) const; + wxWindow* FindWindow(const wxString& name) const; /** - Returns @true if the system supports transparent windows and calling - SetTransparent() may succeed. If this function returns @false, transparent - windows are definitely not supported by the current system. + Returns a reference to the list of the window's children. @c wxWindowList + is a type-safe wxList-like class whose elements are of type @c wxWindow*. */ - virtual bool CanSetTransparent(); + wxWindowList& GetChildren(); /** - Directs all mouse input to this window. - Call ReleaseMouse() to release the capture. + @overload + */ + const wxWindowList& GetChildren() const; - Note that wxWidgets maintains the stack of windows having captured the mouse - and when the mouse is released the capture returns to the window which had had - captured it previously and it is only really released if there were no previous - window. In particular, this means that you must release the mouse as many times - as you capture it, unless the window receives the wxMouseCaptureLostEvent event. + /** + Removes a child window. - Any application which captures the mouse in the beginning of some operation - must handle wxMouseCaptureLostEvent and cancel this operation when it receives - the event. The event handler must not recapture mouse. + 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 wxWidgets and shouldn't be + called by the user code. - @see ReleaseMouse(), wxMouseCaptureLostEvent + @param child + Child window to remove. */ - void CaptureMouse(); + virtual void RemoveChild(wxWindow* child); + + //@} + /** - A synonym for Centre(). + @name Sibling and parent management functions */ - void Center(int dir = wxBOTH); + //@{ /** - A synonym for CentreOnParent(). + Returns the grandparent of a window, or @NULL if there isn't one. */ - void CenterOnParent(int dir = wxBOTH); + wxWindow* GetGrandParent() const; /** - Centres the window. + Returns the next window after this one among the parent children or @NULL + if this window is the last child. - @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag - if you want to center the window on the entire screen and not on its - parent window. + @since 2.8.8 - @remarks If the window is a top level one (i.e. doesn't have a parent), - it will be centered relative to the screen anyhow. + @see GetPrevSibling() + */ + wxWindow* GetNextSibling() const; - @see Center() + /** + Returns the parent of the window, or @NULL if there is no parent. */ - void Centre(int direction = wxBOTH); + wxWindow* GetParent() const; /** - Centres the window on its parent. This is a more readable synonym for Centre(). + Returns the previous window before this one among the parent children or @c + @NULL if this window is the first child. - @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. + @since 2.8.8 - @remarks This methods provides for a way to center top level windows over - their parents instead of the entire screen. If there - is no parent or if the window is not a top level - window, then behaviour is the same as Centre(). + @see GetNextSibling() + */ + wxWindow* GetPrevSibling() const; + /** + Reparents the window, i.e the window will be removed from its + current parent window (e.g. a non-standard toolbar in a wxFrame) + and then re-inserted into another. - @see wxTopLevelWindow::CentreOnScreen + @param newParent + New parent. */ - void CentreOnParent(int direction = wxBOTH); + virtual bool Reparent(wxWindow* newParent); + + //@} + /** - Clears the window by filling it with the current background colour. Does not - cause an erase background event to be generated. + @name Scrolling and scrollbars functions + + Note that these methods don't work with native controls which don't use + wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow). */ - virtual void ClearBackground(); + //@{ /** - Converts to screen coordinates from coordinates relative to this window. + Call this function to force one or both scrollbars to be always shown, even if + the window is big enough to show its entire contents without scrolling. - @param x - A pointer to a integer value for the x coordinate. Pass the client - coordinate in, and a screen coordinate will be passed out. - @param y - A pointer to a integer value for the y coordinate. Pass the client - coordinate in, and a screen coordinate will be passed out. + @since 2.9.0 - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the following methods: - - ClientToScreen(point): Accepts and returns a wxPoint - - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y) - @endWxPythonOnly + @param hflag + Whether the horizontal scroll bar should always be visible. + @param vflag + Whether the vertical scroll bar should always be visible. + + @remarks This function is currently only implemented under Mac/Carbon. */ - void ClientToScreen(int* x, int* y) const; + virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); /** - Converts to screen coordinates from coordinates relative to this window. + Returns the built-in scrollbar position. - @param pt - The client position for the second form of the function. + @see SetScrollbar() */ - wxPoint ClientToScreen(const wxPoint& pt) const; + virtual int GetScrollPos(int orientation) const; /** - Converts client area size @a size to corresponding window size. + Returns the built-in scrollbar range. - In other words, the returned value is what would GetSize() return if this - window had client area of given size. Components with wxDefaultCoord - value are left unchanged. Note that the conversion is not always - exact, it assumes that non-client area doesn't change and so doesn't - take into account things like menu bar (un)wrapping or (dis)appearance - of the scrollbars. + @see SetScrollbar() + */ + virtual int GetScrollRange(int orientation) const; - @since 2.8.8 + /** + Returns the built-in scrollbar thumb size. - @see WindowToClientSize() + @see SetScrollbar() */ - virtual wxSize ClientToWindowSize(const wxSize& size) const; + virtual int GetScrollThumb(int orientation) const; /** - Converts window size @a size to corresponding client area size - In other words, the returned value is what would GetClientSize() return if - this window had given window size. Components with wxDefaultCoord value - are left unchanged. + Returns @true if this window has a scroll bar for this orientation. - Note that the conversion is not always exact, it assumes that - non-client area doesn't change and so doesn't take into account things - like menu bar (un)wrapping or (dis)appearance of the scrollbars. + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + */ + bool HasScrollbar(int orient) const; - @since 2.8.8 + /** + Return whether a scrollbar is always shown. - @see ClientToWindowSize() + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + + @see AlwaysShowScrollbars() */ - virtual wxSize WindowToClientSize(const wxSize& size) const; + virtual bool IsScrollbarAlwaysShown(int orient) const; /** - This function simply generates a wxCloseEvent whose handler usually tries - to close the window. It doesn't close the window itself, however. + Scrolls the window by the given number of lines down (if @a lines is + positive) or up. - @param force - @false if the window's close handler should be able to veto the destruction - of this window, @true if it cannot. + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. - @remarks Close calls the close handler for the window, providing an - opportunity for the window to choose whether to destroy - the window. Usually it is only used with the top level - windows (wxFrame and wxDialog classes) as the others - are not supposed to have any special OnClose() logic. - The close handler should check whether the window is being deleted - forcibly, using wxCloseEvent::CanVeto, in which case it should - destroy the window using wxWindow::Destroy. - Note that calling Close does not guarantee that the window will - be destroyed; but it provides a way to simulate a manual close - of a window, which may or may not be implemented by destroying - the window. The default implementation of wxDialog::OnCloseWindow - does not necessarily delete the dialog, since it will simply - simulate an wxID_CANCEL event which is handled by the appropriate - button event handler and may do anything at all. - To guarantee that the window will be destroyed, call - wxWindow::Destroy instead + @remarks This function is currently only implemented under MSW and + wxTextCtrl under wxGTK (it also works for wxScrolled classes + under all platforms). - @see @ref overview_windowdeletion "Window Deletion Overview", - Destroy(), wxCloseEvent + @see ScrollPages() */ - bool Close(bool force = false); + virtual bool ScrollLines(int lines); - //@{ /** - Converts a point or size from dialog units to pixels. + Scrolls the window by the given number of pages down (if @a pages is + positive) or up. - For the x dimension, the dialog units are multiplied by the average character - width and then divided by 4. - For the y dimension, the dialog units are multiplied by the average character - height and then divided by 8. + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. - @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. - You can also use these functions programmatically. - A convenience macro is defined: - @code - #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt) - @endcode + @remarks This function is currently only implemented under MSW and wxGTK. - @see ConvertPixelsToDialog() + @see ScrollLines() */ - wxPoint ConvertDialogToPixels(const wxPoint& pt); - wxSize ConvertDialogToPixels(const wxSize& sz); - //@} + virtual bool ScrollPages(int pages); - //@{ /** - Converts a point or size from pixels to dialog units. + Physically scrolls the pixels in the window and move child windows accordingly. - For the x dimension, the pixels are multiplied by 4 and then divided by the - average character width. - For the y dimension, the pixels are multiplied by 8 and then divided by the - average character height. + @param dx + Amount to scroll horizontally. + @param dy + Amount to scroll vertically. + @param rect + Rectangle to scroll, if it is @NULL, the whole window is + scrolled (this is always the case under wxGTK which doesn't support this + parameter) - @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. + @remarks Note that you can often use wxScrolled instead of using this + function directly. + */ + virtual void ScrollWindow(int dx, int dy, + const wxRect* rect = NULL); - @see ConvertDialogToPixels() + /** + Same as #ScrollLines (-1). */ - wxPoint ConvertPixelsToDialog(const wxPoint& pt); - wxSize ConvertPixelsToDialog(const wxSize& sz); + bool LineUp(); + + /** + Same as #ScrollLines (1). + */ + bool LineDown(); + + /** + Same as #ScrollPages (-1). + */ + bool PageUp(); + + /** + Same as #ScrollPages (1). + */ + bool PageDown(); + + /** + Sets the position of one of the built-in scrollbars. + + @param orientation + Determines the scrollbar whose position is to be set. + May be wxHORIZONTAL or wxVERTICAL. + @param pos + Position in scroll units. + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks This function does not directly affect the contents of the + window: it is up to the application to take note of + scrollbar attributes and redraw contents accordingly. + + @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, + wxScrolled + */ + virtual void SetScrollPos(int orientation, int pos, + bool refresh = true); + + /** + Sets the scrollbar properties of a built-in scrollbar. + + @param orientation + Determines the scrollbar whose page size is to be set. + May be wxHORIZONTAL or wxVERTICAL. + @param position + The position of the scrollbar in scroll units. + @param thumbSize + The size of the thumb, or visible portion of the scrollbar, in scroll units. + @param range + The maximum position of the scrollbar. Value of -1 can be used to + ask for the scrollbar to be shown but in the disabled state: this + can be used to avoid removing the scrollbar even when it is not + needed (currently this is only implemented in wxMSW port). + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks + Let's say you wish to display 50 lines of text, using the same font. + The window is sized so that you can only see 16 lines at a time. + You would use: + @code + SetScrollbar(wxVERTICAL, 0, 16, 50); + @endcode + Note that with the window at this size, the thumb position can never + go above 50 minus 16, or 34. You can determine how many lines are + currently visible by dividing the current view size by the character + height in pixels. + When defining your own scrollbar behaviour, you will always need + to recalculate the scrollbar settings when the window size changes. + You could therefore put your scrollbar calculations and SetScrollbar + call into a function named AdjustScrollbars, which can be called + initially and also from your wxSizeEvent handler function. + + @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent + */ + virtual void SetScrollbar(int orientation, int position, + int thumbSize, int range, + bool refresh = true); //@} + /** - Destroys the window safely. Use this function instead of the delete operator, - since different window classes can be destroyed differently. Frames and dialogs - are not destroyed immediately when this function is called -- they are added - to a list of windows to be deleted on idle time, when all the window's events - have been processed. This prevents problems with events being sent to - non-existent windows. + @name Sizing functions - @return @true if the window has either been successfully deleted, or it - has been added to the list of windows pending real deletion. + See also the protected functions DoGetBestSize() and SetInitialBestSize(). */ - virtual bool Destroy(); + //@{ /** - Destroys all children of a window. Called automatically by the destructor. + Sets the cached best size value. + + @see GetBestSize() */ - bool DestroyChildren(); + void CacheBestSize(const wxSize& size) const; /** - Returns true if this window is in process of being destroyed. + Converts client area size @a size to corresponding window size. - The top level windows are not deleted immediately but are rather - scheduled for later destruction to give them time to process any - pending messages, see Destroy() description. + In other words, the returned value is what would GetSize() return if this + window had client area of given size. Components with wxDefaultCoord + value are left unchanged. Note that the conversion is not always + exact, it assumes that non-client area doesn't change and so doesn't + take into account things like menu bar (un)wrapping or (dis)appearance + of the scrollbars. - This function returns @true if this window, or one of its parent - windows, is scheduled for destruction and can be useful to avoid - manipulating it as it's usually useless to do something with a window - which is on the point of disappearing anyhow. - */ - bool IsBeingDeleted() const; + @since 2.8.8 + + @see WindowToClientSize() + */ + virtual wxSize ClientToWindowSize(const wxSize& size) const; /** - Disables the window. Same as @ref Enable() Enable(@false). + Converts window size @a size to corresponding client area size + In other words, the returned value is what would GetClientSize() return if + this window had given window size. Components with wxDefaultCoord value + are left unchanged. - @return Returns @true if the window has been disabled, @false if it had - been already disabled before the call to this function. + Note that the conversion is not always exact, it assumes that + non-client area doesn't change and so doesn't take into account things + like menu bar (un)wrapping or (dis)appearance of the scrollbars. + + @since 2.8.8 + + @see ClientToWindowSize() */ - bool Disable(); + virtual wxSize WindowToClientSize(const wxSize& size) const; /** - Does the window-specific updating after processing the update event. - This function is called by UpdateWindowUI() in order to check return - values in the wxUpdateUIEvent and act appropriately. - For example, to allow frame and dialog title updating, wxWidgets - implements this function as follows: + Sizes the window so that it fits around its subwindows. - @code - // do the window-specific processing after processing the update event - void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) - { - if ( event.GetSetEnabled() ) - Enable(event.GetEnabled()); + This function won't do anything if there are no subwindows and will only really + work correctly if sizers are used for the subwindows layout. - if ( event.GetSetText() ) - { - if ( event.GetText() != GetTitle() ) - SetTitle(event.GetText()); - } - } + 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: + + @code + window->SetClientSize(child->GetSize()); @endcode + + instead of calling Fit(). + + @see @ref overview_windowsizing */ - virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); + virtual void Fit(); /** - Enables or disables eligibility for drop file events (OnDropFiles). + Similar to Fit(), but sizes the interior (virtual) size of a window. - @param accept - If @true, the window is eligible for drop file events. - If @false, the window will not accept drop file events. + Mainly useful with scrolled windows to reset scrollbars after sizing + changes that do not trigger a size event, and/or scrolled windows without + an interior sizer. This function similarly won't do anything if there are + no subwindows. + */ + virtual void FitInside(); - @remarks Windows only until version 2.8.9, available on all platforms - since 2.8.10. Cannot be used together with SetDropTarget() on - non-Windows platforms. + /** + This functions returns the best acceptable minimal size for the window. - @see SetDropTarget() + For example, for a static control, it will be the minimal size such that the + control label is not truncated. For windows containing subwindows (typically + wxPanel), the size returned by this function will be the same as the size + the window would have had after calling Fit(). + + Note that when you write your own widget you need to overload the + DoGetBestSize() function instead of this (non-virtual!) function. + + @see CacheBestSize(), @ref overview_windowsizing */ - virtual void DragAcceptFiles(bool accept); + wxSize GetBestSize() const; /** - Enable or disable the window for user input. Note that when a parent window is - disabled, all of its children are disabled as well and they are reenabled again - when the parent is. + Returns the size of the window 'client area' in pixels. - @param enable - If @true, enables the window for input. If @false, disables the window. + The client area is the area which may be drawn on by the programmer, + excluding title bar, border, scrollbars, etc. + Note that if this window is a top-level one and it is currently minimized, the + return size is empty (both width and height are 0). - @return Returns @true if the window has been enabled or disabled, @false - if nothing was done, i.e. if the window had already - been in the specified state. + @see GetSize(), GetVirtualSize() + */ + void GetClientSize(int* width, int* height) const; - @see IsEnabled(), Disable(), wxRadioBox::Enable + /** + @overload */ - virtual bool Enable(bool enable = true); + wxSize GetClientSize() const; /** - Finds the window or control which currently has the keyboard focus. + Merges the window's best size into the min size and returns the result. + This is the value used by sizers to determine the appropriate + ammount of space to allocate for the widget. - @remarks Note that this is a static function, so it can be called without - needing a wxWindow pointer. + This is the method called by any wxSizer when they query the size + of a certain window or control. - @see SetFocus(), HasFocus() + @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing + */ + virtual wxSize GetEffectiveMinSize() const; + + /** + Returns the maximum size of window's client area. + + This is an indication to the sizer layout mechanism that this is the maximum + possible size as well as the upper bound on window's size settable using + SetClientSize(). + + @see GetMaxSize(), @ref overview_windowsizing + */ + virtual wxSize GetMaxClientSize() const; + + /** + Returns the maximum size of the window. + + This is an indication to the sizer layout mechanism that this is the maximum + possible size as well as the upper bound on window's size settable using SetSize(). + + @see GetMaxClientSize(), @ref overview_windowsizing + */ + virtual wxSize GetMaxSize() const; + + /** + Returns the minimum size of window's client area, an indication to the sizer + layout mechanism that this is the minimum required size of its client area. + + It normally just returns the value set by SetMinClientSize(), but it can be + overridden to do the calculation on demand. + + @see GetMinSize(), @ref overview_windowsizing + */ + virtual wxSize GetMinClientSize() const; + + /** + Returns the minimum size of the window, an indication to the sizer layout + mechanism that this is the minimum required size. + + This method normally just returns the value set by SetMinSize(), but it + can be overridden to do the calculation on demand. + + @see GetMinClientSize(), @ref overview_windowsizing + */ + virtual wxSize GetMinSize() const; + + /** + Returns the size of the entire window in pixels, including title bar, border, + scrollbars, etc. + + Note that if this window is a top-level one and it is currently minimized, the + returned size is the restored window size, not the size of the window icon. + + @param width + Receives the window width. + @param height + Receives the window height. + + @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing + */ + void GetSize(int* width, int* height) const; + + /** + See the GetSize(int*,int*) overload for more info. + */ + wxSize GetSize() const; + + /** + This gets the virtual size of the window in pixels. + By default it returns the client size of the window, but after a call to + SetVirtualSize() it will return the size set with that method. + + @see @ref overview_windowsizing + */ + wxSize GetVirtualSize() const; + + /** + Like the other GetVirtualSize() overload but uses pointers instead. + + @param width + Receives the window virtual width. + @param height + Receives the window virtual height. */ - static wxWindow* FindFocus(); + void GetVirtualSize(int* width, int* height) const; /** - Find a child of this window, by @a id. - May return @a this if it matches itself. + Returns the size of the left/right and top/bottom borders of this window in x + and y components of the result respectively. */ - wxWindow* FindWindow(long id) const; + virtual wxSize GetWindowBorderSize() const; /** - Find a child of this window, by name. - May return @a this if it matches itself. + Resets the cached best size value so it will be recalculated the next time it + is needed. + + @see CacheBestSize() */ - wxWindow* FindWindow(const wxString& name) const; + void InvalidateBestSize(); /** - Find the first window with the given @e id. - - If @a parent is @NULL, the search will start from all top-level frames - and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. + Posts a size event to the window. - @see FindWindow() - */ - static wxWindow* FindWindowById(long id, wxWindow* parent = NULL); + This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument. + */ + void PostSizeEvent(); /** - Find a window by its label. - - Depending on the type of window, the label may be a window title - or panel item label. If @a parent is @NULL, the search will start from all - top-level frames and dialog boxes; if non-@NULL, the search will be - limited to the given window hierarchy. - The search is recursive in both cases. + Posts a size event to the parent of this window. - @see FindWindow() - */ - static wxWindow* FindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); + This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST + argument. + */ + void PostSizeEventToParent(); /** - Find a window by its name (as given in a window constructor or @b Create - function call). + This function sends a dummy @ref wxSizeEvent "size event" to + the window allowing it to re-layout its children positions. - If @a parent is @NULL, the search will start from all top-level frames - and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. + It is sometimes useful to call this function after adding or deleting a + children after the frame creation or if a child size changes. Note that + if the frame is using either sizers or constraints for the children + layout, it is enough to call wxWindow::Layout() directly and this + function should not be used in this case. - The search is recursive in both cases. If no window with such name is found, - FindWindowByLabel() is called. + If @a flags includes @c wxSEND_EVENT_POST value, this function posts + the event, i.e. schedules it for later processing, instead of + dispatching it directly. You can also use PostSizeEvent() as a more + readable equivalent of calling this function with this flag. - @see FindWindow() + @param flags + May include @c wxSEND_EVENT_POST. Default value is 0. */ - static wxWindow* FindWindowByName(const wxString& name, - wxWindow* parent = NULL); + virtual void SendSizeEvent(int flags = 0); /** - Sizes the window so that it fits around its subwindows. + Safe wrapper for GetParent()->SendSizeEvent(). - This function won't do anything if there are no subwindows and will only really - work correctly if sizers are used for the subwindows layout. + This function simply checks that the window has a valid parent which is + not in process of being deleted and calls SendSizeEvent() on it. It is + used internally by windows such as toolbars changes to whose state + should result in parent re-layout (e.g. when a toolbar is added to the + top of the window, all the other windows must be shifted down). - 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: + @see PostSizeEventToParent() - @code - window->SetClientSize(child->GetSize()); - @endcode + @param flags + See description of this parameter in SendSizeEvent() documentation. + */ + void SendSizeEventToParent(int flags = 0); - instead of calling Fit(). + /** + This sets the size of the window client area in pixels. + + Using this function to size a window tends to be more device-independent + than SetSize(), since the application need not worry about what dimensions + the border or title bar have when trying to fit the window around panel + items, for example. @see @ref overview_windowsizing */ - virtual void Fit(); + virtual void SetClientSize(int width, int height); /** - Similar to Fit(), but sizes the interior (virtual) size of a window. - - Mainly useful with scrolled windows to reset scrollbars after sizing - changes that do not trigger a size event, and/or scrolled windows without - an interior sizer. This function similarly won't do anything if there are - no subwindows. + @overload */ - virtual void FitInside(); + virtual void SetClientSize(const wxSize& size); /** - Freezes the window or, in other words, prevents any updates from taking - place on screen, the window is not redrawn at all. - - Thaw() must be called to reenable window redrawing. Calls to these two - functions may be nested but to ensure that the window is properly - repainted again, you must thaw it exactly as many times as you froze it. + This normally does not need to be called by user code. + It is called when a window is added to a sizer, and is used so the window + can remove itself from the sizer when it is destroyed. + */ + void SetContainingSizer(wxSizer* sizer); - If the window has any children, they are recursively frozen too. + /** + A @e smart SetSize that will fill in default size components with the + window's @e best size values. - This method is useful for visual appearance optimization (for example, - it is a good idea to use it before doing many large text insertions in - a row into a wxTextCtrl under wxGTK) but is not implemented on all - platforms nor for all controls so it is mostly just a hint to wxWidgets - and not a mandatory directive. + Also sets the window's minsize to the value passed in for use with sizers. + This means that if a full or partial size is passed to this function then + the sizers will use that size instead of the results of GetBestSize() to + determine the minimum needs of the window for layout. - @see wxWindowUpdateLocker, Thaw(), IsFrozen() - */ - void Freeze(); + Most controls will use this to set their initial size, and their min + size to the passed in value (if any.) - /** - Gets the accelerator table for this window. See wxAcceleratorTable. + @see SetSize(), GetBestSize(), GetEffectiveMinSize(), + @ref overview_windowsizing */ - wxAcceleratorTable* GetAcceleratorTable(); + void SetInitialSize(const wxSize& size = wxDefaultSize); /** - Returns the accessible object for this window, if any. - See also wxAccessible. - */ - wxAccessible* GetAccessible(); + Sets the maximum client size of the window, to indicate to the sizer + layout mechanism that this is the maximum possible size of its client area. - /** - Returns the background colour of the window. + Note that this method is just a shortcut for: + @code + SetMaxSize(ClientToWindowSize(size)); + @endcode - @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour() + @see SetMaxSize(), @ref overview_windowsizing */ - wxColour GetBackgroundColour() const; + virtual void SetMaxClientSize(const wxSize& size); /** - Returns the background style of the window. - The background style can be one of the wxBackgroundStyle. + Sets the maximum size of the window, to indicate to the sizer layout mechanism + that this is the maximum possible size. - @see SetBackgroundColour(), GetForegroundColour(), - SetBackgroundStyle(), SetTransparent() + @see SetMaxClientSize(), @ref overview_windowsizing */ - virtual wxBackgroundStyle GetBackgroundStyle() const; + virtual void SetMaxSize(const wxSize& size); /** - This functions returns the best acceptable minimal size for the window. + Sets the minimum client size of the window, to indicate to the sizer + layout mechanism that this is the minimum required size of window's client + area. - For example, for a static control, it will be the minimal size such that the - control label is not truncated. For windows containing subwindows (typically - wxPanel), the size returned by this function will be the same as the size - the window would have had after calling Fit(). - */ - wxSize GetBestSize() const; + You may need to call this if you change the window size after + construction and before adding to its parent sizer. - /** - Returns the currently captured window. + Note, that just as with SetMinSize(), calling this method doesn't + prevent the program from explicitly making the window smaller than the + specified size. - @see HasCapture(), CaptureMouse(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent - */ - static wxWindow* GetCapture(); + Note that this method is just a shortcut for: + @code + SetMinSize(ClientToWindowSize(size)); + @endcode - /** - Returns the caret() associated with the window. + @see SetMinSize(), @ref overview_windowsizing */ - wxCaret* GetCaret() const; + virtual void SetMinClientSize(const wxSize& size); /** - Returns the character height for this window. - */ - virtual int GetCharHeight() const; + Sets the minimum size of the window, to indicate to the sizer layout + mechanism that this is the minimum required size. - /** - Returns the average character width for this window. - */ - virtual int GetCharWidth() const; + You may need to call this if you change the window size after + construction and before adding to its parent sizer. - //@{ - /** - Returns a reference to the list of the window's children. @c wxWindowList - is a type-safe wxList-like class whose elements are of type @c wxWindow*. + Notice that calling this method doesn't prevent the program from making + the window explicitly smaller than the specified size by calling + SetSize(), it just ensures that it won't become smaller than this size + during the automatic layout. + + @see SetMinClientSize(), @ref overview_windowsizing */ - wxWindowList& GetChildren(); - const wxWindowList& GetChildren() const; - //@} + virtual void SetMinSize(const wxSize& size); /** - Returns the default font and colours which are used by the control. - - This is useful if you want to use the same font or colour in your own control - as in a standard control -- which is a much better idea than hard coding specific - colours or fonts which might look completely out of place on the users - system, especially if it uses themes. - - The @a variant parameter is only relevant under Mac currently and is - ignore under other platforms. Under Mac, it will change the size of the - returned font. See SetWindowVariant() for more about this. + Sets the size of the window in pixels. - This static method is "overridden" in many derived classes and so calling, - for example, wxButton::GetClassDefaultAttributes() will typically - return the values appropriate for a button which will be normally different - from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). + @param x + Required x position in pixels, or wxDefaultCoord to indicate that the + existing value should be used. + @param y + Required y position in pixels, or wxDefaultCoord to indicate that the + existing value should be used. + @param width + Required width in pixels, or wxDefaultCoord to indicate that the existing + value should be used. + @param height + Required height position in pixels, or wxDefaultCoord to indicate that the + existing value should be used. + @param sizeFlags + Indicates the interpretation of other parameters. + It is a bit list of the following: + - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate + a wxWidgets-supplied default width. + - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate + a wxWidgets-supplied default height. + - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate + a wxWidgets-supplied default size. + - @c wxSIZE_USE_EXISTING: existing dimensions should be used + if wxDefaultCoord values are supplied. + - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of + wxDefaultCoord) to be interpreted as real + dimensions, not default values. + - @c wxSIZE_FORCE: normally, if the position and the size of the window are + already the same as the parameters of this function, + nothing is done. but with this flag a window resize may + be forced even in this case (supported in wx 2.6.2 and + later and only implemented for MSW and ignored elsewhere + currently). - The @c wxVisualAttributes structure has at least the fields - @c font, @c colFg and @c colBg. All of them may be invalid - if it was not possible to determine the default control appearance or, - especially for the background colour, if the field doesn't make sense as is - the case for @c colBg for the controls with themed background. + @remarks This overload sets the position and optionally size, of the window. + Parameters may be wxDefaultCoord to indicate either that a default + should be supplied by wxWidgets, or that the current value of the + dimension should be used. - @see InheritAttributes() + @see Move(), @ref overview_windowsizing */ - static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); + void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); - //@{ /** - Returns the size of the window 'client area' in pixels. + Sets the size of the window in pixels. + The size is specified using a wxRect, wxSize or by a couple of @c int objects. - The client area is the area which may be drawn on by the programmer, - excluding title bar, border, scrollbars, etc. - Note that if this window is a top-level one and it is currently minimized, the - return size is empty (both width and height are 0). + @remarks This form must be used with non-default width and height values. - @see GetSize(), GetVirtualSize() + @see Move(), @ref overview_windowsizing */ - void GetClientSize(int* width, int* height) const; - wxSize GetClientSize() const; - //@} + virtual void SetSize(const wxRect& rect); /** - Returns a pointer to the window's layout constraints, or @NULL if there are none. + @overload */ - wxLayoutConstraints* GetConstraints() const; + virtual void SetSize(const wxSize& size); /** - Return the sizer that this window is a member of, if any, otherwise @NULL. + @overload */ - wxSizer* GetContainingSizer() const; + virtual void SetSize(int width, int height); /** - Return the cursor associated with this window. + Use of this function for windows which are not toplevel windows + (such as wxDialog or wxFrame) is discouraged. + Please use SetMinSize() and SetMaxSize() instead. - @see SetCursor() + @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing */ - const wxCursor& GetCursor() const; + void SetSizeHints( const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize, + const wxSize& incSize=wxDefaultSize); /** - Currently this is the same as calling - wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). - - One advantage of using this function compared to the static version is that - the call is automatically dispatched to the correct class (as usual with - virtual functions) and you don't have to specify the class name explicitly. + Sets the virtual size of the window in pixels. - The other one is that in the future this function could return different - results, for example it might return a different font for an "Ok" button - than for a generic button if the users GUI is configured to show such buttons - in bold font. Of course, the down side is that it is impossible to call this - function without actually having an object to apply it to whereas the static - version can be used without having to create an object first. + @see @ref overview_windowsizing */ - virtual wxVisualAttributes GetDefaultAttributes() const; + void SetVirtualSize(int width, int height); /** - Returns the associated drop target, which may be @NULL. - - @see SetDropTarget(), @ref overview_dnd + @overload */ - virtual wxDropTarget* GetDropTarget() const; + void SetVirtualSize(const wxSize& size); - /** - Merges the window's best size into the min size and returns the result. - This is the value used by sizers to determine the appropriate - ammount of space to allocate for the widget. + //@} - @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing - */ - wxSize GetEffectiveMinSize() const; /** - Returns the event handler for this window. - By default, the window is its own event handler. + @name Positioning functions + */ + //@{ - @see SetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + /** + A synonym for Centre(). */ - wxEvtHandler* GetEventHandler() const; + void Center(int dir = wxBOTH); /** - Returns the extra style bits for the window. + A synonym for CentreOnParent(). */ - long GetExtraStyle() const; + void CenterOnParent(int dir = wxBOTH); /** - Returns the font for this window. + Centres the window. - @see SetFont() + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag + if you want to center the window on the entire screen and not on its + parent window. + + @remarks If the window is a top level one (i.e. doesn't have a parent), + it will be centered relative to the screen anyhow. + + @see Center() */ - wxFont GetFont() const; + void Centre(int direction = wxBOTH); /** - Returns the foreground colour of the window. + Centres the window on its parent. This is a more readable synonym for Centre(). - @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may be - the text colour or other colour, or it may not be used at all. + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. - @see SetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour() - */ - wxColour GetForegroundColour() const; + @remarks This methods provides for a way to center top level windows over + their parents instead of the entire screen. If there + is no parent or if the window is not a top level + window, then behaviour is the same as Centre(). + @see wxTopLevelWindow::CentreOnScreen + */ + void CentreOnParent(int direction = wxBOTH); /** - Returns the grandparent of a window, or @NULL if there isn't one. + This gets the position of the window in pixels, relative to the parent window + for the child windows or relative to the display origin for the top level windows. + + @param x + Receives the x position of the window if non-@NULL. + @param y + Receives the y position of the window if non-@NULL. + + @see GetScreenPosition() */ - wxWindow* GetGrandParent() const; + void GetPosition(int* x, int* y) const; /** - Returns the platform-specific handle of the physical window. - Cast it to an appropriate handle, such as @b HWND for Windows, - @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS. + This gets the position of the window in pixels, relative to the parent window + for the child windows or relative to the display origin for the top level windows. + + @see GetScreenPosition() */ - virtual WXWidget GetHandle() const; + wxPoint GetPosition() const; /** - Gets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider - implementation, and not in the window object itself. + Returns the position and size of the window as a wxRect object. - @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + @see GetScreenRect() */ - wxString GetHelpText() const; + wxRect GetRect() const; /** - Gets the help text to be used as context-sensitive help for this window. - This method should be overridden if the help message depends on the position - inside the window, otherwise GetHelpText() can be used. + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - @param point - Coordinates of the mouse at the moment of help event emission. - @param origin - Help event origin, see also wxHelpEvent::GetOrigin. + @param x + Receives the x position of the window on the screen if non-@NULL. + @param y + Receives the y position of the window on the screen if non-@NULL. + + @see GetPosition() */ - virtual wxString GetHelpTextAtPoint(const wxPoint& point, - wxHelpEvent::Origin origin) const; + void GetScreenPosition(int* x, int* y) const; /** - Returns the identifier of the window. - - @remarks Each window has an integer identifier. If the application - has not provided one (or the default wxID_ANY) an unique - identifier with a negative value will be generated. + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - @see SetId(), @ref overview_windowids + @see GetPosition() */ - wxWindowID GetId() const; + wxPoint GetScreenPosition() const; /** - Generic way of getting a label from any window, for - identification purposes. + Returns the position and size of the window on the screen as a wxRect object. - @remarks The interpretation of this function differs from class to class. - For frames and dialogs, the value returned is the - title. For buttons or static text controls, it is the - button text. This function can be useful for - meta-programs (such as testing tools or special-needs - access programs) which need to identify windows by name. + @see GetRect() */ - virtual wxString GetLabel() const; + wxRect GetScreenRect() const; /** - Returns the maximum size of window's client area. + Moves the window to the given position. - This is an indication to the sizer layout mechanism that this is the maximum - possible size as well as the upper bound on window's size settable using - SetClientSize(). + @param x + Required x position. + @param y + Required y position. + @param flags + See SetSize() for more info about this parameter. + + @remarks Implementations of SetSize can also implicitly implement the + Move() function, which is defined in the base wxWindow class as the call: + @code + SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING); + @endcode - @see GetMaxSize() + @see SetSize() */ - virtual wxSize GetMaxClientSize() const; + void Move(int x, int y, int flags = wxSIZE_USE_EXISTING); /** - Returns the maximum size of the window. + Moves the window to the given position. - This is an indication to the sizer layout mechanism that this is the maximum - possible size as well as the upper bound on window's size settable using SetSize(). + @param pt + wxPoint object representing the position. + @param flags + See SetSize() for more info about this parameter. + + @remarks Implementations of SetSize() can also implicitly implement the + Move() function, which is defined in the base wxWindow class as the call: + @code + SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING); + @endcode - @see GetMaxClientSize() + @see SetSize() */ - virtual wxSize GetMaxSize() const; + void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); - /** - Returns the minimum size of window's client area, an indication to the sizer - layout mechanism that this is the minimum required size of its client area. + //@} - It normally just returns the value set by SetMinClientSize(), but it can be - overridden to do the calculation on demand. - @see GetMinSize() + /** + @name Coordinate conversion functions */ - virtual wxSize GetMinClientSize() const; + //@{ /** - Returns the minimum size of the window, an indication to the sizer layout - mechanism that this is the minimum required size. + Converts to screen coordinates from coordinates relative to this window. - This method normally just returns the value set by SetMinSize(), but it - can be overridden to do the calculation on demand. + @param x + A pointer to a integer value for the x coordinate. Pass the client + coordinate in, and a screen coordinate will be passed out. + @param y + A pointer to a integer value for the y coordinate. Pass the client + coordinate in, and a screen coordinate will be passed out. - @see GetMinClientSize() + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the following methods: + - ClientToScreen(point): Accepts and returns a wxPoint + - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y) + @endWxPythonOnly */ - virtual wxSize GetMinSize() const; + void ClientToScreen(int* x, int* y) const; /** - Returns the window's name. - - @remarks This name is not guaranteed to be unique; it is up to the - programmer to supply an appropriate name in the window - constructor or via SetName(). + Converts to screen coordinates from coordinates relative to this window. - @see SetName() + @param pt + The client position for the second form of the function. */ - virtual wxString GetName() const; + wxPoint ClientToScreen(const wxPoint& pt) const; /** - Returns the next window after this one among the parent children or @NULL - if this window is the last child. + Converts a point or size from dialog units to pixels. - @since 2.8.8 + For the x dimension, the dialog units are multiplied by the average character + width and then divided by 4. + For the y dimension, the dialog units are multiplied by the average character + height and then divided by 8. - @see GetPrevSibling() + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. + You can also use these functions programmatically. + A convenience macro is defined: + @code + #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt) + @endcode + + @see ConvertPixelsToDialog() */ - wxWindow* GetNextSibling() const; + wxPoint ConvertDialogToPixels(const wxPoint& pt); /** - Returns the parent of the window, or @NULL if there is no parent. + @overload */ - wxWindow* GetParent() const; + wxSize ConvertDialogToPixels(const wxSize& sz); /** - This function shows a popup menu at the given position in this window and - returns the selected id. It can be more convenient than the general purpose - PopupMenu() function for simple menus proposing a choice in a list of - strings to the user. + Converts a point or size from pixels to dialog units. - @param menu - The menu to show - @param pos - The position at which to show the menu in client coordinates + For the x dimension, the pixels are multiplied by 4 and then divided by the + average character width. + For the y dimension, the pixels are multiplied by 8 and then divided by the + average character height. + + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. - @return The selected menu item id or wxID_NONE if none selected or an - error occurred. + @see ConvertDialogToPixels() */ - int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); + wxPoint ConvertPixelsToDialog(const wxPoint& pt); /** - See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload. - This overload differs only because it takes two integers for the - menu position instead of a wxPoint. + @overload */ - int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); + wxSize ConvertPixelsToDialog(const wxSize& sz); /** - This gets the position of the window in pixels, relative to the parent window - for the child windows or relative to the display origin for the top level windows. + Converts from screen to client window coordinates. @param x - Receives the x position of the window if non-@NULL. + Stores the screen x coordinate and receives the client x coordinate. @param y - Receives the y position of the window if non-@NULL. - - @see GetScreenPosition() + Stores the screen x coordinate and receives the client x coordinate. */ - void GetPosition(int* x, int* y) const; + void ScreenToClient(int* x, int* y) const; /** - This gets the position of the window in pixels, relative to the parent window - for the child windows or relative to the display origin for the top level windows. + Converts from screen to client window coordinates. - @see GetScreenPosition() + @param pt + The screen position. */ - wxPoint GetPosition() const; + wxPoint ScreenToClient(const wxPoint& pt) const; - /** - Returns the previous window before this one among the parent children or @c - @NULL if this window is the first child. + //@} - @since 2.8.8 - @see GetNextSibling() + /** + @name Drawing-related functions */ - wxWindow* GetPrevSibling() const; + //@{ /** - Returns the position and size of the window as a wxRect object. - - @see GetScreenRect() + Clears the window by filling it with the current background colour. Does not + cause an erase background event to be generated. */ - wxRect GetRect() const; + virtual void ClearBackground(); /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. + Freezes the window or, in other words, prevents any updates from taking + place on screen, the window is not redrawn at all. - @param x - Receives the x position of the window on the screen if non-@NULL. - @param y - Receives the y position of the window on the screen if non-@NULL. + Thaw() must be called to reenable window redrawing. Calls to these two + functions may be nested but to ensure that the window is properly + repainted again, you must thaw it exactly as many times as you froze it. - @see GetPosition() - */ - void GetScreenPosition(int* x, int* y) const; + If the window has any children, they are recursively frozen too. - /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. + This method is useful for visual appearance optimization (for example, + it is a good idea to use it before doing many large text insertions in + a row into a wxTextCtrl under wxGTK) but is not implemented on all + platforms nor for all controls so it is mostly just a hint to wxWidgets + and not a mandatory directive. - @see GetPosition() + @see wxWindowUpdateLocker, Thaw(), IsFrozen() */ - wxPoint GetScreenPosition() const; + void Freeze(); /** - Returns the position and size of the window on the screen as a wxRect object. + Reenables window updating after a previous call to Freeze(). - @see GetRect() + To really thaw the control, it must be called exactly the same number + of times as Freeze(). + + If the window has any children, they are recursively thawn too. + + @see wxWindowUpdateLocker, Freeze(), IsFrozen() */ - wxRect GetScreenRect() const; + void Thaw(); /** - Returns the built-in scrollbar position. + Returns @true if the window is currently frozen by a call to Freeze(). - @see See SetScrollbar() + @see Freeze(), Thaw() */ - virtual int GetScrollPos(int orientation) const; + bool IsFrozen() const; /** - Returns the built-in scrollbar range. + Returns the background colour of the window. - @see SetScrollbar() + @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour() */ - virtual int GetScrollRange(int orientation) const; + wxColour GetBackgroundColour() const; /** - Returns the built-in scrollbar thumb size. + Returns the background style of the window. + The background style can be one of the wxBackgroundStyle. - @see SetScrollbar() + @see SetBackgroundColour(), GetForegroundColour(), + SetBackgroundStyle(), SetTransparent() */ - virtual int GetScrollThumb(int orientation) const; + virtual wxBackgroundStyle GetBackgroundStyle() const; + /** + Returns the character height for this window. + */ + virtual int GetCharHeight() const; /** - Returns the size of the entire window in pixels, including title bar, border, - scrollbars, etc. + Returns the average character width for this window. + */ + virtual int GetCharWidth() const; - Note that if this window is a top-level one and it is currently minimized, the - returned size is the restored window size, not the size of the window icon. + /** + Currently this is the same as calling + wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). - @param width - Receives the window width. - @param height - Receives the window height. + One advantage of using this function compared to the static version is that + the call is automatically dispatched to the correct class (as usual with + virtual functions) and you don't have to specify the class name explicitly. - @see GetClientSize(), GetVirtualSize() + The other one is that in the future this function could return different + results, for example it might return a different font for an "Ok" button + than for a generic button if the users GUI is configured to show such buttons + in bold font. Of course, the down side is that it is impossible to call this + function without actually having an object to apply it to whereas the static + version can be used without having to create an object first. */ - void GetSize(int* width, int* height) const; + virtual wxVisualAttributes GetDefaultAttributes() const; /** - See the GetSize(int*,int*) overload for more info. + Returns the font for this window. + + @see SetFont() */ - wxSize GetSize() const; + wxFont GetFont() const; /** - Return the sizer associated with the window by a previous call to - SetSizer() or @NULL. + Returns the foreground colour of the window. + + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used at all. + + @see SetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour() */ - wxSizer* GetSizer() const; + wxColour GetForegroundColour() const; /** Gets the dimensions of the string as it would be drawn on the @@ -1224,12 +1444,7 @@ public: Gets the dimensions of the string as it would be drawn on the window with the currently selected font. */ - wxSize GetTextExtent(const wxString& string) const; - - /** - Get the associated tooltip or @NULL if none. - */ - wxToolTip* GetToolTip() const; + wxSize GetTextExtent(const wxString& string) const; /** Returns the region specifying which parts of the window have been damaged. @@ -1237,333 +1452,436 @@ public: @see wxRegion, wxRegionIterator */ - const wxRegion& GetUpdateRegion() const; + const wxRegion& GetUpdateRegion() const; + + /** + Returns @true if this window background is transparent (as, for example, + for wxStaticText) and should show the parent window background. + + This method is mostly used internally by the library itself and you normally + shouldn't have to call it. You may, however, have to override it in your + wxWindow-derived class to ensure that background is painted correctly. + */ + virtual bool HasTransparentBackground(); + + /** + Causes this window, and all of its children recursively (except under wxGTK1 + where this is not implemented), to be repainted. Note that repainting doesn't + happen immediately but only during the next event loop iteration, if you need + to update the window immediately you should use Update() instead. + + @param eraseBackground + If @true, the background will be erased. + @param rect + If non-@NULL, only the given rectangle will be treated as damaged. + + @see RefreshRect() + */ + virtual void Refresh(bool eraseBackground = true, + const wxRect* rect = NULL); + + /** + Redraws the contents of the given rectangle: only the area inside it will be + repainted. + + This is the same as Refresh() but has a nicer syntax as it can be called + with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)). + */ + void RefreshRect(const wxRect& rect, bool eraseBackground = true); + + /** + Calling this method immediately repaints the invalidated area of the window and + all of its children recursively while this would usually only happen when the + flow of control returns to the event loop. + + Notice that this function doesn't invalidate any area of the window so + nothing happens if nothing has been invalidated (i.e. marked as requiring + a redraw). Use Refresh() first if you want to immediately redraw the + window unconditionally. + */ + virtual void Update(); + + /** + Sets the background colour of the window. + Please see InheritAttributes() for explanation of the difference between + this method and SetOwnBackgroundColour(). + + @param colour + The colour to be used as the background colour, pass + wxNullColour to reset to the default colour. + + @remarks The background colour is usually painted by the default + wxEraseEvent event handler function under Windows and + automatically under GTK. + Note that setting the background colour does not cause an + immediate refresh, so you may wish to call wxWindow::ClearBackground + or wxWindow::Refresh after calling this function. + Using this function will disable attempts to use themes for + this window, if the system supports them. Use with care since + usually the themes represent the appearance chosen by the user + to be used for all applications on the system. + + @see GetBackgroundColour(), SetForegroundColour(), + GetForegroundColour(), ClearBackground(), + Refresh(), wxEraseEvent + */ + virtual bool SetBackgroundColour(const wxColour& colour); /** - Returns a pointer to the current validator for the window, or @NULL if - there is none. - */ - virtual wxValidator* GetValidator(); + Sets the background style of the window. see GetBackgroundStyle() for + the description of the possible style values. - //@{ - /** - This gets the virtual size of the window in pixels. - By default it returns the client size of the window, but after a call to - SetVirtualSize() it will return the size set with that method. + @see SetBackgroundColour(), GetForegroundColour(), + SetTransparent() */ - wxSize GetVirtualSize() const; + virtual bool SetBackgroundStyle(wxBackgroundStyle style); /** - Like the other GetVirtualSize() overload but uses pointers instead. + Sets the font for this window. This function should not be called for the + parent window if you don't want its font to be inherited by its children, + use SetOwnFont() instead in this case and see InheritAttributes() for more + explanations. - @param width - Receives the window virtual width. - @param height - Receives the window virtual height. - */ - void GetVirtualSize(int* width, int* height) const; - //@} + Please notice that the given font is not automatically used for + wxPaintDC objects associated with this window, you need to + call wxDC::SetFont too. However this font is used by + any standard controls for drawing their text as well as by + GetTextExtent(). - /** - Returns the size of the left/right and top/bottom borders of this window in x - and y components of the result respectively. - */ - virtual wxSize GetWindowBorderSize() const; + @param font + Font to associate with this window, pass + wxNullFont to reset to the default font. - /** - Gets the window style that was passed to the constructor or @b Create - method. @b GetWindowStyle() is another name for the same function. - */ - virtual long GetWindowStyleFlag() const; + @return @true if the want was really changed, @false if it was already set + to this font and so nothing was done. - /** - Returns the value previously passed to SetWindowVariant(). + @see GetFont(), InheritAttributes() */ - wxWindowVariant GetWindowVariant() const; + virtual bool SetFont(const wxFont& font); /** - This function will generate the appropriate call to - Navigate() if the key event is one normally used for - keyboard navigation and return @true in this case. + Sets the foreground colour of the window. + Please see InheritAttributes() for explanation of the difference between + this method and SetOwnForegroundColour(). - @return Returns @true if the key pressed was for navigation and was - handled, @false otherwise. + @param colour + The colour to be used as the foreground colour, pass + wxNullColour to reset to the default colour. - @see Navigate() + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used at all. + + @see GetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour(), ShouldInheritColours() */ - bool HandleAsNavigationKey(const wxKeyEvent& event); + virtual bool SetForegroundColour(const wxColour& colour); /** - Shorthand for: - @code - GetEventHandler()->SafelyProcessEvent(event); - @endcode + Sets the background colour of the window but prevents it from being inherited + by the children of this window. + + @see SetBackgroundColour(), InheritAttributes() */ - bool HandleWindowEvent(wxEvent& event) const; + void SetOwnBackgroundColour(const wxColour& colour); /** - Returns @true if this window has the current mouse capture. + Sets the font of the window but prevents it from being inherited by the + children of this window. - @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent + @see SetFont(), InheritAttributes() */ - virtual bool HasCapture() const; + void SetOwnFont(const wxFont& font); /** - Returns @true if the window has the given @a exFlag bit set in its - extra styles. + Sets the foreground colour of the window but prevents it from being inherited + by the children of this window. - @see SetExtraStyle() + @see SetForegroundColour(), InheritAttributes() */ - bool HasExtraStyle(int exFlag) const; + void SetOwnForegroundColour(const wxColour& colour); /** - Returns @true if the window has the given @a flag bit set. + @deprecated use wxDC::SetPalette instead. */ - bool HasFlag(int flag) const; + void SetPalette(const wxPalette& pal); /** - Returns @true if the window (or in case of composite controls, its main - child window) has focus. + Return @true from here to allow the colours of this window to be changed by + InheritAttributes(), returning @false forbids inheriting them from the parent window. - @see FindFocus() + The base class version returns @false, but this method is overridden in + wxControl where it returns @true. */ - virtual bool HasFocus() const; + virtual bool ShouldInheritColours() const; /** - This method should be overridden to return @true if this window has - multiple pages. All standard class with multiple pages such as - wxNotebook, wxListbook and wxTreebook already override it to return @true - and user-defined classes with similar behaviour should do it as well to - allow the library to handle such windows appropriately. + This function tells a window if it should use the system's "theme" code + to draw the windows' background instead if its own background drawing + code. This does not always have any effect since the underlying platform + obviously needs to support the notion of themes in user defined windows. + One such platform is GTK+ where windows can have (very colourful) backgrounds + 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. */ - virtual bool HasMultiplePages() const; + virtual void SetThemeEnabled(bool enable); /** - Returns @true if this window has a scroll bar for this orientation. - - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. + Returns @true if the system supports transparent windows and calling + SetTransparent() may succeed. If this function returns @false, transparent + windows are definitely not supported by the current system. */ - bool HasScrollbar(int orient) const; + virtual bool CanSetTransparent(); /** - Returns @true if this window background is transparent (as, for example, - for wxStaticText) and should show the parent window background. + Set the transparency of the window. If the system supports transparent windows, + returns @true, otherwise returns @false and the window remains fully opaque. + See also CanSetTransparent(). - This method is mostly used internally by the library itself and you normally - shouldn't have to call it. You may, however, have to override it in your - wxWindow-derived class to ensure that background is painted correctly. + The parameter @a alpha is in the range 0..255 where 0 corresponds to a + fully transparent window and 255 to the fully opaque one. The constants + @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used. */ - virtual bool HasTransparentBackground(); + virtual bool SetTransparent(wxByte alpha); + + //@} + /** - Equivalent to calling wxWindow::Show(@false). + @name Event-handling functions + + wxWindow allows you to build a (sort of) stack of event handlers which + can be used to override the window's own event handling. */ - bool Hide(); + //@{ /** - This function hides a window, like Hide(), but using a special visual - effect if possible. - - The parameters of this function are the same as for ShowWithEffect(), - please see their description there. + Returns the event handler for this window. + By default, the window is its own event handler. - @since 2.9.0 + @see SetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ - virtual bool HideWithEffect(wxShowEffect effect, - unsigned int timeout = 0); + wxEvtHandler* GetEventHandler() const; /** - This function is (or should be, in case of custom controls) called during - window creation to intelligently set up the window visual attributes, that is - the font and the foreground and background colours. + This function will generate the appropriate call to Navigate() if the key + event is one normally used for keyboard navigation and return @true in this case. - By "intelligently" the following is meant: by default, all windows use their - own @ref GetClassDefaultAttributes() default attributes. - However if some of the parents attributes are explicitly (that is, using - SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding - attribute hadn't been explicitly set for this window itself, then this - window takes the same value as used by the parent. - In addition, if the window overrides ShouldInheritColours() to return @false, - the colours will not be changed no matter what and only the font might. + @return Returns @true if the key pressed was for navigation and was + handled, @false otherwise. - This rather complicated logic is necessary in order to accommodate the - different usage scenarios. The most common one is when all default attributes - are used and in this case, nothing should be inherited as in modern GUIs - different controls use different fonts (and colours) than their siblings so - they can't inherit the same value from the parent. However it was also deemed - desirable to allow to simply change the attributes of all children at once by - just changing the font or colour of their common parent, hence in this case we - do inherit the parents attributes. + @see Navigate() */ - virtual void InheritAttributes(); + bool HandleAsNavigationKey(const wxKeyEvent& event); /** - Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data - to the dialog via validators. - */ - virtual void InitDialog(); + Shorthand for: + @code + GetEventHandler()->SafelyProcessEvent(event); + @endcode - /** - Resets the cached best size value so it will be recalculated the next time it - is needed. + @see ProcessWindowEvent() */ - void InvalidateBestSize(); + bool HandleWindowEvent(wxEvent& event) const; /** - Returns @true if the window contents is double-buffered by the system, i.e. if - any drawing done on the window is really done on a temporary backing surface - and transferred to the screen all at once later. + Convenient wrapper for ProcessEvent(). - @see wxBufferedDC + This is the same as writing @code GetEventHandler()->ProcessEvent(event); + @endcode but more convenient. Notice that ProcessEvent() itself can't + be called for wxWindow objects as it ignores the event handlers + associated with the window, use this function instead. */ - virtual bool IsDoubleBuffered() const; + bool ProcessWindowEvent(wxEvent& event); /** - Returns @true if the window is enabled, i.e. if it accepts user input, - @false otherwise. + Removes and returns the top-most event handler on the event handler stack. - Notice that this method can return @false even if this window itself hadn't - been explicitly disabled when one of its parent windows is disabled. - To get the intrinsic status of this window, use IsThisEnabled() + E.g. in the case of: + @image html overview_eventhandling_winstack.png + when calling @c W->PopEventHandler(), the event handler @c A will be + removed and @c B will be the first handler of the stack. - @see Enable() - */ - bool IsEnabled() const; + Note that it's an error to call this function when no event handlers + were pushed on this window (i.e. when the window itself is its only + event handler). - //@{ - /** - Returns @true if the given point or rectangle area has been exposed since the - last repaint. Call this in an paint event handler to optimize redrawing by - only redrawing those areas, which have been exposed. + @param deleteHandler + If this is @true, the handler will be deleted after it is removed + (and the returned value will be @NULL). + + @see @ref overview_eventhandling_processing */ - bool IsExposed(int x, int y) const; - bool IsExposed(wxPoint& pt) const; - bool IsExposed(int x, int y, int w, int h) const; - bool IsExposed(wxRect& rect) const; - //@} + wxEvtHandler* PopEventHandler(bool deleteHandler = false); /** - Returns @true if the window is currently frozen by a call to Freeze(). + Pushes this event handler onto the event stack for the window. - @see Freeze(), Thaw() + An event handler is an object that is capable of processing the events sent + to a window. By default, the window is its own event handler, but an application + may wish to substitute another, for example to allow central implementation + of event-handling for a variety of different window classes. + + wxWindow::PushEventHandler allows an application to set up a @e stack + of event handlers, where an event not handled by one event handler is + handed to the next one in the chain. + + E.g. if you have two event handlers @c A and @c B and a wxWindow instance + @c W and you call: + @code + W->PushEventHandler(A); + W->PushEventHandler(B); + @endcode + you will end up with the following situation: + @image html overview_eventhandling_winstack.png + + Note that you can use wxWindow::PopEventHandler to remove the event handler. + + @param handler + Specifies the handler to be pushed. + It must not be part of a wxEvtHandler chain; an assert will fail + if it's not unlinked (see wxEvtHandler::IsUnlinked). + + @see @ref overview_eventhandling_processing */ - bool IsFrozen() const; + void PushEventHandler(wxEvtHandler* handler); /** - Returns @true if the window is retained, @false otherwise. + Find the given @a handler in the windows event handler stack and unlinks + (but not delete) it. See wxEvtHandler::Unlink() for more info. - @remarks Retained windows are only available on X platforms. + @param handler + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers stack. + + @return Returns @true if it was found and @false otherwise (this also + results in an assert failure so this function should + only be called when the handler is supposed to be there). + + @see PushEventHandler(), PopEventHandler() */ - virtual bool IsRetained() const; + bool RemoveEventHandler(wxEvtHandler* handler); /** - Return whether a scrollbar is always shown. + Sets the event handler for this window. - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. + Note that if you use this function you may want to use as the "next" handler + of @a handler the window itself; in this way when @a handler doesn't process + an event, the window itself will have a chance to do it. - @see AlwaysShowScrollbars() + @param handler + Specifies the handler to be set. Cannot be @NULL. + + @see @ref overview_eventhandling_processing */ - virtual bool IsScrollbarAlwaysShown(int orient) const; + void SetEventHandler(wxEvtHandler* handler); /** - Returns @true if the window is shown, @false if it has been hidden. + wxWindows cannot be used to form event handler chains; this function + thus will assert when called. - @see IsShownOnScreen() + Note that instead you can use PushEventHandler() or SetEventHandler() to + implement a stack of event handlers to override wxWindow's own + event handling mechanism. */ - virtual bool IsShown() const; + virtual void SetNextHandler(wxEvtHandler* handler); /** - Returns @true if the window is physically visible on the screen, i.e. it - is shown and all its parents up to the toplevel window are shown as well. + wxWindows cannot be used to form event handler chains; this function + thus will assert when called. - @see IsShown() + Note that instead you can use PushEventHandler() or SetEventHandler() to + implement a stack of event handlers to override wxWindow's own + event handling mechanism. */ - virtual bool IsShownOnScreen() const; + virtual void SetPreviousHandler(wxEvtHandler* handler); + + //@} + + /** - Returns @true if this window is intrinsically enabled, @false otherwise, - i.e. if @ref Enable() Enable(@false) had been called. This method is - mostly used for wxWidgets itself, user code should normally use - IsEnabled() instead. + @name Window styles functions */ - bool IsThisEnabled() const; + //@{ /** - Returns @true if the given window is a top-level one. Currently all frames and - dialogs are considered to be top-level windows (even if they have a parent - window). + Returns the extra style bits for the window. */ - virtual bool IsTopLevel() const; + long GetExtraStyle() const; /** - Invokes the constraint-based layout algorithm or the sizer-based algorithm - for this window. - - See SetAutoLayout(): when auto layout is on, this function gets called automatically - when the window is resized. + Gets the window style that was passed to the constructor or Create() + method. GetWindowStyle() is another name for the same function. + */ + virtual long GetWindowStyleFlag() const; - @see @ref overview_windowsizing + /** + See GetWindowStyleFlag() for more info. */ - virtual bool Layout(); + long GetWindowStyle() const; /** - Lowers the window to the bottom of the window hierarchy (Z-order). + Returns @true if the window has the given @a exFlag bit set in its + extra styles. - @see Raise() + @see SetExtraStyle() */ - virtual void Lower(); + bool HasExtraStyle(int exFlag) const; /** - Disables all other windows in the application so that - the user can only interact with this window. + Returns @true if the window has the given @a flag bit set. + */ + bool HasFlag(int flag) const; - @param modal - If @true, this call disables all other windows in the application so that - the user can only interact with this window. If @false, the effect is - reversed. + /** + Sets the extra style bits for the window. + The currently defined extra style bits are reported in the class + description. */ - virtual void MakeModal(bool modal = true); + virtual void SetExtraStyle(long exStyle); /** - Moves the window to the given position. + Sets the style of the window. Please note that some styles cannot be changed + after the window creation and that Refresh() might need to be be called + after changing the others for the change to take place immediately. - @param x - Required x position. - @param y - Required y position. - @param flags - See SetSize() for more info about this parameter. + See @ref overview_windowstyles "Window styles" for more information about flags. - @remarks Implementations of SetSize can also implicitly implement the - Move() function, which is defined in the base wxWindow class as the call: - @code - SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING); - @endcode + @see GetWindowStyleFlag() + */ + virtual void SetWindowStyleFlag(long style); - @see SetSize() + /** + See SetWindowStyleFlag() for more info. */ - void Move(int x, int y, int flags = wxSIZE_USE_EXISTING); + void SetWindowStyle(long style); /** - Moves the window to the given position. + Turns the given @a flag on if it's currently turned off and vice versa. + This function cannot be used if the value of the flag is 0 (which is often + the case for default flags). - @param pt - wxPoint object representing the position. - @param flags - See SetSize() for more info about this parameter. + Also, please notice that not all styles can be changed after the control + creation. - @remarks Implementations of SetSize() can also implicitly implement the - Move() function, which is defined in the base wxWindow class as the call: - @code - SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING); - @endcode + @return Returns @true if the style was turned on by this function, @false + if it was switched off. - @see SetSize() + @see SetWindowStyleFlag(), HasFlag() */ - void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); + bool ToggleWindowStyle(int flag); + + //@} + + + /** + @name Tab order functions + */ + //@{ /** Moves this window in the tab navigation order after the specified @e win. @@ -1614,1037 +1932,945 @@ public: */ bool NavigateIn(int flags = IsForward); - /** - Create a new ID or range of IDs that are not currently in use. - The IDs will be reserved until assigned to a wxWindow ID - or unreserved with UnreserveControlId(). - - See @ref overview_windowids for more information. + //@} - @param count - The number of sequential IDs to reserve. - @return Returns the ID or the first ID of the range, or wxID_NONE if the - specified number of identifiers couldn't be allocated. - @see UnreserveControlId(), wxIdManager, - @ref overview_windowids + /** + @name Z order functions */ - static wxWindowID NewControlId(int count = 1); + //@{ /** - 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. + Lowers the window to the bottom of the window hierarchy (Z-order). - This function may be used to do delayed painting, for example, - and most implementations call UpdateWindowUI() - in order to send update events to the window in idle time. - */ - virtual void OnInternalIdle(); + @remarks + This function only works for wxTopLevelWindow-derived classes. - /** - Same as #ScrollLines (-1). + @see Raise() */ - bool LineUp(); + virtual void Lower(); /** - Same as #ScrollLines (1). + Raises the window to the top of the window hierarchy (Z-order). + + @remarks + This function only works for wxTopLevelWindow-derived classes. + + @see Lower() */ - bool LineDown(); + virtual void Raise(); + + //@} + /** - Same as #ScrollPages (-1). + @name Window status functions */ - bool PageUp(); + //@{ + /** - Same as #ScrollPages (1). + Equivalent to calling wxWindow::Show(@false). */ - bool PageDown(); - + bool Hide(); /** - Removes and returns the top-most event handler on the event handler stack. + This function hides a window, like Hide(), but using a special visual + effect if possible. - @param deleteHandler - If this is @true, the handler will be deleted after it is removed. - The default value is @false. + The parameters of this function are the same as for ShowWithEffect(), + please see their description there. - @see SetEventHandler(), GetEventHandler(), - PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @since 2.9.0 */ - wxEvtHandler* PopEventHandler(bool deleteHandler = false); - - //@{ + virtual bool HideWithEffect(wxShowEffect effect, + unsigned int timeout = 0); /** - Pops up the given menu at the specified coordinates, relative to this - window, and returns control when the user has dismissed the menu. + Returns @true if the window is enabled, i.e. if it accepts user input, + @false otherwise. - If a menu item is selected, the corresponding menu event is generated and will be - processed as usually. If the coordinates are not specified, current mouse - cursor position is used. + Notice that this method can return @false even if this window itself hadn't + been explicitly disabled when one of its parent windows is disabled. + To get the intrinsic status of this window, use IsThisEnabled() - @a menu is the menu to pop up. + @see Enable() + */ + bool IsEnabled() const; - The position where the menu will appear can be specified either as a - wxPoint @a pos or by two integers (@a x and @a y). + /** + Returns @true if the given point or rectangle area has been exposed since the + last repaint. Call this in an paint event handler to optimize redrawing by + only redrawing those areas, which have been exposed. + */ + bool IsExposed(int x, int y) const; - @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to - ensure that the menu items are in the correct state. - The menu does not get deleted by the window. - It is recommended to not explicitly specify coordinates when - calling PopupMenu in response to mouse click, because some of - the ports (namely, wxGTK) can do a better job of positioning - the menu in that case. + /** + @overload + */ + bool IsExposed(wxPoint& pt) const; - @see wxMenu + /** + @overload */ - bool PopupMenu(wxMenu* menu, - const wxPoint& pos = wxDefaultPosition); - bool PopupMenu(wxMenu* menu, int x, int y); - //@} + bool IsExposed(int x, int y, int w, int h) const; /** - Posts a size event to the window. + @overload + */ + bool IsExposed(wxRect& rect) const; + /** + Returns @true if the window is shown, @false if it has been hidden. - This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument. - */ - void PostSizeEvent(); + @see IsShownOnScreen() + */ + virtual bool IsShown() const; /** - Posts a size event to the parent of this window. + Returns @true if the window is physically visible on the screen, i.e. it + is shown and all its parents up to the toplevel window are shown as well. - This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST - argument. - */ - void PostSizeEventToParent(); + @see IsShown() + */ + virtual bool IsShownOnScreen() const; /** - Pushes this event handler onto the event stack for the window. - - @param handler - Specifies the handler to be pushed. + Disables the window. Same as @ref Enable() Enable(@false). - @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is its - own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. - wxWindow::PushEventHandler allows an application to set up a - chain of event handlers, where an event not handled by one event - handler is handed to the next one in the chain. - Use wxWindow::PopEventHandler to remove the event handler. - - @see SetEventHandler(), GetEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @return Returns @true if the window has been disabled, @false if it had + been already disabled before the call to this function. */ - void PushEventHandler(wxEvtHandler* handler); + bool Disable(); /** - Raises the window to the top of the window hierarchy (Z-order). - In current version of wxWidgets this works both for managed and child windows. + Enable or disable the window for user input. Note that when a parent window is + disabled, all of its children are disabled as well and they are reenabled again + when the parent is. + + @param enable + If @true, enables the window for input. If @false, disables the window. + + @return Returns @true if the window has been enabled or disabled, @false + if nothing was done, i.e. if the window had already + been in the specified state. - @see Lower() + @see IsEnabled(), Disable(), wxRadioBox::Enable */ - virtual void Raise(); + virtual bool Enable(bool enable = true); /** - Causes this window, and all of its children recursively (except under wxGTK1 - where this is not implemented), to be repainted. Note that repainting doesn't - happen immediately but only during the next event loop iteration, if you need - to update the window immediately you should use Update() instead. - - @param eraseBackground - If @true, the background will be erased. - @param rect - If non-@NULL, only the given rectangle will be treated as damaged. + Shows or hides the window. You may need to call Raise() + for a top level window if you want to bring it to top, although this is not + needed if Show() is called immediately after the frame creation. - @see RefreshRect() - */ - virtual void Refresh(bool eraseBackground = true, - const wxRect* rect = NULL); + @param show + If @true displays the window. Otherwise, hides it. - /** - Redraws the contents of the given rectangle: only the area inside it will be - repainted. + @return @true if the window has been shown or hidden or @false if nothing + was done because it already was in the requested state. - This is the same as Refresh() but has a nicer syntax as it can be called - with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)). + @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. */ - void RefreshRect(const wxRect& rect, bool eraseBackground = true); + virtual bool Show(bool show = true); /** - Registers a system wide hotkey. Every time the user presses the hotkey - registered here, this window will receive a hotkey event. + This function shows a window, like Show(), but using a special visual + effect if possible. - 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. + @param effect + The effect to use. - @param 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. - @param modifiers - A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT - or wxMOD_WIN specifying the modifier keys that have to be pressed along - with the key. - @param virtualKeyCode - The virtual key code of the hotkey. + @param timeout + The @a timeout parameter specifies the time of the animation, in + milliseconds. If the default value of 0 is used, the default + animation time for the current platform is used. - @return @true if the hotkey was registered successfully. @false if some - other application already registered a hotkey with this - modifier/virtualKeyCode combination. + @note Currently this function is only implemented in wxMSW and does the + same thing as Show() in the other ports. - @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the - event. This function is currently only implemented - under Windows. It is used in the Windows CE port for - detecting hardware button presses. + @since 2.9.0 - @see UnregisterHotKey() + @see HideWithEffect() */ - virtual bool RegisterHotKey(int hotkeyId, int modifiers, - int virtualKeyCode); + virtual bool ShowWithEffect(wxShowEffect effect, + unsigned int timeout = 0); - /** - Releases mouse input captured with CaptureMouse(). + //@} - @see CaptureMouse(), HasCapture(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent - */ - void ReleaseMouse(); /** - Removes a child window. + @name Context-sensitive help functions + */ + //@{ - 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 wxWidgets and shouldn't be - called by the user code. + /** + Gets the help text to be used as context-sensitive help for this window. + Note that the text is actually stored by the current wxHelpProvider + implementation, and not in the window object itself. - @param child - Child window to remove. + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider */ - virtual void RemoveChild(wxWindow* child); + wxString GetHelpText() const; /** - Find the given @a handler in the windows event handler chain and remove - (but not delete) it from it. + Sets the help text to be used as context-sensitive help for this window. + Note that the text is actually stored by the current wxHelpProvider + implementation, and not in the window object itself. - @param handler - The event handler to remove, must be non-@NULL and - must be present in this windows event handlers chain + @see GetHelpText(), wxHelpProvider::AddHelp() + */ + void SetHelpText(const wxString& helpText); - @return Returns @true if it was found and @false otherwise (this also - results in an assert failure so this function should - only be called when the handler is supposed to be there). + /** + Gets the help text to be used as context-sensitive help for this window. + This method should be overridden if the help message depends on the position + inside the window, otherwise GetHelpText() can be used. - @see PushEventHandler(), PopEventHandler() + @param point + Coordinates of the mouse at the moment of help event emission. + @param origin + Help event origin, see also wxHelpEvent::GetOrigin. */ - bool RemoveEventHandler(wxEvtHandler* handler); + virtual wxString GetHelpTextAtPoint(const wxPoint& point, + wxHelpEvent::Origin origin) const; /** - Reparents the window, i.e the window will be removed from its - current parent window (e.g. a non-standard toolbar in a wxFrame) - and then re-inserted into another. - - @param newParent - New parent. + Get the associated tooltip or @NULL if none. */ - virtual bool Reparent(wxWindow* newParent); + wxToolTip* GetToolTip() const; /** - Converts from screen to client window coordinates. + Attach a tooltip to the window. - @param x - Stores the screen x coordinate and receives the client x coordinate. - @param y - Stores the screen x coordinate and receives the client x coordinate. + wxToolTip pointer can be @NULL in the overload taking the pointer, + meaning to unset any existing tooltips, however UnsetToolTip() provides + a more readable alternative to this operation. + + Notice that these methods are always available, even if wxWidgets was + compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this + case. + + @see GetToolTip(), wxToolTip */ - void ScreenToClient(int* x, int* y) const; + void SetToolTip(const wxString& tip); /** - Converts from screen to client window coordinates. - - @param pt - The screen position. + @overload */ - wxPoint ScreenToClient(const wxPoint& pt) const; + void SetToolTip(wxToolTip* tip); /** - Scrolls the window by the given number of lines down (if @a lines is - positive) or up. + Unset any existing tooltip. - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. + @since 2.9.0 - @remarks This function is currently only implemented under MSW and - wxTextCtrl under wxGTK (it also works for wxScrolled classes - under all platforms). + @see SetToolTip() + */ + void UnsetToolTip(); - @see ScrollPages() + //@} + + + /** + @name Popup/context menu functions */ - virtual bool ScrollLines(int lines); + //@{ /** - Scrolls the window by the given number of pages down (if @a pages is - positive) or up. + This function shows a popup menu at the given position in this window and + returns the selected id. - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. + It can be more convenient than the general purpose PopupMenu() function + for simple menus proposing a choice in a list of strings to the user. - @remarks This function is currently only implemented under MSW and wxGTK. + Notice that to avoid unexpected conflicts between the (usually + consecutive range of) ids used by the menu passed to this function and + the existing EVT_UPDATE_UI() handlers, this function temporarily + disables UI updates for the window, so you need to manually disable + (or toggle or ...) any items which should be disabled in the menu + before showing it. - @see ScrollLines() - */ - virtual bool ScrollPages(int pages); + The parameter @a menu is the menu to show. + The parameter @a pos (or the parameters @a x and @a y) is the + position at which to show the menu in client coordinates. - /** - Physically scrolls the pixels in the window and move child windows accordingly. + @return + The selected menu item id or @c wxID_NONE if none selected or an + error occurred. - @param dx - Amount to scroll horizontally. - @param dy - Amount to scroll vertically. - @param rect - Rectangle to scroll, if it is @NULL, the whole window is - scrolled (this is always the case under wxGTK which doesn't support this - parameter) + @since 2.9.0 + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); - @remarks Note that you can often use wxScrolled instead of using this - function directly. + /** + @overload */ - virtual void ScrollWindow(int dx, int dy, - const wxRect* rect = NULL); + int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); /** - This function sends a dummy @ref wxSizeEvent "size event" to - the window allowing it to re-layout its children positions. + Pops up the given menu at the specified coordinates, relative to this + window, and returns control when the user has dismissed the menu. - It is sometimes useful to call this function after adding or deleting a - children after the frame creation or if a child size changes. Note that - if the frame is using either sizers or constraints for the children - layout, it is enough to call wxWindow::Layout() directly and this - function should not be used in this case. + If a menu item is selected, the corresponding menu event is generated and will be + processed as usually. If the coordinates are not specified, current mouse + cursor position is used. - If @a flags includes @c wxSEND_EVENT_POST value, this function posts - the event, i.e. schedules it for later processing, instead of - dispatching it directly. You can also use PostSizeEvent() as a more - readable equivalent of calling this function with this flag. + @a menu is the menu to pop up. - @param flags - May include @c wxSEND_EVENT_POST. Default value is 0. + The position where the menu will appear can be specified either as a + wxPoint @a pos or by two integers (@a x and @a y). + + @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to + ensure that the menu items are in the correct state. + The menu does not get deleted by the window. + It is recommended to not explicitly specify coordinates when + calling PopupMenu in response to mouse click, because some of + the ports (namely, wxGTK) can do a better job of positioning + the menu in that case. + + @see wxMenu */ - virtual void SendSizeEvent(int flags = 0); + bool PopupMenu(wxMenu* menu, + const wxPoint& pos = wxDefaultPosition); /** - Safe wrapper for GetParent()->SendSizeEvent(). - - This function simply checks that the window has a valid parent which is - not in process of being deleted and calls SendSizeEvent() on it. It is - used internally by windows such as toolbars changes to whose state - should result in parent re-layout (e.g. when a toolbar is added to the - top of the window, all the other windows must be shifted down). + @overload + */ + bool PopupMenu(wxMenu* menu, int x, int y); - @see PostSizeEventToParent() + //@} - @param flags - See description of this parameter in SendSizeEvent() documentation. - */ - void SendSizeEventToParent(int flags = 0); /** - Sets the accelerator table for this window. See wxAcceleratorTable. + Validator functions */ - virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + //@{ /** - Sets the accessible for this window. Any existing accessible for this window - will be deleted first, if not identical to @e accessible. - See also wxAccessible. + Returns a pointer to the current validator for the window, or @NULL if + there is none. */ - void SetAccessible(wxAccessible* accessible); + virtual wxValidator* GetValidator(); /** - Determines whether the Layout() function will be called automatically - when the window is resized. Please note that this only happens for the - windows usually used to contain children, namely wxPanel and wxTopLevelWindow - (and the classes deriving from them). + Deletes the current validator (if any) and sets the window validator, having + called wxValidator::Clone to create a new validator of this type. + */ + virtual void SetValidator(const wxValidator& validator); - This method is called implicitly by SetSizer() but if you use SetConstraints() - you should call it manually or otherwise the window layout won't be correctly - updated when its size changes. + /** + Transfers values from child controls to data areas specified by their + validators. Returns @false if a transfer failed. - @param autoLayout - Set this to @true if you wish the Layout function to be - called automatically when the window is resized. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataFromWindow() of all child windows. - @see SetConstraints() + @see TransferDataToWindow(), wxValidator, Validate() */ - void SetAutoLayout(bool autoLayout); + virtual bool TransferDataFromWindow(); /** - Sets the background colour of the window. - Please see InheritAttributes() for explanation of the difference between - this method and SetOwnBackgroundColour(). + Transfers values to child controls from data areas specified by their + validators. - @param colour - The colour to be used as the background colour, pass - wxNullColour to reset to the default colour. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataToWindow() of all child windows. - @remarks The background colour is usually painted by the default - wxEraseEvent event handler function under Windows and - automatically under GTK. - Note that setting the background colour does not cause an - immediate refresh, so you may wish to call wxWindow::ClearBackground - or wxWindow::Refresh after calling this function. - Using this function will disable attempts to use themes for - this window, if the system supports them. Use with care since - usually the themes represent the appearance chosen by the user - to be used for all applications on the system. + @return Returns @false if a transfer failed. - @see GetBackgroundColour(), SetForegroundColour(), - GetForegroundColour(), ClearBackground(), - Refresh(), wxEraseEvent + @see TransferDataFromWindow(), wxValidator, Validate() */ - virtual bool SetBackgroundColour(const wxColour& colour); + virtual bool TransferDataToWindow(); /** - Sets the background style of the window. see GetBackgroundStyle() for - the description of the possible style values. + Validates the current values of the child controls using their validators. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call Validate() of all child windows. - @see SetBackgroundColour(), GetForegroundColour(), - SetTransparent() + @return Returns @false if any of the validations failed. + + @see TransferDataFromWindow(), TransferDataToWindow(), + wxValidator */ - virtual bool SetBackgroundStyle(wxBackgroundStyle style); + virtual bool Validate(); - /** - This method is only implemented by ports which have support for - native TAB traversal (such as GTK+ 2.0). + //@} - It is called by wxWidgets' container control code to give the native - system a hint when doing TAB traversal. A call to this does not disable - or change the effect of programmatically calling SetFocus(). - @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + /** + @name wxWindow properties functions */ - virtual void SetCanFocus(bool canFocus); + //@{ /** - Sets the caret() associated with the window. + Returns the identifier of the window. + + @remarks Each window has an integer identifier. If the application + has not provided one (or the default wxID_ANY) an unique + identifier with a negative value will be generated. + + @see SetId(), @ref overview_windowids */ - void SetCaret(wxCaret* caret); + wxWindowID GetId() const; - //@{ /** - This sets the size of the window client area in pixels. + Generic way of getting a label from any window, for + identification purposes. - Using this function to size a window tends to be more device-independent - than SetSize(), since the application need not worry about what dimensions - the border or title bar have when trying to fit the window around panel - items, for example. + @remarks The interpretation of this function differs from class to class. + For frames and dialogs, the value returned is the + title. For buttons or static text controls, it is the + button text. This function can be useful for + meta-programs (such as testing tools or special-needs + access programs) which need to identify windows by name. */ - virtual void SetClientSize(int width, int height); - virtual void SetClientSize(const wxSize& size); - //@} + virtual wxString GetLabel() const; /** - Sets the window to have the given layout constraints. The window - will then own the object, and will take care of its deletion. - If an existing layout constraints object is already owned by the - window, it will be deleted. + Returns the window's name. - @param constraints - The constraints to set. Pass @NULL to disassociate and delete the window's - constraints. + @remarks This name is not guaranteed to be unique; it is up to the + programmer to supply an appropriate name in the window + constructor or via SetName(). - @remarks You must call SetAutoLayout() to tell a window to use - the constraints automatically in OnSize; otherwise, you - must override OnSize and call Layout() explicitly. When - setting both a wxLayoutConstraints and a wxSizer, only - the sizer will have effect. + @see SetName() */ - void SetConstraints(wxLayoutConstraints* constraints); + virtual wxString GetName() const; /** - This normally does not need to be called by user code. - It is called when a window is added to a sizer, and is used so the window - can remove itself from the sizer when it is destroyed. + Returns the value previously passed to SetWindowVariant(). */ - void SetContainingSizer(wxSizer* sizer); + wxWindowVariant GetWindowVariant() const; /** - Sets the window's cursor. Notice that the window cursor also sets it for the - children of the window implicitly. - - The @a cursor may be @c wxNullCursor in which case the window cursor will - be reset back to default. + Sets the identifier of the window. - @param cursor - Specifies the cursor that the window should normally display. + @remarks Each window has an integer identifier. If the application has + not provided one, an identifier will be generated. + Normally, the identifier should be provided on creation + and should not be modified subsequently. - @see ::wxSetCursor, wxCursor + @see GetId(), @ref overview_windowids */ - virtual bool SetCursor(const wxCursor& cursor); + void SetId(wxWindowID winid); /** - Associates a drop target with this window. - If the window already has a drop target, it is deleted. + Sets the window's label. - @see GetDropTarget(), @ref overview_dnd + @param label + The window label. + + @see GetLabel() */ - virtual void SetDropTarget(wxDropTarget* target); + virtual void SetLabel(const wxString& label); /** - Sets the event handler for this window. + Sets the window's name. - @param handler - Specifies the handler to be set. - - @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is its - own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. - It is usually better to use wxWindow::PushEventHandler since - this sets up a chain of event handlers, where an event not - handled by one event handler is handed to the next one in the chain. - - @see GetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - void SetEventHandler(wxEvtHandler* handler); + @param name + A name to set for the window. - /** - Sets the extra style bits for the window. - The currently defined extra style bits are reported in the class - description. + @see GetName() */ - virtual void SetExtraStyle(long exStyle); + virtual void SetName(const wxString& name); /** - This sets the window to receive keyboard input. + This function can be called under all platforms but only does anything under + Mac OS X 10.3+ currently. Under this system, each of the standard control can + exist in several sizes which correspond to the elements of wxWindowVariant enum. - @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, - wxPanel::SetFocusIgnoringChildren + By default the controls use the normal size, of course, but this function can + be used to change this. */ - virtual void SetFocus(); + void SetWindowVariant(wxWindowVariant variant); - /** - This function is called by wxWidgets keyboard navigation code when the user - gives the focus to this window from keyboard (e.g. using @c TAB key). - By default this method simply calls SetFocus() but - can be overridden to do something in addition to this in the derived classes. + /** + Gets the accelerator table for this window. See wxAcceleratorTable. */ - virtual void SetFocusFromKbd(); + wxAcceleratorTable* GetAcceleratorTable(); /** - Sets the font for this window. This function should not be called for the - parent window if you don't want its font to be inherited by its children, - use SetOwnFont() instead in this case and see InheritAttributes() for more - explanations. - - Please notice that the given font is not automatically used for - wxPaintDC objects associated with this window, you need to - call wxDC::SetFont too. However this font is used by - any standard controls for drawing their text as well as by - GetTextExtent(). - - @param font - Font to associate with this window, pass - wxNullFont to reset to the default font. - - @return @true if the want was really changed, @false if it was already set - to this font and so nothing was done. + Returns the accessible object for this window, if any. + See also wxAccessible. + */ + wxAccessible* GetAccessible(); - @see GetFont(), InheritAttributes() + /** + Sets the accelerator table for this window. See wxAcceleratorTable. */ - virtual bool SetFont(const wxFont& font); + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); /** - Sets the foreground colour of the window. - Please see InheritAttributes() for explanation of the difference between - this method and SetOwnForegroundColour(). + Sets the accessible for this window. Any existing accessible for this window + will be deleted first, if not identical to @e accessible. + See also wxAccessible. + */ + void SetAccessible(wxAccessible* accessible); - @param colour - The colour to be used as the foreground colour, pass - wxNullColour to reset to the default colour. + //@} - @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may be - the text colour or other colour, or it may not be used at all. - @see GetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour(), ShouldInheritColours() + /** + @name Window deletion functions */ - virtual bool SetForegroundColour(const wxColour& colour); + //@{ /** - Sets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider - implementation, and not in the window object itself. + This function simply generates a wxCloseEvent whose handler usually tries + to close the window. It doesn't close the window itself, however. + + @param force + @false if the window's close handler should be able to veto the destruction + of this window, @true if it cannot. + + @remarks Close calls the close handler for the window, providing an + opportunity for the window to choose whether to destroy + the window. Usually it is only used with the top level + windows (wxFrame and wxDialog classes) as the others + are not supposed to have any special OnClose() logic. + The close handler should check whether the window is being deleted + forcibly, using wxCloseEvent::CanVeto, in which case it should + destroy the window using wxWindow::Destroy. + Note that calling Close does not guarantee that the window will + be destroyed; but it provides a way to simulate a manual close + of a window, which may or may not be implemented by destroying + the window. The default implementation of wxDialog::OnCloseWindow + does not necessarily delete the dialog, since it will simply + simulate an wxID_CANCEL event which is handled by the appropriate + button event handler and may do anything at all. + To guarantee that the window will be destroyed, call + wxWindow::Destroy instead - @see GetHelpText(), wxHelpProvider::AddHelp() + @see @ref overview_windowdeletion "Window Deletion Overview", + Destroy(), wxCloseEvent */ - void SetHelpText(const wxString& helpText); + bool Close(bool force = false); /** - Sets the identifier of the window. - - @remarks Each window has an integer identifier. If the application has - not provided one, an identifier will be generated. - Normally, the identifier should be provided on creation - and should not be modified subsequently. + Destroys the window safely. Use this function instead of the delete operator, + since different window classes can be destroyed differently. Frames and dialogs + are not destroyed immediately when this function is called -- they are added + to a list of windows to be deleted on idle time, when all the window's events + have been processed. This prevents problems with events being sent to + non-existent windows. - @see GetId(), @ref overview_windowids + @return @true if the window has either been successfully deleted, or it + has been added to the list of windows pending real deletion. */ - void SetId(wxWindowID winid); + virtual bool Destroy(); /** - A @e smart SetSize that will fill in default size components with the - window's @e best size values. + Returns true if this window is in process of being destroyed. - Also sets the window's minsize to the value passed in for use with sizers. - This means that if a full or partial size is passed to this function then - the sizers will use that size instead of the results of GetBestSize() to - determine the minimum needs of the window for layout. + The top level windows are not deleted immediately but are rather + scheduled for later destruction to give them time to process any + pending messages, see Destroy() description. - Most controls will use this to set their initial size, and their min - size to the passed in value (if any.) + This function returns @true if this window, or one of its parent + windows, is scheduled for destruction and can be useful to avoid + manipulating it as it's usually useless to do something with a window + which is on the point of disappearing anyhow. + */ + bool IsBeingDeleted() const; - @see SetSize(), GetBestSize(), GetEffectiveMinSize(), - @ref overview_windowsizing - */ - void SetInitialSize(const wxSize& size = wxDefaultSize); + //@} - /** - Sets the window's label. - @param label - The window label. - @see GetLabel() + /** + @name Drag and drop functions */ - virtual void SetLabel(const wxString& label); + //@{ /** - Sets the maximum client size of the window, to indicate to the sizer - layout mechanism that this is the maximum possible size of its client area. + Returns the associated drop target, which may be @NULL. - @see SetMaxSize() + @see SetDropTarget(), @ref overview_dnd */ - virtual void SetMaxClientSize(const wxSize& size); + virtual wxDropTarget* GetDropTarget() const; /** - Sets the maximum size of the window, to indicate to the sizer layout mechanism - that this is the maximum possible size. + Associates a drop target with this window. + If the window already has a drop target, it is deleted. - @see SetMaxClientSize() + @see GetDropTarget(), @ref overview_dnd */ - virtual void SetMaxSize(const wxSize& size); + virtual void SetDropTarget(wxDropTarget* target); /** - Sets the minimum client size of the window, to indicate to the sizer - layout mechanism that this is the minimum required size of window's client - area. + Enables or disables eligibility for drop file events (OnDropFiles). - You may need to call this if you change the window size after - construction and before adding to its parent sizer. + @param accept + If @true, the window is eligible for drop file events. + If @false, the window will not accept drop file events. - Note, that just as with SetMinSize(), calling this method doesn't - prevent the program from explicitly making the window smaller than the - specified size. + @remarks Windows only until version 2.8.9, available on all platforms + since 2.8.10. Cannot be used together with SetDropTarget() on + non-Windows platforms. - @see SetMinSize() + @see SetDropTarget() */ - virtual void SetMinClientSize(const wxSize& size); - - /** - Sets the minimum size of the window, to indicate to the sizer layout - mechanism that this is the minimum required size. + virtual void DragAcceptFiles(bool accept); - You may need to call this if you change the window size after - construction and before adding to its parent sizer. + //@} - Notice that calling this method doesn't prevent the program from making - the window explicitly smaller than the specified size by calling - SetSize(), it just ensures that it won't become smaller than this size - during the automatic layout. - @see SetMinClientSize() + /** + @name Constraints, sizers and window layouting functions */ - virtual void SetMinSize(const wxSize& size); + //@{ /** - Sets the window's name. - - @param name - A name to set for the window. - - @see GetName() + Return the sizer that this window is a member of, if any, otherwise @NULL. */ - virtual void SetName(const wxString& name); + wxSizer* GetContainingSizer() const; /** - Sets the background colour of the window but prevents it from being inherited - by the children of this window. - - @see SetBackgroundColour(), InheritAttributes() + Return the sizer associated with the window by a previous call to + SetSizer() or @NULL. */ - void SetOwnBackgroundColour(const wxColour& colour); + wxSizer* GetSizer() const; /** - Sets the font of the window but prevents it from being inherited by the - children of this window. + Sets the window to have the given layout sizer. + The window will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted if the deleteOld parameter is @true. - @see SetFont(), InheritAttributes() - */ - void SetOwnFont(const wxFont& font); + Note that this function will also call SetAutoLayout() implicitly with @true + parameter if the @a sizer is non-@NULL and @false otherwise. - /** - Sets the foreground colour of the window but prevents it from being inherited - by the children of this window. + @param sizer + The sizer to set. Pass @NULL to disassociate and conditionally delete + the window's sizer. See below. + @param deleteOld + If @true (the default), this will delete any pre-existing sizer. + Pass @false if you wish to handle deleting the old sizer yourself. - @see SetForegroundColour(), InheritAttributes() + @remarks SetSizer enables and disables Layout automatically. */ - void SetOwnForegroundColour(const wxColour& colour); + void SetSizer(wxSizer* sizer, bool deleteOld = true); /** - @deprecated use wxDC::SetPalette instead. + This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial + window size to the size needed to accommodate all sizer elements and sets the + size hints which, if this window is a top level one, prevent the user from + resizing it to be less than this minimial size. */ - void SetPalette(const wxPalette& pal); + void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); /** - Sets the position of one of the built-in scrollbars. + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints() const; - @param orientation - Determines the scrollbar whose position is to be set. - May be wxHORIZONTAL or wxVERTICAL. - @param pos - Position in scroll units. - @param refresh - @true to redraw the scrollbar, @false otherwise. + /** + Sets the window to have the given layout constraints. The window + will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted. - @remarks This function does not directly affect the contents of the - window: it is up to the application to take note of - scrollbar attributes and redraw contents accordingly. + @param constraints + The constraints to set. Pass @NULL to disassociate and delete the window's + constraints. - @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, - wxScrolled + @remarks You must call SetAutoLayout() to tell a window to use + the constraints automatically in OnSize; otherwise, you + must override OnSize and call Layout() explicitly. When + setting both a wxLayoutConstraints and a wxSizer, only + the sizer will have effect. */ - virtual void SetScrollPos(int orientation, int pos, - bool refresh = true); + void SetConstraints(wxLayoutConstraints* constraints); - /** - Sets the scrollbar properties of a built-in scrollbar. - @param orientation - Determines the scrollbar whose page size is to be set. - May be wxHORIZONTAL or wxVERTICAL. - @param position - The position of the scrollbar in scroll units. - @param thumbSize - The size of the thumb, or visible portion of the scrollbar, in scroll units. - @param range - The maximum position of the scrollbar. - @param refresh - @true to redraw the scrollbar, @false otherwise. + /** + Invokes the constraint-based layout algorithm or the sizer-based algorithm + for this window. - @remarks - Let's say you wish to display 50 lines of text, using the same font. - The window is sized so that you can only see 16 lines at a time. - You would use: - @code - SetScrollbar(wxVERTICAL, 0, 16, 50); - @endcode - Note that with the window at this size, the thumb position can never - go above 50 minus 16, or 34. You can determine how many lines are - currently visible by dividing the current view size by the character - height in pixels. - When defining your own scrollbar behaviour, you will always need - to recalculate the scrollbar settings when the window size changes. - You could therefore put your scrollbar calculations and SetScrollbar - call into a function named AdjustScrollbars, which can be called - initially and also from your wxSizeEvent handler function. + This function does not get called automatically when the window is resized + because lots of windows deriving from wxWindow does not need this functionality. + If you want to have Layout() called automatically, you should derive + from wxPanel (see wxPanel::Layout). - @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent + @see @ref overview_windowsizing */ - virtual void SetScrollbar(int orientation, int position, - int thumbSize, int range, - bool refresh = true); + virtual bool Layout(); /** - Sets the size of the window in pixels. - - @param x - Required x position in pixels, or wxDefaultCoord to indicate that the - existing value should be used. - @param y - Required y position in pixels, or wxDefaultCoord to indicate that the - existing value should be used. - @param width - Required width in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - @param height - Required height position in pixels, or wxDefaultCoord to indicate that the - existing value should be used. - @param sizeFlags - Indicates the interpretation of other parameters. - It is a bit list of the following: - - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate - a wxWidgets-supplied default width. - - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate - a wxWidgets-supplied default height. - - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate - a wxWidgets-supplied default size. - - @c wxSIZE_USE_EXISTING: existing dimensions should be used - if wxDefaultCoord values are supplied. - - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of - wxDefaultCoord) to be interpreted as real - dimensions, not default values. - - @c wxSIZE_FORCE: normally, if the position and the size of the window are - already the same as the parameters of this function, - nothing is done. but with this flag a window resize may - be forced even in this case (supported in wx 2.6.2 and - later and only implemented for MSW and ignored elsewhere - currently). + Determines whether the Layout() function will be called automatically + when the window is resized. Please note that this only happens for the + windows usually used to contain children, namely wxPanel and wxTopLevelWindow + (and the classes deriving from them). - @remarks This overload sets the position and optionally size, of the window. - Parameters may be wxDefaultCoord to indicate either that a default - should be supplied by wxWidgets, or that the current value of the - dimension should be used. + This method is called implicitly by SetSizer() but if you use SetConstraints() + you should call it manually or otherwise the window layout won't be correctly + updated when its size changes. - @see Move() + @param autoLayout + Set this to @true if you wish the Layout() function to be + called automatically when the window is resized + (really happens only if you derive from wxPanel or wxTopLevelWindow). + + @see SetConstraints() */ - void SetSize(int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO); + void SetAutoLayout(bool autoLayout); - //@{ - /** - Sets the size of the window in pixels. - The size is specified using a wxRect, wxSize or by a couple of @c int objects. + //@} - @remarks This form must be used with non-default width and height values. - @see Move() + + /** + @name Mouse functions */ - virtual void SetSize(const wxRect& rect); - virtual void SetSize(const wxSize& size); - virtual void SetSize(int width, int height); - //@} + //@{ /** - Sets the window to have the given layout sizer. - The window will then own the object, and will take care of its deletion. - If an existing layout constraints object is already owned by the - window, it will be deleted if the deleteOld parameter is @true. + Directs all mouse input to this window. + Call ReleaseMouse() to release the capture. - Note that this function will also call SetAutoLayout() implicitly with @true - parameter if the @a sizer is non-@NULL and @false otherwise. + Note that wxWidgets maintains the stack of windows having captured the mouse + and when the mouse is released the capture returns to the window which had had + captured it previously and it is only really released if there were no previous + window. In particular, this means that you must release the mouse as many times + as you capture it, unless the window receives the wxMouseCaptureLostEvent event. - @param sizer - The sizer to set. Pass @NULL to disassociate and conditionally delete - the window's sizer. See below. - @param deleteOld - If @true (the default), this will delete any pre-existing sizer. - Pass @false if you wish to handle deleting the old sizer yourself. + Any application which captures the mouse in the beginning of some operation + must handle wxMouseCaptureLostEvent and cancel this operation when it receives + the event. The event handler must not recapture mouse. - @remarks SetSizer enables and disables Layout automatically. + @see ReleaseMouse(), wxMouseCaptureLostEvent */ - void SetSizer(wxSizer* sizer, bool deleteOld = true); + void CaptureMouse(); /** - This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial - window size to the size needed to accommodate all sizer elements and sets the - size hints which, if this window is a top level one, prevent the user from - resizing it to be less than this minimial size. + Returns the caret() associated with the window. */ - void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); + wxCaret* GetCaret() const; /** - This function tells a window if it should use the system's "theme" code - to draw the windows' background instead if its own background drawing - code. This does not always have any effect since the underlying platform - obviously needs to support the notion of themes in user defined windows. - One such platform is GTK+ where windows can have (very colourful) backgrounds - defined by a user's selected theme. + Return the cursor associated with this window. - 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. + @see SetCursor() */ - virtual void SetThemeEnabled(bool enable); + const wxCursor& GetCursor() const; - //@{ /** - Attach a tooltip to the window. + Returns @true if this window has the current mouse capture. - wxToolTip pointer can be @NULL in the overload taking the pointer, - meaning to unset any existing tooltips, however UnsetToolTip() provides - a more readable alternative to this operation. + @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent + */ + virtual bool HasCapture() const; - Notice that these methods are always available, even if wxWidgets was - compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this - case. + /** + Releases mouse input captured with CaptureMouse(). - @see GetToolTip(), wxToolTip + @see CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent */ - void SetToolTip(const wxString& tip); - void SetToolTip(wxToolTip* tip); - //@} + void ReleaseMouse(); /** - Set the transparency of the window. If the system supports transparent windows, - returns @true, otherwise returns @false and the window remains fully opaque. - See also CanSetTransparent(). - - The parameter @a alpha is in the range 0..255 where 0 corresponds to a - fully transparent window and 255 to the fully opaque one. The constants - @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used. + Sets the caret() associated with the window. */ - virtual bool SetTransparent(wxByte alpha); + void SetCaret(wxCaret* caret); /** - Deletes the current validator (if any) and sets the window validator, having - called wxValidator::Clone to create a new validator of this type. + Sets the window's cursor. Notice that the window cursor also sets it for the + children of the window implicitly. + + The @a cursor may be @c wxNullCursor in which case the window cursor will + be reset back to default. + + @param cursor + Specifies the cursor that the window should normally display. + + @see ::wxSetCursor, wxCursor */ - virtual void SetValidator(const wxValidator& validator); + virtual bool SetCursor(const wxCursor& cursor); - //@{ /** - Sets the virtual size of the window in pixels. + Moves the pointer to the given position on the window. + + @note This function is not supported under Mac because Apple Human + Interface Guidelines forbid moving the mouse cursor programmatically. + + @param x + The new x position for the cursor. + @param y + The new y position for the cursor. */ - void SetVirtualSize(int width, int height); - void SetVirtualSize(const wxSize& size); + virtual void WarpPointer(int x, int y); + //@} + + + /** - Identical to SetWindowStyleFlag(). + @name Miscellaneous functions */ - void SetWindowStyle(long style); + //@{ /** - Sets the style of the window. Please note that some styles cannot be changed - after the window creation and that Refresh() might need to be be called - after changing the others for the change to take place immediately. + Does the window-specific updating after processing the update event. + This function is called by UpdateWindowUI() in order to check return + values in the wxUpdateUIEvent and act appropriately. + For example, to allow frame and dialog title updating, wxWidgets + implements this function as follows: - See @ref overview_windowstyles "Window styles" for more information about flags. + @code + // do the window-specific processing after processing the update event + void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) + { + if ( event.GetSetEnabled() ) + Enable(event.GetEnabled()); - @see GetWindowStyleFlag() + if ( event.GetSetText() ) + { + if ( event.GetText() != GetTitle() ) + SetTitle(event.GetText()); + } + } + @endcode */ - virtual void SetWindowStyleFlag(long style); + virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); /** - This function can be called under all platforms but only does anything under - Mac OS X 10.3+ currently. Under this system, each of the standard control can - exist in several sizes which correspond to the elements of wxWindowVariant enum. - - By default the controls use the normal size, of course, but this function can - be used to change this. + Returns the platform-specific handle of the physical window. + Cast it to an appropriate handle, such as @b HWND for Windows, + @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS. */ - void SetWindowVariant(wxWindowVariant variant); + virtual WXWidget GetHandle() const; /** - Return @true from here to allow the colours of this window to be changed by - InheritAttributes(), returning @false forbids inheriting them from the parent window. - - The base class version returns @false, but this method is overridden in - wxControl where it returns @true. + This method should be overridden to return @true if this window has + multiple pages. All standard class with multiple pages such as + wxNotebook, wxListbook and wxTreebook already override it to return @true + and user-defined classes with similar behaviour should do it as well to + allow the library to handle such windows appropriately. */ - virtual bool ShouldInheritColours() const; + virtual bool HasMultiplePages() const; /** - Shows or hides the window. You may need to call Raise() - for a top level window if you want to bring it to top, although this is not - needed if Show() is called immediately after the frame creation. - - @param show - If @true displays the window. Otherwise, hides it. + This function is (or should be, in case of custom controls) called during + window creation to intelligently set up the window visual attributes, that is + the font and the foreground and background colours. - @return @true if the window has been shown or hidden or @false if nothing - was done because it already was in the requested state. + By "intelligently" the following is meant: by default, all windows use their + own @ref GetClassDefaultAttributes() default attributes. + However if some of the parents attributes are explicitly (that is, using + SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding + attribute hadn't been explicitly set for this window itself, then this + window takes the same value as used by the parent. + In addition, if the window overrides ShouldInheritColours() to return @false, + the colours will not be changed no matter what and only the font might. - @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. + This rather complicated logic is necessary in order to accommodate the + different usage scenarios. The most common one is when all default attributes + are used and in this case, nothing should be inherited as in modern GUIs + different controls use different fonts (and colours) than their siblings so + they can't inherit the same value from the parent. However it was also deemed + desirable to allow to simply change the attributes of all children at once by + just changing the font or colour of their common parent, hence in this case we + do inherit the parents attributes. */ - virtual bool Show(bool show = true); + virtual void InheritAttributes(); /** - This function shows a window, like Show(), but using a special visual - effect if possible. - - @param effect - The effect to use. - - @param timeout - The @a timeout parameter specifies the time of the animation, in - milliseconds. If the default value of 0 is used, the default - animation time for the current platform is used. - - @note Currently this function is only implemented in wxMSW and does the - same thing as Show() in the other ports. + Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data + to the dialog via validators. + */ + virtual void InitDialog(); - @since 2.9.0 + /** + Returns @true if the window contents is double-buffered by the system, i.e. if + any drawing done on the window is really done on a temporary backing surface + and transferred to the screen all at once later. - @see HideWithEffect() + @see wxBufferedDC */ - virtual bool ShowWithEffect(wxShowEffect effect, - unsigned int timeout = 0); + virtual bool IsDoubleBuffered() const; /** - Reenables window updating after a previous call to Freeze(). - - To really thaw the control, it must be called exactly the same number - of times as Freeze(). + Returns @true if the window is retained, @false otherwise. - If the window has any children, they are recursively thawn too. + @remarks Retained windows are only available on X platforms. + */ + virtual bool IsRetained() const; - @see wxWindowUpdateLocker, Freeze(), IsFrozen() + /** + Returns @true if this window is intrinsically enabled, @false otherwise, + i.e. if @ref Enable() Enable(@false) had been called. This method is + mostly used for wxWidgets itself, user code should normally use + IsEnabled() instead. */ - void Thaw(); + bool IsThisEnabled() const; /** - Turns the given @a flag on if it's currently turned off and vice versa. - This function cannot be used if the value of the flag is 0 (which is often - the case for default flags). - - Also, please notice that not all styles can be changed after the control - creation. + Returns @true if the given window is a top-level one. Currently all frames and + dialogs are considered to be top-level windows (even if they have a parent + window). + */ + virtual bool IsTopLevel() const; - @return Returns @true if the style was turned on by this function, @false - if it was switched off. + /** + Disables all other windows in the application so that + the user can only interact with this window. - @see SetWindowStyleFlag(), HasFlag() + @param modal + If @true, this call disables all other windows in the application so that + the user can only interact with this window. If @false, the effect is + reversed. */ - bool ToggleWindowStyle(int flag); + virtual void MakeModal(bool modal = true); /** - Transfers values from child controls to data areas specified by their - validators. Returns @false if a transfer failed. - - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataFromWindow() of all child windows. + 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. - @see TransferDataToWindow(), wxValidator, Validate() + This function may be used to do delayed painting, for example, + and most implementations call UpdateWindowUI() + in order to send update events to the window in idle time. */ - virtual bool TransferDataFromWindow(); + virtual void OnInternalIdle(); /** - Transfers values to child controls from data areas specified by their - validators. + Registers a system wide hotkey. Every time the user presses the hotkey + registered here, this window will receive a hotkey event. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataToWindow() of all child windows. + 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. - @return Returns @false if a transfer failed. + @param 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. + @param modifiers + A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT + or wxMOD_WIN specifying the modifier keys that have to be pressed along + with the key. + @param virtualKeyCode + The virtual key code of the hotkey. - @see TransferDataFromWindow(), wxValidator, Validate() + @return @true if the hotkey was registered successfully. @false if some + other application already registered a hotkey with this + modifier/virtualKeyCode combination. + + @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the + event. This function is currently only implemented + under Windows. It is used in the Windows CE port for + detecting hardware button presses. + + @see UnregisterHotKey() */ - virtual bool TransferDataToWindow(); + virtual bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); /** Unregisters a system wide hotkey. @@ -2662,40 +2888,6 @@ public: */ virtual bool UnregisterHotKey(int hotkeyId); - /** - Unreserve an ID or range of IDs that was reserved by NewControlId(). - See @ref overview_windowids for more information. - - @param id - The starting ID of the range of IDs to unreserve. - @param count - The number of sequential IDs to unreserve. - - @see NewControlId(), wxIdManager, @ref overview_windowids - */ - static void UnreserveControlId(wxWindowID id, int count = 1); - - /** - Unset any existing tooltip. - - @since 2.9.0 - - @see SetToolTip() - */ - void UnsetToolTip(); - - /** - Calling this method immediately repaints the invalidated area of the window and - all of its children recursively while this would usually only happen when the - flow of control returns to the event loop. - - Notice that this function doesn't invalidate any area of the window so - nothing happens if nothing has been invalidated (i.e. marked as requiring - a redraw). Use Refresh() first if you want to immediately redraw the - window unconditionally. - */ - virtual void Update(); - /** This function sends one or more wxUpdateUIEvent to the window. The particular implementation depends on the window; for example a @@ -2707,7 +2899,7 @@ public: are concerned). This may be necessary if you have called wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit the overhead that wxWidgets incurs by sending update UI events in idle time. - @a flags should be a bitlist of one or more of the wxUpdateUI enumeration. + @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration. If you are calling this function from an OnInternalIdle or OnIdle function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since @@ -2729,30 +2921,137 @@ public: */ virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); + //@} + + + // NOTE: static functions must have their own group or Doxygen will screw + // up the ordering of the member groups + /** - Validates the current values of the child controls using their validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call Validate() of all child windows. + @name Miscellaneous static functions + */ + //@{ - @return Returns @false if any of the validations failed. + /** + Returns the default font and colours which are used by the control. - @see TransferDataFromWindow(), TransferDataToWindow(), - wxValidator + This is useful if you want to use the same font or colour in your own control + as in a standard control -- which is a much better idea than hard coding specific + colours or fonts which might look completely out of place on the users + system, especially if it uses themes. + + The @a variant parameter is only relevant under Mac currently and is + ignore under other platforms. Under Mac, it will change the size of the + returned font. See SetWindowVariant() for more about this. + + This static method is "overridden" in many derived classes and so calling, + for example, wxButton::GetClassDefaultAttributes() will typically + return the values appropriate for a button which will be normally different + from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). + + The @c wxVisualAttributes structure has at least the fields + @c font, @c colFg and @c colBg. All of them may be invalid + if it was not possible to determine the default control appearance or, + especially for the background colour, if the field doesn't make sense as is + the case for @c colBg for the controls with themed background. + + @see InheritAttributes() */ - virtual bool Validate(); + static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); /** - Moves the pointer to the given position on the window. + Finds the window or control which currently has the keyboard focus. - @note This function is not supported under Mac because Apple Human - Interface Guidelines forbid moving the mouse cursor programmatically. + @remarks Note that this is a static function, so it can be called without + needing a wxWindow pointer. - @param x - The new x position for the cursor. - @param y - The new y position for the cursor. + @see SetFocus(), HasFocus() */ - virtual void WarpPointer(int x, int y); + static wxWindow* FindFocus(); + + /** + Find the first window with the given @e id. + + If @a parent is @NULL, the search will start from all top-level frames + and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowById(long id, const wxWindow* parent = 0); + + /** + Find a window by its label. + + Depending on the type of window, the label may be a window title + or panel item label. If @a parent is @NULL, the search will start from all + top-level frames and dialog boxes; if non-@NULL, the search will be + limited to the given window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowByLabel(const wxString& label, + const wxWindow* parent = 0); + + /** + Find a window by its name (as given in a window constructor or Create() + function call). + + If @a parent is @NULL, the search will start from all top-level frames + and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + + The search is recursive in both cases. If no window with such name is found, + FindWindowByLabel() is called. + + @see FindWindow() + */ + static wxWindow* FindWindowByName(const wxString& name, + const wxWindow* parent = 0); + + /** + Returns the currently captured window. + + @see HasCapture(), CaptureMouse(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + static wxWindow* GetCapture(); + + /** + Create a new ID or range of IDs that are not currently in use. + The IDs will be reserved until assigned to a wxWindow ID + or unreserved with UnreserveControlId(). + + See @ref overview_windowids for more information. + + @param count + The number of sequential IDs to reserve. + + @return Returns the ID or the first ID of the range, or wxID_NONE if the + specified number of identifiers couldn't be allocated. + + @see UnreserveControlId(), wxIdManager, + @ref overview_windowids + */ + static wxWindowID NewControlId(int count = 1); + + /** + Unreserve an ID or range of IDs that was reserved by NewControlId(). + See @ref overview_windowids for more information. + + @param id + The starting ID of the range of IDs to unreserve. + @param count + The number of sequential IDs to unreserve. + + @see NewControlId(), wxIdManager, @ref overview_windowids + */ + static void UnreserveControlId(wxWindowID id, int count = 1); + + //@} + protected: @@ -2785,6 +3084,45 @@ protected: @deprecated @todo provide deprecation description */ virtual void SetInitialBestSize(const wxSize& size); + + /** + Generate wxWindowDestroyEvent for this window. + + This is called by the window itself when it is being destroyed and + usually there is no need to call it but see wxWindowDestroyEvent for + explanations of when you might want to do it. + */ + void SendDestroyEvent(); + + /** + This function is public in wxEvtHandler but protected in wxWindow + because for wxWindows you should always call ProcessEvent() on the + pointer returned by GetEventHandler() and not on the wxWindow object + itself. + + For convenience, a ProcessWindowEvent() method is provided as a synonym + for @code GetEventHandler()->ProcessEvent() @endcode. + + Note that it's still possible to call these functions directly on the + wxWindow object (e.g. casting it to wxEvtHandler) but doing that will + create subtle bugs when windows with event handlers pushed on them are + involved. + + This holds also for all other wxEvtHandler functions. + */ + virtual bool ProcessEvent(wxEvent& event); + + //@{ + /** + See ProcessEvent() for more info about why you shouldn't use this function + and the reason for making this function protected in wxWindow. + */ + bool SafelyProcessEvent(wxEvent& event); + virtual void QueueEvent(wxEvent *event); + virtual void AddPendingEvent(const wxEvent& event); + void ProcessPendingEvents(); + bool ProcessThreadEvent(const wxEvent& event); + //@} }; @@ -2793,7 +3131,7 @@ protected: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_misc */ +/** @addtogroup group_funcmacro_misc */ //@{ /**