Plugins-punishui

From Bcontrol

From the help file (In Matlab, >> help Plugins/@punishui/PunishInterface )

% [x, y] = PunishInterface(obj, action, punish_name, x, y)
%
% Puts up a GUI for making a set of states for making a punishment sound.
% The GUI lets you define various aspects of this punishment, and then you
% can make a simple call to add the punishment section to a
% @StateMachineAssembler you are constructing.
%
% QUICKSTART USAGE:
% -----------------
%
% To create a punishment GUI, call
%
%   [x, y] = PunishInterface(obj, 'add', punish_name, x, y)
%
% where punish_name is a string that will identify this punishment section,
% and x and y are the pixel position in the current figure on which a
% the GUI for this punishment section appears. By using different
% punish_name strings, you can have separate, different punishment
% sections.
%
% Then, to use the punishment section, when constructing your StateMachine
% Assembler, call
%
%   sma = PunishInterface(obj, sma, 'add_punishment_states', punish_name, ...
%        'exitstate', exit_state_name);
%
% where sma is a @StateMachineAssembler object, punish_name is the string
% identifying this punishment section, and exit_state_name is a string
% identifying the state to jump to after the punishment is over. The call
% above will add the necessary states to implement the punishment. To start
% the punishment, have the state machine jump to the state named
% punish_name. All of these states that form part of this punishment will
% be associated with the name punish_name.
%
%
% PUNISHMENT CHARACTERISTICS:
% ---------------------------
%
% The "punishment" is defined by an initial sound ("init sound," typically
% very loud and not very long, say 0.5 s or 1 s, used to indicate to the
% animal that it's done something wrong), followed by another sound
% ("ongoing" sound) that loops for a longish time (e.g., 5 s). At the end
% of that longish sound, a jump to exit_state_name is made. 
%    You can use the Reinit button on the GUI to set the punishment so that
% if the animal pokes in any poke, the initial sound plays again, and the
% punishment reinits. Using ReinitGrace, you can also set it so that poking
% again immediately after a reinit doesn't reinit yet again. You can also
% set a "ReinitPenalty", an extra time that the ongoing sound plays if the
% animal poked during the punishment. Finally, you can use the Reinit
% button to set the punishment so that poking doesn't reinit, the
% punishment runs for as long as you indicate regardless of what the animal
% does.
% 
% The "init" sound and the "ongoing" sound are defined using @soundui; a
% figure with their GUI parameters is created. NOTE that how long the
% ongoing sound lasts depends on "Duration" in the punishment 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. 
%
%
%
% PARAMETERS:
% -----------
%
% The first parameter, action, should be one of:
%
%  'add'     Make a GUI for a new punsihment. This action requires three
%            more PARAMETERS:
%
%              punish_name    A string defining the name of the punishment
%            
%              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:
%
%              'new_sounds'    By default 0. If 1, a GUI for the punishment
%                         sounds is not created; instead, two text entry
%                         fields are made. It is then your responsibility
%                         to type in the name of two sounds (names as known
%                         to @soundmanager) that can serve as InitSound and
%                         OngoingSound. NOTE that InitSound *must not
%                         Loop*; and that OngoingSound *must* Loop.
%              'TooltipString'   Default is ''; Tooltip string for title of
%                         GUI.
%
%            This action, 'add', RETURNS:  x, y  next open position on
%                         current figure.
%
% 'set' punish_name 'Duration'|'Reinit'|'ReinitGrace'|'ReinitPenalty'  value
%        
%               The 'set' action allows setting the parameters for any of
%               the punishments that have been created. The next argument
%               after 'set' must be a string, the name of the punishment
%               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:
%                     PunishInterface(obj, 'set', 'mypunish', 'Duration', 5);
%                 or
%                     DistribInterface(obj, 'set', 'mypunish', 'Reinit',   0);
%
% 'get' punish_name 'Duration'|'Reinit'|'ReinitGrace'|'ReinitPenalty'  
%
%               The 'get' action returns the setting of the parameters for any of
%               the punishments that have been created. The next argument
%               after 'get' must be a string, the name of the punishment
%               that was created with 'add'; the next argument must also be
%               a string, as listed above.
%               Example call:
%                     myvarstyle = PunishInterface(obj, 'get', 'mypun', 'Duration')
%
%