mac paths updated

[wxWidgets.git] / interface / tipdlg.h

diff --git a/interface/tipdlg.h b/interface/tipdlg.h
index 4f0e01d18295c43ead2fa6f398016fa94b02db3b..4b68bf8fb615963061d894d7539b3ac48d41f00b 100644 (file)
--- a/interface/tipdlg.h
+++ b/interface/tipdlg.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        tipdlg.h
-// Purpose:     documentation for wxTipProvider class
+// Purpose:     interface of wxTipProvider
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -9,43 +9,41 @@
 /**
     @class wxTipProvider
     @wxheader{tipdlg.h}
-    
-    This is the class used together with wxShowTip function.
+
+    This is the class used together with wxShowTip() function.
     It must implement wxTipProvider::GetTip function and return the
     current tip from it (different tip each time it is called).
-    
+
     You will never use this class yourself, but you need it to show startup tips
     with wxShowTip. Also, if you want to get the tips text from elsewhere than a
     simple text file, you will want to derive a new class from wxTipProvider and
-    use it instead of the one returned by wxCreateFileTipProvider.
-    
+    use it instead of the one returned by wxCreateFileTipProvider().
+
     @library{wxadv}
     @category{FIXME}
-    
-    @seealso
-    @ref overview_tipsoverview "Startup tips overview", ::wxShowTip
+
+    @see @ref overview_tipsoverview "Startup tips overview", ::wxShowTip
 */
-class wxTipProvider 
+class wxTipProvider
 {
 public:
     /**
         Constructor.
-        
-        @param currentTip 
-        The starting tip index.
+
+        @param currentTip
+            The starting tip index.
     */
     wxTipProvider(size_t currentTip);
 
     /**
-        Returns the index of the current tip (i.e. the one which would be returned by 
+        Returns the index of the current tip (i.e. the one which would be returned by
         GetTip).
-        
-        The program usually remembers the value returned by this function after calling 
-        wxShowTip. Note that it is not the same as the value which
+        The program usually remembers the value returned by this function after calling
+        wxShowTip(). Note that it is not the same as the value which
         was passed to wxShowTip + 1 because the user might have pressed the "Next"
         button in the tip dialog.
     */
-    size_t GetCurrentTip();
+    size_t GetCurrentTip() const;
 
     /**
         Return the text of the current tip and pass to the next one. This function is
@@ -55,34 +53,62 @@ public:
 
     /**
         Returns a modified tip. This function will be called immediately after read,
-        and before being check whether it is a comment, an empty string or a string 
+        and before being check whether it is a comment, an empty string or a string
         to translate. You can optionally override this in your custom user-derived
-        class 
-        to optionally to modify the tip as soon as it is read. You can return any 
-        modification to the string. If you return wxEmptyString, then this tip is 
+        class
+        to optionally to modify the tip as soon as it is read. You can return any
+        modification to the string. If you return wxEmptyString, then this tip is
         skipped, and the next one is read.
     */
     virtual wxString PreProcessTip(const wxString& tip);
 };
 
 
+
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_dialog */
+//@{
+
 /**
-    This function creates a wxTipProvider which may be
-    used with wxShowTip.
-    
-    @param filename 
-    The name of the file containing the tips, one per line
-    
-    @param currentTip 
-    The index of the first tip to show - normally this index
-    is remembered between the 2 program runs.
-    
-    @sa @ref overview_tipsoverview "Tips overview"
+    This function creates a wxTipProvider which may be used with wxShowTip().
+
+    @param filename
+        The name of the file containing the tips, one per line.
+    @param currentTip
+        The index of the first tip to show. Normally this index is remembered
+        between the 2 program runs.
+
+    @see @ref overview_tips
+
+    @header{wx/tipdlg.h}
+*/
+wxTipProvider* wxCreateFileTipProvider(const wxString& filename,
+                                       size_t currentTip);
+
+/**
+    This function shows a "startup tip" to the user. The return value is the
+    state of the "Show tips at startup" checkbox.
+
+    @param parent
+        The parent window for the modal dialog.
+    @param tipProvider
+        An object which is used to get the text of the tips. It may be created
+        with the wxCreateFileTipProvider() function.
+    @param showAtStartup
+        Should be true if startup tips are shown, false otherwise. This is
+        used as the initial value for "Show tips at startup" checkbox which is
+        shown in the tips dialog.
+
+    @see @ref overview_tips
+
+    @header{wx/tipdlg.h}
 */
-wxTipProvider * wxCreateFileTipProvider(const wxString& filename,
-                                        size_t currentTip);
+bool wxShowTip(wxWindow *parent,
+               wxTipProvider *tipProvider,
+               bool showAtStartup = true);
+
+//@}