Main Content

findobj

Class: handle

Find handle objects

expand all in page

Syntax

Hmatch = findobj(H)
Hmatch = findobj(H,property,value,...,property,value)
Hmatch = findobj(H,'-not',property,value)
Hmatch = findobj(H,'-regexp',property,expression)
Hmatch = findobj(H,property,value,logicaloperator,property,value)
Hmatch = findobj(H,'-function',fh)
Hmatch = findobj(H,'-function',property,fh)
Hmatch = findobj(H,'-class',class)
Hmatch = findobj(H,'-isa',class)
Hmatch = findobj(H,'-property',property)
Hmatch = findobj(H,'-method',methodname)
Hmatch = findobj(H,'-event',eventname)
Hmatch = findobj(H,'-depth',d,___)

Description

Hmatch = findobj(H) returns the objects listed in H and all of their descendants.

Hmatch = findobj(H,property,value,...,property,value) finds handle objects that have the specified property set to the specified value (compared using isequal).

Hmatch = findobj(H,'-not',property,value) inverts the expression in the following property value pair. That is, find objects whose specified property is not equal to value.

Hmatch = findobj(H,'-regexp',property,expression) uses the regular expression defined in expression to find properties with specific values. Not all classes supported the use of regular expression to find property values.

Hmatch = findobj(H,property,value,logicaloperator,property,value) applies the logical operator to the name/value pairs. Supported logical operators include:

  • '-or'

  • '-and' (default if you do not specify an operator)

  • '-xor'

Hmatch = findobj(H,'-function',fh) calls the function handle fh on the objects in H and returns the objects for which the function returns true.

Hmatch = findobj(H,'-function',property,fh) calls the function handle fh on the specified property’s value for the objects in H and returns the objects for which the function returns true. The function must return a scalar logical value.

Hmatch = findobj(H,'-class',class) finds all objects belonging to the specified class.

Hmatch = findobj(H,'-isa',class) finds all objects belonging to the specified class.

Hmatch = findobj(H,'-property',property) finds all object in H having the named property.

Hmatch = findobj(H,'-method',methodname) finds objects that have the specified method name.

Hmatch = findobj(H,'-event',eventname) finds objects that have the specified event name.

Hmatch = findobj(H,'-depth',d,___) specifies how many levels in the instance hierarchies under the objects in H to search.

Specify all -options as character vectors or string scalars.

Input Arguments

expand all

Objects to search from, specified as an array of object handles. Unless the you specify the '-depth' option, findobj searches the objects in the input array H and child objects in the instance hierarchy.

Property name, specified as case-sensitive, quoted text.

Data Types: char | string

Class of object to find, specified as case-sensitive, quoted text.

Data Types: char | string

Property value, specified as a value or MATLAB® expression.

Method name, specified as case-sensitive quoted text.

Data Types: char | string

Event name, specified as case-sensitive quoted text.

Data Types: char | string

Depth of search, specified as an integer indicating the number of levels below any given object in the input array H.

  • d = n — Search n levels of the hierarchy below each object in H

  • d = 0 — Search only the same level as the objects in H.

  • d = inf — Search all levels below objects in H. This is the default.

Function handle, specifying the function that is evaluated for each object in the input array H. This function must return a scalar, logical value indicating whether there is a match (true) or not (false).

Output Arguments

expand all

Objects found by search, returned as a handle array.

Attributes

Accesspublic

To learn about attributes of methods, see Method Attributes.

Examples

Object with Specific Property Value

Find the object with a specific property value. Given the handle class, BasicHandle:

classdef BasicHandle < handle
   properties
      Prop1
   end
   methods
      function obj = BasicHandle(val)
         if nargin > 0
            obj.Prop1 = val;
         end
      end
   end
end

Create an array of BasicHandle objects:

h(1) = BasicHandle(7);
h(2) = BasicHandle(11);
h(3) = BasicHandle(27);

Find the handle of the object whose Prop1 property has a value of 7:

h7 = findobj(h,'Prop1',7);
h7.Prop1

ans =

     7

Object with Specific Property Name

Find the object with a specific dynamic property. Given the button class:

classdef button < dynamicprops
   properties
      UiHandle
   end
   methods
      function obj = button(pos)
         if nargin > 0
            if length(pos) == 4
               obj.UiHandle = uicontrol('Position',pos,...
                'Style','pushbutton');
            else
               error('Improper position')
            end
         end
      end     
   end   
end

Create an array of button objects, only one element of which defines a dynamic property. Use findobj to get the handle of the object with the dynamic property named ButtonCoord:

b(1) = button([20 40 80 20]);
addprop(b(1),'ButtonCoord');
b(1).ButtonCoord = [2,3];
b(2) = button([120 40 80 20]);
b(3) = button([220 40 80 20]);

h =  findobj(b,'-property','ButtonCoord');
h.ButtonCoord

ans =

     2     3

Find Objects Using Regular Expressions

Find objects based on the value of object properties using regular expressions. While findobj has a -regexp options, not all classes support this option. This example uses the -function option to use a regular expression from a function as an alternative to the -regexp option.

This class defines a static method that builds an object array. Each object has a Name property that contains character representing the array element number.

classdef FindRegExpr < handle
    properties
        Name
    end
    methods (Static)
        function b = regXArray
            b = FindRegExpr.empty(0,50);
            for i = 1:50
                b(i).Name = sprintf('%d',i);
            end
        end
    end
end
A = FindRegExpr.regXArray;
a = 

  1×50 FindRegExpr array with properties:

    Name

Find the objects whose Name property contains a character vector beginning with the character '1'.

subArray = findobj(a, '-function', 'Name', @(x) ~isempty(regexp(x, '^1\d*')));
subArray = 

  11×1 testRegExpr array with properties:

    Name

Tips

  • findobj has access only to public members.

  • If there are no matches, findobj returns an empty array of the same class as the input array H.

  • Logical operator precedence follows MATLAB precedence rules. For more information, see Operator Precedence.

  • Control precedence by grouping within cell arrays

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2008a

See Also