Package qupath.lib.gui

Class QuPathGUI

java.lang.Object
qupath.lib.gui.QuPathGUI
public class QuPathGUI extends Object
Main GUI for QuPath, written using JavaFX.

  • Property Details

  • Field Details

    • TOOLBAR_ICON_SIZE

      public static final int TOOLBAR_ICON_SIZE
      Icon size to use in the main QuPath toolbar
      See Also:

  • Method Details

    • createInstance

      public static QuPathGUI createInstance(Stage stage) throws IllegalStateException
      Static method to launch QuPath on the JavaFX Application thread.

      This may be be called in an Application.start(Stage) method. If so, then it is preferable to use createInstance(Stage, HostServices) to provide host services, which can be used for some tasks (e.g. opening a browser window, or determining the code location for the application). However this method can be used if QuPath is being launched some other way.

      Afterwards, calls to getInstance() will return the QuPath instance.

      Parameters:
      stage - the stage to use for the QuPath UI
      Returns:
      Throws:
      IllegalStateException - if an instance of QuPath is already running (i.e. getInstance() is not null)
      See Also:

    • createInstance

      public static QuPathGUI createInstance(Stage stage, HostServices hostServices) throws IllegalStateException
      Static method to launch QuPath from a JavaFX application.

      This is typically expected to be called in an Application.start(Stage) method, although could potentially be called later from another JavaFX application.

      Afterwards, calls to getInstance() will return the QuPath instance.

      Parameters:
      stage - the stage to use for the QuPath UI (usually from Application.start(Stage))
      hostServices - host services from the JavaFX Application, if available
      Returns:
      Throws:
      IllegalStateException - if an instance of QuPath is already running (i.e. getInstance() is not null)
      See Also:

    • createHiddenInstance

      public static QuPathGUI createHiddenInstance() throws IllegalStateException
      Create a new QuPath instance that is not visible (i.e. its stage is not shown).
      Returns:
      Throws:
      IllegalStateException

    • launchInstanceFromSwing

      public static void launchInstanceFromSwing()
      Static method to launch QuPath from within a Swing/AWT application.

      This aims to handle several things:

      • initializing JavaFX in the appropriate thread
      • flagging that shutting down QuPath should not terminate the JVM
      • showing the QuPath UI window

      This can potentially be used from other environments (e.g. MATLAB, Fiji, Python). Afterwards, calls to getInstance() will return the QuPath instance as soon as it is available. However, note that depending upon the thread from which this method is called, the QuPath instance may not be available until some time after the method returns.

      If there is already an instance of QuPath running, this requests that it is made visible - but otherwise does nothing.

    • requestAutomaticUpdateCheck

      public void requestAutomaticUpdateCheck()
      Request an automated update check in a background thread. This will use the user preferences to determine whether or how to check for updates (i.e. if the preferences have disabled an update check, then it will not be run).
      See Also:

    • requestFullUpdateCheck

      public void requestFullUpdateCheck()
      Request a manual update check in a background thread. This should perform the check if possible, regardless of the user preferences.
      See Also:

    • showAnalysisPaneProperty

      public BooleanProperty showAnalysisPaneProperty()
      Returns:
      the showAnalysisPane property

    • uiBlocked

      public ObservableValue<Boolean> uiBlocked()
      Observable value indicating that the user interface is/should be blocked. This happens when a plugin or script is running.
      Returns:

    • openInBrowser

      public static boolean openInBrowser(String url)
      Try to launch a browser window for a specified URL.
      Parameters:
      url - the URL to open in the browser
      Returns:
      true if this was (as far as we know...) successful, and false otherwise
      Since:
      v0.5.0 (renamed from launchInBrowserWindow(String}

    • getToolManager

      public ToolManager getToolManager()
      Get the ToolManager that handles available and selected tools.
      Returns:

    • getThreadPoolManager

      public SharedThreadPoolManager getThreadPoolManager()
      Get a SharedThreadPoolManager to help with submitting tasks in other threads. A benefit of using this is that all the thread pools created will be shutdown when QuPath is exited.
      Returns:

    • getExtensionCatalogManager

      public static qupath.ext.extensionmanager.core.ExtensionCatalogManager getExtensionCatalogManager()
      Returns:
      the ExtensionCatalogManager that manage catalogs and extensions of this QuPath GUI

    • getViewerManager

      public ViewerManager getViewerManager()
      Get the viewer manager, which gives access to all the viewers available within this QuPath instance.
      Returns:

    • getAvailablePathClasses

      public ObservableList<PathClass> getAvailablePathClasses()
      Get an observable list of available PathClasses.
      Returns:

    • getDefaultDragDropListener

      public DragDropImportListener getDefaultDragDropListener()
      Get a reference to the default drag & drop listener, so this may be added to additional windows if needed.
      Returns:

    • resetAvailablePathClasses

      public boolean resetAvailablePathClasses()
      Populate the availablePathClasses with a default list.
      Returns:
      true if changes were mad to the available classes, false otherwise

    • getAnalysisTabPane

      public TabPane getAnalysisTabPane()
      Access the main tab pane shown in the QuPath window. This enables extensions to add or remove tabs - but be cautious!
      • Removing tabs can impact other functionality
      • If adding a tab, it is usually best to apply FXUtils.makeTabUndockable(Tab)
      Returns:

    • isStandalone

      public boolean isStandalone()
      Query whether this is a standalone QuPathGUI instance, as flagged during startup. It can be important to know this so as to avoid calling System.exit(0) or similar, and bringing down some other application entirely.
      Returns:
      true if this is a standalone QuPathGUI instance, false otherwise

    • getAllViewers

      public ObservableList<QuPathViewer> getAllViewers()
      Get an unmodifiable observable list of all viewers.
      Returns:
      See Also:

    • getViewer

      public QuPathViewer getViewer()
      Get the currently active viewer.
      Returns:

    • getInstance

      public static QuPathGUI getInstance()
      Get the static instance of the current QuPath GUI.
      Returns:

    • openSavedData

      public boolean openSavedData(QuPathViewer viewer, File file, boolean keepExistingServer, boolean promptToSaveChanges) throws IOException
      Open a saved data file within a particular viewer, optionally keeping the same ImageServer as is currently open. The purpose of this is to make it possible for a project (for example) to open the correct server prior to opening the data file, enabling it to make use of relative path names and not have to rely on the absolute path encoded within the ImageData.
      Parameters:
      viewer -
      file -
      keepExistingServer - if true and the viewer already has an ImageServer, then any ImageServer path recorded within the data file will be ignored
      promptToSaveChanges - if true, the user will be prompted to ask whether to save changes or not
      Returns:
      Throws:
      IOException

    • openImageEntry

      public boolean openImageEntry(ProjectImageEntry<BufferedImage> entry)
      Open the image represented by the specified ProjectImageEntry.

      If an image is currently open, this command will prompt to save any changes.

      Parameters:
      entry -
      Returns:

    • promptToOpenImageFile

      public boolean promptToOpenImageFile()
      Show a file chooser to open a new image in the current viewer.

      If this encounters an exception, an error message will be shown.

      Returns:
      true if the image was opened, false otherwise

    • promptToOpenImageFileOrUri

      public boolean promptToOpenImageFileOrUri()
      Show a dialog to open a new image in the current viewer, with support for entering a URL (rather than requiring a local file only).

      If this encounters an exception, an error message will be shown.

      Returns:
      true if the image was opened, false otherwise

    • openImage

      public boolean openImage(QuPathViewer viewer, String pathNew) throws IOException
      Throws:
      IOException

    • openImage

      public boolean openImage(QuPathViewer viewer, String pathNew, boolean prompt, boolean includeURLs) throws IOException
      Open a new whole slide image server, or ImageData. If the path is the same as a currently-open server, do nothing.
      Parameters:
      viewer - the viewer into which the image should be opened
      pathNew -
      prompt - if true, give the user the opportunity to cancel opening if a whole slide server is already set
      includeURLs - if true, any prompt should support URL input and not only a file chooser
      Returns:
      true if the server was set for this GUI, false otherwise
      Throws:
      IOException

    • installGroovyCommand

      public MenuItem installGroovyCommand(String menuPath, File file)
      Install a Groovy script as a new command in QuPath.
      Parameters:
      menuPath - menu where the command should be installed; see lookupMenuItem(String, String...) for the specification. If only a name is provided, the command will be added to the "Extensions" menu. If a menu item already exists for the given path, it will be removed.
      file - the Groovy script to run; note that this will be reloaded each time it is required
      Returns:
      the MenuItem for the command
      See Also:

    • installGroovyCommand

      public MenuItem installGroovyCommand(String menuPath, String script)
      Install a Groovy script as a new command in QuPath.
      Parameters:
      menuPath - menu where the command should be installed; see lookupMenuItem(String, String...) for the specification. If only a name is provided, the command will be added to the "Extensions" menu. If a menu item already exists for the given path, it will be removed.
      script - the Groovy script to run
      Returns:
      the MenuItem for the command
      See Also:

    • installImageDataCommand

      public MenuItem installImageDataCommand(String menuPath, Consumer<ImageData<BufferedImage>> command)
      Install a new command in QuPath that takes the current ImageData as input. The command will only be enabled when an image is available.
      Parameters:
      menuPath - menu where the command should be installed; see lookupMenuItem(String, String...) for the specification. If only a name is provided, the command will be added to the "Extensions" menu. If a menu item already exists for the given path, it will be removed.
      command - the command to run
      Returns:
      the MenuItem for the command
      See Also:

    • installCommand

      public MenuItem installCommand(String menuPath, Runnable runnable)
      Install a new command in QuPath.
      Parameters:
      menuPath - menu where the command should be installed; see lookupMenuItem(String, String...) for the specification. If only a name is provided, the command will be added to the "Extensions" menu. If a menu item already exists for the given path, it will be removed.
      runnable - the command to run
      Returns:
      the MenuItem for the command. This can be further customized if needed.

    • runScript

      public Object runScript(File file, String script) throws ScriptException, IllegalArgumentException
      Convenience method to execute a script. Either a script file or the text of the script must be provided, or both.

      If only the script text is given, the language is assumed to be Groovy.

      Parameters:
      file - the file containing the script to run
      script - the script to run
      Returns:
      result of the script execution
      Throws:
      ScriptException
      IllegalArgumentException - if both file and script are null

    • getPreferencePane

      public PreferencePane getPreferencePane()
      Get a reference to the PreferencePane. This can be used by extensions to add in their own preferences.
      Returns:

    • lookupAccelerator

      public Object lookupAccelerator(String combo)
      Get the action or menu item associated with an accelerator. This is particularly useful to check whether a key combination is in use before using it for a new command.
      Parameters:
      combo -
      Returns:
      an Action or MenuItem associated with the accelerator, or null
      Since:
      v0.4.0

    • lookupAccelerator

      public Object lookupAccelerator(KeyCombination combo)
      Get the action or menu item associated with an key combination. This is particularly useful to check whether a key combination is in use before using it for a new command.
      Parameters:
      combo -
      Returns:
      an Action or MenuItem associated with the accelerator, or null
      Since:
      v0.4.0

    • setAccelerator

      public boolean setAccelerator(String menuCommand, String combo)
      Set an accelerator for the specified menu command. The command is defined as described in lookupMenuItem(String, String...), and the accelerator is the the format used by KeyCombination.valueOf(String). An example: 
        
 setAccelerator("File>Open...", "shift+o");
      Where possible, the accelerator for an action associated with a menu item will be changed. If the combo is null, any existing accelerator will be removed. Additionally, if the accelerator is already assigned to another item then it will be removed from that item.
      Parameters:
      menuCommand -
      combo -
      Returns:
      true if a change was made, false otherwise
      See Also:

    • setAccelerator

      public boolean setAccelerator(MenuItem item, KeyCombination combo)
      Set the accelerator for the specified menu item. Where possible, the accelerator will be set via any action that controls the menu item - so that it is applied consistently for other related buttons or menu items.

      If the combo is null, any existing accelerator will be removed. Additionally, if the accelerator is already assigned to another item then it will be removed from that item.

      Parameters:
      item -
      combo -
      Returns:
      true if changes were made, false otherwise
      See Also:

    • setAccelerator

      public boolean setAccelerator(org.controlsfx.control.action.Action action, KeyCombination combo)
      Set the accelerator for the specified action. If the combo is null, any existing accelerator will be removed. Additionally, if the accelerator is already assigned to another action then it will be removed from that item.
      Parameters:
      action -
      combo -
      Returns:
      true if changes were made, false otherwise
      See Also:

    • createPluginAction

      public org.controlsfx.control.action.Action createPluginAction(String name, Class<? extends PathPlugin> pluginClass, String arg)
      Create an action for a plugin to be run through this QuPath instance.
      Parameters:
      name - name of the plugin
      pluginClass - class of the plugin
      arg - optional argument (may be required by some plugins)
      Returns:

    • createPluginAction

      public org.controlsfx.control.action.Action createPluginAction(String name, PathPlugin<BufferedImage> plugin, String arg)
      Create an Action to call the specified plugin for the current image.
      Parameters:
      name - plugin name
      plugin - the plugin to call
      arg - any argument required by the plugin
      Returns:
      an action that may be called to run the plugin

    • sendQuitRequest

      public void sendQuitRequest()
      Request to quit QuPath.

    • runPlugin

      public boolean runPlugin(PathPlugin<BufferedImage> plugin, String arg, boolean doInteractive) throws Exception
      Run a plugin, interactively (i.e. launching a dialog) if necessary.

      Note that this does not in itself perform any exception handling.

      Parameters:
      plugin - the plugin to run
      arg - optional string argument (usually JSON)
      doInteractive - if true, show an interactive dialog if the plugin is an instance of PathInteractivePlugin
      Returns:
      true if running the plugin was successful and was not cancelled. Note that if doInteractive == true and the dialog was launched but not run, this will also return true.
      Throws:
      Exception

    • createPlugin

      public PathPlugin<BufferedImage> createPlugin(Class<? extends PathPlugin> pluginClass)
      Create a plugin from a specified class.
      Parameters:
      pluginClass -
      Returns:

    • getToolBar

      public ToolBar getToolBar()
      Get the main toolbar.
      Returns:

    • getUndoRedoManager

      public UndoRedoManager getUndoRedoManager()
      Get the UndoRedoManager, which can be useful if needing to clear it in cases where available memory is low.
      Returns:

    • isReadOnly

      public boolean isReadOnly()
      Query whether QuPath is in 'read-only' mode. This suppresses dialogs that ask about saving changes.
      Returns:
      See Also:
      API Note
      Read only mode is an experimental feature; its behavior is subject to change in future versions.

    • readOnlyProperty

      public ReadOnlyBooleanProperty readOnlyProperty()
      Property indicating whether QuPath is in 'read-only' mode.
      Returns:
      See Also:

    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Specify whether QuPath should be in 'read-only' mode.
      Parameters:
      readOnly -
      See Also:
      API Note
      Read only mode is an experimental feature; its behavior is subject to change in future versions.

    • getScriptEditor

      public ScriptEditor getScriptEditor()
      Get a reference to the current ScriptEditor (which may or may not be open at the moment).
      Returns:

    • setScriptEditor

      public void setScriptEditor(ScriptEditor scriptEditor)
      Set a new ScriptEditor, which will be used from now on.
      Parameters:
      scriptEditor -

    • getOverlayOptions

      public OverlayOptions getOverlayOptions()
      Return the global OverlayOptions instance, used to control display within viewers by default.
      Returns:

    • getImageRegionStore

      public DefaultImageRegionStore getImageRegionStore()
      Return the global DefaultImageRegionStore instance, used to cache and paint image tiles.
      Returns:

    • getMenuBar

      public MenuBar getMenuBar()
      Get the menubar for the main QuPath application.
      Returns:

    • getMenu

      public Menu getMenu(String name, boolean createMenu)
      Get a reference to an existing menu from the main QuPath menubar, optionally creating a new menu if it is not present.
      Parameters:
      name -
      createMenu -
      Returns:

    • getStage

      public Stage getStage()
      Get the main QuPath stage.
      Returns:

    • refreshTitle

      public void refreshTitle()
      Refresh the title bar in the main QuPath window.

    • getDisplayedImageName

      public String getDisplayedImageName(ImageData<BufferedImage> imageData)
      Get the image name to display for a specified image. This can be used to determine a name to display in the title bar, for example.
      Parameters:
      imageData -
      Returns:

    • getBuildString

      public static String getBuildString()
      Get a String representing the QuPath version & build time.
      Returns:

    • getVersion

      public static Version getVersion()
      Get the current QuPath version.
      Returns:

    • imageDataProperty

      public ReadOnlyObjectProperty<ImageData<BufferedImage>> imageDataProperty()
      Read-only property containing the image open within the currently-active viewer. To change the open image data, you should do so directly within the viewer.
      Returns:
      See Also:

    • setProject

      public void setProject(Project<BufferedImage> project)
      Set the active project, triggering any necessary GUI updates.
      Parameters:
      project -

    • refreshProject

      public void refreshProject()
      Refresh the project, updating the display if required. This can be called whenever the project has changed (e.g. by adding or removing items).

    • projectProperty

      public ReadOnlyObjectProperty<Project<BufferedImage>> projectProperty()
      Read-only property representing the currently-open project.
      Returns:
      See Also:

    • getProject

      public Project<BufferedImage> getProject()
      Get the value of projectProperty().
      Returns:

    • getImageData

      public ImageData<BufferedImage> getImageData()
      Get the value of imageDataProperty().
      Returns:

    • viewerProperty

      public ReadOnlyObjectProperty<QuPathViewer> viewerProperty()
      Property representing the viewer currently active.
      Returns:
      See Also:

    • closeViewer

      public boolean closeViewer(QuPathViewer viewer)
      Close the image within a viewer, prompting to save changes if necessary.
      Parameters:
      viewer -
      Returns:
      True if the viewer no longer contains an open image (either because it never did contain one, or the image was successfully closed), false otherwise (e.g. if the user thwarted the close request)

    • getLogViewerCommand

      public LogViewerCommand getLogViewerCommand()
      Get the log viewer associated with this QuPath instance.
      Returns:
      Since:
      v0.5.0

    • createImageDataAction

      public org.controlsfx.control.action.Action createImageDataAction(Consumer<ImageData<BufferedImage>> command)
      Create an Action that depends upon an ImageData. When the action is invoked, it will be passed the current ImageData as a parameter. The action will also be disabled if no image data is present.
      Parameters:
      command - the command to run
      Returns:
      an Action with appropriate properties set

    • showInputDisplayProperty

      public BooleanProperty showInputDisplayProperty()
      Property to indicate whether the input display is currently showing
      Returns:
      input display property

    • createViewerAction

      public org.controlsfx.control.action.Action createViewerAction(Consumer<QuPathViewer> command)
      Create an Action that depends upon an QuPathViewer. When the action is invoked, it will be passed the current QuPathViewer as a parameter. The action will also be disabled if no viewer is present.
      Parameters:
      command - the command to run
      Returns:
      an Action with appropriate properties set

    • createImageDataAction

      public org.controlsfx.control.action.Action createImageDataAction(Consumer<ImageData<BufferedImage>> command, String name)
      Create an Action that depends upon an ImageData. When the action is invoked, it will be passed the current QuPathViewer as a parameter. The action will also be disabled if no viewer is present.
      Parameters:
      command - the command to run
      name - text of the action
      Returns:
      an Action with appropriate properties set

    • createProjectAction

      public org.controlsfx.control.action.Action createProjectAction(Consumer<Project<BufferedImage>> command)
      Create an Action that depends upon a Project. When the action is invoked, it will be passed the current Project as a parameter. The action will also be disabled if no image data is present.
      Parameters:
      command - the command to run
      Returns:
      an Action with appropriate properties set

    • installActions

      public void installActions(Collection<? extends org.controlsfx.control.action.Action> actions)
      Install the specified actions. It is assumed that these have been configured via ActionTools, and therefore have sufficient information associated with them (including a menu path).
      Parameters:
      actions -

    • getCommonActions

      public CommonActions getCommonActions()
      Get the common actions associated with this QuPath instance.
      Returns:

    • getAutomateActions

      public AutomateActions getAutomateActions()
      Get the automated actions associated with this QuPath instance.
      Returns:

    • lookupActionByText

      public org.controlsfx.control.action.Action lookupActionByText(String text)
      Search for an action based upon its text (name) property.
      Parameters:
      text - the text to search for
      Returns:
      the action, if found, or null otherwise

    • lookupMenuItem

      public MenuItem lookupMenuItem(String menuPath, String... parts)
      Search for a menu item based upon its path.
      This supports two possible syntaxes: one using > as a delimiter, and the other providing multiple parts as separate strings. This means the following are equivalent: 
      	lookupMenuItem("Main menu>Submenu>Name");
 lookupMenuItem("Main menu", "Submenu", "Name");
      Parameters:
      menuPath - path to the menu item, or first component of the path
      parts - optional additional parts of the path to the menu item
      Returns:
      the menu item corresponding to this path, or null if no menu item is found
      Since:
      v0.6.0 (previously, only a single delimited string input was supported)
      Implementation Note
      The delimiter ">" is used internally. This means that the method currently cannot support menus or menu items that contain > in their text.

    • getOverlayActions

      public OverlayActions getOverlayActions()
      Get the actions associated with the viewer overlay options. This includes showing/hiding/filling objects, or adjusting opacity.
      Returns:

    • getViewerActions

      public ViewerActions getViewerActions()
      Get the associations associated with QuPath image viewers.
      Returns:

    • createSingleThreadExecutor

      @Deprecated public ExecutorService createSingleThreadExecutor(Object owner)
      Deprecated.
      since v0.5.0; use getThreadPoolManager()
      Create an executor using a single thread.

      Optionally specify an owner, in which case the same Executor will be returned for the owner for so long as the Executor has not been shut down; if it has been shut down, a new Executor will be returned.

      Specifying an owner is a good idea if there is a chance that any submitted tasks could block, since the same Executor will be returned for all requests that give a null owner.

      The advantage of using this over creating an ExecutorService some other way is that shutdown will be called on any pools created this way whenever QuPath is quit.

      Parameters:
      owner -
      Returns:

    • createSharedPoolCompletionService

      @Deprecated public <V> ExecutorCompletionService<V> createSharedPoolCompletionService(Class<V> cls)
      Deprecated.
      since v0.5.0; use getThreadPoolManager()
      Create a completion service that uses a shared threadpool for the application.
      Type Parameters:
      V -
      Parameters:
      cls -
      Returns:

    • submitShortTask

      @Deprecated public void submitShortTask(Runnable runnable)
      Deprecated.
      since v0.5.0; use getThreadPoolManager()
      Submit a short task to a shared thread pool
      Parameters:
      runnable -