X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/95b4a59e67af301bb6ff061055ac5a9a09b96d6c..d8efd2198ff050ca5a5726bcad0f42692fe872df:/interface/wx/window.h diff --git a/interface/wx/window.h b/interface/wx/window.h index 518dcb614d..d2ed1799a0 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. */ - virtual void AlwaysShowScrollbars(bool = true, bool = true); + virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true); /** Sets the cached best size value. @@ -600,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); @@ -652,7 +657,7 @@ public: @see FindWindow() */ - static wxWindow* FindWindowById(long id, wxWindow* parent = NULL); + static wxWindow* FindWindowById(long id, const wxWindow* parent = 0); /** Find a window by its label. @@ -666,10 +671,10 @@ public: @see FindWindow() */ static wxWindow* FindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); + const wxWindow* parent = 0); /** - Find a window by its name (as given in a window constructor or @b Create + 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 @@ -682,7 +687,7 @@ public: @see FindWindow() */ static wxWindow* FindWindowByName(const wxString& name, - wxWindow* parent = NULL); + const wxWindow* parent = 0); /** Sizes the window so that it fits around its subwindows. @@ -745,12 +750,6 @@ public: */ wxAccessible* GetAccessible(); - /** - @deprecated - This method is deprecated, use GetEffectiveMinSize() instead. - */ - wxSize GetAdjustedBestSize() const; - /** Returns the background colour of the window. @@ -839,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 +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; /** @@ -1065,28 +1060,34 @@ public: */ 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 - PopupMenu() function for simple menus proposing a choice in a list of - strings to the user. + returns the selected id. - @param menu - The menu to show - @param pos - The position at which to show the menu in client coordinates + 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. - @return The selected menu item id or wxID_NONE if none selected or an - error occurred. - */ - int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); + Notice that to avoid unexpected conflicts between the (usually + consecutive range of) ids used by the menu passed to this function and + the existing EVT_UPDATE_UI() handlers, this function temporarily + disables UI updates for the window, so you need to manually disable + (or toggle or ...) any items which should be disabled in the menu + before showing it. - /** - See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload. - This overload differs only because it takes two integers for the - menu position instead of a wxPoint. + The parameter @a menu is the menu to show. + The parameter @a pos (or the parameters @a x and @a y) is the + position at which to show the menu in client coordinates. + + @return + The selected menu item id or @c wxID_NONE if none selected or an + error occurred. + + @since 2.9.0 */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); + //@} /** This gets the position of the window in pixels, relative to the parent window @@ -1255,7 +1256,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. @@ -1263,7 +1269,6 @@ public: Receives the window virtual height. */ void GetVirtualSize(int* width, int* height) const; - wxSize GetVirtualSize() const; //@} /** @@ -1272,11 +1277,14 @@ public: */ 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. + 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; + long GetWindowStyle() const; + //@} /** Returns the value previously passed to SetWindowVariant(). @@ -1441,9 +1449,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; //@} /** @@ -1504,8 +1512,10 @@ 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 */ @@ -1514,6 +1524,9 @@ public: /** 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(); @@ -1522,7 +1535,7 @@ 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. @@ -1536,6 +1549,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: @@ -1545,13 +1560,15 @@ public: @see SetSize() */ - void Move(int x, int y, int flags = 0); + 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: @@ -1561,7 +1578,7 @@ public: @see SetSize() */ - void Move(const wxPoint& pt, int flags = 0); + void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING); /** Moves this window in the tab navigation order after the specified @e win. @@ -1684,14 +1701,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. @@ -1747,7 +1760,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() */ @@ -1809,8 +1824,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(). @@ -1859,7 +1874,6 @@ public: */ virtual bool Reparent(wxWindow* newParent); - //@{ /** Converts from screen to client window coordinates. @@ -1867,12 +1881,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 @@ -1921,7 +1939,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 @@ -1979,8 +1997,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() */ @@ -2046,13 +2065,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); @@ -2358,7 +2370,10 @@ public: @param thumbSize The size of the thumb, or visible portion of the scrollbar, in scroll units. @param range - The maximum position of the scrollbar. + 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. @@ -2445,6 +2460,17 @@ public: virtual void SetSize(int width, int height); //@} + /** + 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 + */ + 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. @@ -2529,11 +2555,7 @@ public: void SetVirtualSize(const wxSize& size); //@} - /** - Identical to SetWindowStyleFlag(). - */ - void SetWindowStyle(long style); - + //@{ /** Sets the style of the window. Please note that some styles cannot be changed after the window creation and that Refresh() might need to be be called @@ -2544,6 +2566,8 @@ public: @see GetWindowStyleFlag() */ virtual void SetWindowStyleFlag(long style); + void SetWindowStyle(long style); + //@} /** This function can be called under all platforms but only does anything under @@ -2666,7 +2690,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(). @@ -2791,6 +2815,15 @@ 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(); }; @@ -2799,7 +2832,7 @@ protected: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_misc */ +/** @addtogroup group_funcmacro_misc */ //@{ /**