Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

upported wxHelpProvider docs fixes from r52197; minor tweaks to Doxygen docs of other classes in cshelp.h

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52698 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Václav Slavík
2008-03-22 14:57:53 +00:00
parent dbd1c638fe
commit d155b6f47e
2 changed files with 93 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
interface/cshelp.h
View File

@@ -11,8 +11,7 @@
@wxheader{cshelp.h} @wxheader{cshelp.h}
wxHelpProvider is an abstract class used by a program implementing wxHelpProvider is an abstract class used by a program implementing
context-sensitive help to context-sensitive help to show the help text for the given window.
show the help text for the given window.
The current help provider must be explicitly set by the application using The current help provider must be explicitly set by the application using
wxHelpProvider::Set(). wxHelpProvider::Set().
@@ -21,7 +20,8 @@
@category{help} @category{help}
@see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
wxHelpControllerHelpProvider, wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint wxHelpControllerHelpProvider, wxWindow::SetHelpText(),
wxWindow::GetHelpTextAtPoint()
*/ */
class wxHelpProvider class wxHelpProvider
{ {
@@ -32,58 +32,75 @@ public:
~wxHelpProvider(); ~wxHelpProvider();
/** /**
Associates the text with the given window or id. Although all help Associates the text with the given window.
providers have these functions to allow making wxWindow::SetHelpText
work, not all of them implement the functions. @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(wxWindowBase* window, const wxString& text);
/** /**
Unlike some other classes, the help provider is not created on demand. Associates the text with the given ID.
This must be explicitly done by the application.
*/ This help text will be shown for all windows with ID @a id, unless they
wxHelpProvider* Get(); 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.
*/
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 using Set().
*/
static wxHelpProvider* Get();
//@{
/** /**
This version associates the given text with all windows with this id. 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 May be used to set the same help string for all Cancel buttons in
the application, for example. the application, for example.
*/ */
wxString GetHelp(const wxWindowBase* window); virtual wxString GetHelp(const wxWindowBase* window);
void AddHelp(wxWindowID id, const wxString& text);
//@}
/** /**
Removes the association between the window pointer and the help text. This is Removes the association between the window pointer and the help text.
called by the wxWindow destructor. Without this, the table of help strings will This is called by the wxWindow destructor. Without this, the table of
fill up help strings will fill up and when window pointers are reused, the
and when window pointers are reused, the wrong help string will be found. wrong help string will be found.
*/ */
void RemoveHelp(wxWindowBase* window); virtual void RemoveHelp(wxWindowBase* window);
/** /**
Get/set the current, application-wide help provider. Returns Set the current, application-wide help provider.
the previous one.
@return Pointer to previous help provider or @NULL if there wasn't any.
*/ */
wxHelpProvider* Set(wxHelpProvider* helpProvider); static wxHelpProvider* Set(wxHelpProvider* helpProvider);
/** /**
Shows help for the given window. Override this function if the help doesn't Shows help for the given window.
depend on the exact position inside the window, otherwise you need to override
ShowHelpAtPoint(). Override this function if the help doesn't depend on the exact position
Returns @true if help was shown, or @false if no help was available for this inside the window, otherwise you need to override ShowHelpAtPoint().
window. 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 This function may be overridden to show help for the window when it
depend on the position inside the window, By default this method forwards to should depend on the position inside the window, By default this method
ShowHelp(), so it is enough to only implement forwards to ShowHelp(), so it is enough to only implement the latter if
the latter if the help doesn't depend on the position. the help doesn't depend on the position. Returns @true if help was
Returns @true if help was shown, or @false if no help was available for this shown, or @false if no help was available for this window.
window.
@param window @param window
Window to show help text for. Window to show help text for.
@@ -92,8 +109,8 @@ public:
@param origin @param origin
Help event origin, see wxHelpEvent::GetOrigin. Help event origin, see wxHelpEvent::GetOrigin.
*/ */
bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point, virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point,
wxHelpEvent::Origin origin); wxHelpEvent::Origin origin);
}; };
@@ -103,31 +120,27 @@ public:
@wxheader{cshelp.h} @wxheader{cshelp.h}
wxHelpControllerHelpProvider is an implementation of wxHelpProvider which wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
supports supports both context identifiers and plain text help strings. If the help
both context identifiers and plain text help strings. If the help text is an text is an integer, it is passed to wxHelpController::DisplayContextPopup.
integer, Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If
it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the you use this with a wxCHMHelpController instance on windows, it will use
string the native style of tip window instead of wxTipWindow.
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 You can use the convenience function wxContextId() to convert an integer
context context id to a string for passing to wxWindow::SetHelpText().
id to a string for passing to wxWindow::SetHelpText.
@library{wxcore} @library{wxcore}
@category{help} @category{help}
@see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,
wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint()
*/ */
class wxHelpControllerHelpProvider : public wxSimpleHelpProvider class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
{ {
public: public:
/** /**
Note that the instance doesn't own the help controller. The help controller Note that the instance doesn't own the help controller. The help
should be deleted separately. controller should be deleted separately.
*/ */
wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL); wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
@@ -149,30 +162,26 @@ public:
@wxheader{cshelp.h} @wxheader{cshelp.h}
This class changes the cursor to a query and puts the application into a This class changes the cursor to a query and puts the application into a
'context-sensitive help mode'. 'context-sensitive help mode'. When the user left-clicks on a window
When the user left-clicks on a window within the specified window, a wxEVT_HELP within the specified window, a wxEVT_HELP event is sent to that control,
event is and the application may respond to it by popping up some help.
sent to that control, and the application may respond to it by popping up some
help.
For example: For example:
@code @code
wxContextHelp contextHelp(myWindow); wxContextHelp contextHelp(myWindow);
@endcode @endcode
There are a couple of ways to invoke this behaviour implicitly: There are a couple of ways to invoke this behaviour implicitly:
Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This will * Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This
put a question mark will put a question mark in the titlebar, and Windows will put the
in the titlebar, and Windows will put the application into context-sensitive application into context-sensitive help mode automatically, with further
help mode automatically, programming.
with further programming.
Create a wxContextHelpButton, whose predefined behaviour is to create a * Create a wxContextHelpButton, whose predefined behaviour is
context help object. to create a context help object. Normally you will write your application
Normally you will write your application so that this button is only added to a so that this button is only added to a dialog for non-Windows platforms
dialog for non-Windows platforms (use wxDIALOG_EX_CONTEXTHELP on Windows).
(use wxDIALOG_EX_CONTEXTHELP on Windows).
Note that on Mac OS X, the cursor does not change when in context-sensitive Note that on Mac OS X, the cursor does not change when in context-sensitive
help mode. help mode.
@@ -198,16 +207,17 @@ public:
~wxContextHelp(); ~wxContextHelp();
/** /**
Puts the application into context-sensitive help mode. @a window is the window Puts the application into context-sensitive help mode. @a window is the
which will be used to catch events; if @NULL, the top window will be used. window which will be used to catch events; if @NULL, the top window
Returns @true if the application was successfully put into context-sensitive will be used. Returns @true if the application was successfully put
help mode. into context-sensitive help mode. This function only returns when the
This function only returns when the event loop has finished. 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(); bool EndContextHelp();
}; };
@@ -219,15 +229,13 @@ public:
@wxheader{cshelp.h} @wxheader{cshelp.h}
Instances of this class may be used to add a question mark button that when Instances of this class may be used to add a question mark button that when
pressed, puts the pressed, puts the application into context-help mode. It does this by
application into context-help mode. It does this by creating a wxContextHelp creating a wxContextHelp object which itself generates a wxEVT_HELP event
object which itself when the user clicks on a window.
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 On Windows, you may add a question-mark icon to a dialog by use of the
wxDIALOG_EX_CONTEXTHELP extra style, but wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have
on other platforms you will have to add a button explicitly, usually next to to add a button explicitly, usually next to OK, Cancel or similar buttons.
OK, Cancel or similar buttons.
@library{wxcore} @library{wxcore}
@category{help} @category{help}
@@ -237,7 +245,9 @@ public:
class wxContextHelpButton : public wxBitmapButton class wxContextHelpButton : public wxBitmapButton
{ {
public: public:
//@{ /// Default constructor.
wxContextHelpButton();
/** /**
Constructor, creating and showing a context help button. Constructor, creating and showing a context help button.
@@ -254,17 +264,14 @@ public:
@param style @param style
Window style. Window style.
*/ */
wxContextHelpButton();
wxContextHelpButton(wxWindow* parent, wxContextHelpButton(wxWindow* parent,
wxWindowID id = wxID_CONTEXT_HELP, wxWindowID id = wxID_CONTEXT_HELP,
const wxPoint& pos = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize, const wxSize& size = wxDefaultSize,
long style = wxBU_AUTODRAW); long style = wxBU_AUTODRAW);
//@}
}; };
/** /**
@class wxSimpleHelpProvider @class wxSimpleHelpProvider
@wxheader{cshelp.h} @wxheader{cshelp.h}
@@ -277,7 +284,7 @@ public:
@category{help} @category{help}
@see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp, @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint()
*/ */
class wxSimpleHelpProvider : public wxHelpProvider class wxSimpleHelpProvider : public wxHelpProvider
{ {

2
interface/window.h
View File

@@ -2030,7 +2030,7 @@ public:
implementation, implementation,
and not in the window object itself. and not in the window object itself.
@see GetHelpText(), wxHelpProvider @see GetHelpText(), wxHelpProvider::AddHelp()
*/ */
virtual void SetHelpText(const wxString& helpText); virtual void SetHelpText(const wxString& helpText);