Eclipse Plug-in Developer Guide (Galileo) - ContentMergeViewer (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.compare.contentmergeviewer
Class ContentMergeViewer


java.lang.Object
  

org.eclipse.jface.viewers.Viewer
      

org.eclipse.jface.viewers.ContentViewer
          
org.eclipse.compare.contentmergeviewer.ContentMergeViewer

All Implemented Interfaces:: IFlushable, IPropertyChangeNotifier, IInputProvider, IInputSelectionProvider, ISelectionProvider

Direct Known Subclasses:: TextMergeViewer

public abstract class ContentMergeViewer
extends ContentViewer
implements IPropertyChangeNotifier, IFlushable
extends ContentViewer
implements IPropertyChangeNotifier, IFlushable

An abstract compare and merge viewer with two side-by-side content areas and an optional content area for the ancestor. The implementation makes no assumptions about the content type.

ContentMergeViewer

implements the overall layout and defines hooks so that subclasses can easily provide an implementation for a specific content type,
implements the UI for making the areas resizable,
has an action for controlling whether the ancestor area is visible or not,
has actions for copying one side of the input to the other side,
tracks the dirty state of the left and right sides and send out notification on state changes.

A ContentMergeViewer accesses its model by means of a content provider which must implement the IMergeViewerContentProvider interface.

Clients may wish to use the standard concrete subclass TextMergeViewer, or define their own subclass.

See Also:: IMergeViewerContentProvider, TextMergeViewer

Field Summary

Fields inherited from class org.eclipse.jface.viewers. Viewer

WIDGET_DATA_KEY

Constructor Summary

protected ContentMergeViewer (int style, ResourceBundle bundle, CompareConfiguration cc)
          Creates a new content merge viewer and initializes with a resource bundle and a configuration.

Method Summary

void addPropertyChangeListener ( IPropertyChangeListener listener)
          Adds a listener for property changes to this notifier.

protected Control buildControl ( Composite parent)
          Builds the SWT controls for the three areas of a compare/merge viewer.

protected abstract void copy (boolean leftToRight)
          Copies the content of one side to the other side.

protected Control createCenterControl ( Composite parent)
          Create the control that divides the left and right sides of the merge viewer.

protected abstract void createControls ( Composite composite)
          Creates the SWT controls for the ancestor, left, and right content areas of this compare viewer.

protected void createToolItems ( ToolBarManager toolBarManager)
          Contributes items to the given ToolBarManager.

protected boolean doSave ( Object newInput, Object oldInput)
          This method is called from the Viewer method inputChanged to save any unsaved changes of the old input.

void flush ( IProgressMonitor monitor)
          Flush any modifications made in the viewer into the compare input.

protected void flushContent ( Object input, IProgressMonitor monitor)
          Flush the modified content back to input elements via the content provider.

protected Control getCenterControl ()
          Return the center control that divides the left and right sides of the merge viewer.

protected int getCenterWidth ()
          Return the desired width of the center control.

protected CompareConfiguration getCompareConfiguration ()
          Returns the compare configuration of this viewer, or null if this viewer does not yet have a configuration.

protected abstract byte[] getContents (boolean left)
          Returns the byte contents of the left or right side.

Control getControl ()
          Returns the primary control associated with this viewer.

protected ResourceBundle getResourceBundle ()
          Returns the resource bundle of this viewer.

ISelection getSelection ()
          The ContentMergeViewer implementation of this Viewer method returns the empty selection.

String getTitle ()
          Returns the viewer's name.

protected IToolBarManager getToolBarManager ( Composite parent)
          Returns the toolbar manager for this viewer.

protected void handleCompareInputChange ()
          Handle a change to the given input reported from an ICompareInputChangeListener.

protected void handleDispose ( DisposeEvent event)
          Called on the viewer disposal.

protected void handlePropertyChangeEvent ( PropertyChangeEvent event)
          Callback that is invoked when a property in the compare configuration ( getCompareConfiguration() changes.

protected abstract void handleResizeAncestor (int x, int y, int width, int height)
          Lays out the ancestor area of the compare viewer.

protected abstract void handleResizeLeftRight (int x, int y, int leftWidth, int centerWidth, int rightWidth, int height)
          Lays out the left and right areas of the compare viewer.

protected boolean handleSetFocus ()
          Callback that is invoked when the control of this merge viewer is given focus.

protected void inputChanged ( Object input, Object oldInput)
          Internal hook method called when the input to this viewer is initially set or subsequently changed.

protected boolean isAncestorVisible ()
          Return whether the ancestor pane is visible or not.

protected boolean isLeftDirty ()
          Return the dirty state of the left side of this viewer.

protected boolean isRightDirty ()
          Return the dirty state of the right side of this viewer.

protected boolean isThreeWay ()
          Return whether the input is a three-way comparison.

void refresh ()
          Refreshes this viewer completely with information freshly obtained from this viewer's model.

void removePropertyChangeListener ( IPropertyChangeListener listener)
          Removes the given content change listener from this notifier.

void save ( IProgressMonitor monitor)
          Deprecated. use IFlushable.flush(IProgressMonitor).

void setConfirmSave (boolean enable)
          Controls whether doSave(Object, Object) asks for confirmation before saving the old input with saveContent(Object).

void setContentProvider ( IContentProvider contentProvider)
          The ContentMergeViewer implementation of this ContentViewer method checks to ensure that the content provider is an IMergeViewerContentProvider.

protected void setLeftDirty (boolean dirty)
          Sets the dirty state of the left side of this viewer.

protected void setRightDirty (boolean dirty)
          Sets the dirty state of the right side of this viewer.

void setSelection ( ISelection selection, boolean reveal)
          The ContentMergeViewer implementation of this Viewer method does nothing.

protected abstract void updateContent ( Object ancestor, Object left, Object right)
          Initializes the controls of the three content areas with the given input objects.

protected void updateHeader ()
          Updates the headers of the three areas by querying the content provider for a name and image for the three sides of the input object.

protected void updateToolItems ()
          Updates the enabled state of the toolbar items.

Methods inherited from class org.eclipse.jface.viewers. ContentViewer

getContentProvider, getInput, getLabelProvider, handleLabelProviderChanged, hookControl, labelProviderChanged, setInput, setLabelProvider

Methods inherited from class org.eclipse.jface.viewers. Viewer

addHelpListener, addSelectionChangedListener, fireHelpRequested, fireSelectionChanged, getData, handleHelpRequest, removeHelpListener, removeSelectionChangedListener, scrollDown, scrollUp, setData, setSelection

Methods inherited from class java.lang. Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContentMergeViewer

protected ContentMergeViewer(int style,
                             
ResourceBundle bundle,
                             
CompareConfiguration cc)

Creates a new content merge viewer and initializes with a resource bundle and a configuration.

Parameters:: style - SWT style bits; bundle - the resource bundle; cc - the configuration object

Method Detail

getTitle

public 
String getTitle()

Returns the viewer's name.

Returns:: the viewer's name

createControls

protected abstract void createControls(
Composite composite)

Creates the SWT controls for the ancestor, left, and right content areas of this compare viewer. Implementations typically hold onto the controls so that they can be initialized with the input objects in method updateContent.

Parameters:: composite - the container for the three areas

handleResizeAncestor

protected abstract void handleResizeAncestor(int x,
                                             int y,
                                             int width,
                                             int height)

Lays out the ancestor area of the compare viewer. It is called whenever the viewer is resized or when the sashes between the areas are moved to adjust the size of the areas.

Parameters:: x - the horizontal position of the ancestor area within its container; y - the vertical position of the ancestor area within its container; width - the width of the ancestor area; height - the height of the ancestor area

handleResizeLeftRight

protected abstract void handleResizeLeftRight(int x,
                                              int y,
                                              int leftWidth,
                                              int centerWidth,
                                              int rightWidth,
                                              int height)

Lays out the left and right areas of the compare viewer. It is called whenever the viewer is resized or when the sashes between the areas are moved to adjust the size of the areas.

Parameters:: x - the horizontal position of the left area within its container; y - the vertical position of the left and right area within its container; leftWidth - the width of the left area; centerWidth - the width of the gap between the left and right areas; rightWidth - the width of the right area; height - the height of the left and right areas

createToolItems

protected void createToolItems(
ToolBarManager toolBarManager)

Contributes items to the given ToolBarManager. It is called when this viewer is installed in its container and if the container has a ToolBarManager. The ContentMergeViewer implementation of this method does nothing. Subclasses may reimplement.

Parameters:: toolBarManager - the toolbar manager to contribute to

updateContent

protected abstract void updateContent(
Object ancestor,
                                      
Object left,
                                      
Object right)

Initializes the controls of the three content areas with the given input objects.

Parameters:: ancestor - the input for the ancestor area; left - the input for the left area; right - the input for the right area

copy

protected abstract void copy(boolean leftToRight)

Copies the content of one side to the other side. Called from the (internal) actions for copying the sides of the viewer's input object.

Parameters:: leftToRight - if true, the left side is copied to the right side; if false, the right side is copied to the left side

getContents

protected abstract byte[] getContents(boolean left)

Returns the byte contents of the left or right side. If the viewer has no editable content null can be returned.

Parameters:: left - if true, the byte contents of the left area is returned; if false, the byte contents of the right area
Returns:: the content as an array of bytes, or null

getResourceBundle

protected 
ResourceBundle getResourceBundle()

Returns the resource bundle of this viewer.

Returns:: the resource bundle

getCompareConfiguration

protected 
CompareConfiguration getCompareConfiguration()

Returns the compare configuration of this viewer, or null if this viewer does not yet have a configuration.

Returns:: the compare configuration, or null if none

setContentProvider

public void setContentProvider(
IContentProvider contentProvider)

The ContentMergeViewer implementation of this ContentViewer method checks to ensure that the content provider is an IMergeViewerContentProvider.

Overrides:: setContentProvider in class ContentViewer

Parameters:: contentProvider - the content provider to set. Must implement IMergeViewerContentProvider.
See Also:: ContentViewer.getContentProvider()

getSelection

public 
ISelection getSelection()

The ContentMergeViewer implementation of this Viewer method returns the empty selection. Subclasses may override.

Specified by:: getSelection in interface ISelectionProvider
Specified by:: getSelection in class Viewer

Returns:: empty selection.

setSelection

public void setSelection(
ISelection selection,
                         boolean reveal)

The ContentMergeViewer implementation of this Viewer method does nothing. Subclasses may reimplement.

Specified by:: setSelection in class Viewer

Parameters:: selection - the new selection; reveal - true if the selection is to be made visible, and false otherwise
See Also:: Viewer.setSelection(org.eclipse.jface.viewers.ISelection, boolean)

handlePropertyChangeEvent

protected void handlePropertyChangeEvent(
PropertyChangeEvent event)

Callback that is invoked when a property in the compare configuration ( getCompareConfiguration() changes.

Parameters:: event - the property change event
Since:: 3.3

isThreeWay

protected boolean isThreeWay()

Return whether the input is a three-way comparison.

Returns:: whether the input is a three-way comparison
Since:: 3.3

inputChanged

protected final void inputChanged(
Object input,
                                  
Object oldInput)

Internal hook method called when the input to this viewer is initially set or subsequently changed.

The ContentMergeViewer implementation of this Viewer method tries to save the old input by calling doSave(...) and then calls internalRefresh(...).

Overrides:: inputChanged in class Viewer

Parameters:: input - the new input of this viewer, or null if there is no new input; oldInput - the old input element, or null if there was previously no input

doSave

protected boolean doSave(
Object newInput,
                         
Object oldInput)

This method is called from the Viewer method inputChanged to save any unsaved changes of the old input.

The ContentMergeViewer implementation of this method calls saveContent(...). If confirmation has been turned on with setConfirmSave(true), a confirmation alert is posted before saving.

Clients can override this method and are free to decide whether they want to call the inherited method.

Parameters:: newInput - the new input of this viewer, or null if there is no new input; oldInput - the old input element, or null if there was previously no input
Returns:: true if saving was successful, or if the user didn't want to save (by pressing 'NO' in the confirmation dialog).
Since:: 2.0

setConfirmSave

public void setConfirmSave(boolean enable)

Controls whether doSave(Object, Object) asks for confirmation before saving the old input with saveContent(Object).

Parameters:: enable - a value of true enables confirmation
Since:: 2.0

refresh

public void refresh()

Description copied from class: Viewer

Refreshes this viewer completely with information freshly obtained from this viewer's model.

Specified by:: refresh in class Viewer

buildControl

protected final 
Control buildControl(
Composite parent)

Builds the SWT controls for the three areas of a compare/merge viewer.

Calls the hooks createControls and createToolItems to let subclasses build the specific content areas and to add items to an enclosing toolbar.

This method must only be called in the constructor of subclasses.

Parameters:: parent - the parent control
Returns:: the new control

getToolBarManager

protected 
IToolBarManager getToolBarManager(
Composite parent)

Returns the toolbar manager for this viewer. Subclasses may extend this method and use either the toolbar manager provided by the inherited method by calling super.getToolBarManager(parent) or provide an alternate toolbar manager.

Parameters:: parent - a Composite or null
Returns:: a IToolBarManager
Since:: 3.4

handleSetFocus

protected boolean handleSetFocus()

Callback that is invoked when the control of this merge viewer is given focus. This method should return true if a particular widget was given focus and false otherwise. By default, false is returned. Subclasses may override.

Returns:: whether particular widget was given focus
Since:: 3.3

getCenterWidth

protected int getCenterWidth()

Return the desired width of the center control. This width is used to calculate the values used to layout the ancestor, left and right sides.

Returns:: the desired width of the center control
Since:: 3.3
See Also:: handleResizeLeftRight(int, int, int, int, int, int), handleResizeAncestor(int, int, int, int)

isAncestorVisible

protected boolean isAncestorVisible()

Return whether the ancestor pane is visible or not.

Returns:: whether the ancestor pane is visible or not
Since:: 3.3

createCenterControl

protected 
Control createCenterControl(
Composite parent)

Create the control that divides the left and right sides of the merge viewer.

Parameters:: parent - the parent composite
Returns:: the center control
Since:: 3.3

getCenterControl

protected 
Control getCenterControl()

Return the center control that divides the left and right sides of the merge viewer. This method returns the control that was created by calling createCenterControl(Composite).

Returns:: the center control
Since:: 3.3
See Also:: createCenterControl(Composite)

getControl

public 
Control getControl()

Description copied from class: Viewer

Returns the primary control associated with this viewer.

Specified by:: getControl in class Viewer

Returns:: the SWT control which displays this viewer's content

handleDispose

protected void handleDispose(
DisposeEvent event)

Called on the viewer disposal. Unregisters from the compare configuration. Clients may extend if they have to do additional cleanup.

Overrides:: handleDispose in class ContentViewer

Parameters:: event - a dispose event
See Also:: ContentViewer.handleDispose(org.eclipse.swt.events.DisposeEvent)

updateToolItems

protected void updateToolItems()

Updates the enabled state of the toolbar items.

This method is called whenever the state of the items needs updating.

Subclasses may extend this method, although this is generally not required.

updateHeader

protected void updateHeader()

Updates the headers of the three areas by querying the content provider for a name and image for the three sides of the input object.

This method is called whenever the header must be updated.

Subclasses may extend this method, although this is generally not required.

addPropertyChangeListener

public void addPropertyChangeListener(
IPropertyChangeListener listener)

Description copied from interface: IPropertyChangeNotifier

Adds a listener for property changes to this notifier. Has no effect if an identical listener is already registered.

Specified by:: addPropertyChangeListener in interface IPropertyChangeNotifier

Parameters:: listener - a property change listener

removePropertyChangeListener

public void removePropertyChangeListener(
IPropertyChangeListener listener)

Description copied from interface: IPropertyChangeNotifier

Removes the given content change listener from this notifier. Has no effect if the identical listener is not registered.

Specified by:: removePropertyChangeListener in interface IPropertyChangeNotifier

Parameters:: listener - a property change listener

setLeftDirty

protected void setLeftDirty(boolean dirty)

Sets the dirty state of the left side of this viewer. If the new value differs from the old all registered listener are notified with a PropertyChangeEvent with the property name CompareEditorInput.DIRTY_STATE.

Parameters:: dirty - the state of the left side dirty flag

setRightDirty

protected void setRightDirty(boolean dirty)

Sets the dirty state of the right side of this viewer. If the new value differs from the old all registered listener are notified with a PropertyChangeEvent with the property name CompareEditorInput.DIRTY_STATE.

Parameters:: dirty - the state of the right side dirty flag

save

public void save(
IProgressMonitor monitor)
          throws 
CoreException

Deprecated. use IFlushable.flush(IProgressMonitor).

Method from the old internal ISavable interface Save the viewers's content. Note: this method is for internal use only. Clients should not call this method.

Parameters:: monitor - a progress monitor
Throws:: CoreException

flush

public final void flush(
IProgressMonitor monitor)

Flush any modifications made in the viewer into the compare input. This method calls flushContent(Object, IProgressMonitor) with the compare input of the viewer as the first parameter.

Specified by:: flush in interface IFlushable

Parameters:: monitor - a progress monitor
Since:: 3.3
See Also:: IFlushable.flush(org.eclipse.core.runtime.IProgressMonitor)

flushContent

protected void flushContent(
Object input,
                            
IProgressMonitor monitor)

Flush the modified content back to input elements via the content provider. The provided input may be the current input of the viewer or it may be the previous input (i.e. this method may be called to flush modified content during an input change).

Parameters:: input - the compare input; monitor - a progress monitor or null if the method was call from a place where a progress monitor was not available.
Since:: 3.3

isRightDirty

protected boolean isRightDirty()

Return the dirty state of the right side of this viewer.

Returns:: the dirty state of the right side of this viewer
Since:: 3.3

isLeftDirty

protected boolean isLeftDirty()

Return the dirty state of the left side of this viewer.

Returns:: the dirty state of the left side of this viewer
Since:: 3.3

handleCompareInputChange

protected void handleCompareInputChange()

Handle a change to the given input reported from an ICompareInputChangeListener. This class registers a listener with its input and reports any change events through this method. By default, this method prompts for any unsaved changes and then refreshes the viewer. Subclasses may override.

Since:: 3.3

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.compare.contentmergeviewer Class ContentMergeViewer

ContentMergeViewer

getTitle

createControls

handleResizeAncestor

handleResizeLeftRight

createToolItems

updateContent

copy

getContents

getResourceBundle

getCompareConfiguration

setContentProvider

getSelection

setSelection

handlePropertyChangeEvent

isThreeWay

inputChanged

doSave

setConfirmSave

refresh

buildControl

getToolBarManager

handleSetFocus

getCenterWidth

isAncestorVisible

createCenterControl

getCenterControl

getControl

handleDispose

updateToolItems

updateHeader

addPropertyChangeListener

removePropertyChangeListener

setLeftDirty

setRightDirty

save

flush

flushContent

isRightDirty

isLeftDirty

handleCompareInputChange

org.eclipse.compare.contentmergeviewer
Class ContentMergeViewer