function out = addGroup(obj, varargin)
% addGroup    Add new settings group
%
%  addGroup(PARENTGROUP, NAME) adds a new settings group, NAME, to the specified parent
%  group, PARENTGROUP and returns a SettingsGroup object containing the new group. NAME 
%  can be any valid MATLAB variable name. If NAME exists in the specified parent group,
%  MATLAB returns an error.
%
%  addGroup saves the new settings group in the user settings file in the preferences 
%  directory. This ensures that the settings group persists across MATLAB sessions. 
%  If the user settings file is read-only, the settings group is added to the tree for
%  the current session, but does not persist across subsequent MATLAB sessions.
%
%  addGroup(PARENTGROUP, NAME, NAME1, VALUE1, ...) specifies settings group properties
%  using one or more name-value pair arguments. Specify name-valye pairs after all other 
%  input arguments.
%
%  Supported properties included
% 
%  'Hidden'
%   The 'Hidden' property indicates whether this group is a visible settings group.
%   When 'Hidden' is set to true, any child settings groups and settings 
%   within the group are not displayed. The default value of this
%   property is false.
%
%  'ValidationFcn'
%   The 'ValidationFcn' property specifies the function to validate settings in the
%   group. Specify the validation function as a function handle. When specified, 
%   the validation function is used as the default validation function for all the settings 
%   within the group that do not have their own validation function defined. 
%
%  Examples:
%  Assume the settings tree contains these settings groups
%
%                            root
%                            /  \     
%                       matlab  mytoolbox
%                           ......          
%
%  Add the settings group 'mysettings' to the root settings group:
%    >> s = settings;
%    >> addGroup(s, 'mysettings');
%
%  This results in this settings tree
%
%                                 root
%                            /     |     \
%                       matlab mytoolbox mysettings
%                           ...... 
%
%  Add the settings group 'myhiddensettings' to the root settings group. Set the
%  'Hidden' property to true and specify the validation function 'ValidateValue'. 
%
%    >> s = settings;
%    >> addGroup(s, 'myhiddensettings', 'Hidden', true, 'ValidationFcn', @validateValue);
%
%  This results in this settings tree
%
%                                     root
%                            /     /        \            \
%                      matlab mytoolbox mysettings myhiddensettings
%                           ...... 
%
% The hidden settings group 'myhiddensettings' does not display in the parent 
% settings group:
%
%    >> s = 
%    s =
%      SettingsGroup with properties:
%           matlab: [1x1 SettingsGroup]
%        mytoolbox: [1x1 SettingsGroup]
%       mysettings: [1x1 SettingsGroup]
%
%   See also matlab.settings.SettingsGroup, matlab.settings.SettingsGroup/addSetting

%   Copyright 2015-2019 The MathWorks, Inc.

    [results, defaultsUsed] = matlab.settings.internal.parseGroupPropertyValues(varargin);
    % parseGroupPropertyValues function parses and validates user-input for optional property-value pairs with inputParser.
    out = obj.addGroupHelper(results,defaultsUsed);    
end
