USD Manager

Website

USD Manager is an open-source, python-based Qt tool for browsing, managing, and editing text-based files like USD, combining the best features from your favorite web browser and text editor into one application, with hooks to deeply integrate with other pipeline tools. It is developed and maintained by DreamWorks Animation for use with USD and other hierarchical, text-based workflows, primarily geared towards feature film production. While primarily designed around PyQt4, USD Manager uses the Qt.py compatibility library to allow working with PyQt4, PyQt5, PySide, or PySide2 for Qt bindings.

Development Repository

This GitHub repository hosts the trunk of the USD Manager development. This implies that it is the newest public version with the latest features and bug fixes. However, it also means that it has not undergone a lot of testing and is generally less stable than the production releases.

License

USD Manager is released under the Apache 2.0 license, which is a free, open-source, and detailed software license developed and maintained by the Apache Software Foundation.

Contents

User Documentation

Installing USD Manager

USD Manager has primarily been developed for and tested on Linux. While the basics should work on other platforms, they have not been as heavily tested. Notes to help with installation on specific operating systems can be added here.

These steps provide an example only and may need to be modified based on your specific setup and needs.

Contents

• Prerequisites
• Install with setup.py
• OS Specific Notes
  • Linux
  • Mac (OSX)
  • Windows
• Common Problems

Prerequisites

• Install Python 2 (https://www.python.org/downloads/)
  • Windows: Ensure the install location is part of your PATH variable (newer installs should have an option for this)
• Install one of the recommended Python Qt bindings
  • Python 2: PyQt4 or PySide

Install with setup.py

For a site-wide install, try:

python setup.py install

For a personal install, try:

python setup.py install --user

Studios with significant python codebases or non-trivial installs may need to customize setup.py

Your PATH and PYTHONPATH will need to be set appropriately to launch usdmanager, and this will depend on your setup.py install settings.

OS Specific Notes

Linux

Known Issues

• Print server may not recognize network printers.

Mac (OSX)

Known Issues

• User preferences may not preserve between sessions.
• Since this is not installed as an entirely self-contained package, the application name (and icon) will by Python, not USD Manager.

Windows

Installation

1. Launch Command Prompt
2. cd to the downloaded usdmanager folder (you should see a setup.py file in here).
3. Run python setup.py install (may need the --user flag)

If setup.py complains about missing setuptools, you can install it via pip. If you installed a new enough python-2 version, pip should already be handled for you, but you may still need to add it to your PATH. pip should already live somewhere like this (C:\Python27\Scripts\pip.exe), and you can permanently add it to your environment with: setx PATH "%PATH%;C:\Python27\Scripts"

1. Upgrade pip if needed
2. Launch Command Prompt in Administrator mode
3. Run pip install pip --upgrade (may need the --user flag)
4. Install setuptools if needed
5. Run pip install setuptools
6. Re-run the setup.py step above for usdmanager
7. If you don’t modify your path, you should now be able to run something like this to launch the program: python C:\Python27\Scripts\usdmanager

Known Issues

• Drive letter may show doubled-up in address bar (e.g. C:C:/my_file.txt)

Common Problems

• Missing icons (may still be missing some even after this!)
  • pip install django-crystal-small (this also installs django by default, which you may not want)
  • Add installed path to your downloaded usdmanager/config.json file, then re-run the setup.py install. You’ll need a line similar to this in your config.json: "themeSearchPaths": ["C:\\Python27\\Lib\\site-packages\\django_crystal_small\\static\\crystal"]
• Can’t open files in external text editor
  • In Preferences, try setting your default text editor
  • Windows: Try notepad.exe or "C:\Windows\notepad.exe" (including the quotation marks)

Using USD Manager

Once you have installed usdmanager, you can launch from the command line:

usdmanager

You can also specify one or more files to open directly:

usdmanager shot.usd

Contents

• Browse Mode
  • Browsing Standard Features
• Edit Mode
  • Editing Standard Features
• USD Crate
• Preferences
  • Tabbed Browsing
  • Font
  • Programs
• Commands
  • File Info…
  • Diff File…
  • Comment Out
  • Uncomment
  • Indent
  • Unindent
  • Open with usdview…
  • Open with text editor…
  • Open with…

Browse Mode

Browse mode is the standard mode that the application launches in, which displays text-based files like a typical web browser. Additionally, it attempts to parse the given file for links to other files, such as USD references and payloads, images, and models, looking for anything inside of ‘single quotes,’ “double quotes,” and @at symbols@. These links can then be followed like links on a website. Links to files that exist are colored blue, wildcard links to zero or more files are colored yellow, and paths we think are links that cannot be resolved to a valid path are red. Binary USD Crate files are highlighted in purple instead of blue.

Browsing Standard Features

The browser boasts many standard features, including tabbed browsing with rearrangeable tabs, a navigational history per tab, a recent files list (File > Open Recent), and the ability to restore closed Tabs (History > Recently Closed Tabs).

Edit Mode

The program can switch back and forth between browsing (the default) and editing. Before switching to the editor, the file must be writable. If using files in a revision control system, this is where custom plug-ins can come in handy to allow you to check in and out files so that you have write permissions before switching to Edit mode.

To switch between Browse mode and Edit mode, hit the Ctrl+E keyboard shortcut, click the Browser/Editor button above the address bar (to the right of the zoom buttons), or click File -> Browse Mode (or File -> Edit Mode). If you have modified the file without saving, you will be prompted to save your changes before continuing.

Editing Standard Features

The editor includes many standard features such as cut/copy/paste support, comment/uncomment macros, and find/replace functionality.

Files that have been modified are marked as dirty with asterisk around the file name in tabs and the window title. Before saving a modified file, you can choose to diff your file (Commands -> Diff file…) if you want to see what you changed. The diffing tool can be modified per user in preferences (Edit > Preferences…) or with the “diffTool” key in the app config file.

USD Crate

Binary USD Crate files are supported within the app. You can view and edit them just like using usdedit, but under the hood, the app is converting back and forth between binary and ASCII formats as needed. Any edits to the file are saved in the original file format, so opening a binary .usd or .usdc file will save back out in binary. You can force a file to ASCII by saving with the .usda extension. Similarly, you can force a formerly ASCII-based file to the binary Crate format by saving with the .usdc extension. Currently, there is no UI to switch between ASCII and binary other than setting the file extension in the Save As dialog.

Preferences

Most user preferences can be accessed under the Edit > Preferences… menu option. Preferences in this dialog are saved for future sessions.

Tabbed Browsing

Like many web browsers, files can be viewed in multiple tabs. The “+” button on the upper-left of the browser portion adds a new tab, and the “x” closes the current tab. You can choose to always open files in new tabs under Edit > Preferences… On the General tab, select “Open files in new tabs.”

Alternatively, you can open a file in the current tab by left-clicking the link, and open a file in a new tab by Ctrl+left-clicking or middle-mouse-clicking the link. There is also a right-click menu item to open the link in a new tab. To navigate among tabs, you can simply click on the desired tab, or use “Ctrl+Tab” to move forward and “Ctrl+Shift+Tab” to move backwards.

Font

Font sizes can be adjusted with the “Zoom In,” “Zoom Out,” and “Normal Size” options under the “View” menu, or with the keyboard shortcuts: Ctrl++, Ctrl+-, and Ctrl+0. This size will be applied to all future tabs and is saved as a preference for your next session. You can also choose a default font for the displayed document in the Preferences dialog.

Programs

The extensions that usdmanager searches for when creating links to files can be adjusted under the Programs tab of the Preferences dialog. If an extension is not on this page, usdmanager will not know to look for it. Any file type that you wish to display in-app should be listed on the first line in a comma-separated list. File types that you wish to open in external programs such as an image viewer can be designated in the lower section. If you always want .jpg files to open in a fullscreen version of eog, for example, set “eog –fullscreen” for the program and “.jpg” for the extension.

Commands

Commands may be accessed through the “Commands” menu or by right-clicking inside the browser portion of the program.

Additional commands beyond the basics provided here can be added via the app config file and plug-in system. For details, see “Menu plug-ins” in the “Development / Customization” section.

File Info…

View information about the current file, including the owner, size, permissions, and last modified time.

Diff File…

If you have made changes to the file without saving, you can use this command to compare the changes to the version currently saved on disk. The program saves a temporary version of your changes and launches the original and temp files via the diff tool of your choice (default: xdiff), which can be managed via the Preferences dialog and the app config file.

Comment Out

Comment out the selected lines with the appropriate symbol for the current file type. Supports USD, Lua, Python, HTML, and XML comments, defaulting to # for the comment string if the language is unknown.

Uncomment

Uncomment the selected lines. See “Comment Out” above for supported languages.

Indent

Indent the selected lines by one tab stop (4 spaces).

Unindent

Unindent the selected lines by one tab stop (4 spaces).

Open with usdview…

For USD files, launch the current file in usdview.

Open with text editor…

The command launches the current file in a text editor of your choice. By default, usdmanager uses $EDITOR, and nedit if that environment variable is not defined. You can set your preferred editor using the Preferences dialog under Edit > Preferences…. This preference will be saved for future sessions.

Open with…

If usdmanager does not open a file with the program you desire, you can use “Open with…” to enter a program (and any extra flags) of your choosing. The file is appended at the end of what you enter. To open a link in this manner, right-click the link and select “Open link with…” from the context menu.

Keyboard Shortcuts

Full list of all normal and hidden keyboard shortcuts for USD Manager

Keyboard Shortcuts

Command	Shortcut
Select All	Ctrl+A
Copy	Ctrl+C
Edit File	Ctrl+E
Find/Replace	Ctrl+Shift+F
Find Next	Ctrl+G
Find Previous	Ctrl+Shift+G
File Browser	Ctrl+I
File Info…	Ctrl+Shift+I
Go To Line Number…	Ctrl+Shift+L
New Window	Ctrl+N
Open…	Ctrl+O
Open with…	Ctrl+Shift+O
Print…	Ctrl+P
Quit	Ctrl+Q
Reload	Ctrl+R
Save	Ctrl+S
Save As…	Ctrl+Shift+S
New Tab	Ctrl+T
Paste	Ctrl+V
Close Tab	Ctrl+W
Cut	Ctrl+X
Undo	Ctrl+Z
Redo	Ctrl+Shift+Z
Unindent	Ctrl+Shift+0
Uncomment	Ctrl+3
Comment Out	Ctrl+Shift+3
Indent	Ctrl+Shift+9
Zoom In	Ctrl++
Zoom Out	Ctrl+-
Normal Size	Ctrl+0
Back	Alt+Left
Forward	Alt+Right
Stop	Esc
Documentation	F1
Full Screen	F11

Hidden shortcuts

For ease of use, there are some extra shortcuts not shown in the menus themselves:

Command	Shortcut
Back	Backspace
Find	Ctrl+F
Zoom In	Ctrl+=
Next Tab	Ctrl+Tab
Previous Tab	Ctrl+Shift+Tab
Reload	F5

Development / Customization

Most customization of the app is through the usdmanager/config.json file.

Contents

• File extensions
• Syntax highlighting
• Plug-ins
• Icons

File extensions

This app supports more than just USD files! It’s well suited to display most text-based files, but you need to register additional file extensions to search for. Non-text files can also be launched via the program of your choice. For example, .exr files can be launched in your preferred image viewer, and .abc model files in a modeling playback tool like usdview. To register files, define a “defaultPrograms” dictionary in the app config file. The dictionary keys are file extensions (without the starting period). The value is either a blank string, which means files of this type will be opened in this app, or a string to a command to run with the file path appended. USD file types are already included, so you don’t need to redefine these.

Additional default app settings can be optionally overridden via the app config file. Supported keys include:

• appURL (str) - Documentation URL. Defaults to the public GitHub repository.
• defaultPrograms ({str: str}) - File extension keys with the command to open the file type as the values.
• diffTool (str) - Diff command. Defaults to xdiff.
• iconTheme (str) - QtGui.QIcon theme name. Defaults to crystal_project.
• textEditor (str) - Text editor to use when opening files externally if $EDITOR environment variable is not set. Defaults to nedit.
• themeSearchPaths ([str]) - Paths to prepend to QtGui.QIcon’s theme search paths.
• usdview - Command to launch usdview.

Example app config JSON file:

{
    "defaultPrograms": {
        "txt": "",
        "log": "",
        "exr": "r_view",
        "tif": "r_view",
        "tiff": "r_view",
        "abc": "usdview",
        "tx": "rez-run openimageio_arras -- iv"
    },
    "diffTool": "python /usr/bin/meld",
    "iconTheme": "gnome",
    "textEditor": "gedit",
    "themeSearchPaths": []
}

Syntax highlighting

To add syntax highlighting for additional languages, subclass the highlighter.MasterHighlighter class and save your new class in a file in the highlighters directory. Set the class’s extensions list variable to the languages this highlighter supports (e.g. [“.html”, “.xml”]). Already supported languages include USD, Lua, Python, and some basic HTML/XML.

Plug-ins

Plug-ins can be added via the plugins directory. Create a new module in the plugins directory (e.g. my_plugin.py) and define a class that inherits from the Plugin class. This allows you to add your own menu items, customize the UI, etc.

Please be careful if you access, override or define anything in the main window, as future release may break the functionality you added!

Example plug-in file:

from Qt.QtCore import Slot
from Qt.QtGui import QIcon
from Qt.QtWidgets import QMenu

from . import Plugin, images_rc


class CustomExample(Plugin):
    def __init__(self, parent):
        """ Initialize my custom plugin.
        
        :Parameters:
            parent : `UsdMngrWindow`
                Main window
        """
        super(CustomExample, self).__init__(parent)
        
        # Setup UI.
        menu = QMenu("My Menu", parent)
        parent.menubar.insertMenu(parent.helpMenu.menuAction(), menu)
        
        self.customAction = menu.addAction(QIcon(":plugins/custom_icon.png"), "Do something")
        self.customAction.triggered.connect(self.doSomething)
    
    @Slot(bool)
    def doSomething(self, checked=False):
        """ Do something.
        
        :Parameters:
            checked : `bool`
                For slot connection only.
        """
        print("Doing something")

Icons

Most icons in the app come from themes pre-installed on your system, ideally following the freedesktop.org standards. The preferred icon set that usdmanager was originally developed with is Crystal Project Icons. These icons are licensed under LGPL and available via pypi and GitHub here: https://github.com/ambv/django-crystal-small. While not required for the application to work, if you would like these icons to get the most out of the application, please install them to a directory named crystal_project under one of the directories listed by Qt.QtGui.QIcon.themeSearchPaths() (e.g. /usr/share/icons/crystal_project).

Additional icons for custom plug-ins can be placed in the plugins directory and then added to the usdmanager/plugins/images.qrc file. After adding a file to images.rc, run the following to update usdmanager/plugins/images_rc.py:

pyrcc4 usdmanager/plugins/images.rc > usdmanager/plugins/images_rc.py

If using pyrcc4, be sure to replace PyQt4 with Qt in the images_rc.py’s import line.

Contributing

This document details the contributing requirements and coding practices that are used in the USD Manager codebase.

Contents

• The Contributor License Agreement
• Code Signing
• Pull Requests
• Process
• Style Guide
  • Naming Conventions
  • Formatting
  • General

The Contributor License Agreement

Developers who wish to contribute code to be considered for inclusion in the USD Manager distribution must first complete the Contributor License Agreement and submit it to DreamWorks (directions in the CLA).

Code Signing

Every commit must be signed off. That is, every commit log message must include a “Signed-off-by” line (generated, for example, with “git commit --signoff”), indicating that the committer wrote the code and has the right to release it under the Apache 2.0 license. See http://developercertificate.org/ for more information on this requirement.

Pull Requests

Pull requests should be rebased on the latest dev commit and squashed to as few logical commits as possible, preferably one. Each commit should pass tests without requiring further commits.

Process

1. Fork the repository on GitHub
2. Clone it locally
3. Build a local copy

python setup.py install --user

1. Write code, following the style guide.
2. Test it
3. Update any manual documentation pages (like this one) and run sphinx-apidoc with the following command:

sphinx-apidoc -o ./docs/api/ -e -P -f ./usdmanager/

1. Test that the documentation builds without errors with:

sphinx-build -b html docs/ docs/_build

1. Commit changes to the dev branch, signing off on them per the “code signing” instructions, then push the changes to your fork on GitHub
2. Make a pull request targeting the dev branch

Style Guide

In general, Python’s PEP 8 style guide should be followed, with the few exceptions or clarifications noted below. Contributed code should conform to these guidelines to maintain consistency and maintainability. If there is a rule that you would like clarified, changed, or added, please send a note to usdmanager@dreamworks.com.

Naming Conventions

In general, follow Qt naming conventions:

• Class names should be CapitalizedWords with an uppercase starting letter.
• Variable, function, and method names should be mixedCase with a lowercase starting letter.
• Global constants should be UPPER_CASE_WITH_UNDERSCORES; otherwise, names_with_underscores should be avoided.

Formatting

• Indentation is 4 spaces. Do not use tabs.
• Line length generally should not exceed 120 characters, especially for comments, but this is not a strict requirement.
• Use Unix-style carriage returns (“\n”) rather than Windows/DOS ones (“\r\n”).

General

• For new files, be sure to use the right license boilerplate per our license policy.

API Documentation

usdmanager package

Subpackages

usdmanager.highlighters package

Submodules

usdmanager.highlighters.lua module

class usdmanager.highlighters.lua.MasterLuaHighlighter(parent, enableSyntaxHighlighting=False, programs=None)

Bases: usdmanager.highlighter.MasterHighlighter

Lua syntax highlighter.

comment = '--'

extensions = ['lua']

getRules()

Syntax rules specific to this highlighter class.

multilineComment = ('--[[', ']]')

usdmanager.highlighters.python module

class usdmanager.highlighters.python.MasterPythonHighlighter(parent, enableSyntaxHighlighting=False, programs=None)

Bases: usdmanager.highlighter.MasterHighlighter

Python syntax highlighter.

comment = '#'

createRules()

extensions = ['py']

getRules()

Syntax rules specific to this highlighter class.

multilineComment = ('"""', '"""')

usdmanager.highlighters.usd module

class usdmanager.highlighters.usd.MasterUSDHighlighter(parent, enableSyntaxHighlighting=False, programs=None)

Bases: usdmanager.highlighter.MasterHighlighter

USD syntax highlighter

comment = '#'

createRules()

extensions = ('usd', 'usda', 'usdc', 'usdz')

getRules()

Syntax rules specific to this highlighter class.

usdmanager.highlighters.xml module

class usdmanager.highlighters.xml.MasterXMLHighlighter(parent, enableSyntaxHighlighting=False, programs=None)

Bases: usdmanager.highlighter.MasterHighlighter

XML syntax highlighter

comment = None

extensions = ['html', 'xml']

getRules()

XML syntax highlighting rules

multilineComment = ('<!--', '-->')

Module contents

usdmanager.plugins package

Submodules

usdmanager.plugins.images_rc module

Module contents

class usdmanager.plugins.Plugin(parent, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Classes in modules in the plugins directory that inherit from Plugin will be automatically initialized when the main window loads.

Submodules

usdmanager.constants module

Constant values

usdmanager.file_dialog module

class usdmanager.file_dialog.FileDialog(parent=None, caption='', directory='', filters=None, selectedFilter='', showHidden=False)

Bases: sphinx.ext.autodoc.importer._MockObject

Override the QFileDialog to provide hooks for customization.

usdmanager.file_status module

class usdmanager.file_status.FileStatus(url=None, update=True, truncated=False)

Bases: object

File status cache class allowing overriding with additional statuses for custom integration of things like a revision control system.

FILE_NEW = 0

FILE_NOT_WRITABLE = 1

FILE_TRUNCATED = 4

FILE_WRITABLE = 2

icon

Get an icon to display representing the file’s status.

Returns:Icon (may be blank) Rtype:QIcon

text

Get a status string to display for the file.

Returns:File status (may be an empty string) Rtype:str

updateFileStatus(truncated=False)

Cache the status of a file.

Parameters:

truncated : bool

If the file was truncated on read, and therefore should never be edited.

writable

Get if the file is writable.

Returns:If the file is writable Rtype:bool

usdmanager.find_dialog module

class usdmanager.find_dialog.FindDialog(parent=None, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Find/Replace dialog

connectSignals()

Connect signals to slots.

setupUi(widget)

Creates and lays out the widgets defined in the ui file.

Parameters:

widget : QtGui.QWidget

Base widget

updateButtons(text)

Update enabled state of buttons as entered text changes.

Parameters:

text : str

Currently entered find text

updateForEditMode(edit)

Show/Hide text replacement options based on if we are editing or not. If editing, allow replacement of the found text.

Parameters:

edit : bool

If in edit mode or not

usdmanager.highlighter module

Custom syntax highlighters.

class usdmanager.highlighter.Highlighter(parent=None, master=None)

Bases: sphinx.ext.autodoc.importer._MockObject

highlightBlock(text)

Override this method only if needed for a specific language.

isDirty()

masterClass

alias of MasterHighlighter

setDirty()

class usdmanager.highlighter.MasterHighlighter(parent, enableSyntaxHighlighting=False, programs=None)

Bases: sphinx.ext.autodoc.importer._MockObject

Master object containing shared highlighting rules.

comment = '#'

createRules()

dirtied

Used by autodoc_mock_imports.

dirty()

Let highlighters that subscribe to this know a rule has changed.

extensions = [None]

getRules()

Syntax rules specific to this highlighter class.

multilineComment = None

setFindCase(case)

Set the case sensitivity when searching for text.

Parameters:

case : bool

Find is case-sensitive if True.

setFindPhrase(phrase)

Set the “find” phrase when searching for text.

Parameters:

phrase : str

Text in find bar to search for.

setLinkPattern(programs)

Set the rules to search for files based on file extensions, quotes, etc.

Parameters:

programs : dict

extension: program pairs of strings.

setSyntaxHighlighting(enable, force=True)

Enable/Disable syntax highlighting. If enabling, dirties the state of this highlighter so highlighting runs again.

Parameters:

enable : bool

Whether or not to enable syntax highlighting.

force : bool

Force re-enabling syntax highlighting even if it was already enabled. Allows force rehighlighting even if nothing has really changed.

usdmanager.highlighter.createMultilineRule(startPattern, endPattern, color=None, darkColor=None, weight=None, italic=False, cs=<sphinx.ext.autodoc.importer._MockObject object>)

Create a multiline syntax highlighting rule.

Parameters:

startPattern : str

RegEx to match for the start of the block of lines.

endPattern : str

RegEx to match for the end of the block of lines.

color : QtGui.QColor

Color to highlight matches

darkColor : QtGui.QColor

Color to highlight matches when in a dark background theme.

weight : int | None

Optional font weight for matches

italic : bool

Set the font to italic

cs : int

Case sensitivity for RegEx matching

Returns:

Tuple of QtCore.QRegExp and QtGui.QTextCharFormat objects.

Rtype:

tuple

usdmanager.highlighter.createRule(pattern, color=None, darkColor=None, weight=None, italic=False, cs=<sphinx.ext.autodoc.importer._MockObject object>)

Create a single-line syntax highlighting rule.

Parameters:

pattern : str

RegEx to match

color : QtGui.QColor

Color to highlight matches when in a light background theme

darkColor : QtGui.QColor

Color to highlight matches when in a dark background theme. Defaults to color if not given.

weight : int | None

Optional font weight for matches

italic : bool

Set the font to italic

cs : int

Case sensitivity for RegEx matching

Returns:

Tuple of QtCore.QRegExp and QtGui.QTextCharFormat objects.

Rtype:

tuple

usdmanager.highlighter.findHighlighters()

Get the installed highlighter classes.

Returns:List of MasterHighlighter objects Rtype:list

usdmanager.images_rc module

usdmanager.images_rc.qCleanupResources()

usdmanager.images_rc.qInitResources()

usdmanager.include_panel module

class usdmanager.include_panel.IncludePanel(path='', filter='', selectedFilter='', parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

File browsing panel for the left side of the main UI.

accept(*args)

appendToPath(filename, isDirectory)

Parameters:filename : str isDirectory : bool

autoCompleteFileName(text)

enterDirectory(index)

fileSelectionChanged(one, two)

getPath()

onHome(*args)

onOriginal(*args)

onPathComboChanged(index)

onUp(*args)

openFile

Used by autodoc_mock_imports.

pathChanged(path)

select(index)

selectNameFilter(filter)

setDirectory(directory)

setFileDisplay()

setNameFilters(filters)

setPath(path)

showAll(checked)

Show hidden files

Parameters:

checked : bool

If True, show hidden files

usdmanager.linenumbers module

Line numbers widget for optimized display of line numbers on the left side of a text widget.

class usdmanager.linenumbers.LineNumbers(*args, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Line number widget for QTextBrowser and QTextEdit widgets. Currently does not support QPlainTextEdit widgets.

connectSignals()

Connect relevant QTextBrowser or QTextEdit signals.

paintEvent(event)

Override the default paintEvent to add in line numbers.

setTextWidget(widget)

Set the current text widget.

Parameters:

widget : QTextBrowser | QTextEdit

The text widget that uses a QTextDocument

update(*args)

Just update. We know we don’t need to resize with the signals that call this method.

updateAndResize(*args)

Resize bar if needed.

usdmanager.preferences_dialog module

class usdmanager.preferences_dialog.PreferencesDialog(parent, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Preferences dialog

connectSignals()

Connect signals to slots.

deleteItems(layout)

Parameters:

layout : QLayout

Delete all items in given layout.

getPrefAutoCompleteAddressBar()

Returns:State of “Auto complete paths in address bar” check box. Rtype:bool

getPrefDiffTool()

Returns:Text in Diff tool QTextEdit. Rtype:str

getPrefFont()

Returns:Font selected for documents. Rtype:QFont

getPrefLineNumbers()

Returns:State of “Show line numbers” check box. Rtype:bool

getPrefNewTab()

Returns:State of “Open links in new tabs” check box. Rtype:bool

getPrefParseLinks()

Returns:Search for links in the opened file. Disable this for huge files that freeze the app. Rtype:bool

getPrefPrograms()

Returns:Dictionary of extension: program pairs of strings. Rtype:dict

getPrefShowAllMessages()

Returns:State of “Show success messages” check box. Rtype:bool

getPrefShowHiddenFiles()

Returns:State of “Show hidden files” check box. Rtype:bool

getPrefSyntaxHighlighting()

Returns:State of “Enable syntax highlighting” check box. Rtype:bool

getPrefTabSpaces()

Returns:Number of spaces to use instead of a tab. Only use this number of use spaces is also True. Rtype:int

getPrefTeletypeConversion()

Returns:State of “Display teletype colors” check box. Rtype:bool

getPrefTextEditor()

Returns:Text in Text editor QTextEdit. Rtype:str

getPrefUseSpaces()

Returns:State of “Use spaces instead of tabs” check box. Rtype:bool

newProgField(*args)

populateProgsAndExts(programs)

Parameters:

programs : dict

Dictionary of extension: program pairs of strings.

restoreDefaults(btn)

Restore the GUI to the program’s default settings. Don’t update the actual preferences (that happens if OK is pressed).

selectFont(*args)

setupUi(widget)

Creates and lays out the widgets defined in the ui file.

Parameters:

widget : QtGui.QWidget

Base widget

updateFontLabel()

validate()

Make sure everything has valid input. Make sure there are no duplicate extensions. Accepts or rejects accepted() signal accordingly.

usdmanager.utils module

Generic utility functions

usdmanager.utils.expandPath(path, parentPath=None, sdf_format_args=None)

Expand and normalize a path that may have variables in it.

Parameters:

path : str

File path

parentPath : str | None

Parent file path this file is defined in relation to. Helps with asset resolution.

sdf_format_args : dict | None

Dictionary of key/value str pairs from a path’s :SDF_FORMAT_ARGS:

Returns:

Normalized path with variables expanded.

Rtype:

str

usdmanager.utils.findModules(subdir)

Find and import all modules in a subdirectory of this project. Ignores any files starting with an underscore or tilde.

Parameters:

subdir : str

Subdirectory

Returns:

Imported modules

Rtype:

list

usdmanager.utils.generateTemporaryUsdFile(usdFileName)

Generate a temporary ASCII USD file that the user can edit.

Parameters:

usdFileName : str

Binary USD file path

Returns:

Temporary file name

Rtype:

str

Raises OSError:

If usdcat fails

usdmanager.utils.humanReadableSize(size)

Get a human-readable file size string from bytes.

Parameters:

size : int

File size, in bytes

Returns:

Human-readable file size

Rtype:

str

usdmanager.utils.isUsdCrate(path)

Check if a file is a USD crate file by reading in the first line of the file. Doesn’t check the file extension.

Parameters:

path : str

USD file path

Returns:

If the USD file is a crate (binary) file.

Rtype:

bool

usdmanager.utils.isUsdExt(ext)

Check if the given extension is an expected USD file extension.

Parameters:ext : str Returns:If the file extension is a valid USD extension Rtype:bool

usdmanager.utils.isUsdFile(path)

Check if the given file is a USD file based on the file’s extension.

Parameters:path : str Returns:If the file extension is a valid USD extension Rtype:bool

usdmanager.utils.loadUiType(uiFile, sourceFile=None, className='DefaultWidgetClass')

Used to define a custom widget’s class.

Parameters:

uiFile : str

UI file path. Can be relative if loading from the same directory as sourceFile.

sourceFile : str

File path of loading module. Used to help find embedded resources and to find uiFile when the file path is relative.

className : str

Class name

Returns:

Class type

Rtype:

type

usdmanager.utils.loadUiWidget(path, parent=None, source_path=None)

Load a Qt Designer .ui file and return an instance of the user interface

Parameters:

path : str

Absolute path to .ui file

parent : QtWidgets.QWidget

The widget into which UI widgets are loaded

source_path : str

File loading the UI file, if the UI file is relative and needs to be found in the same directory

Returns:

The widget instance

Rtype:

QtWidgets.QWidget

usdmanager.utils.overrideCursor(*args, **kwds)

For use with the “with” keyword, so the override cursor is always restored via a try/finally block, even if the commands in-between fail.

Example:

with overrideCursor():

# do something that may raise an error

usdmanager.utils.queryItemBoolValue(url, key, default=False)

Get a boolean value from a query string.

Parameters:

url : QtCore.QUrl

Full URL with query string

key : str

Query key

default

Value if key not found

Returns:

Query value

Rtype:

bool

usdmanager.utils.queryItemValue(url, key, default=None)

Qt.py compatibility, since Qt5 introduced QUrlQuery, but Qt.py doesn’t support that. PyQt4 just uses QUrl for everything, including hasQueryItem and queryItemValue.

Parameters:

url : QtCore.QUrl

Full URL with query string

key : str

Query key

default

Value if key not found

Returns:

Query value, or None

Rtype:

str | None

Raises ValueError:  

If an invalid query string is given

usdmanager.utils.sdfQuery(link)

Process a link’s query items to see if it has our special sdf entry. This is used to pass along :SDF_FORMAT_ARGS: key/value pairs to downstream files.

Parameters:

link : QtCore.QUrl

Link

Returns:

Sdf format args

Rtype:

dict

usdmanager.utils.unzip(path, layer=None)

Unzip a usdz format file to a temporary directory.

Parameters:

path : str

Input .usdz file

layer : str | None

Default layer within file (e.g. the portion within the square brackets here: @foo.usdz[path/to/file/within/package.usd]@)

Returns:

Destination file

Rtype:

str

Raises OSError:

If unzip fails

Raises ValueError:  

If default layer not found

usdmanager.utils.usdRegEx(exts)

RegEx to find other file paths in USD-based text files.

Parameters:

exts:

Iterable of str file path extensions without the starting dot.

usdmanager.utils.usdcat(inputFile, outputFile, format=None)

Generate a temporary ASCII USD file that the user can edit.

Parameters:

inputFile : str

Input file name

outputFile : str

Output file name

format : str | None

Output USD format (e.g. usda or usdc) Only used if outputFile’s extension is .usd

Raises OSError:

If usdcat fails

Raises ValueError:  

If invalid format given compared to output file extension.

usdmanager.utils.usdzip(inputs, dest)

Zip or unzip a usdz format file.

Parameters:

inputs : str | list

Input file name(s). String or list of strings

dest : str

Output directory (for unzip) or file name

format : str | None

Output USD format (e.g. usda or usdc) Only used if outputFile’s extension is .usd

Raises OSError:

If usdzip fails

usdmanager.version module

Module contents

Application module for usdmanager.

Class hierarchy:

• App
  • UsdMngrWindow (multiple windows allowed)
    • AddressBar
    • TabWidget
      • TabBar
      • BrowserTab (one tab per file)
        • LineNumbers
        • TextBrowser
        • TextEdit

class usdmanager.AddressBar(parent)

Bases: sphinx.ext.autodoc.importer._MockObject

Custom QLineEdit class to enable drag/drop.

addressBarActivated()

Trigger loading of the current path in the address bar.

dragEnterEvent(event)

Allow drag events of a file path to the address bar.

dropEvent(event)

Allow drop events of a file path to the address bar.

goPressed

Used by autodoc_mock_imports.

openFile

Used by autodoc_mock_imports.

class usdmanager.AddressBarCompleter(model, parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

Custom completer for AddressBar.

pathFromIndex(index)

splitPath(path)

class usdmanager.App(*args, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Application class that initializes the main Qt window as defined in a ui template file.

app = None

appDisplayName = 'USD Manager'

config = None

createWindowFrame()

Create a a new widget based on self.uiSource.

Returns:A dynamically-created widget object. Rtype:CustomWidget

mainLoop()

Start the application loop.

newWindow()

Create a new main window.

Returns:New main window widget Rtype:QtGui.QWidget

onExit()

Callback when the application is exiting.

run()

Launch the application.

uiSource

alias of UsdMngrWindow

class usdmanager.BrowserTab(parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

A QWidget that contains custom objects for each tab in the browser. This primarily consists of a text browser and text editor.

changeTab

Used by autodoc_mock_imports.

dragEnterEvent(event)

Accept drag enter events from the custom file browser.

dropEvent(event)

If we receive a drop event with a file path, open the file in a new tab.

findPath(path)

Find the index of the given path in the tab’s history.

Parameters:

path : str

Path to search for in history.

Returns:

Index of the given path in the history, or 0 if not found.

Rtype:

int

getCurrentPath()

Get the absolute path of the current file.

Returns:Absolute path to current file Ex: /studio/filename.usd Rtype:str

getCurrentTextWidget()

Get the current text widget (browser or editor).

Returns:The current text widget, based on edit mode Rtype:TextBrowser | QtGui.QTextEdit

getCurrentUrl()

Get the absolute path to the current file with any query strings appended.

Returns:Absolute path to current file plus any query strings. Ex: /studio/filename.usd?line=14 Rtype:QtCore.QUrl

getFileStatus()

Get the current file’s status.

Returns:The current file’s cached status Rtype:FileStatus

isBackwardAvailable()

Check if you can go back in history.

Returns:If the backward action for history is available. Rtype:bool

isDirty()

Check if the current file has been modified in app.

Returns:If the current text editor document has been modified Rtype:bool

isForwardAvailable()

Check if you can go forward in history.

Returns:If the forward action for history is available. Rtype:bool

onActionTriggered(*args)

Slot called when a file action is activated (e.g. a file from the Recent Files menu).

openFile

Used by autodoc_mock_imports.

restoreTab

Used by autodoc_mock_imports.

setTabSpaces(useSpaces=True, tabSpaces=4)

Set the width of a tab character in spaces, both for display and editing.

Parameters:

useSpaces : bool

Use spaces instead of a tab character

spaces : int

Tab size in spaces

updateBreadcrumb()

Update the breadcrumb of file browsing paths and the action for the currently open file, which lets us restore the tab after it is closed.

updateFileStatus(truncated=False)

Check the status of a file.

Parameters:

truncated : bool

If the file was truncated on read, and therefore should never be edited.

updateHistory(url, update=False, truncated=False)

Add a newly created file to the tab’s history.

Parameters:

url : QtCore.QUrl

Link for file to add to history list.

update : bool

Update the path’s file status cache.

truncated : bool

If the file was truncated on read, and therefore should never be edited.

class usdmanager.PathCacheDict

Bases: collections.defaultdict

Cache if file paths referenced more than once in a file exist, so we don’t check on disk over and over.

class usdmanager.RecentFile(path, parent)

Bases: sphinx.ext.autodoc.importer._MockObject

Action representing an individual file in the Recent Files menu.

onClick(*args)

Signal to open the selected file in the current tab.

openFile

Used by autodoc_mock_imports.

class usdmanager.Settings(*args, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Add a method to get bool values from settings, since bool is stored as the str “true” or “false.”

boolValue(key, default=False)

Boolean values are saved to settings as the string “true” or “false”. Convert a setting back to a bool, since we don’t have QVariant objects in Qt.py.

Parameters:

key : str

Settings key

Returns:

True of the value is “true”; otherwise False. False if the value is undefined.

Rtype:

bool

class usdmanager.TabBar(parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

Customized QTabBar to enable re-ordering of tabs.

crossWindowTabMoveRequested

Used by autodoc_mock_imports.

currentWindowIndex()

Get the index of the current active window.

Returns:Index of the current active window Rtype:int

dragEnterEvent(e)

Drag enter event

Parameters:

e : QtGui.QDragEnterEvent

Drag event

dropEvent(e)

Drop event, used to move tabs.

Parameters:

e : QtGui.QDropEvent

Drop event

mouseMoveEvent(e)

Mouse move event

Parameters:

e : QtGui.QMouseEvent

Mouse move event

mousePressEvent(e)

Mouse press event

Parameters:

e : QtGui.QMouseEvent

Mouse press event

tabMoveRequested

Used by autodoc_mock_imports.

class usdmanager.TabWidget(parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

Customized QTabWidget to enable re-ordering of tabs with a custom QTabBar.

moveTab(fromIndex, toIndex)

Drag and drop tabs within the same window.

Parameters:

fromIndex : int

Original tab position

toIndex : int

New tab position

nextTab()

Switch to the next tab. If on the last tab, go back to the first.

class usdmanager.TextBrowser(parent=None)

Bases: sphinx.ext.autodoc.importer._MockObject

Customized QTextBrowser to override mouse events.

copySelectionToClipboard()

Store current selection to the middle mouse selection.

Doing this on selectionChanged signal instead of mouseReleaseEvent causes the following to be output in Qt5: “QXcbClipboard: SelectionRequest too old”

For some reason, this isn’t needed for QTextEdit but is for QTextBrowser?

mouseReleaseEvent(event)

Add support for middle mouse button clicking of links.

Parameters:

event : QtGui.QMouseEvent

Mouse release event

class usdmanager.TextEdit(parent=None, tabSpaces=4)

Bases: sphinx.ext.autodoc.importer._MockObject

Customized QTextEdit to allow entering spaces with the Tab key.

keyPressEvent(e)

Override the Tab key to insert spaces instead.

Parameters:

e : QtGui.QKeyEvent

Key press event

class usdmanager.UsdMngrWindow(parent=None, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

File Browser/Text Editor for quick navigation and editing among text-based files that reference other files. Normal links are colored blue (USD Crate files are a different shade of blue). The linked file exists. Links to multiple files are colored yellow. Files may or may not exist. Links that cannot be resolved or confirmed as valid files are colored red.

Ideas:

• Better usdz support (https://graphics.pixar.com/usd/docs/Usdz-File-Format-Specification.html)
  • Support nested references on read
  • Ability to write and repackage as usdz
• Add a preference for which files to enable teletype for (currently hard-coded to .log and .txt files).
• Plug-ins based on active file type (ABC-specific commands, USD commands, etc.)
• Link matching RegEx based on active file type instead of all using the same rules. Different extensions to search for based on file type, too.
• Cache converted crate files or previously read in files?
• Add customized print options like name of file and date headers, similar to printing a web page.
• Move setSource link parsing to a thread?
• From Pixar: There’s one feature in a tool our sim dept wrote that might be useful to incorporate into your browser, which can help immensely for big files, and it’s to basically allow filtering of what gets displayed for the usd file’s contents. Not just like pattern matching so only certain prims/properties get shown (though that is also useful), but things like “don’t show timeSamples” or “only show first and last values for each array with an ellipsis in the middle”.
• Dark theme syntax highlighting could use work. The bare minimum to get this working was done.
• Going from Edit mode back to Browse mode shouldn’t reload the document if the file on disk hasn’t changed. Not sure why this is slower than just loading the browse tab in the first place…
• More detailed history that persists between sessions.
• Cross-platform testing:
  • Windows mostly untested.
  • Mac could use more testing and work with icons and theme.
• Remember scroll position per file so going back in history jumps you to approximately where you were before.

Known issues:

• AddressBar file completer has problems occasionally.
• Figure out why network printers aren’t showing up. Linux or DWA issue? macOS and Windows are fine.
• When reading in a USDZ file, the progress bar gets stuck.
• Qt.py problems:
  • PyQt5
    • Non-critical messages
      • QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to ‘/tmp/runtime-mdsandell’
      • QXcbConnection: XCB error: 3 (BadWindow), sequence: 878, resource id: 26166399, major code: 40 (TranslateCoords), minor code: 0
  • PySide2
    • Preferences dialog doesn’t center on main window, can’t load via loadUiType
• Syntax highlighting for USD and Python incorrectly thinks # is a comment even if the # is in a quoted string.

addItemToMenu(path, menu, maxLen=None, start=0, end=None)

Add a path to a history menu.

Parameters:

path : str

The full path to add to the history menu.

menu : QtGui.QMenu

Menu to add history item to.

maxLen : int

Optional maximum number of history items in the menu.

start : int

Optional number of actions at the start of the menu to ignore.

end : int

Optional number of actions at the end of the menu to ignore.

browserBack()

Go back one step in history for the current tab.

browserForward()

Go forward one step in history for the current tab.

changeTab(tab)

Set the current tab to the calling tab.

Parameters:

tab : QtWidgets.QWidget

Tab widget

closeEvent(event)

Override the default closeEvent called on exit.

closeOtherTabs(*args)

Close all tabs except the current tab.

closeRightTabs(*args)

Close all tabs to the right of the current tab.

closeTab(checked=False, index=None)

Close the current tab.

Parameters:

checked : bool

For signal only

index : int | None

Try to close this specific tab instead of where the context menu originated.

Returns:

If the tab was closed or not. If the tab needed to be saved, for example, and the user cancelled, this returns False.

Rtype:

bool

commentOutText(commentStart='#', commentEnd='')

Comment out selected lines.

TODO: For languages that use a different syntax for multi-line comments, use that when multiple lines are selected?

Parameters:

commentStart : str

String used for commenting out lines.

commentEnd : str

If the comment can be applied to multiple lines, this is the string marking the end of the comment.

commentTextRequest()

Slot called by the Comment action.

compileLinkRegEx()

Compile regular expression to find links based on the acceptable extensions stored in self.programs.

NOTE: If this RegEx is changed, the syntax highlighting rule needs to be as well.

TODO: Support different search rules for different file extensions. Since we use the RegEx match groups in

setSource, each file type might be responsible for building its own HTML representation at that point.

connectSignals()

Connect signals to slots.

connectTabSignals(tab)

Connect signals for a new tab.

Parameters:

tab : TabWidget

Tab widget

static convertTeletype(t)

Convert teletype codes to HTML styles. This method assumes you have already escaped any necessary HTML characters.

Parameters:

t : str

Original text

Returns:

String with teletype codes converted to HTML styles.

Rtype:

str

copy()

Copy selected text in the current text editor.

createHighlighter(highlighterClass)

Create a language-specific master highlighter to be used for any file of that language.

Parameters:

highlighterClass : highlighter.MasterHighlighter

Master highlighter or subclass

Returns:

Highlighter instance

Rtype:

highlighter.MasterHighlighter

currentTabChanged(idx)

Slot called when the current tab has changed.

Parameters:

idx : int

Index of the newly selected tab

customTabWidgetContextMenu(pos)

Slot for the right-click context menu for the tab widget.

Parameters:

pos : QtCore.QPoint

Position of the right-click

customTextBrowserContextMenu(pos)

Slot for the right-click context menu when in Browse mode.

Parameters:

pos : QtCore.QPoint

Position of the right-click

customTextEditorContextMenu(pos)

Slot for the right-click context menu when in Edit mode.

Parameters:

pos : QtCore.QPoint

Position of the right-click

cut()

Cut selected text in the current text editor.

decreaseFontSize()

Decrease font size in the text browser and editor.

defaultFontSize()

Reset the text browser and editor to the default font size.

diffFile()

Compare current version of file in app to current version on disk. Allows you to make comparisons using a temporary file, without saving your changes.

dirtySave()

Present a save dialog for dirty tabs to know if they’re safe to close/reload or not.

Returns:False if Cancel selected. True if Discard selected. True if Save selected (and actually saving). Rtype:bool

disconnectTabSignals(tab)

Disconnect signals for a tab.

Parameters:

tab : TabWidget

Tab widget

duplicateTab()

Duplicate the tab that was right-clicked. This doesn’t duplicate edit state or any history at the moment.

editModeChanged

Used by autodoc_mock_imports.

editPreferences()

Open Preferences dialog

fileInfo()

Display information about the current file.

find(flags=None, startPos=3, loop=True)

Find next hit for the search text.

Parameters:

flags

Options for document().find().

startPos : int

Position from which the search should begin. 0=Start of document 1=End of document 2=Start of selection 3=End of selection (default)

loop : bool

True lets us loop through the beginning or end of a document if the phrase was not found from the current position. False limits that behavior so that we don’t endlessly loop.

find2(startPos=3, loop=True, findText=None)

Find functionality for find/replace dialog.

Parameters:

startPos : int

Position from which the search should begin. 0=Start of document 1=End of document 2=Start of selection 3=End of selection (default)

loop : bool

True lets us loop through the beginning or end of a document if the phrase was not found from the current position. False limits that behavior so that we don’t endlessly loop.

findText : str

Text to find.

findAndReplace(findText, replaceText, startPos=0)

Replace a single occurrence of a phrase.

Parameters:

findText : str

Text to find

replaceText : str

Text to replace with

startPos : int

Position from which the search should begin. 0=Start of document (default) 1=End of document 2=Start of selection 3=End of selection

Returns:

Whether or not a match was found.

Rtype:

bool

findHighlightAll()

Highlight all hits for the search text.

findPrev()

Find previous hit for the search text.

getCommentStrings()

Get the language-specific string(s) for a comment.

Returns:Tuple of start str and end str defining a comment. Rtype:tuple

getFindText()

Get the text to find.

Returns:The search text from the Find/Replace dialog. Rtype:str

static getPermissionString(path)

Get permissions string for a file’s mode. Qt.py compatibility fix since QFileInfo.permissions isn’t in PySide2.

Parameters:

path : str

File path

Returns:

String corresponding to read (r), write (w), and execute (x) permissions for file.

getReplaceText()

Get the text to replace the search text with.

Returns:The replace text from the Find/Replace dialog. Rtype:str

getSaveAsPath(path=None)

Get a path from the user to save an arbitrary file as.

Parameters:

path : str | None

Path to use for selecting default file extension filter.

Returns:

Tuple of the absolute path user wants to save file as (or None if no file was selected or an error occurred) and the file format if explicitly set for USD files (e.g. usda)

Rtype:

(str`|None, `int)

goPressed(*args)

Handle loading the current path in the address bar.

goToLineNumber(line=1)

Go to the given line number

Parameters:

line : int

Line number to scroll to. Defaults to 1 (top of document).

goToLineNumberDlg()

Get a line number from the user and scroll to it.

hoverUrl(link)

Slot called when the mouse hovers over a URL.

increaseFontSize()

Increase font size in the text browser and editor.

indentText(numSpaces=4)

Indent selected lines by the given number of spaces.

Parameters:

numSpaces : int

Number of spaces used for indenting.

launchProcess(args, shell=False, **kwargs)

Launch a program with the path str as an argument.

Parameters:

args : list | str

A sequence of program arguments with the program as the first arg. If shell=True, this should be a single string.

shell : bool

Run in a shell

Returns:

Returns process ID or None

Rtype:

subprocess.Popen | None

launchProgramOfChoice(path=None)

Open a file with a program given by the user.

Parameters:

path : str

File to open. If None, use currently open file.

launchTextEditor()

Launch the current file in a separate text editing application.

launchUsdView()

Launch the current file in usdview.

moveTab(fromIndex, toIndex)

Rearrange tabs in menu after a drag/drop event. This isn’t moving the tab itself. That’s handled in the TabWidget class.

Parameters:

fromIndex : int

Original tab position

toIndex : int

New tab position

moveTabAcrossWindows(fromIndex, toIndex, fromWindow, toWindow)

Rearrange tabs in menu after a drag/drop event. This isn’t moving the tab itself. That’s handled in the TabWidget class.

Parameters:

fromIndex : int

Original tab position

toIndex : int

New tab position

newTab(*args)

Create a new tab.

newWindow()

Create a new window.

Returns:New main window widget Rtype:QtGui.QWidget

onBackspace()

Handle the Backspace key for back browser navigation.

onBreadcrumbActivated(path)

Slot called when a breadcrumb link (history for the current tab) is selected.

onBreadcrumbHovered(path)

Slot called when the mouse is hovering over a breadcrumb link.

onOpen(path)

Open the path in a new tab.

Parameters:

path : str

File to open

onOpenLinkNewTab()

Open the currently highlighted link in a new tab.

onOpenLinkNewWindow()

Open the currently highlighted link in a new window.

onOpenLinkWith()

Show the “Open With…” dialog for the currently highlighted link.

openFileDialog()

Show the Open File dialog and open any selected files.

openUrl(checked=False, url=None)

Open a URL in a web browser. This method doesn’t do anything if the URL evaluates to False.

Parameters:

checked : bool

For signal only

url : str

A URL to open. If one is not provided, it defaults to self.appURL.

overrideCursor(**kwds)

For use with the “with” keyword, so the override cursor is always restored via a try/finally block, even if the commands in-between fail.

Example:

with overrideCursor():

# do something that may raise an error

paste()

Paste selected text in the current text editor.

printDialog(checked=False)

Open a print dialog.

Parameters:

checked : bool

For signal only

printPreview(checked=False)

Open a print preview dialog.

Parameters:

checked : bool

For signal only

readSettings()

Read in user config settings.

readUsdCrateFile(fileStr)

Read in a USD crate file via usdcat converting a temp file to ASCII.

Parameters:

fileStr : str

USD file path

Returns:

ASCII file text

Rtype:

bool

redo()

Redo last change in the current text editor.

refreshSelectedTab()

Refresh the tab that was right-clicked.

refreshTab()

Refresh the current tab.

removeTab(index)

Stores as recently closed tab, then closes it.

Parameters:

index : int

Index of tab to remove.

replace(findText=None, replaceText=None)

Replace next hit for the search text.

replaceAll()

Replace all occurrences of the search text.

replaceAllInOpenFiles()

Iterate through all the writable tabs, finding and replacing the search text.

replaceFind()

Replace next hit for the search text, then find the next after that.

restoreOverrideCursor()

If an override cursor is currently set, restore the previous cursor.

restoreTab(tab)

Restore a previously closed tab.

Parameters:

tab : QtWidgets.QWidget

Tab widget

saveFile(filePath, fileFormat=4, _checkUsd=True)

Save the current file as the given filePath.

Parameters:

filePath : str

Path to save file as.

fileFormat : int

File format when saving as a generic extension

_checkUsd : bool

Check if this needs to be written as a binary USD file instead of a text file

Returns:

If saved or not.

Rtype:

bool

saveFileAs()

Save the current file with a new filename.

Returns:If saved or not. Rtype:bool

saveLinkAs()

The user right-clicked a link and wants to save it as a new file. Get a new file path with the Save As dialog and copy the original file to the new file, opening the new file in a new tab.

saveTab()

If the file already has a name, save it; otherwise, get a filename and save it.

Returns:If saved or not. Rtype:bool

selectAll()

Select all text in the current focused widget.

setDirtyTab(dirty=True)

Set the dirty state of the current tab.

Parameters:

dirty : bool

If the current tab is dirty.

setHighlighter(ext=None)

Set the current tab’s highlighter based on the current file extension.

Parameters:

ext : str | None

File extension (language) to highlight.

setIncludePanelActionState(pos=0, index=0)

Set the check state of the include panel action. If it is visible, the action will be checked.

Parameters:

pos : int

Position from left edge of widget. For catching signal only.

index : int

Splitter handle index. For catching signal only.

setOverrideCursor(cursor=<sphinx.ext.autodoc.importer._MockObject object>)

Set the override cursor if it is not already set.

Parameters:

cursor

Qt cursor

setSource(link, isNewFile=True, newTab=False, hScrollPos=0, vScrollPos=0)

Create a new tab or update the current one. Process a file to add links. Send the formatted text to the appropriate tab.

Parameters:

link : QtCore.QUrl

File to open.

isNewFile : bool

Optional bool for if this is a new file or an item from history.

newTab : bool

Optional bool to open in a new tab no matter what.

hScrollPos : int

Horizontal scroll bar position.

vScrollPos : int

Vertical scroll bar position.

setSourceFinish(success=True, warning=None, details=None)

Finish updating UI after loading a new source.

Parameters:

success : bool

If the file was loaded successfully or not

warning : str | None

Optional warning message

details : str | None

Optional details for the warning message

Returns:

Success

Rtype:

bool

setSources(files)

Open multiple files in new tabs.

Parameters:

files : list

List of string-based paths to open

setupUi()

Create and lay out the widgets defined in the ui file, then add additional modifications to the UI.

showAboutDialog(*args)

Display a modal dialog box that shows the “about” information for the application.

showAboutQtDialog(*args)

Show Qt about dialog.

showCriticalMessage(message, details=None, title=None)

Show an error message with optional details text (useful for tracebacks).

Parameters:

message : str

Main message

details : str | None

Optional details

title : str

Dialog title (defaults to app name)

Returns:

Selected StandardButton value

Rtype:

int

showFindReplaceDlg()

Show the Find/Replace dialog.

showSuccessMessage(msg, title=None)

Display a generic message if the user’s preferences are not set to only show warnings/errors.

Parameters:

msg : str

Message to display.

title : str | None

Optional title.

showWarningMessage(message, details=None, title=None, icon=<sphinx.ext.autodoc.importer._MockObject object>)

Show a warning message with optional details text (useful for tracebacks).

Parameters:

message : str

Main message

details : str | None

Optional details

title : str

Dialog title (defaults to app name)

icon : int

QMessageBox.Icon

Returns:

Selected StandardButton value

Rtype:

int

stopTab()

Stop loading the current tab.

tabIterator()

Iterator through the tab widgets.

toggleEdit()

Switch between Browse mode and Edit mode.

toggleFind()

Show/Hide the Find bar.

toggleFindClose()

Hide the Find bar.

toggleFullScreen(*args)

Toggle between full screen mode

toggleInclude(checked)

Show/Hide the side file browser.

Parameters:

checked : bool

State of checked menu.

uncommentText(commentStart='#', commentEnd='')

Uncomment selected lines.

Parameters:

commentStart : str

String used for commenting out lines.

commentEnd : str

If the comment can be applied to multiple lines, this is the string marking the end of the comment.

uncommentTextRequest()

Slot called by the Uncomment action.

undo()

Undo last change in the current text editor.

unindentText(numSpaces=4)

Un-indent selected lines by the given number of spaces.

Parameters:

numSpaces : int

Number of spaces used for indenting.

updateButtons()

Update button states, text fields, and other GUI elements.

updateEditButtons()

Toggle edit action and button text.

updatePreference_findMatchCase(checked)

Stores a bool representation of checkbox’s state.

Parameters:

checked : int

State of checkbox.

updatingButtons

Used by autodoc_mock_imports.

validateAddressBar(address)

Validate the text in the address bar. Currently, this just ensures the address is not an empty string.

Parameters:

address : str

Current text in the address bar.

validateFileSize(path)

If a file’s size is above a certain threshold, confirm the user still wants to open the file.

Parameters:

path : str

File path

Returns:

If we should open the file or not

Rtype:

bool

validateFindBar(text)

Update widgets on the Find bar as the search text changes.

Parameters:

text : str

Current text in the find bar.

viewSource(checked=False)

For debugging, view the source HTML of the text browser widget.

Parameters:

checked : bool

Just for signal

writeSettings()

Write out user config settings.