/////////////////////////////////////////////////////////////////////////////
// Name: cshelp.h
-// Purpose: documentation for wxHelpProvider class
+// Purpose: interface of wxHelpProvider
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxHelpProvider
@wxheader{cshelp.h}
-
+
wxHelpProvider is an abstract class used by a program implementing
- context-sensitive help to
- show the help text for the given window.
-
+ context-sensitive help to show the help text for the given window.
+
The current help provider must be explicitly set by the application using
- wxHelpProvider::Set().
-
+ Set().
+
@library{wxcore}
@category{help}
-
- @seealso
- wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
- wxHelpControllerHelpProvider, wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
+
+ @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
+ wxHelpControllerHelpProvider, wxWindow::SetHelpText(),
+ wxWindow::GetHelpTextAtPoint()
*/
-class wxHelpProvider
+class wxHelpProvider
{
public:
/**
Virtual destructor for any base class.
*/
- ~wxHelpProvider();
+ virtual ~wxHelpProvider();
+
+ /**
+ Associates the text with the given window.
+
+ @remarks
+ Although all help providers have these functions to allow making
+ wxWindow::SetHelpText() work, not all of them implement the functions.
+ */
+ virtual void AddHelp(wxWindowBase* window, const wxString& text);
/**
- Associates the text with the given window or id. Although all help
- providers have these functions to allow making wxWindow::SetHelpText
- work, not all of them implement the functions.
+ Associates the text with the given ID.
+
+ This help text will be shown for all windows with ID @a id, unless they
+ have more specific help text associated using the other AddHelp()
+ prototype. May be used to set the same help string for all Cancel
+ buttons in the application, for example.
+
+ @remarks
+ Although all help providers have these functions to allow making
+ wxWindow::SetHelpText() work, not all of them implement the functions.
*/
- void AddHelp(wxWindowBase* window, const wxString& text);
+ virtual void AddHelp(wxWindowID id, const wxString& text);
/**
+ Returns pointer to help provider instance.
+
Unlike some other classes, the help provider is not created on demand.
- This must be explicitly done by the application.
+ This must be explicitly done by the application using Set().
*/
-#define wxHelpProvider* Get() /* implementation is private */
+ static wxHelpProvider* Get();
- //@{
/**
This version associates the given text with all windows with this id.
May be used to set the same help string for all Cancel buttons in
the application, for example.
*/
- wxString GetHelp(const wxWindowBase* window);
- void AddHelp(wxWindowID id, const wxString& text);
- //@}
+ virtual wxString GetHelp(const wxWindowBase* window);
/**
- Removes the association between the window pointer and the help text. This is
- called by the wxWindow destructor. Without this, the table of help strings will
- fill up
- and when window pointers are reused, the wrong help string will be found.
+ Removes the association between the window pointer and the help text.
+ This is called by the wxWindow destructor. Without this, the table of
+ help strings will fill up and when window pointers are reused, the
+ wrong help string will be found.
*/
- void RemoveHelp(wxWindowBase* window);
+ virtual void RemoveHelp(wxWindowBase* window);
/**
- Get/set the current, application-wide help provider. Returns
- the previous one.
+ Set the current, application-wide help provider.
+
+ @return Pointer to previous help provider or @NULL if there wasn't any.
*/
-#define wxHelpProvider* Set(wxHelpProvider* helpProvider) /* implementation is private */
+ static wxHelpProvider* Set(wxHelpProvider* helpProvider);
/**
- Shows help for the given window. Override this function if the help doesn't
- depend on the exact position inside the window, otherwise you need to override
- ShowHelpAtPoint().
-
- Returns @true if help was shown, or @false if no help was available for this
- window.
+ Shows help for the given window.
+
+ Override this function if the help doesn't depend on the exact position
+ inside the window, otherwise you need to override ShowHelpAtPoint().
+ Returns @true if help was shown, or @false if no help was available for
+ this window.
*/
- bool ShowHelp(wxWindowBase* window);
+ virtual bool ShowHelp(wxWindowBase* window);
/**
- This function may be overridden to show help for the window when it should
- depend on the position inside the window, By default this method forwards to
- ShowHelp(), so it is enough to only implement
- the latter if the help doesn't depend on the position.
-
- Returns @true if help was shown, or @false if no help was available for this
- window.
-
- @param window
- Window to show help text for.
-
- @param point
- Coordinates of the mouse at the moment of help event emission.
-
- @param origin
- Help event origin, see wxHelpEvent::GetOrigin.
+ This function may be overridden to show help for the window when it
+ should depend on the position inside the window, By default this method
+ forwards to ShowHelp(), so it is enough to only implement the latter if
+ the help doesn't depend on the position.
+
+ @param window
+ Window to show help text for.
+ @param point
+ Coordinates of the mouse at the moment of help event emission.
+ @param origin
+ Help event origin, see wxHelpEvent::GetOrigin.
+
+ @return @true if help was shown, or @false if no help was available
+ for this window.
+
+ @since 2.7.0
*/
- bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point,
- wxHelpEvent::Origin origin);
+ virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point,
+ wxHelpEvent::Origin origin);
};
+
/**
@class wxHelpControllerHelpProvider
@wxheader{cshelp.h}
-
+
wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
- supports
- both context identifiers and plain text help strings. If the help text is an
- integer,
- it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the
- string
- in a tooltip as per wxSimpleHelpProvider. If you use this with a
- wxCHMHelpController instance
- on windows, it will use the native style of tip window instead of wxTipWindow.
-
- You can use the convenience function @b wxContextId to convert an integer
- context
- id to a string for passing to wxWindow::SetHelpText.
-
+ supports both context identifiers and plain text help strings. If the help
+ text is an integer, it is passed to wxHelpController::DisplayContextPopup().
+ Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If
+ you use this with a wxCHMHelpController instance on windows, it will use
+ the native style of tip window instead of wxTipWindow.
+
+ You can use the convenience function wxContextId() to convert an integer
+ context id to a string for passing to wxWindow::SetHelpText().
+
@library{wxcore}
@category{help}
-
- @seealso
- wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, wxWindow::SetHelpText,
- wxWindow::GetHelpTextAtPoint
+
+ @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,
+ wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint()
*/
class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
{
public:
/**
- Note that the instance doesn't own the help controller. The help controller
- should be deleted separately.
+ Note that the instance doesn't own the help controller. The help
+ controller should be deleted separately.
*/
- wxHelpControllerHelpProvider(wxHelpControllerBase* hc = @NULL);
+ wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
/**
Returns the help controller associated with this help provider.
*/
- wxHelpControllerBase* GetHelpController();
+ wxHelpControllerBase* GetHelpController() const;
/**
Sets the help controller associated with this help provider.
};
+
/**
@class wxContextHelp
@wxheader{cshelp.h}
-
+
This class changes the cursor to a query and puts the application into a
- 'context-sensitive help mode'.
- When the user left-clicks on a window within the specified window, a wxEVT_HELP
- event is
- sent to that control, and the application may respond to it by popping up some
- help.
-
+ 'context-sensitive help mode'. When the user left-clicks on a window
+ within the specified window, a wxEVT_HELP event is sent to that control,
+ and the application may respond to it by popping up some help.
+
For example:
-
@code
wxContextHelp contextHelp(myWindow);
@endcode
-
+
There are a couple of ways to invoke this behaviour implicitly:
-
- Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This will
- put a question mark
- in the titlebar, and Windows will put the application into context-sensitive
- help mode automatically,
- with further programming.
- Create a wxContextHelpButton, whose predefined behaviour is to create a
- context help object.
- Normally you will write your application so that this button is only added to a
- dialog for non-Windows platforms
- (use wxDIALOG_EX_CONTEXTHELP on Windows).
-
+
+ - Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This
+ will put a question mark in the titlebar, and Windows will put the
+ application into context-sensitive help mode automatically, with further
+ programming.
+
+ - Create a wxContextHelpButton, whose predefined behaviour is
+ to create a context help object. Normally you will write your application
+ so that this button is only added to a dialog for non-Windows platforms
+ (use wxDIALOG_EX_CONTEXTHELP on Windows).
+
Note that on Mac OS X, the cursor does not change when in context-sensitive
help mode.
-
+
@library{wxcore}
@category{help}
-
- @seealso
- wxHelpEvent, wxHelpController, wxContextHelpButton
+
+ @see wxHelpEvent, wxHelpController, wxContextHelpButton
*/
class wxContextHelp : public wxObject
{
public:
/**
Constructs a context help object, calling BeginContextHelp() if
- @e doNow is @true (the default).
-
- If @e window is @NULL, the top window is used.
+ @a doNow is @true (the default).
+
+ If @a window is @NULL, the top window is used.
*/
- wxContextHelp(wxWindow* window = @NULL, bool doNow = @true);
+ wxContextHelp(wxWindow* window = NULL, bool doNow = true);
/**
Destroys the context help object.
~wxContextHelp();
/**
- Puts the application into context-sensitive help mode. @e window is the window
- which will be used to catch events; if @NULL, the top window will be used.
-
- Returns @true if the application was successfully put into context-sensitive
- help mode.
- This function only returns when the event loop has finished.
+ Puts the application into context-sensitive help mode. @a window is the
+ window which will be used to catch events; if @NULL, the top window
+ will be used. Returns @true if the application was successfully put
+ into context-sensitive help mode. This function only returns when the
+ event loop has finished.
*/
- bool BeginContextHelp(wxWindow* window = @NULL);
+ bool BeginContextHelp(wxWindow* window = NULL);
/**
- Ends context-sensitive help mode. Not normally called by the application.
+ Ends context-sensitive help mode. Not normally called by the
+ application.
*/
bool EndContextHelp();
};
+
/**
@class wxContextHelpButton
@wxheader{cshelp.h}
-
+
Instances of this class may be used to add a question mark button that when
- pressed, puts the
- application into context-help mode. It does this by creating a wxContextHelp
- object which itself
- generates a wxEVT_HELP event when the user clicks on a window.
-
+ pressed, puts the application into context-help mode. It does this by
+ creating a wxContextHelp object which itself generates a wxEVT_HELP event
+ when the user clicks on a window.
+
On Windows, you may add a question-mark icon to a dialog by use of the
- wxDIALOG_EX_CONTEXTHELP extra style, but
- on other platforms you will have to add a button explicitly, usually next to
- OK, Cancel or similar buttons.
-
+ wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have
+ to add a button explicitly, usually next to OK, Cancel or similar buttons.
+
@library{wxcore}
@category{help}
-
- @seealso
- wxBitmapButton, wxContextHelp
+
+ @see wxBitmapButton, wxContextHelp
*/
class wxContextHelpButton : public wxBitmapButton
{
public:
- //@{
+ /// Default constructor.
+ wxContextHelpButton();
+
/**
Constructor, creating and showing a context help button.
-
- @param parent
- Parent window. Must not be @NULL.
-
- @param id
- Button identifier. Defaults to wxID_CONTEXT_HELP.
-
- @param pos
- Button position.
-
- @param size
- Button size. If wxDefaultSize is specified then the button is sized
- appropriately for the question mark bitmap.
-
- @param style
- Window style.
+
+ @param parent
+ Parent window. Must not be @NULL.
+ @param id
+ Button identifier. Defaults to wxID_CONTEXT_HELP.
+ @param pos
+ Button position.
+ @param size
+ Button size. If wxDefaultSize is specified then the button is sized
+ appropriately for the question mark bitmap.
+ @param style
+ Window style.
+
+ @remarks
+ Normally you only need pass the parent window to the constructor, and
+ use the defaults for the remaining parameters.
*/
- wxContextHelpButton();
- wxContextHelpButton(wxWindow* parent,
- wxWindowID id = wxID_CONTEXT_HELP,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxBU_AUTODRAW);
- //@}
+ wxContextHelpButton(wxWindow* parent,
+ wxWindowID id = wxID_CONTEXT_HELP,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = wxBU_AUTODRAW);
};
/**
@class wxSimpleHelpProvider
@wxheader{cshelp.h}
-
+
wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
only plain text help strings, and shows the string associated with the
control (if any) in a tooltip.
-
+
@library{wxcore}
@category{help}
-
- @seealso
- wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
- wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
+
+ @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
+ wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint()
*/
class wxSimpleHelpProvider : public wxHelpProvider
{
public:
-
+
};
+
projects / wxWidgets.git / blobdiff