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.bookmark_tree.widget.BookmarkCollectionItem( title: str, data=None, children: List[ItemBase] | None = None, on_mouse_double_clicked_callback: Callable | None = None, )#

Bases: ItemBase

A collection item can hold other collections or some BookmarkItems

__init__( self: omni.ui._ui.AbstractItem, ) → None#

on_mouse_double_clicked()#: Callback for when the mouse is double-clicked on the item

class omni.flux.bookmark_tree.widget.BookmarkCollectionModel#

Bases: AbstractItemModel

The model’s implementation allows the addition of individual items but permanent additions/removals should be done through the collection functions (create_collection, add_item_to_collection, etc.) and refresh function to fetch the updated data.

__init__( self: omni.ui._ui.AbstractItemModel, ) → None#

Constructs AbstractItemModel.

kwargs : dict
See below

### Keyword Arguments:

abstract add_item_to_collection( item: Any, collection_key: str, use_undo_group: bool = True, ) → None#

Add an item reference to a collection

Parameters:

item – the item to add to the collection
collection_key – the key of the collection to be renamed
use_undo_group – Whether a new undo group should be used for the operation

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

abstract clear_collection( collection_key: str, use_undo_group: bool = True, ) → None#

Clear all the items referenced inside a collection

Parameters:

collection_key – the key of the collection to be cleared
use_undo_group – Whether a new undo group should be used for the operation

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

abstract create_collection( collection_name: str, parent: BookmarkCollectionItem | None, use_undo_group: bool = True, ) → str#

Create a collection. For USD this can be a UsdCollection, for files this can be a folder.

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

Parameters:

collection_name – the name of the collection to be created
parent – if this is None, the collection will be created as a root item, otherwise it will be created as a child of the parent.
use_undo_group – Whether a new undo group should be used for the operation

Returns:

A path to the created collection.

abstract delete_collection( collection_key: str, parent: BookmarkCollectionItem | None, use_undo_group: bool = True, ) → None#

Delete an existing collection

Parameters:

collection_key – the key of the collection to be deleted
parent – if this is not None, the item will also be removed from the parent’s references
use_undo_group – Whether a new undo group should be used for the operation

destroy()#

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.

abstract 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

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

abstract get_active_items() → List#

Get the currently active item. For USD this could be the selected viewport item, for files this could be the currently selected file/folder, etc.

Returns:: A list of all active items

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

abstract 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

abstract remove_item_from_collection( item: Any, collection_key: str, use_undo_group: bool = True, ) → None#

Remove a specific item from a collection

Parameters:

item – the item to remove from the collection
collection_key – the key of the collection to be renamed
use_undo_group – Whether a new undo group should be used for the operation

abstract rename_collection( collection_key: str, new_collection_name: str, parent: BookmarkCollectionItem | None, use_undo_group: bool = True, ) → None#

Rename a collection using a new collection name.

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

Parameters:

collection_key – the key of the collection to be renamed
new_collection_name – the new name to use for the collection
parent – if this is not None, the item’s reference will also be changed in the parent
use_undo_group – Whether a new undo group should be used for the operation

abstract set_active_items( items: List[ItemBase], ) → None#

Set the currently active item. For USD this could be the selected viewport item, for files this could be the currently selected file/folder, etc.

Parameters:: items – the items to set as active

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

subscribe_on_active_items_changed( function: Callable, )#

Subscribe to the on_active_items_changed event.

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

subscribe_on_bookmark_collection_double_clicked( function: Callable, )#

Subscribe to the on_bookmark_collection_double_clicked event.

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

subscribe_on_create_item_clicked( function: Callable, )#

Subscribe to the on_create_item_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.bookmark_tree.widget.BookmarkDelegate#

Bases: AbstractItemDelegate

__init__( self: omni.ui._ui.AbstractItemDelegate, ) → None#

Constructs AbstractItemDelegate.

kwargs : dict
See below

### Keyword Arguments:

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

build_widget(model, item, column_id, level, expanded)#: Create a model per item

destroy()#

property dragged_item: ItemBase | None#: The item currently getting dragged by the user.

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], secondary_items: List[ItemBase], all_items: List[ItemBase], ) → None#

Callback for when the tree widget selection changed.

Parameters:

primary_items – the selected items
secondary_items – the secondary selection items
all_items – all items in the model

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

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

Parameters:

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

subscribe_on_add_clicked(function: Callable)#

Subscribe to the on_add_clicked event.

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

subscribe_on_delete_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_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_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.

class omni.flux.bookmark_tree.widget.BookmarkItem( title: str, data=None, on_mouse_double_clicked_callback: Callable | None = None, )#

Bases: ItemBase

A bookmark item is held inside a BookmarkCollectionItem

__init__(self: omni.ui._ui.AbstractItem) → None#

class omni.flux.bookmark_tree.widget.BookmarkTreeWidget( model: BookmarkCollectionModel | None = None, delegate: BookmarkDelegate | None = None, )#

Bases: object

__init__( model: BookmarkCollectionModel | None = None, delegate: BookmarkDelegate | None = None, )#

destroy()#

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.

class omni.flux.bookmark_tree.widget.ComponentTypes(value)#

Bases: Enum

The indexes prefixing the names are used to sort by component type.

bookmark_collection = '0 - BookmarkCollection'#

bookmark_item = '1 - BookmarkItem'#

create_collection = '2 - CreateCollection'#

class omni.flux.bookmark_tree.widget.CreateBookmarkItem( on_mouse_clicked_callback: Callable | None = None, )#

Bases: ItemBase

An item that is used to create new bookmark collections. This looks like a ‘Create a new bookmark…’ button

__init__(self: omni.ui._ui.AbstractItem) → None#

on_mouse_clicked()#: Callback for when the mouse is clicked on the item

class omni.flux.bookmark_tree.widget.ItemBase#

Bases: AbstractItem

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

__init__(self: omni.ui._ui.AbstractItem) → None#

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 component_type: str | None#

The item’s component type.

Use this attribute to set a “type/category” of your item. This attribute can be used in the delegate as a style for the branch icon like: f”TreeViewBranch{item.component_type}”.

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

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.

on_mouse_double_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.bookmark_tree.widget.TemporaryBookmarkModel(placeholder: str)#

Bases: AbstractValueModel

__init__( self: omni.ui._ui.AbstractValueModel, ) → None#

Constructs AbstractValueModel.

kwargs : dict
See below

### Keyword Arguments:

destroy()#

get_value_as_string( self: omni.ui._ui.AbstractValueModel, ) → str#: Return the string representation of the value.

property is_valid: bool#

set_value(*args, **kwargs)#

Overloaded function.

set_value(self: omni.ui._ui.AbstractValueModel, value: bool) -> None

Set the value.

set_value(self: omni.ui._ui.AbstractValueModel, value: int) -> None

Set the value.

set_value(self: omni.ui._ui.AbstractValueModel, value: float) -> None

Set the value.

set_value(self: omni.ui._ui.AbstractValueModel, value: str) -> None

Set the value.

subscribe_on_value_changed_callback(function)#

Subscribe to the on_value_changed_callback event.

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