tree widget

  • 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.utils.widget.tree_widget.AlternatingRowDelegate(row_height: int, scrollbar_spacing: bool = True)

Bases: omni.ui._ui.AbstractItemDelegate

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

Constructs AbstractItemDelegate.

kwargs : dict

See below

### Keyword Arguments:

build_branch(self: omni.ui._ui.AbstractItemDelegate, model: omni.ui._ui.AbstractItemModel, item: omni.ui._ui.AbstractItem = None, column_id: int = 0, level: int = 0, expanded: bool = False) → None

This pure abstract method must be reimplemented to generate custom collapse/expand button.

build_widget(self: omni.ui._ui.AbstractItemDelegate, model: omni.ui._ui.AbstractItemModel, item: omni.ui._ui.AbstractItem = None, index: int = 0, level: int = 0, expanded: bool = False) → None

This pure abstract method must be reimplemented to generate custom widgets for specific item in the model.

property default_attr: dict[str, None]
destroy()
class omni.flux.utils.widget.tree_widget.AlternatingRowItem(index: int)

Bases: omni.ui._ui.AbstractItem

__init__(self: omni.ui._ui.AbstractItem) → None
property alternate: bool
property default_attr: dict[str, None]
destroy()
class omni.flux.utils.widget.tree_widget.AlternatingRowModel

Bases: omni.ui._ui.AbstractItemModel

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

Constructs AbstractItemModel.

kwargs : dict

See below

### Keyword Arguments:

abstract property default_attr: dict[str, None]
destroy()
get_item_children(self: omni.ui._ui.AbstractItemModel, parentItem: omni.ui._ui.AbstractItem = None) → List[omni.ui._ui.AbstractItem]

Returns the vector of items that are nested to the given parent item.

### Arguments:

id :

The item to request children from. If it’s null, the children of root will be returned.

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.

refresh(item_count: int)
class omni.flux.utils.widget.tree_widget.AlternatingRowWidget(header_height: int, row_height: int, scrollbar_spacing: bool = True, model: Optional[omni.flux.utils.widget.tree_widget.model.AlternatingRowModel] = None, delegate: Optional[omni.flux.utils.widget.tree_widget.delegate.AlternatingRowDelegate] = None)

Bases: object

__init__(header_height: int, row_height: int, scrollbar_spacing: bool = True, model: Optional[omni.flux.utils.widget.tree_widget.model.AlternatingRowModel] = None, delegate: Optional[omni.flux.utils.widget.tree_widget.delegate.AlternatingRowDelegate] = None)

A tree widget to be layered below another widget to create an alternating row effect.

Notes

When using this widget, make sure to:

  • Sync the frame height to make sure the entire frame is filled with alternating row backgrounds.

    The computed_content_size_changed_fn callback of the frame wrapping the foreground tree can be used

  • Sync the scroll position whenever the foreground tree’s scroll position changes.

    The scroll_y_changed_fn callback of the wrapping scrolling frame can be used to sync the scroll position

  • Refresh the widget whenever the number of items in the foreground tree changes.

    The subscribe_item_changed_fn callback of the Tree Model can be used to refresh the widget

Example

>>> def _on_content_size_changed(self):
>>>     self._alternating_row_widget.sync_frame_height(self._tree_widget.computed_height)
>>>
>>> def _on_item_changed(self):
>>>     # Expect self._tree_model.item_count to return the total number of items (recursively) in the model
>>>     self._alternating_row_widget.refresh(self._tree_model.item_count)
>>>
>>> def _build_ui(self):
>>>     with ui.ZStack():
>>>         # Build the AlternatingRowWidget
>>>         self._alternating_row_widget = AlternatingRowWidget(header_height, row_height)
>>>         # Build the Foreground TreeView wrapped in a ScrollingFrame
>>>         tree_scroll_frame = ui.ScrollingFrame(
>>>             computed_content_size_changed_fn=self._on_content_size_changed,
>>>             scroll_y_changed_fn=self._alternating_row_widget.sync_scrolling_frame,
>>>         )
>>>         with tree_scroll_frame:
>>>             self._tree_model = TreeModel(...)
>>>             self._tree_delegate = TreeDelegate(...)
>>>             self._item_changed_sub = self._tree_model.subscribe_item_changed_fn(self._on_item_changed)
>>>             self._tree_widget = ui.TreeView(
>>>                 self.tree.model,
>>>                 delegate=self.tree.delegate,
>>>             )
destroy()
refresh(item_count: int = 0)

Refresh the widget whenever the number of items in the foreground tree changes.

Parameters

item_count – The number of items in the foreground tree

sync_frame_height(frame_height: float)

Sync the frame height to make sure the entire frame is filled with alternating row backgrounds.

Parameters

frame_height – The height of the frame this widget should fill.

sync_scrolling_frame(position: float)

Sync the scroll position whenever the foreground tree’s scroll position changes.

Parameters

position – The new scroll position

class omni.flux.utils.widget.tree_widget.TreeDelegateBase

Bases: omni.ui._ui.AbstractItemDelegate

DEFAULT_IMAGE_ICON_SIZE = 24.000000px
__init__()

A base Delegate class to be overridden and used with the TreeWidget.

build_branch(model: _TreeModelBase, item: _TreeItemBase, column_id: int, level: int, expanded: bool)

Create a branch widget that opens or closes the subtree. To define the build function, override _build_branch.

build_header(column_id: int)

Create a header at the top of the tree. To define the build function, override _build_header.

build_widget(model: _TreeModelBase, item: _TreeItemBase, column_id: int, level: int, expanded: bool)

Create a widget per item. To define the build function, override _build_widget. This function wraps the widget in a frame with an on-click listener.

abstract property default_attr: dict[str, None]
destroy()
property selection: list['_TreeItemBase']

Get the currently selected items

subscribe_context_menu_shown(function: Callable[[_TreeModelBase, _TreeItemBase], None])

Return the object that will automatically unsubscribe when destroyed.

subscribe_item_clicked(function: Callable[[bool, _TreeModelBase, _TreeItemBase], None])

Return the object that will automatically unsubscribe when destroyed.

subscribe_item_expanded(function)

Return the object that will automatically unsubscribe when destroyed.

class omni.flux.utils.widget.tree_widget.TreeItemBase(children: Optional[list['TreeItemBase']] = None)

Bases: omni.ui._ui.AbstractItem

__init__(children: Optional[list['TreeItemBase']] = None)

A base Item class to be overridden and used with the TreeWidget.

abstract property can_have_children: bool
property children: list['TreeItemBase']
abstract property default_attr: dict[str, None]
destroy()
class omni.flux.utils.widget.tree_widget.TreeModelBase

Bases: omni.ui._ui.AbstractItemModel, Generic[omni.flux.utils.widget.tree_widget.model.T]

__init__()

A base Model class to be overridden and used with the TreeWidget.

can_item_have_children(self: omni.ui._ui.AbstractItemModel, parentItem: omni.ui._ui.AbstractItem = None) → bool

Returns true if the item can have children. In this way the delegate usually draws +/- icon.

### Arguments:

id :

The item to request children from. If it’s null, the children of root will be returned.

abstract property default_attr: dict[str, None]
destroy()
iter_items_children(items: Optional[Iterable[omni.flux.utils.widget.tree_widget.model.T]] = None, recursive=True) → Iterable[omni.flux.utils.widget.tree_widget.model.T]

Iterate through a collection of items’ children

Parameters

  • items – The collection of items to get children from

  • recursive – Whether to get the children recursively or only the direct children

class omni.flux.utils.widget.tree_widget.TreeWidget(model: _TreeModelBase, delegate: _TreeDelegateBase, select_all_children: bool = True, validate_action_selection: bool = True, **kwargs)

Bases: omni.ui._ui.TreeView

__init__(model: _TreeModelBase, delegate: _TreeDelegateBase, select_all_children: bool = True, validate_action_selection: bool = True, **kwargs)

A tree widget that extends the built-in ui.TreeView.

Parameters

  • model – The tree widget’s model

  • delegate – The tree widget’s delegate

  • select_all_children – Whether the tree should select all children items when selecting a parent item or not

  • validate_action_selection – Whether the selection should be validated & updated to include the item being right-clicked on or not

  • kwargs – The same arguments ui.TreeView exposes

abstract property default_attr: dict[str, None]
destroy(self: omni.ui._ui.Widget) → None

Removes all the callbacks and circular references.

iter_visible_children(items=None, recursive: bool = True)

Iterate through expanded children of items

Parameters

  • items – The collection of items to get children from

  • recursive – Whether to get the children recursively or only the direct children

on_selection_changed(items: list[_TreeItemBase])

Function to be called whenever the tree widget selection widget changes (set_selection_changed_fn).

The base implementation selects children when selecting a parent if _select_all_children is True

Parameters

items – The list of items selected

subscribe_selection_changed(callback: Callable[[list[_TreeItemBase]], None]) → _EventSubscription