fullFileName=filesFullName(inFile, filesExtList, dlgTitle, isErrMode)

function fullFileName=filesFullName(inFile, filesExtList, dlgTitle, isErrMode)
%% filesFullName
% The function attempts to find a full file name (path+file name+extention), filling the
%  missing gaps.
%
%% Syntax
%  fullFileName=filesFullName(inFile, filesExtList);
%  fullFileName=filesFullName(inFile);
%
%% Description
%
%% Input arguments (defaults exist):
%  inFile- input file name. inFile must include file name. File path may be ommited, if
%     file is in Matlab path. File extention can be mmited for simplisuty or laziness.
%  filesExtList- a list of extentions describing the file type we wish to detect. Default
%     file types are Graphical or Videos.
%  dlgTitle- a string used in the files explorer menu.
%  isErrMode- a logical variable defining fnction behaviour in case of non existent file.
%     When enabled- an error messge will be issued (default behaviour). When disabled, an
%     empty name will be returned, without an error
%
%% Output arguments
%   fullFileName-  a full file name (path+file name+extention).
%
%% Issues & Comments
%
%% Example
%
%% See also
%
%% Revision history
% First version: Nikolay S. 2012-05-01.
% Last update:   Nikolay S. 2012-11-14.
%
% *List of Changes:*
%
% 2012-11-14- isErrMode: user can select how to react in case of missing file.
% 2012-07-31- dlgTitle: custom browser title added.
% 2012-07-19- Empty or missing input file name result in opening a browser
% 2012-05-21- Taken care of fileattrib error.
%
if nargin < 4
    isErrMode=true;
end
if nargin < 3
    dlgTitle='Select input file.';
end
if nargin < 2 || isempty(filesExtList) % if no filesExtList was provided try finding video or graphical files
    videoFormats= VideoReader.getFileFormats();
    videoExtList={videoFormats.Extension};    % video files extentions
    imageFormats=imformats;
    imageExtList=cat(2, imageFormats.ext);    % image files extentions
    filesExtList=cat(2, videoExtList, imageExtList);
end

if nargin < 1
    inFile=[];
end

if isempty(inFile)
    filesFilter=sprintf('*.%s;', filesExtList{:});
    
    [fileName, pathName, ~] = uigetfile(filesFilter, dlgTitle);
    if ischar(fileName) % single file was chosen
        fullFileName=strcat(pathName, fileName);
    else % cancel was pressed
        fullFileName=inFile;
    end
    return;
end

[fileDir, ~, fileExt] = fileparts(inFile);
if exist(inFile, 'file')~=2
    if isErrMode
        % error if no file found for such an extention
        assert(isempty(fileExt), 'No such file exists.'); 
    end
    for iFileExt=1:length(filesExtList) % if no file extention was mentioned, try finding one from supported video file extentions list
        candidateFile=strcat(inFile, '.', filesExtList{iFileExt});
        if exist(candidateFile, 'file')==2
            inFile=candidateFile;
            break;
        end
    end
    if exist(inFile, 'file')~=2
        if isErrMode
            % Issue an error if no file found for such an extention
            error('No such file exists.');
        else
            % If error mode is disabled, return empty spaces for non existent files
            fullFileName=[];
            return;
        end
    end
end

fullFileName=inFile;
if isempty(fileDir) % if no directory was specified get full file name and path from file attributes
    [stats, currFileAttr]=fileattrib(fullFileName);
    % sometimes fileattrib fails witout any explanation
    % assert( stats && ~strcmpi(currFileAttr, 'Unknown error occurred.') );
    if ( stats && ~strcmpi(currFileAttr, 'Unknown error occurred.') )
        fullFileName=currFileAttr.Name;
    else
        % if file exists but fileattrib failed use which
        fullFileName=which(fullFileName);
    end
end