findobj (MATLAB Functions)

Locate graphics objects with specific properties

Syntax

h = findobj
h = findobj('PropertyName',PropertyValue,...)
h = findobj('PropertyName',PropertyValue,'-logicaloperator',
                       'PropertyName',PropertyValue,...)
h = findobj('-regexp','PropertyName','regexp',...)
h = findobj('-property','PropertyName')
h = findobj(objhandles,...)
h = findobj(objhandles,'-depth',d,...)
h = findobj(objhandles,'flat','PropertyName',PropertyValue,...)

Description

findobj locates graphics objects and returns their handles. You can limit the search to objects with particular property values and along specific branches of the hierarchy.

h = findobj returns the handles of the root object and all its descendants.

h = findobj('PropertyName',PropertyValue,...) returns the handles of all graphics objects having the property PropertyName, set to the value PropertyValue. You can specify more than one property/value pair, in which case, findobj returns only those objects having all specified values.

h = findobj('PropertyName',PropertyValue,'-logicaloperator', PropertyName',PropertyValue,...) applies the logical operator to the property value matching. Possible values for -logicaloperator are:

-and
-or
-xor
-not

See the Examples section for examples of how to use these operators. See Logical Operators for an explanation of logical operators.

h = findobj('-regexp','PropertyName','regexp',...) matches objects using regular expressions as if the value of the property PropertyName was passed to the regexp function as

```
regexp(PropertyValue,'regexp')
```

If a match occurs, findobj returns the object's handle. See the regexp function for information on how MATLAB uses regular expressions.

h = findobj('-property','PropertyName') finds all objects having the specified property.

h = findobj(objhandles,...) restricts the search to objects listed in objhandles and their descendants.

h = findobj(objhandles,'-depth',d,...) specified the depth of the search. The depth argument d controls how many levels under the handles in objhandles are traversed. Specifying d as inf to get the default behavior of all levels. Specify d as 0 to get the same behavior as using the flat argument.

h = findobj(objhandles,'flat','PropertyName',PropertyValue,...) restricts the search to those objects listed in objhandles and does not search descendants.

Remarks

findobj returns an error if a handle refers to a nonexistent graphics object.

findobj correctly matches any legal property value. For example,

```
findobj('Color','r')
```

finds all objects having a Color property set to red, r, or [1 0 0].

When a graphics object is a descendant of more than one object identified in objhandles, MATLAB searches the object each time findobj encounters its handle. Therefore, implicit references to a graphics object can result in its handle being returned multiple times.

Examples

Find all line objects in the current axes:

```
h = findobj(gca,'Type','line')
```

Find all objects having a Label set to 'foo' and a String set to 'bar':

h = findobj('Label','foo','-and','String','bar');

Find all objects whose String is not 'foo' and is not 'bar':

h = findobj('-not','String','foo','-not','String','bar');

Find all objects having a String set to 'foo' and a Tag set to 'button one' and whose Color is not 'red' or 'blue':

h = findobj('String','foo','-and','Tag','button one',...
    '-and','-not',{'Color','red','-or','Color','blue'})

Find all objects for which you have assigned a value to the Tag property (that is, the value is not the empty string ''):

```
h = findobj('-regexp','Tag','[^'']')
```

Find all children of the current figure that have their BackgroundColor property set to a certain shade of gray ([.7 .7 .7]). Note that this statement also searches the current figure for the matching property value pair.

h = findobj(gcf,'-depth',1,'BackgroundColor',[.7 .7 .7])

See Also

copyobj, gcf, gca, gcbo, gco, get, regexp, set

See Example -- Using Logical Operators and Regular Expressions for more examples.

Finding and Identifying Graphics Objects for related functions

findobj findstr