ZOrder Get/Set

ZOrderGet, ZOrderSet: Get/Set the current z-order position of an existing object of a figure

%ZOrderGet Get the current z-order position of an existing object of a figure
%
% [hIndex, hCount] = ZOrderGet(h = gco)
%
% Set a new z-order position of an existing object of a figure.
% The lower the z-order, the closer the object to the user eye.
%
% When adding a new object to a figure, by default it is provided with
% the first z-order value, so it becomes the most visible one.
%
% Example:
% figure(1); clf; hold on;
% h1 = plot(1, 1, 'o', 'MarkerSize', 10, 'MarkerFaceColor', [1 0 0]);
% h2 = plot(1, 1, 'o', 'MarkerSize', 20, 'MarkerFaceColor', [0 1 0]);
% % the red marker (h1) is not visible at this time
% [i cnt] = ZOrderGet(h1)
% i =
% 2
% cnt =
% 2
%
% Thanks and inspired to AddReorderButtons by Geoffrey K. Adams, November 2007
%
% Copyright 2011
%
% v1.0.0 - 28/04/2011
% Marcello Ferro <[e-mail]>
% http://www.ilc.cnr.it
%

%ZOrderSet Set a new z-order position of an existing object of a figure
%
% ZOrderSet(h = gco, zIndex = 0 (last, default) | n (n-th) | -n (n-th last))
%
% Set a new z-order position of an existing object of a figure.
% The lower the z-order, the closer the object to the user eye.
%
% The zIndex is the target z-order of the object. If out of boundaries,
% it will be clipped.
%
% When adding a new object to a figure, by default it is provided with
% the first z-order value, so it becomes the most visible one.
%
% Example:
% figure(1); clf; hold on;
% h1 = plot(1, 1, 'o', 'MarkerSize', 10, 'MarkerFaceColor', [1 0 0]);
% h2 = plot(1, 1, 'o', 'MarkerSize', 20, 'MarkerFaceColor', [0 1 0]);
% % the red marker (h1) is not visible at this time
% ZOrderSet(h1, 1); % set it to first position: the red marker is visible
% ZOrderSet(h1, 2); % set it to 2nd (last) position: the red marker is not visible
% ZOrderSet(h1, 0); % set it to last position: the red marker is not visible
%
% Thanks and inspired to AddReorderButtons by Geoffrey K. Adams, November 2007
%
% Copyright 2011
%
% v1.0.0 - 28/04/2011
% Marcello Ferro <[e-mail]>
% http://www.ilc.cnr.it
%