/**
- @name Scrolling and scrollbars
+ @name Scrolling and scrollbars functions
*/
//@{
/**
- @name Sizing
+ @name Sizing functions
See also the protected functions DoGetBestSize() and SetInitialBestSize().
*/
*/
virtual wxSize GetWindowBorderSize() const;
- /**
- Return the sizer that this window is a member of, if any, otherwise @NULL.
- */
- wxSizer* GetContainingSizer() const;
-
- /**
- Return the sizer associated with the window by a previous call to
- SetSizer() or @NULL.
- */
- wxSizer* GetSizer() const;
-
/**
Resets the cached best size value so it will be recalculated the next time it
is needed.
const wxSize& maxSize=wxDefaultSize,
const wxSize& incSize=wxDefaultSize);
- /**
- Sets the window to have the given layout sizer.
- The window will then own the object, and will take care of its deletion.
- If an existing layout constraints object is already owned by the
- window, it will be deleted if the deleteOld parameter is @true.
-
- Note that this function will also call SetAutoLayout() implicitly with @true
- parameter if the @a sizer is non-@NULL and @false otherwise.
-
- @param sizer
- The sizer to set. Pass @NULL to disassociate and conditionally delete
- the window's sizer. See below.
- @param deleteOld
- If @true (the default), this will delete any pre-existing sizer.
- Pass @false if you wish to handle deleting the old sizer yourself.
-
- @remarks SetSizer enables and disables Layout automatically.
- */
- void SetSizer(wxSizer* sizer, bool deleteOld = true);
-
- /**
- This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
- window size to the size needed to accommodate all sizer elements and sets the
- size hints which, if this window is a top level one, prevent the user from
- resizing it to be less than this minimial size.
- */
- void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
-
/**
Sets the virtual size of the window in pixels.
*/
/**
- @name Positioning
+ @name Positioning functions
*/
//@{
/**
- @name Coordinate conversion
+ @name Coordinate conversion functions
*/
//@{
/**
- @name Window styles
+ @name Window styles functions
*/
//@{
*/
void SetWindowStyle(long style);
+ /**
+ Turns the given @a flag on if it's currently turned off and vice versa.
+ This function cannot be used if the value of the flag is 0 (which is often
+ the case for default flags).
+
+ Also, please notice that not all styles can be changed after the control
+ creation.
+
+ @return Returns @true if the style was turned on by this function, @false
+ if it was switched off.
+
+ @see SetWindowStyleFlag(), HasFlag()
+ */
+ bool ToggleWindowStyle(int flag);
+
//@}
/**
- @name Tab order
+ @name Tab order functions
*/
//@{
/**
- @name Z-order
+ @name Z order functions
*/
//@{
/**
- @name Show/hide, enable/disable functions
+ @name Window status functions
*/
//@{
//@}
- // NOTE: static functions must have their own group or Doxygen will screw
- // up the ordering of the member groups
-
/**
- @name Static functions
+ @name Context-sensitive help functions
*/
//@{
/**
- Returns the default font and colours which are used by the control.
-
- This is useful if you want to use the same font or colour in your own control
- as in a standard control -- which is a much better idea than hard coding specific
- colours or fonts which might look completely out of place on the users
- system, especially if it uses themes.
-
- The @a variant parameter is only relevant under Mac currently and is
- ignore under other platforms. Under Mac, it will change the size of the
- returned font. See SetWindowVariant() for more about this.
-
- This static method is "overridden" in many derived classes and so calling,
- for example, wxButton::GetClassDefaultAttributes() will typically
- return the values appropriate for a button which will be normally different
- from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
-
- The @c wxVisualAttributes structure has at least the fields
- @c font, @c colFg and @c colBg. All of them may be invalid
- if it was not possible to determine the default control appearance or,
- especially for the background colour, if the field doesn't make sense as is
- the case for @c colBg for the controls with themed background.
-
- @see InheritAttributes()
- */
- static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
-
- /**
- Finds the window or control which currently has the keyboard focus.
-
- @remarks Note that this is a static function, so it can be called without
- needing a wxWindow pointer.
-
- @see SetFocus(), HasFocus()
- */
- static wxWindow* FindFocus();
-
- /**
- Find the first window with the given @e id.
-
- If @a parent is @NULL, the search will start from all top-level frames
- and dialog boxes; if non-@NULL, the search will be limited to the given
- window hierarchy.
- The search is recursive in both cases.
-
- @see FindWindow()
- */
- static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
-
- /**
- Find a window by its label.
-
- Depending on the type of window, the label may be a window title
- or panel item label. If @a parent is @NULL, the search will start from all
- top-level frames and dialog boxes; if non-@NULL, the search will be
- limited to the given window hierarchy.
- The search is recursive in both cases.
-
- @see FindWindow()
- */
- static wxWindow* FindWindowByLabel(const wxString& label,
- const wxWindow* parent = 0);
-
- /**
- Find a window by its name (as given in a window constructor or Create()
- function call).
-
- If @a parent is @NULL, the search will start from all top-level frames
- and dialog boxes; if non-@NULL, the search will be limited to the given
- window hierarchy.
-
- The search is recursive in both cases. If no window with such name is found,
- FindWindowByLabel() is called.
-
- @see FindWindow()
- */
- static wxWindow* FindWindowByName(const wxString& name,
- const wxWindow* parent = 0);
-
- /**
- Returns the currently captured window.
+ Gets the help text to be used as context-sensitive help for this window.
+ Note that the text is actually stored by the current wxHelpProvider
+ implementation, and not in the window object itself.
- @see HasCapture(), CaptureMouse(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
*/
- static wxWindow* GetCapture();
+ wxString GetHelpText() const;
/**
- Create a new ID or range of IDs that are not currently in use.
- The IDs will be reserved until assigned to a wxWindow ID
- or unreserved with UnreserveControlId().
-
- See @ref overview_windowids for more information.
-
- @param count
- The number of sequential IDs to reserve.
-
- @return Returns the ID or the first ID of the range, or wxID_NONE if the
- specified number of identifiers couldn't be allocated.
+ Sets the help text to be used as context-sensitive help for this window.
+ Note that the text is actually stored by the current wxHelpProvider
+ implementation, and not in the window object itself.
- @see UnreserveControlId(), wxIdManager,
- @ref overview_windowids
+ @see GetHelpText(), wxHelpProvider::AddHelp()
*/
- static wxWindowID NewControlId(int count = 1);
+ void SetHelpText(const wxString& helpText);
/**
- Unreserve an ID or range of IDs that was reserved by NewControlId().
- See @ref overview_windowids for more information.
-
- @param id
- The starting ID of the range of IDs to unreserve.
- @param count
- The number of sequential IDs to unreserve.
-
- @see NewControlId(), wxIdManager, @ref overview_windowids
- */
- static void UnreserveControlId(wxWindowID id, int count = 1);
-
- //@}
-
+ Gets the help text to be used as context-sensitive help for this window.
+ This method should be overridden if the help message depends on the position
+ inside the window, otherwise GetHelpText() can be used.
- /**
- @name Tooltip functions
+ @param point
+ Coordinates of the mouse at the moment of help event emission.
+ @param origin
+ Help event origin, see also wxHelpEvent::GetOrigin.
*/
- //@{
+ virtual wxString GetHelpTextAtPoint(const wxPoint& point,
+ wxHelpEvent::Origin origin) const;
/**
Get the associated tooltip or @NULL if none.
//@}
-
/**
- @name Miscellaneous functions
+ Validator functions
*/
//@{
/**
- Directs all mouse input to this window.
- Call ReleaseMouse() to release the capture.
+ Returns a pointer to the current validator for the window, or @NULL if
+ there is none.
+ */
+ virtual wxValidator* GetValidator();
- Note that wxWidgets maintains the stack of windows having captured the mouse
- and when the mouse is released the capture returns to the window which had had
- captured it previously and it is only really released if there were no previous
- window. In particular, this means that you must release the mouse as many times
- as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
+ /**
+ Deletes the current validator (if any) and sets the window validator, having
+ called wxValidator::Clone to create a new validator of this type.
+ */
+ virtual void SetValidator(const wxValidator& validator);
- Any application which captures the mouse in the beginning of some operation
- must handle wxMouseCaptureLostEvent and cancel this operation when it receives
- the event. The event handler must not recapture mouse.
+ /**
+ Transfers values from child controls to data areas specified by their
+ validators. Returns @false if a transfer failed.
- @see ReleaseMouse(), wxMouseCaptureLostEvent
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call TransferDataFromWindow() of all child windows.
+
+ @see TransferDataToWindow(), wxValidator, Validate()
*/
- void CaptureMouse();
+ virtual bool TransferDataFromWindow();
/**
- This function simply generates a wxCloseEvent whose handler usually tries
- to close the window. It doesn't close the window itself, however.
+ Transfers values to child controls from data areas specified by their
+ validators.
- @param force
- @false if the window's close handler should be able to veto the destruction
- of this window, @true if it cannot.
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call TransferDataToWindow() of all child windows.
- @remarks Close calls the close handler for the window, providing an
- opportunity for the window to choose whether to destroy
- the window. Usually it is only used with the top level
- windows (wxFrame and wxDialog classes) as the others
- are not supposed to have any special OnClose() logic.
- The close handler should check whether the window is being deleted
- forcibly, using wxCloseEvent::CanVeto, in which case it should
- destroy the window using wxWindow::Destroy.
- Note that calling Close does not guarantee that the window will
- be destroyed; but it provides a way to simulate a manual close
- of a window, which may or may not be implemented by destroying
- the window. The default implementation of wxDialog::OnCloseWindow
- does not necessarily delete the dialog, since it will simply
- simulate an wxID_CANCEL event which is handled by the appropriate
- button event handler and may do anything at all.
- To guarantee that the window will be destroyed, call
- wxWindow::Destroy instead
+ @return Returns @false if a transfer failed.
- @see @ref overview_windowdeletion "Window Deletion Overview",
- Destroy(), wxCloseEvent
+ @see TransferDataFromWindow(), wxValidator, Validate()
*/
- bool Close(bool force = false);
+ virtual bool TransferDataToWindow();
/**
- Destroys the window safely. Use this function instead of the delete operator,
- since different window classes can be destroyed differently. Frames and dialogs
- are not destroyed immediately when this function is called -- they are added
- to a list of windows to be deleted on idle time, when all the window's events
- have been processed. This prevents problems with events being sent to
- non-existent windows.
-
- @return @true if the window has either been successfully deleted, or it
- has been added to the list of windows pending real deletion.
- */
- virtual bool Destroy();
-
- /**
- Returns true if this window is in process of being destroyed.
-
- The top level windows are not deleted immediately but are rather
- scheduled for later destruction to give them time to process any
- pending messages, see Destroy() description.
-
- This function returns @true if this window, or one of its parent
- windows, is scheduled for destruction and can be useful to avoid
- manipulating it as it's usually useless to do something with a window
- which is on the point of disappearing anyhow.
- */
- bool IsBeingDeleted() const;
-
- /**
- Does the window-specific updating after processing the update event.
- This function is called by UpdateWindowUI() in order to check return
- values in the wxUpdateUIEvent and act appropriately.
- For example, to allow frame and dialog title updating, wxWidgets
- implements this function as follows:
-
- @code
- // do the window-specific processing after processing the update event
- void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
- {
- if ( event.GetSetEnabled() )
- Enable(event.GetEnabled());
-
- if ( event.GetSetText() )
- {
- if ( event.GetText() != GetTitle() )
- SetTitle(event.GetText());
- }
- }
- @endcode
- */
- virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
-
- /**
- Enables or disables eligibility for drop file events (OnDropFiles).
-
- @param accept
- If @true, the window is eligible for drop file events.
- If @false, the window will not accept drop file events.
-
- @remarks Windows only until version 2.8.9, available on all platforms
- since 2.8.10. Cannot be used together with SetDropTarget() on
- non-Windows platforms.
-
- @see SetDropTarget()
- */
- virtual void DragAcceptFiles(bool accept);
-
- /**
- Gets the accelerator table for this window. See wxAcceleratorTable.
- */
- wxAcceleratorTable* GetAcceleratorTable();
-
- /**
- Returns the accessible object for this window, if any.
- See also wxAccessible.
- */
- wxAccessible* GetAccessible();
-
- /**
- Returns the caret() associated with the window.
- */
- wxCaret* GetCaret() const;
-
- /**
- Returns a pointer to the window's layout constraints, or @NULL if there are none.
- */
- wxLayoutConstraints* GetConstraints() const;
-
- /**
- Return the cursor associated with this window.
-
- @see SetCursor()
- */
- const wxCursor& GetCursor() const;
-
- /**
- Returns the associated drop target, which may be @NULL.
+ Validates the current values of the child controls using their validators.
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call Validate() of all child windows.
- @see SetDropTarget(), @ref overview_dnd
- */
- virtual wxDropTarget* GetDropTarget() const;
+ @return Returns @false if any of the validations failed.
- /**
- Returns the platform-specific handle of the physical window.
- Cast it to an appropriate handle, such as @b HWND for Windows,
- @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
+ @see TransferDataFromWindow(), TransferDataToWindow(),
+ wxValidator
*/
- virtual WXWidget GetHandle() const;
+ virtual bool Validate();
- /**
- Gets the help text to be used as context-sensitive help for this window.
- Note that the text is actually stored by the current wxHelpProvider
- implementation, and not in the window object itself.
+ //@}
- @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
- */
- wxString GetHelpText() const;
/**
- Gets the help text to be used as context-sensitive help for this window.
- This method should be overridden if the help message depends on the position
- inside the window, otherwise GetHelpText() can be used.
-
- @param point
- Coordinates of the mouse at the moment of help event emission.
- @param origin
- Help event origin, see also wxHelpEvent::GetOrigin.
+ @name wxWindow properties functions
*/
- virtual wxString GetHelpTextAtPoint(const wxPoint& point,
- wxHelpEvent::Origin origin) const;
+ //@{
/**
Returns the identifier of the window.
*/
virtual wxString GetName() const;
- /**
- Returns a pointer to the current validator for the window, or @NULL if
- there is none.
- */
- virtual wxValidator* GetValidator();
-
/**
Returns the value previously passed to SetWindowVariant().
*/
wxWindowVariant GetWindowVariant() const;
/**
- Returns @true if this window has the current mouse capture.
+ Sets the identifier of the window.
- @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
- wxMouseCaptureChangedEvent
- */
- virtual bool HasCapture() const;
+ @remarks Each window has an integer identifier. If the application has
+ not provided one, an identifier will be generated.
+ Normally, the identifier should be provided on creation
+ and should not be modified subsequently.
- /**
- This method should be overridden to return @true if this window has
- multiple pages. All standard class with multiple pages such as
- wxNotebook, wxListbook and wxTreebook already override it to return @true
- and user-defined classes with similar behaviour should do it as well to
- allow the library to handle such windows appropriately.
+ @see GetId(), @ref overview_windowids
*/
- virtual bool HasMultiplePages() const;
+ void SetId(wxWindowID winid);
/**
- This function is (or should be, in case of custom controls) called during
- window creation to intelligently set up the window visual attributes, that is
- the font and the foreground and background colours.
+ Sets the window's label.
- By "intelligently" the following is meant: by default, all windows use their
- own @ref GetClassDefaultAttributes() default attributes.
- However if some of the parents attributes are explicitly (that is, using
- SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
- attribute hadn't been explicitly set for this window itself, then this
- window takes the same value as used by the parent.
- In addition, if the window overrides ShouldInheritColours() to return @false,
- the colours will not be changed no matter what and only the font might.
+ @param label
+ The window label.
- This rather complicated logic is necessary in order to accommodate the
- different usage scenarios. The most common one is when all default attributes
- are used and in this case, nothing should be inherited as in modern GUIs
- different controls use different fonts (and colours) than their siblings so
- they can't inherit the same value from the parent. However it was also deemed
- desirable to allow to simply change the attributes of all children at once by
- just changing the font or colour of their common parent, hence in this case we
- do inherit the parents attributes.
+ @see GetLabel()
*/
- virtual void InheritAttributes();
+ virtual void SetLabel(const wxString& label);
/**
- Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
- to the dialog via validators.
- */
- virtual void InitDialog();
+ Sets the window's name.
- /**
- Returns @true if the window contents is double-buffered by the system, i.e. if
- any drawing done on the window is really done on a temporary backing surface
- and transferred to the screen all at once later.
+ @param name
+ A name to set for the window.
- @see wxBufferedDC
+ @see GetName()
*/
- virtual bool IsDoubleBuffered() const;
+ virtual void SetName(const wxString& name);
/**
- Returns @true if the window is retained, @false otherwise.
+ This function can be called under all platforms but only does anything under
+ Mac OS X 10.3+ currently. Under this system, each of the standard control can
+ exist in several sizes which correspond to the elements of wxWindowVariant enum.
- @remarks Retained windows are only available on X platforms.
+ By default the controls use the normal size, of course, but this function can
+ be used to change this.
*/
- virtual bool IsRetained() const;
+ void SetWindowVariant(wxWindowVariant variant);
+
/**
- Returns @true if this window is intrinsically enabled, @false otherwise,
- i.e. if @ref Enable() Enable(@false) had been called. This method is
- mostly used for wxWidgets itself, user code should normally use
- IsEnabled() instead.
+ Gets the accelerator table for this window. See wxAcceleratorTable.
*/
- bool IsThisEnabled() const;
+ wxAcceleratorTable* GetAcceleratorTable();
/**
- Returns @true if the given window is a top-level one. Currently all frames and
- dialogs are considered to be top-level windows (even if they have a parent
- window).
+ Returns the accessible object for this window, if any.
+ See also wxAccessible.
*/
- virtual bool IsTopLevel() const;
+ wxAccessible* GetAccessible();
/**
- Invokes the constraint-based layout algorithm or the sizer-based algorithm
- for this window.
-
- This function does not get called automatically when the window is resized
- because lots of windows deriving from wxWindow does not need this functionality.
- If you want to have Layout() called automatically, you should derive
- from wxPanel (see wxPanel::Layout).
-
- @see @ref overview_windowsizing
+ Sets the accelerator table for this window. See wxAcceleratorTable.
*/
- virtual bool Layout();
+ virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
/**
- Disables all other windows in the application so that
- the user can only interact with this window.
-
- @param modal
- If @true, this call disables all other windows in the application so that
- the user can only interact with this window. If @false, the effect is
- reversed.
+ Sets the accessible for this window. Any existing accessible for this window
+ will be deleted first, if not identical to @e accessible.
+ See also wxAccessible.
*/
- virtual void MakeModal(bool modal = true);
+ void SetAccessible(wxAccessible* accessible);
- /**
- This virtual function is normally only used internally, but
- sometimes an application may need it to implement functionality
- that should not be disabled by an application defining an OnIdle
- handler in a derived class.
+ //@}
- This function may be used to do delayed painting, for example,
- and most implementations call UpdateWindowUI()
- in order to send update events to the window in idle time.
+
+ /**
+ @name Window deletion functions
*/
- virtual void OnInternalIdle();
+ //@{
/**
- Registers a system wide hotkey. Every time the user presses the hotkey
- registered here, this window will receive a hotkey event.
+ This function simply generates a wxCloseEvent whose handler usually tries
+ to close the window. It doesn't close the window itself, however.
- It will receive the event even if the application is in the background
- and does not have the input focus because the user is working with some
- other application.
+ @param force
+ @false if the window's close handler should be able to veto the destruction
+ of this window, @true if it cannot.
- @param hotkeyId
- Numeric identifier of the hotkey. For applications this must be between 0
- and 0xBFFF. If this function is called from a shared DLL, it must be a
- system wide unique identifier between 0xC000 and 0xFFFF.
- This is a MSW specific detail.
- @param modifiers
- A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
- or wxMOD_WIN specifying the modifier keys that have to be pressed along
- with the key.
- @param virtualKeyCode
- The virtual key code of the hotkey.
+ @remarks Close calls the close handler for the window, providing an
+ opportunity for the window to choose whether to destroy
+ the window. Usually it is only used with the top level
+ windows (wxFrame and wxDialog classes) as the others
+ are not supposed to have any special OnClose() logic.
+ The close handler should check whether the window is being deleted
+ forcibly, using wxCloseEvent::CanVeto, in which case it should
+ destroy the window using wxWindow::Destroy.
+ Note that calling Close does not guarantee that the window will
+ be destroyed; but it provides a way to simulate a manual close
+ of a window, which may or may not be implemented by destroying
+ the window. The default implementation of wxDialog::OnCloseWindow
+ does not necessarily delete the dialog, since it will simply
+ simulate an wxID_CANCEL event which is handled by the appropriate
+ button event handler and may do anything at all.
+ To guarantee that the window will be destroyed, call
+ wxWindow::Destroy instead
- @return @true if the hotkey was registered successfully. @false if some
- other application already registered a hotkey with this
- modifier/virtualKeyCode combination.
+ @see @ref overview_windowdeletion "Window Deletion Overview",
+ Destroy(), wxCloseEvent
+ */
+ bool Close(bool force = false);
- @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
- event. This function is currently only implemented
- under Windows. It is used in the Windows CE port for
- detecting hardware button presses.
+ /**
+ Destroys the window safely. Use this function instead of the delete operator,
+ since different window classes can be destroyed differently. Frames and dialogs
+ are not destroyed immediately when this function is called -- they are added
+ to a list of windows to be deleted on idle time, when all the window's events
+ have been processed. This prevents problems with events being sent to
+ non-existent windows.
- @see UnregisterHotKey()
+ @return @true if the window has either been successfully deleted, or it
+ has been added to the list of windows pending real deletion.
*/
- virtual bool RegisterHotKey(int hotkeyId, int modifiers,
- int virtualKeyCode);
+ virtual bool Destroy();
/**
- Releases mouse input captured with CaptureMouse().
+ Returns true if this window is in process of being destroyed.
- @see CaptureMouse(), HasCapture(), ReleaseMouse(),
- wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ The top level windows are not deleted immediately but are rather
+ scheduled for later destruction to give them time to process any
+ pending messages, see Destroy() description.
+
+ This function returns @true if this window, or one of its parent
+ windows, is scheduled for destruction and can be useful to avoid
+ manipulating it as it's usually useless to do something with a window
+ which is on the point of disappearing anyhow.
+ */
+ bool IsBeingDeleted() const;
+
+ //@}
+
+
+
+ /**
+ @name Drag and drop functions
*/
- void ReleaseMouse();
+ //@{
/**
- Sets the accelerator table for this window. See wxAcceleratorTable.
+ Returns the associated drop target, which may be @NULL.
+
+ @see SetDropTarget(), @ref overview_dnd
*/
- virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
+ virtual wxDropTarget* GetDropTarget() const;
/**
- Sets the accessible for this window. Any existing accessible for this window
- will be deleted first, if not identical to @e accessible.
- See also wxAccessible.
+ Associates a drop target with this window.
+ If the window already has a drop target, it is deleted.
+
+ @see GetDropTarget(), @ref overview_dnd
*/
- void SetAccessible(wxAccessible* accessible);
+ virtual void SetDropTarget(wxDropTarget* target);
/**
- Determines whether the Layout() function will be called automatically
- when the window is resized. Please note that this only happens for the
- windows usually used to contain children, namely wxPanel and wxTopLevelWindow
- (and the classes deriving from them).
+ Enables or disables eligibility for drop file events (OnDropFiles).
- This method is called implicitly by SetSizer() but if you use SetConstraints()
- you should call it manually or otherwise the window layout won't be correctly
- updated when its size changes.
+ @param accept
+ If @true, the window is eligible for drop file events.
+ If @false, the window will not accept drop file events.
- @param autoLayout
- Set this to @true if you wish the Layout() function to be
- called automatically when the window is resized
- (really happens only if you derive from wxPanel or wxTopLevelWindow).
+ @remarks Windows only until version 2.8.9, available on all platforms
+ since 2.8.10. Cannot be used together with SetDropTarget() on
+ non-Windows platforms.
- @see SetConstraints()
+ @see SetDropTarget()
*/
- void SetAutoLayout(bool autoLayout);
+ virtual void DragAcceptFiles(bool accept);
+
+ //@}
+
/**
- Sets the caret() associated with the window.
+ @name Constraints, sizers and window layouting functions
*/
- void SetCaret(wxCaret* caret);
+ //@{
+
+ /**
+ Return the sizer that this window is a member of, if any, otherwise @NULL.
+ */
+ wxSizer* GetContainingSizer() const;
+
+ /**
+ Return the sizer associated with the window by a previous call to
+ SetSizer() or @NULL.
+ */
+ wxSizer* GetSizer() const;
+
+ /**
+ Sets the window to have the given layout sizer.
+ The window will then own the object, and will take care of its deletion.
+ If an existing layout constraints object is already owned by the
+ window, it will be deleted if the deleteOld parameter is @true.
+
+ Note that this function will also call SetAutoLayout() implicitly with @true
+ parameter if the @a sizer is non-@NULL and @false otherwise.
+
+ @param sizer
+ The sizer to set. Pass @NULL to disassociate and conditionally delete
+ the window's sizer. See below.
+ @param deleteOld
+ If @true (the default), this will delete any pre-existing sizer.
+ Pass @false if you wish to handle deleting the old sizer yourself.
+
+ @remarks SetSizer enables and disables Layout automatically.
+ */
+ void SetSizer(wxSizer* sizer, bool deleteOld = true);
+
+ /**
+ This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
+ window size to the size needed to accommodate all sizer elements and sets the
+ size hints which, if this window is a top level one, prevent the user from
+ resizing it to be less than this minimial size.
+ */
+ void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
+
+ /**
+ Returns a pointer to the window's layout constraints, or @NULL if there are none.
+ */
+ wxLayoutConstraints* GetConstraints() const;
/**
Sets the window to have the given layout constraints. The window
*/
void SetConstraints(wxLayoutConstraints* constraints);
+
+ /**
+ Invokes the constraint-based layout algorithm or the sizer-based algorithm
+ for this window.
+
+ This function does not get called automatically when the window is resized
+ because lots of windows deriving from wxWindow does not need this functionality.
+ If you want to have Layout() called automatically, you should derive
+ from wxPanel (see wxPanel::Layout).
+
+ @see @ref overview_windowsizing
+ */
+ virtual bool Layout();
+
+ /**
+ Determines whether the Layout() function will be called automatically
+ when the window is resized. Please note that this only happens for the
+ windows usually used to contain children, namely wxPanel and wxTopLevelWindow
+ (and the classes deriving from them).
+
+ This method is called implicitly by SetSizer() but if you use SetConstraints()
+ you should call it manually or otherwise the window layout won't be correctly
+ updated when its size changes.
+
+ @param autoLayout
+ Set this to @true if you wish the Layout() function to be
+ called automatically when the window is resized
+ (really happens only if you derive from wxPanel or wxTopLevelWindow).
+
+ @see SetConstraints()
+ */
+ void SetAutoLayout(bool autoLayout);
+
+ //@}
+
+
+
+ /**
+ @name Mouse functions
+ */
+ //@{
+
+ /**
+ Directs all mouse input to this window.
+ Call ReleaseMouse() to release the capture.
+
+ Note that wxWidgets maintains the stack of windows having captured the mouse
+ and when the mouse is released the capture returns to the window which had had
+ captured it previously and it is only really released if there were no previous
+ window. In particular, this means that you must release the mouse as many times
+ as you capture it, unless the window receives the wxMouseCaptureLostEvent event.
+
+ Any application which captures the mouse in the beginning of some operation
+ must handle wxMouseCaptureLostEvent and cancel this operation when it receives
+ the event. The event handler must not recapture mouse.
+
+ @see ReleaseMouse(), wxMouseCaptureLostEvent
+ */
+ void CaptureMouse();
+
+ /**
+ Returns the caret() associated with the window.
+ */
+ wxCaret* GetCaret() const;
+
+ /**
+ Return the cursor associated with this window.
+
+ @see SetCursor()
+ */
+ const wxCursor& GetCursor() const;
+
+ /**
+ Returns @true if this window has the current mouse capture.
+
+ @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent,
+ wxMouseCaptureChangedEvent
+ */
+ virtual bool HasCapture() const;
+
+ /**
+ Releases mouse input captured with CaptureMouse().
+
+ @see CaptureMouse(), HasCapture(), ReleaseMouse(),
+ wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ */
+ void ReleaseMouse();
+
+ /**
+ Sets the caret() associated with the window.
+ */
+ void SetCaret(wxCaret* caret);
+
/**
Sets the window's cursor. Notice that the window cursor also sets it for the
children of the window implicitly.
virtual bool SetCursor(const wxCursor& cursor);
/**
- Associates a drop target with this window.
- If the window already has a drop target, it is deleted.
+ Moves the pointer to the given position on the window.
- @see GetDropTarget(), @ref overview_dnd
+ @note This function is not supported under Mac because Apple Human
+ Interface Guidelines forbid moving the mouse cursor programmatically.
+
+ @param x
+ The new x position for the cursor.
+ @param y
+ The new y position for the cursor.
*/
- virtual void SetDropTarget(wxDropTarget* target);
+ virtual void WarpPointer(int x, int y);
+
+ //@}
+
+
+
/**
- Sets the help text to be used as context-sensitive help for this window.
- Note that the text is actually stored by the current wxHelpProvider
- implementation, and not in the window object itself.
+ @name Miscellaneous functions
+ */
+ //@{
- @see GetHelpText(), wxHelpProvider::AddHelp()
+ /**
+ Does the window-specific updating after processing the update event.
+ This function is called by UpdateWindowUI() in order to check return
+ values in the wxUpdateUIEvent and act appropriately.
+ For example, to allow frame and dialog title updating, wxWidgets
+ implements this function as follows:
+
+ @code
+ // do the window-specific processing after processing the update event
+ void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
+ {
+ if ( event.GetSetEnabled() )
+ Enable(event.GetEnabled());
+
+ if ( event.GetSetText() )
+ {
+ if ( event.GetText() != GetTitle() )
+ SetTitle(event.GetText());
+ }
+ }
+ @endcode
+ */
+ virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
+
+ /**
+ Returns the platform-specific handle of the physical window.
+ Cast it to an appropriate handle, such as @b HWND for Windows,
+ @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
+ */
+ virtual WXWidget GetHandle() const;
+
+ /**
+ This method should be overridden to return @true if this window has
+ multiple pages. All standard class with multiple pages such as
+ wxNotebook, wxListbook and wxTreebook already override it to return @true
+ and user-defined classes with similar behaviour should do it as well to
+ allow the library to handle such windows appropriately.
+ */
+ virtual bool HasMultiplePages() const;
+
+ /**
+ This function is (or should be, in case of custom controls) called during
+ window creation to intelligently set up the window visual attributes, that is
+ the font and the foreground and background colours.
+
+ By "intelligently" the following is meant: by default, all windows use their
+ own @ref GetClassDefaultAttributes() default attributes.
+ However if some of the parents attributes are explicitly (that is, using
+ SetFont() and not wxWindow::SetOwnFont) changed and if the corresponding
+ attribute hadn't been explicitly set for this window itself, then this
+ window takes the same value as used by the parent.
+ In addition, if the window overrides ShouldInheritColours() to return @false,
+ the colours will not be changed no matter what and only the font might.
+
+ This rather complicated logic is necessary in order to accommodate the
+ different usage scenarios. The most common one is when all default attributes
+ are used and in this case, nothing should be inherited as in modern GUIs
+ different controls use different fonts (and colours) than their siblings so
+ they can't inherit the same value from the parent. However it was also deemed
+ desirable to allow to simply change the attributes of all children at once by
+ just changing the font or colour of their common parent, hence in this case we
+ do inherit the parents attributes.
*/
- void SetHelpText(const wxString& helpText);
+ virtual void InheritAttributes();
/**
- Sets the identifier of the window.
-
- @remarks Each window has an integer identifier. If the application has
- not provided one, an identifier will be generated.
- Normally, the identifier should be provided on creation
- and should not be modified subsequently.
-
- @see GetId(), @ref overview_windowids
+ Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
+ to the dialog via validators.
*/
- void SetId(wxWindowID winid);
+ virtual void InitDialog();
/**
- Sets the window's label.
-
- @param label
- The window label.
+ Returns @true if the window contents is double-buffered by the system, i.e. if
+ any drawing done on the window is really done on a temporary backing surface
+ and transferred to the screen all at once later.
- @see GetLabel()
+ @see wxBufferedDC
*/
- virtual void SetLabel(const wxString& label);
+ virtual bool IsDoubleBuffered() const;
/**
- Sets the window's name.
-
- @param name
- A name to set for the window.
+ Returns @true if the window is retained, @false otherwise.
- @see GetName()
+ @remarks Retained windows are only available on X platforms.
*/
- virtual void SetName(const wxString& name);
+ virtual bool IsRetained() const;
/**
- Deletes the current validator (if any) and sets the window validator, having
- called wxValidator::Clone to create a new validator of this type.
+ Returns @true if this window is intrinsically enabled, @false otherwise,
+ i.e. if @ref Enable() Enable(@false) had been called. This method is
+ mostly used for wxWidgets itself, user code should normally use
+ IsEnabled() instead.
*/
- virtual void SetValidator(const wxValidator& validator);
+ bool IsThisEnabled() const;
/**
- This function can be called under all platforms but only does anything under
- Mac OS X 10.3+ currently. Under this system, each of the standard control can
- exist in several sizes which correspond to the elements of wxWindowVariant enum.
-
- By default the controls use the normal size, of course, but this function can
- be used to change this.
+ Returns @true if the given window is a top-level one. Currently all frames and
+ dialogs are considered to be top-level windows (even if they have a parent
+ window).
*/
- void SetWindowVariant(wxWindowVariant variant);
+ virtual bool IsTopLevel() const;
/**
- Turns the given @a flag on if it's currently turned off and vice versa.
- This function cannot be used if the value of the flag is 0 (which is often
- the case for default flags).
-
- Also, please notice that not all styles can be changed after the control
- creation.
-
- @return Returns @true if the style was turned on by this function, @false
- if it was switched off.
+ Disables all other windows in the application so that
+ the user can only interact with this window.
- @see SetWindowStyleFlag(), HasFlag()
+ @param modal
+ If @true, this call disables all other windows in the application so that
+ the user can only interact with this window. If @false, the effect is
+ reversed.
*/
- bool ToggleWindowStyle(int flag);
+ virtual void MakeModal(bool modal = true);
/**
- Transfers values from child controls to data areas specified by their
- validators. Returns @false if a transfer failed.
-
- If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
- the method will also call TransferDataFromWindow() of all child windows.
+ This virtual function is normally only used internally, but
+ sometimes an application may need it to implement functionality
+ that should not be disabled by an application defining an OnIdle
+ handler in a derived class.
- @see TransferDataToWindow(), wxValidator, Validate()
+ This function may be used to do delayed painting, for example,
+ and most implementations call UpdateWindowUI()
+ in order to send update events to the window in idle time.
*/
- virtual bool TransferDataFromWindow();
+ virtual void OnInternalIdle();
/**
- Transfers values to child controls from data areas specified by their
- validators.
+ Registers a system wide hotkey. Every time the user presses the hotkey
+ registered here, this window will receive a hotkey event.
- If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
- the method will also call TransferDataToWindow() of all child windows.
+ It will receive the event even if the application is in the background
+ and does not have the input focus because the user is working with some
+ other application.
- @return Returns @false if a transfer failed.
+ @param hotkeyId
+ Numeric identifier of the hotkey. For applications this must be between 0
+ and 0xBFFF. If this function is called from a shared DLL, it must be a
+ system wide unique identifier between 0xC000 and 0xFFFF.
+ This is a MSW specific detail.
+ @param modifiers
+ A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT
+ or wxMOD_WIN specifying the modifier keys that have to be pressed along
+ with the key.
+ @param virtualKeyCode
+ The virtual key code of the hotkey.
- @see TransferDataFromWindow(), wxValidator, Validate()
+ @return @true if the hotkey was registered successfully. @false if some
+ other application already registered a hotkey with this
+ modifier/virtualKeyCode combination.
+
+ @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the
+ event. This function is currently only implemented
+ under Windows. It is used in the Windows CE port for
+ detecting hardware button presses.
+
+ @see UnregisterHotKey()
*/
- virtual bool TransferDataToWindow();
+ virtual bool RegisterHotKey(int hotkeyId, int modifiers,
+ int virtualKeyCode);
/**
Unregisters a system wide hotkey.
*/
virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE);
+ //@}
+
+
+ // NOTE: static functions must have their own group or Doxygen will screw
+ // up the ordering of the member groups
+
/**
- Validates the current values of the child controls using their validators.
- If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
- the method will also call Validate() of all child windows.
+ @name Miscellaneous static functions
+ */
+ //@{
- @return Returns @false if any of the validations failed.
+ /**
+ Returns the default font and colours which are used by the control.
- @see TransferDataFromWindow(), TransferDataToWindow(),
- wxValidator
+ This is useful if you want to use the same font or colour in your own control
+ as in a standard control -- which is a much better idea than hard coding specific
+ colours or fonts which might look completely out of place on the users
+ system, especially if it uses themes.
+
+ The @a variant parameter is only relevant under Mac currently and is
+ ignore under other platforms. Under Mac, it will change the size of the
+ returned font. See SetWindowVariant() for more about this.
+
+ This static method is "overridden" in many derived classes and so calling,
+ for example, wxButton::GetClassDefaultAttributes() will typically
+ return the values appropriate for a button which will be normally different
+ from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
+
+ The @c wxVisualAttributes structure has at least the fields
+ @c font, @c colFg and @c colBg. All of them may be invalid
+ if it was not possible to determine the default control appearance or,
+ especially for the background colour, if the field doesn't make sense as is
+ the case for @c colBg for the controls with themed background.
+
+ @see InheritAttributes()
*/
- virtual bool Validate();
+ static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
/**
- Moves the pointer to the given position on the window.
+ Finds the window or control which currently has the keyboard focus.
- @note This function is not supported under Mac because Apple Human
- Interface Guidelines forbid moving the mouse cursor programmatically.
+ @remarks Note that this is a static function, so it can be called without
+ needing a wxWindow pointer.
- @param x
- The new x position for the cursor.
- @param y
- The new y position for the cursor.
+ @see SetFocus(), HasFocus()
*/
- virtual void WarpPointer(int x, int y);
+ static wxWindow* FindFocus();
+
+ /**
+ Find the first window with the given @e id.
+
+ If @a parent is @NULL, the search will start from all top-level frames
+ and dialog boxes; if non-@NULL, the search will be limited to the given
+ window hierarchy.
+ The search is recursive in both cases.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
+
+ /**
+ Find a window by its label.
+
+ Depending on the type of window, the label may be a window title
+ or panel item label. If @a parent is @NULL, the search will start from all
+ top-level frames and dialog boxes; if non-@NULL, the search will be
+ limited to the given window hierarchy.
+ The search is recursive in both cases.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowByLabel(const wxString& label,
+ const wxWindow* parent = 0);
+
+ /**
+ Find a window by its name (as given in a window constructor or Create()
+ function call).
+
+ If @a parent is @NULL, the search will start from all top-level frames
+ and dialog boxes; if non-@NULL, the search will be limited to the given
+ window hierarchy.
+
+ The search is recursive in both cases. If no window with such name is found,
+ FindWindowByLabel() is called.
+
+ @see FindWindow()
+ */
+ static wxWindow* FindWindowByName(const wxString& name,
+ const wxWindow* parent = 0);
+
+ /**
+ Returns the currently captured window.
+
+ @see HasCapture(), CaptureMouse(), ReleaseMouse(),
+ wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
+ */
+ static wxWindow* GetCapture();
+
+ /**
+ Create a new ID or range of IDs that are not currently in use.
+ The IDs will be reserved until assigned to a wxWindow ID
+ or unreserved with UnreserveControlId().
+
+ See @ref overview_windowids for more information.
+
+ @param count
+ The number of sequential IDs to reserve.
+
+ @return Returns the ID or the first ID of the range, or wxID_NONE if the
+ specified number of identifiers couldn't be allocated.
+
+ @see UnreserveControlId(), wxIdManager,
+ @ref overview_windowids
+ */
+ static wxWindowID NewControlId(int count = 1);
+
+ /**
+ Unreserve an ID or range of IDs that was reserved by NewControlId().
+ See @ref overview_windowids for more information.
+
+ @param id
+ The starting ID of the range of IDs to unreserve.
+ @param count
+ The number of sequential IDs to unreserve.
+
+ @see NewControlId(), wxIdManager, @ref overview_windowids
+ */
+ static void UnreserveControlId(wxWindowID id, int count = 1);
//@}
+
+
protected:
/**
projects / wxWidgets.git / commitdiff
