X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e25cd7750c571191ce69438de5f7c0293d1b5270..c7d4ca810570664b68f7a4f0f11d2a5a64aa6163:/interface/wx/window.h diff --git a/interface/wx/window.h b/interface/wx/window.h index 62b402c0e1..98d7a1a344 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -269,7 +269,7 @@ public: @see @ref overview_windowdeletion "Window Deletion Overview", Destroy(), wxCloseEvent */ - ~wxWindow(); + virtual ~wxWindow(); /** This method may be overridden in the derived classes to return @false to @@ -319,7 +319,7 @@ public: @remarks This function is currently only implemented under Mac/Carbon. */ - void AlwaysShowScrollbars(bool hflag, bool vflag); + virtual void AlwaysShowScrollbars(bool = true, bool = true); /** Sets the cached best size value. @@ -331,7 +331,7 @@ public: SetTransparent() may succeed. If this function returns @false, transparent windows are definitely not supported by the current system. */ - bool CanSetTransparent(); + virtual bool CanSetTransparent(); /** Directs all mouse input to this window. @@ -349,17 +349,17 @@ public: @see ReleaseMouse(), wxMouseCaptureLostEvent */ - virtual void CaptureMouse(); + void CaptureMouse(); /** A synonym for Centre(). */ - void Center(int direction); + void Center(int dir = wxBOTH); /** A synonym for CentreOnParent(). */ - void CenterOnParent(int direction); + void CenterOnParent(int dir = wxBOTH); /** Centres the window. @@ -397,9 +397,8 @@ public: Clears the window by filling it with the current background colour. Does not cause an erase background event to be generated. */ - void ClearBackground(); + virtual void ClearBackground(); - //@{ /** Converts to screen coordinates from coordinates relative to this window. @@ -409,8 +408,6 @@ public: @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. - @param pt - The client position for the second form of the function. @beginWxPythonOnly In place of a single overloaded method name, wxPython implements the following methods: @@ -419,8 +416,14 @@ public: @endWxPythonOnly */ void ClientToScreen(int* x, int* y) const; + + /** + Converts to screen coordinates from coordinates relative to this window. + + @param pt + The client position for the second form of the function. + */ wxPoint ClientToScreen(const wxPoint& pt) const; - //@} /** Converts client area size @a size to corresponding window size. @@ -436,7 +439,7 @@ public: @see WindowToClientSize() */ - virtual wxSize ClientToWindowSize(const wxSize& size); + virtual wxSize ClientToWindowSize(const wxSize& size) const; /** Converts window size @a size to corresponding client area size @@ -452,7 +455,7 @@ public: @see ClientToWindowSize() */ - virtual wxSize WindowToClientSize(const wxSize& size); + virtual wxSize WindowToClientSize(const wxSize& size) const; /** This function simply generates a wxCloseEvent whose handler usually tries @@ -542,7 +545,7 @@ public: /** Destroys all children of a window. Called automatically by the destructor. */ - virtual void DestroyChildren(); + bool DestroyChildren(); /** Returns true if this window is in process of being destroyed. @@ -566,27 +569,6 @@ public: */ bool Disable(); - /** - Gets the size which best suits the window: for a control, it would be - the minimal size which doesn't truncate the control, for a panel - the - same size as it would have after a call to Fit(). - - The default implementation of this function is designed for use in container - windows, such as wxPanel, and works something like this: - -# If the window has a sizer then it is used to calculate the best size. - -# Otherwise if the window has layout constraints then those are used to - calculate the best size. - -# Otherwise if the window has children then the best size is set to be large - enough to show all the children. - -# Otherwise if there are no children then the window's minimal size will be - used as its best size. - -# Otherwise if there is no minimal size set, then the current size is used - for the best size. - - @see @ref overview_windowsizing - */ - virtual wxSize DoGetBestSize() const; - /** Does the window-specific updating after processing the update event. This function is called by UpdateWindowUI() in order to check return @@ -750,12 +732,12 @@ public: @see wxWindowUpdateLocker, Thaw(), IsFrozen() */ - virtual void Freeze(); + void Freeze(); /** Gets the accelerator table for this window. See wxAcceleratorTable. */ - wxAcceleratorTable* GetAcceleratorTable() const; + wxAcceleratorTable* GetAcceleratorTable(); /** Returns the accessible object for this window, if any. @@ -912,7 +894,7 @@ public: @see SetDropTarget(), @ref overview_dnd */ - wxDropTarget* GetDropTarget() const; + virtual wxDropTarget* GetDropTarget() const; /** Merges the window's best size into the min size and returns the result. @@ -954,7 +936,7 @@ public: @see SetForegroundColour(), SetBackgroundColour(), GetBackgroundColour() */ - wxColour GetForegroundColour(); + wxColour GetForegroundColour() const; /** Returns the grandparent of a window, or @NULL if there isn't one. @@ -966,7 +948,7 @@ public: Cast it to an appropriate handle, such as @b HWND for Windows, @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS. */ - void* GetHandle() const; + virtual WXWidget GetHandle() const; /** Gets the help text to be used as context-sensitive help for this window. @@ -975,7 +957,7 @@ public: @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider */ - virtual wxString GetHelpText() const; + wxString GetHelpText() const; /** Gets the help text to be used as context-sensitive help for this window. @@ -999,7 +981,7 @@ public: @see SetId(), @ref overview_windowids */ - int GetId() const; + wxWindowID GetId() const; /** Generic way of getting a label from any window, for @@ -1023,7 +1005,7 @@ public: @see GetMaxSize() */ - wxSize GetMaxClientSize() const; + virtual wxSize GetMaxClientSize() const; /** Returns the maximum size of the window. @@ -1033,7 +1015,7 @@ public: @see GetMaxClientSize() */ - wxSize GetMaxSize() const; + virtual wxSize GetMaxSize() const; /** Returns the minimum size of window's client area, an indication to the sizer @@ -1081,9 +1063,8 @@ public: /** Returns the parent of the window, or @NULL if there is no parent. */ - virtual wxWindow* GetParent() const; + wxWindow* GetParent() 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 @@ -1094,19 +1075,19 @@ public: The menu to show @param pos The position at which to show the menu in client coordinates - @param x - The horizontal position of the menu - @param y - The vertical position of the menu @return The selected menu item id or wxID_NONE if none selected or an error occurred. */ int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); + + /** + See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload. + This overload differs only because it takes two integers for the + menu position instead of a wxPoint. + */ int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); - //@} - //@{ /** 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. @@ -1119,8 +1100,14 @@ public: @see GetScreenPosition() */ void GetPosition(int* x, int* y) const; + + /** + This gets the position of the window in pixels, relative to the parent window + for the child windows or relative to the display origin for the top level windows. + + @see GetScreenPosition() + */ wxPoint GetPosition() const; - //@} /** Returns the previous window before this one among the parent children or @c @@ -1139,7 +1126,6 @@ public: */ wxRect GetRect() const; - //@{ /** Returns the window position in screen coordinates, whether the window is a child window or a top level one. @@ -1152,8 +1138,14 @@ public: @see GetPosition() */ void GetScreenPosition(int* x, int* y) const; + + /** + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. + + @see GetPosition() + */ wxPoint GetScreenPosition() const; - //@} /** Returns the position and size of the window on the screen as a wxRect object. @@ -1167,23 +1159,22 @@ public: @see See SetScrollbar() */ - virtual int GetScrollPos(int orientation); + virtual int GetScrollPos(int orientation) const; /** Returns the built-in scrollbar range. @see SetScrollbar() */ - virtual int GetScrollRange(int orientation); + virtual int GetScrollRange(int orientation) const; /** Returns the built-in scrollbar thumb size. @see SetScrollbar() */ - virtual int GetScrollThumb(int orientation); + virtual int GetScrollThumb(int orientation) const; - //@{ /** Returns the size of the entire window in pixels, including title bar, border, scrollbars, etc. @@ -1199,8 +1190,11 @@ public: @see GetClientSize(), GetVirtualSize() */ void GetSize(int* width, int* height) const; + + /** + See the GetSize(int*,int*) overload for more info. + */ wxSize GetSize() const; - //@} /** Return the sizer associated with the window by a previous call to @@ -1208,7 +1202,6 @@ public: */ wxSizer* GetSizer() const; - //@{ /** Gets the dimensions of the string as it would be drawn on the window with the currently selected font. @@ -1227,21 +1220,17 @@ public: Return value for external leading (optional). @param font Font to use instead of the current window font (optional). - @param use16 - If @true, string contains 16-bit characters. The default is @false. */ virtual void GetTextExtent(const wxString& string, int* w, int* h, int* descent = NULL, int* externalLeading = NULL, - const wxFont* font = NULL, - bool use16 = false) const; + 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; - //@} /** Get the associated tooltip or @NULL if none. @@ -1254,13 +1243,13 @@ public: @see wxRegion, wxRegionIterator */ - virtual wxRegion GetUpdateRegion() const; + const wxRegion& GetUpdateRegion() const; /** Returns a pointer to the current validator for the window, or @NULL if there is none. */ - wxValidator* GetValidator() const; + virtual wxValidator* GetValidator(); //@{ /** @@ -1281,13 +1270,13 @@ public: Returns the size of the left/right and top/bottom borders of this window in x and y components of the result respectively. */ - wxSize GetWindowBorderSize() const; + virtual wxSize GetWindowBorderSize() const; /** Gets the window style that was passed to the constructor or @b Create method. @b GetWindowStyle() is another name for the same function. */ - long GetWindowStyleFlag() const; + virtual long GetWindowStyleFlag() const; /** Returns the value previously passed to SetWindowVariant(). @@ -1312,7 +1301,7 @@ public: GetEventHandler()->SafelyProcessEvent(event); @endcode */ - bool HandleWindowEvent(wxEvent& event); + bool HandleWindowEvent(wxEvent& event) const; /** Returns @true if this window has the current mouse capture. @@ -1358,7 +1347,7 @@ public: @param orient Orientation to check, either wxHORIZONTAL or wxVERTICAL. */ - virtual bool HasScrollbar(int orient) const; + bool HasScrollbar(int orient) const; /** Returns @true if this window background is transparent (as, for example, @@ -1368,7 +1357,7 @@ public: 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() const; + virtual bool HasTransparentBackground(); /** Equivalent to calling wxWindow::Show(@false). @@ -1385,7 +1374,7 @@ public: @since 2.9.0 */ virtual bool HideWithEffect(wxShowEffect effect, - unsigned timeout = 0); + unsigned int timeout = 0); /** This function is (or should be, in case of custom controls) called during @@ -1410,13 +1399,13 @@ public: just changing the font or colour of their common parent, hence in this case we do inherit the parents attributes. */ - void InheritAttributes(); + virtual void InheritAttributes(); /** Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data to the dialog via validators. */ - void InitDialog(); + virtual void InitDialog(); /** Resets the cached best size value so it will be recalculated the next time it @@ -1443,7 +1432,7 @@ public: @see Enable() */ - virtual bool IsEnabled() const; + bool IsEnabled() const; //@{ /** @@ -1462,7 +1451,7 @@ public: @see Freeze(), Thaw() */ - virtual bool IsFrozen() const; + bool IsFrozen() const; /** Returns @true if the window is retained, @false otherwise. @@ -1479,7 +1468,7 @@ public: @see AlwaysShowScrollbars() */ - bool IsScrollbarAlwaysShown(int orient); + virtual bool IsScrollbarAlwaysShown(int orient) const; /** Returns @true if the window is shown, @false if it has been hidden. @@ -1509,7 +1498,7 @@ public: dialogs are considered to be top-level windows (even if they have a parent window). */ - bool IsTopLevel() const; + virtual bool IsTopLevel() const; /** Invokes the constraint-based layout algorithm or the sizer-based algorithm @@ -1520,25 +1509,25 @@ public: @see @ref overview_windowsizing */ - void Layout(); + virtual bool Layout(); /** Lowers the window to the bottom of the window hierarchy (Z-order). @see Raise() */ - void Lower(); + virtual void Lower(); /** Disables all other windows in the application so that the user can only interact with this window. - @param flag + @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 flag); + virtual void MakeModal(bool modal = true); /** Moves the window to the given position. @@ -1547,6 +1536,8 @@ public: 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: @@ -1556,13 +1547,15 @@ public: @see SetSize() */ - void Move(int x, int y); + void Move(int x, int y, int flags = wxSIZE_USE_EXISTING); /** Moves the window to the given position. @param pt wxPoint object representing the position. + @param flags + See SetSize() for more info about this parameter. @remarks Implementations of SetSize() can also implicitly implement the Move() function, which is defined in the base wxWindow class as the call: @@ -1572,7 +1565,7 @@ public: @see SetSize() */ - void Move(const wxPoint& pt); + void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); /** Moves this window in the tab navigation order after the specified @e win. @@ -1615,13 +1608,13 @@ public: control. See also wxNavigationKeyEvent and HandleAsNavigationKey. */ - bool Navigate(int flags = wxNavigationKeyEvent::IsForward); + bool Navigate(int flags = IsForward); /** Performs a keyboard navigation action inside this window. See Navigate() for more information. */ - bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward); + bool NavigateIn(int flags = IsForward); /** Create a new ID or range of IDs that are not currently in use. @@ -1684,7 +1677,7 @@ public: @see SetEventHandler(), GetEventHandler(), PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ - wxEvtHandler* PopEventHandler(bool deleteHandler = false) const; + wxEvtHandler* PopEventHandler(bool deleteHandler = false); //@{ /** @@ -1762,7 +1755,7 @@ public: @see Lower() */ - void Raise(); + virtual void Raise(); /** Causes this window, and all of its children recursively (except under wxGTK1 @@ -1829,7 +1822,7 @@ public: @see CaptureMouse(), HasCapture(), ReleaseMouse(), wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent */ - virtual void ReleaseMouse(); + void ReleaseMouse(); /** Removes a child window. @@ -1932,7 +1925,7 @@ public: const wxRect* rect = NULL); /** - This function sends a dummy @ref overview_wxsizeevent "size event" to + 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 @@ -1949,7 +1942,7 @@ public: @param flags May include @c wxSEND_EVENT_POST. Default value is 0. */ - void SendSizeEvent(int flags = 0); + virtual void SendSizeEvent(int flags = 0); /** Safe wrapper for GetParent()->SendSizeEvent(). @@ -2030,7 +2023,7 @@ public: @see SetBackgroundColour(), GetForegroundColour(), SetTransparent() */ - virtual void SetBackgroundStyle(wxBackgroundStyle style); + virtual bool SetBackgroundStyle(wxBackgroundStyle style); /** This method is only implemented by ports which have support for @@ -2047,7 +2040,7 @@ public: /** Sets the caret() associated with the window. */ - void SetCaret(wxCaret* caret) const; + void SetCaret(wxCaret* caret); //@{ /** @@ -2106,7 +2099,7 @@ public: @see ::wxSetCursor, wxCursor */ - virtual void SetCursor(const wxCursor& cursor); + virtual bool SetCursor(const wxCursor& cursor); /** Associates a drop target with this window. @@ -2114,7 +2107,7 @@ public: @see GetDropTarget(), @ref overview_dnd */ - void SetDropTarget(wxDropTarget* target); + virtual void SetDropTarget(wxDropTarget* target); /** Sets the event handler for this window. @@ -2142,7 +2135,7 @@ public: The currently defined extra style bits are reported in the class description. */ - void SetExtraStyle(long exStyle); + virtual void SetExtraStyle(long exStyle); /** This sets the window to receive keyboard input. @@ -2182,7 +2175,7 @@ public: @see GetFont(), InheritAttributes() */ - bool SetFont(const wxFont& font); + virtual bool SetFont(const wxFont& font); /** Sets the foreground colour of the window. @@ -2200,7 +2193,7 @@ public: @see GetForegroundColour(), SetBackgroundColour(), GetBackgroundColour(), ShouldInheritColours() */ - virtual void SetForegroundColour(const wxColour& colour); + virtual bool SetForegroundColour(const wxColour& colour); /** Sets the help text to be used as context-sensitive help for this window. @@ -2209,7 +2202,7 @@ public: @see GetHelpText(), wxHelpProvider::AddHelp() */ - virtual void SetHelpText(const wxString& helpText); + void SetHelpText(const wxString& helpText); /** Sets the identifier of the window. @@ -2221,13 +2214,7 @@ public: @see GetId(), @ref overview_windowids */ - void SetId(int id); - - /** - Sets the initial window size if none is given (i.e. at least one of the - components of the size passed to ctor/Create() is wxDefaultCoord). - */ - virtual void SetInitialBestSize(const wxSize& size); + void SetId(wxWindowID winid); /** A @e smart SetSize that will fill in default size components with the @@ -2262,7 +2249,7 @@ public: @see SetMaxSize() */ - void SetMaxClientSize(const wxSize& size); + virtual void SetMaxClientSize(const wxSize& size); /** Sets the maximum size of the window, to indicate to the sizer layout mechanism @@ -2270,7 +2257,7 @@ public: @see SetMaxClientSize() */ - void SetMaxSize(const wxSize& size); + virtual void SetMaxSize(const wxSize& size); /** Sets the minimum client size of the window, to indicate to the sizer @@ -2286,7 +2273,7 @@ public: @see SetMinSize() */ - void SetMinClientSize(const wxSize& size); + virtual void SetMinClientSize(const wxSize& size); /** Sets the minimum size of the window, to indicate to the sizer layout @@ -2302,7 +2289,7 @@ public: @see SetMinClientSize() */ - void SetMinSize(const wxSize& size); + virtual void SetMinSize(const wxSize& size); /** Sets the window's name. @@ -2341,7 +2328,7 @@ public: /** @deprecated use wxDC::SetPalette instead. */ - virtual void SetPalette(wxPalette* palette); + void SetPalette(const wxPalette& pal); /** Sets the position of one of the built-in scrollbars. @@ -2379,31 +2366,29 @@ public: @param refresh @true to redraw the scrollbar, @false otherwise. - @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. - You would use: - @code - SetScrollbar(wxVERTICAL, 0, 16, 50); - @endcode - Note that with the window at this size, the thumb position can never - go above 50 minus 16, or 34. You can determine how many lines are - currently visible by dividing the current view size by the character - height in pixels. - When defining your own scrollbar behaviour, you will always need - to recalculate the scrollbar settings when the window size changes. - You could therefore put your scrollbar calculations and SetScrollbar - call into a function named AdjustScrollbars, which can be called - initially and also from your wxSizeEvent handler function. + @remarks + Let's say you wish to display 50 lines of text, using the same font. + The window is sized so that you can only see 16 lines at a time. + You would use: + @code + SetScrollbar(wxVERTICAL, 0, 16, 50); + @endcode + Note that with the window at this size, the thumb position can never + go above 50 minus 16, or 34. You can determine how many lines are + currently visible by dividing the current view size by the character + height in pixels. + When defining your own scrollbar behaviour, you will always need + to recalculate the scrollbar settings when the window size changes. + You could therefore put your scrollbar calculations and SetScrollbar + call into a function named AdjustScrollbars, which can be called + initially and also from your wxSizeEvent handler function. @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent */ virtual void SetScrollbar(int orientation, int position, - int thumbSize, - int range, + int thumbSize, int range, bool refresh = true); - //@{ /** Sets the size of the window in pixels. @@ -2419,10 +2404,6 @@ public: @param height Required height position in pixels, or wxDefaultCoord to indicate that the existing value should be used. - @param size - wxSize object for setting the size. - @param rect - wxRect object for setting the position and size. @param sizeFlags Indicates the interpretation of other parameters. It is a bit list of the following: @@ -2444,21 +2425,28 @@ public: later and only implemented for MSW and ignored elsewhere currently). - @remarks The second form is a convenience for calling the first form with - default x and y parameters, and must be used with - non-default width and height values. - The first form sets the position and optionally size, of the window. + @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() */ - virtual void SetSize(int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO); + void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); + + //@{ + /** + 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 void SetSize(const wxRect& rect); - virtual void SetSize(int width, int height); virtual void SetSize(const wxSize& size); + virtual void SetSize(int width, int height); //@} /** @@ -2529,7 +2517,7 @@ public: fully transparent window and 255 to the fully opaque one. The constants @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used. */ - bool SetTransparent(wxByte alpha); + virtual bool SetTransparent(wxByte alpha); /** Deletes the current validator (if any) and sets the window validator, having @@ -2578,7 +2566,7 @@ public: The base class version returns @false, but this method is overridden in wxControl where it returns @true. */ - virtual bool ShouldInheritColours(); + virtual bool ShouldInheritColours() const; /** Shows or hides the window. You may need to call Raise() @@ -2615,7 +2603,7 @@ public: @see HideWithEffect() */ virtual bool ShowWithEffect(wxShowEffect effect, - unsigned timeout = 0); + unsigned int timeout = 0); /** Reenables window updating after a previous call to Freeze(). @@ -2627,7 +2615,7 @@ public: @see wxWindowUpdateLocker, Freeze(), IsFrozen() */ - virtual void Thaw(); + void Thaw(); /** Turns the given @a flag on if it's currently turned off and vice versa. @@ -2774,7 +2762,39 @@ public: @param y The new y position for the cursor. */ - void WarpPointer(int x, int y); + virtual void WarpPointer(int x, int y); + + +protected: + + /** + Gets the size which best suits the window: for a control, it would be + the minimal size which doesn't truncate the control, for a panel - the + same size as it would have after a call to Fit(). + + The default implementation of this function is designed for use in container + windows, such as wxPanel, and works something like this: + -# If the window has a sizer then it is used to calculate the best size. + -# Otherwise if the window has layout constraints then those are used to + calculate the best size. + -# Otherwise if the window has children then the best size is set to be large + enough to show all the children. + -# Otherwise if there are no children then the window's minimal size will be + used as its best size. + -# Otherwise if there is no minimal size set, then the current size is used + for the best size. + + @see @ref overview_windowsizing + */ + virtual wxSize DoGetBestSize() const; + + + /** + Sets the initial window size if none is given (i.e. at least one of the + components of the size passed to ctor/Create() is wxDefaultCoord). + @deprecated @todo provide deprecation description + */ + virtual void SetInitialBestSize(const wxSize& size); };