changeset 18723:e68788478aa1

linkprop.m: Overhaul function for performance and Matlab compatibility. * NEWS: Announce changes in linkprop behavior. * linkprop.m: Redo docstring. Add more input validation. When linking, set property values to be that of the first object in the list (missing Matlab compatibility). Use onCleanup instead of an hggroup in order for 'clear hlink' command to correctly unlink properties. For performance, avoid for loops in update_prop and use set() with multiple handles. Add %!demo, %!test, and %!error code to verify function.
author Rik <rik@octave.org>
date Sat, 03 May 2014 16:51:00 -0700
parents f8203daed9d4
children 87fafe6d05d3
files NEWS scripts/plot/util/linkprop.m
diffstat 2 files changed, 112 insertions(+), 36 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Fri May 02 14:45:22 2014 -0700
+++ b/NEWS	Sat May 03 16:51:00 2014 -0700
@@ -24,6 +24,12 @@
     There is still one difference:  Matlab switches to '%e' and Octave
     is currently switching to '%g'.
 
+ ** linkprop has been completely re-coded for performance and Matlab
+    compatibility.  It now returns a linkprop object which must be stored
+    in a variable for as long as the graphic objects should remain linked.
+    To unlink properties use 'clear hlink' where hlink is the variable
+    containing the linkprop object.
+
  ** Other new functions added in 4.2:
 
       dir_in_loadpath
--- a/scripts/plot/util/linkprop.m	Fri May 02 14:45:22 2014 -0700
+++ b/scripts/plot/util/linkprop.m	Sat May 03 16:51:00 2014 -0700
@@ -17,14 +17,24 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
-## @deftypefnx {Function File} {@var{hlink} =} linkprop (@var{h}, @{@var{prop1}, @var{prop2}, @dots{}@})
-## Link graphics object properties, such that a change in one is
-## propagated to the others.
+## @deftypefn  {Function File} {@var{hlink} =} linkprop (@var{h}, "@var{prop}")
+## @deftypefnx {Function File} {@var{hlink} =} linkprop (@var{h}, @{"@var{prop1}", "@var{prop2}", @dots{}@})
+## Link graphic object properties, such that a change in one is propagated to
+## the others.
+##
+## The input @var{h} is a vector of graphic handles to link.
 ##
-## @var{prop} can be a string for a single property, or a cell array of strings
-## for multiple properties.  @var{h} is an array of graphics handles which
-## will have their properties linked.
+## @var{prop} may be a string when linking a single property, or a cell array
+## of strings for multiple properties.  During the linking process all
+## properties in @var{prop} will initially be set to the values that exist on
+## the first object in the list @var{h}.
+##
+## The function returns @var{hlink} which is a special object describing the
+## link.  As long as the reference @var{hlink} exists the link between graphic
+## objects will be active.  This means that @var{hlink} must be preserved in
+## a workspace variable, a global variable, or otherwise stored using a
+## function such as @code{setappdata}, @code{guidata}.  To unlink properties,
+## execute @code{clear @var{hlink}}.
 ##
 ## An example of the use of @code{linkprop} is
 ##
@@ -41,62 +51,122 @@
 ## @end group
 ## @end example
 ##
+## @seealso{linkaxes}
 ## @end deftypefn
 
 function hlink = linkprop (h, prop)
+
+  if (nargin != 2)
+    print_usage ();
+  endif
+
+  if (numel (h) < 2)
+    error ("linkprop: H must contain at least 2 handles");
+  elseif (! all (ishandle (h(:))))
+    error ("linkprop: invalid graphic handle in input H");
+  endif
+
   if (ischar (prop))
     prop = {prop};
-  elseif (!iscellstr (prop))
-    error ("linkprop: properties must be a string or cell string array");
+  elseif (! iscellstr (prop))
+    error ("linkprop: PROP must be a string or cell string array");
   endif
 
+  h = h(:)';  # set() prefers column vectors
+  ## Match all objects to the first one in the list before linking 
+  for j = 1 : numel (prop)
+    set (h(2:end), prop{j}, get (h(1), prop{j})); 
+  endfor
+
+  ## Add listeners to all objects
   for i = 1 : numel (h)
     for j = 1 : numel (prop)
-      addlistener (h(i), prop{j}, {@update_prop, h, prop{j}});
+      addlistener (h(i), prop{j},
+                   {@update_prop, [h(1:i-1),h(i+1:end)], prop{j}});
     endfor
   endfor
 
-  ## This should be an object that when destroyed removes the links
-  ## The below is not quite right. As when you call "clear hlink" the
-  ## hggroup continues to exist.
-  hlink = hggroup ();
-  set (hlink, "deletefcn", {@delete_prop, h, prop});
+  hlink = onCleanup (@() delete_linkprop (h, prop));
+
 endfunction
 
-function update_prop (h, d, hlist, prop)
+function update_prop (h, ~, hlist, prop)
   persistent recursion = false;
 
   ## Don't allow recursion
   if (! recursion)
     unwind_protect
       recursion = true;
-      val = get (h, prop);
-      for hh = hlist(:)'
-        if (hh != h)
-          oldval = get (hh, prop);
-          if (! isequal (val, oldval))
-            set (hh, prop, val);
-          endif
-        endif
-      endfor
+      set (hlist(ishandle (hlist)), prop, get (h, prop));
     unwind_protect_cleanup
       recursion = false;
     end_unwind_protect
   endif
 endfunction
 
-function delete_prop (h, d, hlist, prop)
-  ## FIXME. Actually need to delete the linked properties.
-  ## However, only warn if the graphics objects aren't being deleted.
-  warn = false;
-  for h = hlist(:)'
-    if (ishandle (h) && !strcmpi (get (h, "beingdeleted"), "on"))
-      warn = true;
-      break;
+function delete_linkprop (hlist, prop)
+
+  for i = 1 : numel (hlist)
+    if (ishandle (hlist(i)))
+      for j = 1 : numel (prop)
+        dellistener (hlist(i), prop{j}),
+      endfor
     endif
   endfor
-  if (warn)
-    warning ("linkprop: can not remove linked properties");
-  endif
+
 endfunction
 
+
+%!demo
+%! clf;
+%! x = 0:0.1:10;
+%! subplot (1,2,1);
+%! h1 = plot (x, sin (x), "r");
+%! subplot (1,2,2);
+%! h2 = plot (x, cos (x), "b");
+%! input ("Type <RETURN> to link plots");
+%! hlink = linkprop ([h1, h2], {"color", "linestyle"});
+%! input ("Type <RETURN> to change color");
+%! set (h1, "color", "green");
+%! input ("Type <RETURN> to change linestyle");
+%! set (h2, "linestyle", "--");
+
+%!test
+%! hf1 = figure ("visible", "off");
+%! hl1 = plot (1:10, "or");
+%! hf2 = figure ("visible", "off");
+%! hl2 = plot (1:10, "-*g");
+%! hf3 = figure ("visible", "off");
+%! hl3 = plot (1:10, "-xb");
+%! unwind_protect
+%!   hlink = linkprop ([hl1, hl2, hl3], {"color", "linestyle"});
+%!   ## Test initial values taken from first object in list
+%!   assert (get (hl2, "color"), [1 0 0]);
+%!   assert (get (hl3, "linestyle"), "none");
+%!   ## Test linking
+%!   set (hl2, "color", "b");
+%!   assert (get (hl1, "color"), [0 0 1]);
+%!   assert (get (hl3, "color"), [0 0 1]);
+%!   set (hl3, "linestyle", "--");
+%!   assert (get (hl1, "linestyle"), "--");
+%!   assert (get (hl2, "linestyle"), "--");
+%!   ## Test linking of remaining objects after deletion of one object
+%!   delete (hl2);
+%!   set (hl1, "linestyle", ":");
+%!   assert (get (hl3, "linestyle"), ":");
+%!   ## Test deletion of link
+%!   clear hlink;
+%!   set (hl1, "color", "g");
+%!   assert (get (hl3, "color"), [0 0 1]);
+%! unwind_protect_cleanup
+%!   close ([hf1 hf2 hf3]);
+%! end_unwind_protect
+
+%% Test input validation
+%!error linkprop ()
+%!error linkprop (1)
+%!error linkprop (1,2,3)
+%!error <H must contain at least 2 handles> linkprop (1, "color")
+%!error <invalid graphic handle in input H> linkprop ([pi, e], "color")
+%!error <PROP must be a string or cell string array> linkprop ([0, 0], 1)
+