Eclipse Platform
Release 3.0

org.eclipse.search.ui.text
Class AbstractTextSearchViewPage

java.lang.Object
  extended byorg.eclipse.ui.part.Page
      extended byorg.eclipse.search.ui.text.AbstractTextSearchViewPage
All Implemented Interfaces:
IPage, IPageBookViewPage, ISearchResultPage

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 Summary
protected static Match[] EMPTY_MATCH_ARRAY
          An empty array.
static int FLAG_LAYOUT_FLAT
          Flag (value 1) denoting tree layout.
static int FLAG_LAYOUT_TREE
          Flag (value 2) denoting flat list layout.
 
Constructor Summary
protected AbstractTextSearchViewPage()
          Constructs this page with the default layout flags.
protected AbstractTextSearchViewPage(int supportedLayouts)
          This constructor must be passed a combination of layout flags combined with bitwise or.
 
Method Summary
protected abstract  void clear()
          This method is called whenever all elements have been removed from the shown AbstractSearchResult.
protected abstract  void configureTableViewer(TableViewer viewer)
          Configures the given viewer.
protected abstract  void configureTreeViewer(TreeViewer viewer)
          Configures the given viewer.
 void createControl(Composite parent)
          
protected  TableViewer createTableViewer(Composite parent)
          Creates the table viewer to be shown on this page.
protected  TreeViewer createTreeViewer(Composite parent)
          Creates the tree viewer to be shown on this page.
 void dispose()
          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.
protected abstract  void elementsChanged(Object[] objects)
          This method is called whenever the set of matches for the given elements changes.
protected  void fillContextMenu(IMenuManager mgr)
          Fills the context menu for this page.
protected  void fillToolbar(IToolBarManager tbm)
          Fills the toolbar contribution for this page.
 Control getControl()
          The Page implementation of this IPage method returns null. Subclasses must reimplement.
 Match getCurrentMatch()
          Returns the currently selected match.
 int getDisplayedMatchCount(Object element)
          Returns the number of matches that are currently displayed for the given element.
 Match[] getDisplayedMatches(Object element)
          Returns the matches that are currently displayed for the given element.
 String getID()
          Returns the id set via setID.
 AbstractTextSearchResult getInput()
          Returns the currently shown result.
 String getLabel()
          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'.
 int getLayout()
          Return the layout this page is currently using.
protected  IDialogSettings getSettings()
          Returns a dialog settings object for this search result page.
 Object getUIState()
          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.
protected  StructuredViewer getViewer()
          Returns the viewer currently used in this page.
protected  ISearchResultViewPart getViewPart()
          Returns the view part set with setViewPart(ISearchResultViewPart).
 void gotoNextMatch()
          Selects the element corresponding to the next match and shows the match in an editor.
 void gotoPreviousMatch()
          Selects the element corresponding to the previous match and shows the match in an editor.
protected  void handleOpen(OpenEvent event)
          This method is called when the search page gets an open even from it's underlying viewer (for example on double click).
 void init(IPageSite pageSite)
          The Page implementation of this IPageBookViewPage method stores a reference to the supplied site (the site which contains this page).

Subclasses may extend.

 void internalRemoveSelected()
          Note: this is internal API and should not be called from clients outside of the search plug-in.
 boolean isLayoutSupported(int layout)
          Determines whether a certain layout is supported by this search result page.
 void restoreState(IMemento memento)
          Restores the page state. Note that this applies only to state that is saved across sessions. Subclasses may extend this method.
 void saveState(IMemento memento)
          { @inheritDoc } Subclasses my extend this method.
 void setFocus()
          The Page implementation of this IPage method does nothing. Subclasses must implement.
 void setID(String id)
          Sets the id for this page. This method will be called before any other initialization is done.
 void setInput(ISearchResult search, Object viewState)
          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.
 void setLayout(int layout)
          Sets the layout of this search result page.
 void setViewPart(ISearchResultViewPart part)
          { @inheritDoc }
protected  void showMatch(Match match, int currentOffset, int currentLength)
          Deprecated.  
protected  void showMatch(Match match, int currentOffset, int currentLength, boolean activate)
          Opens an editor on the given element and selects the given range of text.
 
Methods inherited from class org.eclipse.ui.part.Page
getSite, makeContributions, setActionBars
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.eclipse.ui.part.IPageBookViewPage
getSite
 
Methods inherited from interface org.eclipse.ui.part.IPage
setActionBars
 

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

See Also:
Constant Field Values

FLAG_LAYOUT_TREE

public static final int FLAG_LAYOUT_TREE
Flag (value 2) denoting flat list 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)
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

getID

public String getID()
Returns the id set via setID.

Specified by:
getID in interface ISearchResultPage
Returns:
the id of this page

getLabel

public String getLabel()
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

protected void showMatch(Match match,
                         int currentOffset,
                         int currentLength)
                  throws PartInitException
Deprecated.  

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

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.

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

createControl

public void createControl(Composite parent)

Specified by:
createControl in interface IPage
Specified by:
createControl in class Page

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()
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()
The Page implementation of this IPage method returns null. Subclasses must reimplement.

Specified by:
getControl in interface IPage
Specified by:
getControl in class Page

setInput

public void setInput(ISearchResult search,
                     Object viewState)
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:
search - the search result to be shown
viewState - the previously saved UI state
See Also:
ISearchResultPage.getUIState()

getUIState

public Object getUIState()
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.

getInput

public AbstractTextSearchResult getInput()
Returns the currently shown result.

Returns:
the previously set result or null
See Also:
setInput(ISearchResult, Object)

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. While the default implementation just forwards to the current input search result of the page, subclasses may override this method to do filtering, etc. 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)

getDisplayedMatchCount

public int getDisplayedMatchCount(Object element)
Returns the number of matches that are currently displayed for the given element. While the default implementation just forwards to the current input search result of the page, subclasses may override this method to do filtering, etc. 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()
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)
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

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

setViewPart

public void setViewPart(ISearchResultViewPart part)
{ @inheritDoc }

Specified by:
setViewPart in interface ISearchResultPage
Parameters:
part - the parent search view

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

restoreState

public void restoreState(IMemento memento)
Restores the page state. Note that this applies only to state that is saved across sessions. Subclasses may extend this method.

Specified by:
restoreState in interface ISearchResultPage
Parameters:
memento - a memento to restore the page state from or null if no previous state was saved
See Also:
ISearchResultPage.setInput(ISearchResult, Object)

saveState

public void saveState(IMemento memento)
{ @inheritDoc } Subclasses my extend this method.

Specified by:
saveState in interface ISearchResultPage
Parameters:
memento - a memento to receive the object state
See Also:
ISearchResultPage.getUIState()

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.


handleOpen

protected void handleOpen(OpenEvent event)

This method is called when the search page gets an open even from it's 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

Eclipse Platform
Release 3.0

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.