/////////////////////////////////////////////////////////////////////////////
-/**
- Background styles. See wxWindow::SetBackgroundStyle().
-*/
-enum wxBackgroundStyle
-{
- /// Use the default background, as determined by
- /// the system or the current theme.
- wxBG_STYLE_SYSTEM,
-
- /// Use a solid colour for the background, this style is set automatically if you call
- /// SetBackgroundColour() so you only need to set it explicitly if you had
- /// changed the background style to something else before.
- wxBG_STYLE_COLOUR,
-
- /// Don't draw the background at all, it's supposed that it is drawn by
- /// the user-defined erase background event handler.
- /// This style should be used to avoid flicker when the background is entirely
- /// custom-drawn.
- wxBG_STYLE_CUSTOM,
-
- /// The background is (partially) transparent,this style is automatically set if you call
- /// SetTransparent() which is used to set the transparency level.
- wxBG_STYLE_TRANSPARENT
-};
-
-
/**
Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
*/
};
-/**
- Flags which can be used in wxWindow::UpdateWindowUI().
-*/
-enum wxUpdateUI
-{
- wxUPDATE_UI_NONE,
- wxUPDATE_UI_RECURSE,
- wxUPDATE_UI_FROMIDLE /**< Invoked from On(Internal)Idle */
-};
-
-
/**
@class wxWindow
*/
virtual ~wxWindow();
+
+ /**
+ @name Focus functions
+
+ See also the static function FindFocus().
+ */
+ //@{
+
/**
This method may be overridden in the derived classes to return @false to
indicate that this control doesn't accept input at all (i.e. behaves like
*/
virtual bool AcceptsFocusRecursively() const;
+ /**
+ Returns @true if the window (or in case of composite controls, its main
+ child window) has focus.
+
+ @see FindFocus()
+ */
+ virtual bool HasFocus() const;
+
+ /**
+ This method is only implemented by ports which have support for
+ native TAB traversal (such as GTK+ 2.0).
+
+ It is called by wxWidgets' container control code to give the native
+ system a hint when doing TAB traversal. A call to this does not disable
+ or change the effect of programmatically calling SetFocus().
+
+ @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
+ */
+ virtual void SetCanFocus(bool canFocus);
+
+ /**
+ This sets the window to receive keyboard input.
+
+ @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
+ wxPanel::SetFocusIgnoringChildren
+ */
+ virtual void SetFocus();
+
+ /**
+ This function is called by wxWidgets keyboard navigation code when the user
+ gives the focus to this window from keyboard (e.g. using @c TAB key).
+
+ By default this method simply calls SetFocus() but
+ can be overridden to do something in addition to this in the derived classes.
+ */
+ virtual void SetFocusFromKbd();
+
+ //@}
+
+
+ /**
+ @name Child management functions
+ */
+ //@{
+
/**
Adds a child window. This is called automatically by window creation
functions so should not be required by the application programmer.
virtual void AddChild(wxWindow* child);
/**
- Call this function to force one or both scrollbars to be always shown, even if
- the window is big enough to show its entire contents without scrolling.
-
- @since 2.9.0
-
- @param hflag
- Whether the horizontal scroll bar should always be visible.
- @param vflag
- Whether the vertical scroll bar should always be visible.
+ Destroys all children of a window. Called automatically by the destructor.
+ */
+ bool DestroyChildren();
- @remarks This function is currently only implemented under Mac/Carbon.
+ /**
+ Find a child of this window, by @a id.
+ May return @a this if it matches itself.
*/
- virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
+ wxWindow* FindWindow(long id) const;
/**
- Sets the cached best size value.
+ Find a child of this window, by name.
+ May return @a this if it matches itself.
*/
- void CacheBestSize(const wxSize& size) const;
+ wxWindow* FindWindow(const wxString& name) const;
/**
- Returns @true if the system supports transparent windows and calling
- SetTransparent() may succeed. If this function returns @false, transparent
- windows are definitely not supported by the current system.
+ Returns a reference to the list of the window's children. @c wxWindowList
+ is a type-safe wxList-like class whose elements are of type @c wxWindow*.
*/
- virtual bool CanSetTransparent();
+ wxWindowList& GetChildren();
/**
- Directs all mouse input to this window.
- Call ReleaseMouse() to release the capture.
+ @overload
+ */
+ const wxWindowList& GetChildren() const;
- 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.
+ /**
+ Removes a child window.
- 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.
+ This is called automatically by window deletion functions so should not
+ be required by the application programmer.
+ Notice that this function is mostly internal to wxWidgets and shouldn't be
+ called by the user code.
- @see ReleaseMouse(), wxMouseCaptureLostEvent
+ @param child
+ Child window to remove.
*/
- void CaptureMouse();
+ virtual void RemoveChild(wxWindow* child);
+
+ //@}
+
/**
- A synonym for Centre().
+ @name Sibling and parent management functions
*/
- void Center(int dir = wxBOTH);
+ //@{
/**
- A synonym for CentreOnParent().
+ Returns the grandparent of a window, or @NULL if there isn't one.
*/
- void CenterOnParent(int dir = wxBOTH);
+ wxWindow* GetGrandParent() const;
/**
- Centres the window.
+ Returns the next window after this one among the parent children or @NULL
+ if this window is the last child.
- @param direction
- Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
- or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
- if you want to center the window on the entire screen and not on its
- parent window.
+ @since 2.8.8
- @remarks If the window is a top level one (i.e. doesn't have a parent),
- it will be centered relative to the screen anyhow.
+ @see GetPrevSibling()
+ */
+ wxWindow* GetNextSibling() const;
- @see Center()
+ /**
+ Returns the parent of the window, or @NULL if there is no parent.
*/
- void Centre(int direction = wxBOTH);
+ wxWindow* GetParent() const;
/**
- Centres the window on its parent. This is a more readable synonym for Centre().
+ Returns the previous window before this one among the parent children or @c
+ @NULL if this window is the first child.
- @param direction
- Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
- or wxBOTH.
+ @since 2.8.8
- @remarks This methods provides for a way to center top level windows over
- their parents instead of the entire screen. If there
- is no parent or if the window is not a top level
- window, then behaviour is the same as Centre().
+ @see GetNextSibling()
+ */
+ wxWindow* GetPrevSibling() const;
+ /**
+ Reparents the window, i.e the window will be removed from its
+ current parent window (e.g. a non-standard toolbar in a wxFrame)
+ and then re-inserted into another.
- @see wxTopLevelWindow::CentreOnScreen
+ @param newParent
+ New parent.
*/
- void CentreOnParent(int direction = wxBOTH);
+ virtual bool Reparent(wxWindow* newParent);
+
+ //@}
+
/**
- Clears the window by filling it with the current background colour. Does not
- cause an erase background event to be generated.
+ @name Scrolling and scrollbars functions
+
+ Note that these methods don't work with native controls which don't use
+ wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).
*/
- virtual void ClearBackground();
+ //@{
/**
- Converts to screen coordinates from coordinates relative to this window.
+ Call this function to force one or both scrollbars to be always shown, even if
+ the window is big enough to show its entire contents without scrolling.
- @param x
- A pointer to a integer value for the x coordinate. Pass the client
- coordinate in, and a screen coordinate will be passed out.
- @param y
- A pointer to a integer value for the y coordinate. Pass the client
- coordinate in, and a screen coordinate will be passed out.
+ @since 2.9.0
- @beginWxPythonOnly
- In place of a single overloaded method name, wxPython implements the following methods:
- - ClientToScreen(point): Accepts and returns a wxPoint
- - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
- @endWxPythonOnly
+ @param hflag
+ Whether the horizontal scroll bar should always be visible.
+ @param vflag
+ Whether the vertical scroll bar should always be visible.
+
+ @remarks This function is currently only implemented under Mac/Carbon.
*/
- void ClientToScreen(int* x, int* y) const;
+ virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
/**
- Converts to screen coordinates from coordinates relative to this window.
+ Returns the built-in scrollbar position.
- @param pt
- The client position for the second form of the function.
+ @see SetScrollbar()
*/
- wxPoint ClientToScreen(const wxPoint& pt) const;
+ virtual int GetScrollPos(int orientation) const;
/**
- Converts client area size @a size to corresponding window size.
+ Returns the built-in scrollbar range.
- In other words, the returned value is what would GetSize() return if this
- window had client area of given size. Components with wxDefaultCoord
- value are left unchanged. Note that the conversion is not always
- exact, it assumes that non-client area doesn't change and so doesn't
- take into account things like menu bar (un)wrapping or (dis)appearance
- of the scrollbars.
+ @see SetScrollbar()
+ */
+ virtual int GetScrollRange(int orientation) const;
- @since 2.8.8
+ /**
+ Returns the built-in scrollbar thumb size.
- @see WindowToClientSize()
+ @see SetScrollbar()
*/
- virtual wxSize ClientToWindowSize(const wxSize& size) const;
+ virtual int GetScrollThumb(int orientation) const;
/**
- Converts window size @a size to corresponding client area size
- In other words, the returned value is what would GetClientSize() return if
- this window had given window size. Components with wxDefaultCoord value
- are left unchanged.
+ Returns @true if this window has a scroll bar for this orientation.
- Note that the conversion is not always exact, it assumes that
- non-client area doesn't change and so doesn't take into account things
- like menu bar (un)wrapping or (dis)appearance of the scrollbars.
+ @param orient
+ Orientation to check, either wxHORIZONTAL or wxVERTICAL.
+ */
+ bool HasScrollbar(int orient) const;
- @since 2.8.8
+ /**
+ Return whether a scrollbar is always shown.
- @see ClientToWindowSize()
+ @param orient
+ Orientation to check, either wxHORIZONTAL or wxVERTICAL.
+
+ @see AlwaysShowScrollbars()
*/
- virtual wxSize WindowToClientSize(const wxSize& size) const;
+ virtual bool IsScrollbarAlwaysShown(int orient) const;
/**
- This function simply generates a wxCloseEvent whose handler usually tries
- to close the window. It doesn't close the window itself, however.
+ Scrolls the window by the given number of lines down (if @a lines is
+ positive) or up.
- @param force
- @false if the window's close handler should be able to veto the destruction
- of this window, @true if it cannot.
+ @return Returns @true if the window was scrolled, @false if it was already
+ on top/bottom and nothing was done.
- @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
+ @remarks This function is currently only implemented under MSW and
+ wxTextCtrl under wxGTK (it also works for wxScrolled classes
+ under all platforms).
- @see @ref overview_windowdeletion "Window Deletion Overview",
- Destroy(), wxCloseEvent
+ @see ScrollPages()
*/
- bool Close(bool force = false);
+ virtual bool ScrollLines(int lines);
- //@{
/**
- Converts a point or size from dialog units to pixels.
+ Scrolls the window by the given number of pages down (if @a pages is
+ positive) or up.
- For the x dimension, the dialog units are multiplied by the average character
- width and then divided by 4.
- For the y dimension, the dialog units are multiplied by the average character
- height and then divided by 8.
+ @return Returns @true if the window was scrolled, @false if it was already
+ on top/bottom and nothing was done.
- @remarks Dialog units are used for maintaining a dialog's proportions
- even if the font changes.
- You can also use these functions programmatically.
- A convenience macro is defined:
- @code
- #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
- @endcode
+ @remarks This function is currently only implemented under MSW and wxGTK.
- @see ConvertPixelsToDialog()
+ @see ScrollLines()
*/
- wxPoint ConvertDialogToPixels(const wxPoint& pt);
- wxSize ConvertDialogToPixels(const wxSize& sz);
- //@}
+ virtual bool ScrollPages(int pages);
- //@{
/**
- Converts a point or size from pixels to dialog units.
+ Physically scrolls the pixels in the window and move child windows accordingly.
- For the x dimension, the pixels are multiplied by 4 and then divided by the
- average character width.
- For the y dimension, the pixels are multiplied by 8 and then divided by the
- average character height.
+ @param dx
+ Amount to scroll horizontally.
+ @param dy
+ Amount to scroll vertically.
+ @param rect
+ Rectangle to scroll, if it is @NULL, the whole window is
+ scrolled (this is always the case under wxGTK which doesn't support this
+ parameter)
- @remarks Dialog units are used for maintaining a dialog's proportions
- even if the font changes.
+ @remarks Note that you can often use wxScrolled instead of using this
+ function directly.
+ */
+ virtual void ScrollWindow(int dx, int dy,
+ const wxRect* rect = NULL);
- @see ConvertDialogToPixels()
+ /**
+ Same as #ScrollLines (-1).
*/
- wxPoint ConvertPixelsToDialog(const wxPoint& pt);
- wxSize ConvertPixelsToDialog(const wxSize& sz);
+ bool LineUp();
+
+ /**
+ Same as #ScrollLines (1).
+ */
+ bool LineDown();
+
+ /**
+ Same as #ScrollPages (-1).
+ */
+ bool PageUp();
+
+ /**
+ Same as #ScrollPages (1).
+ */
+ bool PageDown();
+
+ /**
+ Sets the position of one of the built-in scrollbars.
+
+ @param orientation
+ Determines the scrollbar whose position is to be set.
+ May be wxHORIZONTAL or wxVERTICAL.
+ @param pos
+ Position in scroll units.
+ @param refresh
+ @true to redraw the scrollbar, @false otherwise.
+
+ @remarks This function does not directly affect the contents of the
+ window: it is up to the application to take note of
+ scrollbar attributes and redraw contents accordingly.
+
+ @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
+ wxScrolled
+ */
+ virtual void SetScrollPos(int orientation, int pos,
+ bool refresh = true);
+
+ /**
+ Sets the scrollbar properties of a built-in scrollbar.
+
+ @param orientation
+ Determines the scrollbar whose page size is to be set.
+ May be wxHORIZONTAL or wxVERTICAL.
+ @param position
+ The position of the scrollbar in scroll units.
+ @param thumbSize
+ The size of the thumb, or visible portion of the scrollbar, in scroll units.
+ @param range
+ The maximum position of the scrollbar. Value of -1 can be used to
+ ask for the scrollbar to be shown but in the disabled state: this
+ can be used to avoid removing the scrollbar even when it is not
+ needed (currently this is only implemented in wxMSW port).
+ @param refresh
+ @true to redraw the scrollbar, @false otherwise.
+
+ @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,
+ bool refresh = true);
//@}
+
/**
- 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.
+ @name Sizing functions
- @return @true if the window has either been successfully deleted, or it
- has been added to the list of windows pending real deletion.
+ See also the protected functions DoGetBestSize() and SetInitialBestSize().
*/
- virtual bool Destroy();
+ //@{
/**
- Destroys all children of a window. Called automatically by the destructor.
+ Sets the cached best size value.
+
+ @see GetBestSize()
*/
- bool DestroyChildren();
+ void CacheBestSize(const wxSize& size) const;
/**
- Returns true if this window is in process of being destroyed.
+ Converts client area size @a size to corresponding window size.
- 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.
+ In other words, the returned value is what would GetSize() return if this
+ window had client area of given size. Components with wxDefaultCoord
+ value are left unchanged. Note that the conversion is not always
+ exact, it assumes that non-client area doesn't change and so doesn't
+ take into account things like menu bar (un)wrapping or (dis)appearance
+ of the scrollbars.
- 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;
+ @since 2.8.8
+
+ @see WindowToClientSize()
+ */
+ virtual wxSize ClientToWindowSize(const wxSize& size) const;
/**
- Disables the window. Same as @ref Enable() Enable(@false).
+ Converts window size @a size to corresponding client area size
+ In other words, the returned value is what would GetClientSize() return if
+ this window had given window size. Components with wxDefaultCoord value
+ are left unchanged.
- @return Returns @true if the window has been disabled, @false if it had
- been already disabled before the call to this function.
+ Note that the conversion is not always exact, it assumes that
+ non-client area doesn't change and so doesn't take into account things
+ like menu bar (un)wrapping or (dis)appearance of the scrollbars.
+
+ @since 2.8.8
+
+ @see ClientToWindowSize()
*/
- bool Disable();
+ virtual wxSize WindowToClientSize(const wxSize& size) 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:
+ Sizes the window so that it fits around its subwindows.
- @code
- // do the window-specific processing after processing the update event
- void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
- {
- if ( event.GetSetEnabled() )
- Enable(event.GetEnabled());
+ This function won't do anything if there are no subwindows and will only really
+ work correctly if sizers are used for the subwindows layout.
- if ( event.GetSetText() )
- {
- if ( event.GetText() != GetTitle() )
- SetTitle(event.GetText());
- }
- }
+ Also, if the window has exactly one subwindow it is better (faster and the result
+ is more precise as Fit() adds some margin to account for fuzziness of its calculations)
+ to call:
+
+ @code
+ window->SetClientSize(child->GetSize());
@endcode
+
+ instead of calling Fit().
+
+ @see @ref overview_windowsizing
*/
- virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
+ virtual void Fit();
/**
- Enables or disables eligibility for drop file events (OnDropFiles).
+ Similar to Fit(), but sizes the interior (virtual) size of a window.
- @param accept
- If @true, the window is eligible for drop file events.
- If @false, the window will not accept drop file events.
+ Mainly useful with scrolled windows to reset scrollbars after sizing
+ changes that do not trigger a size event, and/or scrolled windows without
+ an interior sizer. This function similarly won't do anything if there are
+ no subwindows.
+ */
+ virtual void FitInside();
+
+ /**
+ This functions returns the best acceptable minimal size for the window.
+
+ For example, for a static control, it will be the minimal size such that the
+ control label is not truncated. For windows containing subwindows (typically
+ wxPanel), the size returned by this function will be the same as the size
+ the window would have had after calling Fit().
+
+ Note that when you write your own widget you need to overload the
+ DoGetBestSize() function instead of this (non-virtual!) function.
+
+ @see CacheBestSize(), @ref overview_windowsizing
+ */
+ wxSize GetBestSize() const;
+
+ /**
+ 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).
+
+ @see GetSize(), GetVirtualSize()
+ */
+ void GetClientSize(int* width, int* height) const;
+
+ /**
+ @overload
+ */
+ wxSize GetClientSize() const;
+
+ /**
+ Merges the window's best size into the min size and returns the result.
+ This is the value used by sizers to determine the appropriate
+ ammount of space to allocate for the widget.
+
+ This is the method called by any wxSizer when they query the size
+ of a certain window or control.
+
+ @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
+ */
+ virtual wxSize GetEffectiveMinSize() const;
+
+ /**
+ Returns the maximum size of window's client area.
+
+ This is an indication to the sizer layout mechanism that this is the maximum
+ possible size as well as the upper bound on window's size settable using
+ SetClientSize().
+
+ @see GetMaxSize(), @ref overview_windowsizing
+ */
+ virtual wxSize GetMaxClientSize() const;
+
+ /**
+ Returns the maximum size of the window.
+
+ This is an indication to the sizer layout mechanism that this is the maximum
+ possible size as well as the upper bound on window's size settable using SetSize().
+
+ @see GetMaxClientSize(), @ref overview_windowsizing
+ */
+ virtual wxSize GetMaxSize() const;
+
+ /**
+ Returns the minimum size of window's client area, an indication to the sizer
+ layout mechanism that this is the minimum required size of its client area.
+
+ It normally just returns the value set by SetMinClientSize(), but it can be
+ overridden to do the calculation on demand.
+
+ @see GetMinSize(), @ref overview_windowsizing
+ */
+ virtual wxSize GetMinClientSize() const;
+
+ /**
+ Returns the minimum size of the window, an indication to the sizer layout
+ mechanism that this is the minimum required size.
+
+ This method normally just returns the value set by SetMinSize(), but it
+ can be overridden to do the calculation on demand.
+
+ @see GetMinClientSize(), @ref overview_windowsizing
+ */
+ virtual wxSize GetMinSize() const;
+
+ /**
+ Returns the size of the entire window in pixels, including title bar, border,
+ scrollbars, etc.
+
+ Note that if this window is a top-level one and it is currently minimized, the
+ returned size is the restored window size, not the size of the window icon.
+
+ @param width
+ Receives the window width.
+ @param height
+ Receives the window height.
+
+ @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing
+ */
+ void GetSize(int* width, int* height) const;
+
+ /**
+ See the GetSize(int*,int*) overload for more info.
+ */
+ wxSize GetSize() const;
+
+ /**
+ This gets the virtual size of the window in pixels.
+ By default it returns the client size of the window, but after a call to
+ SetVirtualSize() it will return the size set with that method.
+
+ @see @ref overview_windowsizing
+ */
+ wxSize GetVirtualSize() const;
+
+ /**
+ Like the other GetVirtualSize() overload but uses pointers instead.
+
+ @param width
+ Receives the window virtual width.
+ @param height
+ Receives the window virtual height.
+ */
+ void GetVirtualSize(int* width, int* height) const;
+
+ /**
+ Returns the size of the left/right and top/bottom borders of this window in x
+ and y components of the result respectively.
+ */
+ virtual wxSize GetWindowBorderSize() const;
+
+ /**
+ Resets the cached best size value so it will be recalculated the next time it
+ is needed.
+
+ @see CacheBestSize()
+ */
+ void InvalidateBestSize();
+
+ /**
+ Posts a size event to the window.
+
+ This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
+ */
+ void PostSizeEvent();
+
+ /**
+ Posts a size event to the parent of this window.
+
+ This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
+ argument.
+ */
+ void PostSizeEventToParent();
+
+ /**
+ This function sends a dummy @ref wxSizeEvent "size event" to
+ the window allowing it to re-layout its children positions.
+
+ It is sometimes useful to call this function after adding or deleting a
+ children after the frame creation or if a child size changes. Note that
+ if the frame is using either sizers or constraints for the children
+ layout, it is enough to call wxWindow::Layout() directly and this
+ function should not be used in this case.
+
+ If @a flags includes @c wxSEND_EVENT_POST value, this function posts
+ the event, i.e. schedules it for later processing, instead of
+ dispatching it directly. You can also use PostSizeEvent() as a more
+ readable equivalent of calling this function with this flag.
+
+ @param flags
+ May include @c wxSEND_EVENT_POST. Default value is 0.
+ */
+ virtual void SendSizeEvent(int flags = 0);
+
+ /**
+ Safe wrapper for GetParent()->SendSizeEvent().
+
+ This function simply checks that the window has a valid parent which is
+ not in process of being deleted and calls SendSizeEvent() on it. It is
+ used internally by windows such as toolbars changes to whose state
+ should result in parent re-layout (e.g. when a toolbar is added to the
+ top of the window, all the other windows must be shifted down).
+
+ @see PostSizeEventToParent()
+
+ @param flags
+ See description of this parameter in SendSizeEvent() documentation.
+ */
+ void SendSizeEventToParent(int flags = 0);
+
+ /**
+ This sets the size of the window client area in pixels.
+
+ Using this function to size a window tends to be more device-independent
+ than SetSize(), since the application need not worry about what dimensions
+ the border or title bar have when trying to fit the window around panel
+ items, for example.
+
+ @see @ref overview_windowsizing
+ */
+ virtual void SetClientSize(int width, int height);
- @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.
+ /**
+ @overload
+ */
+ virtual void SetClientSize(const wxSize& size);
- @see SetDropTarget()
+ /**
+ This normally does not need to be called by user code.
+ It is called when a window is added to a sizer, and is used so the window
+ can remove itself from the sizer when it is destroyed.
*/
- virtual void DragAcceptFiles(bool accept);
+ void SetContainingSizer(wxSizer* sizer);
/**
- Enable or disable the window for user input. Note that when a parent window is
- disabled, all of its children are disabled as well and they are reenabled again
- when the parent is.
+ A @e smart SetSize that will fill in default size components with the
+ window's @e best size values.
- @param enable
- If @true, enables the window for input. If @false, disables the window.
+ Also sets the window's minsize to the value passed in for use with sizers.
+ This means that if a full or partial size is passed to this function then
+ the sizers will use that size instead of the results of GetBestSize() to
+ determine the minimum needs of the window for layout.
- @return Returns @true if the window has been enabled or disabled, @false
- if nothing was done, i.e. if the window had already
- been in the specified state.
+ Most controls will use this to set their initial size, and their min
+ size to the passed in value (if any.)
- @see IsEnabled(), Disable(), wxRadioBox::Enable
+ @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
+ @ref overview_windowsizing
*/
- virtual bool Enable(bool enable = true);
+ void SetInitialSize(const wxSize& size = wxDefaultSize);
/**
- Finds the window or control which currently has the keyboard focus.
+ Sets the maximum client size of the window, to indicate to the sizer
+ layout mechanism that this is the maximum possible size of its client area.
- @remarks Note that this is a static function, so it can be called without
- needing a wxWindow pointer.
+ Note that this method is just a shortcut for:
+ @code
+ SetMaxSize(ClientToWindowSize(size));
+ @endcode
- @see SetFocus(), HasFocus()
+ @see SetMaxSize(), @ref overview_windowsizing
*/
- static wxWindow* FindFocus();
+ virtual void SetMaxClientSize(const wxSize& size);
/**
- Find a child of this window, by @a id.
- May return @a this if it matches itself.
- */
- wxWindow* FindWindow(long id) const;
+ Sets the maximum size of the window, to indicate to the sizer layout mechanism
+ that this is the maximum possible size.
- /**
- Find a child of this window, by name.
- May return @a this if it matches itself.
+ @see SetMaxClientSize(), @ref overview_windowsizing
*/
- wxWindow* FindWindow(const wxString& name) const;
+ virtual void SetMaxSize(const wxSize& size);
/**
- Find the first window with the given @e id.
+ Sets the minimum client size of the window, to indicate to the sizer
+ layout mechanism that this is the minimum required size of window's client
+ area.
- 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.
+ You may need to call this if you change the window size after
+ construction and before adding to its parent sizer.
- @see FindWindow()
+ Note, that just as with SetMinSize(), calling this method doesn't
+ prevent the program from explicitly making the window smaller than the
+ specified size.
+
+ Note that this method is just a shortcut for:
+ @code
+ SetMinSize(ClientToWindowSize(size));
+ @endcode
+
+ @see SetMinSize(), @ref overview_windowsizing
*/
- static wxWindow* FindWindowById(long id, wxWindow* parent = NULL);
+ virtual void SetMinClientSize(const wxSize& size);
/**
- Find a window by its label.
+ Sets the minimum size of the window, to indicate to the sizer layout
+ mechanism that this is the minimum required size.
- Depending on the type of window, the label may be a window title
- or panel item label. If @a parent is @NULL, the search will start from all
- top-level frames and dialog boxes; if non-@NULL, the search will be
- limited to the given window hierarchy.
- The search is recursive in both cases.
+ You may need to call this if you change the window size after
+ construction and before adding to its parent sizer.
- @see FindWindow()
+ Notice that calling this method doesn't prevent the program from making
+ the window explicitly smaller than the specified size by calling
+ SetSize(), it just ensures that it won't become smaller than this size
+ during the automatic layout.
+
+ @see SetMinClientSize(), @ref overview_windowsizing
*/
- static wxWindow* FindWindowByLabel(const wxString& label,
- wxWindow* parent = NULL);
+ virtual void SetMinSize(const wxSize& size);
/**
- Find a window by its name (as given in a window constructor or @b Create
- function call).
+ Sets the size of the window in pixels.
- 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.
+ @param x
+ Required x position in pixels, or wxDefaultCoord to indicate that the
+ existing value should be used.
+ @param y
+ Required y position in pixels, or wxDefaultCoord to indicate that the
+ existing value should be used.
+ @param width
+ Required width in pixels, or wxDefaultCoord to indicate that the existing
+ value should be used.
+ @param height
+ Required height position in pixels, or wxDefaultCoord to indicate that the
+ existing value should be used.
+ @param sizeFlags
+ Indicates the interpretation of other parameters.
+ It is a bit list of the following:
+ - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
+ a wxWidgets-supplied default width.
+ - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
+ a wxWidgets-supplied default height.
+ - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
+ a wxWidgets-supplied default size.
+ - @c wxSIZE_USE_EXISTING: existing dimensions should be used
+ if wxDefaultCoord values are supplied.
+ - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
+ wxDefaultCoord) to be interpreted as real
+ dimensions, not default values.
+ - @c wxSIZE_FORCE: normally, if the position and the size of the window are
+ already the same as the parameters of this function,
+ nothing is done. but with this flag a window resize may
+ be forced even in this case (supported in wx 2.6.2 and
+ later and only implemented for MSW and ignored elsewhere
+ currently).
- The search is recursive in both cases. If no window with such name is found,
- FindWindowByLabel() is called.
+ @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 FindWindow()
+ @see Move(), @ref overview_windowsizing
*/
- static wxWindow* FindWindowByName(const wxString& name,
- wxWindow* parent = NULL);
+ void SetSize(int x, int y, int width, int height,
+ int sizeFlags = wxSIZE_AUTO);
/**
- Sizes the window so that it fits around its subwindows.
-
- This function won't do anything if there are no subwindows and will only really
- work correctly if sizers are used for the subwindows layout.
+ Sets the size of the window in pixels.
+ The size is specified using a wxRect, wxSize or by a couple of @c int objects.
- Also, if the window has exactly one subwindow it is better (faster and the result
- is more precise as Fit() adds some margin to account for fuzziness of its calculations)
- to call:
+ @remarks This form must be used with non-default width and height values.
- @code
- window->SetClientSize(child->GetSize());
- @endcode
+ @see Move(), @ref overview_windowsizing
+ */
+ virtual void SetSize(const wxRect& rect);
- instead of calling Fit().
+ /**
+ @overload
+ */
+ virtual void SetSize(const wxSize& size);
- @see @ref overview_windowsizing
+ /**
+ @overload
*/
- virtual void Fit();
+ virtual void SetSize(int width, int height);
/**
- Similar to Fit(), but sizes the interior (virtual) size of a window.
+ Use of this function for windows which are not toplevel windows
+ (such as wxDialog or wxFrame) is discouraged.
+ Please use SetMinSize() and SetMaxSize() instead.
- Mainly useful with scrolled windows to reset scrollbars after sizing
- changes that do not trigger a size event, and/or scrolled windows without
- an interior sizer. This function similarly won't do anything if there are
- no subwindows.
+ @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
*/
- virtual void FitInside();
+ void SetSizeHints( const wxSize& minSize,
+ const wxSize& maxSize=wxDefaultSize,
+ const wxSize& incSize=wxDefaultSize);
/**
- Freezes the window or, in other words, prevents any updates from taking
- place on screen, the window is not redrawn at all.
+ Sets the virtual size of the window in pixels.
- Thaw() must be called to reenable window redrawing. Calls to these two
- functions may be nested but to ensure that the window is properly
- repainted again, you must thaw it exactly as many times as you froze it.
+ @see @ref overview_windowsizing
+ */
+ void SetVirtualSize(int width, int height);
- If the window has any children, they are recursively frozen too.
+ /**
+ @overload
+ */
+ void SetVirtualSize(const wxSize& size);
- This method is useful for visual appearance optimization (for example,
- it is a good idea to use it before doing many large text insertions in
- a row into a wxTextCtrl under wxGTK) but is not implemented on all
- platforms nor for all controls so it is mostly just a hint to wxWidgets
- and not a mandatory directive.
+ //@}
- @see wxWindowUpdateLocker, Thaw(), IsFrozen()
- */
- void Freeze();
/**
- Gets the accelerator table for this window. See wxAcceleratorTable.
+ @name Positioning functions
*/
- wxAcceleratorTable* GetAcceleratorTable();
+ //@{
/**
- Returns the accessible object for this window, if any.
- See also wxAccessible.
+ A synonym for Centre().
*/
- wxAccessible* GetAccessible();
+ void Center(int dir = wxBOTH);
/**
- Returns the background colour of the window.
-
- @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
+ A synonym for CentreOnParent().
*/
- wxColour GetBackgroundColour() const;
+ void CenterOnParent(int dir = wxBOTH);
/**
- Returns the background style of the window.
- The background style can be one of the wxBackgroundStyle.
+ Centres the window.
- @see SetBackgroundColour(), GetForegroundColour(),
- SetBackgroundStyle(), SetTransparent()
+ @param direction
+ Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
+ or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag
+ if you want to center the window on the entire screen and not on its
+ parent window.
+
+ @remarks If the window is a top level one (i.e. doesn't have a parent),
+ it will be centered relative to the screen anyhow.
+
+ @see Center()
*/
- virtual wxBackgroundStyle GetBackgroundStyle() const;
+ void Centre(int direction = wxBOTH);
/**
- This functions returns the best acceptable minimal size for the window.
+ Centres the window on its parent. This is a more readable synonym for Centre().
- For example, for a static control, it will be the minimal size such that the
- control label is not truncated. For windows containing subwindows (typically
- wxPanel), the size returned by this function will be the same as the size
- the window would have had after calling Fit().
- */
- wxSize GetBestSize() const;
+ @param direction
+ Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
+ or wxBOTH.
+ @remarks This methods provides for a way to center top level windows over
+ their parents instead of the entire screen. If there
+ is no parent or if the window is not a top level
+ window, then behaviour is the same as Centre().
+
+ @see wxTopLevelWindow::CentreOnScreen
+ */
+ void CentreOnParent(int direction = wxBOTH);
/**
- Returns the currently captured window.
+ 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 HasCapture(), CaptureMouse(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ @param x
+ Receives the x position of the window if non-@NULL.
+ @param y
+ Receives the y position of the window if non-@NULL.
+
+ @see GetScreenPosition()
*/
- static wxWindow* GetCapture();
+ 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.
- /**
- Returns the caret() associated with the window.
+ @see GetScreenPosition()
*/
- wxCaret* GetCaret() const;
+ wxPoint GetPosition() const;
/**
- Returns the character height for this window.
+ Returns the position and size of the window as a wxRect object.
+
+ @see GetScreenRect()
*/
- virtual int GetCharHeight() const;
+ wxRect GetRect() const;
/**
- Returns the average character width for this window.
+ Returns the window position in screen coordinates, whether the window is a
+ child window or a top level one.
+
+ @param x
+ Receives the x position of the window on the screen if non-@NULL.
+ @param y
+ Receives the y position of the window on the screen if non-@NULL.
+
+ @see GetPosition()
*/
- virtual int GetCharWidth() const;
+ void GetScreenPosition(int* x, int* y) const;
- //@{
/**
- Returns a reference to the list of the window's children. @c wxWindowList
- is a type-safe wxList-like class whose elements are of type @c wxWindow*.
+ Returns the window position in screen coordinates, whether the window is a
+ child window or a top level one.
+
+ @see GetPosition()
*/
- wxWindowList& GetChildren();
- const wxWindowList& GetChildren() const;
- //@}
+ wxPoint GetScreenPosition() const;
/**
- Returns the default font and colours which are used by the control.
+ Returns the position and size of the window on the screen as a wxRect object.
- 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.
+ @see GetRect()
+ */
+ wxRect GetScreenRect() const;
- 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.
+ /**
+ Moves the window to the given position.
- 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().
+ @param x
+ Required x position.
+ @param y
+ Required y position.
+ @param flags
+ See SetSize() for more info about this parameter.
- 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.
+ @remarks Implementations of SetSize can also implicitly implement the
+ Move() function, which is defined in the base wxWindow class as the call:
+ @code
+ SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
+ @endcode
- @see InheritAttributes()
+ @see SetSize()
*/
- static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
+ void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);
- //@{
/**
- Returns the size of the window 'client area' in pixels.
+ Moves the window to the given position.
- 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 pt
+ wxPoint object representing the position.
+ @param flags
+ See SetSize() for more info about this parameter.
- @see GetSize(), GetVirtualSize()
- */
- void GetClientSize(int* width, int* height) const;
- wxSize GetClientSize() const;
- //@}
+ @remarks Implementations of SetSize() can also implicitly implement the
+ Move() function, which is defined in the base wxWindow class as the call:
+ @code
+ SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
+ @endcode
- /**
- Returns a pointer to the window's layout constraints, or @NULL if there are none.
+ @see SetSize()
*/
- wxLayoutConstraints* GetConstraints() const;
+ void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
- /**
- Return the sizer that this window is a member of, if any, otherwise @NULL.
- */
- wxSizer* GetContainingSizer() const;
+ //@}
- /**
- Return the cursor associated with this window.
- @see SetCursor()
+ /**
+ @name Coordinate conversion functions
*/
- const wxCursor& GetCursor() const;
+ //@{
/**
- Currently this is the same as calling
- wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
+ Converts to screen coordinates from coordinates relative to this window.
- One advantage of using this function compared to the static version is that
- the call is automatically dispatched to the correct class (as usual with
- virtual functions) and you don't have to specify the class name explicitly.
+ @param x
+ A pointer to a integer value for the x coordinate. Pass the client
+ coordinate in, and a screen coordinate will be passed out.
+ @param y
+ A pointer to a integer value for the y coordinate. Pass the client
+ coordinate in, and a screen coordinate will be passed out.
- The other one is that in the future this function could return different
- results, for example it might return a different font for an "Ok" button
- than for a generic button if the users GUI is configured to show such buttons
- in bold font. Of course, the down side is that it is impossible to call this
- function without actually having an object to apply it to whereas the static
- version can be used without having to create an object first.
+ @beginWxPythonOnly
+ In place of a single overloaded method name, wxPython implements the following methods:
+ - ClientToScreen(point): Accepts and returns a wxPoint
+ - ClientToScreenXY(x, y): Returns a 2-tuple, (x, y)
+ @endWxPythonOnly
*/
- virtual wxVisualAttributes GetDefaultAttributes() const;
+ void ClientToScreen(int* x, int* y) const;
/**
- Returns the associated drop target, which may be @NULL.
+ Converts to screen coordinates from coordinates relative to this window.
- @see SetDropTarget(), @ref overview_dnd
+ @param pt
+ The client position for the second form of the function.
*/
- virtual wxDropTarget* GetDropTarget() const;
+ wxPoint ClientToScreen(const wxPoint& pt) const;
/**
- Merges the window's best size into the min size and returns the result.
- This is the value used by sizers to determine the appropriate
- ammount of space to allocate for the widget.
-
- @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
- */
- wxSize GetEffectiveMinSize() const;
+ Converts a point or size from dialog units to pixels.
- /**
- Returns the event handler for this window.
- By default, the window is its own event handler.
+ For the x dimension, the dialog units are multiplied by the average character
+ width and then divided by 4.
+ For the y dimension, the dialog units are multiplied by the average character
+ height and then divided by 8.
- @see SetEventHandler(), PushEventHandler(),
- PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
- */
- wxEvtHandler* GetEventHandler() const;
+ @remarks Dialog units are used for maintaining a dialog's proportions
+ even if the font changes.
+ You can also use these functions programmatically.
+ A convenience macro is defined:
+ @code
+ #define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
+ @endcode
- /**
- Returns the extra style bits for the window.
+ @see ConvertPixelsToDialog()
*/
- long GetExtraStyle() const;
+ wxPoint ConvertDialogToPixels(const wxPoint& pt);
/**
- Returns the font for this window.
-
- @see SetFont()
+ @overload
*/
- wxFont GetFont() const;
+ wxSize ConvertDialogToPixels(const wxSize& sz);
/**
- Returns the foreground colour of the window.
+ Converts a point or size from pixels to dialog units.
- @remarks The interpretation of foreground colour is open to
- interpretation according to the window class; it may be
- the text colour or other colour, or it may not be used at all.
+ For the x dimension, the pixels are multiplied by 4 and then divided by the
+ average character width.
+ For the y dimension, the pixels are multiplied by 8 and then divided by the
+ average character height.
- @see SetForegroundColour(), SetBackgroundColour(),
- GetBackgroundColour()
- */
- wxColour GetForegroundColour() const;
+ @remarks Dialog units are used for maintaining a dialog's proportions
+ even if the font changes.
- /**
- Returns the grandparent of a window, or @NULL if there isn't one.
+ @see ConvertDialogToPixels()
*/
- wxWindow* GetGrandParent() const;
+ wxPoint ConvertPixelsToDialog(const wxPoint& pt);
/**
- 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.
+ @overload
*/
- virtual WXWidget GetHandle() const;
+ wxSize ConvertPixelsToDialog(const wxSize& sz);
/**
- 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.
+ Converts from screen to client window coordinates.
- @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
+ @param x
+ Stores the screen x coordinate and receives the client x coordinate.
+ @param y
+ Stores the screen x coordinate and receives the client x coordinate.
*/
- wxString GetHelpText() const;
+ void ScreenToClient(int* x, int* y) 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.
+ Converts from screen to client window coordinates.
- @param point
- Coordinates of the mouse at the moment of help event emission.
- @param origin
- Help event origin, see also wxHelpEvent::GetOrigin.
+ @param pt
+ The screen position.
*/
- virtual wxString GetHelpTextAtPoint(const wxPoint& point,
- wxHelpEvent::Origin origin) const;
+ wxPoint ScreenToClient(const wxPoint& pt) const;
- /**
- Returns the identifier of the window.
+ //@}
- @remarks Each window has an integer identifier. If the application
- has not provided one (or the default wxID_ANY) an unique
- identifier with a negative value will be generated.
- @see SetId(), @ref overview_windowids
+ /**
+ @name Drawing-related functions
*/
- wxWindowID GetId() const;
+ //@{
/**
- Generic way of getting a label from any window, for
- identification purposes.
-
- @remarks The interpretation of this function differs from class to class.
- For frames and dialogs, the value returned is the
- title. For buttons or static text controls, it is the
- button text. This function can be useful for
- meta-programs (such as testing tools or special-needs
- access programs) which need to identify windows by name.
+ Clears the window by filling it with the current background colour. Does not
+ cause an erase background event to be generated.
*/
- virtual wxString GetLabel() const;
+ virtual void ClearBackground();
/**
- Returns the maximum size of window's client area.
-
- This is an indication to the sizer layout mechanism that this is the maximum
- possible size as well as the upper bound on window's size settable using
- SetClientSize().
+ Freezes the window or, in other words, prevents any updates from taking
+ place on screen, the window is not redrawn at all.
- @see GetMaxSize()
- */
- virtual wxSize GetMaxClientSize() const;
+ Thaw() must be called to reenable window redrawing. Calls to these two
+ functions may be nested but to ensure that the window is properly
+ repainted again, you must thaw it exactly as many times as you froze it.
- /**
- Returns the maximum size of the window.
+ If the window has any children, they are recursively frozen too.
- This is an indication to the sizer layout mechanism that this is the maximum
- possible size as well as the upper bound on window's size settable using SetSize().
+ This method is useful for visual appearance optimization (for example,
+ it is a good idea to use it before doing many large text insertions in
+ a row into a wxTextCtrl under wxGTK) but is not implemented on all
+ platforms nor for all controls so it is mostly just a hint to wxWidgets
+ and not a mandatory directive.
- @see GetMaxClientSize()
+ @see wxWindowUpdateLocker, Thaw(), IsFrozen()
*/
- virtual wxSize GetMaxSize() const;
+ void Freeze();
/**
- Returns the minimum size of window's client area, an indication to the sizer
- layout mechanism that this is the minimum required size of its client area.
+ Reenables window updating after a previous call to Freeze().
- It normally just returns the value set by SetMinClientSize(), but it can be
- overridden to do the calculation on demand.
+ To really thaw the control, it must be called exactly the same number
+ of times as Freeze().
+
+ If the window has any children, they are recursively thawn too.
- @see GetMinSize()
+ @see wxWindowUpdateLocker, Freeze(), IsFrozen()
*/
- virtual wxSize GetMinClientSize() const;
+ void Thaw();
/**
- Returns the minimum size of the window, an indication to the sizer layout
- mechanism that this is the minimum required size.
-
- This method normally just returns the value set by SetMinSize(), but it
- can be overridden to do the calculation on demand.
+ Returns @true if the window is currently frozen by a call to Freeze().
- @see GetMinClientSize()
+ @see Freeze(), Thaw()
*/
- virtual wxSize GetMinSize() const;
+ bool IsFrozen() const;
/**
- Returns the window's name.
-
- @remarks This name is not guaranteed to be unique; it is up to the
- programmer to supply an appropriate name in the window
- constructor or via SetName().
+ Returns the background colour of the window.
- @see SetName()
+ @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
*/
- virtual wxString GetName() const;
+ wxColour GetBackgroundColour() const;
/**
- Returns the next window after this one among the parent children or @NULL
- if this window is the last child.
-
- @since 2.8.8
+ Returns the background style of the window.
+ The background style can be one of the wxBackgroundStyle.
- @see GetPrevSibling()
+ @see SetBackgroundColour(), GetForegroundColour(),
+ SetBackgroundStyle(), SetTransparent()
*/
- wxWindow* GetNextSibling() const;
+ virtual wxBackgroundStyle GetBackgroundStyle() const;
+ /**
+ Returns the character height for this window.
+ */
+ virtual int GetCharHeight() const;
/**
- Returns the parent of the window, or @NULL if there is no parent.
+ Returns the average character width for this window.
*/
- wxWindow* GetParent() const;
+ virtual int GetCharWidth() 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.
+ Currently this is the same as calling
+ wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
- @param menu
- The menu to show
- @param pos
- The position at which to show the menu in client coordinates
+ One advantage of using this function compared to the static version is that
+ the call is automatically dispatched to the correct class (as usual with
+ virtual functions) and you don't have to specify the class name explicitly.
- @return The selected menu item id or wxID_NONE if none selected or an
- error occurred.
+ The other one is that in the future this function could return different
+ results, for example it might return a different font for an "Ok" button
+ than for a generic button if the users GUI is configured to show such buttons
+ in bold font. Of course, the down side is that it is impossible to call this
+ function without actually having an object to apply it to whereas the static
+ version can be used without having to create an object first.
*/
- int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
+ virtual wxVisualAttributes GetDefaultAttributes() const;
/**
- See the GetPopupMenuSelectionFromUser(wxMenu&, const wxPoint&) overload.
- This overload differs only because it takes two integers for the
- menu position instead of a wxPoint.
+ Returns the font for this window.
+
+ @see SetFont()
*/
- int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
+ wxFont GetFont() 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.
+ Returns the foreground colour of the window.
- @param x
- Receives the x position of the window if non-@NULL.
- @param y
- Receives the y position of the window if non-@NULL.
+ @remarks The interpretation of foreground colour is open to
+ interpretation according to the window class; it may be
+ the text colour or other colour, or it may not be used at all.
- @see GetScreenPosition()
+ @see SetForegroundColour(), SetBackgroundColour(),
+ GetBackgroundColour()
*/
- void GetPosition(int* x, int* y) const;
+ wxColour GetForegroundColour() 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.
+ Gets the dimensions of the string as it would be drawn on the
+ window with the currently selected font.
- @see GetScreenPosition()
+ The text extent is returned in @a w and @a h pointers.
+
+ @param string
+ String whose extent is to be measured.
+ @param w
+ Return value for width.
+ @param h
+ Return value for height.
+ @param descent
+ Return value for descent (optional).
+ @param externalLeading
+ Return value for external leading (optional).
+ @param font
+ Font to use instead of the current window font (optional).
*/
- wxPoint GetPosition() const;
+ virtual void GetTextExtent(const wxString& string, int* w, int* h,
+ int* descent = NULL,
+ int* externalLeading = NULL,
+ const wxFont* font = NULL) const;
/**
- Returns the previous window before this one among the parent children or @c
- @NULL if this window is the first child.
+ 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;
- @since 2.8.8
+ /**
+ Returns the region specifying which parts of the window have been damaged.
+ Should only be called within an wxPaintEvent handler.
- @see GetNextSibling()
+ @see wxRegion, wxRegionIterator
*/
- wxWindow* GetPrevSibling() const;
+ const wxRegion& GetUpdateRegion() const;
/**
- Returns the position and size of the window as a wxRect object.
+ Returns @true if this window background is transparent (as, for example,
+ for wxStaticText) and should show the parent window background.
- @see GetScreenRect()
+ This method is mostly used internally by the library itself and you normally
+ shouldn't have to call it. You may, however, have to override it in your
+ wxWindow-derived class to ensure that background is painted correctly.
*/
- wxRect GetRect() const;
+ virtual bool HasTransparentBackground();
/**
- Returns the window position in screen coordinates, whether the window is a
- child window or a top level one.
+ Causes this window, and all of its children recursively (except under wxGTK1
+ where this is not implemented), to be repainted. Note that repainting doesn't
+ happen immediately but only during the next event loop iteration, if you need
+ to update the window immediately you should use Update() instead.
- @param x
- Receives the x position of the window on the screen if non-@NULL.
- @param y
- Receives the y position of the window on the screen if non-@NULL.
+ @param eraseBackground
+ If @true, the background will be erased.
+ @param rect
+ If non-@NULL, only the given rectangle will be treated as damaged.
- @see GetPosition()
+ @see RefreshRect()
*/
- void GetScreenPosition(int* x, int* y) const;
+ virtual void Refresh(bool eraseBackground = true,
+ const wxRect* rect = NULL);
/**
- Returns the window position in screen coordinates, whether the window is a
- child window or a top level one.
+ Redraws the contents of the given rectangle: only the area inside it will be
+ repainted.
- @see GetPosition()
+ This is the same as Refresh() but has a nicer syntax as it can be called
+ with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
*/
- wxPoint GetScreenPosition() const;
+ void RefreshRect(const wxRect& rect, bool eraseBackground = true);
/**
- Returns the position and size of the window on the screen as a wxRect object.
+ Calling this method immediately repaints the invalidated area of the window and
+ all of its children recursively while this would usually only happen when the
+ flow of control returns to the event loop.
- @see GetRect()
+ Notice that this function doesn't invalidate any area of the window so
+ nothing happens if nothing has been invalidated (i.e. marked as requiring
+ a redraw). Use Refresh() first if you want to immediately redraw the
+ window unconditionally.
*/
- wxRect GetScreenRect() const;
+ virtual void Update();
/**
- Returns the built-in scrollbar position.
+ Sets the background colour of the window.
+ Please see InheritAttributes() for explanation of the difference between
+ this method and SetOwnBackgroundColour().
- @see See SetScrollbar()
+ @param colour
+ The colour to be used as the background colour, pass
+ wxNullColour to reset to the default colour.
+
+ @remarks The background colour is usually painted by the default
+ wxEraseEvent event handler function under Windows and
+ automatically under GTK.
+ Note that setting the background colour does not cause an
+ immediate refresh, so you may wish to call wxWindow::ClearBackground
+ or wxWindow::Refresh after calling this function.
+ Using this function will disable attempts to use themes for
+ this window, if the system supports them. Use with care since
+ usually the themes represent the appearance chosen by the user
+ to be used for all applications on the system.
+
+ @see GetBackgroundColour(), SetForegroundColour(),
+ GetForegroundColour(), ClearBackground(),
+ Refresh(), wxEraseEvent
*/
- virtual int GetScrollPos(int orientation) const;
+ virtual bool SetBackgroundColour(const wxColour& colour);
/**
- Returns the built-in scrollbar range.
+ Sets the background style of the window. see GetBackgroundStyle() for
+ the description of the possible style values.
- @see SetScrollbar()
+ @see SetBackgroundColour(), GetForegroundColour(),
+ SetTransparent()
*/
- virtual int GetScrollRange(int orientation) const;
+ virtual bool SetBackgroundStyle(wxBackgroundStyle style);
/**
- Returns the built-in scrollbar thumb size.
+ Sets the font for this window. This function should not be called for the
+ parent window if you don't want its font to be inherited by its children,
+ use SetOwnFont() instead in this case and see InheritAttributes() for more
+ explanations.
- @see SetScrollbar()
+ Please notice that the given font is not automatically used for
+ wxPaintDC objects associated with this window, you need to
+ call wxDC::SetFont too. However this font is used by
+ any standard controls for drawing their text as well as by
+ GetTextExtent().
+
+ @param font
+ Font to associate with this window, pass
+ wxNullFont to reset to the default font.
+
+ @return @true if the want was really changed, @false if it was already set
+ to this font and so nothing was done.
+
+ @see GetFont(), InheritAttributes()
*/
- virtual int GetScrollThumb(int orientation) const;
+ virtual bool SetFont(const wxFont& font);
/**
- Returns the size of the entire window in pixels, including title bar, border,
- scrollbars, etc.
+ Sets the foreground colour of the window.
+ Please see InheritAttributes() for explanation of the difference between
+ this method and SetOwnForegroundColour().
- Note that if this window is a top-level one and it is currently minimized, the
- returned size is the restored window size, not the size of the window icon.
+ @param colour
+ The colour to be used as the foreground colour, pass
+ wxNullColour to reset to the default colour.
- @param width
- Receives the window width.
- @param height
- Receives the window height.
+ @remarks The interpretation of foreground colour is open to
+ interpretation according to the window class; it may be
+ the text colour or other colour, or it may not be used at all.
- @see GetClientSize(), GetVirtualSize()
+ @see GetForegroundColour(), SetBackgroundColour(),
+ GetBackgroundColour(), ShouldInheritColours()
*/
- void GetSize(int* width, int* height) const;
+ virtual bool SetForegroundColour(const wxColour& colour);
/**
- See the GetSize(int*,int*) overload for more info.
- */
- wxSize GetSize() const;
+ Sets the background colour of the window but prevents it from being inherited
+ by the children of this window.
- /**
- Return the sizer associated with the window by a previous call to
- SetSizer() or @NULL.
+ @see SetBackgroundColour(), InheritAttributes()
*/
- wxSizer* GetSizer() const;
+ void SetOwnBackgroundColour(const wxColour& colour);
/**
- Gets the dimensions of the string as it would be drawn on the
- window with the currently selected font.
-
- The text extent is returned in @a w and @a h pointers.
+ Sets the font of the window but prevents it from being inherited by the
+ children of this window.
- @param string
- String whose extent is to be measured.
- @param w
- Return value for width.
- @param h
- Return value for height.
- @param descent
- Return value for descent (optional).
- @param externalLeading
- Return value for external leading (optional).
- @param font
- Font to use instead of the current window font (optional).
+ @see SetFont(), InheritAttributes()
*/
- virtual void GetTextExtent(const wxString& string, int* w, int* h,
- int* descent = NULL,
- int* externalLeading = NULL,
- const wxFont* font = NULL) const;
+ void SetOwnFont(const wxFont& font);
/**
- Gets the dimensions of the string as it would be drawn on the
- window with the currently selected font.
+ Sets the foreground colour of the window but prevents it from being inherited
+ by the children of this window.
+
+ @see SetForegroundColour(), InheritAttributes()
*/
- wxSize GetTextExtent(const wxString& string) const;
+ void SetOwnForegroundColour(const wxColour& colour);
/**
- Get the associated tooltip or @NULL if none.
+ @deprecated use wxDC::SetPalette instead.
*/
- wxToolTip* GetToolTip() const;
+ void SetPalette(const wxPalette& pal);
/**
- Returns the region specifying which parts of the window have been damaged.
- Should only be called within an wxPaintEvent handler.
+ Return @true from here to allow the colours of this window to be changed by
+ InheritAttributes(), returning @false forbids inheriting them from the parent window.
- @see wxRegion, wxRegionIterator
+ The base class version returns @false, but this method is overridden in
+ wxControl where it returns @true.
*/
- const wxRegion& GetUpdateRegion() const;
+ virtual bool ShouldInheritColours() const;
/**
- Returns a pointer to the current validator for the window, or @NULL if
- there is none.
+ This function tells a window if it should use the system's "theme" code
+ to draw the windows' background instead if its own background drawing
+ code. This does not always have any effect since the underlying platform
+ obviously needs to support the notion of themes in user defined windows.
+ One such platform is GTK+ where windows can have (very colourful) backgrounds
+ defined by a user's selected theme.
+
+ Dialogs, notebook pages and the status bar have this flag set to @true
+ by default so that the default look and feel is simulated best.
*/
- virtual wxValidator* GetValidator();
+ virtual void SetThemeEnabled(bool enable);
- //@{
/**
- This gets the virtual size of the window in pixels.
- By default it returns the client size of the window, but after a call to
- SetVirtualSize() it will return the size set with that method.
+ Returns @true if the system supports transparent windows and calling
+ SetTransparent() may succeed. If this function returns @false, transparent
+ windows are definitely not supported by the current system.
*/
- wxSize GetVirtualSize() const;
+ virtual bool CanSetTransparent();
/**
- Like the other GetVirtualSize() overload but uses pointers instead.
+ Set the transparency of the window. If the system supports transparent windows,
+ returns @true, otherwise returns @false and the window remains fully opaque.
+ See also CanSetTransparent().
- @param width
- Receives the window virtual width.
- @param height
- Receives the window virtual height.
+ The parameter @a alpha is in the range 0..255 where 0 corresponds to a
+ fully transparent window and 255 to the fully opaque one. The constants
+ @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
*/
- void GetVirtualSize(int* width, int* height) const;
+ virtual bool SetTransparent(wxByte alpha);
+
//@}
- /**
- Returns the size of the left/right and top/bottom borders of this window in x
- and y components of the result respectively.
- */
- 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.
+ @name Event-handling functions
+
+ wxWindow allows you to build a (sort of) stack of event handlers which
+ can be used to override the window's own event handling.
*/
- virtual long GetWindowStyleFlag() const;
+ //@{
/**
- Returns the value previously passed to SetWindowVariant().
+ Returns the event handler for this window.
+ By default, the window is its own event handler.
+
+ @see SetEventHandler(), PushEventHandler(),
+ PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
*/
- wxWindowVariant GetWindowVariant() const;
+ wxEvtHandler* GetEventHandler() const;
/**
- This function will generate the appropriate call to
- Navigate() if the key event is one normally used for
- keyboard navigation and return @true in this case.
+ This function will generate the appropriate call to Navigate() if the key
+ event is one normally used for keyboard navigation and return @true in this case.
@return Returns @true if the key pressed was for navigation and was
handled, @false otherwise.
@code
GetEventHandler()->SafelyProcessEvent(event);
@endcode
+
+ @see ProcessWindowEvent()
*/
bool HandleWindowEvent(wxEvent& event) const;
/**
- Returns @true if this window has the current mouse capture.
+ Convenient wrapper for ProcessEvent().
- @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
- wxMouseCaptureChangedEvent
+ This is the same as writing @code GetEventHandler()->ProcessEvent(event);
+ @endcode but more convenient. Notice that ProcessEvent() itself can't
+ be called for wxWindow objects as it ignores the event handlers
+ associated with the window, use this function instead.
*/
- virtual bool HasCapture() const;
+ bool ProcessWindowEvent(wxEvent& event);
/**
- Returns @true if the window has the given @a exFlag bit set in its
- extra styles.
+ Removes and returns the top-most event handler on the event handler stack.
- @see SetExtraStyle()
- */
- bool HasExtraStyle(int exFlag) const;
+ E.g. in the case of:
+ @image html overview_eventhandling_winstack.png
+ when calling @c W->PopEventHandler(), the event handler @c A will be
+ removed and @c B will be the first handler of the stack.
- /**
- Returns @true if the window has the given @a flag bit set.
- */
- bool HasFlag(int flag) const;
+ Note that it's an error to call this function when no event handlers
+ were pushed on this window (i.e. when the window itself is its only
+ event handler).
- /**
- Returns @true if the window (or in case of composite controls, its main
- child window) has focus.
+ @param deleteHandler
+ If this is @true, the handler will be deleted after it is removed
+ (and the returned value will be @NULL).
- @see FindFocus()
+ @see @ref overview_eventhandling_processing
*/
- virtual bool HasFocus() const;
+ wxEvtHandler* PopEventHandler(bool deleteHandler = false);
/**
- 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;
+ Pushes this event handler onto the event stack for the window.
- /**
- Returns @true if this window has a scroll bar for this orientation.
+ An event handler is an object that is capable of processing the events sent
+ to a window. By default, the window is its own event handler, but an application
+ may wish to substitute another, for example to allow central implementation
+ of event-handling for a variety of different window classes.
- @param orient
- Orientation to check, either wxHORIZONTAL or wxVERTICAL.
- */
- bool HasScrollbar(int orient) const;
+ wxWindow::PushEventHandler allows an application to set up a @e stack
+ of event handlers, where an event not handled by one event handler is
+ handed to the next one in the chain.
- /**
- Returns @true if this window background is transparent (as, for example,
- for wxStaticText) and should show the parent window background.
+ E.g. if you have two event handlers @c A and @c B and a wxWindow instance
+ @c W and you call:
+ @code
+ W->PushEventHandler(A);
+ W->PushEventHandler(B);
+ @endcode
+ you will end up with the following situation:
+ @image html overview_eventhandling_winstack.png
- This method is mostly used internally by the library itself and you normally
- shouldn't have to call it. You may, however, have to override it in your
- wxWindow-derived class to ensure that background is painted correctly.
- */
- virtual bool HasTransparentBackground();
+ Note that you can use wxWindow::PopEventHandler to remove the event handler.
- /**
- Equivalent to calling wxWindow::Show(@false).
+ @param handler
+ Specifies the handler to be pushed.
+ It must not be part of a wxEvtHandler chain; an assert will fail
+ if it's not unlinked (see wxEvtHandler::IsUnlinked).
+
+ @see @ref overview_eventhandling_processing
*/
- bool Hide();
+ void PushEventHandler(wxEvtHandler* handler);
/**
- This function hides a window, like Hide(), but using a special visual
- effect if possible.
+ Find the given @a handler in the windows event handler stack and unlinks
+ (but not delete) it. See wxEvtHandler::Unlink() for more info.
- The parameters of this function are the same as for ShowWithEffect(),
- please see their description there.
+ @param handler
+ The event handler to remove, must be non-@NULL and
+ must be present in this windows event handlers stack.
- @since 2.9.0
+ @return Returns @true if it was found and @false otherwise (this also
+ results in an assert failure so this function should
+ only be called when the handler is supposed to be there).
+
+ @see PushEventHandler(), PopEventHandler()
*/
- virtual bool HideWithEffect(wxShowEffect effect,
- unsigned int timeout = 0);
+ bool RemoveEventHandler(wxEvtHandler* handler);
/**
- 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.
+ Sets the event handler for this window.
- This rather complicated logic is necessary in order to accommodate the
- different usage scenarios. The most common one is when all default attributes
- are used and in this case, nothing should be inherited as in modern GUIs
- different controls use different fonts (and colours) than their siblings so
- they can't inherit the same value from the parent. However it was also deemed
- desirable to allow to simply change the attributes of all children at once by
- just changing the font or colour of their common parent, hence in this case we
- do inherit the parents attributes.
- */
- virtual void InheritAttributes();
+ Note that if you use this function you may want to use as the "next" handler
+ of @a handler the window itself; in this way when @a handler doesn't process
+ an event, the window itself will have a chance to do it.
- /**
- Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
- to the dialog via validators.
- */
- virtual void InitDialog();
+ @param handler
+ Specifies the handler to be set. Cannot be @NULL.
- /**
- Resets the cached best size value so it will be recalculated the next time it
- is needed.
+ @see @ref overview_eventhandling_processing
*/
- void InvalidateBestSize();
+ void SetEventHandler(wxEvtHandler* handler);
/**
- 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.
+ wxWindows cannot be used to form event handler chains; this function
+ thus will assert when called.
- @see wxBufferedDC
+ Note that instead you can use PushEventHandler() or SetEventHandler() to
+ implement a stack of event handlers to override wxWindow's own
+ event handling mechanism.
*/
- virtual bool IsDoubleBuffered() const;
+ virtual void SetNextHandler(wxEvtHandler* handler);
/**
- Returns @true if the window is enabled, i.e. if it accepts user input,
- @false otherwise.
-
- Notice that this method can return @false even if this window itself hadn't
- been explicitly disabled when one of its parent windows is disabled.
- To get the intrinsic status of this window, use IsThisEnabled()
+ wxWindows cannot be used to form event handler chains; this function
+ thus will assert when called.
- @see Enable()
+ Note that instead you can use PushEventHandler() or SetEventHandler() to
+ implement a stack of event handlers to override wxWindow's own
+ event handling mechanism.
*/
- bool IsEnabled() const;
+ virtual void SetPreviousHandler(wxEvtHandler* handler);
- //@{
- /**
- Returns @true if the given point or rectangle area has been exposed since the
- last repaint. Call this in an paint event handler to optimize redrawing by
- only redrawing those areas, which have been exposed.
- */
- bool IsExposed(int x, int y) const;
- bool IsExposed(wxPoint& pt) const;
- bool IsExposed(int x, int y, int w, int h) const;
- bool IsExposed(wxRect& rect) const;
//@}
- /**
- Returns @true if the window is currently frozen by a call to Freeze().
- @see Freeze(), Thaw()
- */
- bool IsFrozen() const;
/**
- Returns @true if the window is retained, @false otherwise.
-
- @remarks Retained windows are only available on X platforms.
+ @name Window styles functions
*/
- virtual bool IsRetained() const;
+ //@{
/**
- Return whether a scrollbar is always shown.
-
- @param orient
- Orientation to check, either wxHORIZONTAL or wxVERTICAL.
-
- @see AlwaysShowScrollbars()
+ Returns the extra style bits for the window.
*/
- virtual bool IsScrollbarAlwaysShown(int orient) const;
+ long GetExtraStyle() const;
/**
- Returns @true if the window is shown, @false if it has been hidden.
-
- @see IsShownOnScreen()
+ Gets the window style that was passed to the constructor or Create()
+ method. GetWindowStyle() is another name for the same function.
*/
- virtual bool IsShown() const;
+ virtual long GetWindowStyleFlag() const;
/**
- Returns @true if the window is physically visible on the screen, i.e. it
- is shown and all its parents up to the toplevel window are shown as well.
-
- @see IsShown()
+ See GetWindowStyleFlag() for more info.
*/
- virtual bool IsShownOnScreen() const;
+ long GetWindowStyle() const;
/**
- Returns @true if this window is intrinsically enabled, @false otherwise,
- i.e. if @ref Enable() Enable(@false) had been called. This method is
- mostly used for wxWidgets itself, user code should normally use
- IsEnabled() instead.
+ Returns @true if the window has the given @a exFlag bit set in its
+ extra styles.
+
+ @see SetExtraStyle()
*/
- bool IsThisEnabled() const;
+ bool HasExtraStyle(int exFlag) const;
/**
- Returns @true if the given window is a top-level one. Currently all frames and
- dialogs are considered to be top-level windows (even if they have a parent
- window).
+ Returns @true if the window has the given @a flag bit set.
*/
- virtual bool IsTopLevel() const;
+ bool HasFlag(int flag) const;
/**
- Invokes the constraint-based layout algorithm or the sizer-based algorithm
- for this window.
-
- This function does not get called automatically when the window is resized
- because lots of windows deriving from wxWindow does not need this functionality.
- If you want to have Layout() called automatically, you should derive
- from wxPanel (see wxPanel::Layout).
-
- @see @ref overview_windowsizing
+ Sets the extra style bits for the window.
+ The currently defined extra style bits are reported in the class
+ description.
*/
- virtual bool Layout();
+ virtual void SetExtraStyle(long exStyle);
/**
- Lowers the window to the bottom of the window hierarchy (Z-order).
+ Sets the style of the window. Please note that some styles cannot be changed
+ after the window creation and that Refresh() might need to be be called
+ after changing the others for the change to take place immediately.
- @remarks
- This function only works for wxTopLevelWindow-derived classes.
+ See @ref overview_windowstyles "Window styles" for more information about flags.
- @see Raise()
+ @see GetWindowStyleFlag()
*/
- virtual void Lower();
+ virtual void SetWindowStyleFlag(long style);
/**
- 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.
+ See SetWindowStyleFlag() for more info.
*/
- virtual void MakeModal(bool modal = true);
+ void SetWindowStyle(long style);
/**
- Moves the window to the given position.
+ Turns the given @a flag on if it's currently turned off and vice versa.
+ This function cannot be used if the value of the flag is 0 (which is often
+ the case for default flags).
- @param x
- Required x position.
- @param y
- Required y position.
- @param flags
- See SetSize() for more info about this parameter.
+ Also, please notice that not all styles can be changed after the control
+ creation.
- @remarks Implementations of SetSize can also implicitly implement the
- Move() function, which is defined in the base wxWindow class as the call:
- @code
- SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
- @endcode
+ @return Returns @true if the style was turned on by this function, @false
+ if it was switched off.
- @see SetSize()
+ @see SetWindowStyleFlag(), HasFlag()
*/
- void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);
-
- /**
- Moves the window to the given position.
+ bool ToggleWindowStyle(int flag);
- @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:
- @code
- SetSize(x, y, wxDefaultCoord, wxDefaultCoord, wxSIZE_USE_EXISTING);
- @endcode
- @see SetSize()
+ /**
+ @name Tab order functions
*/
- void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
+ //@{
/**
Moves this window in the tab navigation order after the specified @e win.
*/
bool NavigateIn(int flags = IsForward);
- /**
- 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
+ /**
+ @name Z order functions
*/
- static wxWindowID NewControlId(int count = 1);
+ //@{
/**
- 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.
+ Lowers the window to the bottom of the window hierarchy (Z-order).
- 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 void OnInternalIdle();
+ @remarks
+ This function only works for wxTopLevelWindow-derived classes.
- /**
- Same as #ScrollLines (-1).
+ @see Raise()
*/
- bool LineUp();
+ virtual void Lower();
/**
- Same as #ScrollLines (1).
- */
- bool LineDown();
+ Raises the window to the top of the window hierarchy (Z-order).
- /**
- Same as #ScrollPages (-1).
- */
- bool PageUp();
+ @remarks
+ This function only works for wxTopLevelWindow-derived classes.
- /**
- Same as #ScrollPages (1).
+ @see Lower()
*/
- bool PageDown();
+ virtual void Raise();
+
+ //@}
/**
- Removes and returns the top-most event handler on the event handler stack.
+ @name Window status functions
+ */
+ //@{
- @param deleteHandler
- If this is @true, the handler will be deleted after it is removed.
- The default value is @false.
- @see SetEventHandler(), GetEventHandler(),
- PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
+ /**
+ Equivalent to calling wxWindow::Show(@false).
*/
- wxEvtHandler* PopEventHandler(bool deleteHandler = false);
+ bool Hide();
- //@{
/**
- Pops up the given menu at the specified coordinates, relative to this
- window, and returns control when the user has dismissed the menu.
+ This function hides a window, like Hide(), but using a special visual
+ effect if possible.
- If a menu item is selected, the corresponding menu event is generated and will be
- processed as usually. If the coordinates are not specified, current mouse
- cursor position is used.
+ The parameters of this function are the same as for ShowWithEffect(),
+ please see their description there.
- @a menu is the menu to pop up.
+ @since 2.9.0
+ */
+ virtual bool HideWithEffect(wxShowEffect effect,
+ unsigned int timeout = 0);
+ /**
+ Returns @true if the window is enabled, i.e. if it accepts user input,
+ @false otherwise.
- 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).
+ Notice that this method can return @false even if this window itself hadn't
+ been explicitly disabled when one of its parent windows is disabled.
+ To get the intrinsic status of this window, use IsThisEnabled()
- @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
- ensure that the menu items are in the correct state.
- The menu does not get deleted by the window.
- It is recommended to not explicitly specify coordinates when
- calling PopupMenu in response to mouse click, because some of
- the ports (namely, wxGTK) can do a better job of positioning
- the menu in that case.
+ @see Enable()
+ */
+ bool IsEnabled() const;
- @see wxMenu
+ /**
+ Returns @true if the given point or rectangle area has been exposed since the
+ last repaint. Call this in an paint event handler to optimize redrawing by
+ only redrawing those areas, which have been exposed.
*/
- bool PopupMenu(wxMenu* menu,
- const wxPoint& pos = wxDefaultPosition);
- bool PopupMenu(wxMenu* menu, int x, int y);
- //@}
+ bool IsExposed(int x, int y) const;
/**
- Posts a size event to the window.
+ @overload
+ */
+ bool IsExposed(wxPoint& pt) const;
- This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
- */
- void PostSizeEvent();
+ /**
+ @overload
+ */
+ bool IsExposed(int x, int y, int w, int h) const;
/**
- Posts a size event to the parent of this window.
+ @overload
+ */
+ bool IsExposed(wxRect& rect) const;
+ /**
+ Returns @true if the window is shown, @false if it has been hidden.
- This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
- argument.
- */
- void PostSizeEventToParent();
+ @see IsShownOnScreen()
+ */
+ virtual bool IsShown() const;
/**
- Pushes this event handler onto the event stack for the window.
-
- @param handler
- Specifies the handler to be pushed.
+ Returns @true if the window is physically visible on the screen, i.e. it
+ is shown and all its parents up to the toplevel window are shown as well.
- @remarks An event handler is an object that is capable of processing the
- events sent to a window. By default, the window is its
- own event handler, but an application may wish to
- substitute another, for example to allow central
- implementation of event-handling for a variety of
- different window classes.
- wxWindow::PushEventHandler allows an application to set up a
- chain of event handlers, where an event not handled by one event
- handler is handed to the next one in the chain.
- Use wxWindow::PopEventHandler to remove the event handler.
-
- @see SetEventHandler(), GetEventHandler(),
- PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
+ @see IsShown()
*/
- void PushEventHandler(wxEvtHandler* handler);
+ virtual bool IsShownOnScreen() const;
/**
- Raises the window to the top of the window hierarchy (Z-order).
-
- @remarks
- This function only works for wxTopLevelWindow-derived classes.
+ Disables the window. Same as @ref Enable() Enable(@false).
- @see Lower()
+ @return Returns @true if the window has been disabled, @false if it had
+ been already disabled before the call to this function.
*/
- virtual void Raise();
+ bool Disable();
/**
- Causes this window, and all of its children recursively (except under wxGTK1
- where this is not implemented), to be repainted. Note that repainting doesn't
- happen immediately but only during the next event loop iteration, if you need
- to update the window immediately you should use Update() instead.
+ Enable or disable the window for user input. Note that when a parent window is
+ disabled, all of its children are disabled as well and they are reenabled again
+ when the parent is.
- @param eraseBackground
- If @true, the background will be erased.
- @param rect
- If non-@NULL, only the given rectangle will be treated as damaged.
+ @param enable
+ If @true, enables the window for input. If @false, disables the window.
- @see RefreshRect()
+ @return Returns @true if the window has been enabled or disabled, @false
+ if nothing was done, i.e. if the window had already
+ been in the specified state.
+
+ @see IsEnabled(), Disable(), wxRadioBox::Enable
*/
- virtual void Refresh(bool eraseBackground = true,
- const wxRect* rect = NULL);
+ virtual bool Enable(bool enable = true);
/**
- Redraws the contents of the given rectangle: only the area inside it will be
- repainted.
+ Shows or hides the window. You may need to call Raise()
+ for a top level window if you want to bring it to top, although this is not
+ needed if Show() is called immediately after the frame creation.
- This is the same as Refresh() but has a nicer syntax as it can be called
- with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)).
+ @param show
+ If @true displays the window. Otherwise, hides it.
+
+ @return @true if the window has been shown or hidden or @false if nothing
+ was done because it already was in the requested state.
+
+ @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
*/
- void RefreshRect(const wxRect& rect, bool eraseBackground = true);
+ virtual bool Show(bool show = true);
/**
- Registers a system wide hotkey. Every time the user presses the hotkey
- registered here, this window will receive a hotkey event.
+ This function shows a window, like Show(), but using a special visual
+ effect if possible.
- 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 effect
+ The effect to use.
- @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.
+ @param timeout
+ The @a timeout parameter specifies the time of the animation, in
+ milliseconds. If the default value of 0 is used, the default
+ animation time for the current platform is used.
- @return @true if the hotkey was registered successfully. @false if some
- other application already registered a hotkey with this
- modifier/virtualKeyCode combination.
+ @note Currently this function is only implemented in wxMSW and does the
+ same thing as Show() in the other ports.
- @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.
+ @since 2.9.0
- @see UnregisterHotKey()
+ @see HideWithEffect()
*/
- virtual bool RegisterHotKey(int hotkeyId, int modifiers,
- int virtualKeyCode);
+ virtual bool ShowWithEffect(wxShowEffect effect,
+ unsigned int timeout = 0);
- /**
- Releases mouse input captured with CaptureMouse().
+ //@}
- @see CaptureMouse(), HasCapture(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
- */
- void ReleaseMouse();
/**
- Removes a child window.
+ @name Context-sensitive help functions
+ */
+ //@{
- This is called automatically by window deletion functions so should not
- be required by the application programmer.
- Notice that this function is mostly internal to wxWidgets and shouldn't be
- called by the user code.
+ /**
+ 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.
- @param child
- Child window to remove.
+ @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
*/
- virtual void RemoveChild(wxWindow* child);
+ wxString GetHelpText() const;
/**
- Find the given @a handler in the windows event handler chain and remove
- (but not delete) it from it.
+ 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.
- @param handler
- The event handler to remove, must be non-@NULL and
- must be present in this windows event handlers chain
+ @see GetHelpText(), wxHelpProvider::AddHelp()
+ */
+ void SetHelpText(const wxString& helpText);
- @return Returns @true if it was found and @false otherwise (this also
- results in an assert failure so this function should
- only be called when the handler is supposed to be there).
+ /**
+ 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.
- @see PushEventHandler(), PopEventHandler()
+ @param point
+ Coordinates of the mouse at the moment of help event emission.
+ @param origin
+ Help event origin, see also wxHelpEvent::GetOrigin.
*/
- bool RemoveEventHandler(wxEvtHandler* handler);
+ virtual wxString GetHelpTextAtPoint(const wxPoint& point,
+ wxHelpEvent::Origin origin) const;
/**
- Reparents the window, i.e the window will be removed from its
- current parent window (e.g. a non-standard toolbar in a wxFrame)
- and then re-inserted into another.
-
- @param newParent
- New parent.
+ Get the associated tooltip or @NULL if none.
*/
- virtual bool Reparent(wxWindow* newParent);
+ wxToolTip* GetToolTip() const;
/**
- Converts from screen to client window coordinates.
+ Attach a tooltip to the window.
- @param x
- Stores the screen x coordinate and receives the client x coordinate.
- @param y
- Stores the screen x coordinate and receives the client x coordinate.
+ wxToolTip pointer can be @NULL in the overload taking the pointer,
+ meaning to unset any existing tooltips, however UnsetToolTip() provides
+ a more readable alternative to this operation.
+
+ Notice that these methods are always available, even if wxWidgets was
+ compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
+ case.
+
+ @see GetToolTip(), wxToolTip
*/
- void ScreenToClient(int* x, int* y) const;
+ void SetToolTip(const wxString& tip);
/**
- Converts from screen to client window coordinates.
-
- @param pt
- The screen position.
+ @overload
*/
- wxPoint ScreenToClient(const wxPoint& pt) const;
+ void SetToolTip(wxToolTip* tip);
/**
- Scrolls the window by the given number of lines down (if @a lines is
- positive) or up.
+ Unset any existing tooltip.
- @return Returns @true if the window was scrolled, @false if it was already
- on top/bottom and nothing was done.
+ @since 2.9.0
- @remarks This function is currently only implemented under MSW and
- wxTextCtrl under wxGTK (it also works for wxScrolled classes
- under all platforms).
+ @see SetToolTip()
+ */
+ void UnsetToolTip();
- @see ScrollPages()
+ //@}
+
+
+ /**
+ @name Popup/context menu functions
*/
- virtual bool ScrollLines(int lines);
+ //@{
/**
- Scrolls the window by the given number of pages down (if @a pages is
- positive) or up.
+ This function shows a popup menu at the given position in this window and
+ returns the selected id.
- @return Returns @true if the window was scrolled, @false if it was already
- on top/bottom and nothing was done.
+ 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.
- @remarks This function is currently only implemented under MSW and wxGTK.
+ 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 ScrollLines()
- */
- virtual bool ScrollPages(int pages);
+ 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.
- /**
- Physically scrolls the pixels in the window and move child windows accordingly.
+ @return
+ The selected menu item id or @c wxID_NONE if none selected or an
+ error occurred.
- @param dx
- Amount to scroll horizontally.
- @param dy
- Amount to scroll vertically.
- @param rect
- Rectangle to scroll, if it is @NULL, the whole window is
- scrolled (this is always the case under wxGTK which doesn't support this
- parameter)
+ @since 2.9.0
+ */
+ int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
- @remarks Note that you can often use wxScrolled instead of using this
- function directly.
+ /**
+ @overload
*/
- virtual void ScrollWindow(int dx, int dy,
- const wxRect* rect = NULL);
+ int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
/**
- This function sends a dummy @ref wxSizeEvent "size event" to
- the window allowing it to re-layout its children positions.
+ Pops up the given menu at the specified coordinates, relative to this
+ window, and returns control when the user has dismissed the menu.
- It is sometimes useful to call this function after adding or deleting a
- children after the frame creation or if a child size changes. Note that
- if the frame is using either sizers or constraints for the children
- layout, it is enough to call wxWindow::Layout() directly and this
- function should not be used in this case.
+ If a menu item is selected, the corresponding menu event is generated and will be
+ processed as usually. If the coordinates are not specified, current mouse
+ cursor position is used.
- If @a flags includes @c wxSEND_EVENT_POST value, this function posts
- the event, i.e. schedules it for later processing, instead of
- dispatching it directly. You can also use PostSizeEvent() as a more
- readable equivalent of calling this function with this flag.
+ @a menu is the menu to pop up.
- @param flags
- May include @c wxSEND_EVENT_POST. Default value is 0.
+ The position where the menu will appear can be specified either as a
+ wxPoint @a pos or by two integers (@a x and @a y).
+
+ @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
+ ensure that the menu items are in the correct state.
+ The menu does not get deleted by the window.
+ It is recommended to not explicitly specify coordinates when
+ calling PopupMenu in response to mouse click, because some of
+ the ports (namely, wxGTK) can do a better job of positioning
+ the menu in that case.
+
+ @see wxMenu
*/
- virtual void SendSizeEvent(int flags = 0);
+ bool PopupMenu(wxMenu* menu,
+ const wxPoint& pos = wxDefaultPosition);
/**
- Safe wrapper for GetParent()->SendSizeEvent().
-
- This function simply checks that the window has a valid parent which is
- not in process of being deleted and calls SendSizeEvent() on it. It is
- used internally by windows such as toolbars changes to whose state
- should result in parent re-layout (e.g. when a toolbar is added to the
- top of the window, all the other windows must be shifted down).
+ @overload
+ */
+ bool PopupMenu(wxMenu* menu, int x, int y);
- @see PostSizeEventToParent()
+ //@}
- @param flags
- See description of this parameter in SendSizeEvent() documentation.
- */
- void SendSizeEventToParent(int flags = 0);
/**
- Sets the accelerator table for this window. See wxAcceleratorTable.
+ Validator functions
*/
- virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
+ //@{
/**
- Sets the accessible for this window. Any existing accessible for this window
- will be deleted first, if not identical to @e accessible.
- See also wxAccessible.
+ Returns a pointer to the current validator for the window, or @NULL if
+ there is none.
*/
- void SetAccessible(wxAccessible* accessible);
+ virtual wxValidator* GetValidator();
/**
- 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).
+ 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);
- 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.
+ /**
+ Transfers values from child controls to data areas specified by their
+ validators. Returns @false if a transfer failed.
- @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).
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call TransferDataFromWindow() of all child windows.
- @see SetConstraints()
+ @see TransferDataToWindow(), wxValidator, Validate()
*/
- void SetAutoLayout(bool autoLayout);
+ virtual bool TransferDataFromWindow();
/**
- Sets the background colour of the window.
- Please see InheritAttributes() for explanation of the difference between
- this method and SetOwnBackgroundColour().
+ Transfers values to child controls from data areas specified by their
+ validators.
- @param colour
- The colour to be used as the background colour, pass
- wxNullColour to reset to the default colour.
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call TransferDataToWindow() of all child windows.
- @remarks The background colour is usually painted by the default
- wxEraseEvent event handler function under Windows and
- automatically under GTK.
- Note that setting the background colour does not cause an
- immediate refresh, so you may wish to call wxWindow::ClearBackground
- or wxWindow::Refresh after calling this function.
- Using this function will disable attempts to use themes for
- this window, if the system supports them. Use with care since
- usually the themes represent the appearance chosen by the user
- to be used for all applications on the system.
+ @return Returns @false if a transfer failed.
- @see GetBackgroundColour(), SetForegroundColour(),
- GetForegroundColour(), ClearBackground(),
- Refresh(), wxEraseEvent
+ @see TransferDataFromWindow(), wxValidator, Validate()
*/
- virtual bool SetBackgroundColour(const wxColour& colour);
+ virtual bool TransferDataToWindow();
/**
- Sets the background style of the window. see GetBackgroundStyle() for
- the description of the possible style values.
+ 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 SetBackgroundColour(), GetForegroundColour(),
- SetTransparent()
+ @return Returns @false if any of the validations failed.
+
+ @see TransferDataFromWindow(), TransferDataToWindow(),
+ wxValidator
*/
- virtual bool SetBackgroundStyle(wxBackgroundStyle style);
+ virtual bool Validate();
- /**
- This method is only implemented by ports which have support for
- native TAB traversal (such as GTK+ 2.0).
+ //@}
- It is called by wxWidgets' container control code to give the native
- system a hint when doing TAB traversal. A call to this does not disable
- or change the effect of programmatically calling SetFocus().
- @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
+ /**
+ @name wxWindow properties functions
*/
- virtual void SetCanFocus(bool canFocus);
+ //@{
/**
- Sets the caret() associated with the window.
+ Returns the identifier of the window.
+
+ @remarks Each window has an integer identifier. If the application
+ has not provided one (or the default wxID_ANY) an unique
+ identifier with a negative value will be generated.
+
+ @see SetId(), @ref overview_windowids
*/
- void SetCaret(wxCaret* caret);
+ wxWindowID GetId() const;
- //@{
/**
- This sets the size of the window client area in pixels.
+ Generic way of getting a label from any window, for
+ identification purposes.
- Using this function to size a window tends to be more device-independent
- than SetSize(), since the application need not worry about what dimensions
- the border or title bar have when trying to fit the window around panel
- items, for example.
+ @remarks The interpretation of this function differs from class to class.
+ For frames and dialogs, the value returned is the
+ title. For buttons or static text controls, it is the
+ button text. This function can be useful for
+ meta-programs (such as testing tools or special-needs
+ access programs) which need to identify windows by name.
*/
- virtual void SetClientSize(int width, int height);
- virtual void SetClientSize(const wxSize& size);
- //@}
+ virtual wxString GetLabel() const;
/**
- Sets the window to have the given layout constraints. The window
- will then own the object, and will take care of its deletion.
- If an existing layout constraints object is already owned by the
- window, it will be deleted.
+ Returns the window's name.
- @param constraints
- The constraints to set. Pass @NULL to disassociate and delete the window's
- constraints.
+ @remarks This name is not guaranteed to be unique; it is up to the
+ programmer to supply an appropriate name in the window
+ constructor or via SetName().
- @remarks You must call SetAutoLayout() to tell a window to use
- the constraints automatically in OnSize; otherwise, you
- must override OnSize and call Layout() explicitly. When
- setting both a wxLayoutConstraints and a wxSizer, only
- the sizer will have effect.
+ @see SetName()
*/
- void SetConstraints(wxLayoutConstraints* constraints);
+ virtual wxString GetName() const;
/**
- This normally does not need to be called by user code.
- It is called when a window is added to a sizer, and is used so the window
- can remove itself from the sizer when it is destroyed.
+ Returns the value previously passed to SetWindowVariant().
*/
- void SetContainingSizer(wxSizer* sizer);
+ wxWindowVariant GetWindowVariant() const;
/**
- Sets the window's cursor. Notice that the window cursor also sets it for the
- children of the window implicitly.
-
- The @a cursor may be @c wxNullCursor in which case the window cursor will
- be reset back to default.
+ Sets the identifier of the window.
- @param cursor
- Specifies the cursor that the window should normally display.
+ @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 ::wxSetCursor, wxCursor
+ @see GetId(), @ref overview_windowids
*/
- virtual bool SetCursor(const wxCursor& cursor);
+ void SetId(wxWindowID winid);
/**
- Associates a drop target with this window.
- If the window already has a drop target, it is deleted.
+ Sets the window's label.
- @see GetDropTarget(), @ref overview_dnd
+ @param label
+ The window label.
+
+ @see GetLabel()
*/
- virtual void SetDropTarget(wxDropTarget* target);
+ virtual void SetLabel(const wxString& label);
/**
- Sets the event handler for this window.
+ Sets the window's name.
- @param handler
- Specifies the handler to be set.
-
- @remarks An event handler is an object that is capable of processing the
- events sent to a window. By default, the window is its
- own event handler, but an application may wish to
- substitute another, for example to allow central
- implementation of event-handling for a variety of
- different window classes.
- It is usually better to use wxWindow::PushEventHandler since
- this sets up a chain of event handlers, where an event not
- handled by one event handler is handed to the next one in the chain.
-
- @see GetEventHandler(), PushEventHandler(),
- PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
- */
- void SetEventHandler(wxEvtHandler* handler);
+ @param name
+ A name to set for the window.
- /**
- Sets the extra style bits for the window.
- The currently defined extra style bits are reported in the class
- description.
+ @see GetName()
*/
- virtual void SetExtraStyle(long exStyle);
+ virtual void SetName(const wxString& name);
/**
- This sets the window to receive keyboard input.
+ 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.
- @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
- wxPanel::SetFocusIgnoringChildren
+ By default the controls use the normal size, of course, but this function can
+ be used to change this.
*/
- virtual void SetFocus();
+ void SetWindowVariant(wxWindowVariant variant);
- /**
- This function is called by wxWidgets keyboard navigation code when the user
- gives the focus to this window from keyboard (e.g. using @c TAB key).
- By default this method simply calls SetFocus() but
- can be overridden to do something in addition to this in the derived classes.
+ /**
+ Gets the accelerator table for this window. See wxAcceleratorTable.
*/
- virtual void SetFocusFromKbd();
+ wxAcceleratorTable* GetAcceleratorTable();
/**
- Sets the font for this window. This function should not be called for the
- parent window if you don't want its font to be inherited by its children,
- use SetOwnFont() instead in this case and see InheritAttributes() for more
- explanations.
-
- Please notice that the given font is not automatically used for
- wxPaintDC objects associated with this window, you need to
- call wxDC::SetFont too. However this font is used by
- any standard controls for drawing their text as well as by
- GetTextExtent().
-
- @param font
- Font to associate with this window, pass
- wxNullFont to reset to the default font.
-
- @return @true if the want was really changed, @false if it was already set
- to this font and so nothing was done.
+ Returns the accessible object for this window, if any.
+ See also wxAccessible.
+ */
+ wxAccessible* GetAccessible();
- @see GetFont(), InheritAttributes()
+ /**
+ Sets the accelerator table for this window. See wxAcceleratorTable.
*/
- virtual bool SetFont(const wxFont& font);
+ virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
/**
- Sets the foreground colour of the window.
- Please see InheritAttributes() for explanation of the difference between
- this method and SetOwnForegroundColour().
+ Sets the accessible for this window. Any existing accessible for this window
+ will be deleted first, if not identical to @e accessible.
+ See also wxAccessible.
+ */
+ void SetAccessible(wxAccessible* accessible);
- @param colour
- The colour to be used as the foreground colour, pass
- wxNullColour to reset to the default colour.
+ //@}
- @remarks The interpretation of foreground colour is open to
- interpretation according to the window class; it may be
- the text colour or other colour, or it may not be used at all.
- @see GetForegroundColour(), SetBackgroundColour(),
- GetBackgroundColour(), ShouldInheritColours()
+ /**
+ @name Window deletion functions
*/
- virtual bool SetForegroundColour(const wxColour& colour);
+ //@{
/**
- 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.
+ This function simply generates a wxCloseEvent whose handler usually tries
+ to close the window. It doesn't close the window itself, however.
- @see GetHelpText(), wxHelpProvider::AddHelp()
+ @param force
+ @false if the window's close handler should be able to veto the destruction
+ of this window, @true if it cannot.
+
+ @remarks Close calls the close handler for the window, providing an
+ opportunity for the window to choose whether to destroy
+ the window. Usually it is only used with the top level
+ windows (wxFrame and wxDialog classes) as the others
+ are not supposed to have any special OnClose() logic.
+ The close handler should check whether the window is being deleted
+ forcibly, using wxCloseEvent::CanVeto, in which case it should
+ destroy the window using wxWindow::Destroy.
+ Note that calling Close does not guarantee that the window will
+ be destroyed; but it provides a way to simulate a manual close
+ of a window, which may or may not be implemented by destroying
+ the window. The default implementation of wxDialog::OnCloseWindow
+ does not necessarily delete the dialog, since it will simply
+ simulate an wxID_CANCEL event which is handled by the appropriate
+ button event handler and may do anything at all.
+ To guarantee that the window will be destroyed, call
+ wxWindow::Destroy instead
+
+ @see @ref overview_windowdeletion "Window Deletion Overview",
+ Destroy(), wxCloseEvent
*/
- void SetHelpText(const wxString& helpText);
+ bool Close(bool force = false);
/**
- 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.
+ 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 GetId(), @ref overview_windowids
+ @return @true if the window has either been successfully deleted, or it
+ has been added to the list of windows pending real deletion.
*/
- void SetId(wxWindowID winid);
+ virtual bool Destroy();
/**
- A @e smart SetSize that will fill in default size components with the
- window's @e best size values.
+ Returns true if this window is in process of being destroyed.
- Also sets the window's minsize to the value passed in for use with sizers.
- This means that if a full or partial size is passed to this function then
- the sizers will use that size instead of the results of GetBestSize() to
- determine the minimum needs of the window for layout.
+ 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.
- Most controls will use this to set their initial size, and their min
- size to the passed in value (if any.)
+ 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;
- @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
- @ref overview_windowsizing
- */
- void SetInitialSize(const wxSize& size = wxDefaultSize);
+ //@}
- /**
- Sets the window's label.
- @param label
- The window label.
- @see GetLabel()
+ /**
+ @name Drag and drop functions
*/
- virtual void SetLabel(const wxString& label);
+ //@{
/**
- Sets the maximum client size of the window, to indicate to the sizer
- layout mechanism that this is the maximum possible size of its client area.
+ Returns the associated drop target, which may be @NULL.
- @see SetMaxSize()
+ @see SetDropTarget(), @ref overview_dnd
*/
- virtual void SetMaxClientSize(const wxSize& size);
+ virtual wxDropTarget* GetDropTarget() const;
/**
- Sets the maximum size of the window, to indicate to the sizer layout mechanism
- that this is the maximum possible size.
+ Associates a drop target with this window.
+ If the window already has a drop target, it is deleted.
- @see SetMaxClientSize()
+ @see GetDropTarget(), @ref overview_dnd
*/
- virtual void SetMaxSize(const wxSize& size);
+ virtual void SetDropTarget(wxDropTarget* target);
/**
- Sets the minimum client size of the window, to indicate to the sizer
- layout mechanism that this is the minimum required size of window's client
- area.
+ Enables or disables eligibility for drop file events (OnDropFiles).
- You may need to call this if you change the window size after
- construction and before adding to its parent sizer.
+ @param accept
+ If @true, the window is eligible for drop file events.
+ If @false, the window will not accept drop file events.
- Note, that just as with SetMinSize(), calling this method doesn't
- prevent the program from explicitly making the window smaller than the
- specified size.
+ @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 SetMinSize()
+ @see SetDropTarget()
*/
- virtual void SetMinClientSize(const wxSize& size);
-
- /**
- Sets the minimum size of the window, to indicate to the sizer layout
- mechanism that this is the minimum required size.
+ virtual void DragAcceptFiles(bool accept);
- You may need to call this if you change the window size after
- construction and before adding to its parent sizer.
+ //@}
- Notice that calling this method doesn't prevent the program from making
- the window explicitly smaller than the specified size by calling
- SetSize(), it just ensures that it won't become smaller than this size
- during the automatic layout.
- @see SetMinClientSize()
+ /**
+ @name Constraints, sizers and window layouting functions
*/
- virtual void SetMinSize(const wxSize& size);
+ //@{
/**
- Sets the window's name.
-
- @param name
- A name to set for the window.
-
- @see GetName()
+ Return the sizer that this window is a member of, if any, otherwise @NULL.
*/
- virtual void SetName(const wxString& name);
+ wxSizer* GetContainingSizer() const;
/**
- Sets the background colour of the window but prevents it from being inherited
- by the children of this window.
-
- @see SetBackgroundColour(), InheritAttributes()
+ Return the sizer associated with the window by a previous call to
+ SetSizer() or @NULL.
*/
- void SetOwnBackgroundColour(const wxColour& colour);
+ wxSizer* GetSizer() const;
/**
- Sets the font of the window but prevents it from being inherited by the
- children of this window.
+ 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.
- @see SetFont(), InheritAttributes()
- */
- void SetOwnFont(const wxFont& font);
+ Note that this function will also call SetAutoLayout() implicitly with @true
+ parameter if the @a sizer is non-@NULL and @false otherwise.
- /**
- Sets the foreground colour of the window but prevents it from being inherited
- by the children of this window.
+ @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.
- @see SetForegroundColour(), InheritAttributes()
+ @remarks SetSizer enables and disables Layout automatically.
*/
- void SetOwnForegroundColour(const wxColour& colour);
+ void SetSizer(wxSizer* sizer, bool deleteOld = true);
/**
- @deprecated use wxDC::SetPalette instead.
+ 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 SetPalette(const wxPalette& pal);
+ void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
/**
- Sets the position of one of the built-in scrollbars.
+ Returns a pointer to the window's layout constraints, or @NULL if there are none.
+ */
+ wxLayoutConstraints* GetConstraints() const;
- @param orientation
- Determines the scrollbar whose position is to be set.
- May be wxHORIZONTAL or wxVERTICAL.
- @param pos
- Position in scroll units.
- @param refresh
- @true to redraw the scrollbar, @false otherwise.
+ /**
+ Sets the window to have the given layout constraints. The window
+ will then own the object, and will take care of its deletion.
+ If an existing layout constraints object is already owned by the
+ window, it will be deleted.
- @remarks This function does not directly affect the contents of the
- window: it is up to the application to take note of
- scrollbar attributes and redraw contents accordingly.
+ @param constraints
+ The constraints to set. Pass @NULL to disassociate and delete the window's
+ constraints.
- @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
- wxScrolled
+ @remarks You must call SetAutoLayout() to tell a window to use
+ the constraints automatically in OnSize; otherwise, you
+ must override OnSize and call Layout() explicitly. When
+ setting both a wxLayoutConstraints and a wxSizer, only
+ the sizer will have effect.
*/
- virtual void SetScrollPos(int orientation, int pos,
- bool refresh = true);
+ void SetConstraints(wxLayoutConstraints* constraints);
- /**
- Sets the scrollbar properties of a built-in scrollbar.
- @param orientation
- Determines the scrollbar whose page size is to be set.
- May be wxHORIZONTAL or wxVERTICAL.
- @param position
- The position of the scrollbar in scroll units.
- @param thumbSize
- The size of the thumb, or visible portion of the scrollbar, in scroll units.
- @param range
- The maximum position of the scrollbar.
- @param refresh
- @true to redraw the scrollbar, @false otherwise.
+ /**
+ Invokes the constraint-based layout algorithm or the sizer-based algorithm
+ for this window.
- @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.
+ 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_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
+ @see @ref overview_windowsizing
*/
- virtual void SetScrollbar(int orientation, int position,
- int thumbSize, int range,
- bool refresh = true);
+ virtual bool Layout();
/**
- Sets the size of the window in pixels.
+ 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).
- @param x
- Required x position in pixels, or wxDefaultCoord to indicate that the
- existing value should be used.
- @param y
- Required y position in pixels, or wxDefaultCoord to indicate that the
- existing value should be used.
- @param width
- Required width in pixels, or wxDefaultCoord to indicate that the existing
- value should be used.
- @param height
- Required height position in pixels, or wxDefaultCoord to indicate that the
- existing value should be used.
- @param sizeFlags
- Indicates the interpretation of other parameters.
- It is a bit list of the following:
- - @c wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate
- a wxWidgets-supplied default width.
- - @c wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate
- a wxWidgets-supplied default height.
- - @c wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate
- a wxWidgets-supplied default size.
- - @c wxSIZE_USE_EXISTING: existing dimensions should be used
- if wxDefaultCoord values are supplied.
- - @c wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of
- wxDefaultCoord) to be interpreted as real
- dimensions, not default values.
- - @c wxSIZE_FORCE: normally, if the position and the size of the window are
- already the same as the parameters of this function,
- nothing is done. but with this flag a window resize may
- be forced even in this case (supported in wx 2.6.2 and
- later and only implemented for MSW and ignored elsewhere
- currently).
+ This 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.
- @remarks This overload sets the position and optionally size, of the window.
- Parameters may be wxDefaultCoord to indicate either that a default
- should be supplied by wxWidgets, or that the current value of the
- dimension should be used.
+ @param 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 Move()
+ @see SetConstraints()
*/
- void SetSize(int x, int y, int width, int height,
- int sizeFlags = wxSIZE_AUTO);
+ void SetAutoLayout(bool autoLayout);
- //@{
- /**
- 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()
+
+ /**
+ @name Mouse functions
*/
- virtual void SetSize(const wxRect& rect);
- virtual void SetSize(const wxSize& size);
- virtual void SetSize(int width, int height);
- //@}
+ //@{
/**
- 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.
+ Directs all mouse input to this window.
+ Call ReleaseMouse() to release the capture.
- Note that this function will also call SetAutoLayout() implicitly with @true
- parameter if the @a sizer is non-@NULL and @false otherwise.
+ Note that wxWidgets maintains the stack of windows having captured the mouse
+ and when the mouse is released the capture returns to the window which had had
+ captured it previously and it is only really released if there were no previous
+ window. In particular, this means that you must release the mouse as many times
+ as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
- @param 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.
+ 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.
- @remarks SetSizer enables and disables Layout automatically.
+ @see ReleaseMouse(), wxMouseCaptureLostEvent
*/
- void SetSizer(wxSizer* sizer, bool deleteOld = true);
+ void CaptureMouse();
/**
- 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.
+ Returns the caret() associated with the window.
*/
- void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
+ wxCaret* GetCaret() const;
/**
- This function tells a window if it should use the system's "theme" code
- to draw the windows' background instead if its own background drawing
- code. This does not always have any effect since the underlying platform
- obviously needs to support the notion of themes in user defined windows.
- One such platform is GTK+ where windows can have (very colourful) backgrounds
- defined by a user's selected theme.
+ Return the cursor associated with this window.
- Dialogs, notebook pages and the status bar have this flag set to @true
- by default so that the default look and feel is simulated best.
+ @see SetCursor()
*/
- virtual void SetThemeEnabled(bool enable);
+ const wxCursor& GetCursor() const;
- //@{
/**
- Attach a tooltip to the window.
+ Returns @true if this window has the current mouse capture.
- wxToolTip pointer can be @NULL in the overload taking the pointer,
- meaning to unset any existing tooltips, however UnsetToolTip() provides
- a more readable alternative to this operation.
+ @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
+ wxMouseCaptureChangedEvent
+ */
+ virtual bool HasCapture() const;
- Notice that these methods are always available, even if wxWidgets was
- compiled with @c wxUSE_TOOLTIPS set to 0, but don't do anything in this
- case.
+ /**
+ Releases mouse input captured with CaptureMouse().
- @see GetToolTip(), wxToolTip
+ @see CaptureMouse(), HasCapture(), ReleaseMouse(),
+ wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
*/
- void SetToolTip(const wxString& tip);
- void SetToolTip(wxToolTip* tip);
- //@}
+ void ReleaseMouse();
/**
- Set the transparency of the window. If the system supports transparent windows,
- returns @true, otherwise returns @false and the window remains fully opaque.
- See also CanSetTransparent().
-
- The parameter @a alpha is in the range 0..255 where 0 corresponds to a
- fully transparent window and 255 to the fully opaque one. The constants
- @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
+ Sets the caret() associated with the window.
*/
- virtual bool SetTransparent(wxByte alpha);
+ void SetCaret(wxCaret* caret);
/**
- Deletes the current validator (if any) and sets the window validator, having
- called wxValidator::Clone to create a new validator of this type.
+ Sets the window's cursor. Notice that the window cursor also sets it for the
+ children of the window implicitly.
+
+ The @a cursor may be @c wxNullCursor in which case the window cursor will
+ be reset back to default.
+
+ @param cursor
+ Specifies the cursor that the window should normally display.
+
+ @see ::wxSetCursor, wxCursor
*/
- virtual void SetValidator(const wxValidator& validator);
+ virtual bool SetCursor(const wxCursor& cursor);
- //@{
/**
- Sets the virtual size of the window in pixels.
+ Moves the pointer to the given position on the window.
+
+ @note This function is not supported under Mac because Apple Human
+ Interface Guidelines forbid moving the mouse cursor programmatically.
+
+ @param x
+ The new x position for the cursor.
+ @param y
+ The new y position for the cursor.
*/
- void SetVirtualSize(int width, int height);
- void SetVirtualSize(const wxSize& size);
+ virtual void WarpPointer(int x, int y);
+
//@}
+
+
+
/**
- Identical to SetWindowStyleFlag().
+ @name Miscellaneous functions
*/
- 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
- after changing the others for the change to take place immediately.
+ 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:
- See @ref overview_windowstyles "Window styles" for more information about flags.
+ @code
+ // do the window-specific processing after processing the update event
+ void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
+ {
+ if ( event.GetSetEnabled() )
+ Enable(event.GetEnabled());
- @see GetWindowStyleFlag()
+ if ( event.GetSetText() )
+ {
+ if ( event.GetText() != GetTitle() )
+ SetTitle(event.GetText());
+ }
+ }
+ @endcode
*/
- virtual void SetWindowStyleFlag(long style);
+ virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
/**
- 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 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.
*/
- void SetWindowVariant(wxWindowVariant variant);
+ virtual WXWidget GetHandle() const;
/**
- Return @true from here to allow the colours of this window to be changed by
- InheritAttributes(), returning @false forbids inheriting them from the parent window.
-
- The base class version returns @false, but this method is overridden in
- wxControl where it returns @true.
+ 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 ShouldInheritColours() const;
+ virtual bool HasMultiplePages() const;
/**
- Shows or hides the window. You may need to call Raise()
- for a top level window if you want to bring it to top, although this is not
- needed if Show() is called immediately after the frame creation.
-
- @param show
- If @true displays the window. Otherwise, hides it.
+ 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.
- @return @true if the window has been shown or hidden or @false if nothing
- was done because it already was in the requested state.
+ 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.
- @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
+ This rather complicated logic is necessary in order to accommodate the
+ different usage scenarios. The most common one is when all default attributes
+ are used and in this case, nothing should be inherited as in modern GUIs
+ different controls use different fonts (and colours) than their siblings so
+ they can't inherit the same value from the parent. However it was also deemed
+ desirable to allow to simply change the attributes of all children at once by
+ just changing the font or colour of their common parent, hence in this case we
+ do inherit the parents attributes.
*/
- virtual bool Show(bool show = true);
+ virtual void InheritAttributes();
/**
- This function shows a window, like Show(), but using a special visual
- effect if possible.
-
- @param effect
- The effect to use.
-
- @param timeout
- The @a timeout parameter specifies the time of the animation, in
- milliseconds. If the default value of 0 is used, the default
- animation time for the current platform is used.
-
- @note Currently this function is only implemented in wxMSW and does the
- same thing as Show() in the other ports.
+ Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
+ to the dialog via validators.
+ */
+ virtual void InitDialog();
- @since 2.9.0
+ /**
+ 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 HideWithEffect()
+ @see wxBufferedDC
*/
- virtual bool ShowWithEffect(wxShowEffect effect,
- unsigned int timeout = 0);
+ virtual bool IsDoubleBuffered() const;
/**
- Reenables window updating after a previous call to Freeze().
-
- To really thaw the control, it must be called exactly the same number
- of times as Freeze().
+ Returns @true if the window is retained, @false otherwise.
- If the window has any children, they are recursively thawn too.
+ @remarks Retained windows are only available on X platforms.
+ */
+ virtual bool IsRetained() const;
- @see wxWindowUpdateLocker, Freeze(), IsFrozen()
+ /**
+ 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.
*/
- void Thaw();
+ bool IsThisEnabled() 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.
+ Returns @true if the given window is a top-level one. Currently all frames and
+ dialogs are considered to be top-level windows (even if they have a parent
+ window).
+ */
+ virtual bool IsTopLevel() const;
- @return Returns @true if the style was turned on by this function, @false
- if it was switched off.
+ /**
+ Disables all other windows in the application so that
+ the user can only interact with this window.
- @see SetWindowStyleFlag(), HasFlag()
+ @param modal
+ If @true, this call disables all other windows in the application so that
+ the user can only interact with this window. If @false, the effect is
+ reversed.
*/
- bool ToggleWindowStyle(int flag);
+ virtual void MakeModal(bool modal = true);
/**
- Transfers values from child controls to data areas specified by their
- validators. Returns @false if a transfer failed.
-
- If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
- the method will also call TransferDataFromWindow() of all child windows.
+ This virtual function is normally only used internally, but
+ sometimes an application may need it to implement functionality
+ that should not be disabled by an application defining an OnIdle
+ handler in a derived class.
- @see TransferDataToWindow(), wxValidator, Validate()
+ This function may be used to do delayed painting, for example,
+ and most implementations call UpdateWindowUI()
+ in order to send update events to the window in idle time.
*/
- virtual bool TransferDataFromWindow();
+ virtual void OnInternalIdle();
/**
- Transfers values to child controls from data areas specified by their
- validators.
+ Registers a system wide hotkey. Every time the user presses the hotkey
+ registered here, this window will receive a hotkey event.
- If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
- the method will also call TransferDataToWindow() of all child windows.
+ It will receive the event even if the application is in the background
+ and does not have the input focus because the user is working with some
+ other application.
- @return Returns @false if a transfer failed.
+ @param hotkeyId
+ Numeric identifier of the hotkey. For applications this must be between 0
+ and 0xBFFF. If this function is called from a shared DLL, it must be a
+ system wide unique identifier between 0xC000 and 0xFFFF.
+ This is a MSW specific detail.
+ @param modifiers
+ A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
+ or wxMOD_WIN specifying the modifier keys that have to be pressed along
+ with the key.
+ @param virtualKeyCode
+ The virtual key code of the hotkey.
- @see TransferDataFromWindow(), wxValidator, Validate()
+ @return @true if the hotkey was registered successfully. @false if some
+ other application already registered a hotkey with this
+ modifier/virtualKeyCode combination.
+
+ @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
+ event. This function is currently only implemented
+ under Windows. It is used in the Windows CE port for
+ detecting hardware button presses.
+
+ @see UnregisterHotKey()
*/
- virtual bool TransferDataToWindow();
+ virtual bool RegisterHotKey(int hotkeyId, int modifiers,
+ int virtualKeyCode);
/**
Unregisters a system wide hotkey.
*/
virtual bool UnregisterHotKey(int hotkeyId);
- /**
- Unreserve an ID or range of IDs that was reserved by NewControlId().
- See @ref overview_windowids for more information.
-
- @param id
- The starting ID of the range of IDs to unreserve.
- @param count
- The number of sequential IDs to unreserve.
-
- @see NewControlId(), wxIdManager, @ref overview_windowids
- */
- static void UnreserveControlId(wxWindowID id, int count = 1);
-
- /**
- Unset any existing tooltip.
-
- @since 2.9.0
-
- @see SetToolTip()
- */
- void UnsetToolTip();
-
- /**
- Calling this method immediately repaints the invalidated area of the window and
- all of its children recursively while this would usually only happen when the
- flow of control returns to the event loop.
-
- Notice that this function doesn't invalidate any area of the window so
- nothing happens if nothing has been invalidated (i.e. marked as requiring
- a redraw). Use Refresh() first if you want to immediately redraw the
- window unconditionally.
- */
- virtual void Update();
-
/**
This function sends one or more wxUpdateUIEvent to the window.
The particular implementation depends on the window; for example a
are concerned). This may be necessary if you have called
wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
the overhead that wxWidgets incurs by sending update UI events in idle time.
- @a flags should be a bitlist of one or more of the wxUpdateUI enumeration.
+ @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.
If you are calling this function from an OnInternalIdle or OnIdle
function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
*/
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:
@deprecated @todo provide deprecation description
*/
virtual void SetInitialBestSize(const wxSize& size);
+
+ /**
+ Generate wxWindowDestroyEvent for this window.
+
+ This is called by the window itself when it is being destroyed and
+ usually there is no need to call it but see wxWindowDestroyEvent for
+ explanations of when you might want to do it.
+ */
+ void SendDestroyEvent();
+
+ /**
+ This function is public in wxEvtHandler but protected in wxWindow
+ because for wxWindows you should always call ProcessEvent() on the
+ pointer returned by GetEventHandler() and not on the wxWindow object
+ itself.
+
+ For convenience, a ProcessWindowEvent() method is provided as a synonym
+ for @code GetEventHandler()->ProcessEvent() @endcode.
+
+ Note that it's still possible to call these functions directly on the
+ wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
+ create subtle bugs when windows with event handlers pushed on them are
+ involved.
+
+ This holds also for all other wxEvtHandler functions.
+ */
+ virtual bool ProcessEvent(wxEvent& event);
+
+ //@{
+ /**
+ See ProcessEvent() for more info about why you shouldn't use this function
+ and the reason for making this function protected in wxWindow.
+ */
+ bool SafelyProcessEvent(wxEvent& event);
+ virtual void QueueEvent(wxEvent *event);
+ virtual void AddPendingEvent(const wxEvent& event);
+ void ProcessPendingEvents();
+ bool ProcessThreadEvent(const wxEvent& event);
+ //@}
};
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
projects / wxWidgets.git / blobdiff