+ @param effect
+ The effect to use.
+
+ @param timeout
+ The @a timeout parameter specifies the time of the animation, in
+ milliseconds. If the default value of 0 is used, the default
+ animation time for the current platform is used.
+
+ @note Currently this function is only implemented in wxMSW and wxOSX
+ (for wxTopLevelWindows only in Carbon version and for any kind of
+ windows in Cocoa) and does the same thing as Show() in the other
+ ports.
+
+ @since 2.9.0
+
+ @see HideWithEffect()
+ */
+ virtual bool ShowWithEffect(wxShowEffect effect,
+ unsigned int timeout = 0);
+
+ //@}
+
+
+ /**
+ @name Context-sensitive help functions
+ */
+ //@{
+
+ /**
+ 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;
+
+ /**
+ 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()
+ */
+ void SetHelpText(const wxString& helpText);
+
+ /**
+ 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;
+
+ /**
+ Get the associated tooltip or @NULL if none.
+ */
+ wxToolTip* GetToolTip() const;
+
+ /**
+ Get the text of the associated tooltip or empty string if none.
+ */
+ wxString GetToolTipText() 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& tipString);
+
+ /**
+ @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.
+ It is recommended to not explicitly specify coordinates when
+ calling this method in response to mouse click, because some of
+ the ports (namely, wxGTK) can do a better job of positioning
+ the menu in that case.
+
+ @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 = wxDefaultPosition);
+
+ /**
+ @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 usual. If coordinates are not specified, the 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);
+
+ //@}
+
+
+ /**
+ Validator functions
+ */
+ //@{
+
+ /**
+ Returns a pointer to the current validator for the window, or @NULL if
+ there is none.
+ */
+ virtual wxValidator* GetValidator();
+
+ /**
+ 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);
+
+ /**
+ 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.
+
+ @see TransferDataToWindow(), wxValidator, Validate()
+ */
+ virtual bool TransferDataFromWindow();
+
+ /**
+ Transfers values to child controls from data areas specified by their
+ validators.
+
+ If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
+ the method will also call TransferDataToWindow() of all child windows.
+
+ @return Returns @false if a transfer failed.
+
+ @see TransferDataFromWindow(), wxValidator, Validate()
+ */
+ virtual bool TransferDataToWindow();
+
+ /**
+ 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.
+
+ @return Returns @false if any of the validations failed.
+
+ @see TransferDataFromWindow(), TransferDataToWindow(),
+ wxValidator
+ */
+ virtual bool Validate();
+
+ //@}
+
+
+ /**
+ @name wxWindow properties functions
+ */
+ //@{
+
+ /**
+ 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) a 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 layout direction for this window,
+ Note that @c wxLayout_Default is returned if layout direction is not supported.
+ */
+ virtual wxLayoutDirection GetLayoutDirection() const;
+
+ /**
+ Mirror coordinates for RTL layout if this window uses it and if the
+ mirroring is not done automatically like Win32.
+ */
+ virtual wxCoord AdjustForLayoutDirection(wxCoord x,
+ wxCoord width,
+ wxCoord widthTotal) 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 the value previously passed to SetWindowVariant().
+ */
+ wxWindowVariant GetWindowVariant() const;
+
+ /**
+ 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
+ */
+ void SetId(wxWindowID winid);
+
+ /**
+ Sets the window's label.
+
+ @param label
+ The window label.
+
+ @see GetLabel()
+ */
+ virtual void SetLabel(const wxString& label);
+
+ /**
+ Sets the layout direction for this window.
+ */
+ virtual void SetLayoutDirection(wxLayoutDirection dir);
+
+ /**
+ Sets the window's name.
+
+ @param name
+ A name to set for the window.
+
+ @see GetName()
+ */
+ virtual void SetName(const wxString& name);
+
+ /**
+ 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.
+ */
+ void SetWindowVariant(wxWindowVariant variant);
+
+ /**
+ 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();
+
+ /**
+ Sets the accelerator table for this window. See wxAcceleratorTable.
+ */
+ virtual void SetAcceleratorTable(const wxAcceleratorTable& accel);
+
+ /**
+ Sets the accessible for this window. Any existing accessible for this window
+ will be deleted first, if not identical to @e accessible.
+ See also wxAccessible.
+ */
+ void SetAccessible(wxAccessible* accessible);
+
+ //@}
+
+
+ /**
+ @name Window deletion functions
+ */
+ //@{
+
+ /**
+ 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.
+
+ @return @true if the event was handled and not vetoed, @false otherwise.
+
+ @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.
+
+ 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
+ */
+ //@{
+
+ /**
+ Returns the associated drop target, which may be @NULL.
+
+ @see SetDropTarget(), @ref overview_dnd
+ */
+ virtual wxDropTarget* GetDropTarget() const;
+
+ /**
+ Associates a drop target with this window.
+ If the window already has a drop target, it is deleted.
+
+ @see GetDropTarget(), @ref overview_dnd
+ */
+ virtual void SetDropTarget(wxDropTarget* target);
+
+ /**
+ 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);
+
+ //@}
+
+
+ /**
+ @name Constraints, sizers and window layout functions
+ */
+ //@{
+
+ /**
+ Returns the sizer of which this window is a member, if any, otherwise @NULL.
+ */
+ wxSizer* GetContainingSizer() const;
+
+ /**
+ Returns 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 @a 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 so that the
+ sizer will be effectively used to layout the window children whenever
+ it is resized.
+
+ @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
+ but remember to do it yourself in this case to avoid memory leaks.
+
+ @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 minimal 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
+ 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.
+ */
+ 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.
+
+ 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.
projects / wxWidgets.git / blobdiff