From 621d922ffd5b3294ac8dbe6cbd27f56ed7916217 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Wed, 9 Mar 2011 10:07:58 +0000
Subject: [PATCH] Corrections to wxTextCtrl::HitTest() documentation.

Fix the signature of the overload returning row and column which got corrupted
during transition to Doxygen and document the overload returning the position
as well. Also document all the parameters.

Closes #12954.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@67159 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 interface/wx/textctrl.h | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/interface/wx/textctrl.h b/interface/wx/textctrl.h
index 35b1e04456..de93cdb340 100644
--- a/interface/wx/textctrl.h
+++ b/interface/wx/textctrl.h
@@ -1226,26 +1226,47 @@ public:
     */
     virtual bool GetStyle(long position, wxTextAttr& style);
 
+    //@{
     /**
         This function finds the character at the specified position expressed
         in pixels.
 
+        The two overloads of this method allow to find either the position of
+        the character, as an index into the text control contents, or its row
+        and column.
+
         If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
-        character closest to this position are returned in the @a col and @a
-        row parameters (unless the pointers are @NULL which is allowed).
-        Please note that this function is currently only implemented in wxUniv, wxMSW
-        and wxGTK2 ports.
+        character closest to this position are returned, otherwise the output
+        parameters are not modified.
+
+        Please note that this function is currently only implemented in wxUniv,
+        wxMSW and wxGTK2 ports and always returns @c wxTE_HT_UNKNOWN in the
+        other ports.
 
         @beginWxPerlOnly
         In wxPerl this function takes only the @a pt argument and
         returns a 3-element list (result, col, row).
         @endWxPerlOnly
 
+        @param pt
+            The position of the point to check, in window device coordinates.
+        @param col
+            Receives the column of the character at the given position. May be
+            @NULL.
+        @param row
+            Receives the row of the character at the given position. May be
+            @NULL.
+        @param pos
+            Receives the position of the character at the given position. May
+            be @NULL.
+
         @see PositionToXY(), XYToPosition()
     */
+    wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const;
     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
-                                    wxTextCoord col,
-                                    wxTextCoord row) const;
+                                    wxTextCoord *col,
+                                    wxTextCoord *row) const;
+    //@}
 
     /**
         Returns @true if the text has been modified by user.
-- 
2.45.2