| /******************************************************************************* |
| * Copyright (c) 2000, 2009 IBM Corporation and others. |
| * |
| * This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.team.ui.synchronize; |
| |
| import org.eclipse.compare.CompareConfiguration; |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.core.runtime.IExecutableExtension; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| import org.eclipse.jface.preference.PreferencePage; |
| import org.eclipse.jface.resource.ImageDescriptor; |
| import org.eclipse.jface.util.IPropertyChangeListener; |
| import org.eclipse.team.core.TeamException; |
| import org.eclipse.ui.IMemento; |
| import org.eclipse.ui.IWorkbenchPart; |
| import org.eclipse.ui.PartInitException; |
| import org.eclipse.ui.part.IPageBookViewPage; |
| |
| /** |
| * A synchronize participant is a visual component that can be displayed within any |
| * control (e.g. view, editor, dialog). Typically a participant is used to show changes between |
| * local resources and variant states of those resources and allows the user to perform actions |
| * to manipulate the changes. |
| * <p> |
| * This class does not mandate how the synchronization state is displayed, but instead provides |
| * the accessors that clients would use to create a visual instance of the this participant. |
| * </p><p> |
| * A participant can display multiple instances of its synchronization state to the user via the creation |
| * of a page {@link #createPage(ISynchronizePageConfiguration)} and |
| * clients can decide where to display the page. For example, the synchronize view is an example |
| * of a client that displays a participant in a view. However, you can imagine that a client may |
| * also want to display this state in a wizard or dialog instead. |
| * </p><p> |
| * When a participant is registered with the {@link ISynchronizeManager} it will automatically display |
| * in the <i>Synchronize View</i> and if the participant extension point |
| * enabled <code>synchronizeWizards</code> it will also appear in the global synchronize action |
| * toolbar. |
| * <p> |
| * A participant is added to the workbench as follows:</p> |
| * <ul> |
| * <li>A <code>synchronizeParticipant</code> extension is contributed to |
| * the team registry. This extension defines the participant id, name, icon, type, and |
| * participant class. |
| * <li>A user via a wizard provided by the <code>synchronizeWizards</code> extension point |
| * or client code, creates a participant instance and registers it with the |
| * synchronize manager. It then appears in the synchronize view. |
| * <li>A synchronization can be persistent and thus re-initialized at startup. |
| * <li>A pinned participant will only be removed from the synchronize manager if it is un-pinned. |
| * </ul> |
| * <p> |
| * Once a participant is added to the synchronize manager its lifecycle will be managed. On shutdown if |
| * the participant is persistable, the participant will be asked to persist state via |
| * the <code>saveState()</code> method. At startup the <code>init()</code> method is called |
| * with a handle to the state that was saved. The dispose method is called when the participant is |
| * removed from the manager and at shutdown. |
| * </p> |
| * @see ISynchronizeView |
| * @see ISynchronizeManager |
| * @see AbstractSynchronizeParticipant |
| * @since 3.0 |
| * @noimplement Clients are not intended to implement this interface. Instead, |
| * subclass {@link AbstractSynchronizeParticipant}. |
| */ |
| public interface ISynchronizeParticipant extends IExecutableExtension, IAdaptable { |
| |
| /** |
| * A property constant that can be used to indicate that the content of this participant |
| * has changed. This is a general event that can be used to indicate to the user that there |
| * is a change in state for the participant. In general, the values associated with the event do not have |
| * any meaning. |
| * |
| * @see #addPropertyChangeListener(IPropertyChangeListener) |
| */ |
| public static final String P_CONTENT = "org.eclipse.team.ui.content"; //$NON-NLS-1$ |
| |
| /** |
| * Returns the unique id that identified the <i>type</i> of this |
| * synchronize participant. The synchronize manager supports registering |
| * several instances of the same participant type. |
| * |
| * @return the unique id that identified the <i>type</i> of this |
| * synchronize participant. |
| */ |
| public String getId(); |
| |
| /** |
| * Returns the instance id that identified the unique instance of this |
| * participant. The synchronize manager supports registering |
| * several instances of the same participant type and this id is used |
| * to differentiate between them. |
| * |
| * @return the instance id that identified the unique instance of this |
| * participant or <code>null</code> if this participant doesn't support |
| * multiple instances. |
| */ |
| public String getSecondaryId(); |
| |
| /** |
| * Returns the name of this synchronize participant. This name is displayed to the user. |
| * |
| * @return the name of this synchronize participant |
| */ |
| public String getName(); |
| |
| /** |
| * Returns an image descriptor for this synchronize participant, or <code>null</code> |
| * if none. |
| * |
| * @return an image descriptor for this synchronize participant, or <code>null</code> |
| * if none |
| */ |
| public ImageDescriptor getImageDescriptor(); |
| |
| /** |
| * Returns if this participant is pinned. Pinned participants will only be removed from the |
| * synchronize manager until they are un-pinned. |
| * |
| * @return <code>true</code> if this participant is pinned and <code>false</code> |
| * otherwise. |
| */ |
| public boolean isPinned(); |
| |
| /** |
| * Sets whether this participant is pinned. |
| * |
| * @param pinned sets if the participant is pinned. |
| */ |
| public void setPinned(boolean pinned); |
| |
| /** |
| * Creates the configuration for the participant page. The configuration controls the |
| * options for displaying the participant. The configuration used to initialize the page |
| * when {@link #createPage(ISynchronizePageConfiguration)} is called and as such |
| * can be used to pre-configure visual properties of the displayed page. |
| * |
| * @return the configuration for the participant page. |
| */ |
| public ISynchronizePageConfiguration createPageConfiguration(); |
| |
| /** |
| * Creates and returns a new page for this synchronize participant. The |
| * page is displayed using the parameters from the configuration. For example, |
| * the configuration defines the context in which the page is shown, via the |
| * {@link ISynchronizePageSite}. |
| * |
| * @param configuration used to initialize the page |
| * @return a page book view page representation of this synchronize |
| * participant |
| */ |
| public IPageBookViewPage createPage(ISynchronizePageConfiguration configuration); |
| |
| /** |
| * Runs the participants action. Typically this would be some action to refresh the synchronization |
| * state of the participant. This action is run from the global synchronize drop-down. |
| * |
| * @param part the part in which the action is run or <code>null</code> if the action |
| * is not being run in a workbench part. |
| */ |
| public void run(IWorkbenchPart part); |
| |
| /** |
| * Initializes this participant with the given participant state. |
| * A memento is passed to the participant which contains a snapshot |
| * of the participants state from a previous session. |
| * <p> |
| * This method is automatically called by the team plugin shortly after |
| * participant construction. It marks the start of the views |
| * lifecycle. Clients must not call this method. |
| * </p> |
| * @param secondaryId the secondayId of this participant instance or <code>null</code> |
| * if this participant doesn't support multiple instances. |
| * @param memento the participant state or <code>null</code> if there |
| * is no previous saved state |
| * @exception PartInitException if this participant was not initialized |
| * successfully |
| */ |
| public void init(String secondaryId, IMemento memento) throws PartInitException; |
| |
| /** |
| * Disposes of this synchronize participant and is called to free the |
| * resources associated with a participant. When a participant is added |
| * to the {@link ISynchronizeManager} this method is called when the |
| * manager is shutdown or the participant is removed from the manager. |
| * <p> |
| * Within this method a participant may release any resources, fonts, images, etc. |
| * held by this part. It is also very important to remove all listeners. |
| * </p><p> |
| * Clients should not call this method (the synchronize manager calls this |
| * method at appropriate times). |
| * </p> |
| */ |
| public void dispose(); |
| |
| /** |
| * Saves the participants object state within the memento. This state |
| * will be available when the participant is restored via <code>init</code>. |
| * <p> |
| * This method can be called multiple times during the lifetime of the |
| * participant object. |
| * </p> |
| * @param memento a memento to receive the object state |
| */ |
| public void saveState(IMemento memento); |
| |
| /** |
| * Adds a listener for changes to properties of this synchronize |
| * participant. Has no effect if an identical listener is already |
| * registered. |
| * <p> |
| * The changes supported by the synchronize view are as follows: |
| * </p> |
| * <ul> |
| * <li><code>IBasicPropertyConstants.P_TEXT</code>- indicates the name |
| * of a synchronize participant has changed</li> |
| * <li><code>IBasicPropertyConstants.P_IMAGE</code>- indicates the |
| * image of a synchronize participant has changed</li> |
| * </ul> |
| * <p> |
| * Clients may define additional properties as required. |
| * </p> |
| * @param listener a property change listener |
| */ |
| public void addPropertyChangeListener(IPropertyChangeListener listener); |
| |
| /** |
| * Removes the given property listener from this synchronize participant. |
| * Has no effect if an identical listener is not already registered. |
| * |
| * @param listener a property listener |
| */ |
| public void removePropertyChangeListener(IPropertyChangeListener listener); |
| |
| /** |
| * Prepare the given element and compare configuration for use with a compare editor |
| * input. |
| * @param element the sync model element whose contents are about to be displayed to the user |
| * in a compare editor or compare dialog |
| * @param configuration the compare configuration that will be used to configure the compare editor or dialog |
| * @param monitor a progress monitor that can be used if contacting a server to prepare the element and configuration |
| * @throws TeamException if an error occurred that should prevent the display of the compare editor containing |
| * the element |
| * |
| * @since 3.1 |
| */ |
| public void prepareCompareInput( |
| ISynchronizeModelElement element, |
| CompareConfiguration configuration, |
| IProgressMonitor monitor) |
| throws TeamException; |
| |
| /** |
| * Return the list of preference pages that are associated with this participant |
| * @return the list of preference pages that are associated with this participant |
| * @since 3.1 |
| */ |
| public PreferencePage[] getPreferencePages(); |
| |
| /** |
| * Returns the help context id of this participant. |
| * |
| * @return the help context id of this participant |
| * @since 3.5 |
| */ |
| public String getHelpContextId(); |
| } |