IHistoryPage


1   /*******************************************************************************
2    * Copyright (c) 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.team.ui.history;
13  
14  import org.eclipse.core.resources.IResource;
15  import org.eclipse.jface.util.IPropertyChangeListener;
16  import org.eclipse.team.core.RepositoryProvider;
17  import org.eclipse.team.core.history.IFileHistoryProvider;
18  import org.eclipse.team.internal.ui.TeamUIPlugin;
19  import org.eclipse.team.ui.TeamUI;
20  import org.eclipse.ui.SubActionBars;
21  
22  
23  /**
24   * <p>Interface for pages that appear in the team history view.</p>
25   * <p><em>This interface is not intended to be implemented by clients.
26   * Clients can instead subclass {@link HistoryPage}.</em></p>
27   *  
28   * <h3>Lifecycle</h3>
29   * <p>
30   * Once an Object requests to have its history shown in the History View (through an action or DND), the History View
31   * will first try to see if any of the open History Views (there can be multiple Views if some of them are pinned) currently
32   * show the requested Object's history. It does this by calling {@link HistoryPage#getInput()} on each IHistoryPage (which is supposed
33   * to extend {@link HistoryPage} and comparing the input with the passed in Object. If a History View is found that already contains the Object, 
34   * it is brought to the front and its history is refreshed (by calling {@link #refresh()}).
35   * If no History View already contains the requested Object an <code>IHistoryPage</code> might need to be created if the current <code>IHistoryPage</code>
36   * being shown in the History View doesn't know how to display the Object or if there are no <code>IHistoryPage</code>s being shown in the History View. 
37   * </p>
38   * <p>
39   * The History View uses an {@link IHistoryPageSource#createPage(Object)} to create the <code>IHistoryPage</code>. If the History View can 
40   * determine what the Repository Provider is for the dropped Object (i.e. the Object is an instance of {@link IResource}), then it will try
41   * to get the {@link IFileHistoryProvider} for the Repository Provider by calling {@link RepositoryProvider#getFileHistoryProvider()}. If no
42   * <code>IFileHistoryProvider</code> is returned, the History View will try to adapt the Repository Provider to a <code>IFileHistoryProvider</code>.
43   * If the Object whose history is being requested is not an {@link IResource}, it will not be possible to retrieve the Repository Provider from it. 
44   * In these instances the History View will try to adapt the Object to an {@link IHistoryPageSource}.
45   * </p>
46   * <p>
47   * Once the <code>IHistoryPage</code> is created, {@link IHistoryPage#setInput(Object)} is called; this is handled by {@link HistoryPage} which clients
48   * should subclass for their own <code>IHistoryPage</code> implementations. <code>HistoryPage</code> will in turn call {@link HistoryPage#inputSet()} -
49   * which clients can use for setting up their <code>IHistoryPage</code>. The old page in the History View (along with its {@link SubActionBars} is disposed  - 
50   * {@link HistoryPage#dispose()} gets called; interested clients can supply a <code>dispose()</code> method in their subclass. Finally, the new page is shown 
51   * and its SubActionBars are activated.
52   * </p>
53   * 
54   * 
55   * @see TeamUI#getHistoryView()
56   * @since 3.2
57   */
58  public interface IHistoryPage {
59      
60      /**
61       * Property name constant (value <code>"org.eclipse.team.ui.name"</code>)
62       * for the page's name.
63       * @since 3.3
64       */
65      public static final String   P_NAME = TeamUIPlugin.ID + ".name"; //$NON-NLS-1$
66  
67      /**
68       * Property name constant (value <code>"org.eclipse.team.ui.description"</code>)
69       * for an page's description.
70       * @since 3.3
71       */
72      public static final String   P_DESCRIPTION = TeamUIPlugin.ID + ".description"; //$NON-NLS-1$
73      
74      /**
75       * Fetches and populates the history page for the given Object. Clients
76       * should provide an implementation for their individual pages.
77       * 
78       * @param object the object for which history is being requested for
79       * @return true if the page was able to display the history for the object, false otherwise
80       * @since 3.2
81       */
82      public boolean setInput(Object   object);
83  
84      /**
85       * Returns the object whose history is currently being displayed in the history page. 
86       * @return object   the object being displayed in the history page or <code>null</code> 
87       * if no input has been set;
88       * @since 3.2
89       */
90      public Object   getInput();
91      
92      /**
93       * Returns true if this history page can show a history for the given object, false if it cannot
94       * @param object the object that is to have history shown
95       * @return boolean 
96       * @since 3.2
97       */
98      public boolean isValidInput(Object   object);
99  
100     /**
101      * Requests a refresh of the information presented by the history page.
102      * @since 3.2
103      */
104     public void refresh();
105 
106     /**
107      * Returns the name of the object whose history the page is showing
108      * @return String containing the name of the object 
109      * @since 3.2
110      */
111     public String   getName();
112     
113     /**
114      * Returns a one line description of the object whose history is
115      * being displayed. For example, for files, this may be the 
116      * workspace path of the file. The description may be displayed to
117      * the user as tooltip text or by some other means.
118      * @return a one line description of the object whose history is
119      * being displayed or <code>null</code>
120      * @since 3.2
121      */
122     public String   getDescription();
123 
124     /**
125      * Set the site for the page - this needs to be replaced with a proper
126      * {@link IHistoryPageSite} in order to allow history pages to be displayed in 
127      * both views and dialogs.
128      * @param site the history page site
129      * @since 3.2
130      */
131     public void setSite(IHistoryPageSite site);
132     
133     /**
134      * Returns the {@link IHistoryPageSite} set for this page.
135      * @return the history page site for this page
136      * @since 3.2
137      */
138     public IHistoryPageSite getHistoryPageSite();
139     
140     /**
141      * Called to allow IHistoryPage a chance to dispose of any widgets created 
142      * for its page implementation
143      * @since 3.2
144      */
145     public void dispose();
146     
147     /**
148      * Returns the {@link IHistoryView} instance that contains this history page or <em>null</em> if 
149      * the history view instance cannot be determined.
150      * @return IHistoryView the history view that contains this history page or <em>null</em> if 
151      * the history view instance cannot be determined.
152      * @since 3.3
153      */
154     public IHistoryView getHistoryView();
155     
156     /**
157      * Adds a listener for changes to properties of this page. 
158      * Has no effect if an identical listener is already
159      * registered.
160      * <p>
161      * The changes supported by the page are as follows:
162      * <ul>
163      * <li><code>P_NAME</code>- indicates the name
164      * of the page has changed</li>
165      * <li><code>P_DESCRIPTION</code>- indicates the
166      * description of the page has changed</li>
167      * </ul></p>
168      * <p>
169      * Clients may define additional properties as required.
170      * </p>
171      * @param listener a property change listener
172      * @since 3.3
173      */
174     public void addPropertyChangeListener(IPropertyChangeListener listener);
175     
176     /**
177      * Removes the given property listener from this page.
178      * Has no effect if an identical listener is not already registered.
179      * 
180      * @param listener a property listener
181      * @since 3.3
182      */
183     public void removePropertyChangeListener(IPropertyChangeListener listener);
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags