function y = fdatool_help
%FDATOOL_HELP Help system functions for FDATool GUI.

%   Copyright 1988-2000 The MathWorks, Inc.
%   $Revision: 1.28 $  $Date: 2000/08/30 18:53:46 $

% Return structure of public function handles:
y.install_CSH      = @install_CSH;
y.toolhelp_cb      = @toolhelp_cb;
y.producthelp_cb   = @producthelp_cb;
y.HelpWhatsThis_cb = @HelpWhatsThis_cb;
y.importhelp_cb    = @importhelp_cb;
y.exporthelp_cb    = @exporthelp_cb;
y.saveopensessionshelp_cb = @saveopensessionshelp_cb;
y.demos_cb         = @demos_cb;
y.about_cb         = @about_cb;

% General Context Sensitive Help (CSH) system rules:
%  - context menus that launch the "What's This?" item have their
%    tag set to 'WT?...', where the '...' is the "keyword" for the
%    help lookup system.


% --------------------------------------------------------------
function figHelpFcn(hco,eventStruct)
% figHelpFcn Figure Help function called from either
%   the menu-based "What's This?" function, or the toolbar icon.

hFig  = gcbf;
hOver = gco;  % handle to object under pointer

% Dispatch to context help:
hc = get(hOver,'uicontextmenu');
hm = get(hc,'children');  % menu(s) pointed to by context menu

% Multiple entries (children) of context-menu may be present
% Tag is a string, but we may get a cell-array of strings if
% multiple context menus are present:
% Find 'What's This?' help entry
tag = get(hm,'tag');
helpIdx = find(strncmp(tag,'WT?',3));
if ~isempty(helpIdx),
    % in case there were accidentally multiple 'WT?' entries,
    % take the first (and hopefully, the only) index:
    if iscell(tag),
	    tag = tag{helpIdx(1)};
    end
	HelpGeneral([],[],tag);
end
set(handle(hFig),'cshelpmode','off');

% --------------------------------------------------------------
function toolhelp_cb(hco,eventStruct)
% toolhelp_cb Overview of the tool (reference-page help).

helpview ([docroot '/mapfiles/signal.map'], 'fdatool_overview');

% --------------------------------------------------------------
function producthelp_cb(hco,eventStruct)
% producthelp_cb Opens the Help window with the online doc Roadmap
%                page (a.k.a. "product page") displayed.

doc signal/

% --------------------------------------------------------------
function HelpWhatsThis_cb(hco, eventStruct)
% HelpWhatsThis_cb Get "What's This?" help
%   This mimics the context-menu help selection, but allows
%   cursor-selection of the help topic

hFig = gcbf;
cshelp(hFig);
set(handle(hFig),'cshelpmode','on');
set(hFig,'HelpFcn',@figHelpFcn);

% --------------------------------------------------------------
function importhelp_cb(hco,eventStruct)
% importhelp_cb Help on Importing into the tool.

helpview ([docroot '/mapfiles/signal.map'],...
	'fdatool_importfilterdesign');

% --------------------------------------------------------------
function exporthelp_cb(hco,eventStruct)
% exporthelp_cb Help on Exporting from the tool.

helpview ([docroot '/mapfiles/signal.map'],...
	'fdatool_exportfilterdesign');

% --------------------------------------------------------------
function saveopensessionshelp_cb(hco,eventStruct)
% saveopensessionshelp_cb Help on Exporting from the tool.

helpview ([docroot '/mapfiles/signal.map'],...
	'fdatool_saveopensessions');

% --------------------------------------------------------------
function demos_cb(hco,eventStruct)
% demos_cb Starts Demo window, with the appropriate product's
%                demo highlighted in the Demo window contents pane.

demo toolbox signal

% --------------------------------------------------------------
function about_cb(hco,eventStruct)
% about_cb Displays version number of product, and copyright.

str = sprintf(['Signal Processing Toolbox 5.0\n',...
	'Copyright 1988-2000 The MathWorks, Inc.']);
msgbox(str,'About the Signal Processing Toolbox','modal');

% --------------------------------------------------------------
function HelpGeneral(hco,eventStruct,tag)
% HelpGeneral Bring up the help corresponding to the tag string.

hFig = gcbf;
hco  = gcbo;

% Get tag (of the context menu) if it was not passed in directly:
if nargin<3, tag=get(hco,'tag'); end

% Check for legal tag string:
if ~ischar(tag),
   helpError(hFig,'Invalid context-sensitive help tag.');
   return
end

% Remove 'WT?' prefix;
if strncmp(tag,'WT?',3),
    tag(1:3) = '';
else
    msg = 'Context-sensitive help Tag string must begin with the "WT?" prefix.';
    helpError(hFig,msg);
    return
end

% Intercept general tags and map them to specific tags in the doc.
doclink = tag_mapping(hFig,tag);
bring_up_help_window(hFig,doclink);

% --------------------------------------------------------------
function tag = tag_mapping(hFig,tag);
% Intercept general tags to differentiate as appropriate, if 
% necessary, otherwise, return the input tag string.

switch tag
case 'fdatool_other_filtertypes_button',% Other filter types button.
    tag = otherfiltertypes_tags(hFig,tag);
    
case 'fdatool_ALL_analysis_plots',      % Analysis plots.
    tag = analysisplots_tags(hFig,tag);
    
case 'fdatool_ALL_import_structures',   % Import filter structures.
    tag = importstructures_tags(hFig,tag);
    
case 'fdatool_ALL_freq_specs_frame',    % Frequency specifications frame.
    tag = designspecs_tags(hFig,tag,'freq');
    
case 'fdatool_ALL_mag_specs_frame',     % Magnitude specifications frame.
    tag = designspecs_tags(hFig,tag,'mag');
    
case 'fdatool_ALL_freqmag_specs_frame', % Freq. & Mag. specifications frame.
    tag = freqmagspecs_tags(hFig,tag);
	
end

% --------------------------------------------------------------
function bring_up_help_window(hFig,tag);
% Attempt to bring up helpview
% Provide appropriate error messages on failure

try,
    helpview([docroot '\mapfiles\signal.map'], tag);
    
catch,
    % Help failed
    % Do some basic debugging of the help system:
    msg = {'';
        'Failed to find on-line help entry:';
        ['   "' tag '"'];
        ''};
    
    if isempty(docroot),
        msg = [msg; {'The "docroot" command is used to identify the on-line documentation';
                'path, and it has returned an empty string.  This usually indicates';
                'that you have not installed on-line help, or you have not properly';
                'set up the MATLAB Preferences.';
                ''}];
    else
        msg = [msg; {'The "docroot" command is used to identify the on-line documentation';
                'path, and it has returned a non-empty string.  This generally indicates';
                'that you have installed on-line help, but the specified directory path';
                'may be incorrect.';
                ''}];
    end
    
    msg = [msg;
        {'To modify your preference settings for the documentation path, go';
            'to the File menu in the Command Window, and choose "Preferences".';
            'Select "Help Browser", then check the "Documentation Location"';
            'directory path to ensure it points the location of your on-line';
            'help.'}];
    
    % Produce the error message:
    helpError(hFig,msg);
end


% --------------------------------------------------------------
function install_CSH(hFig)
%install_CSH Install Context-Sensitive Help


% ==================================================================
%
% Here is where all the handle-to-help relationships are constructed
%
% ==================================================================

ud = get(hFig,'userdata');

% Each relationship is set up as follows:
%
%  add_contextmenu(hFig, [vector_of_UI_handles], tagString);
%
% where tagStr corresponds to the link used in the doc map file. 

% Overview; figure.
add_contextmenu(hFig,ud.h.Fig, 'fdatool_overview');

% Current filter information frame and UIs.
currentfilterinfo_frame(hFig);

% Quantization switch frame and UIs.
quantizationswitch_frame(hFig)

% Analysis area.
analysis_frame(hFig);

% Mode (tab) buttons.
modebtns(hFig);

% Import Filter tab and contents.
importparams_tab(hFig);

% Filter Design tab and contents.
designparams_tab(hFig);

% Quantization tab and contents.
% quantizeparams_tab(hFig);

% Action (apply) buttons.
actionbtns(hFig)

% --------------------------------------------------------------
function currentfilterinfo_frame(hFig)
% Install help for the current filter information frame and it's UIs.

ud = get(hFig,'userdata');

% Make a vector of handles of the uis in the frame; exclude convert btn.
h_cfi = ud.h.currentfilterinfo;
h_cfi_all = [...
        h_cfi.frame,...
        h_cfi.structLbl,...
        h_cfi.structTxt,...
        h_cfi.filtertitle,...
        h_cfi.srcLbl,...
        h_cfi.srcTxt,...
        h_cfi.ordLbl,...
        h_cfi.ordTxt,...
        h_cfi.stableLbl,...
        h_cfi.stableTxt,...
        h_cfi.nosecLbl,...
        h_cfi.nosecTxt];
add_contextmenu(hFig, h_cfi_all, 'fdatool_currentfilterinfo_frame'); 

% Convert button.
add_contextmenu(hFig, h_cfi.convertbtn, 'fdatool_convertstruct_button'); 

% --------------------------------------------------------------
function quantizationswitch_frame(hFig)
% Install help for the quantization switch frame and uicontrol.

ud = get(hFig,'userdata');
if ud.flags.fdqexists,
    % "Turn quantization on" frame and uicontrol.
    h_qswitch = [ud.h.qswitch.frame ud.h.qswitch.quantizeSwitch];
    add_contextmenu(hFig, h_qswitch, 'fdatool_quantizationswitch_frame'); 
end

% --------------------------------------------------------------
function analysis_frame(hFig)
% Install help for the analysis area.

ud = get(hFig,'userdata');
% Analysis frame, the plots and the coefficient viewer.
add_contextmenu(hFig, ud.h.analysis.frame, 'fdatool_display_frame');
add_contextmenu(hFig, ud.h.analysis.filtcoeff_eb,'fdatool_filtercoefficients_viewer');

% Don't install CSH for the analysis plots because it conflicts with zoom
% (when using the right-mouse click).
%add_contextmenu(hFig, ud.h.analysis.ax,'fdatool_ALL_analysis_plots');

% --------------------------------------------------------------
function modebtns(hFig)
% Install help for the mode (tab) buttons.

% Get figure's userdata & extract appropriate structure's branch.
ud = get(hFig,'userdata');
h_mb = ud.h.modeFr;

% Mode (tab) buttons.
%add_contextmenu(hFig, h_mb.frame, '');  % background behind mode buttons
add_contextmenu(hFig, h_mb.designbtn,  'fdatool_designfilter_tab');
add_contextmenu(hFig, h_mb.importbtn,  'fdatool_importfilter_tab');
%add_contextmenu(hFig, h_mb.quantizebtn,'fdatool_quantizefilter_tab');

% --------------------------------------------------------------
function designparams_tab(hFig)
% Install help for the Filter Design tab.

% Get figure's userdata & extract appropriate structure's branch.
ud = get(hFig,'userdata');
h_dp = ud.h.design_params;

% Filter type frame.
ft = h_dp.filtTypes;
add_contextmenu(hFig, ft.frame, 'fdatool_filter_type_frame');
add_contextmenu(hFig, ft.rb(1), 'fdatool_lp_radiobutton');
add_contextmenu(hFig, ft.rb(2), 'fdatool_hp_radiobutton');
add_contextmenu(hFig, ft.rb(3), 'fdatool_bp_radiobutton');
add_contextmenu(hFig, ft.rb(4), 'fdatool_bs_radiobutton');

% The "Other" filter types.
add_contextmenu(hFig, ft.rb(5:6), 'fdatool_other_filtertypes_button');

% Filter design method frame.
m = h_dp.methods;
add_contextmenu(hFig, [m.frame m.rb.iir m.rb.fir m.pop.iir m.pop.fir ],...
    'fdatool_design_method_frame');

% Filter order frame
h_fo = h_dp.filtOrder;
add_contextmenu(hFig, [h_fo.frame h_fo.rb h_fo.lb h_fo.eb], 'fdatool_filter_order_specs_frame');

% Window frame.
winFr = h_dp.firwindow.frame;
add_contextmenu(hFig,...
    [winFr m.pop.firWin m.pop.winLabel m.pop.eb m.pop.eblabel],...
    'fdatool_window_specs_frame');

% Frequency specifications frame.
freqspecs = struct2cell(h_dp.specs.freq);
add_contextmenu(hFig, [freqspecs{:}], 'fdatool_ALL_freq_specs_frame');

% Magnitude specifications frame.
magspecs = struct2cell(h_dp.specs.mag);
add_contextmenu(hFig, [magspecs{:}], 'fdatool_ALL_mag_specs_frame');

% Frequency & Magnitude specifications frame.
freqmagspecs = struct2cell(h_dp.specs.freqmag);
add_contextmenu(hFig, [freqmagspecs{:}], 'fdatool_ALL_freqmag_specs_frame');

             
% --------------------------------------------------------------
function importparams_tab(hFig)
% Install help for the Import tab and it's uicontrols.

% Get figure's userdata & extract appropriate structure's branch.
ud = get(hFig,'userdata');
h_ip = ud.h.import_params;

% General overview of import filter coefficients frame.
h_s = h_ip.importFilter;
h_Fs = h_ip.importFs;
fs_hdnls = [h_Fs.fstitle, h_Fs.fspop, h_Fs.fseb, h_Fs.fslbl, h_Fs.fseblbl];
add_contextmenu(hFig, [h_s.frame(:);fs_hdnls(:)], 'fdatool_importfiltercoefficients_frame');

% Filter structure popupmenu and corresponding edit boxes and labels 
% for each corresponding filter structure.
h_structures = [h_s.pop, h_s.popLbl, h_s.coeffebs, h_s.tflbls, h_s.soslbls,...
        h_s.sslbls, h_s.lattarmalbls, h_s.lattapslbls, h_s.lattmaminlbls,...
        h_s.lattmamaxlbls, h_s.clrpbs];
if ud.flags.fdqexists, % Add handle to qfilt edit box label.
    h_structures = [h_structures(:);h_s.qfiltlbls];
end
add_contextmenu(hFig, h_structures(:), 'fdatool_ALL_import_structures');

% --------------------------------------------------------------
function quantizeparams_tab(hFig)
% Install help for the Quantization tab frames and uicontrols.

% Get figure's userdata.
ud = get(hFig,'userdata');

if ud.flags.fdqexists,
    % Quantize tab - two frames in the quantize tab.
    add_contextmenu(hFig, ud.h.quantize_params.qfiltobjs.frame, ...
        'fdatool_scaling_params_frame');
    add_contextmenu(hFig, ud.h.quantize_params.quantizerprops.frame,...
        'fdatool_quantizer_params_frame');
end

% --------------------------------------------------------------
function actionbtns(hFig)
% Install help for the action (apply) buttons.

% Get figure's userdata & extract appropriate structure's branch.
ud = get(hFig,'userdata');
h_btns = ud.h.actionFr.btn;

% Action (apply) buttons for Design, Import and Quantize tab.
add_contextmenu(hFig, h_btns(1), 'fdatool_design_filter_button');
add_contextmenu(hFig, h_btns(2), 'fdatool_import_filter_button');
add_contextmenu(hFig, h_btns(3), 'fdatool_quantizefilter_button');



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  Functions that intercept general tags and maps them to a specific tag. %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% --------------------------------------------------------------
function tag = otherfiltertypes_tags(hFig,tag)
% "Other" filter types button in the 
% Filter Type frame.

% Intercept general tags to differentiate as appropriate:
ud = get(hFig,'userdata');
all_filterTypes = get(ud.h.design_params.filtTypes.rb(end),'String');
indx = get(ud.h.design_params.filtTypes.rb(end),'Value');
filterType = lower(all_filterTypes{indx});

% Removed spaces from the filter type string.
filterType(isspace(filterType)) = '';
tag = ['fdatool_',filterType,'_othertype'];

% --------------------------------------------------------------
function tag = analysisplots_tags(hFig,tag)
% Analysis plots tags.

ud = get(hFig,'userdata');
analysisPlot = ud.toolbar.analysis;
tag = ['fdatool_',analysisPlot,'_plot'];

% --------------------------------------------------------------
function tag = importstructures_tags(hFig,tag)
% Structures in the Import tab.

ud = get(hFig,'userdata');
switch lower(ud.specs.import.impfiltstruct.struct),
case {'direct form i','direct form ii','direct form i transposed',...
        'direct form ii transposed'},
    tag = 'fdatool_transferfunction_specs';
    
case 'direct form ii (second-order sections)',
    tag = 'fdatool_sos_specs';
    
case 'state-space',
    tag = 'fdatool_statespace_specs';
    
case 'lattice allpass'
    %tag = 'fdatool_latticeallpass_specs';
    tag = 'fdatool_lattice_specs';
    
case {'lattice ma min. phase','lattice ma max. phase'},
    %tag = 'fdatool_latticema_specs';
    tag = 'fdatool_lattice_specs';
    
case 'lattice arma',
    tag = 'fdatool_lattice_specs';
    
case 'quantized filter (qfilt object)',
    tag = 'fdatool_quantizedfilter_specs';
end

% --------------------------------------------------------------
function tag = designspecs_tags(hFig,tag,frame)
% Tags for the filter design specifications frames (mag and freq).

% Intercept general tags to differentiate as appropriate:
ud=get(hFig,'userdata');
filterType = ud.specs.design.type;
method = ud.specs.design.method;

switch method
case 'cheb1'
    method = 'cheby1';
case 'cheb2'
    method = 'cheby2';    
end
tag = ['fdatool_',filterType,'_',frame,'_specs_',method];

% --------------------------------------------------------------
function tag = freqmagspecs_tags(hFig,tag)
% Tags for the filter design freqmag specifications frames.

% Intercept general tags to differentiate as appropriate:
ud=get(hFig,'userdata');
filterType = ud.specs.design.type;
tag = ['fdatool_',filterType,'_','freqmag_specs'];

% --------------------------------------------------------------
function add_contextmenu(hFig,hItem,tagStr)
% Add a "What's This?" context menu.

hc = uicontextmenu('parent',hFig);

uimenu('Label','What''s This?',...
	'Callback',@HelpGeneral,...
	'Parent',hc,...
	'Tag',['WT?' tagStr]);

set(hItem,'uicontextmenu',hc);

% --------------------------------------------------------------
function helpError(hFig,msg)
% Generate a modal dialog box to display errors while trying to obtain help

hmsg = errordlg(msg,'FDATool Help Error','modal');
centerfigonfig(hFig, hmsg);

% [EOF] fdatool_help.m
