org.eclipse.team.ui.history

## Interface IHistoryPage

All Known Implementing Classes:
  HistoryPage

    public interface IHistoryPage

Interface for pages that appear in the team history view.

This interface is not intended to be implemented by clients. Clients can instead subclass `HistoryPage`.

### Lifecycle

Once an Object requests to have its history shown in the History View (through an action or DND), the History View will first try to see if any of the open History Views (there can be multiple Views if some of them are pinned) currently show the requested Object's history. It does this by calling `HistoryPage.getInput()` on each IHistoryPage (which is supposed to extend `HistoryPage` and comparing the input with the passed in Object. If a History View is found that already contains the Object, it is brought to the front and its history is refreshed (by calling `refresh()`). If no History View already contains the requested Object an `IHistoryPage` might need to be created if the current `IHistoryPage` being shown in the History View doesn't know how to display the Object or if there are no `IHistoryPage`s being shown in the History View.

The History View uses an `IHistoryPageSource.createPage(Object)` to create the `IHistoryPage`. If the History View can determine what the Repository Provider is for the dropped Object (i.e. the Object is an instance of `IResource`), then it will try to get the `IFileHistoryProvider` for the Repository Provider by calling `RepositoryProvider.getFileHistoryProvider()`. If no `IFileHistoryProvider` is returned, the History View will try to adapt the Repository Provider to a `IFileHistoryProvider`. If the Object whose history is being requested is not an `IResource`, it will not be possible to retrieve the Repository Provider from it. In these instances the History View will try to adapt the Object to an `IHistoryPageSource`.

Once the `IHistoryPage` is created, `setInput(Object)` is called; this is handled by `HistoryPage` which clients should subclass for their own `IHistoryPage` implementations. `HistoryPage` will in turn call `HistoryPage.inputSet()` - which clients can use for setting up their `IHistoryPage`. The old page in the History View (along with its `SubActionBars` is disposed - `Page.dispose()` gets called; interested clients can supply a `dispose()` method in their subclass. Finally, the new page is shown and its SubActionBars are activated.

Since:
  3.2
See Also:
  `TeamUI.getHistoryView()`

### Field Summary

Fields
`static String` `P_DESCRIPTION` Property name constant (value `"org.eclipse.team.ui.description"`) for an page's description.
`static String` `P_NAME` Property name constant (value `"org.eclipse.team.ui.name"`) for the page's name.

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `addPropertyChangeListener(IPropertyChangeListener listener)` Adds a listener for changes to properties of this page.
`void` `dispose()` Called to allow IHistoryPage a chance to dispose of any widgets created for its page implementation
`String` `getDescription()` Returns a one line description of the object whose history is being displayed.
`IHistoryPageSite` `getHistoryPageSite()` Returns the `IHistoryPageSite` set for this page.
`IHistoryView` `getHistoryView()` Returns the `IHistoryView` instance that contains this history page or null if the history view instance cannot be determined.
`Object` `getInput()` Returns the object whose history is currently being displayed in the history page.
`String` `getName()` Returns the name of the object whose history the page is showing
`boolean` `isValidInput(Object object)` Returns true if this history page can show a history for the given object, false if it cannot
`void` `refresh()` Requests a refresh of the information presented by the history page.
`void` `removePropertyChangeListener(IPropertyChangeListener listener)` Removes the given property listener from this page.
`boolean` `setInput(Object object)` Fetches and populates the history page for the given Object.
`void` `setSite(IHistoryPageSite site)` Set the site for the page - this needs to be replaced with a proper `IHistoryPageSite` in order to allow history pages to be displayed in both views and dialogs.

### Field Detail

#### P_NAME

    static final String P_NAME

Property name constant (value `"org.eclipse.team.ui.name"`) for the page's name.

Since:
  3.3
See Also:
  Constant Field Values

#### P_DESCRIPTION

    static final String P_DESCRIPTION

Property name constant (value `"org.eclipse.team.ui.description"`) for an page's description.

Since:
  3.3
See Also:
  Constant Field Values

### Method Detail

#### setInput

    boolean setInput(Object object)

Fetches and populates the history page for the given Object. Clients should provide an implementation for their individual pages.

Parameters:
  `object` - the object for which history is being requested for
Returns:
  true if the page was able to display the history for the object, false otherwise
Since:
  3.2

#### getInput

    Object getInput()

Returns the object whose history is currently being displayed in the history page.

Returns:
  object the object being displayed in the history page or `null` if no input has been set;
Since:
  3.2

#### isValidInput

    boolean isValidInput(Object object)

Returns true if this history page can show a history for the given object, false if it cannot

Parameters:
  `object` - the object that is to have history shown
Returns:
  boolean
Since:
  3.2

#### refresh

    void refresh()

Requests a refresh of the information presented by the history page.

Since:
  3.2

#### getName

    String getName()

Returns the name of the object whose history the page is showing

Returns:
  String containing the name of the object
Since:
  3.2

#### getDescription

    String getDescription()

Returns a one line description of the object whose history is being displayed. For example, for files, this may be the workspace path of the file. The description may be displayed to the user as tooltip text or by some other means.

Returns:
  a one line description of the object whose history is being displayed or `null`
Since:
  3.2

#### setSite

    void setSite(IHistoryPageSite site)

Set the site for the page - this needs to be replaced with a proper `IHistoryPageSite` in order to allow history pages to be displayed in both views and dialogs.

Parameters:
  `site` - the history page site
Since:
  3.2

#### getHistoryPageSite

    IHistoryPageSite getHistoryPageSite()

Returns the `IHistoryPageSite` set for this page.

Returns:
  the history page site for this page
Since:
  3.2

#### dispose

    void dispose()

Called to allow IHistoryPage a chance to dispose of any widgets created for its page implementation

Since:
  3.2

#### getHistoryView

    IHistoryView getHistoryView()

Returns the `IHistoryView` instance that contains this history page or null if the history view instance cannot be determined.

Returns:
  IHistoryView the history view that contains this history page or null if the history view instance cannot be determined.
Since:
  3.3

#### addPropertyChangeListener

    void addPropertyChangeListener(IPropertyChangeListener listener)

Adds a listener for changes to properties of this page. Has no effect if an identical listener is already registered.

The changes supported by the page are as follows:

- `P_NAME`- indicates the name of the page has changed
- `P_DESCRIPTION`- indicates the description of the page has changed

Clients may define additional properties as required.

Parameters:
  `listener` - a property change listener
Since:
  3.3

#### removePropertyChangeListener

    void removePropertyChangeListener(IPropertyChangeListener listener)

Removes the given property listener from this page. Has no effect if an identical listener is not already registered.

Parameters:
  `listener` - a property listener
Since:
  3.3