findobj find an object with specified property

## Syntax

                h = findobj()
                h = findobj(propertyName, propertyValue)
                h = findobj(propertyName, propertyValue, operator, propertyName, propertyValue, ...)
                h = findobj("-property", propertyName, ...)
                h = findobj(searchHandles, ...)
                h = findobj(..., '-depth', d, ...)
                h = findobj(..., '-flat', ...)

## Arguments

propertyName

  string character Name of the property to test (case unsensitive).

propertyValue

  character string specify the value the tested property should be equal to (case sensitive).

operator

  character string belonging to the set {"-and", "-or", "-not"}.

searchHandles

  Vector of graphic handles where the search is restricted to.

d

  positive integer, the depth of the search.

h

  handles of the found objects.

## Description

Without arguments `findobj` returns handles of all graphic objects and their descendants. If such an object does not exist, the function returns an empty matrix.

`findobj(propertyName, propertyValue, ...)` returns the handles of objects having the property `propertyName` set to `propertyValue`. If successive property/vaue pairs are given the handles of objects verifing all conditions are returned, i.e. there is an implicit `"-and"` operator between pairs. Another operator can be explicitely given with `findobj(propertyName, propertyValue, operator, propertyName, propertyValue, ...)`.

The priority of evaluations in a composite condition using operators can be controlled by using a cell argument, e.g. `findobj({propertyName, propertyValue, ...}, operator, ...)`

`findobj("-property", propertyName, ...)` returns the handles of objects having the property `propertyName`. Other conditions can be added.

By default the search is done within all figures and `findobj(searchHandles, ...)` restricts the search to the given handles. The depth of the search is by default infinite and can be restricted by `findobj(searchHandles, '-depth', d, ...)`. A value of 0 restricts the search to objects given in `searchHandles` and does not search within descendants, this is equivalent to the `"flat"` optional string.

## Examples

    // Create a figure
    h=scf();
    // Put a text in the figure
    uicontrol(h, "style","text", ...
                 "string","This is a figure", ...
                 "position",[50 70 100 100], ...
                 "fontsize",15, ...
                 "tag","Alabel");
    // Find the object which "tag" value is "Alabel"
    lab=findobj("tag","Alabel");
    disp("The text of the label is """+lab.string+"""");

    // Create a figure
    h=scf();
    // plot something
    plot()
    xlabel abscissae
    ylabel ordinate
    title "a plot"
    legend "c1" "c2" "c3"

    // Find the objects having a "font_size" property
    h1 = findobj("-property","font_size")
    // Change the font size of all text objects
    h1.font_size = 3

    // Find the objects having a "thickness" property
    h2 = findobj("-property","thickness")
    // Change the thickness of such objects
    h2.thickness = 2

## See also

- uicontrol
- uimenu
- set
- get