Restore append functionality for MATLAB >= R2017a

The addition of 'AutoUpdate' to legend in R2017a breaks the
functionality of append. With 'AutoUpdate' turned off we can restore
the functionality of legtools, but turning it back on causes our
appended legend entries to be deleted. Clearing out the undocumented
'PlotChildrenExcluded' legend property seems to prevent this from
occuring

This is untested in versions < R2017a

See #15

Author: sco1

Readme.md

@@ -18,6 +18,8 @@ Append string(s), `newStrings`, to the specified `Legend` object, `legendhandle`
 
 The legend will only be updated with the new strings if the number of strings in the existing legend plus the number of strings in `newStrings` is the same as the number of plots on the associated `Axes` object (e.g. if you have 2 lineseries and 2 legend entries already no changes will be made).
 
+**NOTE**: For MATLAB R2017a or newer, the `legend` object's [`'AutoUpdate'`](https://www.mathworks.com/help/matlab/ref/matlab.graphics.illustration.legend-properties.html#bt7bgi4-1-AutoUpdate) property *must* be set to `'off'` before adding additional lineseries to the plot.
+
 #### Examples
 ##### Adding one legend entry
     % Sample data
@@ -154,4 +156,4 @@ For a single dummy legend entry, `plotParams` is defined as a cell array of stri
     plotParams = {{'Color', 'Red'}, {'Color', 'green'}};
     legtools.adddummy(lh, newStrings, plotParams)
 
-![addummy2](https://github.com/sco1/sco1.github.io/blob/master/legtools/adddummy2.png)
+![addummy2](https://github.com/sco1/sco1.github.io/blob/master/legtools/adddummy2.png)

legtools.m

@@ -11,6 +11,10 @@
     %     remove   - Remove one or more legend entries
     %     adddummy - Add one or more entries to the legend for unsupported graphics objects
     %
+    % NOTE:
+    %      For MATLAB versions >= R2017a, the legend object's 'AutoUpdate'
+    %      property must be set to 'off' before using this utility
+    %
     % See also legend
 
     methods (Static)
@@ -38,6 +42,8 @@ function append(lh, newStrings)
 
             newStrings = legtools.strcheck('append', newStrings);
 
+            legtools.autoupdatecheck(lh)
+            
             % To make sure we target the right axes, pull the legend's
             % PlotChildren and get their parent axes object
             parentaxes = lh.PlotChildren(1).Parent;
@@ -66,6 +72,19 @@ function append(lh, newStrings)
                         'Ignoring extra legend entries');
             end
             lh.String = newlegendstr;
+            
+            if ~verLessThan('matlab', '9.2')
+                % The addition of 'AutoUpdate' to legend in R2017a breaks
+                % the functionality of append. With 'AutoUpdate' turned off
+                % we can restore the functionality of legtools, but turning
+                % it back on causes our appended legend entries to be
+                % deleted. Clearing out the undocumented
+                % 'PlotChildrenExcluded' legend property seems to prevent
+                % this from occuring
+                %
+                % NOTE: This is untested in versions < R2017a
+                lh.PlotChildrenExcluded = [];
+            end
         end
 
 
@@ -312,5 +331,17 @@ function verchk()
                 end
             end
         end
+        
+        function autoupdatecheck(lh)       
+            % If we're using R2017a or newer, we need to make sure that 
+            % 'AutoUpdate' is off
+            if ~verLessThan('matlab', '9.2')
+                if ~strcmp(lh.AutoUpdate, 'off')
+                    lh.AutoUpdate = 'off';
+                    warning('legtools:autoupdatecheck:AutoUpdateNotOff', ...
+                            'Input legend object''s ''AutoUpdate'' property has been set to ''off''')
+                end
+            end
+        end
     end
 end