Package org.eclipse.search.ui.text

Class AbstractTextSearchViewPage

  • All Implemented Interfaces:
    ISearchResultPage, IPage, IPageBookViewPage
    public abstract class AbstractTextSearchViewPage
extends Page
implements ISearchResultPage
    An abstract base implementation for classes showing AbstractTextSearchResult instances. This class assumes that the input element set via setInput(ISearchResult,Object) is a subclass of AbstractTextSearchResult. This result page supports a tree and/or a table presentation of search results. Subclasses can determine which presentations they want to support at construction time by passing the appropriate flags. Subclasses must customize the viewers for each presentation with a label provider and a content provider.
    Changes in the search result are handled by updating the viewer in the elementsChanged() and clear() methods.
    Since:
    3.0

    • Field Detail

      • EMPTY_MATCH_ARRAY

        protected static final Match[] EMPTY_MATCH_ARRAY
        An empty array.

      • FLAG_LAYOUT_FLAT

        public static final int FLAG_LAYOUT_FLAT
        Flag (value 1) denoting flat list layout.
        See Also:
        Constant Field Values

      • FLAG_LAYOUT_TREE

        public static final int FLAG_LAYOUT_TREE
        Flag (value 2) denoting tree layout.
        See Also:
        Constant Field Values

    • Constructor Detail

      • AbstractTextSearchViewPage

        protected AbstractTextSearchViewPage​(int supportedLayouts)
        This constructor must be passed a combination of layout flags combined with bitwise or. At least one flag must be passed in (i.e. 0 is not a permitted value).
        Parameters:
        supportedLayouts - flags determining which layout options this page supports. Must not be 0
        See Also:
        FLAG_LAYOUT_FLAT, FLAG_LAYOUT_TREE

      • AbstractTextSearchViewPage

        protected AbstractTextSearchViewPage()
        Constructs this page with the default layout flags.
        See Also:
        AbstractTextSearchViewPage(int)

    • Method Detail

      • getSettings

        protected IDialogSettings getSettings()
        Returns a dialog settings object for this search result page. There will be one dialog settings object per search result page id.
        Returns:
        the dialog settings for this search result page
        See Also:
        getID()

      • setID

        public void setID​(String id)
        Description copied from interface: ISearchResultPage
        Sets the id for this page. This method will be called before any other initialization is done.
        Specified by:
        setID in interface ISearchResultPage
        Parameters:
        id - the id for this page

      • getLabel

        public String getLabel()
        Description copied from interface: ISearchResultPage
        Returns a user readable label for this search result page. The label will be used to describe the contents for the page to the user (for example it will be displayed in the search view title bar). To take an example from file search, a label might read like this: 'test' - 896 matches in workspace.
        Specified by:
        getLabel in interface ISearchResultPage
        Returns:
        the user readable label for this search result page

      • showMatch

        @Deprecated
protected void showMatch​(Match match,
                         int currentOffset,
                         int currentLength)
                  throws PartInitException
        Deprecated.
        Use showMatch(Match, int, int, boolean) instead
        Opens an editor on the given element and selects the given range of text. If a search results implements a IFileMatchAdapter, match locations will be tracked and the current match range will be passed into this method.
        Parameters:
        match - the match to show
        currentOffset - the current start offset of the match
        currentLength - the current length of the selection
        Throws:
        PartInitException - if an editor can't be opened
        See Also:
        ITextFileBufferManager, IFileMatchAdapter

      • showMatch

        protected void showMatch​(Match match,
                         int currentOffset,
                         int currentLength,
                         boolean activate)
                  throws PartInitException
        Opens an editor on the given element and selects the given range of text. If a search results implements a IFileMatchAdapter, match locations will be tracked and the current match range will be passed into this method. If the activate parameter is true the opened editor should have be activated. Otherwise the focus should not be changed.
        Parameters:
        match - the match to show
        currentOffset - the current start offset of the match
        currentLength - the current length of the selection
        activate - whether to activate the editor.
        Throws:
        PartInitException - if an editor can't be opened
        See Also:
        ITextFileBufferManager, IFileMatchAdapter

      • openAndSelect

        protected final IEditorPart openAndSelect​(IWorkbenchPage page,
                                          IFile file,
                                          int offset,
                                          int length,
                                          boolean activate)
                                   throws PartInitException
        Opens an editor on the given file resource and tries to select the given offset and length.

        If the page already has an editor open on the target object then that editor is brought to front; otherwise, a new editor is opened. If activate == true the editor will be activated.

        Parameters:
        page - the workbench page in which the editor will be opened
        file - the file to open
        offset - the offset to select in the editor
        length - the length to select in the editor
        activate - if true the editor will be activated
        Returns:
        an open editor or null if an external editor was opened
        Throws:
        PartInitException - if the editor could not be initialized
        Since:
        3.6
        See Also:
        IWorkbenchPage.openEditor(IEditorInput, String, boolean)

      • open

        protected final IEditorPart open​(IWorkbenchPage page,
                                 IFile file,
                                 boolean activate)
                          throws PartInitException
        Opens an editor on the given file resource.

        If the page already has an editor open on the target object then that editor is brought to front; otherwise, a new editor is opened. If activate == true the editor will be activated.

        Parameters:
        page - the workbench page in which the editor will be opened
        file - the file to open
        activate - if true the editor will be activated
        Returns:
        an open editor or null if an external editor was opened
        Throws:
        PartInitException - if the editor could not be initialized
        Since:
        3.6
        See Also:
        IWorkbenchPage.openEditor(IEditorInput, String, boolean)

      • elementsChanged

        protected abstract void elementsChanged​(Object[] objects)
        This method is called whenever the set of matches for the given elements changes. This method is guaranteed to be called in the UI thread. Note that this notification is asynchronous. i.e. further changes may have occurred by the time this method is called. They will be described in a future call.

        The changed elements are evaluated by evaluateChangedElements(Match[], Set).

        Parameters:
        objects - array of objects that has to be refreshed

      • clear

        protected abstract void clear()
        This method is called whenever all elements have been removed from the shown AbstractSearchResult. This method is guaranteed to be called in the UI thread. Note that this notification is asynchronous. i.e. further changes may have occurred by the time this method is called. They will be described in a future call.

      • configureTreeViewer

        protected abstract void configureTreeViewer​(TreeViewer viewer)
        Configures the given viewer. Implementers have to set at least a content provider and a label provider. This method may be called if the page was constructed with the flag FLAG_LAYOUT_TREE.
        Parameters:
        viewer - the viewer to be configured

      • configureTableViewer

        protected abstract void configureTableViewer​(TableViewer viewer)
        Configures the given viewer. Implementers have to set at least a content provider and a label provider. This method may be called if the page was constructed with the flag FLAG_LAYOUT_FLAT.
        Parameters:
        viewer - the viewer to be configured

      • fillContextMenu

        protected void fillContextMenu​(IMenuManager mgr)
        Fills the context menu for this page. Subclasses may override this method.
        Parameters:
        mgr - the menu manager representing the context menu

      • canRemoveMatchesWith

        protected boolean canRemoveMatchesWith​(ISelection selection)
        Determines whether the provided selection can be used to remove matches from the result.
        Parameters:
        selection - the selection to test
        Returns:
        returns true if the elements in the current selection can be removed.
        Since:
        3.2

      • createControl

        public void createControl​(Composite parent)
        Description copied from interface: IPage
        Creates the SWT control for this page under the given parent control.

        Clients should not call this method (the workbench calls this method when it needs to, which may be never).

        Specified by:
        createControl in interface IPage
        Specified by:
        createControl in class Page
        Parameters:
        parent - the parent control

      • postEnsureSelection

        protected void postEnsureSelection()
        Posts a UI update to make sure an element is selected.
        Since:
        3.2

      • isLayoutSupported

        public boolean isLayoutSupported​(int layout)
        Determines whether a certain layout is supported by this search result page.
        Parameters:
        layout - the layout to test for
        Returns:
        whether the given layout is supported or not
        See Also:
        AbstractTextSearchViewPage(int)

      • setLayout

        public void setLayout​(int layout)
        Sets the layout of this search result page. The layout must be on of FLAG_LAYOUT_FLAT or FLAG_LAYOUT_TREE and it must be one of the values passed during construction of this search result page.
        Parameters:
        layout - the new layout
        See Also:
        isLayoutSupported(int)

      • getLayout

        public int getLayout()
        Return the layout this page is currently using.
        Returns:
        the layout this page is currently using
        See Also:
        FLAG_LAYOUT_FLAT, FLAG_LAYOUT_TREE

      • createTreeViewer

        protected TreeViewer createTreeViewer​(Composite parent)
        Creates the tree viewer to be shown on this page. Clients may override this method.
        Parameters:
        parent - the parent widget
        Returns:
        returns a newly created TreeViewer.

      • createTableViewer

        protected TableViewer createTableViewer​(Composite parent)
        Creates the table viewer to be shown on this page. Clients may override this method.
        Parameters:
        parent - the parent widget
        Returns:
        returns a newly created TableViewer

      • setFocus

        public void setFocus()
        Description copied from class: Page
        The Page implementation of this IPage method does nothing. Subclasses must implement.
        Specified by:
        setFocus in interface IPage
        Specified by:
        setFocus in class Page

      • getControl

        public Control getControl()
        Description copied from class: Page
        The Page implementation of this IPage method returns null. Subclasses must reimplement.
        Specified by:
        getControl in interface IPage
        Specified by:
        getControl in class Page
        Returns:
        the SWT control for this page, or null if this page does not have a control

      • setInput

        public void setInput​(ISearchResult newSearch,
                     Object viewState)
        Description copied from interface: ISearchResultPage
        Sets the search result to be shown in this search results page. Implementers should restore UI state (e.g. selection) from the previously saved uiState object.
        Specified by:
        setInput in interface ISearchResultPage
        Parameters:
        newSearch - the search result to be shown or null to clear the page.
        viewState - the previously saved UI state
        See Also:
        ISearchResultPage.getUIState()

      • getUIState

        public Object getUIState()
        Description copied from interface: ISearchResultPage
        Returns an object representing the current user interface state of the page. For example, the current selection in a viewer. The UI state will be later passed into the setInput() method when the currently shown ISearchResult is shown again.
        Specified by:
        getUIState in interface ISearchResultPage
        Returns:
        an object representing the UI state of this page

      • getViewer

        protected StructuredViewer getViewer()
        Returns the viewer currently used in this page.
        Returns:
        the currently used viewer or null if none has been created yet.

      • gotoNextMatch

        public void gotoNextMatch()
        Selects the element corresponding to the next match and shows the match in an editor. Note that this will cycle back to the first match after the last match.

      • gotoPreviousMatch

        public void gotoPreviousMatch()
        Selects the element corresponding to the previous match and shows the match in an editor. Note that this will cycle back to the last match after the first match.

      • getCurrentMatch

        public Match getCurrentMatch()
        Returns the currently selected match.
        Returns:
        the selected match or null if none are selected

      • getDisplayedMatches

        public Match[] getDisplayedMatches​(Object element)
        Returns the matches that are currently displayed for the given element. If AbstractTextSearchResult.getActiveMatchFilters() is not null, only matches are returned that are not filtered by the match filters. If AbstractTextSearchResult.getActiveMatchFilters() is null all matches of the given element are returned. Any action operating on the visible matches in the search result page should use this method to get the matches for a search result (instead of asking the search result directly).
        Parameters:
        element - The element to get the matches for
        Returns:
        The matches displayed for the given element. If the current input of this page is null, an empty array is returned
        See Also:
        AbstractTextSearchResult.getMatches(Object)

      • getCurrentMatchLocation

        public IRegion getCurrentMatchLocation​(Match match)
        Returns the current location of the match. This takes possible modifications of the file into account. Therefore the result may differ from the position information that can be obtained directly off the match.
        Parameters:
        match - the match to get the position for.
        Returns:
        the current position of the match.
        Since:
        3.2

      • getDisplayedMatchCount

        public int getDisplayedMatchCount​(Object element)
        Returns the number of matches that are currently displayed for the given element. If AbstractTextSearchResult.getActiveMatchFilters() is not null, only matches are returned that are not filtered by the match filters. Any action operating on the visible matches in the search result page should use this method to get the match count for a search result (instead of asking the search result directly).
        Parameters:
        element - The element to get the matches for
        Returns:
        The number of matches displayed for the given element. If the current input of this page is null, 0 is returned
        See Also:
        AbstractTextSearchResult.getMatchCount(Object)

      • dispose

        public void dispose()
        Description copied from class: Page
        The Page implementation of this IPage method disposes of this page's control (if it has one and it has not already been disposed). Subclasses may extend.
        Specified by:
        dispose in interface IPage
        Overrides:
        dispose in class Page

      • init

        public void init​(IPageSite pageSite)
        Description copied from class: Page
        The Page implementation of this IPageBookViewPage method stores a reference to the supplied site (the site which contains this page).

        Subclasses may extend.

        Specified by:
        init in interface IPageBookViewPage
        Overrides:
        init in class Page
        Parameters:
        pageSite - the page site

      • fillToolbar

        protected void fillToolbar​(IToolBarManager tbm)
        Fills the toolbar contribution for this page. Subclasses may override this method.
        Parameters:
        tbm - the tool bar manager representing the view's toolbar

      • getViewPart

        protected ISearchResultViewPart getViewPart()
        Returns the view part set with setViewPart(ISearchResultViewPart).
        Returns:
        The view part or null if the view part hasn't been set yet (or set to null).

      • handleSearchResultChanged

        protected void handleSearchResultChanged​(SearchResultEvent e)
        Handles a search result event for the current search result.
        Parameters:
        e - the event to handle
        Since:
        3.2

      • evaluateChangedElements

        protected void evaluateChangedElements​(Match[] matches,
                                       Set<Object> changedElements)
        Evaluates the elements to that are later passed to elementsChanged(Object[]). By default the element to change are the elements received by (Match.getElement()). Client implementations can modify this behavior.
        Parameters:
        matches - the matches that were added or removed
        changedElements - the set that collects the elements to change. Clients should only add elements to the set.
        Since:
        3.4

      • internalRemoveSelected

        public void internalRemoveSelected()
        Note: this is internal API and should not be called from clients outside of the search plug-in.

        Removes the currently selected match. Does nothing if no match is selected.

        Restriction:
        This method is not intended to be referenced by clients.

      • handleOpen

        protected void handleOpen​(OpenEvent event)

        This method is called when the search page gets an 'open' event from its underlying viewer (for example on double click). The default implementation will open the first match on any element that has matches. If the element to be opened is an inner node in the tree layout, the node will be expanded if it's collapsed and vice versa. Subclasses are allowed to override this method.

        Parameters:
        event - the event sent for the currently shown viewer
        See Also:
        IOpenListener

      • setElementLimit

        public void setElementLimit​(Integer limit)
        Sets the maximal number of top level elements to be shown in a viewer. If null is set, the view page does not support to limit the elements and will not provide UI to configure it. If a non-null value is set, configuration UI will be provided. The limit value must be a positive number or -1 to not limit top level element. If enabled, the element limit has to be enforced by the content provider that is implemented by the client. The view page just manages the value and configuration.
        Parameters:
        limit - the element limit. Valid values are:
        • null to not limit and not provide configuration UI
        • -1 to not limit and provide configuration UI
        • positive integer to limit by the given value and provide configuration UI
        Since:
        3.3

      • getElementLimit

        public Integer getElementLimit()
        Gets the maximal number of top level elements to be shown in a viewer. null means the view page does not limit the elements and will not provide UI to configure it. If a non-null value is set, configuration UI will be provided. The limit value must be a positive number or -1 to not limit top level element.
        Returns:
        returns the element limit. Valid values are:
        • null to not limit and not provide configuration UI (default value)
        • -1 to not limit and provide configuration UI
        • positive integer to limit by the given value and provide configuration UI
        Since:
        3.3