findobj

Class: handle

Find handle objects

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

H — Objects to search from

handle array

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 — Property name

character vector | string scalar

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

Data Types: char | string

class — Class of object to find

character vector | string scalar

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

Data Types: char | string

value — Property value

any value

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

methodname — Method name

character vector | string scalar

Method name, specified as case-sensitive quoted text.

Data Types: char | string

eventname — Event name

character vector | string scalar

Event name, specified as case-sensitive quoted text.

Data Types: char | string

d — Depth of search

integer >= 0

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.

fh — Function handle

function handle

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

Hmatch — Objects found by search

handle array

Objects found by search, returned as a handle array.

Attributes

Access

public

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