Merge branch 'point-ctor-round-document'

Document change in wxPoint(wxRealPoint) behaviour and provide
alternatives.

See #26100.

include/wx/gdicmn.h

@@ -614,7 +614,18 @@ public:
     wxPoint(int xx, int yy) : x(xx), y(yy) { }
     wxPoint(const wxRealPoint& pt) : x(wxRound(pt.x)), y(wxRound(pt.y)) { }
 
-    // no copy ctor or assignment operator - the defaults are ok
+    static wxPoint Round(const wxRealPoint& pt)
+    {
+        return wxPoint(pt);
+    }
+
+    static wxPoint Truncate(const wxRealPoint& pt)
+    {
+        return wxPoint(static_cast<int>(pt.x), static_cast<int>(pt.y));
+    }
+
+    wxPoint(const wxPoint& pt) = default;
+    wxPoint& operator=(const wxPoint& pt) = default;
 
     //assignment operators
     wxPoint& operator+=(const wxPoint& p) { x += p.x; y += p.y; return *this; }

interface/wx/gdicmn.h

@@ -700,18 +700,34 @@ public:
         Converts the given wxRealPoint (with floating point coordinates) to a
         wxPoint instance.
 
-        Notice that this truncates the floating point values of @a pt
-        components, if you want to round them instead you need to do it
-        manually, e.g.
-        @code
-            #include <wx/math.h>    // for wxRound()
-
-            wxRealPoint rp = ...;
-            wxPoint p(wxRound(rp.x), wxRound(rp.y));
-        @endcode
+        Notice that since v3.1.2 the behaviour of this constructor has changed
+        to round the floating point values of @a pt components, if you want to
+        truncate them instead, please use wxPoint::Truncate().
     */
     wxPoint(const wxRealPoint& pt);
 
+    /**
+        Creates a wxPoint by rounding the coordinates of the given
+        wxRealPoint.
+
+        This is equivalent to using the constructor taking wxRealPoint but is
+        more explicit about the fact that rounding is performed.
+
+        @since 3.3.2
+    */
+    static wxPoint Round(const wxRealPoint& pt);
+
+    /**
+        Creates a wxPoint by truncating the coordinates of the given
+        wxRealPoint.
+
+        This is similar to Round() but instead of rounding the coordinates,
+        they are simply truncated to integers.
+
+        @since 3.3.2
+    */
+    static wxPoint Truncate(const wxRealPoint& pt);
+
     /**
         @name Miscellaneous operators
 

tests/geometry/point.cpp

@@ -19,6 +19,21 @@
 
 #include "wx/math.h"
 
+TEST_CASE("wxPoint::Create", "[point]")
+{
+    const wxRealPoint rp(1.7, 2.3);
+
+    wxPoint p(rp);
+    CHECK( p.x == 2 );
+    CHECK( p.y == 2 );
+
+    CHECK( wxPoint::Round(rp) == p );
+
+    p = wxPoint::Truncate(rp);
+    CHECK( p.x == 1 );
+    CHECK( p.y == 2 );
+}
+
 TEST_CASE("wxPoint::Operators", "[point]")
 {
     wxPoint p1(1,2);