ishghandle’s undocumented input parameter

Two weeks ago I wrote about Matlab Handle Graphics (HG) undocumented acceptance of structs as input parameter to some plotting functions. Continuing in a related matter, today I expose an undocumented input parameter for HG’s ishghandle function.

ishghandle is a fully-documented built-in Matlab function that returns a logical flag indicating whether the specified input is a valid HG handle or not. The input could be an invalid handle for several reasons: Perhaps it is not an HG handle in the first place, or perhaps the corresponding HG object has since been deleted (for example, its parent figure window was closed). The usage is very simple:

if ishghandle(myHandle)
    set(myHandle, ...);
end

But what if myHandle could be any of several possible HG types (e.g., plot line, patch or 3D surface) and our logic depends on the type? Of course, we could always add an extra condition to the logic:

if ishghandle(myHandle) && strcmp(get(h,'type'),'surface')
%or: if ishghandle(myHandle) && isa(handle(h),'surface')
    set(myHandle, ...);
end

There’s an undocumented alternative: we can simply specify the expected type as a second input argument to ishghandle. This is in fact the simplest and fastest alternative:

if ishghandle(myHandle,'surface')
    set(myHandle, ...);
end

If the second input argument is specified, then ishghandle will only return true if both (1) the input handle is a valid HG handle and (2) if its type is the specified second input argument. ishghandle‘s second input arg is case in-sensitive, so we can enter either ‘surface’, ‘Surface’ or ‘SURFACE’ (unlike the isa function, which is case-sensitive for some unknown reason).

I’ve first came across this ishghandle feature in a post by Sam Roberts. While the second-arg syntax is not very common in the Matlab code corpus, it does appear in several dozen places, for example:

• %matlabroot%/toolbox/matlab/graph2d/plotedit.m: if any(ishghandle(varargin{1}, 'figure'))
• %matlabroot%/toolbox/matlab/graph2d/subplot.m: if ~ishghandle(h, 'axes')
• %matlabroot%/toolbox/matlab/graph3d/camlight.m: ...any(ishghandle(args{1},'light'))
• %matlabroot%/toolbox/matlab/graph3d/colordef.m: ...~ishghandle(arg1, 'figure') && ~ishghandle(arg1, 'root')
• %matlabroot%/toolbox/matlab/graph3d/objbounds.m: if (ishghandle(h(i),'surface') || ishghandle(h(i),'line') || ishghandle(h(i),'image'))
• %matlabroot%/toolbox/matlab/graph3d/objbounds.m: elseif ishghandle(h(i),'patch')
• %matlabroot%/toolbox/matlab/graphics/@graphics/@pan/schema.m: ... ~ishghandle(valueProposed,'uicontextmenu')
• %matlabroot%/toolbox/matlab/scribe/selectobject.m: if ~ishghandle(obj,'axes') && ~ishghandle(obj,'figure') && ~ishghandle(obj,'uipanel')
• %matlabroot%/toolbox/matlab/uitools/@uitools/@uimode/createuimode.m: ... ishghandle(figureState.LastObject,'uicontrol') || ishghandle(figureState.LastObject,'uitable')
• %matlabroot%/toolbox/matlab/uitools/private/javacomponentundoc_helper.m: ishghandle(hParent, 'uicontainer') || ishghandle(hParent, 'uiflowcontainer') || ishghandle(hParent, 'uigridcontainer') ... ishghandle(hParent, 'uitoolbar') ... ishghandle(hParent, 'uisplittool') || ishghandle(hParent, 'uitogglesplittool') ... ishghandle(hParent, 'hgjavacomponent')
• %matlabroot%/toolbox/matlab/uitools/winmenu.m: ... ~ishghandle(h,'uimenu')
• %matlabroot%/toolbox/matlab/guide/guidemfile.m: mychildren(ishghandle(mychildren,'hggroup')) = [];

Did you happen to notice any other stock Matlab function with undocumented input arguments? If so, please write a short comment about it below.