Team FAQ

• Team Wiki page
• Team Component page

Team API Questions

History API

I have an IHistoryPage implementation. How do I hook it up into the History View?

You have a number of options here:

• Provide your own action that will show your object in the History View. You can get a handle to the History View by calling TeamUI.getHistoryView().You then call IHistoryView.showHistoryFor(Object) and pass the object that your action is triggered from.
• Supply your own drag and drop adapter (see below)

What is the lifecyle of an IHistoryPage?

• The user requests the history for an object (either by selecting an action, or dragging and dropping the object on the History View, or by clicking on an object with linking enabled on the History View).
• For an IResource:
  1. Check to see if the resource is currently being displayed in the History View; if it is then IHistoryPage.refresh gets called to refresh the HistoryPage's contents.
     • If the resource is not found in the current page being displayed in the view, check to see if there are other view instances around (i.e. some History Views have been pinned) and if they contain the resource. If they do, bring them to the top, and refresh the page.
  2. If the view that the resource has been dropped on is pinned, first check to see if another view already contains that resource (if it does it is brought to the top and refreshed), if none does a new History View instance gets created.
  3. Try to get the RepositoryProvider from the resource, and get the IFileHistoryProvider from the RepositoryProvider. If an IFileHistoryProvider can be obtained, adapt it to a IHistoryPageSource. If no IFileHistoryProvider can be obtained from the RepositoryProvider, try to adapt the RepositoryProvider itself to an IHistoryPageSource.
  4. Check to see if the current page in the History View can handle the dropped item (call IHistoryPage.isValidInput), if it's not, it uses the IHistoryPageSource to create the page.
  5. Call setInput on HistoryPage, which will in turn call inputSet.
  6. Set the resource name as the content description.
  7. Dispose of the old page being shown in the view by calling dispose and dispose of the old page's subAction bars.
• For an Object:
  1. Check to see if the Object adapts to IHistoryPageSource
  2. If the History View is currently showing a History page already, see if it knows how to display the dropped object; if it doesn't know how to display it create a new page and show it (same steps as in the resource case above)

How do I add drag-and-drop for my IHistoryPage?

• The History View supplies a GenericHistoryDropAdapter which will handle DND for all IResources.
• If you wish to add handling of custom objects, you need to provide an implementation of IDropActionDelegate and extend the org.eclipse.ui.dropActions extension point.

What is the difference between IHistoryPage.getName() and IHistoryPage.getDescription()

• getName() is the name displayed in the History View for the Object being shown.
• getDescription() can be a longer string describing the Object being shown.

What is an IHistoryPage expected to do on a setFocus() call?

Since clients are expected to subclass HistoryPage for their HistoryPage implementations, and HistoryPage extends Page, clients must provide a setFocus() implementation in their class. Clients can use this to pass the focus to whatever widget they are using for their page. This allows keystrokes to be routed to the current History Page.

When does createControl() get called?

When the History View needs to create a new history page, it will call IHistoryPageSource.createPage(Object). It will then call the createControl() on the returned Page.

How do I annotate a file with revision information in the revision ruler on an editor

There are two issues related to file annotation. The first is how to populate the revision ruler and the second is how to link the revision selections with entries in a history view or vice versa. The second issue is covered in the next FAQ entry.

To populate the revision ruler on an editor you must do the following:

• Create an instance of .RevisionInformation and populate it with a set of org.eclipse.jface.text.revisions.Revision instances. Each Revision has an id and a set of org.eclipse.jface.text.source.LineRange instances that define the regons of the file that ae associated with that particular revision.

• Open the editor on the file. The editor must be an instance of org.eclipse.ui.texteditor.AbstractDecoratedTextEditor. You can use the openEditor helper methods on org.eclipse.team.ui.history.RevisionAnnotationController to ensure that an appropriate editor is opened.

• Set the revision information of the editor by calling showRevisionInformation. This method also require that you provide the id of a quick diff provider that can be used to fetch the contents of the file.

How do I link entries in the history view with revisions in the revision ruler

The org.eclipse.team.ui.history.RevisionAnnotationController class is API that can be used to link a history list (e.g. History view) to the revision ruler of an editor. It tracks the selection of both the history list (an ISelectionProvider) and the revision ruler and keeps them in-sync. Clients need to create a subclass in order to translate Revision instance from the revision ruler into history list entries and vice versa.