Shotgun Desktop

Shotgun Desktop

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

Table of Contents:

Overview Summary

Documentation

      Usage

            The system tray

            The project browser

            The command launcher

            The console

      Architecture

            Site configuration and Project configuration

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

The Desktop Engine is the engine which runs inside of the Shotgun Desktop Application. It handles UI functions and establishes a bridge between Toolkit apps and the Shotgun Desktop Application.

Overview Video

The following video gives a quick overview of features and functionality.

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.

This doc is a short users guide for the Desktop app. If you are looking to download the Desktop app or for a guide on how to get started with Toolkit, please see our documentation on setting up your first project:

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:

Usage

The system tray

When the application starts up it shows up as an icon in your system tray. To show the window, click the icon. By default the window will be pinned to the system tray, which means that if the window loses focus, it will automatically hide itself.

You can unpin the window by selecting "Undock from Menu" from the user menu or by dragging it by its header. When the window is unpinned it will look like a regular window and will no longer hide itself when it loses focus.

While the window is undocked, you can hide it by clicking on the close button. To show it again, click on the system tray icon.

The project browser

The first main view of the app is the project browser. Here you will see all the projects in your Shotgun instance. Your most recently accessed projects will be listed first.

Clicking on a project will take you to the command launcher view for that project, where you can launch the tools in the project's configuration.

Near the bottom right of the window you will see your Shotgun account's thumbnail. This is the user menu, where you can do things like dock/undock the window, keep it on top of other windows, and show the logging console.

At the top of the window, you can click on the magnifying glass icon to show the search box. Typing in this box will filter the list of projects shown to just those that contain the letters you are typing.

The command launcher

Once you've clicked on a project you are taken to the command launcher for that project. This window will show whatever Toolkit apps are configured for the desktop engine in the project's configuration.

This window shows a grid of buttons. Simply click on a button to launch its app. The app will run in a project specific environment, and if it is an app that Toolkit supports, you'll have access to all your pipeline tools already setup for you.

The command launcher can show the most recent commands you've launched so it is easy to get at your most used tools. The commands can be grouped into collapsible groups so that they are easy to organize. Multiple commands can also be collapsed into a single button, for things like giving access to multiple versions of Maya while still having a single Maya button.

How commands are grouped, and how they are collapsed is completely customizable. See the documentation on the engine settings below for details.

Click for details on the environment and pipeline configurations that populate this view

The command launcher window always uses the project environment from the project's primary configuration. If you have access to more than one pipeline configuration for the project, you can switch between them from the project menu on the right hand side of the project header.

For more information on how to use multiple pipeline configurations for a project, see our document on managing your project configuration:

The console

You can launch the console from the user menu. The logs from launching a project are displayed here. If you run into an error, the details of the error should be shown here.

If you right click on the console, you are given a standard edit menu, allowing you to select all of the text, copy your selection, or to clear the text in the console.

Architecture

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.

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:

> tank Project XYZ install_engine asset tk-desktop

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

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.

show_recents

Type: bool

Default Value: True

Description: Controls whether to show the recently clicked on commands

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.

debug_logging

Type: bool

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

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

Follow

17 Comments

  • 0
    Avatar
    John Coldrick

    In terms of best practices going forward, does it make sense to say that in an ideal world, the path to python in the site-wide Shotgun config will eventually be set to the bundled python that comes with the shotgun desktop?  I realize technically that's not required, and larger shops might well have all sorts of reasons to point to their own, but would that be a good idea?  Right now we have a config that points at C:\Python26, I was thinking about upgrading everyone to 27, but there's something to be said for pointing it to C:\Program Files\Shotgun\Python, right?

  • 0
    Avatar
    Mitchell Lotierzo

    I may be doing something wrong, but it seems like the "groups" configuration setting isn't working. I have it set to:

    groups:

    - {name: Softimage Tools, matches: ['Softimage']}

    - {name: Nuke Tools, matches: ['Nuke']}

     

    The only group I see in the UI is "Studio" still.

  • 0
    Avatar
    Rob Blau

    Hi John,

    We intend the built in python to be a good option for your configs.  We bundle in some modules that are used in the toolkit code (PySide being the big one, but also something like the win32 module which the login framework can use if available) which makes it easy to setup.  If you are going to be installing the desktop for everybody, then either choice should work for you, but pointing to ours would mean that you have slightly more up to date installs (python 2.7, Qt 4.8, PySide 1.2.1).

    We aren't going to mandate that infrastructure for your projects, but we do want to have it readily available as a good option if you want to use it.

  • 0
    Avatar
    Rob Blau

    Hi Mitchell,

    The syntax for the groups setting needs a glob style string for the matches.  If you do something like this, do you start seeing what you'd expect?

    groups:

    - {name: Softimage Tools, matches: ['* Softimage *']}

    - {name: Nuke Tools, matches: ['* Nuke *']}

  • 0
    Avatar
    Mitchell Lotierzo

    That works. Thanks for that little bit of guidance :)

    I've also noticed something in the console that may be of concern. It looks like it is pulling PySide from the Fabric Engine directory?

    "2014-08-14 12:01:35,829 [ DEBUG] [PROXY] Successfully initialized PySide '1.1.2' located in C:\Program Files\Fabric Engine\Python\2.7\PySide\__init__.pyc."

    Is that going to be problematic? I'm assuming it should be pointing to the PySide that comes bundled with the desktop engine, right?

  • 0
    Avatar
    Rob Blau

    Glad that worked for you.

    Too many things fighting for control of that global PYTHONPATH.  :)

    We will be pushing out a fix next week that'll make sure that when the app starts up it pulls in the intended toolkit install and other bundled modules (including PySide).  So yes, that is a potential issue right now, but we've got it in our sights and'll be pushing out a fix soon.  Thanks for letting us know about it!

  • 0
    Avatar
    Mitchell Lotierzo

    Awesome. Thanks.

    One more thing! :) It would be nice to have control over how the versions are sorted for a command. I specified the 'versions' param for my app launcher like "['2012', '2013', '2014']" and it still sets 2014 as the default (the entry with an asterisk). I thought whichever value was first in the list was considered the default?

    Awesome job by the way. I'm loving this new engine so far. 

  • 0
    Avatar
    Rob Blau

    Hi Mitchell,

    Unfortunately right now if you collapse multiple versions into a button the most recent one is the one that'll be the default.  We are going to be updating that to give you more control over the order those commands get collapsed in, but unfortunately that didn't make the initial release of the engine.  For the time being you'd need to separate out 2012 as its own group to separate it from the rest.

    We'll be updating the engine soon and this is one of the higher priority changes to come.

    Glad you're liking it!

  • 0
    Avatar
    David van Heeswijk

    Hey Guys,

    We're using Gnome 3 on some of our newer Linux boxes.
    Under Gnome 2, the Shotgun Desktop icon was visible in the top bar, like under OSX.

    Now on Gnome 3, the icon is in the system tray (hidden in a drawer in the bottom of the screen) which you can acces by pressing command (or windows key) + M. However, we would like the same behaviour like under Gnome 2.

    Is there a way to get the icon back to the top of the screen by default?

    Cheers,

    David

  • 0
    Avatar
    Rob Blau

    Hi David,

    The Gnome 3 notification setup definitely leaves a little to be desired.  From what I can tell you need to use a shell extension to be able and use it.  This is the one that seems to do what you'd want:

    https://extensions.gnome.org/extension/99/evial-status-icon-forerver/

    although you might want the fork from this repo:

    https://github.com/mathematicalcoffee/EvilStatusIconForever

    Does that look like it would work for you?

  • 0
    Avatar
    Patrick Macdonald

    Is it possible to open a project in a pipeline-config clone rather than the primary pipeline-config? 

  • 0
    Avatar
    Patrick Macdonald

    Ah found it, there's a dropdown in the desktop project page providing access to dev environments.

  • 0
    Avatar
    Matthias Wäsch - Celluloid VFX

    Hey Guys,

    how did you get the "combine related commands into submenus" working, showing different Nuke versions in the picture above? If I try customizing the collapse rules, it looks like menu_label don´t understands the token "$version". If I try instead off this, the token "$app", it´s working but kind of senseless this way. So why is $version not working?

    Another Question is, is it possible to create just one launch_nuke entry in app_launchers.yml for different nuke versions Nuke 8 & 9, using the configuration setting "versions:". Their executable files has different names and the path includes build version in the version description.

    nuke8.0_windows: 'C:\Program Files\Nuke8.0v6\Nuke8.0.exe'

    nuke9.0_windows: 'C:\Program Files\Nuke9.0v8\Nuke9.0.exe'

    At the moment I import two entries launchnuke8.0 and launch_nuke9.0 with two different "windows_path"s defined.

    Cheers, Matthias

  • 0
    Avatar
    Rob Blau

    Hi Matthias, for version to work you'd need to have that token in the match portion of the collapse rules like this:

    collapse_rules: [{'menu_label': '$version', 'match': 'Launch $app $version', 'button_label': '$app'}]

    And you can use the syntax described here to collapse down the config for Nuke 8/9:

    https://github.com/shotgunsoftware/tk-multi-launchapp/blob/d2c7d63f3500022ade7f9f7c0bdaee237ecd89be/app.py#L205

    So if you have versions set to ["(9.0)v4(beta1)", "(9.0)v3"] then you could use "{v0}" in your paths.

  • 0
    Avatar
    Matthias Wäsch - Celluloid VFX

    Hi Rob,

    thanks for replying!

    At First, the syntax you described for the collapse_rules confused me a bit, because you are using square & curly brackets and all that single quotation marks. I tried this and got errors while launching Shotgun Desktop. But If I keep the syntax for collapse_rules, the project.yml file provides:

    collapse_rules:

    - {button_label: $app, match: Launch $app $version, menu_label: $version}

    Then it´s working fine.

    Great Hint, how to deal with the syntax for the versions! Now I just have one Nuke path defined for several versions and for two entries (one for Nuke and one for NukeX) in the app_launcher.yml.

    Do I need to have two entries there, for the ability to have Nuke and NukeX running? Or maybe is there a way, with only one launch_nuke entry for both abilities?

    I´m wondering why the hint with the syntax for the versions isn't in the official documentation for the Desktop-Engine or Application-Launcher. Especially the screenshot here is showing that is possible, but it's not described how! So Rob, thanks a lot!

    Cheers Matthias

     

  • 0
    Avatar
    Rob Blau

    Hi Matthias,

    I was surprised to see our lack of docs on this feature too!  I just updated the documentation for how to use the versions setting to include these details.  It'll show up with the next release of the multi launchapp.

    Sorry about that!

  • 0
    Avatar
    Anthony Scudese

    Is it possible to have folder creation and other things in the sg desktop app?

Please sign in to leave a comment.