mac paths updated

[wxWidgets.git] / interface / cshelp.h

diff --git a/interface/cshelp.h b/interface/cshelp.h
index 18a1eee9d87cbdbc7773b4f191e2b45bb9aeabd9..e727f54a71a4d32b8888fefe7fa67bf644db378a 100644 (file)
--- a/interface/cshelp.h
+++ b/interface/cshelp.h
@@ -11,17 +11,17 @@
     @wxheader{cshelp.h}
 
     wxHelpProvider is an abstract class used by a program implementing
     @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
 
     The current help provider must be explicitly set by the application using

-    wxHelpProvider::Set().
+    Set().

 
     @library{wxcore}
     @category{help}
 
     @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
 
     @library{wxcore}
     @category{help}
 
     @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,

-    wxHelpControllerHelpProvider, wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
+         wxHelpControllerHelpProvider, wxWindow::SetHelpText(),
+         wxWindow::GetHelpTextAtPoint()

 */
 class wxHelpProvider
 {
 */
 class wxHelpProvider
 {


@@ -29,61 +29,76 @@ public:
     /**
         Virtual destructor for any base class.
     */
     /**
         Virtual destructor for any base class.
     */

-    ~wxHelpProvider();
+    virtual ~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.
         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.
     */
     /**
         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.

 
         @param window
             Window to show help text for.
 
         @param window
             Window to show help text for.


@@ -91,9 +106,14 @@ public:
             Coordinates of the mouse at the moment of help event emission.
         @param origin
             Help event origin, see wxHelpEvent::GetOrigin.
             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);

 };
 
 
 };
 
 


@@ -103,31 +123,27 @@ public:
     @wxheader{cshelp.h}
 
     wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
     @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}
 
     @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,
 
     @library{wxcore}
     @category{help}
 
     @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,

-    wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
+         wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint()

 */
 class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 {
 public:
     /**
 */
 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);
 


@@ -149,30 +165,26 @@ public:
     @wxheader{cshelp.h}
 
     This class changes the cursor to a query and puts the application into a
     @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:
 
     For example:

-

     @code
     wxContextHelp contextHelp(myWindow);
     @endcode
 
     There are a couple of ways to invoke this behaviour implicitly:
 
     @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.
 
     Note that on Mac OS X, the cursor does not change when in context-sensitive
     help mode.


@@ -188,6 +200,7 @@ public:
     /**
         Constructs a context help object, calling BeginContextHelp() if
         @a doNow is @true (the default).
     /**
         Constructs a context help object, calling BeginContextHelp() if
         @a doNow is @true (the default).

+

         If @a window is @NULL, the top window is used.
     */
     wxContextHelp(wxWindow* window = NULL, bool doNow = true);
         If @a window is @NULL, the top window is used.
     */
     wxContextHelp(wxWindow* window = NULL, bool doNow = true);


@@ -198,16 +211,17 @@ public:
     ~wxContextHelp();
 
     /**
     ~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);
 
     /**
     */
     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 +233,13 @@ public:
     @wxheader{cshelp.h}
 
     Instances of this class may be used to add a question mark button that when
     @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
 
     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}
 
     @library{wxcore}
     @category{help}


@@ -237,7 +249,9 @@ public:
 class wxContextHelpButton : public wxBitmapButton
 {
 public:
 class wxContextHelpButton : public wxBitmapButton
 {
 public:

-    //@{
+    /// Default constructor.
+    wxContextHelpButton();
+

     /**
         Constructor, creating and showing a context help button.
 
     /**
         Constructor, creating and showing a context help button.
 


@@ -248,23 +262,23 @@ public:
         @param pos
             Button position.
         @param size
         @param pos
             Button position.
         @param size

-            Button size. If wxDefaultSize is specified then the button is
-        sized
+            Button size. If wxDefaultSize is specified then the button is sized

             appropriately for the question mark bitmap.
         @param style
             Window style.
             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}
 /**
     @class wxSimpleHelpProvider
     @wxheader{cshelp.h}


@@ -277,7 +291,7 @@ public:
     @category{help}
 
     @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
     @category{help}
 
     @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,

-    wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
+         wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint()

 */
 class wxSimpleHelpProvider : public wxHelpProvider
 {
 */
 class wxSimpleHelpProvider : public wxHelpProvider
 {