ancestor — Find a graphics object ancestor with a requested type.
ancestor returns the closest graphics handle whose object type matches the requested type name. The search includes the input object itself, follows the encoded handle parent chain, and returns an empty handle array when no match exists.
Syntax
p = ancestor(h, type)
p = ancestor(h, type, 'toplevel')Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
h | Any | Yes | — | Graphics handle or array of graphics handles to inspect. |
type | Any | Yes | — | Object type name or cell/string array of type names. |
option | StringScalar | No | — | Use 'toplevel' to return the highest matching ancestor. |
Returns
| Name | Type | Description |
|---|---|---|
p | Any | Matching graphics ancestor handle, or an empty handle array when none exists. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:ancestor:InvalidArgument | Arguments are missing, the type selector is invalid, or the option is not 'toplevel'. | ancestor: invalid argument |
How ancestor works
typecan be a character vector, string scalar, string array, or cell array of type names.ancestor(h, type)returns the nearest matching object, includinghitself when its type matches.ancestor(h, type, 'toplevel')returns the highest matching object among the requested types.- Invalid or non-graphics scalar handles return an empty handle array instead of throwing.
- Numeric handle arrays are processed elementwise and return the matching ancestor handles in a row vector; if no entries match, the result is empty.
- Supported graphics types include
root,figure,axes,numericruler,text,legend, and RunMat plot child types such asline,scatter,bar,surface,patch, andcontour.
Does RunMat run ancestor on the GPU?
ancestor performs no provider dispatch and does not gather or upload GPU arrays.
GPU memory and residency
ancestor only reads host-managed graphics handle metadata. It does not inspect, gather, or transform GPU-resident plot data.
Examples
Find the axes and figure for a plotted line
h = plot(1:3);
ax = ancestor(h, 'axes');
fig = ancestor(h, 'figure');Expected output:
ax and fig are graphics handlesChoose nearest or top-level match from multiple types
h = plot(1:3);
nearest = ancestor(h, {'axes','figure'});
top = ancestor(h, {'axes','figure'}, 'toplevel');Expected output:
nearest is the axes handle; top is the figure handleInspect a ruler handle
ax = gca;
xr = get(ax, 'XAxis');
ancestor(xr, 'numericruler')Expected output:
ans = xrUsing ancestor with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ancestor changes the result.
Run a small ancestor example, explain the result, then change one input and compare the output.
FAQ
Does ancestor scan every plot object in the figure?⌄
No. RunMat graphics handles encode or snapshot their own object type and parent location, so ancestor builds the parent chain directly from handle metadata.
Why do array results use NaN for misses?⌄
No. Unmatched or invalid entries are omitted from array results. If none of the entries has a matching ancestor, ancestor returns an empty handle array.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · animatedline · axes · barh · cla · clf · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · textscatter · textscatter3 · triplot · waitbar · wordcloud · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how ancestor is executed, line by line, in Rust.
- View the source for ancestor in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.