Fix function wxControlBase::DoEllipsizeSingleLine to really make sure that the ellipsized string takes less pixels than maxFinalWidthPx.

Add comments to explain in more details what the function does and in particular the valid ranges of all internal variables; fix in that regard both the code of both wxELLIPSIZE_START, wxELLIPSIZE_MIDDLE and wxELLIPSIZE_END.
Add more asserts to check the valid ranges and turn a couple of time-expensive checks in level-2 asserts.
Add a test unit for the wxControl::Ellipsize function.
Fix minor details in the docs of wxControl::Ellipsize.
Closes #11567.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@63660 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/control.h

@@ -96,6 +96,10 @@ public:
     /**
         Replaces parts of the @a label string with ellipsis, if needed, so
         that it doesn't exceed @a maxWidth.
+        
+        Note that this functions is guaranteed to always returns a string
+        whose rendering on the given DC takes less than @a maxWidth pixels
+        in horizontal.
 
         @param label
             The string to ellipsize
@@ -103,11 +107,15 @@ public:
             The DC used to retrieve the character widths through the
             wxDC::GetPartialTextExtents() function.
         @param mode
-            The ellipsization modes. See ::wxEllipsizeMode.
+            The ellipsization mode. This is the setting which determines
+            which part of the string should be replaced by the ellipsis.
+            See ::wxEllipsizeMode enumeration values for more info.
         @param maxWidth
             The maximum width of the returned string in pixels.
+            This argument determines how much characters of the string need to
+            be removed (and replaced by ellipsis).
         @param flags
-            One or more of the ::wxEllipsize
+            One or more of the ::wxEllipsizeFlags enumeration values combined.
     */
     static wxString Ellipsize(const wxString& label, const wxDC& dc,
                               wxEllipsizeMode mode, int maxWidth,