omni.kit.widget.filebrowser¶

Kit Filebrowser Widget.

Changelog

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)¶

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 (Callable) – Function called on mouse press. Function signature: void mouse_pressed_fn(pane: int, button: int, key_mode: int, item: FileBrowserItem)
mouse_double_clicked_fn (Callable) – 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 (Callable) – Function called when selection changed. Function signature: void selection_changed_fn(pane: int, selections: list[FileBrowserItem])
drop_fn (Callable) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_path: str)
filter_fn (Callable) – 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 (Callable) – This callback provides an icon to replace the default one in the tree view. Signature: str icon_provider(item: FileBrowserItem, expanded: bool).
thumbnail_provider (Callable) – 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 (Callable) – 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 (Callable) – This callback provides the list of badges to layer atop the thumbnail in the grid view. Callback signature: [str] badges_provider(item: FileBrowserItem)
treeview_identifier (str) – widget identifier for treeview, only used by tests.

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]

link_views(src_widget: object)¶

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(name: Optional[str] = None, root_path: str = '', **kwargs)¶

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 (Callable) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)
filter_fn (Callable) – 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 (Callable) – 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.

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

dst_item (FileBrowserItem) – Target item.
src_item (FileBrowserItem) – Source item.

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

dst_item (FileBrowserItem) – Target item.
src_item (FileBrowserItem) – Source item.

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.Result, event: omni.client.ListEvent, entry: omni.client.ListEntry, throttle_frames: int = 4)¶

Processes change events for the given folder.

Parameters

item (FileBrowserItem) – The folder item.
result (omni.client.Result) – Set by omni.client upon listing the folder.
event (omni.client.ListEvent) – Event type.
throttle_frames – Number of frames to throttle the UI refresh.

static reconnect_url(url: str, timeout: float = 600.0)¶

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

Parameters: url (str) – Path to server.

property root¶

Gets/sets the root item of this model.

Type: FileBrowserItem

static sign_out(url: str)¶

Signs out from given server.

Parameters: url (str) – Path to server.

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 (Callable) – 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(path: str, fields: omni.kit.widget.filebrowser.model.FileBrowserItemFields, is_folder: bool = False)¶

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.ListEvent, entry: omni.client.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

event (omni.client.ListEvent) – One of of {UNKNOWN, CREATED, UPDATED, DELETED, METADATA, LOCKED, UNLOCKED}.
entry (omni.client.ListEntry) – Updated entry as defined by omni.client.

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 (Callable) – 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 (Callable) – 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(name: str, root_path: str = 'C:', **kwargs)¶

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 (Callable) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)
filter_fn (Callable) – 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(name: str, root_path: str, **kwargs)¶

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 (Callable) – Function called to handle drag-n-drops. Function signature: void drop_fn(dst_item: FileBrowserItem, src_item: FileBrowserItem)
filter_fn (Callable) – 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.