Merge branch 'col-dialog-current'

Add events for current colour change in wxColourDialog and
wxColourPickerCtrl.

See https://github.com/wxWidgets/wxWidgets/pull/1301

interface/wx/clrpicker.h

@@ -44,7 +44,20 @@ wxEventType wxEVT_COLOURPICKER_CHANGED;
            The user changed the colour selected in the control either using the
            button or using text control (see @c wxCLRP_USE_TEXTCTRL; note that
            in this case the event is fired only if the user’s input is valid,
-           i.e. recognizable).
+           i.e. recognizable). When using a popup dialog for changing the
+           colour, this event is sent only when the changes in the dialog are
+           accepted by the user, unlike @c EVT_COLOURPICKER_CURRENT_CHANGED.
+    @event{EVT_COLOURPICKER_CURRENT_CHANGED(id, func)}
+           The user changed the currently selected colour in the dialog
+           associated with the control. This event is sent immediately when the
+           selection changes and you must also handle @c EVT_COLOUR_CANCELLED
+           to revert to the previously selected colour if the selection ends up
+           not being accepted. This event is new since wxWidgets 3.1.3 and
+           currently is only implemented in wxMSW.
+    @event{EVT_COLOURPICKER_DIALOG_CANCELLED(id, func)}
+           The user cancelled the colour dialog associated with the control,
+           i.e. closed it without accepting the selection. This event is new
+           since wxWidgets 3.1.3 and currently is only implemented in wxMSW.
     @endEventTable
 
     @library{wxcore}
@@ -124,6 +137,15 @@ public:
     @beginEventTable{wxColourPickerEvent}
     @event{EVT_COLOURPICKER_CHANGED(id, func)}
            Generated whenever the selected colour changes.
+    @event{EVT_COLOURPICKER_CURRENT_CHANGED(id, func)}
+           Generated whenever the currently selected colour in the dialog shown
+           by the picker changes. This event is new since wxWidgets 3.1.3 and
+           currently is only implemented in wxMSW.
+    @event{EVT_COLOURPICKER_DIALOG_CANCELLED(id, func)}
+           Generated when the user cancels the colour dialog associated with
+           the control, i.e. closes it without accepting the selection. This
+           event is new since wxWidgets 3.1.3 and currently is only implemented
+           in wxMSW.
     @endEventTable
 
     @library{wxcore}

interface/wx/colordlg.h

@@ -10,11 +10,46 @@
 
     This class represents the colour chooser dialog.
 
+    Starting from wxWidgets 3.1.3 and currently in the MSW port only, this
+    dialog generates wxEVT_COLOUR_CHANGED events while it is being shown, i.e.
+    from inside its ShowModal() method, that notify the program about the
+    change of the currently selected colour and allow it to e.g. preview the
+    effect of selecting this colour. Note that if you react to this event, you
+    should also correctly revert to the previously selected colour if the
+    dialog is cancelled by the user.
+
+    Example of using this class with dynamic feedback for the selected colour:
+    @code
+        // Some function for redrawing using the given colour. Ideally, it
+        // shouldn't do anything if the colour is the same as the one used
+        // before.
+        void Redraw(const wxColour& colour);
+
+        wxColourData data;
+        data.SetColour(initialColourToUse);
+        wxColourData dlg(this, &data);
+        dlg.Bind(wxEVT_COLOUR_CHANGED, [](wxColourDialogEvent& event) {
+                    Redraw(event.GetColour());
+                 });
+        if ( dlg.ShowModal() == wxID_OK ) {
+            // Colour did change.
+        } else {
+            // Colour didn't change.
+        }
+
+        // This call is unnecessary under platforms generating
+        // wxEVT_COLOUR_CHANGED if the dialog was accepted and unnecessary
+        // under the platforms not generating this event if it was cancelled,
+        // so we could check for the different cases explicitly to avoid it,
+        // but it's simpler to just always call it.
+        Redraw(data.GetColour());
+    @endcode
+
     @library{wxcore}
     @category{cmndlg}
 
     @see @ref overview_cmndlg_colour, wxColour, wxColourData,
-         wxGetColourFromUser()
+          wxColourDialogEvent, wxGetColourFromUser()
 */
 class wxColourDialog : public wxDialog
 {
@@ -55,7 +90,30 @@ public:
     virtual int ShowModal();
 };
 
+/**
+    This event class is used for the events generated by wxColourDialog.
 
+    @beginEventTable{wxColourPickerEvent}
+    @event{EVT_COLOUR_CHANGED(id, func)}
+           Generated whenever the currently selected colour in the dialog
+           changes. This event is currently only implemented in wxMSW.
+    @endEventTable
+
+    @library{wxcore}
+    @category{events}
+
+    @see wxColourDialog
+
+    @since 3.1.3
+ */
+class wxColourDialogEvent : public wxCommandEvent
+{
+public:
+    /**
+        Retrieve the colour the user has just selected.
+    */
+    wxColour GetColour() const;
+};
 
 // ============================================================================
 // Global functions/macros