*/
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;
/**
- Adds a child window. This is called automatically by window creation
- 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.
+ Returns @true if the window (or in case of composite controls, its main
+ child window) has focus.
- @param child
- Child window to add.
+ @see FindFocus()
*/
- virtual void AddChild(wxWindow* child);
+ virtual bool HasFocus() const;
/**
- 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.
+ This method is only implemented by ports which have support for
+ native TAB traversal (such as GTK+ 2.0).
- @since 2.9.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().
- @param hflag
- Whether the horizontal scroll bar should always be visible.
- @param vflag
- Whether the vertical scroll bar should always be visible.
+ @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
+ */
+ virtual void SetCanFocus(bool canFocus);
- @remarks This function is currently only implemented under Mac/Carbon.
+ /**
+ This sets the window to receive keyboard input.
+
+ @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
+ wxPanel::SetFocusIgnoringChildren
*/
- virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
+ virtual void SetFocus();
/**
- Sets the cached best size value.
+ 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.
*/
- void CacheBestSize(const wxSize& size) const;
+ virtual void SetFocusFromKbd();
+
+ //@}
+
/**
- 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.
+ @name Child management functions
*/
- virtual bool CanSetTransparent();
+ //@{
/**
- Directs all mouse input to this window.
- Call ReleaseMouse() to release the capture.
+ Adds a child window. This is called automatically by window creation
+ 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.
- 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 child
+ Child window to add.
+ */
+ virtual void AddChild(wxWindow* child);
- 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.
+ /**
+ Destroys all children of a window. Called automatically by the destructor.
+ */
+ bool DestroyChildren();
- @see ReleaseMouse(), wxMouseCaptureLostEvent
+ /**
+ Find a child of this window, by @a id.
+ May return @a this if it matches itself.
*/
- void CaptureMouse();
+ wxWindow* FindWindow(long id) const;
/**
- A synonym for Centre().
+ Find a child of this window, by name.
+ May return @a this if it matches itself.
*/
- void Center(int dir = wxBOTH);
+ wxWindow* FindWindow(const wxString& name) const;
/**
- A synonym for CentreOnParent().
+ 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*.
*/
- void CenterOnParent(int dir = wxBOTH);
+ wxWindowList& GetChildren();
/**
- Centres the window.
+ @overload
+ */
+ const wxWindowList& GetChildren() const;
- @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.
+ /**
+ Removes a child 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.
+ 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 Center()
+ @param child
+ Child window to remove.
*/
- void Centre(int direction = wxBOTH);
-
- /**
- Centres the window on its parent. This is a more readable synonym for Centre().
+ virtual void RemoveChild(wxWindow* child);
- @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
+ /**
+ @name Sibling and parent management functions
*/
- void CentreOnParent(int direction = wxBOTH);
+ //@{
/**
- Clears the window by filling it with the current background colour. Does not
- cause an erase background event to be generated.
+ Returns the grandparent of a window, or @NULL if there isn't one.
*/
- virtual void ClearBackground();
+ wxWindow* GetGrandParent() const;
/**
- Converts to screen coordinates from coordinates relative to this window.
+ Returns the next window after this one among the parent children or @NULL
+ if this window is the last child.
- @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.8.8
- @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
+ @see GetPrevSibling()
*/
- void ClientToScreen(int* x, int* y) const;
+ wxWindow* GetNextSibling() const;
/**
- Converts to screen coordinates from coordinates relative to this window.
-
- @param pt
- The client position for the second form of the function.
+ Returns the parent of the window, or @NULL if there is no parent.
*/
- wxPoint ClientToScreen(const wxPoint& pt) const;
+ wxWindow* GetParent() const;
/**
- Converts client area size @a size to corresponding window size.
-
- 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.
+ Returns the previous window before this one among the parent children or @c
+ @NULL if this window is the first child.
@since 2.8.8
- @see WindowToClientSize()
+ @see GetNextSibling()
*/
- virtual wxSize ClientToWindowSize(const wxSize& size) const;
-
+ wxWindow* GetPrevSibling() 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.
+ 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.
- 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 newParent
+ New parent.
+ */
+ virtual bool Reparent(wxWindow* newParent);
- @since 2.8.8
+ //@}
- @see ClientToWindowSize()
+
+ /**
+ @name Scrolling and scrollbars
*/
- virtual wxSize WindowToClientSize(const wxSize& size) const;
+ //@{
/**
- This function simply generates a wxCloseEvent whose handler usually tries
- to close the window. It doesn't close the window itself, however.
+ 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 force
- @false if the window's close handler should be able to veto the destruction
- of this window, @true if it cannot.
+ @since 2.9.0
- @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
+ @param hflag
+ Whether the horizontal scroll bar should always be visible.
+ @param vflag
+ Whether the vertical scroll bar should always be visible.
- @see @ref overview_windowdeletion "Window Deletion Overview",
- Destroy(), wxCloseEvent
+ @remarks This function is currently only implemented under Mac/Carbon.
*/
- bool Close(bool force = false);
+ virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
- //@{
/**
- Converts a point or size from dialog units to pixels.
+ Returns the built-in scrollbar position.
- 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 See SetScrollbar()
+ */
+ virtual int GetScrollPos(int orientation) 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 built-in scrollbar range.
- @see ConvertPixelsToDialog()
+ @see SetScrollbar()
*/
- wxPoint ConvertDialogToPixels(const wxPoint& pt);
- wxSize ConvertDialogToPixels(const wxSize& sz);
- //@}
+ virtual int GetScrollRange(int orientation) const;
- //@{
/**
- Converts a point or size from pixels to dialog units.
-
- 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.
-
- @remarks Dialog units are used for maintaining a dialog's proportions
- even if the font changes.
+ Returns the built-in scrollbar thumb size.
- @see ConvertDialogToPixels()
+ @see SetScrollbar()
*/
- wxPoint ConvertPixelsToDialog(const wxPoint& pt);
- wxSize ConvertPixelsToDialog(const wxSize& sz);
- //@}
+ virtual int GetScrollThumb(int orientation) const;
/**
- 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.
+ Returns @true if this window has a scroll bar for this orientation.
- @return @true if the window has either been successfully deleted, or it
- has been added to the list of windows pending real deletion.
+ @param orient
+ Orientation to check, either wxHORIZONTAL or wxVERTICAL.
*/
- virtual bool Destroy();
+ bool HasScrollbar(int orient) const;
/**
- Destroys all children of a window. Called automatically by the destructor.
+ Return whether a scrollbar is always shown.
+
+ @param orient
+ Orientation to check, either wxHORIZONTAL or wxVERTICAL.
+
+ @see AlwaysShowScrollbars()
*/
- bool DestroyChildren();
+ virtual bool IsScrollbarAlwaysShown(int orient) const;
/**
- Returns true if this window is in process of being destroyed.
+ Scrolls the window by the given number of lines down (if @a lines is
+ positive) or up.
- 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.
+ @return Returns @true if the window was scrolled, @false if it was already
+ on top/bottom and nothing was done.
- 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;
+ @remarks This function is currently only implemented under MSW and
+ wxTextCtrl under wxGTK (it also works for wxScrolled classes
+ under all platforms).
+
+ @see ScrollPages()
+ */
+ virtual bool ScrollLines(int lines);
/**
- Disables the window. Same as @ref Enable() Enable(@false).
+ Scrolls the window by the given number of pages down (if @a pages is
+ positive) or up.
- @return Returns @true if the window has been disabled, @false if it had
- been already disabled before the call to this function.
+ @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.
+
+ @see ScrollLines()
*/
- bool Disable();
+ virtual bool ScrollPages(int pages);
/**
- 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:
+ Physically scrolls the pixels in the window and move child windows accordingly.
- @code
- // do the window-specific processing after processing the update event
- void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
- {
- if ( event.GetSetEnabled() )
- Enable(event.GetEnabled());
+ @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)
- if ( event.GetSetText() )
- {
- if ( event.GetText() != GetTitle() )
- SetTitle(event.GetText());
- }
- }
- @endcode
+ @remarks Note that you can often use wxScrolled instead of using this
+ function directly.
*/
- virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
+ virtual void ScrollWindow(int dx, int dy,
+ const wxRect* rect = NULL);
/**
- Enables or disables eligibility for drop file events (OnDropFiles).
+ Same as #ScrollLines (-1).
+ */
+ bool LineUp();
- @param accept
- If @true, the window is eligible for drop file events.
- If @false, the window will not accept drop file events.
+ /**
+ Same as #ScrollLines (1).
+ */
+ bool LineDown();
- @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.
+ /**
+ Same as #ScrollPages (-1).
+ */
+ bool PageUp();
- @see SetDropTarget()
+ /**
+ Same as #ScrollPages (1).
*/
- virtual void DragAcceptFiles(bool accept);
+ bool PageDown();
/**
- 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.
+ Sets the position of one of the built-in scrollbars.
- @param enable
- If @true, enables the window for input. If @false, disables the window.
+ @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.
- @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.
+ @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 IsEnabled(), Disable(), wxRadioBox::Enable
+ @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
+ wxScrolled
*/
- virtual bool Enable(bool enable = true);
+ virtual void SetScrollPos(int orientation, int pos,
+ bool refresh = true);
/**
- Finds the window or control which currently has the keyboard focus.
+ Sets the scrollbar properties of a built-in scrollbar.
- @remarks Note that this is a static function, so it can be called without
- needing a wxWindow pointer.
+ @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.
- @see SetFocus(), HasFocus()
- */
- static wxWindow* FindFocus();
+ @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.
- /**
- Find a child of this window, by @a id.
- May return @a this if it matches itself.
+ @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
*/
- wxWindow* FindWindow(long id) const;
+ virtual void SetScrollbar(int orientation, int position,
+ int thumbSize, int range,
+ bool refresh = true);
+ //@}
- /**
- 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.
+ @name Sizing
- 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 also the protected functions DoGetBestSize() and SetInitialBestSize().
+ */
+ //@{
- @see FindWindow()
+ /**
+ Sets the cached best size value.
*/
- static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
+ void CacheBestSize(const wxSize& size) const;
/**
- Find a window by its label.
+ Converts client area size @a size to corresponding window 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.
+ 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 FindWindow()
+ @since 2.8.8
+
+ @see WindowToClientSize()
*/
- static wxWindow* FindWindowByLabel(const wxString& label,
- const wxWindow* parent = 0);
+ virtual wxSize ClientToWindowSize(const wxSize& size) const;
/**
- Find a window by its name (as given in a window constructor or Create()
- function call).
+ 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.
- 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.
+ 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.
- The search is recursive in both cases. If no window with such name is found,
- FindWindowByLabel() is called.
+ @since 2.8.8
- @see FindWindow()
+ @see ClientToWindowSize()
*/
- static wxWindow* FindWindowByName(const wxString& name,
- const wxWindow* parent = 0);
+ virtual wxSize WindowToClientSize(const wxSize& size) const;
/**
Sizes the window so that it fits around its subwindows.
*/
virtual void FitInside();
- /**
- Freezes the window or, in other words, prevents any updates from taking
- place on screen, the window is not redrawn at all.
-
- 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.
-
- If the window has any children, they are recursively frozen too.
-
- 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.
- */
- wxAcceleratorTable* GetAcceleratorTable();
-
- /**
- Returns the accessible object for this window, if any.
- See also wxAccessible.
- */
- wxAccessible* GetAccessible();
-
- /**
- Returns the background colour of the window.
-
- @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
- */
- wxColour GetBackgroundColour() const;
-
- /**
- Returns the background style of the window.
- The background style can be one of the wxBackgroundStyle.
-
- @see SetBackgroundColour(), GetForegroundColour(),
- SetBackgroundStyle(), SetTransparent()
- */
- virtual wxBackgroundStyle GetBackgroundStyle() const;
-
/**
This functions returns the best acceptable minimal size for the window.
*/
wxSize GetBestSize() const;
- /**
- Returns the currently captured window.
-
- @see HasCapture(), CaptureMouse(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
- */
- static wxWindow* GetCapture();
-
- /**
- Returns the caret() associated with the window.
- */
- wxCaret* GetCaret() const;
-
- /**
- Returns the character height for this window.
- */
- virtual int GetCharHeight() const;
-
- /**
- Returns the average character width for this window.
- */
- virtual int GetCharWidth() 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*.
- */
- wxWindowList& GetChildren();
- const wxWindowList& GetChildren() const;
- //@}
-
- /**
- Returns the default font and colours which are used by the control.
-
- This is useful if you want to use the same font or colour in your own control
- as in a standard control -- which is a much better idea than hard coding specific
- colours or fonts which might look completely out of place on the users
- system, especially if it uses themes.
-
- The @a variant parameter is only relevant under Mac currently and is
- ignore under other platforms. Under Mac, it will change the size of the
- returned font. See SetWindowVariant() for more about this.
-
- This static method is "overridden" in many derived classes and so calling,
- for example, wxButton::GetClassDefaultAttributes() will typically
- return the values appropriate for a button which will be normally different
- from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
-
- The @c wxVisualAttributes structure has at least the fields
- @c font, @c colFg and @c colBg. All of them may be invalid
- if it was not possible to determine the default control appearance or,
- especially for the background colour, if the field doesn't make sense as is
- the case for @c colBg for the controls with themed background.
-
- @see InheritAttributes()
- */
- static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
-
- //@{
/**
Returns the size of the window 'client area' in pixels.
@see GetSize(), GetVirtualSize()
*/
void GetClientSize(int* width, int* height) const;
- wxSize GetClientSize() const;
- //@}
-
- /**
- Returns a pointer to the window's layout constraints, or @NULL if there are none.
- */
- wxLayoutConstraints* GetConstraints() const;
-
- /**
- 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()
- */
- const wxCursor& GetCursor() const;
-
- /**
- Currently this is the same as calling
- wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
-
- 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.
-
- 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.
- */
- virtual wxVisualAttributes GetDefaultAttributes() const;
/**
- Returns the associated drop target, which may be @NULL.
-
- @see SetDropTarget(), @ref overview_dnd
+ @overload
*/
- virtual wxDropTarget* GetDropTarget() const;
+ wxSize GetClientSize() const;
/**
Merges the window's best size into the min size and returns the result.
*/
wxSize GetEffectiveMinSize() const;
- /**
- Returns the event handler for this window.
- By default, the window is its own event handler.
-
- @see SetEventHandler(), PushEventHandler(),
- PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
- */
- wxEvtHandler* GetEventHandler() const;
-
- /**
- Returns the extra style bits for the window.
- */
- long GetExtraStyle() const;
-
- /**
- Returns the font for this window.
-
- @see SetFont()
- */
- wxFont GetFont() const;
-
- /**
- Returns the foreground colour of the window.
-
- @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 SetForegroundColour(), SetBackgroundColour(),
- GetBackgroundColour()
- */
- wxColour GetForegroundColour() const;
-
- /**
- Returns the grandparent of a window, or @NULL if there isn't one.
- */
- wxWindow* GetGrandParent() const;
-
- /**
- Returns the platform-specific handle of the physical window.
- Cast it to an appropriate handle, such as @b HWND for Windows,
- @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
- */
- virtual WXWidget GetHandle() const;
-
- /**
- Gets the help text to be used as context-sensitive help for this window.
- Note that the text is actually stored by the current wxHelpProvider
- implementation, and not in the window object itself.
-
- @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
- */
- wxString GetHelpText() const;
-
- /**
- Gets the help text to be used as context-sensitive help for this window.
- This method should be overridden if the help message depends on the position
- inside the window, otherwise GetHelpText() can be used.
-
- @param point
- Coordinates of the mouse at the moment of help event emission.
- @param origin
- Help event origin, see also wxHelpEvent::GetOrigin.
- */
- virtual wxString GetHelpTextAtPoint(const wxPoint& point,
- wxHelpEvent::Origin origin) 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
- */
- 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.
- */
- virtual wxString GetLabel() const;
-
/**
Returns the maximum size of window's client area.
virtual wxSize GetMinSize() const;
/**
- Returns the window's name.
+ Returns the size of the entire window in pixels, including title bar, border,
+ scrollbars, etc.
- @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().
+ 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.
- @see SetName()
+ @param width
+ Receives the window width.
+ @param height
+ Receives the window height.
+
+ @see GetClientSize(), GetVirtualSize()
*/
- virtual wxString GetName() const;
+ void GetSize(int* width, int* height) 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
-
- @see GetPrevSibling()
+ See the GetSize(int*,int*) overload for more info.
*/
- wxWindow* GetNextSibling() const;
+ wxSize GetSize() const;
/**
- Returns the parent of the window, or @NULL if there is no parent.
+ 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.
*/
- wxWindow* GetParent() const;
+ wxSize GetVirtualSize() 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.
-
- 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.
-
- The parameter @a menu is the menu to show.
- The parameter @a pos (or the parameters @a x and @a y) is the
- position at which to show the menu in client coordinates.
-
- @return
- The selected menu item id or @c wxID_NONE if none selected or an
- error occurred.
+ Like the other GetVirtualSize() overload but uses pointers instead.
- @since 2.9.0
+ @param width
+ Receives the window virtual width.
+ @param height
+ Receives the window virtual height.
*/
- int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
- int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
- //@}
+ void GetVirtualSize(int* width, int* height) 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.
-
- @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()
+ Returns the size of the left/right and top/bottom borders of this window in x
+ and y components of the result respectively.
*/
- void GetPosition(int* x, int* y) const;
+ virtual wxSize GetWindowBorderSize() 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.
-
- @see GetScreenPosition()
+ Return the sizer that this window is a member of, if any, otherwise @NULL.
*/
- wxPoint GetPosition() const;
+ wxSizer* GetContainingSizer() const;
/**
- Returns the previous window before this one among the parent children or @c
- @NULL if this window is the first child.
-
- @since 2.8.8
-
- @see GetNextSibling()
+ Return the sizer associated with the window by a previous call to
+ SetSizer() or @NULL.
*/
- wxWindow* GetPrevSibling() const;
+ wxSizer* GetSizer() const;
/**
- Returns the position and size of the window as a wxRect object.
-
- @see GetScreenRect()
+ Resets the cached best size value so it will be recalculated the next time it
+ is needed.
*/
- wxRect GetRect() const;
-
+ void InvalidateBestSize();
/**
- 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.
+ Posts a size event to the window.
- @see GetPosition()
- */
- void GetScreenPosition(int* x, int* y) const;
+ This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
+ */
+ void PostSizeEvent();
/**
- Returns the window position in screen coordinates, whether the window is a
- child window or a top level one.
+ Posts a size event to the parent of this window.
- @see GetPosition()
- */
- wxPoint GetScreenPosition() const;
+ This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
+ argument.
+ */
+ void PostSizeEventToParent();
/**
- Returns the position and size of the window on the screen as a wxRect object.
+ This function sends a dummy @ref wxSizeEvent "size event" to
+ the window allowing it to re-layout its children positions.
- @see GetRect()
- */
- wxRect GetScreenRect() const;
+ 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.
- /**
- Returns the built-in scrollbar position.
+ 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.
- @see See SetScrollbar()
+ @param flags
+ May include @c wxSEND_EVENT_POST. Default value is 0.
*/
- virtual int GetScrollPos(int orientation) const;
+ virtual void SendSizeEvent(int flags = 0);
/**
- Returns the built-in scrollbar range.
+ Safe wrapper for GetParent()->SendSizeEvent().
- @see SetScrollbar()
- */
- virtual int GetScrollRange(int orientation) const;
+ 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).
- /**
- Returns the built-in scrollbar thumb size.
+ @see PostSizeEventToParent()
- @see SetScrollbar()
- */
- virtual int GetScrollThumb(int orientation) const;
+ @param flags
+ See description of this parameter in SendSizeEvent() documentation.
+ */
+ void SendSizeEventToParent(int flags = 0);
/**
- 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.
+ This sets the size of the window client area in pixels.
- @see GetClientSize(), GetVirtualSize()
+ 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.
*/
- void GetSize(int* width, int* height) const;
+ virtual void SetClientSize(int width, int height);
/**
- See the GetSize(int*,int*) overload for more info.
+ @overload
*/
- wxSize GetSize() const;
+ virtual void SetClientSize(const wxSize& size);
/**
- Return the sizer associated with the window by a previous call to
- SetSizer() or @NULL.
+ 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.
*/
- wxSizer* GetSizer() const;
+ void SetContainingSizer(wxSizer* sizer);
/**
- Gets the dimensions of the string as it would be drawn on the
- window with the currently selected font.
+ A @e smart SetSize that will fill in default size components with the
+ window's @e best size values.
- The text extent is returned in @a w and @a h pointers.
+ 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.
- @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).
- */
- virtual void GetTextExtent(const wxString& string, int* w, int* h,
- int* descent = NULL,
- int* externalLeading = NULL,
- const wxFont* font = NULL) const;
+ Most controls will use this to set their initial size, and their min
+ size to the passed in value (if any.)
- /**
- Gets the dimensions of the string as it would be drawn on the
- window with the currently selected font.
+ @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
+ @ref overview_windowsizing
*/
- wxSize GetTextExtent(const wxString& string) const;
+ void SetInitialSize(const wxSize& size = wxDefaultSize);
/**
- Get the associated tooltip or @NULL if none.
+ 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.
+
+ @see SetMaxSize()
*/
- wxToolTip* GetToolTip() const;
+ virtual void SetMaxClientSize(const wxSize& size);
/**
- Returns the region specifying which parts of the window have been damaged.
- Should only be called within an wxPaintEvent handler.
+ Sets the maximum size of the window, to indicate to the sizer layout mechanism
+ that this is the maximum possible size.
- @see wxRegion, wxRegionIterator
+ @see SetMaxClientSize()
*/
- const wxRegion& GetUpdateRegion() const;
+ virtual void SetMaxSize(const wxSize& size);
/**
- Returns a pointer to the current validator for the window, or @NULL if
- there is none.
- */
- virtual wxValidator* GetValidator();
+ 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.
- //@{
- /**
- 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.
- */
- wxSize GetVirtualSize() const;
+ You may need to call this if you change the window size after
+ construction and before adding to its parent sizer.
- /**
- Like the other GetVirtualSize() overload but uses pointers instead.
+ Note, that just as with SetMinSize(), calling this method doesn't
+ prevent the program from explicitly making the window smaller than the
+ specified size.
- @param width
- Receives the window virtual width.
- @param height
- Receives the window virtual height.
+ @see SetMinSize()
*/
- void GetVirtualSize(int* width, int* height) const;
- //@}
+ virtual void SetMinClientSize(const wxSize& size);
/**
- 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;
+ Sets the minimum size of the window, to indicate to the sizer layout
+ mechanism that this is the minimum required size.
- //@{
- /**
- Gets the window style that was passed to the constructor or Create()
- method. GetWindowStyle() is another name for the same function.
+ 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 long GetWindowStyleFlag() const;
- long GetWindowStyle() const;
- //@}
+ virtual void SetMinSize(const wxSize& size);
/**
- Returns the value previously passed to SetWindowVariant().
+ Sets the size of the window in pixels.
+
+ @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).
+
+ @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 Move()
*/
- wxWindowVariant GetWindowVariant() const;
+ void SetSize(int x, int y, int width, int height,
+ int sizeFlags = wxSIZE_AUTO);
/**
- 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.
+ Sets the size of the window in pixels.
+ The size is specified using a wxRect, wxSize or by a couple of @c int objects.
- @return Returns @true if the key pressed was for navigation and was
- handled, @false otherwise.
+ @remarks This form must be used with non-default width and height values.
- @see Navigate()
+ @see Move()
*/
- bool HandleAsNavigationKey(const wxKeyEvent& event);
+ virtual void SetSize(const wxRect& rect);
/**
- Shorthand for:
- @code
- GetEventHandler()->SafelyProcessEvent(event);
- @endcode
+ @overload
*/
- bool HandleWindowEvent(wxEvent& event) const;
+ virtual void SetSize(const wxSize& size);
/**
- Returns @true if this window has the current mouse capture.
-
- @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
- wxMouseCaptureChangedEvent
+ @overload
*/
- virtual bool HasCapture() const;
+ virtual void SetSize(int width, int height);
/**
- Returns @true if the window has the given @a exFlag bit set in its
- extra styles.
+ 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 SetExtraStyle()
+ @see wxTopLevelWindow::SetSizeHints
*/
- bool HasExtraStyle(int exFlag) const;
+ void SetSizeHints( const wxSize& minSize,
+ const wxSize& maxSize=wxDefaultSize,
+ const wxSize& incSize=wxDefaultSize);
/**
- Returns @true if the window has the given @a flag bit set.
- */
- bool HasFlag(int flag) const;
+ Sets the window to have the given layout sizer.
+ The window will then own the object, and will take care of its deletion.
+ If an existing layout constraints object is already owned by the
+ window, it will be deleted if the deleteOld parameter is @true.
- /**
- Returns @true if the window (or in case of composite controls, its main
- child window) has focus.
+ Note that this function will also call SetAutoLayout() implicitly with @true
+ parameter if the @a sizer is non-@NULL and @false otherwise.
- @see FindFocus()
+ @param sizer
+ The sizer to set. Pass @NULL to disassociate and conditionally delete
+ the window's sizer. See below.
+ @param deleteOld
+ If @true (the default), this will delete any pre-existing sizer.
+ Pass @false if you wish to handle deleting the old sizer yourself.
+
+ @remarks SetSizer enables and disables Layout automatically.
*/
- virtual bool HasFocus() const;
+ void SetSizer(wxSizer* sizer, bool deleteOld = 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.
+ 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.
*/
- virtual bool HasMultiplePages() const;
+ void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
/**
- Returns @true if this window has a scroll bar for this orientation.
+ Sets the virtual size of the window in pixels.
+ */
+ void SetVirtualSize(int width, int height);
- @param orient
- Orientation to check, either wxHORIZONTAL or wxVERTICAL.
+ /**
+ @overload
*/
- bool HasScrollbar(int orient) const;
+ void SetVirtualSize(const wxSize& size);
+
+ //@}
+
/**
- Returns @true if this window background is transparent (as, for example,
- for wxStaticText) and should show the parent window background.
+ @name Positioning
+ */
+ //@{
- 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.
+ /**
+ A synonym for Centre().
*/
- virtual bool HasTransparentBackground();
+ void Center(int dir = wxBOTH);
/**
- Equivalent to calling wxWindow::Show(@false).
+ A synonym for CentreOnParent().
*/
- bool Hide();
+ void CenterOnParent(int dir = wxBOTH);
/**
- This function hides a window, like Hide(), but using a special visual
- effect if possible.
+ Centres the window.
- The parameters of this function are the same as for ShowWithEffect(),
- please see their description there.
+ @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.9.0
+ @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 bool HideWithEffect(wxShowEffect effect,
- unsigned int timeout = 0);
+ void Centre(int direction = wxBOTH);
/**
- 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.
+ Centres the window on its parent. This is a more readable synonym for Centre().
- By "intelligently" the following is meant: by default, all windows use their
- own @ref GetClassDefaultAttributes() default attributes.
- However if some of the parents attributes are explicitly (that is, using
- SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
- attribute hadn't been explicitly set for this window itself, then this
- window takes the same value as used by the parent.
- In addition, if the window overrides ShouldInheritColours() to return @false,
- the colours will not be changed no matter what and only the font might.
+ @param direction
+ Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
+ or wxBOTH.
- 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();
+ @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);
/**
- Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
- to the dialog via validators.
+ 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.
+
+ @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()
*/
- virtual void InitDialog();
+ void GetPosition(int* x, int* y) const;
/**
- Resets the cached best size value so it will be recalculated the next time it
- is needed.
+ 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 GetScreenPosition()
*/
- void InvalidateBestSize();
+ wxPoint GetPosition() const;
/**
- 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.
+ Returns the position and size of the window as a wxRect object.
- @see wxBufferedDC
+ @see GetScreenRect()
*/
- virtual bool IsDoubleBuffered() const;
+ wxRect GetRect() const;
/**
- Returns @true if the window is enabled, i.e. if it accepts user input,
- @false otherwise.
+ Returns the window position in screen coordinates, whether the window is a
+ child window or a top level one.
- 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()
+ @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 Enable()
+ @see GetPosition()
*/
- bool IsEnabled() const;
-
- //@{
- /**
- 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.
- */
- virtual bool IsRetained() const;
-
- /**
- Return whether a scrollbar is always shown.
-
- @param orient
- Orientation to check, either wxHORIZONTAL or wxVERTICAL.
-
- @see AlwaysShowScrollbars()
- */
- virtual bool IsScrollbarAlwaysShown(int orient) const;
-
- /**
- Returns @true if the window is shown, @false if it has been hidden.
-
- @see IsShownOnScreen()
- */
- virtual bool IsShown() 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()
- */
- virtual bool IsShownOnScreen() 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.
- */
- bool IsThisEnabled() 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).
- */
- virtual bool IsTopLevel() 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
- */
- virtual bool Layout();
+ void GetScreenPosition(int* x, int* y) const;
/**
- Lowers the window to the bottom of the window hierarchy (Z-order).
-
- @remarks
- This function only works for wxTopLevelWindow-derived classes.
+ Returns the window position in screen coordinates, whether the window is a
+ child window or a top level one.
- @see Raise()
+ @see GetPosition()
*/
- virtual void Lower();
+ wxPoint GetScreenPosition() const;
/**
- Disables all other windows in the application so that
- the user can only interact with this window.
+ Returns the position and size of the window on the screen as a wxRect object.
- @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 GetRect()
*/
- virtual void MakeModal(bool modal = true);
+ wxRect GetScreenRect() const;
/**
Moves the window to the given position.
*/
void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
+ //@}
+
+
/**
- Moves this window in the tab navigation order after the specified @e win.
- This means that when the user presses @c TAB key on that other window,
- the focus switches to this window.
+ @name Coordinate conversion
+ */
+ //@{
- Default tab order is the same as creation order, this function and
- MoveBeforeInTabOrder() allow to change
- it after creating all the windows.
+ /**
+ Converts to screen coordinates from coordinates relative to this window.
- @param win
- A sibling of this window which should precede it in tab order,
- must not be @NULL
+ @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.
+
+ @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
*/
- void MoveAfterInTabOrder(wxWindow* win);
+ void ClientToScreen(int* x, int* y) const;
/**
- Same as MoveAfterInTabOrder() except that it inserts this window just
- before @a win instead of putting it right after it.
+ Converts to screen coordinates from coordinates relative to this window.
+
+ @param pt
+ The client position for the second form of the function.
*/
- void MoveBeforeInTabOrder(wxWindow* win);
+ wxPoint ClientToScreen(const wxPoint& pt) const;
/**
- Performs a keyboard navigation action starting from this window.
- This method is equivalent to calling NavigateIn() method on the
- parent window.
+ Converts a point or size from dialog units to pixels.
- @param flags
- A combination of wxNavigationKeyEvent::IsForward and
- wxNavigationKeyEvent::WinChange.
+ 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 focus was moved to another window or @false
- if nothing changed.
+ @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 You may wish to call this from a text control custom keypress
- handler to do the default navigation behaviour for the
- tab key, since the standard default behaviour for a
- multiline text control with the wxTE_PROCESS_TAB style
- is to insert a tab and not navigate to the next
- control. See also wxNavigationKeyEvent and
- HandleAsNavigationKey.
+ @see ConvertPixelsToDialog()
*/
- bool Navigate(int flags = IsForward);
+ wxPoint ConvertDialogToPixels(const wxPoint& pt);
/**
- Performs a keyboard navigation action inside this window.
- See Navigate() for more information.
+ @overload
*/
- bool NavigateIn(int flags = IsForward);
+ wxSize ConvertDialogToPixels(const wxSize& sz);
/**
- 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().
+ Converts a point or size from pixels to dialog units.
- See @ref overview_windowids for more information.
+ 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 count
- The number of sequential IDs to reserve.
+ @remarks Dialog units are used for maintaining a dialog's proportions
+ even if the font changes.
- @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 ConvertDialogToPixels()
+ */
+ wxPoint ConvertPixelsToDialog(const wxPoint& pt);
- @see UnreserveControlId(), wxIdManager,
- @ref overview_windowids
+ /**
+ @overload
*/
- static wxWindowID NewControlId(int count = 1);
+ wxSize ConvertPixelsToDialog(const wxSize& sz);
/**
- 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.
+ Converts from screen to client window coordinates.
- 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.
+ @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.
*/
- virtual void OnInternalIdle();
+ void ScreenToClient(int* x, int* y) const;
/**
- Same as #ScrollLines (-1).
+ Converts from screen to client window coordinates.
+
+ @param pt
+ The screen position.
*/
- bool LineUp();
+ wxPoint ScreenToClient(const wxPoint& pt) const;
+
+ //@}
+
/**
- Same as #ScrollLines (1).
+ @name Drawing-related functions
*/
- bool LineDown();
+ //@{
/**
- Same as #ScrollPages (-1).
+ Clears the window by filling it with the current background colour. Does not
+ cause an erase background event to be generated.
*/
- bool PageUp();
+ virtual void ClearBackground();
/**
- Same as #ScrollPages (1).
- */
- bool PageDown();
+ Freezes the window or, in other words, prevents any updates from taking
+ place on screen, the window is not redrawn at all.
+ 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.
- /**
- Removes and returns the top-most event handler on the event handler stack.
+ If the window has any children, they are recursively frozen too.
- @param deleteHandler
- If this is @true, the handler will be deleted after it is removed.
- The default value is @false.
+ 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 SetEventHandler(), GetEventHandler(),
- PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
+ @see wxWindowUpdateLocker, Thaw(), IsFrozen()
*/
- wxEvtHandler* PopEventHandler(bool deleteHandler = false);
+ void Freeze();
- //@{
/**
- Pops up the given menu at the specified coordinates, relative to this
- window, and returns control when the user has dismissed the menu.
+ Reenables window updating after a previous call to Freeze().
- 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.
+ To really thaw the control, it must be called exactly the same number
+ of times as Freeze().
- @a menu is the menu to pop up.
+ If the window has any children, they are recursively thawn too.
- 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).
+ @see wxWindowUpdateLocker, Freeze(), IsFrozen()
+ */
+ void Thaw();
- @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.
+ /**
+ Returns @true if the window is currently frozen by a call to Freeze().
- @see wxMenu
+ @see Freeze(), Thaw()
*/
- bool PopupMenu(wxMenu* menu,
- const wxPoint& pos = wxDefaultPosition);
- bool PopupMenu(wxMenu* menu, int x, int y);
- //@}
+ bool IsFrozen() const;
/**
- Posts a size event to the window.
+ Returns the background colour of the window.
- This is the same as SendSizeEvent() with @c wxSEND_EVENT_POST argument.
- */
- void PostSizeEvent();
+ @see SetBackgroundColour(), SetForegroundColour(), GetForegroundColour()
+ */
+ wxColour GetBackgroundColour() const;
/**
- Posts a size event to the parent of this window.
+ Returns the background style of the window.
+ The background style can be one of the wxBackgroundStyle.
- This is the same as SendSizeEventToParent() with @c wxSEND_EVENT_POST
- argument.
- */
- void PostSizeEventToParent();
+ @see SetBackgroundColour(), GetForegroundColour(),
+ SetBackgroundStyle(), SetTransparent()
+ */
+ virtual wxBackgroundStyle GetBackgroundStyle() const;
+ /**
+ Returns the character height for this window.
+ */
+ virtual int GetCharHeight() const;
/**
- Pushes this event handler onto the event stack for the window.
+ Returns the average character width for this window.
+ */
+ virtual int GetCharWidth() const;
- @param handler
- Specifies the handler to be pushed.
+ /**
+ Currently this is the same as calling
+ wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()).
- @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.
+ 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.
- @see SetEventHandler(), GetEventHandler(),
- PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
+ 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.
*/
- void PushEventHandler(wxEvtHandler* handler);
+ virtual wxVisualAttributes GetDefaultAttributes() const;
/**
- Raises the window to the top of the window hierarchy (Z-order).
+ Returns the font for this window.
- @remarks
- This function only works for wxTopLevelWindow-derived classes.
+ @see SetFont()
+ */
+ wxFont GetFont() const;
- @see Lower()
+ /**
+ Returns the foreground colour of the window.
+
+ @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 SetForegroundColour(), SetBackgroundColour(),
+ GetBackgroundColour()
*/
- virtual void Raise();
+ wxColour GetForegroundColour() const;
+
+ /**
+ 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.
+
+ @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).
+ */
+ virtual void GetTextExtent(const wxString& string, int* w, int* h,
+ int* descent = NULL,
+ int* externalLeading = NULL,
+ const wxFont* font = NULL) const;
+
+ /**
+ 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;
+
+ /**
+ Returns the region specifying which parts of the window have been damaged.
+ Should only be called within an wxPaintEvent handler.
+
+ @see wxRegion, wxRegionIterator
+ */
+ const wxRegion& GetUpdateRegion() const;
+
+ /**
+ Returns @true if this window background is transparent (as, for example,
+ for wxStaticText) and should show the parent window background.
+
+ 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();
/**
Causes this window, and all of its children recursively (except under wxGTK1
void RefreshRect(const wxRect& rect, bool eraseBackground = true);
/**
- Registers a system wide hotkey. Every time the user presses the hotkey
- registered here, this window will receive a hotkey event.
+ 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.
- 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.
+ 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();
- @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.
+ /**
+ Sets the background colour of the window.
+ Please see InheritAttributes() for explanation of the difference between
+ this method and SetOwnBackgroundColour().
- @return @true if the hotkey was registered successfully. @false if some
- other application already registered a hotkey with this
- modifier/virtualKeyCode combination.
+ @param colour
+ The colour to be used as the background colour, pass
+ wxNullColour to reset to the default colour.
- @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.
+ @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 UnregisterHotKey()
+ @see GetBackgroundColour(), SetForegroundColour(),
+ GetForegroundColour(), ClearBackground(),
+ Refresh(), wxEraseEvent
*/
- virtual bool RegisterHotKey(int hotkeyId, int modifiers,
- int virtualKeyCode);
+ virtual bool SetBackgroundColour(const wxColour& colour);
/**
- Releases mouse input captured with CaptureMouse().
+ Sets the background style of the window. see GetBackgroundStyle() for
+ the description of the possible style values.
- @see CaptureMouse(), HasCapture(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ @see SetBackgroundColour(), GetForegroundColour(),
+ SetTransparent()
*/
- void ReleaseMouse();
+ virtual bool SetBackgroundStyle(wxBackgroundStyle style);
/**
- Removes a child window.
+ 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.
- 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.
+ 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 child
- Child window to remove.
+ @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 void RemoveChild(wxWindow* child);
+ virtual bool SetFont(const wxFont& font);
/**
- Find the given @a handler in the windows event handler chain and remove
- (but not delete) it from it.
+ Sets the foreground colour of the window.
+ Please see InheritAttributes() for explanation of the difference between
+ this method and SetOwnForegroundColour().
- @param handler
- The event handler to remove, must be non-@NULL and
- must be present in this windows event handlers chain
+ @param colour
+ The colour to be used as the foreground colour, pass
+ wxNullColour to reset to the default colour.
- @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).
+ @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 PushEventHandler(), PopEventHandler()
+ @see GetForegroundColour(), SetBackgroundColour(),
+ GetBackgroundColour(), ShouldInheritColours()
*/
- bool RemoveEventHandler(wxEvtHandler* handler);
+ virtual bool SetForegroundColour(const wxColour& colour);
/**
- 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.
+ Sets the background colour of the window but prevents it from being inherited
+ by the children of this window.
- @param newParent
- New parent.
+ @see SetBackgroundColour(), InheritAttributes()
*/
- virtual bool Reparent(wxWindow* newParent);
+ void SetOwnBackgroundColour(const wxColour& colour);
/**
- Converts from screen to client window coordinates.
+ Sets the font of the window but prevents it from being inherited by the
+ children of this 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.
+ @see SetFont(), InheritAttributes()
*/
- void ScreenToClient(int* x, int* y) const;
+ void SetOwnFont(const wxFont& font);
/**
- Converts from screen to client window coordinates.
+ Sets the foreground colour of the window but prevents it from being inherited
+ by the children of this window.
- @param pt
- The screen position.
+ @see SetForegroundColour(), InheritAttributes()
*/
- wxPoint ScreenToClient(const wxPoint& pt) const;
+ void SetOwnForegroundColour(const wxColour& colour);
/**
- Scrolls the window by the given number of lines down (if @a lines is
- positive) or up.
-
- @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
- wxTextCtrl under wxGTK (it also works for wxScrolled classes
- under all platforms).
-
- @see ScrollPages()
+ @deprecated use wxDC::SetPalette instead.
*/
- virtual bool ScrollLines(int lines);
+ void SetPalette(const wxPalette& pal);
/**
- Scrolls the window by the given number of pages down (if @a pages is
- positive) or up.
-
- @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.
+ 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 ScrollLines()
+ The base class version returns @false, but this method is overridden in
+ wxControl where it returns @true.
*/
- virtual bool ScrollPages(int pages);
+ virtual bool ShouldInheritColours() const;
/**
- Physically scrolls the pixels in the window and move child windows accordingly.
+ 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.
- @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)
+ 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 void SetThemeEnabled(bool enable);
- @remarks Note that you can often use wxScrolled instead of using this
- function directly.
+ /**
+ 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.
*/
- virtual void ScrollWindow(int dx, int dy,
- const wxRect* rect = NULL);
+ virtual bool CanSetTransparent();
/**
- This function sends a dummy @ref wxSizeEvent "size event" to
- the window allowing it to re-layout its children positions.
+ 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().
- 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.
+ 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.
+ */
+ virtual bool SetTransparent(wxByte alpha);
- 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.
+
+ /**
+ @name Event-handling functions
*/
- virtual void SendSizeEvent(int flags = 0);
+ //@{
/**
- Safe wrapper for GetParent()->SendSizeEvent().
+ Returns the event handler for this window.
+ By default, the window is its own event handler.
- 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 SetEventHandler(), PushEventHandler(),
+ PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
+ */
+ wxEvtHandler* GetEventHandler() const;
- @see PostSizeEventToParent()
+ /**
+ 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.
- @param flags
- See description of this parameter in SendSizeEvent() documentation.
- */
- void SendSizeEventToParent(int flags = 0);
+ @return Returns @true if the key pressed was for navigation and was
+ handled, @false otherwise.
- /**
- Sets the accelerator table for this window. See wxAcceleratorTable.
+ @see Navigate()
*/
- virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
+ bool HandleAsNavigationKey(const wxKeyEvent& event);
/**
- 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.
+ Shorthand for:
+ @code
+ GetEventHandler()->SafelyProcessEvent(event);
+ @endcode
*/
- void SetAccessible(wxAccessible* accessible);
+ bool HandleWindowEvent(wxEvent& event) const;
/**
- Determines whether the Layout() function will be called automatically
- when the window is resized. Please note that this only happens for the
- windows usually used to contain children, namely wxPanel and wxTopLevelWindow
- (and the classes deriving from them).
-
- This method is called implicitly by SetSizer() but if you use SetConstraints()
- you should call it manually or otherwise the window layout won't be correctly
- updated when its size changes.
+ Removes and returns the top-most event handler on the event handler stack.
- @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).
+ @param deleteHandler
+ If this is @true, the handler will be deleted after it is removed.
+ The default value is @false.
- @see SetConstraints()
+ @see SetEventHandler(), GetEventHandler(),
+ PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
*/
- void SetAutoLayout(bool autoLayout);
+ wxEvtHandler* PopEventHandler(bool deleteHandler = false);
/**
- Sets the background colour of the window.
- Please see InheritAttributes() for explanation of the difference between
- this method and SetOwnBackgroundColour().
+ Pushes this event handler onto the event stack for the window.
- @param colour
- The colour to be used as the background colour, pass
- wxNullColour to reset to the default colour.
+ @param handler
+ Specifies the handler to be pushed.
- @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.
+ @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 GetBackgroundColour(), SetForegroundColour(),
- GetForegroundColour(), ClearBackground(),
- Refresh(), wxEraseEvent
+ @see SetEventHandler(), GetEventHandler(),
+ PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
*/
- virtual bool SetBackgroundColour(const wxColour& colour);
+ void PushEventHandler(wxEvtHandler* handler);
/**
- Sets the background style of the window. see GetBackgroundStyle() for
- the description of the possible style values.
+ Find the given @a handler in the windows event handler chain and remove
+ (but not delete) it from it.
- @see SetBackgroundColour(), GetForegroundColour(),
- SetTransparent()
+ @param handler
+ The event handler to remove, must be non-@NULL and
+ must be present in this windows event handlers chain
+
+ @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 SetBackgroundStyle(wxBackgroundStyle style);
+ bool RemoveEventHandler(wxEvtHandler* handler);
/**
- This method is only implemented by ports which have support for
- native TAB traversal (such as GTK+ 2.0).
+ Sets the event handler for this window.
- 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().
+ @param handler
+ Specifies the handler to be set.
- @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren
+ @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
*/
- virtual void SetCanFocus(bool canFocus);
+ void SetEventHandler(wxEvtHandler* handler);
+
+ //@}
+
/**
- Sets the caret() associated with the window.
+ @name Window styles
*/
- void SetCaret(wxCaret* caret);
-
//@{
+
/**
- 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.
- */
- virtual void SetClientSize(int width, int height);
- virtual void SetClientSize(const wxSize& size);
- //@}
-
- /**
- 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.
-
- @param constraints
- The constraints to set. Pass @NULL to disassociate and delete the window's
- constraints.
-
- @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.
+ Returns the extra style bits for the window.
*/
- void SetConstraints(wxLayoutConstraints* constraints);
+ long GetExtraStyle() 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.
+ Gets the window style that was passed to the constructor or Create()
+ method. GetWindowStyle() is another name for the same function.
*/
- void SetContainingSizer(wxSizer* sizer);
+ virtual long GetWindowStyleFlag() 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.
-
- @param cursor
- Specifies the cursor that the window should normally display.
-
- @see ::wxSetCursor, wxCursor
+ See GetWindowStyleFlag() for more info.
*/
- virtual bool SetCursor(const wxCursor& cursor);
+ long GetWindowStyle() const;
/**
- Associates a drop target with this window.
- If the window already has a drop target, it is deleted.
+ Returns @true if the window has the given @a exFlag bit set in its
+ extra styles.
- @see GetDropTarget(), @ref overview_dnd
+ @see SetExtraStyle()
*/
- virtual void SetDropTarget(wxDropTarget* target);
+ bool HasExtraStyle(int exFlag) const;
/**
- Sets the event handler for this window.
-
- @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
+ Returns @true if the window has the given @a flag bit set.
*/
- void SetEventHandler(wxEvtHandler* handler);
+ bool HasFlag(int flag) const;
/**
Sets the extra style bits for the window.
virtual void SetExtraStyle(long exStyle);
/**
- This sets the window to receive keyboard input.
-
- @see HasFocus(), wxFocusEvent, wxPanel::SetFocus,
- wxPanel::SetFocusIgnoringChildren
- */
- virtual void SetFocus();
+ 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.
- /**
- 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).
+ See @ref overview_windowstyles "Window styles" for more information about flags.
- By default this method simply calls SetFocus() but
- can be overridden to do something in addition to this in the derived classes.
+ @see GetWindowStyleFlag()
*/
- virtual void SetFocusFromKbd();
+ virtual void SetWindowStyleFlag(long style);
/**
- 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().
+ See SetWindowStyleFlag() for more info.
+ */
+ void SetWindowStyle(long style);
- @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()
+ /**
+ @name Tab order
*/
- virtual bool SetFont(const wxFont& font);
+ //@{
/**
- Sets the foreground colour of the window.
- Please see InheritAttributes() for explanation of the difference between
- this method and SetOwnForegroundColour().
-
- @param colour
- The colour to be used as the foreground colour, pass
- wxNullColour to reset to the default colour.
+ Moves this window in the tab navigation order after the specified @e win.
+ This means that when the user presses @c TAB key on that other window,
+ the focus switches to this window.
- @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.
+ Default tab order is the same as creation order, this function and
+ MoveBeforeInTabOrder() allow to change
+ it after creating all the windows.
- @see GetForegroundColour(), SetBackgroundColour(),
- GetBackgroundColour(), ShouldInheritColours()
+ @param win
+ A sibling of this window which should precede it in tab order,
+ must not be @NULL
*/
- virtual bool SetForegroundColour(const wxColour& colour);
+ void MoveAfterInTabOrder(wxWindow* win);
/**
- Sets the help text to be used as context-sensitive help for this window.
- Note that the text is actually stored by the current wxHelpProvider
- implementation, and not in the window object itself.
-
- @see GetHelpText(), wxHelpProvider::AddHelp()
+ Same as MoveAfterInTabOrder() except that it inserts this window just
+ before @a win instead of putting it right after it.
*/
- void SetHelpText(const wxString& helpText);
+ void MoveBeforeInTabOrder(wxWindow* win);
/**
- Sets the identifier of the window.
+ Performs a keyboard navigation action starting from this window.
+ This method is equivalent to calling NavigateIn() method on the
+ parent 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.
+ @param flags
+ A combination of wxNavigationKeyEvent::IsForward and
+ wxNavigationKeyEvent::WinChange.
- @see GetId(), @ref overview_windowids
+ @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
+ handler to do the default navigation behaviour for the
+ tab key, since the standard default behaviour for a
+ multiline text control with the wxTE_PROCESS_TAB style
+ is to insert a tab and not navigate to the next
+ control. See also wxNavigationKeyEvent and
+ HandleAsNavigationKey.
*/
- void SetId(wxWindowID winid);
+ bool Navigate(int flags = IsForward);
/**
- A @e smart SetSize that will fill in default size components with the
- window's @e best size values.
+ Performs a keyboard navigation action inside this window.
+ See Navigate() for more information.
+ */
+ bool NavigateIn(int flags = IsForward);
- 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.
+ //@}
- Most controls will use this to set their initial size, and their min
- size to the passed in value (if any.)
- @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
- @ref overview_windowsizing
+
+ /**
+ @name Z-order
*/
- void SetInitialSize(const wxSize& size = wxDefaultSize);
+ //@{
/**
- Sets the window's label.
+ Lowers the window to the bottom of the window hierarchy (Z-order).
- @param label
- The window label.
+ @remarks
+ This function only works for wxTopLevelWindow-derived classes.
- @see GetLabel()
+ @see Raise()
*/
- virtual void SetLabel(const wxString& label);
+ virtual void Lower();
/**
- 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.
+ Raises the window to the top of the window hierarchy (Z-order).
- @see SetMaxSize()
+ @remarks
+ This function only works for wxTopLevelWindow-derived classes.
+
+ @see Lower()
*/
- virtual void SetMaxClientSize(const wxSize& size);
+ virtual void Raise();
- /**
- Sets the maximum size of the window, to indicate to the sizer layout mechanism
- that this is the maximum possible size.
+ //@}
- @see SetMaxClientSize()
- */
- virtual void SetMaxSize(const wxSize& size);
/**
- 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
- construction and before adding to its parent sizer.
+ @name Show/hide, enable/disable functions
+ */
+ //@{
- 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()
+ /**
+ Equivalent to calling wxWindow::Show(@false).
*/
- virtual void SetMinClientSize(const wxSize& size);
+ bool Hide();
/**
- 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.
+ This function hides a window, like Hide(), but using a special visual
+ effect if possible.
- 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.
+ The parameters of this function are the same as for ShowWithEffect(),
+ please see their description there.
- @see SetMinClientSize()
+ @since 2.9.0
*/
- virtual void SetMinSize(const wxSize& size);
-
+ virtual bool HideWithEffect(wxShowEffect effect,
+ unsigned int timeout = 0);
/**
- Sets the window's name.
+ Returns @true if the window is enabled, i.e. if it accepts user input,
+ @false otherwise.
- @param name
- A name to set for the window.
+ 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()
- @see GetName()
+ @see Enable()
*/
- virtual void SetName(const wxString& name);
+ bool IsEnabled() const;
/**
- Sets the background colour of the window but prevents it from being inherited
- by the children of this window.
+ 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;
- @see SetBackgroundColour(), InheritAttributes()
+ /**
+ @overload
*/
- void SetOwnBackgroundColour(const wxColour& colour);
+ bool IsExposed(wxPoint& pt) const;
/**
- Sets the font of the window but prevents it from being inherited by the
- children of this window.
+ @overload
+ */
+ bool IsExposed(int x, int y, int w, int h) const;
- @see SetFont(), InheritAttributes()
+ /**
+ @overload
*/
- void SetOwnFont(const wxFont& font);
+ bool IsExposed(wxRect& rect) const;
+ /**
+ Returns @true if the window is shown, @false if it has been hidden.
+
+ @see IsShownOnScreen()
+ */
+ virtual bool IsShown() const;
/**
- Sets the foreground colour of the window but prevents it from being inherited
- by the children of this window.
+ 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 SetForegroundColour(), InheritAttributes()
+ @see IsShown()
*/
- void SetOwnForegroundColour(const wxColour& colour);
+ virtual bool IsShownOnScreen() const;
/**
- @deprecated use wxDC::SetPalette instead.
+ Disables the window. Same as @ref Enable() Enable(@false).
+
+ @return Returns @true if the window has been disabled, @false if it had
+ been already disabled before the call to this function.
*/
- void SetPalette(const wxPalette& pal);
+ bool Disable();
/**
- Sets the position of one of the built-in scrollbars.
+ 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 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.
+ @param enable
+ If @true, enables the window for input. If @false, disables the window.
- @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.
+ @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 SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
- wxScrolled
+ @see IsEnabled(), Disable(), wxRadioBox::Enable
*/
- virtual void SetScrollPos(int orientation, int pos,
- bool refresh = true);
+ virtual bool Enable(bool enable = true);
/**
- Sets the scrollbar properties of a built-in scrollbar.
+ 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 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.
+ @param show
+ If @true displays the window. Otherwise, hides it.
- @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.
+ @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 @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
+ @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
*/
- virtual void SetScrollbar(int orientation, int position,
- int thumbSize, int range,
- bool refresh = true);
+ virtual bool Show(bool show = true);
/**
- Sets the size of the window in pixels.
+ This function shows a window, like Show(), but using a special visual
+ effect if possible.
- @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).
+ @param effect
+ The effect to use.
- @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 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.
- @see Move()
+ @note Currently this function is only implemented in wxMSW and does the
+ same thing as Show() in the other ports.
+
+ @since 2.9.0
+
+ @see HideWithEffect()
*/
- void SetSize(int x, int y, int width, int height,
- int sizeFlags = wxSIZE_AUTO);
+ virtual bool ShowWithEffect(wxShowEffect effect,
+ unsigned int timeout = 0);
+
+ //@}
+
+ // NOTE: static functions must have their own group or Doxygen will screw
+ // up the ordering of the member groups
+
+ /**
+ @name Static functions
+ */
//@{
+
/**
- Sets the size of the window in pixels.
- The size is specified using a wxRect, wxSize or by a couple of @c int objects.
+ Returns the default font and colours which are used by the control.
- @remarks This form must be used with non-default width and height values.
+ 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 Move()
+ 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 void SetSize(const wxRect& rect);
- virtual void SetSize(const wxSize& size);
- virtual void SetSize(int width, int height);
- //@}
+ static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
+
+ /**
+ Finds the window or control which currently has the keyboard focus.
+
+ @remarks Note that this is a static function, so it can be called without
+ needing a wxWindow pointer.
+
+ @see SetFocus(), HasFocus()
+ */
+ static wxWindow* FindFocus();
+
+ /**
+ Find the first window with the given @e id.
+
+ If @a parent is @NULL, the search will start from all top-level frames
+ and dialog boxes; if non-@NULL, the search will be limited to the given
+ window hierarchy.
+ The search is recursive in both cases.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
+
+ /**
+ Find a window by its label.
+
+ Depending on the type of window, the label may be a window title
+ or panel item label. If @a parent is @NULL, the search will start from all
+ top-level frames and dialog boxes; if non-@NULL, the search will be
+ limited to the given window hierarchy.
+ The search is recursive in both cases.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowByLabel(const wxString& label,
+ const wxWindow* parent = 0);
+
+ /**
+ Find a window by its name (as given in a window constructor or Create()
+ function call).
+
+ If @a parent is @NULL, the search will start from all top-level frames
+ and dialog boxes; if non-@NULL, the search will be limited to the given
+ window hierarchy.
+
+ The search is recursive in both cases. If no window with such name is found,
+ FindWindowByLabel() is called.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowByName(const wxString& name,
+ const wxWindow* parent = 0);
+
+ /**
+ Returns the currently captured window.
+
+ @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);
+
+ //@}
+
+
+ /**
+ @name Tooltip functions
+ */
+ //@{
+
+ /**
+ Get the associated tooltip or @NULL if none.
+ */
+ wxToolTip* GetToolTip() const;
+
+ /**
+ Attach a tooltip to the window.
+
+ 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 SetToolTip(const wxString& tip);
+
+ /**
+ @overload
+ */
+ void SetToolTip(wxToolTip* tip);
+
+ /**
+ Unset any existing tooltip.
+
+ @since 2.9.0
+
+ @see SetToolTip()
+ */
+ void UnsetToolTip();
+
+ //@}
+
+
+ /**
+ @name Popup/context menu functions
+ */
+ //@{
+
+ /**
+ 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.
+
+ 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.
+
+ The parameter @a menu is the menu to show.
+ The parameter @a pos (or the parameters @a x and @a y) is the
+ position at which to show the menu in client coordinates.
+
+ @return
+ The selected menu item id or @c wxID_NONE if none selected or an
+ error occurred.
+
+ @since 2.9.0
+ */
+ int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
+
+ /**
+ @overload
+ */
+ int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
+
+ /**
+ Pops up the given menu at the specified coordinates, relative to this
+ window, and returns control when the user has dismissed the menu.
+
+ 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.
+
+ @a menu is the menu to pop up.
+
+ The position where the menu will appear can be specified either as a
+ wxPoint @a pos or by two integers (@a x and @a y).
+
+ @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
+ ensure that the menu items are in the correct state.
+ 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
+ */
+ bool PopupMenu(wxMenu* menu,
+ const wxPoint& pos = wxDefaultPosition);
+
+ /**
+ @overload
+ */
+ bool PopupMenu(wxMenu* menu, int x, int y);
+
+ //@}
+
+
+
+ /**
+ @name Miscellaneous functions
+ */
+ //@{
+
+ /**
+ Directs all mouse input to this window.
+ Call ReleaseMouse() to release the capture.
+
+ Note that wxWidgets maintains the stack of windows having captured the mouse
+ and when the mouse is released the capture returns to the window which had had
+ captured it previously and it is only really released if there were no previous
+ window. In particular, this means that you must release the mouse as many times
+ as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
+
+ Any application which captures the mouse in the beginning of some operation
+ must handle wxMouseCaptureLostEvent and cancel this operation when it receives
+ the event. The event handler must not recapture mouse.
+
+ @see ReleaseMouse(), wxMouseCaptureLostEvent
+ */
+ void CaptureMouse();
+
+ /**
+ This function simply generates a wxCloseEvent whose handler usually tries
+ to close the window. It doesn't close the window itself, however.
+
+ @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
+ */
+ bool Close(bool force = false);
+
+ /**
+ Destroys the window safely. Use this function instead of the delete operator,
+ since different window classes can be destroyed differently. Frames and dialogs
+ are not destroyed immediately when this function is called -- they are added
+ to a list of windows to be deleted on idle time, when all the window's events
+ have been processed. This prevents problems with events being sent to
+ non-existent windows.
+
+ @return @true if the window has either been successfully deleted, or it
+ has been added to the list of windows pending real deletion.
+ */
+ virtual bool Destroy();
+
+ /**
+ Returns true if this window is in process of being destroyed.
+
+ The top level windows are not deleted immediately but are rather
+ scheduled for later destruction to give them time to process any
+ pending messages, see Destroy() description.
+
+ This function returns @true if this window, or one of its parent
+ windows, is scheduled for destruction and can be useful to avoid
+ manipulating it as it's usually useless to do something with a window
+ which is on the point of disappearing anyhow.
+ */
+ bool IsBeingDeleted() const;
+
+ /**
+ Does the window-specific updating after processing the update event.
+ This function is called by UpdateWindowUI() in order to check return
+ values in the wxUpdateUIEvent and act appropriately.
+ For example, to allow frame and dialog title updating, wxWidgets
+ implements this function as follows:
+
+ @code
+ // do the window-specific processing after processing the update event
+ void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
+ {
+ if ( event.GetSetEnabled() )
+ Enable(event.GetEnabled());
+
+ if ( event.GetSetText() )
+ {
+ if ( event.GetText() != GetTitle() )
+ SetTitle(event.GetText());
+ }
+ }
+ @endcode
+ */
+ virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
+
+ /**
+ Enables or disables eligibility for drop file events (OnDropFiles).
+
+ @param accept
+ If @true, the window is eligible for drop file events.
+ If @false, the window will not accept drop file events.
+
+ @remarks Windows only until version 2.8.9, available on all platforms
+ since 2.8.10. Cannot be used together with SetDropTarget() on
+ non-Windows platforms.
+
+ @see SetDropTarget()
+ */
+ virtual void DragAcceptFiles(bool accept);
+
+ /**
+ Gets the accelerator table for this window. See wxAcceleratorTable.
+ */
+ wxAcceleratorTable* GetAcceleratorTable();
+
+ /**
+ Returns the accessible object for this window, if any.
+ See also wxAccessible.
+ */
+ wxAccessible* GetAccessible();
+
+ /**
+ Returns the caret() associated with the window.
+ */
+ wxCaret* GetCaret() const;
+
+ /**
+ Returns a pointer to the window's layout constraints, or @NULL if there are none.
+ */
+ wxLayoutConstraints* GetConstraints() const;
+
+ /**
+ Return the cursor associated with this window.
+
+ @see SetCursor()
+ */
+ const wxCursor& GetCursor() const;
+
+ /**
+ Returns the associated drop target, which may be @NULL.
+
+ @see SetDropTarget(), @ref overview_dnd
+ */
+ virtual wxDropTarget* GetDropTarget() const;
+
+ /**
+ Returns the platform-specific handle of the physical window.
+ Cast it to an appropriate handle, such as @b HWND for Windows,
+ @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
+ */
+ virtual WXWidget GetHandle() const;
+
+ /**
+ Gets the help text to be used as context-sensitive help for this window.
+ Note that the text is actually stored by the current wxHelpProvider
+ implementation, and not in the window object itself.
+
+ @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
+ */
+ wxString GetHelpText() const;
+
+ /**
+ Gets the help text to be used as context-sensitive help for this window.
+ This method should be overridden if the help message depends on the position
+ inside the window, otherwise GetHelpText() can be used.
+
+ @param point
+ Coordinates of the mouse at the moment of help event emission.
+ @param origin
+ Help event origin, see also wxHelpEvent::GetOrigin.
+ */
+ virtual wxString GetHelpTextAtPoint(const wxPoint& point,
+ wxHelpEvent::Origin origin) 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
+ */
+ 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.
+ */
+ virtual wxString GetLabel() 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().
+
+ @see SetName()
+ */
+ virtual wxString GetName() const;
+
+ /**
+ Returns a pointer to the current validator for the window, or @NULL if
+ there is none.
+ */
+ virtual wxValidator* GetValidator();
+
+ /**
+ Returns the value previously passed to SetWindowVariant().
+ */
+ wxWindowVariant GetWindowVariant() const;
+
+ /**
+ Returns @true if this window has the current mouse capture.
+
+ @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
+ wxMouseCaptureChangedEvent
+ */
+ virtual bool HasCapture() const;
+
+ /**
+ This method should be overridden to return @true if this window has
+ multiple pages. All standard class with multiple pages such as
+ wxNotebook, wxListbook and wxTreebook already override it to return @true
+ and user-defined classes with similar behaviour should do it as well to
+ allow the library to handle such windows appropriately.
+ */
+ virtual bool HasMultiplePages() const;
+
+ /**
+ This function is (or should be, in case of custom controls) called during
+ window creation to intelligently set up the window visual attributes, that is
+ the font and the foreground and background colours.
+
+ By "intelligently" the following is meant: by default, all windows use their
+ own @ref GetClassDefaultAttributes() default attributes.
+ However if some of the parents attributes are explicitly (that is, using
+ SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
+ attribute hadn't been explicitly set for this window itself, then this
+ window takes the same value as used by the parent.
+ In addition, if the window overrides ShouldInheritColours() to return @false,
+ the colours will not be changed no matter what and only the font might.
+
+ This rather complicated logic is necessary in order to accommodate the
+ different usage scenarios. The most common one is when all default attributes
+ are used and in this case, nothing should be inherited as in modern GUIs
+ different controls use different fonts (and colours) than their siblings so
+ they can't inherit the same value from the parent. However it was also deemed
+ desirable to allow to simply change the attributes of all children at once by
+ just changing the font or colour of their common parent, hence in this case we
+ do inherit the parents attributes.
+ */
+ virtual void InheritAttributes();
+
+ /**
+ Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
+ to the dialog via validators.
+ */
+ virtual void InitDialog();
+
+ /**
+ 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 wxBufferedDC
+ */
+ virtual bool IsDoubleBuffered() const;
+
+ /**
+ Returns @true if the window is retained, @false otherwise.
+
+ @remarks Retained windows are only available on X platforms.
+ */
+ virtual bool IsRetained() 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.
+ */
+ bool IsThisEnabled() 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).
+ */
+ virtual bool IsTopLevel() 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
+ */
+ virtual bool Layout();
+
+ /**
+ 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.
+ */
+ virtual void MakeModal(bool modal = true);
+
+ /**
+ This virtual function is normally only used internally, but
+ sometimes an application may need it to implement functionality
+ that should not be disabled by an application defining an OnIdle
+ handler in a derived class.
+
+ This function may be used to do delayed painting, for example,
+ and most implementations call UpdateWindowUI()
+ in order to send update events to the window in idle time.
+ */
+ virtual void OnInternalIdle();
+
+ /**
+ Registers a system wide hotkey. Every time the user presses the hotkey
+ registered here, this window will receive a hotkey event.
+
+ 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 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.
- /**
- Use of this function for windows which are not toplevel windows
- (such as wxDialog or wxFrame) is discouraged.
- Please use SetMinSize() and SetMaxSize() instead.
+ @return @true if the hotkey was registered successfully. @false if some
+ other application already registered a hotkey with this
+ modifier/virtualKeyCode combination.
- @see wxTopLevelWindow::SetSizeHints
+ @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()
*/
- void SetSizeHints( const wxSize& minSize,
- const wxSize& maxSize=wxDefaultSize,
- const wxSize& incSize=wxDefaultSize);
+ virtual bool RegisterHotKey(int hotkeyId, int modifiers,
+ int virtualKeyCode);
/**
- Sets the window to have the given layout sizer.
- The window will then own the object, and will take care of its deletion.
- If an existing layout constraints object is already owned by the
- window, it will be deleted if the deleteOld parameter is @true.
-
- Note that this function will also call SetAutoLayout() implicitly with @true
- parameter if the @a sizer is non-@NULL and @false otherwise.
-
- @param sizer
- The sizer to set. Pass @NULL to disassociate and conditionally delete
- the window's sizer. See below.
- @param deleteOld
- If @true (the default), this will delete any pre-existing sizer.
- Pass @false if you wish to handle deleting the old sizer yourself.
+ Releases mouse input captured with CaptureMouse().
- @remarks SetSizer enables and disables Layout automatically.
+ @see CaptureMouse(), HasCapture(), ReleaseMouse(),
+ wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
*/
- void SetSizer(wxSizer* sizer, bool deleteOld = true);
+ void ReleaseMouse();
/**
- 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.
+ Sets the accelerator table for this window. See wxAcceleratorTable.
*/
- void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
+ virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
/**
- 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.
+ Sets the accessible for this window. Any existing accessible for this window
+ will be deleted first, if not identical to @e accessible.
+ See also wxAccessible.
*/
- virtual void SetThemeEnabled(bool enable);
+ void SetAccessible(wxAccessible* accessible);
- //@{
/**
- Attach a tooltip to the window.
+ 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).
- 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.
+ 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.
- 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.
+ @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 GetToolTip(), wxToolTip
+ @see SetConstraints()
*/
- void SetToolTip(const wxString& tip);
- void SetToolTip(wxToolTip* tip);
- //@}
+ void SetAutoLayout(bool autoLayout);
/**
- 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.
- */
- virtual void SetValidator(const wxValidator& validator);
+ 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.
- //@{
- /**
- Sets the virtual size of the window in pixels.
+ @param constraints
+ The constraints to set. Pass @NULL to disassociate and delete the window's
+ constraints.
+
+ @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.
*/
- void SetVirtualSize(int width, int height);
- void SetVirtualSize(const wxSize& size);
- //@}
+ void SetConstraints(wxLayoutConstraints* constraints);
- //@{
/**
- 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.
+ Sets the window's cursor. Notice that the window cursor also sets it for the
+ children of the window implicitly.
- See @ref overview_windowstyles "Window styles" for more information about flags.
+ The @a cursor may be @c wxNullCursor in which case the window cursor will
+ be reset back to default.
- @see GetWindowStyleFlag()
+ @param cursor
+ Specifies the cursor that the window should normally display.
+
+ @see ::wxSetCursor, wxCursor
*/
- virtual void SetWindowStyleFlag(long style);
- void SetWindowStyle(long style);
- //@}
+ virtual bool SetCursor(const wxCursor& cursor);
/**
- 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.
+ Associates a drop target with this window.
+ If the window already has a drop target, it is deleted.
- By default the controls use the normal size, of course, but this function can
- be used to change this.
+ @see GetDropTarget(), @ref overview_dnd
*/
- void SetWindowVariant(wxWindowVariant variant);
+ virtual void SetDropTarget(wxDropTarget* target);
/**
- 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.
+ 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.
- The base class version returns @false, but this method is overridden in
- wxControl where it returns @true.
+ @see GetHelpText(), wxHelpProvider::AddHelp()
*/
- virtual bool ShouldInheritColours() const;
+ void SetHelpText(const wxString& helpText);
/**
- 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.
+ Sets the identifier of the window.
- @return @true if the window has been shown or hidden or @false if nothing
- was done because it already was in the requested state.
+ @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 IsShown(), Hide(), wxRadioBox::Show, wxShowEvent.
+ @see GetId(), @ref overview_windowids
*/
- virtual bool Show(bool show = true);
+ void SetId(wxWindowID winid);
/**
- This function shows a window, like Show(), but using a special visual
- effect if possible.
+ Sets the window's label.
- @param effect
- The effect to use.
+ @param label
+ The window label.
- @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.
+ @see GetLabel()
+ */
+ virtual void SetLabel(const wxString& label);
- @note Currently this function is only implemented in wxMSW and does the
- same thing as Show() in the other ports.
+ /**
+ Sets the window's name.
- @since 2.9.0
+ @param name
+ A name to set for the window.
- @see HideWithEffect()
+ @see GetName()
*/
- virtual bool ShowWithEffect(wxShowEffect effect,
- unsigned int timeout = 0);
+ virtual void SetName(const wxString& name);
/**
- 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().
+ 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);
- If the window has any children, they are recursively thawn too.
+ /**
+ 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 wxWindowUpdateLocker, Freeze(), IsFrozen()
+ By default the controls use the normal size, of course, but this function can
+ be used to change this.
*/
- void Thaw();
+ void SetWindowVariant(wxWindowVariant variant);
/**
Turns the given @a flag on if it's currently turned off and vice versa.
*/
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
*/
virtual void WarpPointer(int x, int y);
+ //@}
protected:
projects / wxWidgets.git / commitdiff
