Trying to make wxString readable again

[wxWidgets.git] / interface / caret.h

diff --git a/interface/caret.h b/interface/caret.h
index 4e8a9c177dc54baf944de6aaacd3eae75b0f5fd6..4182c41f60b7eb7baf05b2d543e5c04f320d1018 100644 (file)
--- a/interface/caret.h
+++ b/interface/caret.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        caret.h
-// Purpose:     documentation for wxCaret class
+// Purpose:     interface of wxCaret
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -11,106 +11,90 @@
     @wxheader{caret.h}
 
     A caret is a blinking cursor showing the position where the typed text will
-    appear. The text controls usually have a caret but wxCaret class also allows
-    to use a caret in other windows.
+    appear. Text controls usually have their own caret but wxCaret provides a
+    way to use a caret in other windows.
 
-    Currently, the caret appears as a rectangle of the given size. In the future,
-    it will be possible to specify a bitmap to be used for the caret shape.
+    Currently, the caret appears as a rectangle of the given size. In the
+    future, it will be possible to specify a bitmap to be used for the caret
+    shape.
 
     A caret is always associated with a window and the current caret can be
-    retrieved using wxWindow::GetCaret. The same caret
-    can't be reused in two different windows.
+    retrieved using wxWindow::GetCaret(). The same caret can't be reused in two
+    different windows.
 
     @library{wxcore}
     @category{misc}
-
-    @seealso
-    wxCaret::GetBlinkTime
 */
 class wxCaret
 {
 public:
-    //@{
     /**
-        Create the caret of given (in pixels) width and height and associates it
-        with the given window.
+        Default constructor.
     */
     wxCaret();
+
+    //@{
+    /**
+        Creates a caret with the given size (in pixels) and associates it with
+        the @a window.
+    */
     wxCaret(wxWindow* window, int width, int height);
     wxCaret(wxWindowBase* window, const wxSize& size);
     //@}
 
     //@{
     /**
-        Create the caret of given (in pixels) width and height and associates it
-        with the given window (same as constructor).
+        Creates a caret with the given size (in pixels) and associates it with
+        the @a window (same as the equivalent constructors).
     */
     bool Create(wxWindowBase* window, int width, int height);
     bool Create(wxWindowBase* window, const wxSize& size);
     //@}
 
     /**
-        Returns the blink time which is measured in milliseconds and is the time elapsed
-        between 2 inversions of the caret (blink time of the caret is the same
-        for all carets, so this functions is static).
+        Returns the blink time which is measured in milliseconds and is the
+        time elapsed between 2 inversions of the caret (blink time of the caret
+        is the same for all carets, so this functions is static).
     */
     static int GetBlinkTime();
 
     //@{
     /**
         Get the caret position (in pixels).
-        
-        @b GetPosition()
-        
-        Returns a Wx::Point
-        
-        @b GetPositionXY()
-        
-        Returns a 2-element list
-         @c ( x, y )
     */
-    void GetPosition(int* x, int* y);
-    wxPoint GetPosition();
+    void GetPosition(int* x, int* y) const;
+    const wxPoint GetPosition() const;
     //@}
 
     //@{
     /**
         Get the caret size.
-        
-        @b GetSize()
-        
-        Returns a Wx::Size
-        
-        @b GetSizeWH()
-        
-        Returns a 2-element list
-         @c ( width, height )
     */
-    void GetSize(int* width, int* height);
-    wxSize GetSize();
+    void GetSize(int* width, int* height) const;
+    const wxSize  GetSize() const;
     //@}
 
     /**
         Get the window the caret is associated with.
     */
-    wxWindow* GetWindow();
+    wxWindow* GetWindow() const;
 
     /**
-        Same as wxCaret::Show(@false).
+        Hides the caret, same as Show(@false).
     */
     void Hide();
 
     /**
         Returns @true if the caret was created successfully.
     */
-    bool IsOk();
+    bool IsOk() const;
 
     /**
         Returns @true if the caret is visible and @false if it is permanently
-        hidden (if it is is blinking and not shown currently but will be after the
-        next blink, this method still returns @true).
+        hidden (if it is is blinking and not shown currently but will be after
+        the next blink, this method still returns @true).
     */
-    bool IsVisible();
+    bool IsVisible() const;
 
     //@{
     /**
@@ -122,11 +106,11 @@ public:
 
     /**
         Sets the blink time for all the carets.
-        
-        @remarks Under Windows, this function will change the blink time for all
-                 carets permanently (until the next time it is called),
-                 even for the carets in other applications.
-        
+
+        @warning Under Windows, this function will change the blink time for
+                 all carets permanently (until the next time it is called),
+                 even for carets in other applications.
+
         @see GetBlinkTime()
     */
     static void SetBlinkTime(int milliseconds);
@@ -140,8 +124,9 @@ public:
     //@}
 
     /**
-        Shows or hides the caret. Notice that if the caret was hidden N times, it
-        must be shown N times as well to reappear on the screen.
+        Shows or hides the caret. Notice that if the caret was hidden N times,
+        it must be shown N times as well to reappear on the screen.
     */
     void Show(bool show = true);
 };
+