API#

SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

class omni.flux.layer_tree.usd.widget.ItemBase#

Bases: TreeItemBase

Base Item of the model. This should not be used directly other than for typing, instead use one of the children classes.

__init__()#: A base Item class to be overridden and used with the TreeWidget.

append_child( child: ItemBase, sort: bool = True, ) → None#

Append a child to the item and set the child’s parent

Parameters:

child – the item to append
sort – whether the children should be sorted after appending the child

property can_have_children: bool#

Define if the item can have children or not.

Use this attribute to determine whether the item should have an expansion arrow or not in the delegate.

property children: List[ItemBase]#: The item’s children

clear_children() → None#: Clear all the item’s children

property data: Any#: Any data that the item needs to carry.

abstract property default_attr: dict[str, None]#

property enabled: bool#: Whether the item is enabled or not.

insert_child( child: ItemBase, index: int, ) → None#

Insert a child at a given index in the item’s children and set the child’s parent

Parameters:

child – the item to insert
index – the index at which to insert the child

on_key_pressed(key, pressed) → None#: Should be overridden by the inheriting class.

on_mouse_clicked() → None#: Should be overridden by the inheriting class.

property parent: ItemBase | None#: The item’s parent item. Not every item has a parent.

remove_child( child: ItemBase, ) → None#

Remove a child from the item’s children and reset the child’s parent

Parameters:: child – the item to remove

set_children( children: List[ItemBase], sort: bool = True, ) → None#

Set an item’s children and the children’s parent

Parameters:

children – the list of children to set
sort – whether the children should be sorted

property title: str#

The title is the property that will be displayed in the tree widget

The title is assumed to be unique inside the collection. This is true both for the collection title and the children item titles

class omni.flux.layer_tree.usd.widget.LayerDelegate#

Bases: TreeDelegateBase

__init__()#: A base Delegate class to be overridden and used with the TreeWidget.

build_branch( model: LayerModel, item: ItemBase, column_id, level, expanded, )#: Create a branch core that opens or closes subtree

abstract property default_attr: dict[str, None]#

destroy()#

get_scroll_frames()#

Get the scroll frames used in the delegates. This can be used to control the scrolling of the items externally.

Returns:: A list of the scroll frames displayed in the tree widget

on_item_selected( primary_items: List[ItemBase], all_items: List[ItemBase], model: LayerModel, ) → None#

Callback for when the tree widget selection changed.

Parameters:

primary_items – the selected items
all_items – all items in the model
model – the model

refresh_gradient_color( item: ItemBase, model: LayerModel, deferred: bool = True, ) → None#

Refresh the item gradient based on selection, hover state, etc.

Parameters:

item – the item to refresh
model – the model
deferred – whether the refresh should be deferred to a future frame

subscribe_on_export_clicked(function: Callable)#

Subscribe to the on_export_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_item_expanded(function: Callable)#

Subscribe to the on_item_expanded event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_lock_clicked(function: Callable)#

Subscribe to the on_lock_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_merge_clicked(function: Callable)#

Subscribe to the on_merge_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_remove_clicked(function: Callable)#

Subscribe to the on_remove_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_save_as_clicked(function: Callable)#

Subscribe to the on_save_as_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_save_clicked(function: Callable)#

Subscribe to the on_save_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_set_authoring_layer( function: Callable, )#

Subscribe to the on_set_authoring_layer event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_transfer_clicked( function: Callable, )#

Subscribe to the on_transfer_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

subscribe_on_visible_clicked(function: Callable)#

Subscribe to the on_visible_clicked event.

Parameters:: function – the callback to execute when the event is triggered
Returns:: An object that will automatically unsubscribe when destroyed.

class omni.flux.layer_tree.usd.widget.LayerItem( title: str, data: dict | None = None, parent: ItemBase | None = None, children: List[ItemBase] | None = None, )#

Bases: ItemBase

A layer item is held inside a LayerCollectionItem

__init__( title: str, data: dict | None = None, parent: ItemBase | None = None, children: List[ItemBase] | None = None, )#: A base Item class to be overridden and used with the TreeWidget.

abstract property default_attr: dict[str, None]#

class omni.flux.layer_tree.usd.widget.LayerModel( context_name: str = '', layer_creation_validation_fn: Callable[[str, str], bool] | None = None, layer_creation_validation_failed_callback: Callable[[str, str], None] | None = None, layer_import_validation_fn: Callable[[str, str], bool] | None = None, layer_import_validation_failed_callback: Callable[[str, str], None] | None = None, exclude_remove_fn: Callable[[], List[str]] | None = None, exclude_lock_fn: Callable[[], List[str]] | None = None, exclude_mute_fn: Callable[[], List[str]] | None = None, exclude_edit_target_fn: Callable[[], List[str]] | None = None, exclude_add_child_fn: Callable[[], List[str]] | None = None, exclude_move_fn: Callable[[], List[str]] | None = None, )#

Bases: TreeModelBase[ItemBase]

The model’s implementation allows the addition of individual items but these actions should be reserved for temporary items (such as a TemporaryLayerItem). Permanent additions/removals should be done through the layer functions (create_layer, set_layer_parent, etc.) and refresh function to fetch the updated data.

__init__( context_name: str = '', layer_creation_validation_fn: Callable[[str, str], bool] | None = None, layer_creation_validation_failed_callback: Callable[[str, str], None] | None = None, layer_import_validation_fn: Callable[[str, str], bool] | None = None, layer_import_validation_failed_callback: Callable[[str, str], None] | None = None, exclude_remove_fn: Callable[[], List[str]] | None = None, exclude_lock_fn: Callable[[], List[str]] | None = None, exclude_mute_fn: Callable[[], List[str]] | None = None, exclude_edit_target_fn: Callable[[], List[str]] | None = None, exclude_add_child_fn: Callable[[], List[str]] | None = None, exclude_move_fn: Callable[[], List[str]] | None = None, )#

Parameters:

context_name – the context name
layer_creation_validation_fn – a callback to validate the selected file before it’s created
layer_creation_validation_failed_callback – a callback called when the file creation validation fails. Can be used to display popups, log the error, etc.
layer_import_validation_fn – a callback to validate the selected file before it’s imported
layer_import_validation_failed_callback – a callback called when the file import validation fails. Can be used to display popups, log the error, etc.
exclude_remove_fn – list of layer identifiers to disallow removing
exclude_lock_fn – list of layer identifiers to disallow locking/unlocking
exclude_mute_fn – list of layer identifiers to disallow muting/unmuting
exclude_edit_target_fn – list of layer identifiers to disallow setting as edit target
exclude_add_child_fn – list of layer identifiers to disallow adding children sublayers
exclude_move_fn – list of layer identifiers to disallow moving (setting parent or index)

append_item( item: ItemBase, parent: ItemBase | None = None, sort: bool = False, force: bool = False, ) → None#

Append an item to display in the tree widget. If the parent argument is set this will append an item to the parent’s children.

Parameters:

item – the item to append to the tree widget’s item list
parent – if this is not None, the item will be appended to the parent’s children
sort – whether the items should be sorted after the item is appended
force – if duplicate items should be allowed to be appended

clear_items( parent: ItemBase | None = None, ) → None#

Clear all the items to be displayed in the tree widget. If the parent argument is set this will clear an item’s children.

Parameters:: parent – if this is not None, the parent’s children will be cleared

create_layer( create_or_insert: bool, parent: LayerItem | None = None, layer_created_callback: Callable[[str], None] | None = None, ) → None#

Note: The layer name could differ from the given one if the layer name was already in use. A unique name is generated for every entry

Parameters:

create_or_insert – if true, a layer will be created, otherwise an existing layer is inserted.
parent – the layer the new layer should be parented to. If null the layer will be parented to the root
layer_created_callback – callback called after the sublayer is inserted or created. Receives the path of the created layer as an argument.

abstract property default_attr: dict[str, None]#

delete_layer( layer: LayerItem, ) → None#

Delete an existing layer

Parameters:: layer – the layer to be deleted

destroy()#

disable_refresh(refresh_on_exit: bool = True)#: Disable refresh temporarily

drop(*args, **kwargs)#

Overloaded function.

drop(self: omni.ui._ui.AbstractItemModel, item_tagget: omni.ui._ui.AbstractItem, item_source: omni.ui._ui.AbstractItem, drop_location: int = -1) -> None

Called when the user droped one item to another. Small explanation why the same default value is declared in multiple places. We use the default value to be compatible with the previous API and especially with Stage 2.0. Thr signature in the old Python API is: def drop(self, target_item, source) drop(self, target_item, source) PyAbstractItemModel::drop AbstractItemModel.drop pybind11::class_<AbstractItemModel>.def(“drop”) AbstractItemModel

drop(self: omni.ui._ui.AbstractItemModel, item_tagget: omni.ui._ui.AbstractItem, source: str, drop_location: int = -1) -> None

Called when the user droped a string to the item.

drop_accepted(*args, **kwargs)#

Overloaded function.

drop_accepted(self: omni.ui._ui.AbstractItemModel, item_tagget: omni.ui._ui.AbstractItem, item_source: omni.ui._ui.AbstractItem, drop_location: int = -1) -> bool

Called to determine if the model can perform drag and drop to the given item. If this method returns false, the widget shouldn’t highlight the visual element that represents this item.

drop_accepted(self: omni.ui._ui.AbstractItemModel, item_tagget: omni.ui._ui.AbstractItem, source: str, drop_location: int = -1) -> bool

Called to determine if the model can perform drag and drop of the given string to the given item. If this method returns false, the widget shouldn’t highlight the visual element that represents this item.

enable_listeners(value: bool) → None#

If listeners are required in the model, enable/disable them based on the value given.

Parameters:: value – whether the listeners should be enabled or disabled

export_layer( layer: LayerItem, )#

Persist an existing layer in a new file but don’t replace it in the current stage

Parameters:: layer – the layer to be exported

find_item( value, comparison: Callable[[ItemBase, Any], bool], parent: ItemBase | None = None, ) → ItemBase#

Find an item displayed in the tree widget.

Parameters:

value – value to search for
comparison – the comparison that should be used to determine if the item is a match or not. Uses the value.
parent – items will be searched recursively from the parent to the last children. If this is None, the model root will be used as a base.

Returns:

The item displayed in the tree widget

get_drag_mime_data( self: omni.ui._ui.AbstractItemModel, item: omni.ui._ui.AbstractItem = None, ) → str#: Returns Multipurpose Internet Mail Extensions (MIME) for drag and drop.

get_item_children( parent: ItemBase | None = None, recursive: bool = False, ) → List[ItemBase]#

Get the model’s items or item’s children.

Parameters:

parent – if this is not None, it will return the parent’s children
recursive – whether the items should be listed recursively or only top-level

Returns:

The items in the model or children in the parent

get_item_index( item: ItemBase, parent: ItemBase | None = None, ) → int#

Get an item’s index.

Parameters:

item – item to search for
parent – items will be searched recursively from the parent to the last children. If this is None, the model root will be used as a base.

Returns:

The index of the item displayed in the tree widget

get_item_value_model_count( self: omni.ui._ui.AbstractItemModel, item: omni.ui._ui.AbstractItem = None, ) → int#: Returns the number of columns this model item contains.

get_items_count( parent: ItemBase | None = None, ) → int#

Get the number of items or children.

Parameters:: parent – if this is not None, it will return the number of children in the parent
Returns:: The number of items in the model or children in the parent

insert_item( item: ItemBase, index: int, parent: ItemBase | None = None, force: bool = False, ) → None#

Insert an item to display in the tree widget at a given index. If the parent argument is set this will insert an item in the parent’s children.

Parameters:

item – the item to insert in the tree widget’s item list
index – the index at which to insert the item
parent – if this is not None, the item will be inserted in the parent’s children
force – if duplicate items should be allowed to be inserted

is_layer_locked( layer: LayerItem, ) → bool#

Get the lock state of a layer item

Returns:: True if the layer is locked, False otherwise

is_layer_muted( layer: LayerItem, ) → bool#

Get the muteness state of a layer item

Returns:: True if the layer is muted, False otherwise

merge_layers( layers: List[LayerItem], )#

Merge the overrides located in multiple layers in a single layer. Only the layer with the strongest opinions will remain at the end of this operation.

Parameters:: layers – the layers to be merged

move_sublayer( layer: LayerItem, new_parent: LayerItem, item_position: int = -1, ) → None#

Set a new parent for an existing layer

Parameters:

layer – the layer to be moved
new_parent – the new layer’s parent
item_position – the index position of the layer

refresh() → None#: Force a refresh of the model.

remove_item( item: ItemBase, parent: ItemBase | None = None, ) → None#

Remove an item from the tree widget list. If the parent argument is set this will remove an item from the parent’s children.

Parameters:

item – the item to remove from the tree widget’s item list
parent – if this is not None, the item will be removed from the parent’s children

save_layer( layer: LayerItem, ) → None#

Persist an existing layer

Parameters:: layer – the layer to be saved

save_layer_as( layer: LayerItem, )#

Persist an existing layer in a new file and replace it in the current stage

Parameters:: layer – the layer to be saved

set_authoring_layer( layer: LayerItem, ) → None#

Set a new authoring layer

Parameters:: layer – the layer to be saved

set_items( items: List[ItemBase], parent: ItemBase | None = None, ) → None#

Set the items to be displayed in the tree widget. If the parent argument is set this will set an item’s children.

Parameters:

items – the items to display in the tree widget
parent – if this is not None, the parent’s children will be set

set_lock_layer( layer: LayerItem, value: bool, ) → None#

Parameters:

layer – the layer to be locked or unlocked
value – whether to lock or unlock the layer

set_mute_layer( layer: LayerItem, value: bool, ) → None#

Parameters:

layer – the layer to be muted or unmuted
value – whether to mute or unmute the layer

subscribe_refresh_completed(function)#: Return the object that will automatically unsubscribe when destroyed.

subscribe_refresh_started(function)#: Return the object that will automatically unsubscribe when destroyed.

toggle_lock_layer( layer: LayerItem, ) → None#

Parameters:: layer – the layer to be locked or unlocked

toggle_mute_layer( layer: LayerItem, ) → None#

Parameters:: layer – the layer to be muted or unmuted

transfer_layer_overrides( layer: LayerItem, existing_layer: bool, )#

Transfer the overrides of a layer in a sublayer. The sublayer can be an existing one or a new one.

Parameters:

layer – the layer to be saved
existing_layer – whether the layer exists or should be created

class omni.flux.layer_tree.usd.widget.LayerTreeWidget( context_name: str = '', model: LayerModel | None = None, delegate: LayerDelegate | None = None, height: int | None = None, expansion_default: bool = False, hide_create_insert_buttons: bool = False, )#

Bases: object

__init__( context_name: str = '', model: LayerModel | None = None, delegate: LayerDelegate | None = None, height: int | None = None, expansion_default: bool = False, hide_create_insert_buttons: bool = False, )#

destroy()#

on_selection_changed( items: list[ItemBase], )#

show(value: bool)#: Let the widget know if it’s visible or not. This will internally enable/disabled the USD listener to reduce the amount of resources used by the widget with it’s not visible.