15.3.4 Searching Properties

: h = findobj ()

: h = findobj (prop_name, prop_value, …)

: h = findobj (prop_name, prop_value, "-logical_op", prop_name, prop_value)

: h = findobj ("-property", prop_name)

: h = findobj ("-regexp", prop_name, pattern)

: h = findobj (hlist, …)

: h = findobj (hlist, "flat", …)

: h = findobj (hlist, "-depth", d, …)

Find graphics objects with specified properties.

When called without arguments, return all graphic objects beginning with the root object (0) and including all of its descendants.

The simplest form for narrowing the results is

findobj (prop_name, prop_value)

which returns the handles of all objects which have a property named prop_name that has the value prop_value. If multiple property/value pairs are specified then only objects meeting all of the conditions (equivalent to -and) are returned.

The search can be limited to a particular set of objects and their descendants, by passing a handle or set of handles hlist as the first argument.

The depth of the object hierarchy to search can be limited with the "-depth" argument. An example of searching through only three generations of children is:

findobj (hlist, "-depth", 3, prop_name, prop_value)

Specifying a depth d of 0 limits the search to the set of objects passed in hlist. A depth of 0 is also equivalent to the "flat" argument. The default depth value is Inf which includes all descendants.

A specified logical operator may be used between prop_name, prop_value pairs. The supported logical operators are: "-and", "-or", "-xor", "-not". Example code to locate all figure and axes objects is

findobj ("type", "figure", "-or", "type", "axes")

Objects may also be matched by comparing a regular expression to the property values, where property values that match regexp (prop_value, pattern) are returned.

Finally, objects which have a property name can be found with the "-property" option. For example, code to locate objects with a "meshstyle" property is

findobj ("-property", "meshstyle")

Implementation Note: The search only includes objects with visible handles (HandleVisibility = "on"). See findall, to search for all objects including hidden ones.

See also: findall, allchild, get, set.

: h = findall ()

: h = findall (prop_name, prop_value, …)

: h = findall (prop_name, prop_value, "-logical_op", prop_name, prop_value)

: h = findall ("-property", prop_name)

: h = findall ("-regexp", prop_name, pattern)

: h = findall (hlist, …)

: h = findall (hlist, "flat", …)

: h = findall (hlist, "-depth", d, …)

Find graphics object, including hidden ones, with specified properties.

The return value h is a list of handles to the found graphic objects.

findall performs the same search as findobj, but it includes hidden objects (HandleVisibility = "off"). For full documentation, see findobj.

See also: findobj, allchild, get, set.