Merge branch 'peninfo'

Add wxPenInfo and wxGraphicsPenInfo which allows to specify fractional
pen widths when using wxGraphicsContext.

Closes #17087.

Closes https://github.com/wxWidgets/wxWidgets/pull/472

interface/wx/graphics.h

@@ -253,7 +253,7 @@ enum wxInterpolationQuality
     /** default interpolation, based on type of context, in general medium quality */
     wxINTERPOLATION_DEFAULT,
     /** no interpolation */
-    wxINTERPOLATION_NONE, 
+    wxINTERPOLATION_NONE,
     /** fast interpolation, suited for interactivity */
     wxINTERPOLATION_FAST,
     /** better quality */
@@ -331,7 +331,7 @@ public:
     wxImage ConvertToImage() const;
 
     /**
-        Return the pointer to the native bitmap data. (CGImageRef for Core Graphics, 
+        Return the pointer to the native bitmap data. (CGImageRef for Core Graphics,
         cairo_surface_t for Cairo, Bitmap* for GDI+.)
 
         @since 2.9.4
@@ -677,8 +677,19 @@ public:
 
     /**
         Creates a native pen from a wxPen.
+
+        Prefer to use the overload taking wxGraphicsPenInfo unless you already
+        have a wxPen as constructing one only to pass it to this method is
+        wasteful.
     */
-    virtual wxGraphicsPen CreatePen(const wxPen& pen) const;
+    wxGraphicsPen CreatePen(const wxPen& pen) const;
+
+    /**
+        Creates a native pen from a wxGraphicsPenInfo.
+
+        @since 3.1.1
+    */
+    wxGraphicsPen CreatePen(const wxGraphicsPenInfo& info) const;
 
     /**
         Sets the pen used for stroking.
@@ -1415,9 +1426,11 @@ public:
     virtual wxGraphicsPath CreatePath() = 0;
 
     /**
-        Creates a native pen from a wxPen.
+        Creates a native pen from its description.
+
+        @since 3.1.1
     */
-    virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0;
+    virtual wxGraphicsPen CreatePen(const wxGraphicsPenInfo& info) = 0;
 
     /**
         Creates a native brush with a radial gradient.
@@ -1528,6 +1541,51 @@ public:
 
 
 
+/**
+    @class wxGraphicsPenInfo
+
+    This class is a helper used for wxGraphicsPen creation using named parameter
+    idiom: it allows to specify various wxGraphicsPen attributes using the chained
+    calls to its clearly named methods instead of passing them in the fixed
+    order to wxGraphicsPen constructors.
+
+    Typically you would use wxGraphicsPenInfo with a wxGraphicsContext, e.g. to
+    start drawing with a dotted blue pen slightly wider than normal you could
+    write the following:
+    @code
+    wxGraphicsContext ctx = wxGraphicsContext::Create(dc);
+
+    ctx.SetPen(wxGraphicsPenInfo(*wxBLUE).Width(1.25).Style(wxPENSTYLE_DOT));
+    @endcode
+
+    @since 3.1.1
+ */
+class wxGraphicsPenInfo
+{
+public:
+    explicit wxGraphicsPenInfo(const wxColour& colour = wxColour(),
+                               wxDouble width = 1.0,
+                               wxPenStyle style = wxPENSTYLE_SOLID);
+
+    wxGraphicsPenInfo& Colour(const wxColour& col);
+
+    wxGraphicsPenInfo& Width(wxDouble width);
+
+    wxGraphicsPenInfo& Style(wxPenStyle style);
+
+    wxGraphicsPenInfo& Style(wxPenStyle style);
+
+    wxGraphicsPenInfo& Stipple(const wxBitmap& stipple);
+
+    wxGraphicsPenInfo& Dashes(int nb_dashes, const wxDash *dash);
+
+    wxGraphicsPenInfo& Join(wxPenJoin join);
+
+    wxGraphicsPenInfo& Cap(wxPenCap cap);
+};
+
+
+
 /**
     @class wxGraphicsPen
 

interface/wx/pen.h

@@ -101,6 +101,48 @@ enum wxPenCap
 
 
 
+/**
+    @class wxPenInfo
+
+    This class is a helper used for wxPen creation using named parameter
+    idiom: it allows to specify various wxPen attributes using the chained
+    calls to its clearly named methods instead of passing them in the fixed
+    order to wxPen constructors.
+
+    For instance, to create a dotted blue pen with the given join style you
+    could do
+    @code
+    wxPen pen(wxPenInfo(*wxBLUE).Style(wxPENSTYLE_DOT).Join(wxJOIN_BEVEL));
+    @endcode
+
+    @since 3.1.1
+ */
+class wxPenInfo
+{
+public:
+    explicit wxPenInfo(const wxColour& colour = wxColour(),
+                       int width = 1,
+                       wxPenStyle style = wxPENSTYLE_SOLID);
+
+    wxPenInfo& Colour(const wxColour& col);
+
+    wxPenInfo& Width(int width);
+
+    wxPenInfo& Style(wxPenStyle style);
+
+    wxPenInfo& Style(wxPenStyle style);
+
+    wxPenInfo& Stipple(const wxBitmap& stipple);
+
+    wxPenInfo& Dashes(int nb_dashes, const wxDash *dash);
+
+    wxPenInfo& Join(wxPenJoin join);
+
+    wxPenInfo& Cap(wxPenCap cap);
+};
+
+
+
 /**
     @class wxPen
 
@@ -157,6 +199,11 @@ public:
     */
     wxPen();
 
+    /**
+        Creates a pen object using the specified pen description.
+    */
+    wxPen(const wxPenInfo& info);
+
     /**
         Constructs a pen from a colour object, pen width and style.