omni.kit.widget.filebrowser

Kit Filebrowser Widget.

• Overview
• 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.

• show_recycle_widget (bool) – If True, show recycle view in the left bottom corner. Default False.

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

• on_toggle_grid_view_fn (Callable) – Callback after toggle grid view is executed. Default None.

• on_scale_grid_view_fn (Callable) – Callback after scale grid view is executed. Default None.

• 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).

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

• enable_zoombar (bool) – Enables/disables zoombar. Default True.

destroy()

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

get_selected_item(pane: int = 1) → FileBrowserItem

Returns last of selected item from the specified pane.

Parameters

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

Returns

FileBrowserItem or None

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[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: 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: 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.

auto_refresh_item(item: 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

drop(dst_item: FileBrowserItem, source: Union[str, 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: FileBrowserItem, src_item: 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

get_drag_mime_data(item: FileBrowserItem)

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

get_item_children(item: 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: 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: FileBrowserItem) → int

Returns the number of columns this model item contains.

Parameters

item (FileBrowserItem) – The item in question.

Returns

int

on_list_change_event(item: FileBrowserItem, result: Result, event: ListEvent, entry: 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.

property root: FileBrowserItem

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: bool

Gets/sets the sort ascending state.

Type

FileBrowserItem

property sort_by_field: str

Gets/sets the sort-by field name.

Type

FileBrowserItem

sync_up_item_changes(item: 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: FileBrowserItemFields, is_folder: bool = False, is_deleted: 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: OrderedDict

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: bool

True if item’s children are sortable.

Type

bool

property expandable: bool

whether this FileBrowserItem is expandable. Override to change behavior

property fields: FileBrowserItemFields

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

Type

FileBrowserItemFields

async get_custom_thumbnails_for_folder_async() → Dict

Returns the thumbnail dictionary for this (folder) item.

Returns

With children url’s as keys, and url’s to thumbnail files as values.

Return type

Dict

get_subitem_model(index: int) → object

Returns ith column of this item.

Returns

AbstractValueModel

property hideable: bool

whether this FileBrowserItem is hideable. Override to change behavior

property icon: str

Gets/sets path to icon file.

Type

str

property is_deleted: bool

True if this item is a deleted folder/file.

Type

bool

property is_folder: bool

True if this item is a folder.

Type

bool

property is_udim_file: bool

Gets/Sets item udim_file state.

Type

bool

property item_changed: bool

True if this item is has been restore/delete aready.

Type

bool

property models: Tuple

The columns of this item.

Type

Tuple[ui.AbstractValueModel]

property name: str

Item name.

Type

str

on_list_change_event(event: ListEvent, entry: 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: object

Parent of this item.

Type

FileBrowserItem

property path: str

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: bool

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.