X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..a0f4d36895556e3054e2256cb5f1787cc9fcf75c:/interface/cshelp.h diff --git a/interface/cshelp.h b/interface/cshelp.h index 821fe2bd0a..22f366dd71 100644 --- a/interface/cshelp.h +++ b/interface/cshelp.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: cshelp.h -// Purpose: documentation for wxHelpProvider class +// Purpose: interface of wxHelpProvider // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,8 +11,7 @@ @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(). @@ -20,9 +19,9 @@ @library{wxcore} @category{help} - @seealso - wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, - wxHelpControllerHelpProvider, wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint + @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, + wxHelpControllerHelpProvider, wxWindow::SetHelpText(), + wxWindow::GetHelpTextAtPoint() */ class wxHelpProvider { @@ -33,59 +32,76 @@ public: ~wxHelpProvider(); /** - 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 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 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(). */ - wxHelpProvider* Get(); + 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. */ - wxHelpProvider* Set(wxHelpProvider* helpProvider); + 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. - + 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 @@ -93,42 +109,38 @@ public: @param origin Help event origin, see wxHelpEvent::GetOrigin. */ - 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); @@ -144,35 +156,32 @@ public: }; + /** @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. @@ -180,8 +189,7 @@ public: @library{wxcore} @category{help} - @seealso - wxHelpEvent, wxHelpController, wxContextHelpButton + @see wxHelpEvent, wxHelpController, wxContextHelpButton */ class wxContextHelp : public wxObject { @@ -199,49 +207,50 @@ public: ~wxContextHelp(); /** - 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. + 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); /** - 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 @@ -255,13 +264,11 @@ public: @param style Window style. */ - wxContextHelpButton(); wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxBU_AUTODRAW); - //@} }; @@ -276,12 +283,12 @@ public: @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: }; +