omni.flux.utils.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.

omni.flux.utils.widget.background_pattern.create_widget_with_pattern( widget: Callable | partial, background_name: str, v_pattern_loop: int = 3, h_pattern_loop: int = 3, image_size: int = 256, height: Length | None = None, width: Length | None = None, background_margin: tuple[int, int] | None = None, pattern_image_name: str = 'TreePanelLinesBackground', pattern_background_rectangle_name: str = 'WorkspaceBackground', widget_margin: tuple[int, int] | None = None, )#

Create a widget with a pattern as a background

Parameters:

widget – the function that will create the widget, like ui.Widget
background_name – the name of the rectangle used as a background of the widget
v_pattern_loop – the number of time the pattern will loop vertically
h_pattern_loop – the number of time the pattern will loop horizontally
image_size – the size of the pattern image
height – the height of the whole ui widget
width – the width of the whole ui widget
background_margin – margin of the whole ui widget
pattern_image_name – image name to use for the pattern
pattern_background_rectangle_name – image name to use for the background rectangle of the pattern
widget_margin – margin of the given widget to create

Returns:

the created widget given by the “widget” arg

Return type:

ui.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.

omni.flux.utils.widget.button.create_button_from_widget( widget: Widget, on_clicked: Callable[[float, float, int, int], None], )#

Sets the mouse pressed/hovered/release button events to the given widget to give it button behavior.

Parameters:

widget – Widget that will have events added to it.
on_clicked – (optional) method that is fired with same arguments as ui.Widget.set_mouse_pressed_fn callback

omni.flux.utils.widget.button.create_button_with_custom_font( text: str, text_style_name: str, rectangle_style_name: str, height: Length, height_padding: Length, pressed_fn: Callable | None = None, ) → tuple[ByteImageProvider, Rectangle]#

Create a button with a text that has a custom font

Parameters:

text – the text to show
text_style_name – the style name of the text label
rectangle_style_name – the style name of the background rectangle
height – the height of the button
height_padding – padding between the top of the button, the text, and the bottom
pressed_fn – function that will be called when the button if pressed

Returns:

The image ui widget that contains the text and the background rectangle ui widget

omni.flux.utils.widget.button.create_button_with_label_style( text: str, text_style_name: str, rectangle_style_name: str, on_clicked: Callable[[float, float, int, int], None] | None = None, ) → tuple[Label, Rectangle]#

Create a button with a text that have a custom style

Parameters:

text – the text to show
text_style_name – the style name of the text label
rectangle_style_name – the style name of the background rectangle
on_clicked – (optional) method that is fired with same arguments as ui.Widget.set_mouse_pressed_fn callback

Returns:

The label ui widget and the background rectangle ui 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.

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.

omni.flux.utils.widget.color.color_to_hex( color: tuple[float, float, float] | tuple[float, float, float, float], ) → int#: Convert float rgb to int

omni.flux.utils.widget.color.hex_to_color(hex_value: int) → tuple[int, int, int, int]#: Convert hex to RGBA

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.

omni.flux.utils.widget.file_pickers.file_picker.open_file_picker( title, callback: Callable[[str | list[str]], None], callback_cancel: Callable[[str | list[str]], None], apply_button_label: str = 'Select', current_file: str | None = None, fallback=False, file_extension_options: list[tuple[str, str]] | None = None, select_directory: bool = False, validate_selection: Callable[[str, str], bool] | Callable[[list[str]], bool] | None = None, validation_failed_callback: Callable[[str, str], None] | Callable[[list[str]], None] | None = None, bookmarks: dict[str, str] | None = None, allow_multi_selection: bool = False, )#

Open a file picker

Parameters:

title – title of the window
callback – function to execute when the user clicks on the select button. If allow_multi_selection is True, the input arg is a list of paths
callback_cancel – function to execute when the user clicks on the cancel button. If allow_multi_selection is True, the input arg is a list of paths
apply_button_label – The string to display in the “apply” button
current_file – current file to select when the window is opened. If unset, the file browser will open at the last known directory
fallback – if True and if the file picker has a current folder, a default folder will be shown when the window is opened
file_extension_options –

A list of filename extension options. Each list element is an (extension name,
description) pair.

Examples: ("*.usdc", "Binary format") or (".usd*", "USD format")
or ("*.png, *.jpg, *.exr", "Image format")
select_directory – whether the file picker is used to select a directory or a file
validate_selection – function to execute to validate the selected file/directory. If false, the window file will not be selected. If allow_multi_selection is True, the callback will take a list of file
validation_failed_callback – function to call if the selection validation returns False. If allow_multi_selection is True, the callback will take a list of file
bookmarks – Bookmarks to add to the file picker in the format { name: path }
allow_multi_selection – Allow multi file selection in picker

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.

omni.flux.utils.widget.gradient.create_checkerboard( width: int, height: int, cell_size: int = 4, ) → ndarray#

Create an RGBA checkerboard pattern (light/dark gray) for alpha previews.

Parameters:

width – Pixel width of the output image.
height – Pixel height of the output image.
cell_size – Size of each checker cell in pixels.

Returns:

A numpy.ndarray of shape (height, width, 4) and dtype uint8.

omni.flux.utils.widget.gradient.create_gradient( width: int, height: int, values1: tuple[int, ...], values2: tuple[int, ...], is_horizontal_list: tuple[bool, ...], ) → ndarray#

Create a gradient (like a RGBA) of any dimension

Parameters:

width – width of the gradient
height – height of the gradient
values1 – start values (like (0, 0, 0, 255)) of the gradient. Work with any dimension.
values2 – end values (like (255, 255, 255, 255)) of the gradient. Work with any dimension.
is_horizontal_list – horizontal or vertical gradient (like (True, True, True, True))

Returns:

The gradient values

omni.flux.utils.widget.gradient.create_gradient_1d( width: int, height: int, int1: int, int2: int, is_horizontal: bool, ) → ndarray#

Create a 1d gradient

Parameters:

width – width of the gradient
height – height of the gradient
int1 – start number of the gradient, like 0
int2 – end number of the gradient, like 255
is_horizontal – horizontal or vertical gradient

Returns:

The 1d gradient

omni.flux.utils.widget.gradient.create_multi_stop_gradient( width: int, height: int, stops: Sequence[tuple[float, tuple[int, int, int, int]]], ) → ndarray#

Create a horizontal RGBA gradient with multiple color stops.

Each stop is a (time, (r, g, b, a)) pair where time is in [0, 1] and the color channels are integers in [0, 255]. Stops must be sorted by time. The function linearly interpolates between adjacent stops to fill a (height, width, 4) uint8 array suitable for ui.ByteImageProvider.set_bytes_data.

If fewer than two stops are provided the entire image is filled with the single stop color (or transparent black when the list is empty).

Parameters:

width – Pixel width of the output image.
height – Pixel height of the output image.
stops – Sequence of (time, (r, g, b, a)) tuples sorted by time.

Returns:

A numpy.ndarray of shape (height, width, 4) and dtype uint8.

omni.flux.utils.widget.gradient.sample_gradient_at_time( stops: Sequence[tuple[float, tuple[float, float, float, float]]], time: float, ) → tuple[float, float, float, float]#

Sample a multi-stop gradient at a specific time using linear interpolation.

This is a shared utility function used both for rendering gradients and for sampling colors when adding new keyframes.

Parameters:

stops – Sequence of (time, (r, g, b, a)) tuples where time is in [0, 1] and color channels are floats in [0, 1]. Must be sorted by time.
time – The time position to sample at, in [0, 1].

Returns:

A tuple (r, g, b, a) with interpolated color values as floats in [0, 1].

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.hover.CursorShapesEnum(value)#

Enumeration of the cursor shapes.

Provides a simpler way for developers to define their desired cursor shape, since carb.windowing.CursorStandardShape is not a standard Python Enum - it’s a binding.

omni.flux.utils.widget.hover.hover_helper( widget: Widget, cursor_shape: CursorStandardShape | None = None, ) → None#

Adds hover actions for the specified widget.

The cursor will change to the cursor shape passed to the __init__() function, with a default of HAND. The shape must be one of the shapes defined in carb.windowing.CursorStandardShape; these are:

ARROW
CROSSHAIR
HAND
HORIZONTAL_RESIZE
IBEAM
VERTICAL_RESIZE

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.

omni.flux.utils.widget.label.create_label_with_font( text: str, style_name: str, remove_offset: bool = True, offset_divider: int = 1, max_width: int = 0, max_height: int = 0, custom_image_height: Length | None = None, font_size_multiply: float = 1.0, deferred: bool = False, multiline_if_max_width: bool = True, tooltip: str | None = None, quality_multiplier: int = 2, ext_name: str | None = None, rotation: Rotation | None = None, ) → tuple[ByteImageProvider, ImageWithProvider, Task | None]#

Create a label with a custom font

Parameters:

text – the text to show
style_name – the style name of the text label used with an ui.ImageWithProvider
remove_offset – remove the offset on the top and left of the text
offset_divider – divide the offset length on the top and left of the text
max_width – the max width of the final widget
max_height – the max height of the final widget
custom_image_height – set a custom height of the final widget
font_size_multiply – multiply the font size by this number
deferred – build the widget async
multiline_if_max_width – if max_width is specify and the text is longer, create a multiline
tooltip – tool tip to add on the widget
quality_multiplier – internal multiplier of the text size to have a better quality
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.
rotation – rotate the text or not

Returns:

The image provider, the image, and the task if “deferred” is True

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.

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.

omni.flux.utils.widget.resources.get_background_images(ext_name: str | None = None) → list[str]#

Get background image from a resource extension

Parameters:

name – the name of the background image to get (without the extension)
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.

Returns:

Path of the background image

omni.flux.utils.widget.resources.get_font_list(ext_name: str | None = None) → dict[str, str]#

Get font list from a resource extension

Parameters:: ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.
Returns:: Dictionary with the name of the font and the font path

omni.flux.utils.widget.resources.get_fonts(name: str, ext_name: str | None = None) → str | None#

Get font from a resource extension

Parameters:

name – the name of the font to get (without the extension)
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.

Returns:

Path of the font

omni.flux.utils.widget.resources.get_icons(name: str, ext_name: str | None = None) → str | None#

Get icon from a resource extension

Parameters:

name – the name of the icon to get (without the extension)
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.

Returns:

Path of the icon

omni.flux.utils.widget.resources.get_image(name: str, ext_name: str | None = None) → str | None#

Get image from a resource extension

Parameters:

name – the name of the image to get (without the extension)
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.

Returns:

Path of the image

omni.flux.utils.widget.resources.get_menubar_ignore_file(ext_name: str | None = None) → str | None#

Get menubar ignore file path from a resource extension

Parameters:: ext_name – the name of the resource extension. Defaults to /exts/omni.flux.utils.widget/default_resources_ext setting.
Returns:: Path of the menubar ignore file

omni.flux.utils.widget.resources.get_quicklayout_config( name: str, ext_name: str | None = None, ) → str | None#

Get QuickLayout layout JSON file path from a resource extension

Parameters:

name – the name of the layout to get (without the extension)
ext_name – the name of the resource extension. Defaults to /exts/omni.flux.utils.widget/default_resources_ext setting.

Returns:

Path of the layout

omni.flux.utils.widget.resources.get_test_data(name: str, ext_name: str | None = None) → str | None#

Get test data from a resource extension

Parameters:

name – the name of the data to get (without the extension). Can be “hello.usd” or “hello/hello.usd”
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.

Returns:

Path of test data

SPDX-FileCopyrightText: Copyright (c) 2026 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.scrolling_tree_view.ScrollingTreeWidget(

model: TreeModelBase,

delegate: TreeDelegateBase,

alternating_rows: bool = False,

header_height: int = 28,

row_height: int = 28,

select_all_children: bool = True,

frame_selection: bool = False,

validate_action_selection: bool = True,

expansion_caching: bool = False,

**kwargs,

)#

A scrollable tree widget with optional alternating row backgrounds.

This widget wraps TreeWidget with scroll handling, automatic content size updates, and optional alternating row visual effects.

Parameters:

model – The tree widget’s data model
delegate – The tree widget’s delegate for custom rendering
alternating_rows – Whether to display alternating row background colors
header_height – Height of the header row in pixels (default: 28)
row_height – Height of each data row in pixels (default: 28)
select_all_children – Whether selecting a parent item also selects all its children
frame_selection – Whether to automatically expand and scroll to items when the selection changes (default: False)
validate_action_selection – Whether to validate and update selection to include the right-clicked item
**kwargs – Additional arguments passed to the underlying ui.TreeView

property delegate: TreeDelegateBase#: The tree widget’s delegate for custom rendering.

dirty_widgets(*args, **kwargs)#: Mark the tree widget as dirty, forcing a redraw on the next frame.

async expand_to_items( items: Iterable[TreeItemBase], )#

Expand all parent items necessary to reveal the specified items.

Traverses each item’s ancestry and expands parents from root downward, ensuring proper render order. Waits two frames for UI updates.

Parameters:: items – The items whose parents should be expanded.

property height: Length#

Get or set the height of the scrolling tree widget.

This controls the height of the internal ScrollingFrame, allowing external resize manipulators to adjust the widget’s visible area.

Returns:: The current height of the scroll frame.

is_expanded(*args, **kwargs)#

Check if an item is currently expanded.

Parameters:: item – The tree item to check
Returns:: True if the item is expanded, False otherwise.

iter_visible_items( recursive=True, ) → Iterable[TreeItemBase]#

Iterate through all currently visible (expanded) items in the tree.

Yields items in breadth-first order, respecting the expansion state of parent items. Only items whose parents are expanded will be yielded.

Parameters:: recursive – If True, recursively yields children of expanded items. If False, yields only top-level items.
Yields:: TreeItemBase – Each visible item in breadth-first traversal order.

property model: TreeModelBase#: The tree widget’s data model.

on_selection_changed(*args, **kwargs)#

Handle selection changes in the tree widget.

This method is called when the tree selection changes and handles auto-selecting children when select_all_children=True. Pass-through to the underlying TreeWidget.

Parameters:: items – The list of newly selected items.

Note

When select_all_children=False, this is effectively a no-op. Typically called from a selection changed callback to ensure child selection behavior is applied.

async scroll_to_items( items: list[TreeItemBase], center_ratio: float = 0.2, )#

Scroll to reveal the first item in items.

Parameters:

items – The items to scroll to
center_ratio – where to frame first item (0.0: top, 0.5: center, 1.0: bottom)

property selection: list[TreeItemBase]#: The currently selected items in the tree.

set_expanded(item, expanded, recursive)#

Set the expansion state of an item.

Parameters:

item – The tree item to expand or collapse
expanded – True to expand, False to collapse
recursive – If True, also applies to all children

subscribe_selection_changed(*args, **kwargs)#

Subscribe to selection change events.

Parameters:

callback – Function called when selection changes, receives the list of currently selected items.

Returns:

Subscription handle. Keep a reference to: maintain the subscription; releasing it unsubscribes.

Return type:

EventSubscription

property visible: bool#

Get or set the visibility of the entire scrolling tree widget.

When set to False, hides the root frame which contains both the TreeWidget and any alternating row backgrounds. This is useful for showing loading overlays or temporarily hiding the tree.

Returns:: True if the widget is visible, False otherwise.

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.search.SearchItem( dir_path: str, file_entry: ListEntry, )#

property name: str#: The name as it appears in the widget

property path: str#: The full path that goes to usd when Drag and Drop

class omni.flux.utils.widget.search.SearchModel( search_text: str | None = None, current_dir: str | None = None, search_lifetime: str | None = None, )#

destroy()#: Called to cancel current search

property items: list[SearchItem]#: Should be implemented

omni.flux.utils.widget.search.create_search_widget( callback: Callable[[str], None], ) → _SearchWidget#

Create a widget with an input field to be able to do search

Parameters:: callback – the function that will be called when the used input a character in the field

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.text_to_image.Rotation(value)#: An enumeration.

omni.flux.utils.widget.text_to_image.generate_image_from_text( text: str, font_path: str, size: int, remove_offset: bool = True, offset_divider: int = 1, max_width: int = 0, max_height: int = 0, size_multiplier: float = 1, multiline_if_max_width: bool = True, ext_name: str | None = None, rotation: Rotation | None = None, )#

Generate an image from a text

Parameters:

text – the text to show
font_path – the font path
size – the size of the font to use
remove_offset – if True, it will remove the padding at the top of the font
offset_divider – to add more padding at the top
max_width – max width of the final text
max_height – max height of the final text
size_multiplier – multiply the font size
multiline_if_max_width – if the text is bigger than the max width, do multiline or not
ext_name – the name of the resource extension. If not specify, /exts/omni.flux.utils.widget/default_resources_ext setting will be used.
rotation – rotate the text or not

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.delegate.AlternatingRowDelegate( row_height: int, scrollbar_spacing: bool = True, )#

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.

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

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.

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.

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.item.AlternatingRowItem(index: int)#

A simple item used by AlternatingRowWidget to create alternating row backgrounds.

Each item knows its position (odd/even) to determine its background style.

Parameters:: index – The row index, used to determine if this is an alternating row.

class omni.flux.utils.widget.tree_widget.item.TreeItemBase( parent: TreeItemBase | None = None, )#

Base class for items displayed in a TreeWidget.

This class provides the fundamental tree structure with parent-child relationships, enabling hierarchical data representation. Items maintain bidirectional references to their parent and children, automatically managing relationship updates when items are reparented.

The internal children storage uses a dict (with None values) for O(1) lookups while preserving insertion order.

Subclasses should:

Override can_have_children to define if the item supports child items.
Override default_attr to add custom attributes that need cleanup on destroy.
Add custom properties like display_name, data, tooltip, etc.

abstract property can_have_children: bool#

Whether this item can have child items.

Subclasses must implement this property to indicate whether the item supports a hierarchical structure. This is used by the TreeWidget to determine whether to show expand/collapse controls.

Returns:: True if the item can contain children, False otherwise.

property children: list[TreeItemBase]#

The list of child items.

Returns a copy of the children list to prevent accidental mutation of the internal collection. The underlying storage is a dict for O(1) lookups.

Returns:: A list of child TreeItemBase instances.

clear_children()#

Remove all children from this item.

Iterates through all children and sets their parent to None, which automatically removes them from this item’s children collection.

property parent: TreeItemBase | None#

The parent item of this item.

Returns:: The parent TreeItemBase, or None if this is a root-level item.

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.model.AlternatingRowModel#

A model that provides alternating row items for visual background effects.

Used by AlternatingRowWidget to create a background layer with alternating row colors that syncs with a TreeWidget’s scroll position.

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.

class omni.flux.utils.widget.tree_widget.model.TreeModelBase#

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

This class provides core tree functionality including item management and iteration.

Subclasses should:

Override _build_item: Factory method to create new TreeItem instances.
Override default_attr to add custom attributes that need cleanup on destroy.

Example

>>> class MyModel(TreeModelBase):
...     def _build_item(self, identifier, data):
...         return MyTreeItem(identifier, data)
...
...     def _build_items(self):
...         for item_data in self.data:
...             tree_item = self._build_item(item_data.id, item_data)

can_item_have_children( item: T, ) → bool#

Determine whether an item can have children in the tree hierarchy.

Parameters:: item – The tree item to check.
Returns:: True if the item exists and can have children, False otherwise.

get_children_count( items: Iterable[T] | None = None, recursive=True, ) → int#

Count the number of items in the tree.

More efficient than len(list(iter_items_children())) as it avoids creating intermediate objects.

Parameters:

items – The items to count from. If None, counts from root items.
recursive – If True, includes all descendants. If False, counts only the provided items (or root items if items is None).

Returns:

The total number of items.

iter_items_children( items: Iterable[T] | None = None, recursive=True, ) → Iterable[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

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.widget.TreeWidget(

model: _TreeModelBase,

delegate: _TreeDelegateBase,

select_all_children: bool = True,

validate_action_selection: bool = True,

**kwargs,

)#

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

visible_descendant_count(item: _TreeItemBase) → int#: Count all visible (expanded) descendants of an item.