API reference - Class LayerPropertiesIterator

Notation used in Ruby API documentation

Module: lay

Description: Layer properties iterator

This iterator provides a flat view for the layers in the layer tree if used with the next method. In this mode it will descend into the hierarchy and deliver node by node as a linear (flat) sequence.

The iterator can also be used to navigate through the node hierarchy using next_sibling, down_first_child, parent etc.

The iterator also plays an important role for manipulating the layer properties tree, i.e. by specifying insertion points in the tree for the LayoutView class.

Public constructors

new LayerPropertiesIterator ptrnewCreates a new object of this class

Public methods

[const]bool!=(const LayerPropertiesIterator other)Inequality
[const]bool<(const LayerPropertiesIterator other)Comparison
[const]bool==(const LayerPropertiesIterator other)Equality
[const]LayerPropertiesIterator ptr_const_castReturns a non-const reference to self.
void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidassign(const LayerPropertiesIterator other)Assigns another object to self
[const]boolat_end?At-the-end property
[const]boolat_top?At-the-top property
[const]unsigned longchild_indexReturns the index of the child within the parent
[const]LayerPropertiesNodeRefcurrentReturns a reference to the layer properties node that the iterator points to
LayerPropertiesIteratordown_first_childMove to the first child
LayerPropertiesIteratordown_last_childMove to the last child
[const]new LayerPropertiesIterator ptrdupCreates a copy of self
[const]LayerPropertiesIteratorfirst_childReturns the iterator pointing to the first child
[const]boolis_null?"is null" predicate
[const]LayerPropertiesIteratorlast_childReturns the iterator pointing behind the last child
LayerPropertiesIteratornextIncrement operator
LayerPropertiesIteratornext_sibling(long n)Move to the next sibling by a given distance
[const]unsigned longnum_siblingsReturn the number of siblings
[const]LayerPropertiesIteratorparentReturns the iterator pointing to the parent node
LayerPropertiesIteratorto_sibling(unsigned long n)Move to the sibling with the given index
LayerPropertiesIteratorupMove up

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

!=

Signature: [const] bool != (const LayerPropertiesIterator other)

Description: Inequality

other:The other object to compare against

<

Signature: [const] bool < (const LayerPropertiesIterator other)

Description: Comparison

other:The other object to compare against
Returns:true, if self points to an object that comes before other

==

Signature: [const] bool == (const LayerPropertiesIterator other)

Description: Equality

other:The other object to compare against

Returns true, if self and other point to the same layer properties node. Caution: this does not imply that both layer properties nodes sit in the same tab. Just their position in the tree is compared.

_const_cast

Signature: [const] LayerPropertiesIterator ptr _const_cast

Description: Returns a non-const reference to self.

Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects.

This method has been introduced in version 0.29.6.

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

assign

Signature: void assign (const LayerPropertiesIterator other)

Description: Assigns another object to self

at_end?

Signature: [const] bool at_end?

Description: At-the-end property

This predicate is true if the iterator is at the end of either all elements or at the end of the child list (if down_last_child or down_first_child is used to iterate).

at_top?

Signature: [const] bool at_top?

Description: At-the-top property

This predicate is true if there is no parent node above the node addressed by self.

child_index

Signature: [const] unsigned long child_index

Description: Returns the index of the child within the parent

This method returns the index of that the properties node the iterator points to in the list of children of its parent. If the element does not have a parent, the index of the element in the global list is returned.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

current

Signature: [const] LayerPropertiesNodeRef current

Description: Returns a reference to the layer properties node that the iterator points to

Starting with version 0.25, the returned object can be manipulated and the changes will be reflected in the view immediately.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

down_first_child

Signature: LayerPropertiesIterator down_first_child

Description: Move to the first child

This method moves to the first child of the current element. If there is no child, at_end? will be true. Even then, the iterator is sitting at the the child level and up can be used to move back.

down_last_child

Signature: LayerPropertiesIterator down_last_child

Description: Move to the last child

This method moves behind the last child of the current element. at_end? will be true then. Even then, the iterator points to the child level and up can be used to move back.

Despite the name, the iterator does not address the last child, but the position after that child. To actually get the iterator for the last child, use down_last_child and next_sibling(-1).

dup

Signature: [const] new LayerPropertiesIterator ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

first_child

Signature: [const] LayerPropertiesIterator first_child

Description: Returns the iterator pointing to the first child

If there is no children, the iterator will be a valid insert point but not point to any valid element. It will report at_end? = true.

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

is_null?

Signature: [const] bool is_null?

Description: "is null" predicate

This predicate is true if the iterator is "null". Such an iterator can be created with the default constructor or by moving a top-level iterator up.

last_child

Signature: [const] LayerPropertiesIterator last_child

Description: Returns the iterator pointing behind the last child

The iterator will be a valid insert point but not point to any valid element. It will report at_end? = true.

Despite the name, the iterator does not address the last child, but the position after that child. To actually get the iterator for the last child, use last_child and call next_sibling(-1) on that iterator.

new

Signature: [static] new LayerPropertiesIterator ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object.

next

Signature: LayerPropertiesIterator next

Description: Increment operator

The iterator will be incremented to point to the next layer entry. It will descend into the hierarchy to address child nodes if there are any.

next_sibling

Signature: LayerPropertiesIterator next_sibling (long n)

Description: Move to the next sibling by a given distance

The iterator is moved to the nth next sibling of the current element. Use negative distances to move backward.

num_siblings

Signature: [const] unsigned long num_siblings

Description: Return the number of siblings

The count includes the current element. More precisely, this property delivers the number of children of the current node's parent.

parent

Signature: [const] LayerPropertiesIterator parent

Description: Returns the iterator pointing to the parent node

This method will return an iterator pointing to the parent element. If there is no parent, the returned iterator will be a null iterator.

to_sibling

Signature: LayerPropertiesIterator to_sibling (unsigned long n)

Description: Move to the sibling with the given index

The iterator is moved to the nth sibling by selecting the nth child in the current node's parent.

up

Signature: LayerPropertiesIterator up

Description: Move up

The iterator is moved to point to the current element's parent. If the current element does not have a parent, the iterator will become a null iterator.