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 returns the path to the item’s thumbnail. If not specified, then a default thumbnail is used. Signature: str thumbnail_provider(item: FileBrowserItem).

  • thumbnail_dict_provider_async (func) – Returns a dictionary of thumbnails for the current folder. It is called from an async thread and typically queries a remote server, e.g. Nucleus. Signature: async dict thumbnail_dict_provider_async(item: FileBrowserItem). Returns a dictionary with item name as key, and fullpath to thumbnail file as value.

  • 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: Optional[omni.kit.widget.filebrowser.model.FileBrowserItem] = None, listview_only: bool = False)

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.

  • thumbnail_dict_provider_async (func) – Returns a dictionary of thumbnails for the current folder. It is called from an async thread and typically queries a remote server, e.g. Nucleus. Signature: async dict thumbnail_dict_provider_async(item: FileBrowserItem). Returns a dictionary with item name as key, and fullpath to thumbnail file as value.

Constructs AbstractItemModel.

Parameters

kwargs (dict) – See below

Keyword Arguments

auto_refresh_item(item: omni.kit.widget.filebrowser.model.FileBrowserItem, throttle_frames: int = 4)

Watches the given folder and updates the children list as soon as its contents are changed.

Parameters
  • item (FileBrowserItem) – The folder item to watch.

  • throttle_frames – Number of frames to throttle the UI refresh.

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 = 300.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]

async get_item_thumbnail_dict_async(item: omni.kit.widget.filebrowser.model.FileBrowserItem)

Returns the thumbnail dictionary for the given (folder) item if one is available.

Parameters

item (FileBrowserItem) – The folder item to watch.

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

on_list_change_event(item: omni.kit.widget.filebrowser.model.FileBrowserItem, result: omni.client._omniclient.Result, event: omni.client._omniclient.ListEvent, entry: omni.client._omniclient.ListEntry, throttle_frames: int = 4)

Processes change events for the given folder.

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

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

Scans given folder for missed changes; processes any changes found.

Parameters

item (FileBrowserItem) – The folder item to watch.

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

on_list_change_event(event: omni.client._omniclient.ListEvent, entry: omni.client._omniclient.ListEntry)bool

Virtual method to be implemented by sub-class. When called with a ListEvent, should update this item’s children list with the corresponding ListEntry.

Parameters
property parent

Parent of this item.

Type

FileBrowserItem

property path

Full path name.

Type

str

async populate_async(callback_async: Optional[Callable] = None, timeout: float = 10.0) → Any

Populates current item asynchronously if not already. Override this method to customize for specific file systems.

Parameters
  • callback_async (func) – Function signature is void callback(result, children: [FileBrowserItem]), where result is an Exception type upon error.

  • timeout (float) – Time out duration on failed server connections. Default 10.0.

Returns

Result of executing callback.

Return type

Any

populate_with_callback(callback: Callable, timeout: float = 10.0)

Populates this item if not already populated. When done, executes callback.

Parameters
  • callback (func) – Function signature is void callback(children: [FileBrowserItem]).

  • timeout (float) – Time out duration on failed server connections. Default 10.0.

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.

Constructs AbstractItemModel.

Parameters

kwargs (dict) – See below

Keyword Arguments

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.

Constructs AbstractItemModel.

Parameters

kwargs (dict) – See below

Keyword Arguments