X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..6496345c33824373fdb8cf7de04a43197fa0341c:/interface/wx/window.h diff --git a/interface/wx/window.h b/interface/wx/window.h index 42ad351c86..ab349f2486 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -207,8 +207,9 @@ enum wxUpdateUI Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an application window. - This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so - these two styles are automatically turned of if this one is used. + This style cannot be used (because of the underlying native behaviour) + together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles + are automatically turned off if this one is used. @style{wxWS_EX_PROCESS_IDLE} This window should always process idle events, even if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. @@ -319,7 +320,7 @@ public: @remarks This function is currently only implemented under Mac/Carbon. */ - void AlwaysShowScrollbars(bool hflag, bool vflag); + virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); /** Sets the cached best size value. @@ -354,12 +355,12 @@ public: /** 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. @@ -545,7 +546,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. @@ -569,27 +570,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 @@ -621,7 +601,11 @@ public: If @true, the window is eligible for drop file events. If @false, the window will not accept drop file events. - @remarks Windows only. + @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); @@ -766,12 +750,6 @@ public: */ wxAccessible* GetAccessible(); - /** - @deprecated - This method is deprecated, use GetEffectiveMinSize() instead. - */ - wxSize GetAdjustedBestSize() const; - /** Returns the background colour of the window. @@ -860,16 +838,12 @@ public: //@{ /** Returns the size of the window 'client area' in pixels. + The client area is the area which may be drawn on by the programmer, excluding title bar, border, scrollbars, etc. Note that if this window is a top-level one and it is currently minimized, the return size is empty (both width and height are 0). - @param width - Receives the client width in pixels. - @param height - Receives the client height in pixels. - @see GetSize(), GetVirtualSize() */ void GetClientSize(int* width, int* height) const; @@ -969,7 +943,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. @@ -990,7 +964,7 @@ public: @param origin Help event origin, see also wxHelpEvent::GetOrigin. */ - virtual wxString GetHelpTextAtPoint(const wxPoint point, + virtual wxString GetHelpTextAtPoint(const wxPoint& point, wxHelpEvent::Origin origin) const; /** @@ -1002,7 +976,7 @@ public: @see SetId(), @ref overview_windowids */ - int GetId() const; + wxWindowID GetId() const; /** Generic way of getting a label from any window, for @@ -1241,14 +1215,11 @@ 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 @@ -1267,7 +1238,7 @@ 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 @@ -1279,7 +1250,12 @@ public: /** 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 that size. + SetVirtualSize() it will return the size set with that method. + */ + wxSize GetVirtualSize() const; + + /** + Like the other GetVirtualSize() overload but uses pointers instead. @param width Receives the window virtual width. @@ -1287,7 +1263,6 @@ public: Receives the window virtual height. */ void GetVirtualSize(int* width, int* height) const; - wxSize GetVirtualSize() const; //@} /** @@ -1398,7 +1373,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 @@ -1465,9 +1440,9 @@ public: only redrawing those areas, which have been exposed. */ bool IsExposed(int x, int y) const; - const bool IsExposed(wxPoint amp;pt) const; - const bool IsExposed(int x, int y, int w, int h) const; - const bool IsExposed(wxRect amp;rect) const; + bool IsExposed(wxPoint& pt) const; + bool IsExposed(int x, int y, int w, int h) const; + bool IsExposed(wxRect& rect) const; //@} /** @@ -1528,16 +1503,21 @@ public: Invokes the constraint-based layout algorithm or the sizer-based algorithm for this window. - See SetAutoLayout(): when auto layout is on, this function gets called automatically - when the window is resized. + 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 */ - void Layout(); + 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(); @@ -1546,12 +1526,12 @@ public: 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. @@ -1560,6 +1540,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: @@ -1569,13 +1551,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: @@ -1585,7 +1569,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. @@ -1628,13 +1612,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. @@ -1708,14 +1692,10 @@ public: processed as usually. If the coordinates are not specified, current mouse cursor position is used. - @param menu - Menu to pop up. - @param pos - The position where the menu will appear. - @param x - Required x position for the menu to appear. - @param y - Required y position for the menu to appear. + @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. @@ -1771,7 +1751,9 @@ public: /** Raises the window to the top of the window hierarchy (Z-order). - In current version of wxWidgets this works both for managed and child windows. + + @remarks + This function only works for wxTopLevelWindow-derived classes. @see Lower() */ @@ -1833,8 +1815,8 @@ public: @see UnregisterHotKey() */ - bool RegisterHotKey(int hotkeyId, int modifiers, - int virtualKeyCode); + virtual bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); /** Releases mouse input captured with CaptureMouse(). @@ -1883,7 +1865,6 @@ public: */ virtual bool Reparent(wxWindow* newParent); - //@{ /** Converts from screen to client window coordinates. @@ -1891,12 +1872,16 @@ public: Stores the screen x coordinate and receives the client x coordinate. @param y Stores the screen x coordinate and receives the client x coordinate. + */ + void ScreenToClient(int* x, int* y) const; + + /** + Converts from screen to client window coordinates. + @param pt - The screen position for the second form of the function. + The screen position. */ - virtual void ScreenToClient(int* x, int* y) const; - virtual wxPoint ScreenToClient(const wxPoint& pt) const; - //@} + wxPoint ScreenToClient(const wxPoint& pt) const; /** Scrolls the window by the given number of lines down (if @a lines is @@ -1945,7 +1930,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 @@ -2003,8 +1988,9 @@ public: 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. + 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() */ @@ -2043,7 +2029,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 @@ -2070,13 +2056,6 @@ public: 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. - - @param width - The required client area width. - @param height - The required client area height. - @param size - The required client size. */ virtual void SetClientSize(int width, int height); virtual void SetClientSize(const wxSize& size); @@ -2119,7 +2098,7 @@ public: @see ::wxSetCursor, wxCursor */ - virtual void SetCursor(const wxCursor& cursor); + virtual bool SetCursor(const wxCursor& cursor); /** Associates a drop target with this window. @@ -2213,7 +2192,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. @@ -2234,13 +2213,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 @@ -2354,7 +2327,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. @@ -2458,8 +2431,8 @@ public: @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); //@{ /** @@ -2629,7 +2602,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(). @@ -2696,7 +2669,7 @@ public: @see RegisterHotKey() */ - bool UnregisterHotKey(int hotkeyId); + virtual bool UnregisterHotKey(int hotkeyId); /** Unreserve an ID or range of IDs that was reserved by NewControlId(). @@ -2789,6 +2762,38 @@ public: The new y position for the cursor. */ 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); };