(octave.info)Searching Properties

---

Next: Managing Default Properties Prev: Graphics Object Properties Up: Graphics Data Structures

---

Enter node , (file) or (file)node

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").  Note: findall, to
     search for all objects including hidden ones.

     See also: Note: findall, Note: allchild,
     Note: get, Note: 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,
     Note: findobj.

     See also: Note: findobj, Note: allchild,
     Note: get, Note: set.