org.eclipse.team.ui.synchronize
Interface ISynchronizeParticipant
-
All Superinterfaces:
-
IAdaptable,
IExecutableExtension
-
All Known Implementing Classes:
-
AbstractSynchronizeParticipant,
ModelSynchronizeParticipant,
SubscriberParticipant
-
public interface ISynchronizeParticipant
- extends
IExecutableExtension,
IAdaptable
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.
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.
A participant can display multiple instances of its synchronization state to the user via the creation
of a page
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. That is possible by
When a participant is registered with the
ISynchronizeManager it will automatically display
in the Synchronize View and if the participant extension point
enabled synchronizeWizards it will also appear in the global synchronize action
toolbar.
A participant is added to the workbench as follows:
- A
synchronizeParticipant extension is contributed to
the team registry. This extension defines the participant id, name, icon, type, and
participant class.
- A user via a wizard provided by the
synchronizeWizards extension point
or client code, creates a participant instance and registers it with the
synchronize manager. It then appears in the synchronize view.
- A synchronization can be persistent and thus re-initialized at startup.
- A pinned participant will only be removed from the synchronize manager if it is un-pinned.
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 saveState() method. At startup the init() 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.
-
Since:
- 3.0
-
See Also:
-
ISynchronizeView,
ISynchronizeManager,
AbstractSynchronizeParticipant
-
Restriction:
- Clients are not intended to implement this interface. Instead,
subclass
AbstractSynchronizeParticipant.
|
Field Summary
|
static
String
|
P_CONTENT
A property constant that can be used to indicate that the content of this participant
has changed. |
P_CONTENT
static final
String P_CONTENT
- 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 Also:
-
addPropertyChangeListener(IPropertyChangeListener),
Constant Field Values
getId
String getId()
- Returns the unique id that identified the type of this
synchronize participant. The synchronize manager supports registering
several instances of the same participant type.
-
-
-
Returns:
- the unique id that identified the type of this
synchronize participant.
getSecondaryId
String getSecondaryId()
- 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.
-
-
-
Returns:
- the instance id that identified the unique instance of this
participant or
null if this participant doesn't support
multiple instances.
getName
String getName()
- Returns the name of this synchronize participant. This name is displayed to the user.
-
-
-
Returns:
- the name of this synchronize participant
getImageDescriptor
ImageDescriptor getImageDescriptor()
- Returns an image descriptor for this synchronize participant, or
null
if none.
-
-
-
Returns:
- an image descriptor for this synchronize participant, or
null
if none
isPinned
boolean isPinned()
- Returns if this participant is pinned. Pinned participants will only be removed from the
synchronize manager until they are un-pinned.
-
-
-
Returns:
-
true if this participant is pinned and false
otherwise.
setPinned
void setPinned(boolean pinned)
- Sets whether this participant is pinned.
-
-
-
Parameters:
-
pinned - sets if the participant is pinned.
createPageConfiguration
ISynchronizePageConfiguration createPageConfiguration()
- Creates the configuration for the participant page. The configuration controls the
options for displaying the participant. The configuration used to initialize the page
when
createPage(ISynchronizePageConfiguration) is called and as such
can be used to pre-configure visual properties of the displayed page.
-
-
-
Returns:
- the configuration for the participant page.
createPage
IPageBookViewPage createPage(
ISynchronizePageConfiguration configuration)
- 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
ISynchronizePageSite.
-
-
-
Parameters:
-
configuration - used to initialize the page
-
Returns:
- a page book view page representation of this synchronize
participant
run
void run(
IWorkbenchPart part)
- 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.
-
-
-
Parameters:
-
part - the part in which the action is run or null if the action
is not being run in a workbench part.
init
void init(
String secondaryId,
IMemento memento)
throws
PartInitException
- 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.
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.
-
-
-
Parameters:
-
secondaryId - the secondayId of this participant instance or null
if this participant doesn't support multiple instances. -
memento - the participant state or null if there
is no previous saved state
-
Throws:
-
PartInitException
- if this participant was not initialized
successfully
dispose
void dispose()
- Disposes of this synchronize participant and is called to free the
resources associated with a participant. When a participant is added
to the
ISynchronizeManager this method is called when the
manager is shutdown or the participant is removed from the manager.
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.
Clients should not call this method (the synchronize manager calls this
method at appropriate times).
-
-
saveState
void saveState(
IMemento memento)
- Saves the participants object state within the memento. This state
will be available when the participant is restored via
init.
This method can be called multiple times during the lifetime of the
participant object.
-
-
-
Parameters:
-
memento - a memento to receive the object state
addPropertyChangeListener
void addPropertyChangeListener(
IPropertyChangeListener listener)
- Adds a listener for changes to properties of this synchronize
participant. Has no effect if an identical listener is already
registered.
The changes supported by the synchronize view are as follows:
-
IBasicPropertyConstants.P_TEXT- indicates the name
of a synchronize participant has changed
-
IBasicPropertyConstants.P_IMAGE- indicates the
image of a synchronize participant has changed
Clients may define additional properties as required.
-
-
-
Parameters:
-
listener - a property change listener
removePropertyChangeListener
void removePropertyChangeListener(
IPropertyChangeListener listener)
- Removes the given property listener from this synchronize participant.
Has no effect if an identical listener is not already registered.
-
-
-
Parameters:
-
listener - a property listener
prepareCompareInput
void prepareCompareInput(
ISynchronizeModelElement element,
CompareConfiguration configuration,
IProgressMonitor monitor)
throws
TeamException
- Prepare the given element and compare configuration for use with a compare editor
input.
-
-
-
Parameters:
-
element - the sync model element whose contents are about to be displayed to the user
in a compare editor or compare dialog -
configuration - the compare configuration that will be used to configure the compare editor or dialog -
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
getPreferencePages
PreferencePage[] getPreferencePages()
- Return the list of preference pages that are associated with this participant
-
-
-
Returns:
- the list of preference pages that are associated with this participant
-
Since:
- 3.1
getHelpContextId
String getHelpContextId()
- Returns the help context id of this participant.
-
-
-
Returns:
- the help context id of this participant
-
Since:
- 3.5
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
