From d0a6715724f10ef967bd9c3868c433142efab9b1 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 22 Jan 2009 01:45:21 +0000 Subject: [PATCH] no real change: just grouped the tons of wxWindows function in meaningful groups git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58289 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/window.h | 3373 ++++++++++++++++++++++------------------- 1 file changed, 1773 insertions(+), 1600 deletions(-) diff --git a/interface/wx/window.h b/interface/wx/window.h index d2ed1799a0..f8df295621 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -272,6 +272,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 @@ -297,397 +305,384 @@ public: virtual bool AcceptsFocusRecursively() const; /** - Adds a child window. This is called automatically by window creation - functions so should not be required by the application programmer. - Notice that this function is mostly internal to wxWidgets and shouldn't be - called by the user code. + Returns @true if the window (or in case of composite controls, its main + child window) has focus. - @param child - Child window to add. + @see FindFocus() */ - virtual void AddChild(wxWindow* child); + virtual bool HasFocus() const; /** - 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. + This method is only implemented by ports which have support for + native TAB traversal (such as GTK+ 2.0). - @since 2.9.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(). - @param hflag - Whether the horizontal scroll bar should always be visible. - @param vflag - Whether the vertical scroll bar should always be visible. + @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + */ + virtual void SetCanFocus(bool canFocus); - @remarks This function is currently only implemented under Mac/Carbon. + /** + This sets the window to receive keyboard input. + + @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, + wxPanel::SetFocusIgnoringChildren */ - virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); + virtual void SetFocus(); /** - Sets the cached best size value. + 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. */ - void CacheBestSize(const wxSize& size) const; + virtual void SetFocusFromKbd(); + + //@} + /** - 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. + @name Child management functions */ - virtual bool CanSetTransparent(); + //@{ /** - Directs all mouse input to this window. - Call ReleaseMouse() to release the capture. + Adds a child window. This is called automatically by window creation + functions so should not be required by the application programmer. + Notice that this function is mostly internal to wxWidgets and shouldn't be + called by the user code. - 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 child + Child window to add. + */ + virtual void AddChild(wxWindow* child); - 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. + /** + Destroys all children of a window. Called automatically by the destructor. + */ + bool DestroyChildren(); - @see ReleaseMouse(), wxMouseCaptureLostEvent + /** + Find a child of this window, by @a id. + May return @a this if it matches itself. */ - void CaptureMouse(); + wxWindow* FindWindow(long id) const; /** - A synonym for Centre(). + Find a child of this window, by name. + May return @a this if it matches itself. */ - void Center(int dir = wxBOTH); + wxWindow* FindWindow(const wxString& name) const; /** - A synonym for CentreOnParent(). + 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*. */ - void CenterOnParent(int dir = wxBOTH); + wxWindowList& GetChildren(); /** - Centres the window. + @overload + */ + const wxWindowList& GetChildren() const; - @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. + /** + Removes a child 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. + 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 Center() + @param child + Child window to remove. */ - void Centre(int direction = wxBOTH); - - /** - Centres the window on its parent. This is a more readable synonym for Centre(). + virtual void RemoveChild(wxWindow* child); - @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. + //@} - @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 + /** + @name Sibling and parent management functions */ - void CentreOnParent(int direction = wxBOTH); + //@{ /** - Clears the window by filling it with the current background colour. Does not - cause an erase background event to be generated. + Returns the grandparent of a window, or @NULL if there isn't one. */ - virtual void ClearBackground(); + wxWindow* GetGrandParent() const; /** - Converts to screen coordinates from coordinates relative to this window. + Returns the next window after this one among the parent children or @NULL + if this window is the last child. - @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.8.8 - @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 + @see GetPrevSibling() */ - void ClientToScreen(int* x, int* y) const; + wxWindow* GetNextSibling() const; /** - Converts to screen coordinates from coordinates relative to this window. - - @param pt - The client position for the second form of the function. + Returns the parent of the window, or @NULL if there is no parent. */ - wxPoint ClientToScreen(const wxPoint& pt) const; + wxWindow* GetParent() const; /** - Converts client area size @a size to corresponding window size. - - 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. + 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 WindowToClientSize() + @see GetNextSibling() */ - virtual wxSize ClientToWindowSize(const wxSize& size) const; - + wxWindow* GetPrevSibling() 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. + 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. - 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 newParent + New parent. + */ + virtual bool Reparent(wxWindow* newParent); - @since 2.8.8 + //@} - @see ClientToWindowSize() + + /** + @name Scrolling and scrollbars */ - virtual wxSize WindowToClientSize(const wxSize& size) const; + //@{ /** - This function simply generates a wxCloseEvent whose handler usually tries - to close the window. It doesn't close the window itself, however. + 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 force - @false if the window's close handler should be able to veto the destruction - of this window, @true if it cannot. + @since 2.9.0 - @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 + @param hflag + Whether the horizontal scroll bar should always be visible. + @param vflag + Whether the vertical scroll bar should always be visible. - @see @ref overview_windowdeletion "Window Deletion Overview", - Destroy(), wxCloseEvent + @remarks This function is currently only implemented under Mac/Carbon. */ - bool Close(bool force = false); + virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); - //@{ /** - Converts a point or size from dialog units to pixels. + Returns the built-in scrollbar position. - 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 See SetScrollbar() + */ + virtual int GetScrollPos(int orientation) const; - @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 + /** + Returns the built-in scrollbar range. - @see ConvertPixelsToDialog() + @see SetScrollbar() */ - wxPoint ConvertDialogToPixels(const wxPoint& pt); - wxSize ConvertDialogToPixels(const wxSize& sz); - //@} + virtual int GetScrollRange(int orientation) const; - //@{ /** - Converts a point or size from pixels to dialog units. - - 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. + Returns the built-in scrollbar thumb size. - @see ConvertDialogToPixels() + @see SetScrollbar() */ - wxPoint ConvertPixelsToDialog(const wxPoint& pt); - wxSize ConvertPixelsToDialog(const wxSize& sz); - //@} + virtual int GetScrollThumb(int orientation) const; /** - 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. + Returns @true if this window has a scroll bar for this orientation. - @return @true if the window has either been successfully deleted, or it - has been added to the list of windows pending real deletion. + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. */ - virtual bool Destroy(); + bool HasScrollbar(int orient) const; /** - Destroys all children of a window. Called automatically by the destructor. + Return whether a scrollbar is always shown. + + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + + @see AlwaysShowScrollbars() */ - bool DestroyChildren(); + virtual bool IsScrollbarAlwaysShown(int orient) const; /** - Returns true if this window is in process of being destroyed. + Scrolls the window by the given number of lines down (if @a lines is + positive) or up. - 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. + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. - 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; + @remarks This function is currently only implemented under MSW and + wxTextCtrl under wxGTK (it also works for wxScrolled classes + under all platforms). + + @see ScrollPages() + */ + virtual bool ScrollLines(int lines); /** - Disables the window. Same as @ref Enable() Enable(@false). + Scrolls the window by the given number of pages down (if @a pages is + positive) or up. - @return Returns @true if the window has been disabled, @false if it had - been already disabled before the call to this function. + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. + + @remarks This function is currently only implemented under MSW and wxGTK. + + @see ScrollLines() */ - bool Disable(); + virtual bool ScrollPages(int pages); /** - 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: + Physically scrolls the pixels in the window and move child windows accordingly. - @code - // do the window-specific processing after processing the update event - void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) - { - if ( event.GetSetEnabled() ) - Enable(event.GetEnabled()); + @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) - if ( event.GetSetText() ) - { - if ( event.GetText() != GetTitle() ) - SetTitle(event.GetText()); - } - } - @endcode + @remarks Note that you can often use wxScrolled instead of using this + function directly. */ - virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); + virtual void ScrollWindow(int dx, int dy, + const wxRect* rect = NULL); /** - Enables or disables eligibility for drop file events (OnDropFiles). + Same as #ScrollLines (-1). + */ + bool LineUp(); - @param accept - If @true, the window is eligible for drop file events. - If @false, the window will not accept drop file events. + /** + Same as #ScrollLines (1). + */ + bool LineDown(); - @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. + /** + Same as #ScrollPages (-1). + */ + bool PageUp(); - @see SetDropTarget() + /** + Same as #ScrollPages (1). */ - virtual void DragAcceptFiles(bool accept); + bool PageDown(); /** - 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. + Sets the position of one of the built-in scrollbars. - @param enable - If @true, enables the window for input. If @false, disables the window. + @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. - @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. + @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 IsEnabled(), Disable(), wxRadioBox::Enable + @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, + wxScrolled */ - virtual bool Enable(bool enable = true); + virtual void SetScrollPos(int orientation, int pos, + bool refresh = true); /** - Finds the window or control which currently has the keyboard focus. + Sets the scrollbar properties of a built-in scrollbar. - @remarks Note that this is a static function, so it can be called without - needing a wxWindow pointer. + @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. - @see SetFocus(), HasFocus() - */ - static wxWindow* FindFocus(); + @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. - /** - Find a child of this window, by @a id. - May return @a this if it matches itself. + @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent */ - wxWindow* FindWindow(long id) const; + virtual void SetScrollbar(int orientation, int position, + int thumbSize, int range, + bool refresh = true); + //@} - /** - Find a child of this window, by name. - May return @a this if it matches itself. - */ - wxWindow* FindWindow(const wxString& name) const; /** - Find the first window with the given @e id. + @name Sizing - 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 also the protected functions DoGetBestSize() and SetInitialBestSize(). + */ + //@{ - @see FindWindow() + /** + Sets the cached best size value. */ - static wxWindow* FindWindowById(long id, const wxWindow* parent = 0); + void CacheBestSize(const wxSize& size) const; /** - Find a window by its label. + Converts client area size @a size to corresponding window size. - 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. + 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 FindWindow() + @since 2.8.8 + + @see WindowToClientSize() */ - static wxWindow* FindWindowByLabel(const wxString& label, - const wxWindow* parent = 0); + virtual wxSize ClientToWindowSize(const wxSize& size) const; /** - Find a window by its name (as given in a window constructor or Create() - function call). + 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. - 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. + 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. - The search is recursive in both cases. If no window with such name is found, - FindWindowByLabel() is called. + @since 2.8.8 - @see FindWindow() + @see ClientToWindowSize() */ - static wxWindow* FindWindowByName(const wxString& name, - const wxWindow* parent = 0); + virtual wxSize WindowToClientSize(const wxSize& size) const; /** Sizes the window so that it fits around its subwindows. @@ -719,53 +714,6 @@ public: */ virtual void FitInside(); - /** - 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. - - If the window has any children, they are recursively frozen too. - - 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 wxWindowUpdateLocker, Thaw(), IsFrozen() - */ - void Freeze(); - - /** - Gets the accelerator table for this window. See wxAcceleratorTable. - */ - wxAcceleratorTable* GetAcceleratorTable(); - - /** - Returns the accessible object for this window, if any. - See also wxAccessible. - */ - wxAccessible* GetAccessible(); - - /** - Returns the background colour of the window. - - @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour() - */ - wxColour GetBackgroundColour() const; - - /** - Returns the background style of the window. - The background style can be one of the wxBackgroundStyle. - - @see SetBackgroundColour(), GetForegroundColour(), - SetBackgroundStyle(), SetTransparent() - */ - virtual wxBackgroundStyle GetBackgroundStyle() const; - /** This functions returns the best acceptable minimal size for the window. @@ -776,66 +724,6 @@ public: */ wxSize GetBestSize() const; - /** - Returns the currently captured window. - - @see HasCapture(), CaptureMouse(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent - */ - static wxWindow* GetCapture(); - - /** - Returns the caret() associated with the window. - */ - wxCaret* GetCaret() const; - - /** - Returns the character height for this window. - */ - virtual int GetCharHeight() const; - - /** - Returns the average character width for this window. - */ - virtual int GetCharWidth() const; - - //@{ - /** - 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*. - */ - wxWindowList& GetChildren(); - const wxWindowList& GetChildren() const; - //@} - - /** - 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. - - 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() - */ - static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); - - //@{ /** Returns the size of the window 'client area' in pixels. @@ -847,49 +735,11 @@ public: @see GetSize(), GetVirtualSize() */ void GetClientSize(int* width, int* height) const; - wxSize GetClientSize() const; - //@} - - /** - Returns a pointer to the window's layout constraints, or @NULL if there are none. - */ - wxLayoutConstraints* GetConstraints() const; - - /** - Return the sizer that this window is a member of, if any, otherwise @NULL. - */ - wxSizer* GetContainingSizer() const; - - /** - Return the cursor associated with this window. - - @see SetCursor() - */ - const wxCursor& GetCursor() const; - - /** - 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. - - 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. - */ - virtual wxVisualAttributes GetDefaultAttributes() const; /** - Returns the associated drop target, which may be @NULL. - - @see SetDropTarget(), @ref overview_dnd + @overload */ - virtual wxDropTarget* GetDropTarget() const; + wxSize GetClientSize() const; /** Merges the window's best size into the min size and returns the result. @@ -900,97 +750,6 @@ public: */ wxSize GetEffectiveMinSize() const; - /** - Returns the event handler for this window. - By default, the window is its own event handler. - - @see SetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - wxEvtHandler* GetEventHandler() const; - - /** - Returns the extra style bits for the window. - */ - long GetExtraStyle() const; - - /** - Returns the font for this window. - - @see SetFont() - */ - wxFont GetFont() const; - - /** - 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() - */ - wxColour GetForegroundColour() const; - - /** - Returns the grandparent of a window, or @NULL if there isn't one. - */ - wxWindow* GetGrandParent() 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. - */ - virtual WXWidget GetHandle() 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. - - @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider - */ - wxString GetHelpText() 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. - - @param point - Coordinates of the mouse at the moment of help event emission. - @param origin - Help event origin, see also wxHelpEvent::GetOrigin. - */ - virtual wxString GetHelpTextAtPoint(const wxPoint& point, - wxHelpEvent::Origin origin) 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. - - @see SetId(), @ref overview_windowids - */ - wxWindowID GetId() const; - - /** - Generic way of getting a label from any window, for - identification purposes. - - @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 wxString GetLabel() const; - /** Returns the maximum size of window's client area. @@ -1035,512 +794,422 @@ public: virtual wxSize GetMinSize() const; /** - Returns the window's name. + Returns the size of the entire window in pixels, including title bar, border, + scrollbars, etc. - @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(). + 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. - @see SetName() + @param width + Receives the window width. + @param height + Receives the window height. + + @see GetClientSize(), GetVirtualSize() */ - virtual wxString GetName() const; + void GetSize(int* width, int* height) const; /** - Returns the next window after this one among the parent children or @NULL - if this window is the last child. - - @since 2.8.8 - - @see GetPrevSibling() + See the GetSize(int*,int*) overload for more info. */ - wxWindow* GetNextSibling() const; + wxSize GetSize() const; /** - Returns the parent of the window, or @NULL if there is no parent. + 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. */ - wxWindow* GetParent() const; + wxSize GetVirtualSize() const; - //@{ /** - 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. - - 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. - - 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. - - @return - The selected menu item id or @c wxID_NONE if none selected or an - error occurred. + Like the other GetVirtualSize() overload but uses pointers instead. - @since 2.9.0 + @param width + Receives the window virtual width. + @param height + Receives the window virtual height. */ - int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); - int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); - //@} + void GetVirtualSize(int* width, int* height) 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. - - @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() + Returns the size of the left/right and top/bottom borders of this window in x + and y components of the result respectively. */ - void GetPosition(int* x, int* y) const; + virtual wxSize GetWindowBorderSize() 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. - - @see GetScreenPosition() + Return the sizer that this window is a member of, if any, otherwise @NULL. */ - wxPoint GetPosition() const; + wxSizer* GetContainingSizer() 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() + Return the sizer associated with the window by a previous call to + SetSizer() or @NULL. */ - wxWindow* GetPrevSibling() const; + wxSizer* GetSizer() const; /** - Returns the position and size of the window as a wxRect object. - - @see GetScreenRect() + Resets the cached best size value so it will be recalculated the next time it + is needed. */ - wxRect GetRect() const; - + void InvalidateBestSize(); /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. - - @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. + Posts a size event to the window. - @see GetPosition() - */ - void GetScreenPosition(int* x, int* y) const; + This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument. + */ + void PostSizeEvent(); /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. + Posts a size event to the parent of this window. - @see GetPosition() - */ - wxPoint GetScreenPosition() const; + This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST + argument. + */ + void PostSizeEventToParent(); /** - Returns the position and size of the window on the screen as a wxRect object. + This function sends a dummy @ref wxSizeEvent "size event" to + the window allowing it to re-layout its children positions. - @see GetRect() - */ - wxRect GetScreenRect() const; + 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. - /** - Returns the built-in scrollbar position. + 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 See SetScrollbar() + @param flags + May include @c wxSEND_EVENT_POST. Default value is 0. */ - virtual int GetScrollPos(int orientation) const; + virtual void SendSizeEvent(int flags = 0); /** - Returns the built-in scrollbar range. + Safe wrapper for GetParent()->SendSizeEvent(). - @see SetScrollbar() - */ - virtual int GetScrollRange(int orientation) const; + 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). - /** - Returns the built-in scrollbar thumb size. + @see PostSizeEventToParent() - @see SetScrollbar() - */ - virtual int GetScrollThumb(int orientation) const; + @param flags + See description of this parameter in SendSizeEvent() documentation. + */ + void SendSizeEventToParent(int flags = 0); /** - 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. + This sets the size of the window client area in pixels. - @see GetClientSize(), GetVirtualSize() + 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. */ - void GetSize(int* width, int* height) const; + virtual void SetClientSize(int width, int height); /** - See the GetSize(int*,int*) overload for more info. + @overload */ - wxSize GetSize() const; + virtual void SetClientSize(const wxSize& size); /** - Return the sizer associated with the window by a previous call to - SetSizer() or @NULL. + 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. */ - wxSizer* GetSizer() const; + void SetContainingSizer(wxSizer* sizer); /** - Gets the dimensions of the string as it would be drawn on the - window with the currently selected font. + A @e smart SetSize that will fill in default size components with the + window's @e best size values. - The text extent is returned in @a w and @a h pointers. + 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. - @param string - String whose extent is to be measured. - @param w - Return value for width. - @param h - Return value for height. - @param descent - Return value for descent (optional). - @param externalLeading - Return value for external leading (optional). - @param font - Font to use instead of the current window font (optional). - */ - virtual void GetTextExtent(const wxString& string, int* w, int* h, - int* descent = NULL, - int* externalLeading = NULL, - const wxFont* font = NULL) const; + Most controls will use this to set their initial size, and their min + size to the passed in value (if any.) - /** - Gets the dimensions of the string as it would be drawn on the - window with the currently selected font. + @see SetSize(), GetBestSize(), GetEffectiveMinSize(), + @ref overview_windowsizing */ - wxSize GetTextExtent(const wxString& string) const; + void SetInitialSize(const wxSize& size = wxDefaultSize); /** - Get the associated tooltip or @NULL if none. + 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. + + @see SetMaxSize() */ - wxToolTip* GetToolTip() const; + virtual void SetMaxClientSize(const wxSize& size); /** - Returns the region specifying which parts of the window have been damaged. - Should only be called within an wxPaintEvent handler. + Sets the maximum size of the window, to indicate to the sizer layout mechanism + that this is the maximum possible size. - @see wxRegion, wxRegionIterator + @see SetMaxClientSize() */ - const wxRegion& GetUpdateRegion() const; + virtual void SetMaxSize(const wxSize& size); /** - Returns a pointer to the current validator for the window, or @NULL if - there is none. - */ - virtual wxValidator* GetValidator(); + 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. - //@{ - /** - 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. - */ - wxSize GetVirtualSize() const; + You may need to call this if you change the window size after + construction and before adding to its parent sizer. - /** - Like the other GetVirtualSize() overload but uses pointers instead. + Note, that just as with SetMinSize(), calling this method doesn't + prevent the program from explicitly making the window smaller than the + specified size. - @param width - Receives the window virtual width. - @param height - Receives the window virtual height. + @see SetMinSize() */ - void GetVirtualSize(int* width, int* height) const; - //@} + virtual void SetMinClientSize(const wxSize& size); /** - 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; + Sets the minimum size of the window, to indicate to the sizer layout + mechanism that this is the minimum required size. - //@{ - /** - Gets the window style that was passed to the constructor or Create() - method. GetWindowStyle() is another name for the same function. + 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() */ - virtual long GetWindowStyleFlag() const; - long GetWindowStyle() const; - //@} + virtual void SetMinSize(const wxSize& size); /** - Returns the value previously passed to SetWindowVariant(). + 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). + + @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 Move() */ - wxWindowVariant GetWindowVariant() const; + void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); /** - 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 size of the window in pixels. + The size is specified using a wxRect, wxSize or by a couple of @c int objects. - @return Returns @true if the key pressed was for navigation and was - handled, @false otherwise. + @remarks This form must be used with non-default width and height values. - @see Navigate() + @see Move() */ - bool HandleAsNavigationKey(const wxKeyEvent& event); + virtual void SetSize(const wxRect& rect); /** - Shorthand for: - @code - GetEventHandler()->SafelyProcessEvent(event); - @endcode + @overload */ - bool HandleWindowEvent(wxEvent& event) const; + virtual void SetSize(const wxSize& size); /** - Returns @true if this window has the current mouse capture. - - @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent + @overload */ - virtual bool HasCapture() const; + virtual void SetSize(int width, int height); /** - Returns @true if the window has the given @a exFlag bit set in its - extra styles. + 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 SetExtraStyle() + @see wxTopLevelWindow::SetSizeHints */ - bool HasExtraStyle(int exFlag) const; + void SetSizeHints( const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize, + const wxSize& incSize=wxDefaultSize); /** - Returns @true if the window has the given @a flag bit set. - */ - bool HasFlag(int flag) const; + 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. - /** - Returns @true if the window (or in case of composite controls, its main - child window) has focus. + Note that this function will also call SetAutoLayout() implicitly with @true + parameter if the @a sizer is non-@NULL and @false otherwise. - @see FindFocus() + @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. + + @remarks SetSizer enables and disables Layout automatically. */ - virtual bool HasFocus() const; + void SetSizer(wxSizer* sizer, bool deleteOld = 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. + 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. */ - virtual bool HasMultiplePages() const; + void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); /** - Returns @true if this window has a scroll bar for this orientation. + Sets the virtual size of the window in pixels. + */ + void SetVirtualSize(int width, int height); - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. + /** + @overload */ - bool HasScrollbar(int orient) const; + void SetVirtualSize(const wxSize& size); + + //@} + /** - Returns @true if this window background is transparent (as, for example, - for wxStaticText) and should show the parent window background. + @name Positioning + */ + //@{ - 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. + /** + A synonym for Centre(). */ - virtual bool HasTransparentBackground(); + void Center(int dir = wxBOTH); /** - Equivalent to calling wxWindow::Show(@false). + A synonym for CentreOnParent(). */ - bool Hide(); + void CenterOnParent(int dir = wxBOTH); /** - This function hides a window, like Hide(), but using a special visual - effect if possible. + Centres the window. - The parameters of this function are the same as for ShowWithEffect(), - please see their description there. + @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.9.0 + @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() */ - virtual bool HideWithEffect(wxShowEffect effect, - unsigned int timeout = 0); + void Centre(int direction = wxBOTH); /** - 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. + Centres the window on its parent. This is a more readable synonym for Centre(). - 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. + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. - 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 void InheritAttributes(); + @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); /** - Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data - to the dialog via validators. + 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() */ - virtual void InitDialog(); + void GetPosition(int* x, int* y) const; /** - Resets the cached best size value so it will be recalculated the next time it - is needed. + 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() */ - void InvalidateBestSize(); + wxPoint GetPosition() 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. + Returns the position and size of the window as a wxRect object. - @see wxBufferedDC + @see GetScreenRect() */ - virtual bool IsDoubleBuffered() const; + wxRect GetRect() const; /** - Returns @true if the window is enabled, i.e. if it accepts user input, - @false otherwise. + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - 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() + @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 Enable() + @see GetPosition() */ - bool IsEnabled() const; - - //@{ - /** - 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; - bool IsExposed(wxPoint& pt) const; - bool IsExposed(int x, int y, int w, int h) const; - bool IsExposed(wxRect& rect) const; - //@} - - /** - Returns @true if the window is currently frozen by a call to Freeze(). - - @see Freeze(), Thaw() - */ - bool IsFrozen() const; - - /** - Returns @true if the window is retained, @false otherwise. - - @remarks Retained windows are only available on X platforms. - */ - virtual bool IsRetained() const; - - /** - Return whether a scrollbar is always shown. - - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. - - @see AlwaysShowScrollbars() - */ - virtual bool IsScrollbarAlwaysShown(int orient) const; - - /** - Returns @true if the window is shown, @false if it has been hidden. - - @see IsShownOnScreen() - */ - virtual bool IsShown() const; - - /** - 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. - - @see IsShown() - */ - virtual bool IsShownOnScreen() const; - - /** - 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. - */ - 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). - */ - virtual bool IsTopLevel() const; - - /** - Invokes the constraint-based layout algorithm or the sizer-based algorithm - for this window. - - 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_windowsizing - */ - virtual bool Layout(); + void GetScreenPosition(int* x, int* y) const; /** - Lowers the window to the bottom of the window hierarchy (Z-order). - - @remarks - This function only works for wxTopLevelWindow-derived classes. + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - @see Raise() + @see GetPosition() */ - virtual void Lower(); + wxPoint GetScreenPosition() const; /** - Disables all other windows in the application so that - the user can only interact with this window. + Returns the position and size of the window on the screen as a wxRect object. - @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. + @see GetRect() */ - virtual void MakeModal(bool modal = true); + wxRect GetScreenRect() const; /** Moves the window to the given position. @@ -1580,193 +1249,264 @@ public: */ void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); + //@} + + /** - Moves this window in the tab navigation order after the specified @e win. - This means that when the user presses @c TAB key on that other window, - the focus switches to this window. + @name Coordinate conversion + */ + //@{ - Default tab order is the same as creation order, this function and - MoveBeforeInTabOrder() allow to change - it after creating all the windows. + /** + Converts to screen coordinates from coordinates relative to this window. - @param win - A sibling of this window which should precede it in tab order, - must not be @NULL + @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. + + @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 */ - void MoveAfterInTabOrder(wxWindow* win); + void ClientToScreen(int* x, int* y) const; /** - Same as MoveAfterInTabOrder() except that it inserts this window just - before @a win instead of putting it right after it. + Converts to screen coordinates from coordinates relative to this window. + + @param pt + The client position for the second form of the function. */ - void MoveBeforeInTabOrder(wxWindow* win); + wxPoint ClientToScreen(const wxPoint& pt) const; /** - Performs a keyboard navigation action starting from this window. - This method is equivalent to calling NavigateIn() method on the - parent window. + Converts a point or size from dialog units to pixels. - @param flags - A combination of wxNavigationKeyEvent::IsForward and - wxNavigationKeyEvent::WinChange. + 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 focus was moved to another window or @false - if nothing changed. + @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 You may wish to call this from a text control custom keypress - handler to do the default navigation behaviour for the - tab key, since the standard default behaviour for a - multiline text control with the wxTE_PROCESS_TAB style - is to insert a tab and not navigate to the next - control. See also wxNavigationKeyEvent and - HandleAsNavigationKey. + @see ConvertPixelsToDialog() */ - bool Navigate(int flags = IsForward); + wxPoint ConvertDialogToPixels(const wxPoint& pt); /** - Performs a keyboard navigation action inside this window. - See Navigate() for more information. + @overload */ - bool NavigateIn(int flags = IsForward); + wxSize ConvertDialogToPixels(const wxSize& sz); /** - 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(). + Converts a point or size from pixels to dialog units. - See @ref overview_windowids for more information. + 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 count - The number of sequential IDs to reserve. + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. - @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 ConvertDialogToPixels() + */ + wxPoint ConvertPixelsToDialog(const wxPoint& pt); - @see UnreserveControlId(), wxIdManager, - @ref overview_windowids + /** + @overload */ - static wxWindowID NewControlId(int count = 1); + wxSize ConvertPixelsToDialog(const wxSize& sz); /** - 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. + Converts from screen to client window coordinates. - 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. + @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. */ - virtual void OnInternalIdle(); + void ScreenToClient(int* x, int* y) const; /** - Same as #ScrollLines (-1). + Converts from screen to client window coordinates. + + @param pt + The screen position. */ - bool LineUp(); + wxPoint ScreenToClient(const wxPoint& pt) const; + + //@} + /** - Same as #ScrollLines (1). + @name Drawing-related functions */ - bool LineDown(); + //@{ /** - Same as #ScrollPages (-1). + Clears the window by filling it with the current background colour. Does not + cause an erase background event to be generated. */ - bool PageUp(); + virtual void ClearBackground(); /** - Same as #ScrollPages (1). - */ - bool PageDown(); + 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. - /** - Removes and returns the top-most event handler on the event handler stack. + If the window has any children, they are recursively frozen too. - @param deleteHandler - If this is @true, the handler will be deleted after it is removed. - The default value is @false. + 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 SetEventHandler(), GetEventHandler(), - PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @see wxWindowUpdateLocker, Thaw(), IsFrozen() */ - wxEvtHandler* PopEventHandler(bool deleteHandler = false); + void Freeze(); - //@{ /** - Pops up the given menu at the specified coordinates, relative to this - window, and returns control when the user has dismissed the menu. + Reenables window updating after a previous call to Freeze(). - 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. + To really thaw the control, it must be called exactly the same number + of times as Freeze(). - @a menu is the menu to pop up. + If the window has any children, they are recursively thawn too. - 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). + @see wxWindowUpdateLocker, Freeze(), IsFrozen() + */ + void Thaw(); - @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. + /** + Returns @true if the window is currently frozen by a call to Freeze(). - @see wxMenu + @see Freeze(), Thaw() */ - bool PopupMenu(wxMenu* menu, - const wxPoint& pos = wxDefaultPosition); - bool PopupMenu(wxMenu* menu, int x, int y); - //@} + bool IsFrozen() const; /** - Posts a size event to the window. + Returns the background colour of the window. - This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument. - */ - void PostSizeEvent(); + @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour() + */ + wxColour GetBackgroundColour() const; /** - Posts a size event to the parent of this window. + Returns the background style of the window. + The background style can be one of the wxBackgroundStyle. - This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST - argument. - */ - void PostSizeEventToParent(); + @see SetBackgroundColour(), GetForegroundColour(), + SetBackgroundStyle(), SetTransparent() + */ + virtual wxBackgroundStyle GetBackgroundStyle() const; + /** + Returns the character height for this window. + */ + virtual int GetCharHeight() const; /** - Pushes this event handler onto the event stack for the window. + Returns the average character width for this window. + */ + virtual int GetCharWidth() const; - @param handler - Specifies the handler to be pushed. + /** + Currently this is the same as calling + wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). - @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. + 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 SetEventHandler(), GetEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + 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 PushEventHandler(wxEvtHandler* handler); + virtual wxVisualAttributes GetDefaultAttributes() const; /** - Raises the window to the top of the window hierarchy (Z-order). + Returns the font for this window. - @remarks - This function only works for wxTopLevelWindow-derived classes. + @see SetFont() + */ + wxFont GetFont() const; - @see Lower() + /** + 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() */ - virtual void Raise(); + wxColour GetForegroundColour() const; + + /** + Gets the dimensions of the string as it would be drawn on the + window with the currently selected font. + + The text extent is returned in @a w and @a h pointers. + + @param string + String whose extent is to be measured. + @param w + Return value for width. + @param h + Return value for height. + @param descent + Return value for descent (optional). + @param externalLeading + Return value for external leading (optional). + @param font + Font to use instead of the current window font (optional). + */ + virtual void GetTextExtent(const wxString& string, int* w, int* h, + int* descent = NULL, + int* externalLeading = NULL, + const wxFont* font = NULL) const; + + /** + 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; + + /** + Returns the region specifying which parts of the window have been damaged. + Should only be called within an wxPaintEvent handler. + + @see wxRegion, wxRegionIterator + */ + 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 @@ -1794,349 +1534,306 @@ public: void RefreshRect(const wxRect& rect, bool eraseBackground = true); /** - Registers a system wide hotkey. Every time the user presses the hotkey - registered here, this window will receive a hotkey event. + 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. - 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. + 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(); - @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. + /** + Sets the background colour of the window. + Please see InheritAttributes() for explanation of the difference between + this method and SetOwnBackgroundColour(). - @return @true if the hotkey was registered successfully. @false if some - other application already registered a hotkey with this - modifier/virtualKeyCode combination. + @param colour + The colour to be used as the background colour, pass + wxNullColour to reset to the default colour. - @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. + @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 UnregisterHotKey() + @see GetBackgroundColour(), SetForegroundColour(), + GetForegroundColour(), ClearBackground(), + Refresh(), wxEraseEvent */ - virtual bool RegisterHotKey(int hotkeyId, int modifiers, - int virtualKeyCode); + virtual bool SetBackgroundColour(const wxColour& colour); /** - Releases mouse input captured with CaptureMouse(). + Sets the background style of the window. see GetBackgroundStyle() for + the description of the possible style values. - @see CaptureMouse(), HasCapture(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + @see SetBackgroundColour(), GetForegroundColour(), + SetTransparent() */ - void ReleaseMouse(); + virtual bool SetBackgroundStyle(wxBackgroundStyle style); /** - Removes a child window. + 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. - 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. + 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 child - Child window to remove. + @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. + + @see GetFont(), InheritAttributes() */ - virtual void RemoveChild(wxWindow* child); + virtual bool SetFont(const wxFont& font); /** - Find the given @a handler in the windows event handler chain and remove - (but not delete) it from it. + Sets the foreground colour of the window. + Please see InheritAttributes() for explanation of the difference between + this method and SetOwnForegroundColour(). - @param handler - The event handler to remove, must be non-@NULL and - must be present in this windows event handlers chain + @param colour + The colour to be used as the foreground colour, pass + wxNullColour to reset to the default colour. - @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). + @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 PushEventHandler(), PopEventHandler() + @see GetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour(), ShouldInheritColours() */ - bool RemoveEventHandler(wxEvtHandler* handler); + virtual bool SetForegroundColour(const wxColour& colour); /** - 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. + Sets the background colour of the window but prevents it from being inherited + by the children of this window. - @param newParent - New parent. + @see SetBackgroundColour(), InheritAttributes() */ - virtual bool Reparent(wxWindow* newParent); + void SetOwnBackgroundColour(const wxColour& colour); /** - Converts from screen to client window coordinates. + Sets the font of the window but prevents it from being inherited by the + children of this 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. + @see SetFont(), InheritAttributes() */ - void ScreenToClient(int* x, int* y) const; + void SetOwnFont(const wxFont& font); /** - Converts from screen to client window coordinates. + Sets the foreground colour of the window but prevents it from being inherited + by the children of this window. - @param pt - The screen position. + @see SetForegroundColour(), InheritAttributes() */ - wxPoint ScreenToClient(const wxPoint& pt) const; + void SetOwnForegroundColour(const wxColour& colour); /** - Scrolls the window by the given number of lines down (if @a lines is - positive) or up. - - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. - - @remarks This function is currently only implemented under MSW and - wxTextCtrl under wxGTK (it also works for wxScrolled classes - under all platforms). - - @see ScrollPages() + @deprecated use wxDC::SetPalette instead. */ - virtual bool ScrollLines(int lines); + void SetPalette(const wxPalette& pal); /** - Scrolls the window by the given number of pages down (if @a pages is - positive) or up. - - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. - - @remarks This function is currently only implemented under MSW and wxGTK. + 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 ScrollLines() + The base class version returns @false, but this method is overridden in + wxControl where it returns @true. */ - virtual bool ScrollPages(int pages); + virtual bool ShouldInheritColours() const; /** - Physically scrolls the pixels in the window and move child windows accordingly. + 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. - @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) + 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 void SetThemeEnabled(bool enable); - @remarks Note that you can often use wxScrolled instead of using this - function directly. + /** + 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. */ - virtual void ScrollWindow(int dx, int dy, - const wxRect* rect = NULL); + virtual bool CanSetTransparent(); /** - This function sends a dummy @ref wxSizeEvent "size event" to - the window allowing it to re-layout its children positions. + 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(). - 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 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 SetTransparent(wxByte alpha); - 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. + //@} - @param flags - May include @c wxSEND_EVENT_POST. Default value is 0. + + /** + @name Event-handling functions */ - virtual void SendSizeEvent(int flags = 0); + //@{ /** - Safe wrapper for GetParent()->SendSizeEvent(). + Returns the event handler for this window. + By default, the window is its own event handler. - 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). + @see SetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + wxEvtHandler* GetEventHandler() const; - @see PostSizeEventToParent() + /** + 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. - @param flags - See description of this parameter in SendSizeEvent() documentation. - */ - void SendSizeEventToParent(int flags = 0); + @return Returns @true if the key pressed was for navigation and was + handled, @false otherwise. - /** - Sets the accelerator table for this window. See wxAcceleratorTable. + @see Navigate() */ - virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + bool HandleAsNavigationKey(const wxKeyEvent& event); /** - 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. + Shorthand for: + @code + GetEventHandler()->SafelyProcessEvent(event); + @endcode */ - void SetAccessible(wxAccessible* accessible); + bool HandleWindowEvent(wxEvent& event) const; /** - 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). - - 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. + Removes and returns the top-most event handler on the event handler stack. - @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). + @param deleteHandler + If this is @true, the handler will be deleted after it is removed. + The default value is @false. - @see SetConstraints() + @see SetEventHandler(), GetEventHandler(), + PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ - void SetAutoLayout(bool autoLayout); + wxEvtHandler* PopEventHandler(bool deleteHandler = false); /** - Sets the background colour of the window. - Please see InheritAttributes() for explanation of the difference between - this method and SetOwnBackgroundColour(). + Pushes this event handler onto the event stack for the window. - @param colour - The colour to be used as the background colour, pass - wxNullColour to reset to the default colour. + @param handler + Specifies the handler to be pushed. - @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. + @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 GetBackgroundColour(), SetForegroundColour(), - GetForegroundColour(), ClearBackground(), - Refresh(), wxEraseEvent + @see SetEventHandler(), GetEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ - virtual bool SetBackgroundColour(const wxColour& colour); + void PushEventHandler(wxEvtHandler* handler); /** - Sets the background style of the window. see GetBackgroundStyle() for - the description of the possible style values. + Find the given @a handler in the windows event handler chain and remove + (but not delete) it from it. - @see SetBackgroundColour(), GetForegroundColour(), - SetTransparent() + @param handler + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers chain + + @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 SetBackgroundStyle(wxBackgroundStyle style); + bool RemoveEventHandler(wxEvtHandler* handler); /** - This method is only implemented by ports which have support for - native TAB traversal (such as GTK+ 2.0). + Sets the event handler for this window. - 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(). + @param handler + Specifies the handler to be set. - @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + @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 */ - virtual void SetCanFocus(bool canFocus); + void SetEventHandler(wxEvtHandler* handler); + + //@} + /** - Sets the caret() associated with the window. + @name Window styles */ - void SetCaret(wxCaret* caret); - //@{ + /** - 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. - */ - virtual void SetClientSize(int width, int height); - virtual void SetClientSize(const wxSize& size); - //@} - - /** - 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. - - @param constraints - The constraints to set. Pass @NULL to disassociate and delete the window's - constraints. - - @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. + Returns the extra style bits for the window. */ - void SetConstraints(wxLayoutConstraints* constraints); + long GetExtraStyle() 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. + Gets the window style that was passed to the constructor or Create() + method. GetWindowStyle() is another name for the same function. */ - void SetContainingSizer(wxSizer* sizer); + virtual long GetWindowStyleFlag() 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. - - @param cursor - Specifies the cursor that the window should normally display. - - @see ::wxSetCursor, wxCursor + See GetWindowStyleFlag() for more info. */ - virtual bool SetCursor(const wxCursor& cursor); + long GetWindowStyle() const; /** - Associates a drop target with this window. - If the window already has a drop target, it is deleted. + Returns @true if the window has the given @a exFlag bit set in its + extra styles. - @see GetDropTarget(), @ref overview_dnd + @see SetExtraStyle() */ - virtual void SetDropTarget(wxDropTarget* target); + bool HasExtraStyle(int exFlag) const; /** - Sets the event handler for this window. - - @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 + Returns @true if the window has the given @a flag bit set. */ - void SetEventHandler(wxEvtHandler* handler); + bool HasFlag(int flag) const; /** Sets the extra style bits for the window. @@ -2146,496 +1843,1005 @@ public: virtual void SetExtraStyle(long exStyle); /** - This sets the window to receive keyboard input. - - @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, - wxPanel::SetFocusIgnoringChildren - */ - virtual void SetFocus(); + 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. - /** - 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). + See @ref overview_windowstyles "Window styles" for more information about flags. - By default this method simply calls SetFocus() but - can be overridden to do something in addition to this in the derived classes. + @see GetWindowStyleFlag() */ - virtual void SetFocusFromKbd(); + virtual void SetWindowStyleFlag(long style); /** - 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(). + See SetWindowStyleFlag() for more info. + */ + void SetWindowStyle(long style); - @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. - @see GetFont(), InheritAttributes() + /** + @name Tab order */ - virtual bool SetFont(const wxFont& font); + //@{ /** - Sets the foreground colour of the window. - Please see InheritAttributes() for explanation of the difference between - this method and SetOwnForegroundColour(). - - @param colour - The colour to be used as the foreground colour, pass - wxNullColour to reset to the default colour. + Moves this window in the tab navigation order after the specified @e win. + This means that when the user presses @c TAB key on that other window, + the focus switches to this 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. + Default tab order is the same as creation order, this function and + MoveBeforeInTabOrder() allow to change + it after creating all the windows. - @see GetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour(), ShouldInheritColours() + @param win + A sibling of this window which should precede it in tab order, + must not be @NULL */ - virtual bool SetForegroundColour(const wxColour& colour); + void MoveAfterInTabOrder(wxWindow* win); /** - 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. - - @see GetHelpText(), wxHelpProvider::AddHelp() + Same as MoveAfterInTabOrder() except that it inserts this window just + before @a win instead of putting it right after it. */ - void SetHelpText(const wxString& helpText); + void MoveBeforeInTabOrder(wxWindow* win); /** - Sets the identifier of the window. + Performs a keyboard navigation action starting from this window. + This method is equivalent to calling NavigateIn() method on the + parent 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. + @param flags + A combination of wxNavigationKeyEvent::IsForward and + wxNavigationKeyEvent::WinChange. - @see GetId(), @ref overview_windowids + @return Returns @true if the focus was moved to another window or @false + if nothing changed. + + @remarks You may wish to call this from a text control custom keypress + handler to do the default navigation behaviour for the + tab key, since the standard default behaviour for a + multiline text control with the wxTE_PROCESS_TAB style + is to insert a tab and not navigate to the next + control. See also wxNavigationKeyEvent and + HandleAsNavigationKey. */ - void SetId(wxWindowID winid); + bool Navigate(int flags = IsForward); /** - A @e smart SetSize that will fill in default size components with the - window's @e best size values. + Performs a keyboard navigation action inside this window. + See Navigate() for more information. + */ + bool NavigateIn(int flags = IsForward); - 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. + //@} - Most controls will use this to set their initial size, and their min - size to the passed in value (if any.) - @see SetSize(), GetBestSize(), GetEffectiveMinSize(), - @ref overview_windowsizing + + /** + @name Z-order */ - void SetInitialSize(const wxSize& size = wxDefaultSize); + //@{ /** - Sets the window's label. + Lowers the window to the bottom of the window hierarchy (Z-order). - @param label - The window label. + @remarks + This function only works for wxTopLevelWindow-derived classes. - @see GetLabel() + @see Raise() */ - virtual void SetLabel(const wxString& label); + virtual void Lower(); /** - 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. + Raises the window to the top of the window hierarchy (Z-order). - @see SetMaxSize() + @remarks + This function only works for wxTopLevelWindow-derived classes. + + @see Lower() */ - virtual void SetMaxClientSize(const wxSize& size); + virtual void Raise(); - /** - Sets the maximum size of the window, to indicate to the sizer layout mechanism - that this is the maximum possible size. + //@} - @see SetMaxClientSize() - */ - virtual void SetMaxSize(const wxSize& size); /** - 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. - - You may need to call this if you change the window size after - construction and before adding to its parent sizer. + @name Show/hide, enable/disable functions + */ + //@{ - 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 SetMinSize() + /** + Equivalent to calling wxWindow::Show(@false). */ - virtual void SetMinClientSize(const wxSize& size); + bool Hide(); /** - Sets the minimum size of the window, to indicate to the sizer layout - mechanism that this is the minimum required size. - - You may need to call this if you change the window size after - construction and before adding to its parent sizer. + This function hides a window, like Hide(), but using a special visual + effect if possible. - 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. + The parameters of this function are the same as for ShowWithEffect(), + please see their description there. - @see SetMinClientSize() + @since 2.9.0 */ - virtual void SetMinSize(const wxSize& size); - + virtual bool HideWithEffect(wxShowEffect effect, + unsigned int timeout = 0); /** - Sets the window's name. + Returns @true if the window is enabled, i.e. if it accepts user input, + @false otherwise. - @param name - A name to set for the window. + 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() - @see GetName() + @see Enable() */ - virtual void SetName(const wxString& name); + bool IsEnabled() const; /** - Sets the background colour of the window but prevents it from being inherited - by the children of this window. + 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; - @see SetBackgroundColour(), InheritAttributes() + /** + @overload */ - void SetOwnBackgroundColour(const wxColour& colour); + bool IsExposed(wxPoint& pt) const; /** - Sets the font of the window but prevents it from being inherited by the - children of this window. + @overload + */ + bool IsExposed(int x, int y, int w, int h) const; - @see SetFont(), InheritAttributes() + /** + @overload */ - void SetOwnFont(const wxFont& font); + bool IsExposed(wxRect& rect) const; + /** + Returns @true if the window is shown, @false if it has been hidden. + + @see IsShownOnScreen() + */ + virtual bool IsShown() const; /** - Sets the foreground colour of the window but prevents it from being inherited - by the children 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. - @see SetForegroundColour(), InheritAttributes() + @see IsShown() */ - void SetOwnForegroundColour(const wxColour& colour); + virtual bool IsShownOnScreen() const; /** - @deprecated use wxDC::SetPalette instead. + Disables the window. Same as @ref Enable() Enable(@false). + + @return Returns @true if the window has been disabled, @false if it had + been already disabled before the call to this function. */ - void SetPalette(const wxPalette& pal); + bool Disable(); /** - Sets the position of one of the built-in scrollbars. + 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 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. + @param enable + If @true, enables the window for input. If @false, disables the window. - @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. + @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 SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, - wxScrolled + @see IsEnabled(), Disable(), wxRadioBox::Enable */ - virtual void SetScrollPos(int orientation, int pos, - bool refresh = true); + virtual bool Enable(bool enable = true); /** - Sets the scrollbar properties of a built-in scrollbar. + 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 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. + @param show + If @true displays the window. Otherwise, hides it. - @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. + @return @true if the window has been shown or hidden or @false if nothing + was done because it already was in the requested state. - @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent + @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. */ - virtual void SetScrollbar(int orientation, int position, - int thumbSize, int range, - bool refresh = true); + virtual bool Show(bool show = true); /** - Sets the size of the window in pixels. + This function shows a window, like Show(), but using a special visual + effect if possible. - @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). + @param effect + The effect to use. - @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. + @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. - @see Move() + @note Currently this function is only implemented in wxMSW and does the + same thing as Show() in the other ports. + + @since 2.9.0 + + @see HideWithEffect() */ - void SetSize(int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO); + virtual bool ShowWithEffect(wxShowEffect effect, + unsigned int timeout = 0); + + //@} + + // NOTE: static functions must have their own group or Doxygen will screw + // up the ordering of the member groups + + /** + @name Static functions + */ //@{ + /** - Sets the size of the window in pixels. - The size is specified using a wxRect, wxSize or by a couple of @c int objects. + Returns the default font and colours which are used by the control. - @remarks This form must be used with non-default width and height values. + 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. - @see Move() + 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 void SetSize(const wxRect& rect); - virtual void SetSize(const wxSize& size); - virtual void SetSize(int width, int height); - //@} + static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); + + /** + Finds the window or control which currently has the keyboard focus. + + @remarks Note that this is a static function, so it can be called without + needing a wxWindow pointer. + + @see SetFocus(), HasFocus() + */ + 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); + + //@} + + + /** + @name Tooltip functions + */ + //@{ + + /** + Get the associated tooltip or @NULL if none. + */ + wxToolTip* GetToolTip() const; + + /** + Attach a tooltip to the window. + + 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 SetToolTip(const wxString& tip); + + /** + @overload + */ + void SetToolTip(wxToolTip* tip); + + /** + Unset any existing tooltip. + + @since 2.9.0 + + @see SetToolTip() + */ + void UnsetToolTip(); + + //@} + + + /** + @name Popup/context menu functions + */ + //@{ + + /** + 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. + + 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. + + 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. + + @return + The selected menu item id or @c wxID_NONE if none selected or an + error occurred. + + @since 2.9.0 + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); + + /** + @overload + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); + + /** + Pops up the given menu at the specified coordinates, relative to this + window, and returns control when the user has dismissed the menu. + + 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. + + @a menu is the menu to pop up. + + 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 + */ + bool PopupMenu(wxMenu* menu, + const wxPoint& pos = wxDefaultPosition); + + /** + @overload + */ + bool PopupMenu(wxMenu* menu, int x, int y); + + //@} + + + + /** + @name Miscellaneous functions + */ + //@{ + + /** + Directs all mouse input to this window. + Call ReleaseMouse() to release the capture. + + 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. + + 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. + + @see ReleaseMouse(), wxMouseCaptureLostEvent + */ + void CaptureMouse(); + + /** + 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 @ref overview_windowdeletion "Window Deletion Overview", + Destroy(), wxCloseEvent + */ + bool Close(bool force = false); + + /** + 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. + + @return @true if the window has either been successfully deleted, or it + has been added to the list of windows pending real deletion. + */ + virtual bool Destroy(); + + /** + Returns true if this window is in process of being destroyed. + + 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. + + 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; + + /** + 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: + + @code + // do the window-specific processing after processing the update event + void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) + { + if ( event.GetSetEnabled() ) + Enable(event.GetEnabled()); + + if ( event.GetSetText() ) + { + if ( event.GetText() != GetTitle() ) + SetTitle(event.GetText()); + } + } + @endcode + */ + virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); + + /** + Enables or disables eligibility for drop file events (OnDropFiles). + + @param accept + If @true, the window is eligible for drop file events. + If @false, the window will not accept drop file events. + + @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 SetDropTarget() + */ + virtual void DragAcceptFiles(bool accept); + + /** + Gets the accelerator table for this window. See wxAcceleratorTable. + */ + wxAcceleratorTable* GetAcceleratorTable(); + + /** + Returns the accessible object for this window, if any. + See also wxAccessible. + */ + wxAccessible* GetAccessible(); + + /** + Returns the caret() associated with the window. + */ + wxCaret* GetCaret() const; + + /** + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints() const; + + /** + Return the cursor associated with this window. + + @see SetCursor() + */ + const wxCursor& GetCursor() const; + + /** + Returns the associated drop target, which may be @NULL. + + @see SetDropTarget(), @ref overview_dnd + */ + virtual wxDropTarget* GetDropTarget() 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. + */ + virtual WXWidget GetHandle() 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. + + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + */ + wxString GetHelpText() 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. + + @param point + Coordinates of the mouse at the moment of help event emission. + @param origin + Help event origin, see also wxHelpEvent::GetOrigin. + */ + virtual wxString GetHelpTextAtPoint(const wxPoint& point, + wxHelpEvent::Origin origin) 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. + + @see SetId(), @ref overview_windowids + */ + wxWindowID GetId() const; + + /** + Generic way of getting a label from any window, for + identification purposes. + + @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 wxString GetLabel() 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(). + + @see SetName() + */ + virtual wxString GetName() const; + + /** + Returns a pointer to the current validator for the window, or @NULL if + there is none. + */ + virtual wxValidator* GetValidator(); + + /** + Returns the value previously passed to SetWindowVariant(). + */ + wxWindowVariant GetWindowVariant() const; + + /** + Returns @true if this window has the current mouse capture. + + @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent + */ + virtual bool HasCapture() 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. + */ + virtual bool HasMultiplePages() 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. + + 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. + + 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 void InheritAttributes(); + + /** + Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data + to the dialog via validators. + */ + virtual void InitDialog(); + + /** + 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 wxBufferedDC + */ + virtual bool IsDoubleBuffered() const; + + /** + Returns @true if the window is retained, @false otherwise. + + @remarks Retained windows are only available on X platforms. + */ + virtual bool IsRetained() const; + + /** + 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. + */ + 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). + */ + virtual bool IsTopLevel() const; + + /** + Invokes the constraint-based layout algorithm or the sizer-based algorithm + for this window. + + 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_windowsizing + */ + virtual bool Layout(); + + /** + Disables all other windows in the application so that + the user can only interact with this window. + + @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. + */ + virtual void MakeModal(bool modal = true); + + /** + This virtual function is normally only used internally, but + sometimes an application may need it to implement functionality + that should not be disabled by an application defining an OnIdle + handler in a derived class. + + This function may be used to do delayed painting, for example, + and most implementations call UpdateWindowUI() + in order to send update events to the window in idle time. + */ + virtual void OnInternalIdle(); + + /** + Registers a system wide hotkey. Every time the user presses the hotkey + registered here, this window will receive a hotkey event. + + It will receive the event even if the application is in the background + and does not have the input focus because the user is working with some + other application. + + @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. - /** - Use of this function for windows which are not toplevel windows - (such as wxDialog or wxFrame) is discouraged. - Please use SetMinSize() and SetMaxSize() instead. + @return @true if the hotkey was registered successfully. @false if some + other application already registered a hotkey with this + modifier/virtualKeyCode combination. - @see wxTopLevelWindow::SetSizeHints + @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() */ - void SetSizeHints( const wxSize& minSize, - const wxSize& maxSize=wxDefaultSize, - const wxSize& incSize=wxDefaultSize); + virtual bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); /** - 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. - - Note that this function will also call SetAutoLayout() implicitly with @true - parameter if the @a sizer is non-@NULL and @false otherwise. - - @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. + Releases mouse input captured with CaptureMouse(). - @remarks SetSizer enables and disables Layout automatically. + @see CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent */ - void SetSizer(wxSizer* sizer, bool deleteOld = true); + void ReleaseMouse(); /** - 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. + Sets the accelerator table for this window. See wxAcceleratorTable. */ - void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); /** - 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. + 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. */ - virtual void SetThemeEnabled(bool enable); + void SetAccessible(wxAccessible* accessible); - //@{ /** - Attach a tooltip to the window. + 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). - 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. + 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. - 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. + @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 GetToolTip(), wxToolTip + @see SetConstraints() */ - void SetToolTip(const wxString& tip); - void SetToolTip(wxToolTip* tip); - //@} + void SetAutoLayout(bool autoLayout); /** - 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. - */ - virtual void SetValidator(const wxValidator& validator); + 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. - //@{ - /** - Sets the virtual size of the window in pixels. + @param constraints + The constraints to set. Pass @NULL to disassociate and delete the window's + constraints. + + @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. */ - void SetVirtualSize(int width, int height); - void SetVirtualSize(const wxSize& size); - //@} + void SetConstraints(wxLayoutConstraints* constraints); - //@{ /** - 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. + Sets the window's cursor. Notice that the window cursor also sets it for the + children of the window implicitly. - See @ref overview_windowstyles "Window styles" for more information about flags. + The @a cursor may be @c wxNullCursor in which case the window cursor will + be reset back to default. - @see GetWindowStyleFlag() + @param cursor + Specifies the cursor that the window should normally display. + + @see ::wxSetCursor, wxCursor */ - virtual void SetWindowStyleFlag(long style); - void SetWindowStyle(long style); - //@} + virtual bool SetCursor(const wxCursor& cursor); /** - 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. + Associates a drop target with this window. + If the window already has a drop target, it is deleted. - By default the controls use the normal size, of course, but this function can - be used to change this. + @see GetDropTarget(), @ref overview_dnd */ - void SetWindowVariant(wxWindowVariant variant); + virtual void SetDropTarget(wxDropTarget* target); /** - 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. + 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. - The base class version returns @false, but this method is overridden in - wxControl where it returns @true. + @see GetHelpText(), wxHelpProvider::AddHelp() */ - virtual bool ShouldInheritColours() const; + void SetHelpText(const wxString& helpText); /** - 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. + Sets the identifier of the window. - @return @true if the window has been shown or hidden or @false if nothing - was done because it already was in the requested state. + @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 IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. + @see GetId(), @ref overview_windowids */ - virtual bool Show(bool show = true); + void SetId(wxWindowID winid); /** - This function shows a window, like Show(), but using a special visual - effect if possible. + Sets the window's label. - @param effect - The effect to use. + @param label + The window label. - @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. + @see GetLabel() + */ + virtual void SetLabel(const wxString& label); - @note Currently this function is only implemented in wxMSW and does the - same thing as Show() in the other ports. + /** + Sets the window's name. - @since 2.9.0 + @param name + A name to set for the window. - @see HideWithEffect() + @see GetName() */ - virtual bool ShowWithEffect(wxShowEffect effect, - unsigned int timeout = 0); + virtual void SetName(const wxString& name); /** - 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(). + 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); - If the window has any children, they are recursively thawn too. + /** + 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 wxWindowUpdateLocker, Freeze(), IsFrozen() + By default the controls use the normal size, of course, but this function can + be used to change this. */ - void Thaw(); + void SetWindowVariant(wxWindowVariant variant); /** Turns the given @a flag on if it's currently turned off and vice versa. @@ -2692,40 +2898,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 @@ -2784,6 +2956,7 @@ public: */ virtual void WarpPointer(int x, int y); + //@} protected: -- 2.45.2