makedatatip(hObj,index)

function varargout = makedatatip(hObj,index)
%MAKEDATATIP  Adds data tips to specified data points of graphical objects.
%
%  MAKEDATATIP(HOBJ,INDEX) adds a datatip to the graphical object HOBJ at
%  the data point defined by INDEX.
%
%  HOUT = MAKEDATATIP(...) returns handles to the created datatips.
%
%  If HOBJ is 1-dimensional, INDEX can be of any size and is assumed to be
%  a linear index into the data contained by HOBJ.  HOUT will be of the
%  same size as INDEX.
%
%  If HOBJ is 2-dimensional and INDEX is N-by-2, INDEX is assumed to be a
%  set of N subscripts, and HOUT will be N-by-1.  If INDEX is of any other
%  size, it is assumed to a linear index and HOUT will be the same size as
%  INDEX.  Note that if you wish to specify 2 linear indices, ensure INDEX
%  is a column vector, else it will be assumed to be a single set of
%  subscripts.
%
% Example: 
%     x = 1:10;
%     y = rand(1,10);
%     hPlot = plot(x,y);
%     makedatatip(hPlot,[3 8])
%
% Example:
%     [X,Y,Z] = peaks(30);
%     hObj = surf(X,Y,Z);
%     makedatatip(hObj,[5 8; 20 12; 22 28])
%
% Example: Add a single data tip to data point (5,25)
%     [X,Y,Z] = peaks(30);
%     hObj = surf(X,Y,Z);
%     makedatatip(hObj,[5 25])
%
% Example: Add two data tips to data points (5) and (25)
%     [X,Y,Z] = peaks(30);
%     hObj = surf(X,Y,Z);
%     makedatatip(hObj,[5; 25])

% Author: Tim Farajian
% Release: 1.0
% Release date: 5/10/2008

error(nargchk(2,2,nargin))
error(nargoutchk(0, 1, nargout))

% Ensure hObj is valid target
handleObj = handle(hObj);
if ~ishandle(hObj)
  error('MAKEDATATIP:InvalidHandle',...
    'HOBJ is an invalid handle object.');
elseif ~isa(handleObj,'hg.surface') &&...
    ~isa(handleObj,'hg.patch') &&...
    ~isa(handleObj,'hg.line') &&...
    ~isa(handleObj,'hg.image')
  error('MAKEDATATIP:InvalidObjectType',...
    'Objects of class ''%s'' are not a valid targets for datatips.',...
    class(handleObj));
end

% Read data from hObj
X = get(hObj,'XData');
Y = get(hObj,'YData');
Z = get(hObj,'ZData');

% Ensure subscripts or indices are valid values and sizes
if isempty(index)
  return
elseif ~isnumeric(index)
  error('MAKEDATATIP:InvalidDataType',...
    'Subscript indices must be of numeric data type.')
elseif any(index(:)<1) ||...
    any(fix(index(:))~=index(:)) ||...
    any(isinf(index(:)))
  error('MAKEDATATIP:InvalidIndex',...
    'Subscript indices must be positive integers.')
elseif ~isvector(index) && ~any(size(index)==2)
  error('MAKEDATATIP:InvalidIndexMatrixSize',...
    'Subscript indices must be a vector or N-by-2 matrix.')
elseif isvector(X) || size(index,2)~=2
  hDatatip = zeros(size(index));
  index = index(:);
  isLinear = true;
else
  hDatatip = zeros(size(index,1),1);
  isLinear = false;
end

% Get handle to datacursor mode object
hDataCursorMgr = datacursormode(ancestor(hObj,'figure'));

% Loop through each specified data point
for n = 1:size(index,1)
  
  % Create position vector
  if isempty(Z)
    pos = [X(index(n)) Y(index(n))];
  elseif isLinear
    pos = [X(index(n)) Y(index(n)) Z(index(n))];
  else
    pos = [...
      X(index(n,1),index(n,2))...
      Y(index(n,1),index(n,2))...
      Z(index(n,1),index(n,2))];
  end
  
  % Create datatip
  hDatatip(n) = createDatatip(hDataCursorMgr, hObj);
  % Specify data cursor properties
  set(get(hDatatip(n),'DataCursor'),'DataIndex',index(n),...
    'TargetPoint',pos)
  % Specify datatip properties
  set(hDatatip(n),'Position',pos)
  
end

% Update all data cursors
updateDataCursors(hDataCursorMgr)

% Return handles if requested
if nargout==1
  varargout = {hDatatip};
end