% NAME: magnifyOnFigure
% AUTHOR: David Fernandez Prim (david.fernandez.prim@gmail.com)
% PURPOSE: Shows a functional zoom tool, suitable for publishing of zoomed
% images and 2D plots
%
% INPUT ARGUMENTS:
% figureHandle [double 1x1]: graphic handle of the target figure
% axesHandle [double 1x1]: graphic handle of the target axes.
%
% OUTPUT ARGUMENTS:
% none
%
% SINTAX:
% 1) magnifyOnFigure;
% $ Adds magnifier on the first axes of the current figure, with
% default behavior.
%
% 2) magnifyOnFigure( figureHandle );
% $ Adds magnifier on the first axes of the figure with handle
% 'figureHandle', with default behavior.
%
% 3) magnifyOnFigure( figureHandle, 'property1', value1,... );
% $ Adds magnifier on the first axes of the figure with handle
% 'figureHandle', with modified behavior.
%
% 4) magnifyOnFigure( axesHandle );
% $ Adds magnifier on the axes with handle 'axesHandle', with
% default behavior.
%
% 5) magnifyOnFigure( axesHandle, 'property1', value1,... );
% $ Adds magnifier on the axes with handle 'axesHandle', with
% modified behavior.
%
% 6) Consecutive calls to this function (in any of the syntaxes
% exposed above) produce multiple selectable magnifiers on the target axes.
%
% USAGE EXAMPLES: see script 'magnifyOnFigure_examples.m'
%
% PROPERTIES:
% 'magnifierShape': 'Shape of the magnifier ('rectangle' or 'ellipse' allowed, 'rectangle' as default)
% 'secondaryAxesFaceColor': ColorSpec
% 'edgeWidth' Color of the box surrounding the secondary
% axes, magnifier and link. Default 1
% 'edgeColor': Color of the box surrounding the secondary
% axes, magnifier and link. Default 'black'
% 'displayLinkStyle': Style of the link. 'none', 'straight' or
% 'edges', with 'straight' as default.
% 'mode': 'manual' or 'interactive' (allowing
% adjustments through mouse/keyboard). Default
% 'interactive'.
% 'units' Units in which the position vectors are
% given. Only 'pixels' currently supported
% 'initialPositionSecondaryAxes': Initial position vector ([left bottom width height])
% of secondary axes, in pixels
% 'initialPositionMagnifier': Initial position vector ([left bottom width height])
% of magnifier, in pixels
% 'secondaryAxesXLim': Initial XLim value of the secondary axes
% 'secondaryAxesYLim': Initial YLim value of the secondary axes
% 'frozenZoomAspectRatio': Specially useful for images, forces the use of the same zoom
% factor on both X and Y axes, in order to keep the aspect ratio
% ('on' or 'off' allowed, 'off' by default
%
% HOT KEYS (active if 'mode' set to 'interactive')
%
% -In a figure with multiple tool instances
% 'Tab': Switch the focus from one magnifier instance
% to the next one on the current figure.
% 'Mouse pointer on secondary axes or magnifier of a tool+double left click'
% Regain focus
%
% -On the focused magnifier instance
% 'up arrow': Moves magnifier 1 pixel upwards
% 'down arrow': Moves magnifier 1 pixel downwards
% 'left arrow': Moves magnifier 1 pixel to the left
% 'right arrow': Moves magnifier 1 pixel to the right
% 'Shift+up arrow': Expands magnifier 10% on the Y-axis
% 'Shift+down arrow': Compress magnifier 10% on the Y-axis
% 'Shift+left arrow': Compress magnifier 10% on the X-axis
% 'Shift+right arrow': Expands magnifier 10% on the X-axis
% 'Control+up arrow': Moves secondary axes 1 pixel upwards
% 'Control+down arrow': Moves secondary axes 1 pixel downwards
% 'Control+left arrow': Moves secondary axes 1 pixel to the left
% 'Control+right arrow': Moves secondary axes 1 pixel to the right
% 'Alt+up arrow': Expands secondary axes 10% on the Y-axis
% 'Alt+down arrow': Compress secondary axes 10% on the Y-axis
% 'Alt+left arrow': Compress secondary axes 10% on the X-axis
% 'Alt+right arrow': Expands secondary axes 10% on the X-axis
% 'PageUp': Increase additional zooming factor on X-axis
% 'PageDown': Decrease additional zooming factor on X-axis
% 'Shift+PageUp': Increase additional zooming factor on Y-axis
% 'Shift+PageDown': Decrease additional zooming factor on Y-axis
% 'Control+Q': Resets the additional zooming factors to 0
% 'Control+A': Displays position of secondary axes and
% magnifier in the command window
% 'Control+D': Deletes the focused tool
% 'Control+I': Shows/hides the tool identifier (red
% background color when the tool has the focus,
% black otherwise)
% 'Mouse pointer on magnifier+left click' Drag magnifier to any
% direction
% 'Mouse pointer on secondary axes+left click' Drag secondary axes in any
% direction
%
% TODO:
% - Use another axes copy as magnifier instead of rectangle (no ticks).
% - Adapt to work on 3D plots.
% - Add tip tool with interface description?.
%
% KNOWN ISSUES:
% - Secondary axes are not updated when the zoomming or panning tools of the figure are used.
% - Degraded performance for big data sets or big window sizes.
% - The size and position of the magnifier are modified for
% 'PaperPositionMode' equal to 'auto', when the figure is printed to file
% through 'print'
% CHANGE HISTORY:
function magnifyOnFigure( varargin )
clear global appDataStruct
global appDataStruct
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%CHECK OUTPUT ARGUMENTS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
switch nargout
case 0
%Correct
outputObjectExpected = false;
case 1
%tool object expected at the output
outputObjectExpected = false;
otherwise
error('Number of output arguments not supported.');
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%CHECK INPUT ARGUMENTS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
if nargin == 0
%Initialize 'appDataStructuct' with default values
appDataStruct = initializeToolStruct();
%Set figure handle
appDataStruct.figureHandle = gcf;
% Get number of axes in the same figure
childHandle = get(appDataStruct.figureHandle, 'Children');
iAxes = find(strcmpi(get(childHandle, 'Type'), 'axes'));
% If no target axes specified, select the first found as mainAxes
appDataStruct.mainAxesHandle = childHandle( iAxes(end) );
elseif nargin > 0
if isstruct(varargin{1})
%Initialize 'appDataStructuct' with existent structure
