Main Content

guihandles

Retrieve child objects of figure

collapse all in page

Syntax

s = guihandles(obj)
s = guihandles

Description

Note

Locating child objects of a figure with findobj or findall is recommended over using guihandles. The recommended functions enable you to control the types of objects that are returned using specific property values or regular expressions. For more information about retrieving child objects of a graphics object, see Find Objects.

s = guihandles(obj) returns child objects of a figure that have a nonempty Tag property.

  • If obj is a Figure object, guihandles returns child objects of the specified figure.

  • If obj is a graphics object in a figure, guihandles returns the child objects of the figure that contains obj.

example

s = guihandles returns all child objects that have a nonempty Tag property of the current figure. If no figure exists, MATLAB® creates a new figure and sets it as the current figure.

Examples

collapse all

First, create a UI figure and add UI components to it.

f = uifigure;
p = uipanel(f,"Position",[80 10 450 400]);
b1 = uibutton(f,"Text","One","Position",[10 40 60 30]);
b2 = uibutton(f,"Text","Two","Position",[10 10 60 30]);
b3 = uibutton(p,"Text","Three","Position",[10 10 60 30]);

For some UI components, add a tag to the object by using the Tag property. 

p.Tag = "panel";
b1.Tag = "button";

Query the objects in the UI figure using the guihandles function. Because most UI components have an empty Tag property by default, only the panel p and button b1 are included in the output structure. The structure field names match the values of the Tag property of the child objects.

s = guihandles(f)

s = struct with fields:
    button: [1×1 Button]
     panel: [1×1 Panel]

Use the structure field names to access the UI components and specific component properties. For example, access the text displayed on the first button. 

s.button.Text
ans = 'One'

You can also pass a child component of a Figure object to guihandles to retrieve the child objects of the figure that contains the component. For example, passing the Panel object to the function returns the same structure. 

s2 = guihandles(p)
s2 = struct with fields:
    button: [1×1 Button]
     panel: [1×1 Panel]

Input Arguments

collapse all

Graphics object. You can specify a Figure object or any child object of a figure.

Output Arguments

collapse all

Objects in the figure with a nonempty Tag property, returned as a structure. The field names in the structure match the values of the Tag property of the UI components or graphics objects placed in the figure. guihandles does not return objects with Tag property values that are not valid variable names.

  • If only one object has a given Tag property, the value of the field associated with the tag contains the graphics object.

  • If multiple objects have the same Tag property, the value of the field associated with the tag contains a vector of graphics objects.

guihandles returns objects even if their HandleVisibility property is set to "off". For more information about hidden objects, see Prevent Access to Figures and Axes.

Version History

Introduced before R2006a

See Also

Functions

Topics