Please note that all children of the window will be deleted automatically by
the destructor before the window itself is deleted which means that you don't
have to worry about deleting them manually. Please see the @ref
- overview_windowdeletionoverview "window
- deletion overview" for more information.
+ overview_windowdeletion "window deletion overview" for more information.
Also note that in this, and many others, wxWidgets classes some
@c GetXXX() methods may be overloaded (as, for example,
- wxWindow::GetSize or
- wxWindow::GetClientSize). In this case, the overloads
+ wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
are non-virtual because having multiple virtual functions with the same name
results in a virtual function name hiding at the derived class level (in
English, this means that the derived class has to override all overloaded
@library{wxcore}
@category{FIXME}
- @see @ref overview_eventhandlingoverview, @ref overview_windowsizingoverview
- "Window sizing overview"
+ @see @ref overview_eventhandling "Event handling overview",
+ @ref overview_windowsizing "Window sizing overview"
*/
class wxWindow : public wxEvtHandler
{
public:
- //@{
+ /**
+ Default constructor
+ */
+ wxWindow();
+
/**
Constructs a window, which can be a child of a frame, dialog or any other
non-control window.
@param name
Window name.
*/
- wxWindow();
wxWindow(wxWindow* parent, wxWindowID id,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxString& name = wxPanelNameStr);
- //@}
/**
Destructor. Deletes all sub-windows, then deletes itself. Instead of using
@see AcceptsFocusFromKeyboard()
*/
- bool AcceptsFocus() const;
+ virtual bool AcceptsFocus() const;
/**
This method may be overridden in the derived classes to return @false to
clicks it with the mouse, it shouldn't be included in the TAB traversal chain
when using the keyboard.
*/
- bool AcceptsFocusFromKeyboard() const;
+ virtual bool AcceptsFocusFromKeyboard() const;
+ /**
+ Overridden to indicate wehter this window or one of its children accepts
+ focus. Usually it's the same as AcceptsFocus() but is overridden for
+ container windows
+ */
+ virtual bool AcceptsFocusRecursively() const;
+
/**
Adds a child window. This is called automatically by window creation
functions so should not be required by the application programmer.
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.
- @wxsince{2.9.0}
+ @since 2.9.0
@param hflag
Whether the horizontal scroll bar should always be visible.
@param pt
The client position for the second form of the function.
*/
- virtual void ClientToScreen(int* x, int* y) const;
- const virtual wxPoint ClientToScreen(const wxPoint& pt) const;
+ void ClientToScreen(int* x, int* y) const;
+ wxPoint ClientToScreen(const wxPoint& pt) const;
//@}
/**
non-existent
windows.
- @returns @true if the window has either been successfully deleted, or it
+ @return @true if the window has either been successfully deleted, or it
has been added to the list of windows pending real
deletion.
*/
/**
Disables the window, same as @ref enable() Enable(@false).
- @returns Returns @true if the window has been disabled, @false if it had
+ @return Returns @true if the window has been disabled, @false if it had
been already disabled before the call to this function.
*/
bool Disable();
@param enable
If @true, enables the window for input. If @false, disables the window.
- @returns Returns @true if the window has been enabled or disabled, @false
+ @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.
*/
static wxWindow* FindFocus();
- //@{
/**
- Find a child of this window, by name.
+ Find a child of this window, by @a id. May return @a this if
+ it matches itself.
*/
wxWindow* FindWindow(long id) const;
- const wxWindow* FindWindow(const wxString& name) const;
- //@}
+
+
+ /**
+ Find a child of this window, by name. May return @a this if
+ it matches itself.
+ */
+ wxWindow* FindWindow(const wxString& name) const;
/**
Find the first window with the given @e id.
@see SetBackgroundColour(), SetForegroundColour(),
GetForegroundColour()
*/
- virtual wxColour GetBackgroundColour() const;
+ wxColour GetBackgroundColour() const;
/**
Returns the background style of the window. The background style can be one of:
//@{
/**
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 *.
+ is a type-safe wxList-like class whose elements are of type @c wxWindow*.
*/
- wxWindowList GetChildren() const;
- const wxWindowList GetChildren() const;
+ wxWindowList& GetChildren();
+ const wxWindowList& GetChildren() const;
//@}
/**
@see GetSize(), GetVirtualSize()
*/
void GetClientSize(int* width, int* height) const;
- const wxSize GetClientSize() const;
+ wxSize GetClientSize() const;
//@}
/**
Return the sizer that this window is a member of, if any, otherwise
@NULL.
*/
- const wxSizer* GetContainingSizer() const;
+ wxSizer* GetContainingSizer() const;
/**
Return the cursor associated with this window.
@see SetCursor()
*/
- const wxCursor GetCursor() const;
+ const wxCursor& GetCursor() const;
/**
Currently this is the same as calling
@see SetForegroundColour(), SetBackgroundColour(),
GetBackgroundColour()
*/
- virtual wxColour GetForegroundColour();
+ wxColour GetForegroundColour();
/**
Returns the grandparent of a window, or @NULL if there isn't one.
/**
Returns the minimum size of the window, an indication to the sizer layout
- mechanism
- that this is the minimum required size. It normally just returns the value set
- by SetMinSize(), but it can be overridden to do the
- calculation on demand.
+ 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()
*/
Returns the next window after this one among the parent children or @NULL if
this window is the last child.
- @wxsince{2.8.8}
+ @since 2.8.8
@see GetPrevSibling()
*/
@param y
The vertical position of the menu
- @returns The selected menu item id or wxID_NONE if none selected or an
+ @return The selected menu item id or wxID_NONE if none selected or an
error occurred.
*/
int GetPopupMenuSelectionFromUser(wxMenu& menu,
@see GetScreenPosition()
*/
- virtual void GetPosition(int* x, int* y) const;
- const wxPoint GetPosition() const;
+ void GetPosition(int* x, int* y) const;
+ wxPoint GetPosition() const;
//@}
/**
@NULL if
this window is the first child.
- @wxsince{2.8.8}
+ @since 2.8.8
@see GetNextSibling()
*/
@see GetScreenRect()
*/
- virtual wxRect GetRect() const;
+ wxRect GetRect() const;
//@{
/**
@see GetPosition()
*/
- virtual void GetScreenPosition(int* x, int* y) const;
- const wxPoint GetScreenPosition() const;
+ void GetScreenPosition(int* x, int* y) const;
+ wxPoint GetScreenPosition() const;
//@}
/**
@see GetRect()
*/
- virtual wxRect GetScreenRect() const;
+ wxRect GetScreenRect() const;
/**
Returns the built-in scrollbar position.
Navigate() if the key event is one normally used for
keyboard navigation and return @true in this case.
- @returns Returns @true if the key pressed was for navigation and was
+ @return Returns @true if the key pressed was for navigation and was
handled, @false otherwise.
@see Navigate()
bool Hide();
/**
- This function hides a window, like Hide(), but using a
- special visual effect if possible.
- The parameters of this function are the same as for
- ShowWithEffect(), please see their
- description there.
+ This function hides a window, like Hide(), but using a special visual
+ effect if possible.
+
+ The parameters of this function are the same as for ShowWithEffect(),
+ please see their description there.
- @wxsince{2.9.0}
+ @since 2.9.0
*/
virtual bool HideWithEffect(wxShowEffect effect,
- unsigned timeout = 0,
- wxDirection dir = wxBOTTOM);
+ unsigned timeout = 0);
/**
This function is (or should be, in case of custom controls) called during
A combination of wxNavigationKeyEvent::IsForward and
wxNavigationKeyEvent::WinChange.
- @returns Returns @true if the focus was moved to another window or @false
+ @return Returns @true if the focus was moved to another window or @false
if nothing changed.
@remarks You may wish to call this from a text control custom keypress
@param count
The number of sequential IDs to reserve.
- @returns Returns the ID or the first ID of the range, or wxID_NONE if the
+ @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_windowidsoverview
@param virtualKeyCode
The virtual key code of the hotkey.
- @returns @true if the hotkey was registered successfully. @false if some
+ @return @true if the hotkey was registered successfully. @false if some
other application already registered a hotkey with this
modifier/virtualKeyCode combination.
The event handler to remove, must be non-@NULL and
must be present in this windows event handlers chain
- @returns Returns @true if it was found and @false otherwise (this also
+ @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).
Scrolls the window by the given number of lines down (if @a lines is
positive) or up.
- @returns Returns @true if the window was scrolled, @false if it was already
+ @return Returns @true if the window was scrolled, @false if it was already
on top/bottom and nothing was done.
@remarks This function is currently only implemented under MSW and
Scrolls the window by the given number of pages down (if @a pages is
positive) or up.
- @returns Returns @true if the window was scrolled, @false if it was already
+ @return Returns @true if the window was scrolled, @false if it was already
on top/bottom and nothing was done.
@remarks This function is currently only implemented under MSW and wxGTK.
Font to associate with this window, pass
wxNullFont to reset to the default font.
- @returns @true if the want was really changed, @false if it was already set
+ @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()
/**
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. You may need to call this if you change the window size after
+ area.
+
+ You may need to call this if you change the window size after
construction and before adding to its parent sizer.
+ Note, that just as with SetMinSize(), calling this method doesn't
+ prevent the program from explicitly making the window smaller than the
+ specified size.
+
@see SetMinSize()
*/
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. You may need to call this
- if you change the window size after construction and before adding
- to its parent sizer.
+ Sets the minimum size of the window, to indicate to the sizer layout
+ mechanism that this is the minimum required size.
+
+ 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()
*/
virtual void SetSize(const wxSize& size);
//@}
- /**
- Use of this function for windows which are not toplevel windows
- (such as wxDialog or wxFrame) is discouraged. Please use
- SetMinSize() and SetMaxSize()
- instead.
-
- @see wxTopLevelWindow::SetSizeHints.
- */
-
-
/**
Sets the window to have the given layout sizer. The window
will then own the object, and will take care of its deletion.
void SetVirtualSize(const wxSize& size);
//@}
- //@{
- /**
- Allows specification of minimum and maximum virtual window sizes.
- If a pair of values is not set (or set to -1), the default values
- will be used.
-
- @param minW
- Specifies the minimum width allowable.
- @param minH
- Specifies the minimum height allowable.
- @param maxW
- Specifies the maximum width allowable.
- @param maxH
- Specifies the maximum height allowable.
- @param minSize
- Minimum size.
- @param maxSize
- Maximum size.
-
- @remarks If this function is called, the user will not be able to size
- the virtual area of the window outside the given bounds.
- */
- virtual void SetVirtualSizeHints(int minW, int minH, int maxW = -1,
- int maxH = -1);
- void SetVirtualSizeHints(const wxSize& minSize = wxDefaultSize,
- const wxSize& maxSize = wxDefaultSize);
- //@}
-
/**
Identical to SetWindowStyleFlag().
*/
@param show
If @true displays the window. Otherwise, hides it.
- @returns @true if the window has been shown or hidden or @false if nothing
+ @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
virtual bool Show(bool show = true);
/**
- This function shows a window, like Show(), but using a
- special visual effect if possible.
- Possible values for @a effect are:
+ This function shows a window, like Show(), but using a special visual
+ effect if possible.
- wxSHOW_EFFECT_ROLL
+ @param effect
+ The effect to use.
- Roll window effect
+ @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.
- wxSHOW_EFFECT_SLIDE
+ @note Currently this function is only implemented in wxMSW and does the
+ same thing as Show() in the other ports.
- Sliding window effect
-
- wxSHOW_EFFECT_BLEND
-
- Fade in or out effect
-
- wxSHOW_EFFECT_EXPAND
-
- Expanding or collapsing effect
-
- For the roll and slide effects the @a dir parameter specifies the animation
- direction: it can be one of @c wxTOP, @c wxBOTTOM, @c wxLEFT
- or @c wxRIGHT. For the other effects, this parameter is unused.
- 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.
- Currently this function is only implemented in wxMSW and does the same thing as
- Show() in the other ports.
-
- @wxsince{2.9.0}
+ @since 2.9.0
@see HideWithEffect()
*/
virtual bool ShowWithEffect(wxShowEffect effect,
- unsigned timeout = 0,
- wxDirection dir = wxBOTTOM);
+ unsigned timeout = 0);
/**
Reenables window updating after a previous call to Freeze().
Also, please notice that not all styles can be changed after the control
creation.
- @returns Returns @true if the style was turned on by this function, @false
+ @return Returns @true if the style was turned on by this function, @false
if it was switched off.
@see SetWindowStyleFlag(), HasFlag()
If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
the method will also call TransferDataToWindow() of all child windows.
- @returns Returns @false if a transfer failed.
+ @return Returns @false if a transfer failed.
@see TransferDataFromWindow(), wxValidator, Validate()
*/
Numeric identifier of the hotkey. Must be the same id that was passed to
RegisterHotKey.
- @returns @true if the hotkey was unregistered successfully, @false if the
+ @return @true if the hotkey was unregistered successfully, @false if the
id was invalid.
@remarks This function is currently only implemented under MSW.
If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
the method will also call Validate() of all child windows.
- @returns Returns @false if any of the validations failed.
+ @return Returns @false if any of the validations failed.
@see TransferDataFromWindow(), TransferDataToWindow(),
wxValidator
};
+/// Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
+enum wxShowEffect
+{
+ /// Roll window to the left
+ wxSHOW_EFFECT_ROLL_TO_LEFT,
+ /// Roll window to the right
+ wxSHOW_EFFECT_ROLL_TO_RIGHT,
+ /// Roll window to the top
+ wxSHOW_EFFECT_ROLL_TO_TOP,
+ /// Roll window to the bottom
+ wxSHOW_EFFECT_ROLL_TO_BOTTOM,
+ /// Slide window to the left
+ wxSHOW_EFFECT_SLIDE_TO_LEFT,
+ /// Slide window to the right
+ wxSHOW_EFFECT_SLIDE_TO_RIGHT,
+ /// Slide window to the top
+ wxSHOW_EFFECT_SLIDE_TO_TOP,
+ /// Slide window to the bottom
+ wxSHOW_EFFECT_SLIDE_TO_BOTTOM,
+ /// Fade in or out effect
+ wxSHOW_EFFECT_BLEND,
+ /// Expanding or collapsing effect
+ wxSHOW_EFFECT_EXPAND
+};
+
+
// ============================================================================
// Global functions/macros
projects / wxWidgets.git / blobdiff