X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b21126db7a8232fa9e64b29f916d73d6b0153bef..232b2162776e08c0b16d5280b90f5c075f38c667:/interface/wx/window.h diff --git a/interface/wx/window.h b/interface/wx/window.h index 039d34c1f3..03eb0a6894 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 functions */ - 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 functions - 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, wxWindow* parent = NULL); + 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, - wxWindow* parent = NULL); + 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, - wxWindow* parent = NULL); + virtual wxSize WindowToClientSize(const wxSize& size) const; /** Sizes the window so that it fits around its subwindows. @@ -720,54 +715,7 @@ 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. + This functions returns the best acceptable minimal size for the window. For example, for a static control, it will be the minimal size such that the control label is not truncated. For windows containing subwindows (typically @@ -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,522 +794,393 @@ 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() + Resets the cached best size value so it will be recalculated the next time it + is needed. */ - wxPoint GetPosition() const; - + void InvalidateBestSize(); /** - 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 + Posts a size event to the window. - @see GetNextSibling() - */ - wxWindow* GetPrevSibling() const; + This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument. + */ + void PostSizeEvent(); /** - Returns the position and size of the window as a wxRect object. + Posts a size event to the parent of this window. - @see GetScreenRect() - */ - wxRect GetRect() const; + This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST + argument. + */ + void PostSizeEventToParent(); /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. + This function sends a dummy @ref wxSizeEvent "size event" to + the window allowing it to re-layout its children positions. - @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. + 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. - @see GetPosition() + 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. */ - void GetScreenPosition(int* x, int* y) const; + virtual void SendSizeEvent(int flags = 0); /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. + Safe wrapper for GetParent()->SendSizeEvent(). - @see GetPosition() - */ - wxPoint GetScreenPosition() 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 position and size of the window on the screen as a wxRect object. + @see PostSizeEventToParent() - @see GetRect() - */ - wxRect GetScreenRect() const; + @param flags + See description of this parameter in SendSizeEvent() documentation. + */ + void SendSizeEventToParent(int flags = 0); /** - Returns the built-in scrollbar position. + This sets the size of the window client area in pixels. - @see See SetScrollbar() + 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 int GetScrollPos(int orientation) const; + virtual void SetClientSize(int width, int height); /** - Returns the built-in scrollbar range. - - @see SetScrollbar() + @overload */ - virtual int GetScrollRange(int orientation) const; + virtual void SetClientSize(const wxSize& size); /** - Returns the built-in scrollbar thumb size. - - @see SetScrollbar() + 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. */ - virtual int GetScrollThumb(int orientation) const; + void SetContainingSizer(wxSizer* sizer); /** - Returns the size of the entire window in pixels, including title bar, border, - scrollbars, etc. + A @e smart SetSize that will fill in default size components with the + window's @e best size values. - 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. + 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 width - Receives the window width. - @param height - Receives the window height. + Most controls will use this to set their initial size, and their min + size to the passed in value (if any.) - @see GetClientSize(), GetVirtualSize() + @see SetSize(), GetBestSize(), GetEffectiveMinSize(), + @ref overview_windowsizing */ - void GetSize(int* width, int* height) const; + void SetInitialSize(const wxSize& size = wxDefaultSize); /** - See the GetSize(int*,int*) overload for more info. - */ - wxSize GetSize() const; + 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. - /** - Return the sizer associated with the window by a previous call to - SetSizer() or @NULL. + @see SetMaxSize() */ - wxSizer* GetSizer() const; + virtual void SetMaxClientSize(const wxSize& size); /** - 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. + Sets the maximum size of the window, to indicate to the sizer layout mechanism + that this is the maximum possible size. - @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). + @see SetMaxClientSize() */ - virtual void GetTextExtent(const wxString& string, int* w, int* h, - int* descent = NULL, - int* externalLeading = NULL, - const wxFont* font = NULL) const; + virtual void SetMaxSize(const wxSize& size); /** - 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; + 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. - /** - Get the associated tooltip or @NULL if none. - */ - wxToolTip* GetToolTip() const; + You may need to call this if you change the window size after + construction and before adding to its parent sizer. - /** - Returns the region specifying which parts of the window have been damaged. - Should only be called within an wxPaintEvent handler. + 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 wxRegion, wxRegionIterator + @see SetMinSize() */ - const wxRegion& GetUpdateRegion() const; + virtual void SetMinClientSize(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 size of the window, to indicate to the sizer layout + mechanism that this is the minimum required size. - //@{ - /** - 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. + 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() */ - wxSize GetVirtualSize() const; + virtual void SetMinSize(const wxSize& size); /** - Like the other GetVirtualSize() overload but uses pointers instead. + Sets the size of the window in pixels. - @param width - Receives the window virtual width. + @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 - Receives the window virtual 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() */ - void GetVirtualSize(int* width, int* height) const; - //@} + void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); /** - Returns the size of the left/right and top/bottom borders of this window in x - and y components of the result respectively. + Sets the size of the window in pixels. + The size is specified using a wxRect, wxSize or by a couple of @c int objects. + + @remarks This form must be used with non-default width and height values. + + @see Move() */ - virtual wxSize GetWindowBorderSize() const; + virtual void SetSize(const wxRect& rect); - //@{ /** - Gets the window style that was passed to the constructor or Create() - method. GetWindowStyle() is another name for the same function. + @overload */ - virtual long GetWindowStyleFlag() const; - long GetWindowStyle() const; - //@} + virtual void SetSize(const wxSize& size); /** - Returns the value previously passed to SetWindowVariant(). + @overload */ - wxWindowVariant GetWindowVariant() const; + virtual void SetSize(int width, int height); /** - 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. - - @return Returns @true if the key pressed was for navigation and was - handled, @false otherwise. + 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 Navigate() + @see wxTopLevelWindow::SetSizeHints */ - bool HandleAsNavigationKey(const wxKeyEvent& event); + void SetSizeHints( const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize, + const wxSize& incSize=wxDefaultSize); /** - Shorthand for: - @code - GetEventHandler()->SafelyProcessEvent(event); - @endcode + Sets the virtual size of the window in pixels. */ - bool HandleWindowEvent(wxEvent& event) const; + void SetVirtualSize(int width, int height); /** - Returns @true if this window has the current mouse capture. - - @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent + @overload */ - virtual bool HasCapture() const; + void SetVirtualSize(const wxSize& size); - /** - Returns @true if the window has the given @a exFlag bit set in its - extra styles. + //@} - @see SetExtraStyle() - */ - bool HasExtraStyle(int exFlag) const; /** - Returns @true if the window has the given @a flag bit set. + @name Positioning functions */ - bool HasFlag(int flag) const; + //@{ /** - Returns @true if the window (or in case of composite controls, its main - child window) has focus. - - @see FindFocus() + A synonym for Centre(). */ - virtual bool HasFocus() const; + void Center(int dir = wxBOTH); /** - 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. + A synonym for CentreOnParent(). */ - virtual bool HasMultiplePages() const; + void CenterOnParent(int dir = wxBOTH); /** - Returns @true if this window has a scroll bar for this orientation. + Centres the window. - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. - */ - bool HasScrollbar(int orient) 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. - /** - Returns @true if this window background is transparent (as, for example, - for wxStaticText) and should show the parent window background. + @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 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. + @see Center() */ - virtual bool HasTransparentBackground(); + void Centre(int direction = wxBOTH); /** - Equivalent to calling wxWindow::Show(@false). - */ - bool Hide(); + Centres the window on its parent. This is a more readable synonym for Centre(). - /** - This function hides a window, like Hide(), but using a special visual - effect if possible. + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. - The parameters of this function are the same as for ShowWithEffect(), - please see their description there. + @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(). - @since 2.9.0 + @see wxTopLevelWindow::CentreOnScreen */ - virtual bool HideWithEffect(wxShowEffect effect, - unsigned int timeout = 0); - + void CentreOnParent(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. + 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. - 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 x + Receives the x position of the window if non-@NULL. + @param y + Receives the y position of the window if non-@NULL. - This rather complicated logic is necessary in order to accommodate the - different usage scenarios. The most common one is when all default attributes - are used and in this case, nothing should be inherited as in modern GUIs - different controls use different fonts (and colours) than their siblings so - they can't inherit the same value from the parent. However it was also deemed - desirable to allow to simply change the attributes of all children at once by - just changing the font or colour of their common parent, hence in this case we - do inherit the parents attributes. + @see GetScreenPosition() */ - virtual void InheritAttributes(); + void GetPosition(int* x, int* y) const; /** - Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data - to the dialog via validators. - */ - virtual void InitDialog(); + 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. - /** - Resets the cached best size value so it will be recalculated the next time it - is needed. + @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. - - 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() + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - @see Enable() - */ - bool IsEnabled() const; + @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. - //@{ - /** - 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. + @see GetPosition() */ - 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; - //@} + void GetScreenPosition(int* x, int* y) const; /** - Returns @true if the window is currently frozen by a call to Freeze(). + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. - @see Freeze(), Thaw() + @see GetPosition() */ - bool IsFrozen() const; + wxPoint GetScreenPosition() const; /** - Returns @true if the window is retained, @false otherwise. + Returns the position and size of the window on the screen as a wxRect object. - @remarks Retained windows are only available on X platforms. + @see GetRect() */ - virtual bool IsRetained() const; + wxRect GetScreenRect() const; /** - Return whether a scrollbar is always shown. + Moves the window to the given position. - @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(); - - /** - Lowers the window to the bottom of the window hierarchy (Z-order). - - @remarks - This function only works for wxTopLevelWindow-derived classes. - - @see Raise() - */ - virtual void Lower(); - - /** - 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); - - /** - Moves the window to the given position. - - @param x - Required x position. - @param y - Required y position. - @param flags - See SetSize() for more info about this parameter. + @param x + Required x position. + @param y + Required y position. + @param flags + See SetSize() for more info about this parameter. @remarks Implementations of SetSize can also implicitly implement the Move() function, which is defined in the base wxWindow class as the call: @@ -1580,193 +1210,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 functions + */ + //@{ - 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. - - @see SetEventHandler(), GetEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + 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. */ - 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 +1495,340 @@ 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. + @deprecated use wxDC::SetPalette instead. + */ + void SetPalette(const wxPalette& pal); - @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). + /** + 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 ScrollPages() + The base class version returns @false, but this method is overridden in + wxControl where it returns @true. */ - virtual bool ScrollLines(int lines); + virtual bool ShouldInheritColours() const; /** - 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. + 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. - @see ScrollLines() + Dialogs, notebook pages and the status bar have this flag set to @true + by default so that the default look and feel is simulated best. */ - virtual bool ScrollPages(int pages); + virtual void SetThemeEnabled(bool enable); /** - Physically scrolls the pixels in the window and move child windows accordingly. + 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 bool CanSetTransparent(); - @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) + /** + 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(). - @remarks Note that you can often use wxScrolled instead of using this - function directly. + 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 void ScrollWindow(int dx, int dy, - const wxRect* rect = NULL); + virtual bool SetTransparent(wxByte alpha); - /** - This function sends a dummy @ref wxSizeEvent "size event" to - the window allowing it to re-layout its children positions. + //@} - It is sometimes useful to call this function after adding or deleting a - children after the frame creation or if a child size changes. Note that - if the frame is using either sizers or constraints for the children - layout, it is enough to call wxWindow::Layout() directly and this - function should not be used in this case. - If @a 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. + /** + @name Event-handling functions - @param flags - May include @c wxSEND_EVENT_POST. Default value is 0. + wxWindow allows you to build a (sort of) stack of event handlers which + can be used to override the window's own event handling. */ - 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). + Removes and returns the top-most event handler on the event handler stack. - 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. + E.g. in the case of: + @image html overview_eventhandling_winstack.png + when calling @c W->PopEventHandler(), the event handler @c A will be + removed and @c B will be the first handler of the stack. - @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). + Note that it's an error to call this function when no event handlers + were pushed on this window (i.e. when the window itself is its only + event handler). - @see SetConstraints() + @param deleteHandler + If this is @true, the handler will be deleted after it is removed + (and the returned value will be @NULL). + + @see @ref overview_eventhandling_processing */ - 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. + 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. - @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. + wxWindow::PushEventHandler allows an application to set up a @e stack + of event handlers, where an event not handled by one event handler is + handed to the next one in the chain. - @see GetBackgroundColour(), SetForegroundColour(), - GetForegroundColour(), ClearBackground(), - Refresh(), wxEraseEvent + E.g. if you have two event handlers @c A and @c B and a wxWindow instance + @c W and you call: + @code + W->PushEventHandler(A); + W->PushEventHandler(B); + @endcode + you will end up with the following situation: + @image html overview_eventhandling_winstack.png + + Note that you can use wxWindow::PopEventHandler to remove the event handler. + + @param handler + Specifies the handler to be pushed. + It must not be part of a wxEvtHandler chain; an assert will fail + if it's not unlinked (see wxEvtHandler::IsUnlinked). + + @see @ref overview_eventhandling_processing */ - 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 stack and unlinks + (but not delete) it. See wxEvtHandler::Unlink() for more info. - @see SetBackgroundColour(), GetForegroundColour(), - SetTransparent() + @param handler + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers stack. + + @return Returns @true if it was found and @false otherwise (this also + results in an assert failure so this function should + only be called when the handler is supposed to be there). + + @see PushEventHandler(), PopEventHandler() */ - virtual bool 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(). + Note that if you use this function you may want to use as the "next" handler + of @a handler the window itself; in this way when @a handler doesn't process + an event, the window itself will have a chance to do it. - @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + @param handler + Specifies the handler to be set. Cannot be @NULL. + + @see @ref overview_eventhandling_processing */ - virtual void SetCanFocus(bool canFocus); + void SetEventHandler(wxEvtHandler* handler); /** - Sets the caret() associated with the window. + wxWindows cannot be used to form event handler chains; this function + thus will assert when called. + + Note that instead you can use PushEventHandler() or SetEventHandler() to + implement a stack of event handlers to override wxWindow's own + event handling mechanism. */ - void SetCaret(wxCaret* caret); + virtual void SetNextHandler(wxEvtHandler* handler); - //@{ /** - This sets the size of the window client area in pixels. + wxWindows cannot be used to form event handler chains; this function + thus will assert when called. - 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. + Note that instead you can use PushEventHandler() or SetEventHandler() to + implement a stack of event handlers to override wxWindow's own + event handling mechanism. */ - virtual void SetClientSize(int width, int height); - virtual void SetClientSize(const wxSize& size); + virtual void SetPreviousHandler(wxEvtHandler* handler); + //@} - /** - 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. + /** + @name Window styles functions */ - void SetConstraints(wxLayoutConstraints* constraints); + //@{ /** - This normally does not need to be called by user code. - It is called when a window is added to a sizer, and is used so the window - can remove itself from the sizer when it is destroyed. + Returns the extra style bits for the window. */ - void SetContainingSizer(wxSizer* sizer); + long GetExtraStyle() 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. + Gets the window style that was passed to the constructor or Create() + method. GetWindowStyle() is another name for the same function. + */ + virtual long GetWindowStyleFlag() const; - @see ::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,373 +1838,300 @@ public: virtual void SetExtraStyle(long exStyle); /** - This sets the window to receive keyboard input. + 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. - @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, - wxPanel::SetFocusIgnoringChildren + See @ref overview_windowstyles "Window styles" for more information about flags. + + @see GetWindowStyleFlag() */ - virtual void SetFocus(); + virtual void SetWindowStyleFlag(long style); /** - 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. + See SetWindowStyleFlag() for more info. */ - virtual void SetFocusFromKbd(); + void SetWindowStyle(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(). + Turns the given @a flag on if it's currently turned off and vice versa. + This function cannot be used if the value of the flag is 0 (which is often + the case for default flags). - @param font - Font to associate with this window, pass - wxNullFont to reset to the default font. + Also, please notice that not all styles can be changed after the control + creation. - @return @true if the want was really changed, @false if it was already set - to this font and so nothing was done. + @return Returns @true if the style was turned on by this function, @false + if it was switched off. - @see GetFont(), InheritAttributes() + @see SetWindowStyleFlag(), HasFlag() */ - virtual bool SetFont(const wxFont& font); + bool ToggleWindowStyle(int flag); + + //@} + /** - Sets the foreground colour of the window. - Please see InheritAttributes() for explanation of the difference between - this method and SetOwnForegroundColour(). + @name Tab order functions + */ + //@{ - @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 functions */ - 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 Window status 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. - - @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). + This function shows a window, like Show(), but using a special visual + effect if possible. - @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 effect + The effect to use. - @see Move() - */ - void SetSize(int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO); + @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. - //@{ - /** - Sets the size of the window in pixels. - The size is specified using a wxRect, wxSize or by a couple of @c int objects. + @note Currently this function is only implemented in wxMSW and does the + same thing as Show() in the other ports. - @remarks This form must be used with non-default width and height values. + @since 2.9.0 - @see Move() + @see HideWithEffect() */ - virtual void SetSize(const wxRect& rect); - virtual void SetSize(const wxSize& size); - virtual void SetSize(int width, int height); + virtual bool ShowWithEffect(wxShowEffect effect, + unsigned int timeout = 0); + //@} - /** - 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 wxTopLevelWindow::SetSizeHints + /** + @name Context-sensitive help functions */ - void SetSizeHints( const wxSize& minSize, - const wxSize& maxSize=wxDefaultSize, - const wxSize& incSize=wxDefaultSize); + //@{ /** - 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. + 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. - Note that this function will also call SetAutoLayout() implicitly with @true - parameter if the @a sizer is non-@NULL and @false otherwise. + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + */ + wxString GetHelpText() const; - @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. + /** + 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. - @remarks SetSizer enables and disables Layout automatically. + @see GetHelpText(), wxHelpProvider::AddHelp() */ - void SetSizer(wxSizer* sizer, bool deleteOld = true); + void SetHelpText(const wxString& helpText); /** - 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. + 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. */ - void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); + virtual wxString GetHelpTextAtPoint(const wxPoint& point, + wxHelpEvent::Origin origin) const; /** - This function tells a window if it should use the system's "theme" code - to draw the windows' background instead if its own background drawing - code. This does not always have any effect since the underlying platform - obviously needs to support the notion of themes in user defined windows. - One such platform is GTK+ where windows can have (very colourful) backgrounds - defined by a user's selected theme. - - 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. + Get the associated tooltip or @NULL if none. */ - virtual void SetThemeEnabled(bool enable); + wxToolTip* GetToolTip() const; - //@{ /** Attach a tooltip to the window. @@ -2527,154 +2146,724 @@ public: @see GetToolTip(), wxToolTip */ void SetToolTip(const wxString& tip); - void SetToolTip(wxToolTip* tip); - //@} - - /** - 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. - */ - virtual bool SetTransparent(wxByte alpha); /** - Deletes the current validator (if any) and sets the window validator, having - called wxValidator::Clone to create a new validator of this type. + @overload */ - virtual void SetValidator(const wxValidator& validator); + void SetToolTip(wxToolTip* tip); - //@{ /** - Sets the virtual size of the window in pixels. - */ - void SetVirtualSize(int width, int height); - void SetVirtualSize(const wxSize& size); - //@} + Unset any existing tooltip. - //@{ - /** - 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. + @since 2.9.0 - See @ref overview_windowstyles "Window styles" for more information about flags. + @see SetToolTip() + */ + void UnsetToolTip(); - @see GetWindowStyleFlag() - */ - virtual void SetWindowStyleFlag(long style); - void SetWindowStyle(long style); //@} - /** - This function can be called under all platforms but only does anything under - Mac OS X 10.3+ currently. Under this system, each of the standard control can - exist in several sizes which correspond to the elements of wxWindowVariant enum. - By default the controls use the normal size, of course, but this function can - be used to change this. + /** + @name Popup/context menu functions */ - void SetWindowVariant(wxWindowVariant variant); + //@{ /** - 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. + This function shows a popup menu at the given position in this window and + returns the selected id. - The base class version returns @false, but this method is overridden in - wxControl where it returns @true. - */ - virtual bool ShouldInheritColours() const; + 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. - /** - 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. + 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. - @param show - If @true displays the window. Otherwise, hides 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 @true if the window has been shown or hidden or @false if nothing - was done because it already was in the requested state. + @return + The selected menu item id or @c wxID_NONE if none selected or an + error occurred. - @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. + @since 2.9.0 */ - virtual bool Show(bool show = true); + int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); /** - This function shows a window, like Show(), but using a special visual - effect if possible. + @overload + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); - @param effect - The effect to use. + /** + 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); + + //@} + + + /** + Validator functions + */ + //@{ + + /** + Returns a pointer to the current validator for the window, or @NULL if + there is none. + */ + virtual wxValidator* GetValidator(); + + /** + 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); + + /** + Transfers values from child controls to data areas specified by their + validators. Returns @false if a transfer failed. + + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataFromWindow() of all child windows. + + @see TransferDataToWindow(), wxValidator, Validate() + */ + virtual bool TransferDataFromWindow(); + + /** + Transfers values to child controls from data areas specified by their + validators. + + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataToWindow() of all child windows. + + @return Returns @false if a transfer failed. + + @see TransferDataFromWindow(), wxValidator, Validate() + */ + virtual bool TransferDataToWindow(); + + /** + Validates the current values of the child controls using their validators. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call Validate() of all child windows. + + @return Returns @false if any of the validations failed. + + @see TransferDataFromWindow(), TransferDataToWindow(), + wxValidator + */ + virtual bool Validate(); + + //@} + + + /** + @name wxWindow properties functions + */ + //@{ + + /** + 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 the value previously passed to SetWindowVariant(). + */ + wxWindowVariant GetWindowVariant() const; + + /** + Sets the identifier of the window. + + @remarks Each window has an integer identifier. If the application has + not provided one, an identifier will be generated. + Normally, the identifier should be provided on creation + and should not be modified subsequently. + + @see GetId(), @ref overview_windowids + */ + void SetId(wxWindowID winid); + + /** + Sets the window's label. + + @param label + The window label. + + @see GetLabel() + */ + virtual void SetLabel(const wxString& label); + + /** + Sets the window's name. + + @param name + A name to set for the window. + + @see GetName() + */ + virtual void SetName(const wxString& name); + + /** + This function can be called under all platforms but only does anything under + Mac OS X 10.3+ currently. Under this system, each of the standard control can + exist in several sizes which correspond to the elements of wxWindowVariant enum. + + By default the controls use the normal size, of course, but this function can + be used to change this. + */ + void SetWindowVariant(wxWindowVariant variant); + + + /** + 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(); + + /** + Sets the accelerator table for this window. See wxAcceleratorTable. + */ + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + + /** + Sets the accessible for this window. Any existing accessible for this window + will be deleted first, if not identical to @e accessible. + See also wxAccessible. + */ + void SetAccessible(wxAccessible* accessible); + + //@} + + + /** + @name Window deletion functions + */ + //@{ + + /** + 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; + + //@} + + + + /** + @name Drag and drop functions + */ + //@{ + + /** + Returns the associated drop target, which may be @NULL. + + @see SetDropTarget(), @ref overview_dnd + */ + virtual wxDropTarget* GetDropTarget() const; + + /** + Associates a drop target with this window. + If the window already has a drop target, it is deleted. + + @see GetDropTarget(), @ref overview_dnd + */ + virtual void SetDropTarget(wxDropTarget* target); + + /** + 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); + + //@} + + + /** + @name Constraints, sizers and window layouting functions + */ + //@{ + + /** + Return the sizer that this window is a member of, if any, otherwise @NULL. + */ + wxSizer* GetContainingSizer() const; + + /** + Return the sizer associated with the window by a previous call to + SetSizer() or @NULL. + */ + wxSizer* GetSizer() 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. + + 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. - @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. + @remarks SetSizer enables and disables Layout automatically. + */ + void SetSizer(wxSizer* sizer, bool deleteOld = true); - @note Currently this function is only implemented in wxMSW and does the - same thing as Show() in the other ports. + /** + This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial + window size to the size needed to accommodate all sizer elements and sets the + size hints which, if this window is a top level one, prevent the user from + resizing it to be less than this minimial size. + */ + void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); - @since 2.9.0 + /** + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints() const; - @see HideWithEffect() + /** + 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. */ - virtual bool ShowWithEffect(wxShowEffect effect, - unsigned int timeout = 0); + void SetConstraints(wxLayoutConstraints* constraints); + /** - Reenables window updating after a previous call to Freeze(). + Invokes the constraint-based layout algorithm or the sizer-based algorithm + for this window. - To really thaw the control, it must be called exactly the same number - of times as Freeze(). + 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). - If the window has any children, they are recursively thawn too. + @see @ref overview_windowsizing + */ + virtual bool Layout(); + + /** + 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. + + @param autoLayout + Set this to @true if you wish the Layout() function to be + called automatically when the window is resized + (really happens only if you derive from wxPanel or wxTopLevelWindow). + + @see SetConstraints() + */ + void SetAutoLayout(bool autoLayout); + + //@} + + + + /** + @name Mouse 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(); + + /** + Returns the caret() associated with the window. + */ + wxCaret* GetCaret() const; + + /** + Return the cursor associated with this window. + + @see SetCursor() + */ + const wxCursor& GetCursor() const; + + /** + Returns @true if this window has the current mouse capture. + + @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent + */ + virtual bool HasCapture() const; + + /** + Releases mouse input captured with CaptureMouse(). + + @see CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + void ReleaseMouse(); + + /** + Sets the caret() associated with the window. + */ + void SetCaret(wxCaret* caret); + + /** + Sets the window's cursor. Notice that the window cursor also sets it for the + children of the window implicitly. + + The @a cursor may be @c wxNullCursor in which case the window cursor will + be reset back to default. + + @param cursor + Specifies the cursor that the window should normally display. + + @see ::wxSetCursor, wxCursor + */ + virtual bool SetCursor(const wxCursor& cursor); + + /** + Moves the pointer to the given position on the window. + + @note This function is not supported under Mac because Apple Human + Interface Guidelines forbid moving the mouse cursor programmatically. + + @param x + The new x position for the cursor. + @param y + The new y position for the cursor. + */ + virtual void WarpPointer(int x, int y); + + //@} + + + + + /** + @name Miscellaneous functions + */ + //@{ + + /** + 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); + + /** + 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; + + /** + 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. - @see wxWindowUpdateLocker, Freeze(), IsFrozen() + @remarks Retained windows are only available on X platforms. */ - void Thaw(); + virtual bool IsRetained() const; /** - Turns the given @a flag on if it's currently turned off and vice versa. - This function cannot be used if the value of the flag is 0 (which is often - the case for default flags). + 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; - Also, please notice that not all styles can be changed after the control - creation. + /** + Returns @true if the given window is a top-level one. Currently all frames and + dialogs are considered to be top-level windows (even if they have a parent + window). + */ + virtual bool IsTopLevel() const; - @return Returns @true if the style was turned on by this function, @false - if it was switched off. + /** + Disables all other windows in the application so that + the user can only interact with this window. - @see SetWindowStyleFlag(), HasFlag() + @param modal + If @true, this call disables all other windows in the application so that + the user can only interact with this window. If @false, the effect is + reversed. */ - bool ToggleWindowStyle(int flag); + virtual void MakeModal(bool modal = true); /** - Transfers values from child controls to data areas specified by their - validators. Returns @false if a transfer failed. - - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataFromWindow() of all child windows. + This virtual function is normally only used internally, but + sometimes an application may need it to implement functionality + that should not be disabled by an application defining an OnIdle + handler in a derived class. - @see TransferDataToWindow(), wxValidator, Validate() + This function may be used to do delayed painting, for example, + and most implementations call UpdateWindowUI() + in order to send update events to the window in idle time. */ - virtual bool TransferDataFromWindow(); + virtual void OnInternalIdle(); /** - Transfers values to child controls from data areas specified by their - validators. + Registers a system wide hotkey. Every time the user presses the hotkey + registered here, this window will receive a hotkey event. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataToWindow() of all child windows. + It will receive the event even if the application is in the background + and does not have the input focus because the user is working with some + other application. - @return Returns @false if a transfer failed. + @param hotkeyId + Numeric identifier of the hotkey. For applications this must be between 0 + and 0xBFFF. If this function is called from a shared DLL, it must be a + system wide unique identifier between 0xC000 and 0xFFFF. + This is a MSW specific detail. + @param modifiers + A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT + or wxMOD_WIN specifying the modifier keys that have to be pressed along + with the key. + @param virtualKeyCode + The virtual key code of the hotkey. - @see TransferDataFromWindow(), wxValidator, Validate() + @return @true if the hotkey was registered successfully. @false if some + other application already registered a hotkey with this + modifier/virtualKeyCode combination. + + @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the + event. This function is currently only implemented + under Windows. It is used in the Windows CE port for + detecting hardware button presses. + + @see UnregisterHotKey() */ - virtual bool TransferDataToWindow(); + virtual bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); /** Unregisters a system wide hotkey. @@ -2692,40 +2881,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 @@ -2759,30 +2914,137 @@ public: */ virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); + //@} + + + // NOTE: static functions must have their own group or Doxygen will screw + // up the ordering of the member groups + /** - Validates the current values of the child controls using their validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call Validate() of all child windows. + @name Miscellaneous static functions + */ + //@{ - @return Returns @false if any of the validations failed. + /** + Returns the default font and colours which are used by the control. - @see TransferDataFromWindow(), TransferDataToWindow(), - wxValidator + This is useful if you want to use the same font or colour in your own control + as in a standard control -- which is a much better idea than hard coding specific + colours or fonts which might look completely out of place on the users + system, especially if it uses themes. + + The @a variant parameter is only relevant under Mac currently and is + ignore under other platforms. Under Mac, it will change the size of the + returned font. See SetWindowVariant() for more about this. + + This static method is "overridden" in many derived classes and so calling, + for example, wxButton::GetClassDefaultAttributes() will typically + return the values appropriate for a button which will be normally different + from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). + + The @c wxVisualAttributes structure has at least the fields + @c font, @c colFg and @c colBg. All of them may be invalid + if it was not possible to determine the default control appearance or, + especially for the background colour, if the field doesn't make sense as is + the case for @c colBg for the controls with themed background. + + @see InheritAttributes() */ - virtual bool Validate(); + static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); /** - Moves the pointer to the given position on the window. + Finds the window or control which currently has the keyboard focus. - @note This function is not supported under Mac because Apple Human - Interface Guidelines forbid moving the mouse cursor programmatically. + @remarks Note that this is a static function, so it can be called without + needing a wxWindow pointer. - @param x - The new x position for the cursor. - @param y - The new y position for the cursor. + @see SetFocus(), HasFocus() */ - virtual void WarpPointer(int x, int y); + static wxWindow* FindFocus(); + + /** + Find the first window with the given @e id. + + If @a parent is @NULL, the search will start from all top-level frames + and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowById(long id, const wxWindow* parent = 0); + + /** + Find a window by its label. + + Depending on the type of window, the label may be a window title + or panel item label. If @a parent is @NULL, the search will start from all + top-level frames and dialog boxes; if non-@NULL, the search will be + limited to the given window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowByLabel(const wxString& label, + const wxWindow* parent = 0); + + /** + Find a window by its name (as given in a window constructor or Create() + function call). + + If @a parent is @NULL, the search will start from all top-level frames + and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + + The search is recursive in both cases. If no window with such name is found, + FindWindowByLabel() is called. + + @see FindWindow() + */ + static wxWindow* FindWindowByName(const wxString& name, + const wxWindow* parent = 0); + + /** + Returns the currently captured window. + + @see HasCapture(), CaptureMouse(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + static wxWindow* GetCapture(); + + /** + Create a new ID or range of IDs that are not currently in use. + The IDs will be reserved until assigned to a wxWindow ID + or unreserved with UnreserveControlId(). + + See @ref overview_windowids for more information. + + @param count + The number of sequential IDs to reserve. + + @return Returns the ID or the first ID of the range, or wxID_NONE if the + specified number of identifiers couldn't be allocated. + + @see UnreserveControlId(), wxIdManager, + @ref overview_windowids + */ + static wxWindowID NewControlId(int count = 1); + + /** + Unreserve an ID or range of IDs that was reserved by NewControlId(). + See @ref overview_windowids for more information. + + @param id + The starting ID of the range of IDs to unreserve. + @param count + The number of sequential IDs to unreserve. + + @see NewControlId(), wxIdManager, @ref overview_windowids + */ + static void UnreserveControlId(wxWindowID id, int count = 1); + + //@} + protected: @@ -2815,6 +3077,34 @@ protected: @deprecated @todo provide deprecation description */ virtual void SetInitialBestSize(const wxSize& size); + + /** + Generate wxWindowDestroyEvent for this window. + + This is called by the window itself when it is being destroyed and + usually there is no need to call it but see wxWindowDestroyEvent for + explanations of when you might want to do it. + */ + void SendDestroyEvent(); + + //@{ + /** + This function is public in wxEvtHandler but is protected in wxWindow because + for wxWindows you should always use this function on the pointer returned + by GetEventHandler() and not on the wxWindow object itself. + + Note that it's still possible to call these functions directly on the + wxWindow object (e.g. downcasting it to wxEvtHandler) but doing that + will create subtle bugs when windows with event handlers pushed on them + are involved. + */ + virtual bool ProcessEvent(wxEvent& event); + bool SafelyProcessEvent(wxEvent& event); + virtual void QueueEvent(wxEvent *event); + virtual void AddPendingEvent(const wxEvent& event); + void ProcessPendingEvents(); + bool ProcessThreadEvent(const wxEvent& event); + //@} };