Plugins-warndanger

From Bcontrol

From the help file (in Matlab, help @warnDanger/WarnDangerInterface)

% [x, y] = WarnDangerInterface(obj, action, wd_name, x, y)
%
% Puts up a GUI for making a set of states for making a warning sound
% followed by a "danger" sound-- if the animal pokes during the danger
% sound, a jump to a state you name ensues. (Typically, this is a poke to a
% punishment state, but it's whatever you define.) The GUI lets you define
% various aspects of this warning/danger combo, and then you can make a
% simple call to add the necessary states to a @StateMachineAssembler you
% are constructing.
%
% QUICKSTART USAGE:
% -----------------
%
% To create a warn/danger GUI, call
%
%   [x, y] = WarnDangerInterface(obj, 'add', wd_name, x, y)
%
% where wd_name is a string that will identify this warn/danger section,
% and x and y are the pixel position in the current figure on which a
% the GUI for this warn/danger section appears. By using different
% wd_name strings, you can have separate, different warn/danger
% sections.
%
% Then, to use the warn/danger section, when constructing your StateMachine
% Assembler, call
%
%   sma = WarnDangerInterface(obj, sma, 'add_sma_states', wd_name, ...
%        'exitstate', exit_state_name, 'on_poke_when_danger_state', onpoke_state_name);
%
% where sma is a @StateMachineAssembler object, wd_name is the string
% identifying this warn/danger section; exit_state_name is a string
% identifying the state to jump to after the warn/danger is over; and
% onpoke_state_name is the name of the state to jump to if the animal pokes
% during the danger states. The call above will add the necessary states to
% implement the warn/danger. To start the warn/danger, have the state
% machine jump to the state named wd_name. The states that form part of the
% warning will be called [wd_name '_warning']; the states that form part of 
% the danger will be called [wd_name '_danger']. Thus, if you wish to jump
% straight to the danger section and ignore the warning, jump to [wd_name
% '_danger']. 
%    All three of a state called wd_name, a state called [wd_name '_warning'],
% and a state called [wd_name '_danger'] are always guaranteed to exist,
% you can always jump to them even if some durations have been set to 0.
%
%
% warn/danger CHARACTERISTICS:
% ---------------------------
%
% The "warn/danger" is defined by an initial sound ("warning" sound, e.g.
% a ramp of increadingly loud white noise), followed by another sound
% ("danger" sound) that loops for some desired time (e.g., white noise that
% loops until 10 s have elapsed). At the end of the danger sound, a jump to 
% exit_state_name is made. If the animal pokes during the danger sound, a
% jump to onpoke_state_name is made.
%    The "warning" sound and the "danger" sound are defined using @soundui;
% a figure with their GUI parameters is created. NOTE that how long the
% danger sound lasts depends on "DangerDur" in the warn/danger GUI, since
% the ongoing sound is forcibly set to loop. The duration in the @soundui
% GUI for this sound defines only how long one of the loop cycles lasts. 
%
% ** NOTE ** Currently only warning sounds with a single duration (Dur1)
% are supported. ToneSweeps and BupsSweeps are not yet supported. Bug
% Carlos if you want them added.
%
%
% PARAMETERS:
% -----------
%
% The first parameter, action, should be one of:
%
%  'add'     Make a GUI for a new warn/danger. This action requires three
%            more PARAMETERS:
%
%              wd_name    A string defining the name of the warn/danger
%            
%              x, y            x and y position, in pixels from bottom
%                              left of current figure, at which to start
%                              putting in the GUI elements.
%         
%            This action, 'add', also takes a number of OPTIONAL PARAMETERS:
%
%              'TooltipString'   Default is ''; Tooltip string for title of
%                         GUI.
%
%            This action, 'add', RETURNS:  x, y  next open position on
%                         current figure.
%
% 'set' wd_name 'WarnDur'|'DangerDur'  value
%        
%               The 'set' action allows setting the parameters for any of
%               the warn/dangers that have been created. The next argument
%               after 'set' must be a string, the name of the warn/danger
%               that was created with 'add'; the next argument must also be
%               a string, as listed above; and the last argument should be
%               the value the corresponding setting will be changed to.
%               Example calls:
%                     WarnDangerInterface(obj, 'set', 'mywd', 'WarnDur', 5);
%                 or
%                     DistribInterface(obj, 'set', 'mywd', 'DangerDur',   0);
%
%               It is allowable for either or both of WarnDur or DangerDur
%               to be zero. The code is robust to that.
%
%
% 'get' wd_name 'WarnDur'|'DangerDur'  
%
%               The 'get' action returns the setting of the parameters for any of
%               the warn/dangers that have been created. The next argument
%               after 'get' must be a string, the name of the warn/danger
%               that was created with 'add'; the next argument must also be
%               a string, as listed above.
%               Example call:
%                     myvarstyle = WarnDangerInterface(obj, 'get', 'mywd', 'WarnDur')
%
% 'disable' wd_name    Disables all of the GUI elements of wd_name
%
% 'enable'  wd_name    Enables all of the GUI elements of wd_name
%