From: Francesco Montorsi Date: Thu, 22 Jan 2009 02:07:08 +0000 (+0000) Subject: a few more member groups, in line with the real header's groups X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/47009083ce5da26c6125fae8947e0615b202a81b a few more member groups, in line with the real header's groups git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58290 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/wx/window.h b/interface/wx/window.h index f8df295621..3bfeaf9b37 100644 --- a/interface/wx/window.h +++ b/interface/wx/window.h @@ -452,7 +452,7 @@ public: /** - @name Scrolling and scrollbars + @name Scrolling and scrollbars functions */ //@{ @@ -641,7 +641,7 @@ public: /** - @name Sizing + @name Sizing functions See also the protected functions DoGetBestSize() and SetInitialBestSize(). */ @@ -837,17 +837,6 @@ public: */ virtual wxSize GetWindowBorderSize() const; - /** - 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; - /** Resets the cached best size value so it will be recalculated the next time it is needed. @@ -1068,34 +1057,6 @@ public: 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. - - 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. - - @remarks SetSizer enables and disables Layout automatically. - */ - void SetSizer(wxSizer* sizer, bool deleteOld = true); - - /** - 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); - /** Sets the virtual size of the window in pixels. */ @@ -1110,7 +1071,7 @@ public: /** - @name Positioning + @name Positioning functions */ //@{ @@ -1253,7 +1214,7 @@ public: /** - @name Coordinate conversion + @name Coordinate conversion functions */ //@{ @@ -1802,7 +1763,7 @@ public: /** - @name Window styles + @name Window styles functions */ //@{ @@ -1858,11 +1819,26 @@ public: */ void SetWindowStyle(long style); + /** + 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). + + Also, please notice that not all styles can be changed after the control + creation. + + @return Returns @true if the style was turned on by this function, @false + if it was switched off. + + @see SetWindowStyleFlag(), HasFlag() + */ + bool ToggleWindowStyle(int flag); + //@} /** - @name Tab order + @name Tab order functions */ //@{ @@ -1920,7 +1896,7 @@ public: /** - @name Z-order + @name Z order functions */ //@{ @@ -1948,7 +1924,7 @@ public: /** - @name Show/hide, enable/disable functions + @name Window status functions */ //@{ @@ -2081,139 +2057,41 @@ public: //@} - // NOTE: static functions must have their own group or Doxygen will screw - // up the ordering of the member groups - /** - @name Static functions + @name Context-sensitive help functions */ //@{ /** - 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); - - /** - Finds the window or control which currently has the keyboard focus. - - @remarks Note that this is a static function, so it can be called without - needing a wxWindow pointer. - - @see SetFocus(), HasFocus() - */ - static wxWindow* FindFocus(); - - /** - Find the first window with the given @e id. - - If @a parent is @NULL, the search will start from all top-level frames - and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. - - @see FindWindow() - */ - static wxWindow* FindWindowById(long id, const wxWindow* parent = 0); - - /** - Find a window by its label. - - Depending on the type of window, the label may be a window title - or panel item label. If @a parent is @NULL, the search will start from all - top-level frames and dialog boxes; if non-@NULL, the search will be - limited to the given window hierarchy. - The search is recursive in both cases. - - @see FindWindow() - */ - static wxWindow* FindWindowByLabel(const wxString& label, - const wxWindow* parent = 0); - - /** - Find a window by its name (as given in a window constructor or Create() - function call). - - If @a parent is @NULL, the search will start from all top-level frames - and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - - The search is recursive in both cases. If no window with such name is found, - FindWindowByLabel() is called. - - @see FindWindow() - */ - static wxWindow* FindWindowByName(const wxString& name, - const wxWindow* parent = 0); - - /** - Returns the currently captured window. + 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 HasCapture(), CaptureMouse(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider */ - static wxWindow* GetCapture(); + wxString GetHelpText() const; /** - 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. + 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 UnreserveControlId(), wxIdManager, - @ref overview_windowids + @see GetHelpText(), wxHelpProvider::AddHelp() */ - static wxWindowID NewControlId(int count = 1); + void SetHelpText(const wxString& helpText); /** - 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); - - //@} - + 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. - /** - @name Tooltip functions + @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; /** Get the associated tooltip or @NULL if none. @@ -2322,190 +2200,66 @@ public: //@} - /** - @name Miscellaneous functions + Validator functions */ //@{ /** - Directs all mouse input to this window. - Call ReleaseMouse() to release the capture. + Returns a pointer to the current validator for the window, or @NULL if + there is none. + */ + virtual wxValidator* GetValidator(); - 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. + /** + 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); - 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. + /** + Transfers values from child controls to data areas specified by their + validators. Returns @false if a transfer failed. - @see ReleaseMouse(), wxMouseCaptureLostEvent + 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() */ - void CaptureMouse(); + virtual bool TransferDataFromWindow(); /** - This function simply generates a wxCloseEvent whose handler usually tries - to close the window. It doesn't close the window itself, however. + Transfers values to child controls from data areas specified by their + validators. - @param force - @false if the window's close handler should be able to veto the destruction - of this window, @true if it cannot. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataToWindow() of all child windows. - @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 + @return Returns @false if a transfer failed. - @see @ref overview_windowdeletion "Window Deletion Overview", - Destroy(), wxCloseEvent + @see TransferDataFromWindow(), wxValidator, Validate() */ - bool Close(bool force = false); + virtual bool TransferDataToWindow(); /** - Destroys the window safely. Use this function instead of the delete operator, - since different window classes can be destroyed differently. Frames and dialogs - are not destroyed immediately when this function is called -- they are added - to a list of windows to be deleted on idle time, when all the window's events - have been processed. This prevents problems with events being sent to - non-existent windows. - - @return @true if the window has either been successfully deleted, or it - has been added to the list of windows pending real deletion. - */ - virtual bool Destroy(); - - /** - Returns true if this window is in process of being destroyed. - - The top level windows are not deleted immediately but are rather - scheduled for later destruction to give them time to process any - pending messages, see Destroy() description. - - This function returns @true if this window, or one of its parent - windows, is scheduled for destruction and can be useful to avoid - manipulating it as it's usually useless to do something with a window - which is on the point of disappearing anyhow. - */ - bool IsBeingDeleted() const; - - /** - Does the window-specific updating after processing the update event. - This function is called by UpdateWindowUI() in order to check return - values in the wxUpdateUIEvent and act appropriately. - For example, to allow frame and dialog title updating, wxWidgets - implements this function as follows: - - @code - // do the window-specific processing after processing the update event - void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) - { - if ( event.GetSetEnabled() ) - Enable(event.GetEnabled()); - - if ( event.GetSetText() ) - { - if ( event.GetText() != GetTitle() ) - SetTitle(event.GetText()); - } - } - @endcode - */ - virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); - - /** - Enables or disables eligibility for drop file events (OnDropFiles). - - @param accept - If @true, the window is eligible for drop file events. - If @false, the window will not accept drop file events. - - @remarks Windows only until version 2.8.9, available on all platforms - since 2.8.10. Cannot be used together with SetDropTarget() on - non-Windows platforms. - - @see SetDropTarget() - */ - virtual void DragAcceptFiles(bool accept); - - /** - Gets the accelerator table for this window. See wxAcceleratorTable. - */ - wxAcceleratorTable* GetAcceleratorTable(); - - /** - Returns the accessible object for this window, if any. - See also wxAccessible. - */ - wxAccessible* GetAccessible(); - - /** - Returns the caret() associated with the window. - */ - wxCaret* GetCaret() const; - - /** - Returns a pointer to the window's layout constraints, or @NULL if there are none. - */ - wxLayoutConstraints* GetConstraints() const; - - /** - Return the cursor associated with this window. - - @see SetCursor() - */ - const wxCursor& GetCursor() const; - - /** - Returns the associated drop target, which may be @NULL. + 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. - @see SetDropTarget(), @ref overview_dnd - */ - virtual wxDropTarget* GetDropTarget() const; + @return Returns @false if any of the validations failed. - /** - 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. + @see TransferDataFromWindow(), TransferDataToWindow(), + wxValidator */ - virtual WXWidget GetHandle() const; + virtual bool Validate(); - /** - 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. + @name wxWindow properties functions */ - virtual wxString GetHelpTextAtPoint(const wxPoint& point, - wxHelpEvent::Origin origin) const; + //@{ /** Returns the identifier of the window. @@ -2542,209 +2296,233 @@ public: */ virtual wxString GetName() const; - /** - Returns a pointer to the current validator for the window, or @NULL if - there is none. - */ - virtual wxValidator* GetValidator(); - /** Returns the value previously passed to SetWindowVariant(). */ wxWindowVariant GetWindowVariant() const; /** - Returns @true if this window has the current mouse capture. + Sets the identifier of the window. - @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent - */ - virtual bool HasCapture() const; + @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. - /** - 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. + @see GetId(), @ref overview_windowids */ - virtual bool HasMultiplePages() const; + void SetId(wxWindowID winid); /** - 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. + Sets the window's label. - 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 label + The window label. - 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 GetLabel() */ - virtual void InheritAttributes(); + virtual void SetLabel(const wxString& label); /** - Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data - to the dialog via validators. - */ - virtual void InitDialog(); + Sets the window's name. - /** - 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. + @param name + A name to set for the window. - @see wxBufferedDC + @see GetName() */ - virtual bool IsDoubleBuffered() const; + virtual void SetName(const wxString& name); /** - Returns @true if the window is retained, @false otherwise. + 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. - @remarks Retained windows are only available on X platforms. + By default the controls use the normal size, of course, but this function can + be used to change this. */ - virtual bool IsRetained() const; + void SetWindowVariant(wxWindowVariant variant); + /** - 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. + Gets the accelerator table for this window. See wxAcceleratorTable. */ - bool IsThisEnabled() const; + wxAcceleratorTable* GetAcceleratorTable(); /** - 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). + Returns the accessible object for this window, if any. + See also wxAccessible. */ - virtual bool IsTopLevel() const; + wxAccessible* GetAccessible(); /** - 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 + Sets the accelerator table for this window. See wxAcceleratorTable. */ - virtual bool Layout(); + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); /** - 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. + Sets the accessible for this window. Any existing accessible for this window + will be deleted first, if not identical to @e accessible. + See also wxAccessible. */ - virtual void MakeModal(bool modal = true); + void SetAccessible(wxAccessible* accessible); - /** - This virtual function is normally only used internally, but - sometimes an application may need it to implement functionality - that should not be disabled by an application defining an OnIdle - handler in a derived class. + //@} - This function may be used to do delayed painting, for example, - and most implementations call UpdateWindowUI() - in order to send update events to the window in idle time. + + /** + @name Window deletion functions */ - virtual void OnInternalIdle(); + //@{ /** - Registers a system wide hotkey. Every time the user presses the hotkey - registered here, this window will receive a hotkey event. + This function simply generates a wxCloseEvent whose handler usually tries + to close the window. It doesn't close the window itself, however. - It will receive the event even if the application is in the background - and does not have the input focus because the user is working with some - other application. + @param force + @false if the window's close handler should be able to veto the destruction + of this window, @true if it cannot. - @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. + @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 - @return @true if the hotkey was registered successfully. @false if some - other application already registered a hotkey with this - modifier/virtualKeyCode combination. + @see @ref overview_windowdeletion "Window Deletion Overview", + Destroy(), wxCloseEvent + */ + bool Close(bool force = false); - @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. + /** + 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. - @see UnregisterHotKey() + @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 RegisterHotKey(int hotkeyId, int modifiers, - int virtualKeyCode); + virtual bool Destroy(); /** - Releases mouse input captured with CaptureMouse(). + Returns true if this window is in process of being destroyed. - @see CaptureMouse(), HasCapture(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + 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 */ - void ReleaseMouse(); + //@{ /** - Sets the accelerator table for this window. See wxAcceleratorTable. + Returns the associated drop target, which may be @NULL. + + @see SetDropTarget(), @ref overview_dnd */ - virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + virtual wxDropTarget* GetDropTarget() const; /** - 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. + Associates a drop target with this window. + If the window already has a drop target, it is deleted. + + @see GetDropTarget(), @ref overview_dnd */ - void SetAccessible(wxAccessible* accessible); + virtual void SetDropTarget(wxDropTarget* target); /** - 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). + Enables or disables eligibility for drop file events (OnDropFiles). - 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 accept + If @true, the window is eligible for drop file events. + If @false, the window will not accept drop file events. - @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). + @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 SetConstraints() + @see SetDropTarget() */ - void SetAutoLayout(bool autoLayout); + virtual void DragAcceptFiles(bool accept); + + //@} + /** - Sets the caret() associated with the window. + @name Constraints, sizers and window layouting functions */ - void SetCaret(wxCaret* caret); + //@{ + + /** + 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. + + @remarks SetSizer enables and disables Layout automatically. + */ + void SetSizer(wxSizer* sizer, bool deleteOld = true); + + /** + 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); + + /** + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints() const; /** Sets the window to have the given layout constraints. The window @@ -2764,6 +2542,99 @@ public: */ void SetConstraints(wxLayoutConstraints* constraints); + + /** + 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(); + + /** + 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. @@ -2779,108 +2650,186 @@ public: virtual bool SetCursor(const wxCursor& cursor); /** - Associates a drop target with this window. - If the window already has a drop target, it is deleted. + Moves the pointer to the given position on the window. - @see GetDropTarget(), @ref overview_dnd + @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 SetDropTarget(wxDropTarget* target); + virtual void WarpPointer(int x, int y); + + //@} + + + /** - 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. + @name Miscellaneous functions + */ + //@{ - @see GetHelpText(), wxHelpProvider::AddHelp() + /** + 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. */ - void SetHelpText(const wxString& helpText); + virtual void InheritAttributes(); /** - 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 + Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data + to the dialog via validators. */ - void SetId(wxWindowID winid); + virtual void InitDialog(); /** - Sets the window's label. - - @param label - The window label. + 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 GetLabel() + @see wxBufferedDC */ - virtual void SetLabel(const wxString& label); + virtual bool IsDoubleBuffered() const; /** - Sets the window's name. - - @param name - A name to set for the window. + Returns @true if the window is retained, @false otherwise. - @see GetName() + @remarks Retained windows are only available on X platforms. */ - virtual void SetName(const wxString& name); + virtual bool IsRetained() const; /** - Deletes the current validator (if any) and sets the window validator, having - called wxValidator::Clone to create a new validator of this type. + 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. */ - virtual void SetValidator(const wxValidator& validator); + bool IsThisEnabled() const; /** - 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. + 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). */ - void SetWindowVariant(wxWindowVariant variant); + virtual bool IsTopLevel() 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). - - Also, please notice that not all styles can be changed after the control - creation. - - @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. @@ -2931,33 +2880,139 @@ 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: /**