enaml.core.object

Functions

flag_property

A factory function which creates a flag accessor property.

Classes

Object

The most base class of the Enaml object hierarchy.

enaml.core.object.flag_property(flag)[source]

A factory function which creates a flag accessor property.

class enaml.core.object.Object(parent=None, **kwargs)[source]

Bases: Atom

The most base class of the Enaml object hierarchy.

An Enaml Object provides supports parent-children relationships and provides methods for navigating, searching, and destroying the tree.

name

An optional name to give to this object to assist in finding it in the tree (see . the ‘find’ method). There is no guarantee of uniqueness for an object name. It is left to the developer to choose an appropriate name.

property parent

The read-only property which returns the object parent. This will be an Object or None. Use ‘set_parent()’ or pass the parent to the constructor to set the parent of an object.

property children

A read-only property which returns the object children. This is a list of Object instances. User code should not modify the list directly. Instead, use ‘set_parent()’ or ‘insert_children()’.

property is_destroyed

A property which gets and sets the destroyed flag. This should not be manipulated directly by user code.

destroyed

An event fired when an object has been destroyed. It is triggered once during the object lifetime, just before the object is removed from the tree structure.

__init__(parent=None, **kwargs)[source]

Initialize an Object.

Parameters:
  • parent (Object or None, optional) – The Object instance which is the parent of this object, or None if the object has no parent. Defaults to None.

  • **kwargs – Additional keyword arguments to apply as attributes to the object.

destroy()[source]

Destroy this object and all of its children recursively.

This will emit the destroyed event before any change to the object tree is made. After this returns, the object should be considered invalid and should no longer be used.

set_parent(parent)[source]

Set the parent for this object.

If the parent is not None, the child will be appended to the end of the parent’s children. If the parent is already the parent of this object, then this method is a no-op. If this object already has a parent, then it will be properly reparented.

Parameters:

parent (Object or None) – The Object instance to use for the parent, or None if this object should be unparented.

Notes

It is the responsibility of the caller to initialize and activate the object as needed, if it is reparented dynamically at runtime.

insert_children(before, insert)[source]

Insert children into this object at the given location.

The children will be automatically parented and inserted into the object’s children. If any children are already children of this object, then they will be moved appropriately.

Parameters:
  • before (Object, int or None) – A child object or int to use as the marker for inserting the new children. The new children will be inserted before this marker. If the Object is None or not a child, or if the int is not a valid index, then the new children will be added to the end of the children.

  • insert (iterable) – An iterable of Object children to insert into this object.

Notes

It is the responsibility of the caller to initialize and activate the object as needed, if it is reparented dynamically at runtime.

parent_changed(old, new)[source]

A method invoked when the parent of the object changes.

This method is called when the parent on the object has changed, but before the children of the new parent have been updated. Sublasses may reimplement this method as required.

Parameters:
  • old (Object or None) – The old parent of the object.

  • new (Object or None) – the new parent of the object.

child_added(child)[source]

A method invoked when a child is added to the object.

Sublasses may reimplement this method as required.

Parameters:

child (Object) – The child added to this object.

child_moved(child)[source]

A method invoked when a child is moved in the object.

Sublasses may reimplement this method as required.

Parameters:

child (Object) – The child moved in this object.

child_removed(child)[source]

A method invoked when a child is removed from the object.

Sublasses may reimplement this method as required.

Parameters:

child (Object) – The child removed from the object.

root_object()[source]

Get the root object for this hierarchy.

Returns:

result – The top-most object in the hierarchy to which this object belongs.

Return type:

Object

traverse(depth_first=False)[source]

Yield all of the objects in the tree, from this object down.

Parameters:

depth_first (bool, optional) – If True, yield the nodes in depth first order. If False, yield the nodes in breadth first order. Defaults to False.

traverse_ancestors(root=None)[source]

Yield all of the objects in the tree, from this object up.

Parameters:

root (Object, optional) – The object at which to stop traversal. Defaults to None.

find(name, regex=False)[source]

Find the first object in the subtree with the given name.

This method will traverse the tree of objects, breadth first, from this object downward, looking for an object with the given name. The first object with the given name is returned, or None if no object is found with the given name.

Parameters:
  • name (string) – The name of the object for which to search.

  • regex (bool, optional) – Whether the given name is a regex string which should be matched against the names of children instead of tested for equality. Defaults to False.

Returns:

result – The first object found with the given name, or None if no object is found with the given name.

Return type:

Object or None

find_all(name, regex=False)[source]

Find all objects in the subtree with the given name.

This method will traverse the tree of objects, breadth first, from this object downward, looking for a objects with the given name. All of the objects with the given name are returned as a list.

Parameters:
  • name (string) – The name of the objects for which to search.

  • regex (bool, optional) – Whether the given name is a regex string which should be matched against the names of objects instead of testing for equality. Defaults to False.

Returns:

result – The list of objects found with the given name, or an empty list if no objects are found with the given name.

Return type:

list of Object