xxsimAddCurveToPlot

 xxsimAddCurveToPlot - Add a new curve to the specified plot

 Syntax: 
   retval = xxsimAddCurveToPlot(window, plot, yPath, labelName, xVariable, varargin)

 Inputs:
   window    = Name or ID from the plot window where the curve is added to.
   plot      = Name or ID from the plot where the curve is added to.
   yPath     = Path of the 20-sim variable that is plotted in the curve.
   labelName = [Optional] Label given to the curve, as shown in the legend of the plot (default is yPath).
   xVariable = [Optional] The variable plotted on the X-axis of the curve (default: time).
   varargin  = [Optional] Specify key-value pairs as needed (optional, default is no key-value pair).

   Keys supported for the key-value pairs are:
   colorR   =  The red component of the RGB colour that the curve should have (if colorG or colorB is specified, the default value will be 0) [0-255].
   colorG   =  The green component of the RGB colour that the curve should have (if colorR or colorB is specified, the default value will be 0) [0-255].
   colorB   =  The blue component of the RGB colour that the curve should have (if colorR or colorG is specified, the default value will be 0) [0-255].
   thickness=  The thickness of the line [1-50].

 Outputs: 
   retval = returns a unique ID corresponding to the curve that was created.
 
 Example:
   retval = xxsimAddCurveToPlot(1,2,'MotionProfile.x')
   
     - Adds a curve to plot 2 in window 1 with MotionProfile.x on its y-axis.
     - retval now contains an ID that is uniquely coupled to this
       newly added curve.
     - Note: The simulator should be open before calling this function.  
   retval = xxsimAddCurveToPlot(1,2,'MotionProfile.x','Position','colorR',255)
   
     - Adds a curve to plot 2 in window 1 with MotionProfile.x on its y-axis with label "Position".
     - The curve will now be red.

 See also: xxsimRemoveCurveFromPlot, xxsimOpenSimulator, xxsimAddPlotToWindow, xxsimGetCurvesFromPlot

 Author: Controllab Products B.V.
 email: info@controllab.nl
 Website: http://www.controllab.nl
 May 2018

0001 function retval = xxsimAddCurveToPlot(window,plot,yPath,labelName,xVariable,varargin)
0002 % xxsimAddCurveToPlot - Add a new curve to the specified plot
0003 %
0004 % Syntax:
0005 %   retval = xxsimAddCurveToPlot(window, plot, yPath, labelName, xVariable, varargin)
0006 %
0007 % Inputs:
0008 %   window    = Name or ID from the plot window where the curve is added to.
0009 %   plot      = Name or ID from the plot where the curve is added to.
0010 %   yPath     = Path of the 20-sim variable that is plotted in the curve.
0011 %   labelName = [Optional] Label given to the curve, as shown in the legend of the plot (default is yPath).
0012 %   xVariable = [Optional] The variable plotted on the X-axis of the curve (default: time).
0013 %   varargin  = [Optional] Specify key-value pairs as needed (optional, default is no key-value pair).
0014 %
0015 %   Keys supported for the key-value pairs are:
0016 %   colorR   =  The red component of the RGB colour that the curve should have (if colorG or colorB is specified, the default value will be 0) [0-255].
0017 %   colorG   =  The green component of the RGB colour that the curve should have (if colorR or colorB is specified, the default value will be 0) [0-255].
0018 %   colorB   =  The blue component of the RGB colour that the curve should have (if colorR or colorG is specified, the default value will be 0) [0-255].
0019 %   thickness=  The thickness of the line [1-50].
0020 %
0021 % Outputs:
0022 %   retval = returns a unique ID corresponding to the curve that was created.
0023 %
0024 % Example:
0025 %   retval = xxsimAddCurveToPlot(1,2,'MotionProfile.x')
0026 %
0027 %     - Adds a curve to plot 2 in window 1 with MotionProfile.x on its y-axis.
0028 %     - retval now contains an ID that is uniquely coupled to this
0029 %       newly added curve.
0030 %     - Note: The simulator should be open before calling this function.
0031 %   retval = xxsimAddCurveToPlot(1,2,'MotionProfile.x','Position','colorR',255)
0032 %
0033 %     - Adds a curve to plot 2 in window 1 with MotionProfile.x on its y-axis with label "Position".
0034 %     - The curve will now be red.
0035 %
0036 % See also: xxsimRemoveCurveFromPlot, xxsimOpenSimulator, xxsimAddPlotToWindow, xxsimGetCurvesFromPlot
0037 %
0038 % Author: Controllab Products B.V.
0039 % email: info@controllab.nl
0040 % Website: http://www.controllab.nl
0041 % May 2018
0042 
0043 %------------- BEGIN CODE --------------
0044   % Check the obtained amount of input arguments.
0045   if(nargin<3)
0046     error('Too little input arguments were specified.');
0047   end;
0048 
0049   % If no labelName is specified, set it to the yPath.
0050   if(nargin < 4)
0051     labelName = yPath;
0052   end;
0053   
0054   % If no xVariable is specified, set it to 'time'.
0055   if(nargin < 5)
0056     xVariable = 'time';
0057   end;
0058 
0059   % Create an empty key-value array, if no key-value pairs are specified.
0060   if(nargin < 6)
0061     keyValueArray = [];
0062   end;
0063   
0064   % If key-value pairs are given, set it into a struct.
0065   if(nargin > 5)
0066     % If there is an odd number of key-value arguments, give an error, since every key should have a value.
0067     if(mod(length(varargin),2) == 1)
0068       error('Odd number of key-value arguments specified. Please specify each time a key, followed by a value.');
0069     end;
0070     
0071     % Loop through all varargins in pairs of 2.
0072     counter = 1;
0073     for i=1:2:length(varargin)
0074       if(~ischar(varargin{i}) || ~ischar(varargin{i+1}))
0075         error('All key-value arguments should be of type string.');
0076       end;
0077       
0078       keyValueStruct = struct('key',varargin{i},'value',varargin{i+1});
0079       keyValueArray(counter) = keyValueStruct;
0080       counter=counter + 1;
0081     end;
0082   end;
0083 
0084   % Check if the window and plot are a number or string
0085   if(~isnumeric(window) && ~ischar(window))
0086     error('Please specify the ID of the plot window (numeric) or its name (a string).');
0087   elseif(~ischar(plot) && ~isnumeric(plot))
0088     error('Please specify a string as name for the plot');
0089   end;
0090   
0091   % Check if the path is a string.
0092   if(~ischar(yPath))
0093     error('Please specify the path to the variable you would like to add as a string.');
0094   end;
0095   
0096   % Check if the labelName is a string.
0097   if(~ischar(labelName))
0098     error('Please specify the label name of this curve as a string.');
0099   end;
0100 
0101   % Check if the xVariable is a string.
0102   if(~ischar(xVariable))
0103     error('Please specify the xVariable name of this curve as a string.');
0104   end;
0105   
0106   % Get the IDs if the input is a string.
0107   windowID = xxsimGetPlotWindowIDFromName(window);
0108   plotID = xxsimGetPlotIDFromName(window,plot);
0109 
0110   % And make the actual call to 20-sim
0111   retval = xrlinvoke('xxsim.plot.addCurveToPlot', struct('windowID',int32(windowID),'plotID',int32(plotID),'xVariablePath',xVariable,'yVariablePath',yPath,'zVariablePath','dummy','labelName',labelName,'keyvalues',{{keyValueArray,'array'}}));
0112 
0113 end
0114 %------------- END OF CODE --------------