Package org.eclipse.debug.ui

Class DebugUITools

java.lang.Object
org.eclipse.debug.ui.DebugUITools
public class DebugUITools extends Object
This class provides utilities for clients of the debug UI.

Images retrieved from this facility should not be disposed. The images will be disposed when this plug-in is shutdown.

Note: all methods in this class are expected to be called on the Display thread unless otherwise noted.

Restriction:
This class is not intended to be subclassed by clients.
Restriction:
This class is not intended to be instantiated by clients.

  • Constructor Details

    • DebugUITools

      public DebugUITools()

  • Method Details

    • getImage

      public static Image getImage(String key)
      Returns the shared image managed under the given key, or null if none.

      Note that clients MUST NOT dispose the image returned by this method.

      See IDebugUIConstants for available images.

      Parameters:
      key - the image key
      Returns:
      the image, or null if none
      See Also:

    • getImageDescriptor

      public static ImageDescriptor getImageDescriptor(String key)
      Returns the shared image descriptor managed under the given key, or null if none.

      See IDebugUIConstants for available image descriptors.

      Parameters:
      key - the image descriptor key
      Returns:
      the image descriptor, or null if none
      See Also:

    • getDefaultImageDescriptor

      public static ImageDescriptor getDefaultImageDescriptor(Object element)
      Returns the default image descriptor for the given element.
      Parameters:
      element - the element
      Returns:
      the image descriptor or null if none

    • getPreferenceStore

      public static IPreferenceStore getPreferenceStore()
      Returns the preference store for the debug UI plug-in.
      Returns:
      preference store

    • newDebugModelPresentation

      public static IDebugModelPresentation newDebugModelPresentation()
      Returns a new debug model presentation that delegates to appropriate debug models.

      It is the client's responsibility dispose the presentation.

      Returns:
      a debug model presentation
      Since:
      2.0
      See Also:

    • newDebugModelPresentation

      public static IDebugModelPresentation newDebugModelPresentation(String identifier)
      Returns a new debug model presentation for specified debug model, or null if a presentation does not exist.

      It is the client's responsibility dispose the presentation.

      Parameters:
      identifier - debug model identifier
      Returns:
      a debug model presentation, or null
      Since:
      2.0
      See Also:

    • getDebugContext

      public static IAdaptable getDebugContext()
      Returns the element of the currently selected context in the active workbench window. Returns null if there is no current debug context.

      This method used to return null when called from a non-UI thread, but since 3.1, this methods also works when called from a non-UI thread.

      Returns:
      the currently selected debug context, or null
      Since:
      2.0

    • getDebugContextForPart

      public static ISelection getDebugContextForPart(IWorkbenchPart part)
      Returns the currently selected context in the given part or part's workbench window. Returns null if there is no current debug context.
      Parameters:
      part - workbench part where the active context is to be evaluated
      Returns:
      the currently selected debug context in the given workbench part, or null
      Since:
      3.8
      See Also:

    • getBreakpointsUndoContext

      public static IUndoContext getBreakpointsUndoContext()
      Return the undo context that should be used for operations involving breakpoints.
      Returns:
      the undo context for breakpoints
      Since:
      3.7

    • deleteBreakpoints

      public static void deleteBreakpoints(IBreakpoint[] breakpoints, Shell shell, IProgressMonitor progressMonitor) throws CoreException
      Deletes the given breakpoints using the operation history, which allows to undo the deletion.
      Parameters:
      breakpoints - the breakpoints to delete
      shell - the shell used for potential user interactions, or null if unknown
      progressMonitor - the progress monitor
      Throws:
      CoreException - if the deletion fails
      Since:
      3.7

    • getPartDebugContext

      public static IAdaptable getPartDebugContext(IWorkbenchPartSite site)
      Returns the currently active context for the given workbench part. Returns null if there is no current debug context.
      Parameters:
      site - the part's site where to look up the active context
      Returns:
      the currently active debug context in the given part, or null
      Since:
      3.7

    • addPartDebugContextListener

      public static void addPartDebugContextListener(IWorkbenchPartSite site, IDebugContextListener listener)
      Adds the given debug context listener as a listener to the debug context changed events, in the context of the given workbench part.

      This method is a utility method which ultimately calls IDebugContextService.addDebugContextListener(IDebugContextListener, String, String) using the part id parameters extracted from the given part parameter.

      Parameters:
      site - the part's site to get the part ID and part secondary ID from
      listener - Debug context listener to add
      Since:
      3.7
      See Also:

    • removePartDebugContextListener

      public static void removePartDebugContextListener(IWorkbenchPartSite site, IDebugContextListener listener)
      Removes the given debug context listener as a listener to the debug context changed events, in the context of the given workbench part.

      This method is a utility method which ultimately calls IDebugContextService.removeDebugContextListener(IDebugContextListener, String, String) using the part id parameters extracted from the given part parameter.

      Parameters:
      site - the part's site to get the part ID and part secondary ID from
      listener - Debug context listener to remove
      Since:
      3.7
      See Also:

    • getSelectedResource

      public static IResource getSelectedResource()
      Returns the currently selected resource in the active workbench window, or null if none. If an editor is active, the resource adapter associated with the editor is returned, if any.
      Returns:
      selected resource or null
      Since:
      3.0

    • getCurrentProcess

      public static IProcess getCurrentProcess()
      Returns the process associated with the current debug context. If there is no debug context currently, the most recently launched process is returned. If there is no current process null is returned.
      Returns:
      the current process, or null
      Since:
      2.0

    • openLaunchConfigurationDialog

      @Deprecated public static int openLaunchConfigurationDialog(Shell shell, IStructuredSelection selection, String mode)
      Deprecated.
      use openLaunchConfigurationDialogOnGroup(Shell, IStructuredSelection, String) to specify the launch group that the dialog should be opened on. This method will open on the launch group with the specified mode and a null category
      Open the launch configuration dialog with the specified initial selection. The selection may be null, or contain any mix of ILaunchConfiguration or ILaunchConfigurationType elements.

      Before opening a new dialog, this method checks if there is an existing open launch configuration dialog. If there is, this dialog is used with the specified selection. If there is no existing dialog, a new one is created.

      Note that if an existing dialog is reused, the mode argument is ignored and the existing dialog keeps its original mode.

      Parameters:
      shell - the parent shell for the launch configuration dialog
      selection - the initial selection for the dialog
      mode - the mode (run or debug) in which to open the launch configuration dialog. This should be one of the constants defined in ILaunchManager.
      Returns:
      the return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      2.0
      See Also:

    • openLaunchConfigurationDialogOnGroup

      public static int openLaunchConfigurationDialogOnGroup(Shell shell, IStructuredSelection selection, String groupIdentifier)
      Open the launch configuration dialog with the specified initial selection. The selection may be null, or contain any mix of ILaunchConfiguration or ILaunchConfigurationType elements.

      Before opening a new dialog, this method checks if there is an existing open launch configuration dialog. If there is, this dialog is used with the specified selection. If there is no existing dialog, a new one is created.

      Note that if an existing dialog is reused, the mode argument is ignored and the existing dialog keeps its original mode.

      Parameters:
      shell - the parent shell for the launch configuration dialog
      selection - the initial selection for the dialog
      groupIdentifier - the identifier of the launch group to display (corresponds to the identifier of a launch group extension)
      Returns:
      The return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      2.1
      See Also:

    • openLaunchConfigurationDialogOnGroup

      public static int openLaunchConfigurationDialogOnGroup(Shell shell, IStructuredSelection selection, String groupIdentifier, IStatus status)
      Open the launch configuration dialog with the specified initial selection. The selection may be null, or contain any mix of ILaunchConfiguration or ILaunchConfigurationType elements.

      Before opening a new dialog, this method checks if there is an existing open launch configuration dialog. If there is, this dialog is used with the specified selection. If there is no existing dialog, a new one is created.

      Note that if an existing dialog is reused, the mode argument is ignored and the existing dialog keeps its original mode.

      If a status is specified, a status handler is consulted to handle the status. The status handler is passed the instance of the launch configuration dialog that is opened. This gives the status handler an opportunity to perform error handling/initialization as required.

      Parameters:
      shell - the parent shell for the launch configuration dialog
      selection - the initial selection for the dialog
      groupIdentifier - the identifier of the launch group to display (corresponds to the identifier of a launch group extension)
      status - the status to display in the dialog, or null if none
      Returns:
      the return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      2.1
      See Also:

    • openLaunchConfigurationPropertiesDialog

      public static int openLaunchConfigurationPropertiesDialog(Shell shell, ILaunchConfiguration configuration, String groupIdentifier)
      Open the launch configuration properties dialog on the specified launch configuration.
      Parameters:
      shell - the parent shell for the launch configuration dialog
      configuration - the configuration to display
      groupIdentifier - group identifier of the launch group the launch configuration belongs to
      Returns:
      the return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      2.1
      See Also:

    • openLaunchConfigurationPropertiesDialog

      public static int openLaunchConfigurationPropertiesDialog(Shell shell, ILaunchConfiguration configuration, String groupIdentifier, IStatus status)
      Open the launch configuration properties dialog on the specified launch configuration.
      Parameters:
      shell - the parent shell for the launch configuration dialog
      configuration - the configuration to display
      groupIdentifier - group identifier of the launch group the launch configuration belongs to
      status - the status to display, or null if none
      Returns:
      the return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      3.0
      See Also:

    • openLaunchConfigurationDialog

      public static int openLaunchConfigurationDialog(Shell shell, ILaunchConfiguration configuration, String groupIdentifier, IStatus status)
      Open the launch configuration dialog on the specified launch configuration. The dialog displays the tabs for a single configuration only (a tree of launch configuration is not displayed), and provides a launch (run or debug) button.

      If a status is specified, a status handler is consulted to handle the status. The status handler is passed the instance of the launch configuration dialog that is opened. This gives the status handler an opportunity to perform error handling/initialization as required.

      Parameters:
      shell - the parent shell for the launch configuration dialog
      configuration - the configuration to display
      groupIdentifier - group identifier of the launch group the launch configuration belongs to
      status - the status to display, or null if none
      Returns:
      the return code from opening the launch configuration dialog - one of Window.OK or Window.CANCEL. Window.CANCEL is returned if an invalid launch group identifier is provided.
      Since:
      2.1
      See Also:

    • saveAndBuildBeforeLaunch

      @Deprecated(forRemoval=true, since="2023-12") public static boolean saveAndBuildBeforeLaunch()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Saving has been moved to the launch delegate LaunchConfigurationDelegate to allow for scoped saving of resources that are only involved in the current launch, no longer the entire workspace
      Saves all dirty editors and builds the workspace according to current preference settings, and returns whether a launch should proceed.

      The following preferences affect whether dirty editors are saved, and/or if the user is prompted to save dirty editors:

      • PREF_NEVER_SAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      • PREF_PROMPT_SAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      • PREF_AUTOSAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      The following preference affects whether a build is performed before launching (if required):
      • PREF_BUILD_BEFORE_LAUNCH
      Returns:
      whether a launch should proceed
      Since:
      2.0

    • saveBeforeLaunch

      @Deprecated(forRemoval=true, since="2025-09") public static boolean saveBeforeLaunch()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Saving has been moved to the launch delegate LaunchConfigurationDelegate to allow for scoped saving of resources that are only involved in the current launch, no longer the entire workspace
      Saves all dirty editors according to current preference settings, and returns whether a launch should proceed.

      The following preferences affect whether dirty editors are saved, and/or if the user is prompted to save dirty editors:

      • PREF_NEVER_SAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      • PREF_PROMPT_SAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      • PREF_AUTOSAVE_DIRTY_EDITORS_BEFORE_LAUNCH
      Returns:
      whether a launch should proceed
      Since:
      2.1

    • launch

      public static void launch(ILaunchConfiguration configuration, String mode)
      Saves and builds the workspace according to current preference settings, and launches the given launch configuration in the specified mode. It terminates the current launch for the same configuration if it was specified via Preferences or toggled by Shift.

      This method must be called in the UI thread.

      Parameters:
      configuration - the configuration to launch
      mode - launch mode - run or debug
      Since:
      2.1

    • storeLaunchToggleTerminate

      public static void storeLaunchToggleTerminate(Object data, Object isShift)
      Stores the toggle data for launch in a Map to be used while launching to decide if previous launch for same configuration can be terminated.
      Parameters:
      data - the editor or selected tree node
      isShift - is Shift pressed (use false if no support for Shift)
      Since:
      3.12

    • removeLaunchToggleTerminate

      public static void removeLaunchToggleTerminate(Object data)
      Stores the toggle data for launch in a Map to be used while launching to decide if previous launch for same configuration can be terminated.
      Parameters:
      data - the editor or selected tree node
      Since:
      3.12

    • reLaunch

      public static void reLaunch(ILaunchConfiguration configuration, String mode)
      Saves and builds the workspace according to current preference settings, and launches the given launch configuration in the specified mode.

      This method must be called in the UI thread.

      Parameters:
      configuration - the configuration to launch
      mode - launch mode - run or debug
      Since:
      3.12

    • launch

      public static void launch(ILaunchConfiguration configuration, String mode, boolean isShift)
      Saves and builds the workspace according to current preference settings, and launches the given launch configuration in the specified mode. It terminates the current launch for the same configuration if it was specified via Preferences or toggled by Shift

      This method must be called in the UI thread.

      Parameters:
      configuration - the configuration to launch
      mode - launch mode - run or debug
      isShift - is Shift pressed (use false if no support for Shift)
      Since:
      3.12

    • buildAndLaunch

      public static ILaunch buildAndLaunch(ILaunchConfiguration configuration, String mode, IProgressMonitor monitor) throws CoreException
      Builds the workspace according to current preference settings, and launches the given configuration in the specified mode, returning the resulting launch object.

      The following preference affects whether a build is performed before launching (if required):

      • PREF_BUILD_BEFORE_LAUNCH
      Parameters:
      configuration - the configuration to launch
      mode - the mode to launch in
      monitor - progress monitor
      Returns:
      the resulting launch object
      Throws:
      CoreException - if building or launching fails
      Since:
      2.1

    • getLaunchPerspective

      public static String getLaunchPerspective(ILaunchConfigurationType type, String mode)
      Returns the perspective to switch to when a configuration of the given type is launched in the given mode, or null if no switch should take place. In 3.3 this method is equivalent to calling getLaunchPerspective(ILaunchConfigurationType type, Set modes, ILaunchDelegate delegate), with the 'mode' parameter comprising a single element set and passing null as the launch delegate.
      Parameters:
      type - launch configuration type
      mode - launch mode identifier
      Returns:
      perspective identifier or null
      Since:
      3.0

    • getLaunchPerspective

      public static String getLaunchPerspective(ILaunchConfigurationType type, ILaunchDelegate delegate, Set<String> modes)
      Returns the perspective id to switch to when a configuration of the given type launched with the specified delegate is launched in the given mode set, or null if no switch should occurr.
      Parameters:
      type - the configuration type
      delegate - the launch delegate
      modes - the set of modes
      Returns:
      the perspective id or null if no switch should occur
      Since:
      3.3

    • setLaunchPerspective

      public static void setLaunchPerspective(ILaunchConfigurationType type, String mode, String perspective)
      Sets the perspective to switch to when a configuration of the given type is launched in the given mode. PERSPECTIVE_NONE indicates no perspective switch should take place. PERSPECTIVE_DEFAULT indicates a default perspective switch should take place, as defined by the associated launch tab group extension. In 3.3 this method is equivalent to calling setLaunchPerspective(ILaunchConfigurationType type, Set modes, ILaunchDelegate delegate, String perspectiveid), with the parameter 'mode' used in the set modes, and null passed as the delegate
      Parameters:
      type - launch configuration type
      mode - launch mode identifier
      perspective - identifier, PERSPECTIVE_NONE, or PERSPECTIVE_DEFAULT
      Since:
      3.0

    • setLaunchPerspective

      public static void setLaunchPerspective(ILaunchConfigurationType type, ILaunchDelegate delegate, Set<String> modes, String perspectiveid)
      Sets the perspective to switch to when a configuration of the specified type and launched using the specified launch delegate is launched in the specified modeset. PERSPECTIVE_NONE indicates no perspective switch should take place. Passing null for the launch delegate is quivalent to using the default perspective for the specified type.
      Parameters:
      type - the configuration type
      delegate - the launch delegate
      modes - the set of modes
      perspectiveid - identifier or PERSPECTIVE_NONE
      Since:
      3.3

    • isPrivate

      public static boolean isPrivate(ILaunchConfiguration configuration)
      Returns whether the given launch configuration is private. Generally, private launch configurations should not be displayed to the user. The private status of a launch configuration is determined by the IDebugUIConstants.ATTR_PRIVATE attribute.
      Parameters:
      configuration - launch configuration
      Returns:
      whether the given launch configuration is private
      Since:
      3.0

    • setUseStepFilters

      public static void setUseStepFilters(boolean useStepFilters)
      Sets whether step filters should be applied to step commands. This setting is a global option applied to all registered debug targets.

      Since 3.3, this is equivalent to calling DebugPlugin.setUseStepFilters(boolean).

      Parameters:
      useStepFilters - whether step filters should be applied to step commands
      Since:
      3.0
      See Also:

    • isUseStepFilters

      public static boolean isUseStepFilters()
      Returns whether step filters are applied to step commands.

      Since 3.3, this is equivalent to calling DebugPlugin.isUseStepFilters().

      Returns:
      whether step filters are applied to step commands
      Since:
      3.0
      See Also:

    • getConsole

      public static IConsole getConsole(IProcess process)
      Returns the console associated with the given process, or null if none.
      Parameters:
      process - a process
      Returns:
      console associated with the given process, or null if none
      Since:
      3.0

    • getConsole

      public static IConsole getConsole(IDebugElement element)
      Returns the console associated with the given debug element, or null if none.
      Parameters:
      element - a debug model element
      Returns:
      console associated with the given element, or null if none
      Since:
      3.0

    • getLaunchGroups

      public static ILaunchGroup[] getLaunchGroups()
      Returns all registered launch group extensions.
      Returns:
      all registered launch group extensions
      Since:
      3.0

    • getLastLaunch

      public static ILaunchConfiguration getLastLaunch(String groupId)
      Returns the last configuration that was launched for specified launch group or null, if there is not one. This method does not provide any form of filtering on the returned launch configurations.
      Parameters:
      groupId - the unique identifier of a launch group
      Returns:
      the last launched configuration for the specified group or null.
      Since:
      3.3
      See Also:

    • getLaunchGroup

      public static ILaunchGroup getLaunchGroup(ILaunchConfiguration configuration, String mode)
      Returns the launch group that the given launch configuration belongs to, for the specified mode, or null if none.
      Parameters:
      configuration - the launch configuration
      mode - the mode
      Returns:
      the launch group the given launch configuration belongs to, for the specified mode, or null if none
      Since:
      3.0

    • lookupSource

      public static ISourceLookupResult lookupSource(Object artifact, ISourceLocator locator)
      Performs source lookup on the given artifact and returns the result. Optionally, a source locator may be specified.
      Parameters:
      artifact - object for which source is to be resolved
      locator - the source locator to use, or null. When null a source locator is determined from the artifact, if possible. If the artifact is a debug element, the source locator from its associated launch is used.
      Returns:
      a source lookup result
      Since:
      3.1

    • displaySource

      public static void displaySource(ISourceLookupResult result, IWorkbenchPage page)
      Displays the given source lookup result in an editor in the given workbench page. Has no effect if the result has an unknown editor id or editor input. The editor is opened, positioned, and annotated.

      Honors user preference for editors re-use.

      Parameters:
      result - source lookup result to display
      page - the page to display the result in
      Since:
      3.1

    • getMemoryRenderingManager

      public static IMemoryRenderingManager getMemoryRenderingManager()
      Returns the memory rendering manager.
      Returns:
      the memory rendering manager
      Since:
      3.1

    • getSourceContainerImage

      public static Image getSourceContainerImage(String id)
      Returns the image associated with the specified type of source container or null if none.
      Parameters:
      id - unique identifier for a source container type
      Returns:
      image associated with the specified type of source container or null if none
      Since:
      3.2
      See Also:

    • getSourceContainerBrowser

      public static ISourceContainerBrowser getSourceContainerBrowser(String id)
      Returns a new source container browser for the specified type of source container or null if a browser has not been registered.
      Parameters:
      id - unique identifier for a source container type
      Returns:
      source container browser or null if none
      Since:
      3.2
      See Also:

    • getPreferenceColor

      public static Color getPreferenceColor(String id)
      Returns the color associated with the specified preference identifier or null if none.
      Parameters:
      id - preference identifier of the color
      Returns:
      the color associated with the specified preference identifier or null if none
      Since:
      3.2
      See Also:

    • getDebugContextManager

      public static IDebugContextManager getDebugContextManager()
      Returns the debug context manager.
      Returns:
      debug context manager
      Since:
      3.3

    • getDebugContextForEvent

      public static ISelection getDebugContextForEvent(ExecutionEvent event)
      Return the debug context for the given executionEvent or null if none.
      Parameters:
      event - The execution event that contains the application context
      Returns:
      the current debug context, or null.
      Since:
      3.5

    • getDebugContextForEventChecked

      public static ISelection getDebugContextForEventChecked(ExecutionEvent event) throws ExecutionException
      Return the debug context for the given executionEvent.
      Parameters:
      event - The execution event that contains the application context
      Returns:
      the debug context. Will not return null.
      Throws:
      ExecutionException - If the current selection variable is not found.
      Since:
      3.5

    • getToggleBreakpointsTargetManager

      public static IToggleBreakpointsTargetManager getToggleBreakpointsTargetManager()
      Returns the global instance of toggle breakpoints target manager.
      Returns:
      toggle breakpoints target manager
      Since:
      3.8

    • getLaunchConfiguration

      public static ILaunchConfiguration getLaunchConfiguration(ILaunchConfigurationDialog dialog)
      Returns the ILaunchConfiguration corresponding to ILaunchConfigurationDialog
      Parameters:
      dialog - The input launch configuration dialog
      Returns:
      ILaunchConfiguration Corresponding launch configuration
      Since:
      3.13