# HG changeset patch
# User Pantxo Diribarne <pantxo.diribarne@gmail.com>
# Date 1487250269 -3600
#      Thu Feb 16 14:04:29 2017 +0100
# Node ID 13d33cb0a02a163b9b372d6f0e2bb66eea4b4570
# Parent  e2e182a8e6996bfaf63aa8a3bca617a23c5d651b
New mechanism to deprecate graphics properties (bug #50327)

* genprop.awk (emit_get_accessor, emit_declarations): new flag "d" to mark 
   deprecated properties. Emit warning in generated accessors
* graphics.in.h (figure::preoperties, axes::properties): remove FIXME about some
   deprecated properties and mark them deprecated for genprop.awk
* deprecate-props.tst: new test file to be fed with properties that where 
   deprecated in a given version

diff -r e2e182a8e699 -r 13d33cb0a02a NEWS
--- a/NEWS	Wed Feb 15 13:10:39 2017 +0100
+++ b/NEWS	Thu Feb 16 14:04:29 2017 +0100
@@ -31,6 +31,23 @@
       Function             | Replacement
       ---------------------|------------------
 
+ ** Deprecated graphics properties.
+
+    The following properties have been deprecated in Octave 4.4 and will
+    be removed from Octave 4.8 (or whatever version is the second major
+    release after 4.4):
+
+      Object               | Property
+      ---------------------|------------------
+      figure               | doublebuffer
+                           | mincolormap
+                           | wvisual
+                           | wvisualmode
+                           | xdisplay
+                           | xvisual
+                           | xvisualmode
+      axes                 | drawmode
+      annotation           | edgecolor ("rectangle")
 
  ** The following functions were deprecated in Octave 4.0 and have been
     removed from Octave 4.4.
diff -r e2e182a8e699 -r 13d33cb0a02a libinterp/corefcn/graphics.in.h
--- a/libinterp/corefcn/graphics.in.h	Wed Feb 15 13:10:39 2017 +0100
+++ b/libinterp/corefcn/graphics.in.h	Thu Feb 16 14:04:29 2017 +0100
@@ -3471,11 +3471,6 @@
 
     // See the genprops.awk script for an explanation of the
     // properties declarations.
-    // FIXME: Several properties have been deleted from Matlab.
-    //        We should either immediately remove them or figure out a way
-    //        to deprecate them for a release or two.
-    // Obsolete properties: doublebuffer, mincolormap, wvisual, wvisualmode,
-    // xdisplay, xvisual, xvisualmode
 
     // Programming note: Keep property list sorted if new ones are added.
 
@@ -3548,13 +3543,13 @@
       // Obsolete properties: doublebuffer, mincolormap, wvisual, wvisualmode,
       //                      xdisplay, xvisual, xvisualmode
       // FIXME: Remove in version 4.6
-      bool_property doublebuffer h , "on"
-      double_property mincolormap h , 64
-      string_property wvisual hm , ""
-      radio_property wvisualmode h , "{auto}|manual"
-      string_property xdisplay h , ""
-      string_property xvisual hm , ""
-      radio_property xvisualmode h , "{auto}|manual"
+      bool_property doublebuffer hd , "on"
+      double_property mincolormap hd , 64
+      string_property wvisual hmd , ""
+      radio_property wvisualmode hd , "{auto}|manual"
+      string_property xdisplay hd , ""
+      string_property xvisual hmd , ""
+      radio_property xvisualmode hd , "{auto}|manual"
     END_PROPERTIES
 
   protected:
@@ -3913,11 +3908,6 @@
     // See the genprops.awk script for an explanation of the
     // properties declarations.
 
-    // FIXME: Several properties have been deleted from Matlab.
-    //        We should either immediately remove them or figure out a way
-    //        to deprecate them for a release or two.
-    // Obsolete properties: drawmode
-
     // Programming note: Keep property list sorted if new ones are added.
 
     BEGIN_PROPERTIES (axes)
@@ -3944,7 +3934,7 @@
       array_property currentpoint , Matrix (2, 3, 0.0)
       row_vector_property dataaspectratio mu , Matrix (1, 3, 1.0)
       radio_property dataaspectratiomode u , "{auto}|manual"
-      radio_property drawmode , "{normal}|fast"
+      radio_property drawmode hd , "{normal}|fast"
       radio_property fontangle u , "{normal}|italic"
       string_property fontname u , OCTAVE_DEFAULT_FONTNAME
       double_property fontsize u , 10
diff -r e2e182a8e699 -r 13d33cb0a02a libinterp/genprops.awk
--- a/libinterp/genprops.awk	Wed Feb 15 13:10:39 2017 +0100
+++ b/libinterp/genprops.awk	Thu Feb 16 14:04:29 2017 +0100
@@ -55,7 +55,7 @@
 ##   }
 ##
 ## If present, the QUALIFIERS string may include any of the characters
-## g, G, m, s, S, o, O, h, which have the following meanings:
+## g, G, m, s, S, o, O, h, d which have the following meanings:
 ##
 ##   g:  There is a custom inline definition for the get function,
 ##       so we don't emit one.
@@ -69,6 +69,8 @@
 ##   S:  There is a custom extern definition for the type-specific set
 ##       function, so we emit only the declaration.
 ##
+##   d:  The property is deprecated and a warning is emitted when accessing it.
+##
 ################################################################################
 ##   'o','O','a' are currently not processed.  They are commented out in code.
 ################################################################################
@@ -144,7 +146,9 @@
 {
   printf ("  %s get_%s (void) const", rtype, name[i]);
 
-  if (emit_get[i] == "definition")
+  if (emit_get[i] == "definition" && deprecated[i])
+    printf ("\n{\n  warning_with_id (\"Octave:deprecated-property\",\"'%s' is deprecated and will be removed from a future version of Octave\");\n  return %s.%s ();\n}\n", name[i], name[i], faccess);
+  else if (emit_get[i] == "definition")
     printf (" { return %s.%s (); }\n", name[i], faccess);
   else
     printf (";\n");
@@ -388,6 +392,8 @@
           printf ("            set_%smode (\"manual\");\n", name[i]);
         if (updater[i])
           printf ("            update_%s ();\n", name[i]);
+        if (deprecated[i])
+          printf ("            warning_with_id (\"Octave:deprecated-property\",\"'%s' is deprecated and will be removed from a future version of Octave\");\n", name[i]);
         if (limits[i])
           printf ("            update_axis_limits (\"%s\");\n", name[i]);
         if (has_builtin_listeners)
@@ -760,6 +766,7 @@
     emit_set[idx] = "definition";
     defval[idx] = "";
     updater[idx] = "";
+    deprecated[idx] = 0;
     factory[idx] = 1;
 ##    if (type[idx] == "octave_value")
 ##      emit_ov_set[idx] = "";
@@ -816,6 +823,10 @@
         if (index (quals, "U"))
           updater[idx] = "extern";
 
+        ## The property is deprecated 
+        if (index (quals, "d"))
+          deprecated[idx] = 1;
+
         ## There is not factory default value
         if (index (quals, "f"))
           factory[idx] = 0;
diff -r e2e182a8e699 -r 13d33cb0a02a test/deprecate-props.tst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/deprecate-props.tst	Thu Feb 16 14:04:29 2017 +0100
@@ -0,0 +1,100 @@
+## Copyright (C) 2017 Pantxo Diribarne
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+%% Put here graphics properties that should be removed or for which some
+%% values (radio strings only) should not be accepted anymore in a given
+%% future version. Don't forget to add a note in the NEWS file.
+
+%!function testprop (h, prop, vrs, val = [])
+%!  vrsmax = strsplit (vrs, ".");
+%!  vrscur = strsplit (version (), ".");
+%!  if (num2str (vrsmax{1}) < num2str (vrscur{1}) ||
+%!      num2str (vrsmax{2}) < num2str (vrscur{2}))
+%!    if (isempty (val) && isprop (h, prop))
+%!      error ("Please remove %s property %s", get (h, "type"), prop)
+%!    elseif (! isempty (val) && ! isempty (strfind (val, set (h, prop))))
+%!      error ("Please remove '%s' from allowed values for %s property %s",
+%!             val, get (h, "type"), prop)
+%!    endif
+%!  endif
+%!endfunction
+
+%% patch/surface "normalmode" deprecated in 4.2, remove from 4.5.+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   hp = patch ();
+%!   testprop (hp, "normalmode", "4.4")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
+
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   hs = surface ();
+%!   testprop (hs, "normalmode", "4.4")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
+
+%% axes, "zero" value for "x/yaxislocation" deprecated in 4.2, remove from 4.5.+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   ha = axes ();
+%!   testprop (ha, "xaxislocation", "4.4", "zero")
+%!   testprop (ha, "yaxislocation", "4.4", "zero")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
+
+%% annotation rectangle "edgecolor" deprecated in 4.4, remove from 4.7.+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   ha = annotation ("rectangle");
+%!   testprop (ha, "edgecolor", "4.6")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
+
+%% figure "doublebuffer, mincolormap, wvisual, wvisualmode, xdisplay,
+%% xvisual, xvisualmode" deprecated in 4.4, remove from 4.7.+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   testprop (hf, "doublebuffer", "4.6")
+%!   testprop (hf, "mincolormap", "4.6")
+%!   testprop (hf, "wvisual", "4.6")
+%!   testprop (hf, "wvisualmode", "4.6")
+%!   testprop (hf, "xdisplay", "4.6")
+%!   testprop (hf, "xvisual", "4.6")
+%!   testprop (hf, "xvisualmode", "4.6")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
+
+%% axes "drawmode" deprecated in 4.4, remove from 4.7.+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   hax = axes ();
+%!   testprop (hax, "drawmode", "4.6")
+%! unwind_protect_cleanup
+%!   close (hf)
+%! end_unwind_protect
