Class 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 Detail

      • DebugUITools

        public DebugUITools()
    • Method Detail

      • 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:
        IDebugUIConstants
      • 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:
        IDebugUIConstants
      • 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:
        IBaseLabelProvider.dispose()
      • 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:
        IBaseLabelProvider.dispose()
      • 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
      • 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
      • 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:
        ILaunchGroup
      • 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:
        ILaunchGroup
      • 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:
        IStatusHandler, ILaunchGroup
      • 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:
        ILaunchGroup
      • 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:
        ILaunchGroup
      • 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:
        ILaunchGroup
      • saveAndBuildBeforeLaunch

        @Deprecated
        public static boolean saveAndBuildBeforeLaunch()
        Deprecated.
        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
        public static boolean saveBeforeLaunch()
        Deprecated.
        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:
        IStepFilters
      • 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:
        IStepFilters
      • 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:
        getLaunchGroups()
      • 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:
        ISourceContainerType
      • 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:
        ISourceContainerBrowser
      • 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:
        IDebugUIConstants
      • 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