Shotgun Desktop The engine that runs inside the Shotgun Desktop Application Latest Version: v2.5.0 (prod) For our version numbers, we follow the Semantic Versioning standard. System Name: tk-desktop

Documentation

The tk-desktop engine is an application to let you easily run your Toolkit apps. It is a system tray based window that makes it easy to get started with Toolkit, setup Projects for Toolkit, and access your Projects' pipeline.

If you have already set up your first project and you are looking for help configuring it to meet your needs, see our 'next steps' documentation:

> Beyond your first project

Site configuration and Project configuration

When you launch the desktop application, it will startup the tk-desktop engine for your site configuration. This configuration is usually automatically managed, although it is possible to disable that behavior and take control over what is in that environment.

One of the fundamental principles of Toolkit is that projects can be completely isolated from each other. This is usually done to make sure that changes made to one project cannot adversely effect another project (possibly nearing delivery). In order to offer this project isolation, the desktop engine makes sure that whenever you are looking at the commands for a particular project, you will run them in a separate python interpreter that has been initialized just for that project.

When you click on a project, a python interpreter is launched in the background. This python interpreter is the one the project has been configured to use and on startup will initialize the tk-desktop for that project. That instance of the engine will communicate back to the GUI what commands it can launch.

When you click on a command, that background python process is responsible for launching the command. This makes it possible (for example) to have one project running python 2.6 while testing python 2.7 on another project.

Registering custom panels

Toolkit apps which have panel based UI will be automatically docked in tabs inside of Desktop when they execute.

If you have a panel based app such as the Shotgun Panel, and want it to appear as a tab in Shotgun desktop, just configure it to run at startup. When Desktop starts up in its site context mode (where it displays all projects), it will launch all items registered to auto start. If any of these items are panels, these will get docked. Items will be processed in the order they are defined in the configuration and this will dictate the tab order.

For example, if you wanted the Shotgun Panel to show as a tab in Shotgun Desktop, add the following configuration for your site level environment:

tk-desktop:
  apps:
    tk-multi-shotgunpanel:
      actions_hook: ...
      action_mappings: ...
      location: ...
  location: ...
  run_at_startup:
  - {app_instance: '', name: Apps}
  - {app_instance: tk-multi-shotgunpanel, name: ''}

Please note that the special Apps entry controls where (in the tab order) the default Apps tab should appear.

> The Shotgun Panel.

Installation and Updates

Adding this Engine to the Shotgun Pipeline Toolkit

If you want to add this engine to Project XYZ, and an environment named asset, execute the following command:

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-desktop.

Special Requirements

• You need Shotgun Pipeline Toolkit Core API version v0.19.5 or higher to use this.

Configuration

Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.

software_entity_config_link

Type: str

Default Value: https://support.shotgunsoftware.com/entries/95443887#Setting%20up%20Application%20Paths

Description: Link to a Shotgun Support article detailing how to configure Software entities for a site.

run_at_startup

Type: list

Default Value: [{u'app_instance': u'', u'name': u'Apps'}]

Description: Controls what apps will run on startup. This is a list where each element is a dictionary with two keys: 'app_instance' and 'name'. The 'app_instance' value connects this entry to a particular app instance defined in the environment configuration file. The 'name' is the menu name of the command to run when desktop starts up. If 'name' is '', then all commands from the given app instance are started. To add the 'Apps' tab (which contains the app launcher), add the following startup command to the list: {app_instance: '', name: 'Apps'}

show_recents

Type: bool

Default Value: True

Description: Controls whether to show the recently clicked on commands

debug_logging

Type: bool

Description: Controls whether debug messages should be emitted to the logger

collapse_rules

Type: list

Default Value: [{u'menu_label': u'None', u'match': u'Launch $app', u'button_label': u'$app'}]

Description: A list of dictionaries that define how to collapse multile commands into a single button in the GUI. Each dictionary needs to have the following keys: match - a string that will match against the display name of a registered command, button_label - what the text label of the resulting button should be, menu_label - what the text label of the item in the button's menu should be. As commands are added to the engine, their display name will be compared to each match in turn. The match string can contain '$' style variables, which will be matched against any single word in the dislay name of the command. Those '$' variables are available for use in the button_label and the menu_label. For example a match of 'Launch $APP $VERSION' will match any display name made up of 'Launch' followed by two words. If the display name is 'Launch Maya 2014' then this would match, and the value of '$APP' would be 'Maya' and the value of '$VERSION' would be '2014'. If menu_label is the special string 'None' then the button name will be translated per the value of button_label, but no menu entry will be added for the commands. If multiple commands collapse down to a button in this way, only the first one will be registered. If a display name does not match any collapse rule, then it will show up as a button without any menu. The first matching rule will determine the button and menu labels.

default_group

Type: str

Default Value: Studio

Description: Controls the name of the default command grouping for any commands that do not match any of the values in the groups setting.

hook_launch_python

Type: hook

Default Value: launch_python

Description: This hook is responsible for launching the python interpreter for a specific project. The first argument to the hook is 'project_python', the path to the python interpreter to be launched. The next argument to the hook is 'pickle_data_path' which is a full path to a python pickle that contains the info needed to initialize the project's tk-desktop engine and talk back to the desktop GUI. The third argument is the path to a utilities python module. This module should be loaded in the new interpreter and used to start up the engine.

sg_software_entity

Type: str

Default Value: CustomNonProjectEntity23

Description: Shotgun CustomNonProjectEntity designated as the Software entity until it becomes native.

groups

Type: list

Description: A list of dictionaries that define what commands get put in which groups. Each dictionary entry needs to have the following keys: name - the name of the group, matches - a list of strings for what commands to add to the group. As commands are added to the engine, each match from the group's matches list will be treated as a case insensitive glob style match against the command's display name. If there is a match then the command will be added to the group. For example 'Maya' will match against any command that contains the string 'maya' in the display name, regardless of case. It is possible for a command to show up in multiple groups if it has matches against multiple groups.

Release Notes

Welcome to the release notes for this App. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!

v2.5.0

2020-Mar-31

Projects using a Python 3 interpreter can now be launched from Shotgun Desktop.

Details:

Once a project has been configured to use Python 3 by editing the config/core/interpreter_<os>.cfg file inside a centralized configuration or the core/interpreter_<os>.cfg inside a distributed or descriptor-based configuration, Shotgun Desktop will launch that project with Python 3.

Thank you to @aparna-d2 for providing the PySide2 support code.

v2.4.14

2020-Jan-24

Fixes a regression in the last release, where python processes would be left orphaned instead of being closed when leaving the project in Shotgun Desktop.

v2.4.13

2020-Jan-07

Shotgun Desktop should now log a full error traceback if an error occurs when loading a project configuration, or when running an app.

v2.4.12

2018-Jun-27

Fixes a bug where Project Filesystem Folder would not be displayed in the Desktop menu.

Details:

Note that this fix is applicable only to projects configured through the Advanced Project Setup. Cloud-based and descriptor-based configurations cannot display this menu item at the moment due to a technical limitation.

v2.4.11

2018-Apr-17

Bumps required core version to v0.18.143

v2.4.10

2018-Apr-11

Better error handling when tank_name is not set on a project.

v2.4.6

2018-Mar-22

Shotgun Desktop will now provide a clearer error message when a pipeline configuration has not been properly configured.

v2.4.5

2018-Mar-19

Shotgun Desktop will not freeze when downloading big configurations from Shotgun.

v2.4.3

2018-Jan-22

Resolves an issue where errors raised during bootstrap were not reported to the user on Windows.

v2.4.2

2017-Dec-06

Fixed project menu duplicated items on invoking 'Reload and Restart' also updated metrics logged.

v2.4.1

2017-Nov-28

Fixes project menu duplicating menu items on invoking 'Reload and Restart'

v2.4.0

2017-Nov-10

Adds debug logging toggle to Advanced menu

v2.3.12

2017-Oct-26

Update engine to use newer metrics API

v2.3.11

2017-Oct-23

Updated to make use of the new metrics API provided by tk-core.

v2.3.10

2017-Sep-25

Hides Regenerate Certificates option when using shotgunlocalhost.com.

v2.3.8

2017-Aug-18

Ensures widget instance is properly returned from show_panel

v2.3.7

2017-Jul-25

Fixes a crash that occurred immediately after selecting a project using Python 2.6.

v2.3.6

2017-Jul-21

Fixes an issue when a project uses a Toolkit core more recent than the Shotgun Desktop.

v2.3.2

2017-Jul-19

Fixes a bug causing panel dialogs not to open when in project mode.

v2.3.1

2017-Jul-17

Custom panels now pick up standard stylesheets.

v2.3.0

2017-Jun-19

Adds support for tabs and apps running at startup.

v2.2.4

2017-Jun-13

hot fix for first launch notification

v2.2.3

2017-Jun-12

This release fixes some UI issues in addition to reporting usage statistics to Shotgun about which version of the Shotgun Desktop is being used.

Details:

The various UI enhancements fixes are: - Product name is no longer displayed twice on shortcuts. - Adds a Help menu to the user menu. - Fixed some links pointing to outdated documentation. - Toolkit apps launched from the Shotgun Desktop will now log back to the Shotgun Desktop console.

v2.2.2

2017-Jun-07

Is it now possible to regenerate the browser integration certificates from the user menu.

v2.1.9

2017-Jun-05

Fixes an issue with unicode strings and environment variables on Windows.

v2.1.8

2017-Jun-01

Adds support for Shotgun Integrations.

v2.0.28

2017-Mar-30

Fixes an issue where sometimes an empty dialog would appear when launching an app on Windows.

v2.0.27

2017-Mar-24

Fixes an authentication related issue and a window positioning bug on Windows 10.

Details:

• On Windows 10, the Shotgun Desktop dialog will not be cropped if the tray area is too small.
• Fixes an authentication issue that can arise when using 0.18-based projects with Shotgun Desktop. In those circumstances, the Shotgun Desktop would not display the available Toolkit applications after selecting a project.

v2.0.23

2016-Dec-06

Show or hide project menu item 'Project Filesystem Folder'.

Details:

Show or hide project menu item 'Project Filesystem Folder' based on the availability of the project locations.

v2.0.22

2016-Sep-23

Fixes multiple UI issues.

Details:

• The project menu at the top right no longer grows as you switch pipeline configurations.
• The "Refresh Projects" menu item in the user menu at the bottom right is no longer present when inside a project.
• The "Setup Project" message is no longer rendered over the launcher icons after configuring a project.

v2.0.21

2016-Sep-09

Fixes a bug where logging a non-string value with log_exception would raise an exception.

v2.0.20

2016-Sep-08

Fixes a bug where logging a non-string value with log_exception would raise an exception.

v2.0.19

2016-Aug-25

Updates the framework dependencies to the latest major version.

v2.0.18

2016-Aug-23

Fixes for hanging Python processes and the initial launch of a dialog being hidden.

Details:

This release fixes an issue where the Shotgun Desktop will not properly close Python subprocesses when switching project or the Shotgun Desktop is closed. It also fixes an issue on Windows where the first launch of a GUI based Toolkit application will not show any UI.

While the Desktop application and the pipeline configuration can be updated separately, both need to be updated to fix the Python process leaks.

v2.0.16

2016-Aug-10

Fix for exception that can occur when turning show_recents off. Note: v2.0.14 and v2.0.15 were skipped due to issues found in QA.

v2.0.13

2016-Jun-07

Minor improvements to management of recent apps settings

v2.0.12

2016-Jun-07

minor improvements to management of recent apps settings management

v2.0.11

2016-Jun-01

No longer use the event log for tracking recent activity

Details:

Improves performance by storing recents using the settings module instead of requiring calls to Shotgun.

v2.0.10

2016-Feb-22

Clicking the search icon automatically focuses the text widget.

v2.0.9

2015-Nov-12

Friendlier error behaviour on empty OS path

Details:

Friendlier error messages and allow to change the pipeline config even if loading the current config failed.

v2.0.8

2015-Oct-09

Change the tray icon to fit in OSX Dark mode.

v2.0.7

When restarting the Desktop, the login screen will always be displayed.

Details:

In the newest version of the Shotgun Desktop, not being logged in on startup sends the user in tray-mode. The user then needs to click on the tray icon and pick "Sign in to Shotgun Desktop" in order to login. When signing out of the Desktop however, the Desktop will be restarted and jump straight into the login screen.

v2.0.6

Fixed a bug on Windows where restarting the Shotgun Desktop kept port 9000 alive even tough the Desktop had been closed.

Details:

Once you have restarted the Shotgun Desktop and let it auto-update itself, you will probably encounter the port 9000 issue again. You will need to quit all applications that were launched from the Shotgun Desktop or from a web browser. You will also need to close the Shotgun Desktop itself. Then launching the Shotgun Desktop again should work without any issues.

If you still encounter the port 9000 issue, something else might be holding on to it. Please log out of your Windows user account and log back in. This should definitely release the port 9000 once and for all and then the Shotgun Desktop will able to launch and close port 9000 correctly in the future.

v2.0.5

Adds support for two factor authentication using the 1.0.x Shotgun Desktop.

v2.0.4

Fixes the Project Filesystem Folder launcher.

v2.0.3

Fixes a crash when adding the tk-desktop engine to the project context.

v2.0.2

Users only see the projects they have permissions for.

v2.0.1

Tweaked when credentials are refreshed.

Details:

When the project configuration is login based, the desktop engine will refresh the credentials before launching any app, possibly prompting the user for this password., even if the site project is script based.

v2.0.0

Added support for login based authentication from v0.16.0.

Details:

Added support for login based authentication from v0.16.0.

v2.0.0RC9

Release Candidate 9.

v1.0.13

Better error handling around missing Python interpreter. Misc changes.

Details:

• Better checks and prompting when python is not found a project.
• Fixed issue with font sizes being inconsistent across operating systems.
• Updated copyright notice.

v1.0.12

Fixed a bug with Shotgun Desktop 1.02.

Details:

Fixed a bug with Shotgun Desktop 1.02.

v1.0.11

Filtering out Shotgun 6.0 Template Projects from the project selection screen.

Details:

Filtering out Shotgun 6.0 Template Projects from the project selection screen.

v1.0.10

Display better error message when project is already set up

v1.0.9

About Box now displays the version of core.

Details:

About Box now displays the version of core.

v1.0.8

Instrument time spend querying event logs.

v1.0.7

Fix for crash if there is an error on logout.

v1.0.6

Fix for windows subprocess bug when updating project config on Windows.

v1.0.5

"Always on Top" Setting Disrupts "Browse" Windows in Setup Wizard

Details:

When browsing for a config in project setup wizard on mac, the file finder appears under every one of our windows. This fixes the issue by removing the always on top setting while the wizard is running.

v1.0.4

Update the project python bootstrap to reset PATH

Details:

Prevents DLL loading issues with some engines (maxplus) on windows.

v1.0.3

Bug fix for when the model storing project data has no associated Shotgun data.

v1.0.2

Updated manifest with tweaked display name and description.

v1.0.1

Updated documentation

v1.0.0

Visual polish and a few small bug fixes.

Details:

• Sort commands within groups alphabetically
• Visual polish for the setup new os screen
• Pack command widgets in a little tighter
• Items in the command menu are sorted latest version to oldest version
• Default button action is the first action in its menu
• Limit the number of recent commands
• Fix for floating editor when scrolling commands
• Update to use login framework v1.x
• Switch to subprocess for restart on log out for better Windows behavior

v0.1.17

Bug fix and handle projects not set up for current OS.

Details:

• Added screen for when a configuration has not been set up for the current os
• Fix for projects not showing up on first launch
• Dark icon for default user thumbnail

v0.1.16

Updated to be compatible with the new splash screen. New project icon.

v0.1.15

Visual polish. Fix for copying from the console.

Details:

Fix for right clicking on a project or command triggering it Fixed Console menu. Made copy work. Search icon highlights on hover Preserve Project thumbnail size and grow to handle long Project Names Clip long project names for the project header Pretty up the Shotgun and User buttons a little Default values to strip "Launching" from default config's launcher setup Updated about screen

v0.1.14

Fix for bug that broke project filtering via the search box

v0.1.13

Lots of GUI changes.

Details:

No longer show the console automatically Remove preferences dialog Project thumbnails squared Fix for auto-hide when a sub-dialog got focus Don't show empty groups About screen No recent projects shelf Various other visual tweaks

v0.1.12

Major update of the engine, including setup project UI and no requirement for PySide/PyQt for project pythons.

Details:

• Added setup project UI for when clicking on a project that has not been setup in Toolkit
• Added instructions for turning on Toolkit when connecting to a site with Toolkit off
• Remember what groups are expanded
• Console window for logging
• Highlight matching characters from the fuzzy search algorithm
• Use the login framework
• Added ability to refresh the project model

v0.1.11

Fix for disabled Shotgun menu in some launched apps.

v0.1.10

Override python icon. Better logout behavior. PyQt support for project python.

v0.1.9

Use v2 of the shotgunutils framework.

v0.1.8

Added a hook to launch python and updated the gui code to be more model/view based.

Details: New hook that lets studios take over the launching of the project specific python if they need to. Updated the GUI code to be more model/view based so commands are more consistent.

v0.1.7

Bug fix to explicitly add .pyd file on windows for osutils extension.

v0.1.6

Added ability to choose Pipeline Configurations other than Primary.

v0.1.5

Better systray click handling. Raise hotkey and start on login options.

v0.1.4

Added project loading spinners and a splash screen.

v0.1.3

Update the version of the shotgunutils framework.

v0.1.2

Support for docking to any side of the screen and stylesheet for sub-process.

v0.1.1

A bunch of little fixes. Better (but not yet great) windows support.

v0.1.0

Initial app store release.

v0.0.1

Initial test release