omni.kit.widget.filebrowser

Kit Filebrowser Widget.

The basic UI widget and set of supporting classes for navigating the filesystem through a tree view. The filesystem can either be from your local machine or the Omniverse server.

Example

With just a few lines of code, you can create a powerful, flexible tree view widget that you can embed into your view.

filebrowser = FileBrowserWidget(

“Omniverse”, layout=SPLIT_PANES, mouse_pressed_fn=on_mouse_pressed, selection_changed_fn=on_selection_changed, drop_fn=drop_handler, filter_fn=item_filter_fn,

)

Module Constants:

layout: {LAYOUT_SINGLE_PANE_SLIM, LAYOUT_SINGLE_PANE_WIDE, LAYOUT_SPLIT_PANES, LAYOUT_DEFAULT}

class omni.kit.widget.filebrowser.FileBrowserWidget(title: str, **kwargs)

Bases: object

The basic UI widget for navigating a filesystem as a tree view. The filesystem can either be from your local machine or the Omniverse server.

Parameters

title (str) – Widget title. Default None.

Keyword Arguments
  • layout (int) – The overall layout of the window, one of: {LAYOUT_SPLIT_PANES, LAYOUT_SINGLE_PANE_SLIM, LAYOUT_SINGLE_PANE_WIDE, LAYOUT_DEFAULT}. Default LAYOUT_SPLIT_PANES.

  • splitter_offset (int) – Position of vertical splitter bar. Default 300.

  • tooltip (bool) – Display tooltips when hovering over items. Default False.

  • allow_multi_selection (bool) – Allow multiple items to be selected at once. Default True.

  • mouse_pressed_fn (func) – Function called on mouse press. Function signature: void mouse_pressed_fn(pane: int, button: int, key_mode: int, item: FileBrowserItem)

  • mouse_double_clicked_fn (func) – Function called on mouse double click. Function signature: void mouse_double_clicked_fn(pane: int, button: int, key_mode: int, item: FileBrowserItem)

  • selection_changed_fn (func) – Function called when selection changed. Function signature: void selection_changed_fn(pane: int, selections: list[FileBrowserItem])

  • drop_fn (func) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_path: str)

  • filter_fn (func) – This user function should return True if the given tree view item is visible, False otherwise. Function signature: bool filter_fn(item: FileBrowserItem)

  • show_grid_view (bool) – If True, initializes the folder view to display icons. Default False.

  • grid_view_scale (int) – Scales grid view, ranges from 0-5. Default 2.

  • icon_provider (func) – This callback provides an icon to replace the default one in the tree view. Signature: str icon_provider(item: FileBrowserItem, expanded: bool).

  • thumbnail_provider (func) – This callback provides a thumbnail to replace the default one in the grid view. Signature: (str, bool) thumbnail_provider(item: FileBrowserItem, local_only: bool). If local_only is True, then the returned thumbnail should be locally available for immediate display. Returns tuple incl. path to the thumbnail and a bool specifying whether to retry this function asynchronously, in order to find a better thumbnail on the Nucleus server.

  • badges_provider (func) – This callback provides the list of badges to layer atop the thumbnail in the grid view. Callback signature: [str] badges_provider(item: FileBrowserItem)

destroy()

Destructor. Called by extension before destroying this object. It doesn’t happen automatically. Without this hot reloading doesn’t work.

get_selections(pane: int = 1) → [<class ‘omni.kit.widget.filebrowser.model.FileBrowserItem’>]

Returns list of selected items from the specified pane.

Parameters

pane (int) – One of TREEVIEW_PANE, LISTVIEW_PANE. Returns the union if None is specified.

Returns

list[FileBrowserItem]

Links this widget to the given widget, i.e. the 2 widgets will therafter display the same models but not necessarily share the same view.

Parameters

src_widget (FilePickerWidget) – The source widget.

refresh_ui(item: omni.kit.widget.filebrowser.model.FileBrowserItem = None)

Redraws the subtree rooted at the given item. If item is None, then redraws entire tree.

Parameters

item (FileBrowserItem) – Root of subtree to redraw. Default None, i.e. root.

select_and_center(selection: omni.kit.widget.filebrowser.model.FileBrowserItem, pane: int = 1)

Selects and centers the tree view on the given item, expanding the tree if needed.

Parameters
  • selection (FileBrowserItem) – The selected item.

  • pane (int) – One of TREEVIEW_PANE, LISTVIEW_PANE.

set_expanded(item: omni.kit.widget.filebrowser.model.FileBrowserItem, expanded: bool, recursive: bool = False)

Sets the expansion state of the given item.

Parameters
  • item (FileBrowserItem) – The item to effect.

  • expanded (bool) – True to expand, False to collapse.

  • recursive (bool) – Apply state recursively to descendent nodes. Default False.

set_selections(selections: [<class 'omni.kit.widget.filebrowser.model.FileBrowserItem'>], pane: int = 1)

Selected given items in given pane.

Parameters
  • selections (list[FileBrowserItem]) – list of selections.

  • pane (int) – One of TREEVIEW_PANE, LISTVIEW_PANE, or None for both. Default None.

class omni.kit.widget.filebrowser.FileBrowserModel(self: omni.ui._ui.AbstractItemModel)None

Bases: omni.ui._ui.AbstractItemModel

Base class for the Filebrowser tree view Model. Should be sub-classed to implement specific filesystem behavior.

Parameters

name (str) – Name of root item. If None given, then create an initally empty model.

Keyword Arguments
  • drop_fn (func) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)

  • filter_fn (func) – This handler should return True if the given tree view item is visible, False otherwise. Function signature: bool filter_fn(item: FileBrowserItem)

  • sort_by_field (str) – Name of column by which to sort items in the same folder. Default “name”.

  • sort_ascending (bool) – Sort in ascending order. Default True.

property builtin_column_count

Return the number of available columns without tag delegates

async static copy_item_async(rel_path: str, src_root: str, dst_root: str, timeout: float = 30.0)str

Async function. Copies item (recursively) from one path to another. Note: this function simply uses the copy function from omni.client and makes no attempt to optimize for copying from one Omniverse server to another. For that, use the Copy Service. Example usage: await copy_item_async(“my_file.usd”, “C:/tmp”, “omniverse://ov-content/Users/me”)

Parameters
  • rel_path (str) – Name of file or folder relative to the source and destination paths.

  • src_root (str) – Source path to item being copied.

  • dst_root (str) – Destination path to copy the item.

  • timeout (float) – Number of seconds to try before erroring out. Default 10.

Returns

Destination path name

Return type

str

Raises

RuntimeWarning – If error or timeout.

async static create_folder_async(path: str, timeout: float = 10.0)str

Async function. Creates a new folder at the given path name.

Parameters
  • path (str) – The full path name of a file or folder, e.g. “omniverse://ov-content/Users/me”.

  • timeout (float) – Number of seconds to try before erroring out. Default 10.

Returns

Folder path name

Return type

str

Raises

RuntimeWarning – If error or timeout.

async static delete_item_async(path: str, timeout: float = 10.0)str

Async function. Deletes the item at the given path name.

Parameters
  • path (str) – The full path name of a file or folder, e.g. “omniverse://ov-content/Users/me”.

  • timeout (float) – Number of seconds to try before erroring out. Default 10.

Returns

Deleted path name

Return type

str

Raises

RuntimeWarning – If error or timeout.

drop(dst_item: omni.kit.widget.filebrowser.model.FileBrowserItem, source: Union[str, omni.kit.widget.filebrowser.model.FileBrowserItem])

Invokes user-supplied function to handle dropping source onto destination item.

Parameters
drop_accepted(dst_item: omni.kit.widget.filebrowser.model.FileBrowserItem, src_item: omni.kit.widget.filebrowser.model.FileBrowserItem)bool

Reimplemented from AbstractItemModel. Called to highlight target when drag and drop. Returns True if destination item is able to accept a drop. This function can be overriden to implement a different behavior.

Parameters
Returns

bool

async static get_auth_token_async(path: str, timeout: float = 10.0) → Tuple[str, str, str]

Async function. Retrieves the authentication token for the given server/path.

Parameters
  • path (str) – The full path name to the server, e.g. “omniverse://ov-content”.

  • timeout (float) – Number of seconds to try before erroring out. Default 10.

Returns

host, username, auth_token.

Return type

tupe[str, str, str]

Raises

RuntimeWarning – If error or timeout.

get_drag_mime_data(item: omni.kit.widget.filebrowser.model.FileBrowserItem)

Returns Multipurpose Internet Mail Extensions (MIME) data for be able to drop this item somewhere

get_item_children(item: omni.kit.widget.filebrowser.model.FileBrowserItem) → [<class ‘omni.kit.widget.filebrowser.model.FileBrowserItem’>]

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

Parameters

item (FileBrowserItem) – Parent item.

Returns

list[FileBrowserItem]

get_item_value_model(item: omni.kit.widget.filebrowser.model.FileBrowserItem, index: int)object

Get the value model associated with this item.

Parameters

item (FileBrowserItem) – The item in question.

Returns

AbstractValueModel

get_item_value_model_count(item: omni.kit.widget.filebrowser.model.FileBrowserItem)int

Returns the number of columns this model item contains.

Parameters

item (FileBrowserItem) – The item in question.

Returns

int

static normalize_url(url: str)str

Wraps the omni.client function to sanitize given URL into a form that it can process.

Parameters

url (str) – Path to normalize.

Returns

str

static reconnect_url(url: str) → omni.client._omniclient.ListEntry

Forces a reconnection to specified server after clearing authorization tokens from the local cache.

Parameters

url (str) – Path to server.

Returns

omni.client.ListEntry

property root

Gets/sets the root item of this model.

Type

FileBrowserItem

property single_column

The panel on the left side works in one-column mode

property sort_ascending

Gets/sets the sort ascending state.

Type

FileBrowserItem

property sort_by_field

Gets/sets the sort-by field name.

Type

FileBrowserItem

static stat_path(path: str) → omni.client._omniclient.ListEntry

Uses omni.client to synchronously stat the given path. Raises errors if path is unreachable or invalid.

Parameters

path (str) – The full path name of a file or folder, e.g. “omniverse://ov-content/Users/me”.

Returns

omni.client.ListEntry

Raises

RuntimeWarning – If path is unreachable or invalid.

static stat_path_with_callback(path: str, callback: Callable, timeout: float = 10.0)

Uses omni.client to asynchronously stat the given path. Executes given callback with found stats or exception.

Parameters
  • path (str) – The full path name of a file or folder, e.g. “omniverse://ov-content/Users/me”.

  • callback (func) – Invokes this callback when done with either stats or an exception. Function signature: void callback(stats_or_error: Union[omni.client.ListEntry, Exception]).

  • timeout (float) – Number of seconds to try before erroring out. Default 10.

class omni.kit.widget.filebrowser.FileBrowserItem(self: omni.ui._ui.AbstractItem)None

Bases: omni.ui._ui.AbstractItem

Base class for the Filebrowser tree view Item. Should be sub-classed to implement specific filesystem behavior. The Constructor should not be called directly. Instead there are factory methods available for creating instances when needed.

add_child(item: object)

Adds item as child.

Parameters

item (FileBrowserItem) – Child item.

property children

Children of this item. Does not populate the item if not already populated.

Type

dict[FileBrowserItem]

del_child(item_name: str)

Deletes child item by name.

Parameters

item_name (str) – Name of child item.

property enable_sorting

True if item’s children are sortable.

Type

bool

property fields

A subset of the item’s stats stored as a string tuple.

Type

FileBrowserItemFields

get_subitem_model(index: int)object

Returns ith column of this item.

Returns

AbstractValueModel

property icon

Gets/sets path to icon file.

Type

str

property is_folder

True if this item is a folder.

Type

bool

property models

The columns of this item.

Type

Tuple[ui.AbstractValueModel]

property name

Item name.

Type

str

property parent

Parent of this item.

Type

FileBrowserItem

property path

Full path name.

Type

str

populate() → [<class ‘object’>]

If not already populated, populates this item using its populate_func.

Returns

List of children items.

Return type

list[FileBrowserItem]

property populate_func

The function called to populate an item. Function signature: list[obj] populate_func(item: FileBrowserItem).

Type

func

property populated

Gets/Sets item populated state.

Type

bool

class omni.kit.widget.filebrowser.FileSystemModel(self: omni.ui._ui.AbstractItemModel)None

Bases: omni.kit.widget.filebrowser.model.FileBrowserModel

A Filebrowser model class for navigating a the local filesystem in a tree view. Sub-classed from FileBrowserModel.

Parameters
  • name (str) – Name of root item..

  • root_path (str) – Root path. If None, then create empty model. Default “C:”.

Keyword Arguments
  • drop_fn (func) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)

  • filter_fn (func) – This handler should return True if the given tree view item is visible, False otherwise. Function signature: bool filter_fn(item: FileBrowserItem)

  • sort_by_field (str) – Name of column by which to sort items in the same folder. Default “name”.

  • sort_ascending (bool) – Sort in ascending order. Default True.

class omni.kit.widget.filebrowser.NucleusModel(self: omni.ui._ui.AbstractItemModel)None

Bases: omni.kit.widget.filebrowser.model.FileBrowserModel

A Filebrowser model class for navigating a Nucleus server in a tree view. Sub-classed from FileBrowserModel.

Parameters
  • name (str) – Name of root item..

  • root_path (str) – Root path. If None, then create empty model. Example: “omniverse://ov-content”.

Keyword Arguments
  • drop_fn (func) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)

  • filter_fn (func) – This handler should return True if the given tree view item is visible, False otherwise. Function signature: bool filter_fn(item: FileBrowserItem)

  • sort_by_field (str) – Name of column by which to sort items in the same folder. Default “name”.

  • sort_ascending (bool) – Sort in ascending order. Default True.