org.eclipse.compare

## Class CompareConfiguration

- java.lang.Object
- - org.eclipse.compare.CompareConfiguration

    public class CompareConfiguration
    extends Object

A `CompareConfiguration` object controls various UI aspects of compare/merge viewers like title labels and images, or whether a side of a merge viewer is editable. In addition to these fixed properties `CompareConfiguration` provides API for an open ended set of properties. Different viewers which share the same configuration can communicate via this mechanism. E.g. if a compare editor has a button for controlling whether compare viewers ignore white space, the button would trigger a change of the boolean `IGNORE_WHITESPACE` property and all interested viewers would receive notification.

Suitable default labels are provided (without images); both the left and right sides are editable.

Clients may use this class as is, or subclass to add new state and behavior.

### Field Summary

Fields
`static String` `IGNORE_WHITESPACE` Name of the ignore whitespace property (value `"IGNORE_WHITESPACE"`).
`static String` `MIRRORED` Name of the mirrored property, i.e. if left input is shown on the right side and vice versa.
`static String` `SHOW_PSEUDO_CONFLICTS` Name of the show pseudo conflicts property (value `"SHOW_PSEUDO_CONFLICTS"`).
`static String` `USE_OUTLINE_VIEW` Name of the use outline view property (value `"USE_OUTLINE_VIEW"`).

### Constructor Summary

Constructors
Constructor and Description
`CompareConfiguration()` Creates a new configuration with editable left and right sides, suitable default labels, and no images.
`CompareConfiguration(IPreferenceStore prefStore)` Creates a new configuration with editable left and right sides, suitable default labels, and no images.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addPropertyChangeListener(IPropertyChangeListener listener)`
`void` `dispose()` Dispose of this compare configuration.
`Image` `getAncestorImage(Object element)` Returns the image for the ancestor side of compare/merge viewers.
`String` `getAncestorLabel(Object element)` Returns the label for the ancestor side of compare/merge viewers.
`ICompareContainer` `getContainer()` Return the container of the compare associated with this configuration.
`Image` `getImage(Image base, int kind)` Returns an image showing the specified change kind applied to a given base image.
`Image` `getImage(int kind)` Returns an image showing the specified change kind.
`ICompareInputLabelProvider` `getLabelProvider()` Return the label provider that is used to determine the text and labels return by this compare configuration.
`Image` `getLeftImage(Object element)` Returns the image for the left hand side of compare/merge viewers.
`String` `getLeftLabel(Object element)` Returns the label for the left hand side of compare/merge viewers.
`IPreferenceStore` `getPreferenceStore()` Returns the preference store of this configuration.
`Object` `getProperty(String key)` Returns the property with the given name, or `null` if no such property exists.
`Image` `getRightImage(Object element)` Returns the image for the right hand side of compare/merge viewers.
`String` `getRightLabel(Object element)` Returns the label for the right hand side of compare/merge viewers.
`boolean` `isChangeIgnored(int kind)` Return if a given change kind is ignored while computing differences between documents.
`boolean` `isLeftEditable()` Returns whether the left hand side of a merge viewer is editable.
`boolean` `isMirrored()` Only the views are mirrored.
`boolean` `isRightEditable()` Returns whether the right hand side of a merge viewer is editable.
`void` `removePropertyChangeListener(IPropertyChangeListener listener)`
`void` `setAncestorImage(Image image)` Sets the image to use for the ancestor of compare/merge viewers.
`void` `setAncestorLabel(String label)` Sets the label to use for the ancestor of compare/merge viewers.
`void` `setChangeIgnored(int kind, boolean ignored)` Set whether given change kind should be ignored while computing differences between documents.
`void` `setContainer(ICompareContainer container)` Set the container of the compare associated with this configuration.
`void` `setDefaultLabelProvider(ICompareInputLabelProvider labelProvider)` Set the default label provider for this configuration.
`void` `setLabelProvider(ICompareInput input, ICompareInputLabelProvider labelProvider)` Set the label provider for the given compare input.
`void` `setLeftEditable(boolean editable)` Controls whether the left side of a merge viewer is editable.
`void` `setLeftImage(Image image)` Sets the image to use for the left side of compare/merge viewers.
`void` `setLeftLabel(String label)` Sets the label to use for the left side of compare/merge viewers.
`void` `setProperty(String key, Object newValue)` Sets the property with the given name.
`void` `setRightEditable(boolean editable)` Controls whether the right side of a merge viewer is editable.
`void` `setRightImage(Image image)` Sets the image to use for the right side of compare/merge viewers.
`void` `setRightLabel(String label)` Sets the label to use for the right side of compare/merge viewers.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### IGNORE_WHITESPACE

    public static final String IGNORE_WHITESPACE

Name of the ignore whitespace property (value `"IGNORE_WHITESPACE"`).

See Also:
  Constant Field Values

#### SHOW_PSEUDO_CONFLICTS

    public static final String SHOW_PSEUDO_CONFLICTS

Name of the show pseudo conflicts property (value `"SHOW_PSEUDO_CONFLICTS"`).

See Also:
  Constant Field Values

#### USE_OUTLINE_VIEW

    public static final String USE_OUTLINE_VIEW

Name of the use outline view property (value `"USE_OUTLINE_VIEW"`).

Since:
  3.0
See Also:
  Constant Field Values

#### MIRRORED

    public static final String MIRRORED

Name of the mirrored property, i.e. if left input is shown on the right side and vice versa.

Since:
  3.7
See Also:
  Constant Field Values

### Constructor Detail

#### CompareConfiguration

    public CompareConfiguration(IPreferenceStore prefStore)

Creates a new configuration with editable left and right sides, suitable default labels, and no images. The given preference store is used to connect this configuration with the Compare preference page properties `ComparePreferencePage.INITIALLY_SHOW_ANCESTOR_PANE`, `CompareConfiguration.IGNORE_WHITESPACE` and `MIRRORED`

Parameters:
  `prefStore` - the preference store which this configuration holds onto.
Since:
  2.0

#### CompareConfiguration

    public CompareConfiguration()

Creates a new configuration with editable left and right sides, suitable default labels, and no images. This configuration uses the preference store of the Compare plug-in (`CompareUIPlugin.getDefault().getPreferenceStore()`).

### Method Detail

#### getPreferenceStore

    public IPreferenceStore getPreferenceStore()

Returns the preference store of this configuration.

Returns:
  the preference store of this configuration.
Since:
  2.0

#### getImage

    public Image getImage(int kind)

Returns an image showing the specified change kind. The different kind of changes are defined in the `Differencer`. Newly created images are remembered by this class and disposed when the `dispose` method is called.

Parameters:
  `kind` - the kind of change as defined in `Differencer`.
Returns:
  an modification of the base image reflecting the kind of change or `null` if there is no image descriptor registered for given id.
Since:
  2.0
See Also:
  `Differencer`

#### getImage

    public Image getImage(Image base,
                          int kind)

Returns an image showing the specified change kind applied to a given base image. The different kind of changes are defined in the `Differencer`. Typically an implementation would build a composite image from the given base image and an image representing the change kind. Newly created images are remembered by this class and disposed when the `dispose` method is called.

Parameters:
  `base` - the image which is modified to reflect the kind of change
  `kind` - the kind of change as defined in `Differencer`.
Returns:
  an modification of the base image reflecting the kind of change.
See Also:
  `Differencer`

#### isMirrored

    public boolean isMirrored()

Only the views are mirrored. All model values for left and right are not changed!

Returns:
  true if the left and right side of the viewer are mirrored. Default is false.
Since:
  3.7

#### dispose

    public void dispose()

Dispose of this compare configuration. This method is called if the compare configuration is no longer used. An implementation must dispose of all resources.

#### addPropertyChangeListener

    public void addPropertyChangeListener(IPropertyChangeListener listener)

#### removePropertyChangeListener

    public void removePropertyChangeListener(IPropertyChangeListener listener)

#### setProperty

    public void setProperty(String key,
                            Object newValue)

Sets the property with the given name. If the new value differs from the old a `PropertyChangeEvent` is sent to registered listeners.

Parameters:
  `key` - the name of the property to set
  `newValue` - the new value of the property

#### getProperty

    public Object getProperty(String key)

Returns the property with the given name, or `null` if no such property exists.

Parameters:
  `key` - the name of the property to retrieve
Returns:
  the property with the given name, or `null` if not found

#### setAncestorLabel

    public void setAncestorLabel(String label)

Sets the label to use for the ancestor of compare/merge viewers. This label will be used if the element for which a label is requested does not have an ancestor or the element does not have a registered label provider or the label provider returns `null` as the label.

Parameters:
  `label` - the new label for the ancestor of compare/merge viewers

#### getAncestorLabel

    public String getAncestorLabel(Object element)

Returns the label for the ancestor side of compare/merge viewers. This label is typically shown in the title of the ancestor area in a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the label for the ancestor side or `null`

#### setAncestorImage

    public void setAncestorImage(Image image)

Sets the image to use for the ancestor of compare/merge viewers. The CompareConfiguration does not automatically dispose the old image. This image will be used if the element for which a image is requested does not have an ancestor or the element does not have a registered label provider or the label provider returns `null` as the image.

Parameters:
  `image` - the new image for the ancestor of compare/merge viewers

#### getAncestorImage

    public Image getAncestorImage(Object element)

Returns the image for the ancestor side of compare/merge viewers. This image is typically shown in the title of the ancestor area in a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the image for the ancestor side or `null`

#### setLeftEditable

    public void setLeftEditable(boolean editable)

Controls whether the left side of a merge viewer is editable.

Parameters:
  `editable` - if the value is `true` left side is editable

#### isLeftEditable

    public boolean isLeftEditable()

Returns whether the left hand side of a merge viewer is editable.

Returns:
  `true` if the left hand side is editable

#### setLeftLabel

    public void setLeftLabel(String label)

Sets the label to use for the left side of compare/merge viewers. This label will be used if the element for which a label is requested does not have a left contributor or the element does not have a registered label provider or the label provider returns `null` as the label.

Parameters:
  `label` - the new label for the left side of compare/merge viewers

#### getLeftLabel

    public String getLeftLabel(Object element)

Returns the label for the left hand side of compare/merge viewers. This label is typically shown in the title of the left side of a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the label for the left hand side or `null`

#### setLeftImage

    public void setLeftImage(Image image)

Sets the image to use for the left side of compare/merge viewers. The compare configuration does not automatically dispose the old image. This image will be used if the element for which a image is requested does not have an left contributor or the element does not have a registered label provider or the label provider returns `null` as the image.

Parameters:
  `image` - the new image for the left side of compare/merge viewers

#### getLeftImage

    public Image getLeftImage(Object element)

Returns the image for the left hand side of compare/merge viewers. This image is typically shown in the title of the left side of a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the image for the left hand side or `null`

#### setRightEditable

    public void setRightEditable(boolean editable)

Controls whether the right side of a merge viewer is editable.

Parameters:
  `editable` - if the value is `true` right side is editable

#### isRightEditable

    public boolean isRightEditable()

Returns whether the right hand side of a merge viewer is editable.

Returns:
  `true` if the right hand side is editable

#### setRightLabel

    public void setRightLabel(String label)

Sets the label to use for the right side of compare/merge viewers. This label will be used if the element for which a label is requested does not have an right contributor or the element does not have a registered label provider or the label provider returns `null` as the label.

Parameters:
  `label` - the new label for the right side of compare/merge viewers

#### getRightLabel

    public String getRightLabel(Object element)

Returns the label for the right hand side of compare/merge viewers. This label is typically shown in the title of the right side of a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the label for the right hand side or `null`

#### setRightImage

    public void setRightImage(Image image)

Sets the image to use for the right side of compare/merge viewers. The compare configuration does not automatically dispose the old image. This image will be used if the element for which a image is requested does not have an right contributor or the element does not have a registered label provider or the label provider returns `null` as the image.

Parameters:
  `image` - the new image for the right side of compare/merge viewers

#### getRightImage

    public Image getRightImage(Object element)

Returns the image for the right hand side of compare/merge viewers. This image is typically shown in the title of the right side of a compare viewer.

Parameters:
  `element` - the input object of a compare/merge viewer or `null`
Returns:
  the image for the right hand side or `null`

#### getContainer

    public ICompareContainer getContainer()

Return the container of the compare associated with this configuration.

Returns:
  the container of the compare associated with this configuration
Since:
  3.3

#### setContainer

    public void setContainer(ICompareContainer container)

Set the container of the compare associated with this configuration.

Parameters:
  `container` - the container of the compare associated with this configuration.
Since:
  3.3

#### getLabelProvider

    public ICompareInputLabelProvider getLabelProvider()

Return the label provider that is used to determine the text and labels return by this compare configuration.

Returns:
  the label provider that is used to determine the text and labels return by this compare configuration
Since:
  3.3
See Also:
  `getAncestorImage(Object)`, `getAncestorLabel(Object)`, `getLeftImage(Object)`, `getLeftLabel(Object)`, `getRightImage(Object)`, `getRightLabel(Object)`

#### setLabelProvider

    public void setLabelProvider(ICompareInput input,
                                 ICompareInputLabelProvider labelProvider)

Set the label provider for the given compare input. The compare configuration will not dispose of the label provider when the configuration is disposed. It is up to the provider of the label provider to ensure that it is disposed when it is no longer needed.

Parameters:
  `input` - the compare input
  `labelProvider` - the label provider for the compare input
Since:
  3.3

#### setDefaultLabelProvider

    public void setDefaultLabelProvider(ICompareInputLabelProvider labelProvider)

Set the default label provider for this configuration. The default label provider is used when a particular label provider has not been assigned using `setLabelProvider(ICompareInput, ICompareInputLabelProvider)`. The compare configuration will not dispose of the label provider when the configuration is disposed. It is up to the provider of the label provider to ensure that it is disposed when it is no longer needed.

Parameters:
  `labelProvider` - the default label provider
Since:
  3.3

#### setChangeIgnored

    public void setChangeIgnored(int kind,
                                 boolean ignored)

Set whether given change kind should be ignored while computing differences between documents. Changes specified by this method will be excluded from a comparison result.

Parameters:
  `kind` - type of change, possible values are: `RangeDifference.CHANGE` `RangeDifference.CONFLICT` `RangeDifference.RIGHT` `RangeDifference.LEFT` `RangeDifference.ANCESTOR` `RangeDifference.ERROR`
  `ignored` - whether given kind should be included in the ignored set
Since:
  3.5

#### isChangeIgnored

    public boolean isChangeIgnored(int kind)

Return if a given change kind is ignored while computing differences between documents.

Parameters:
  `kind` - type of change, possible values are: `RangeDifference.CHANGE` `RangeDifference.CONFLICT` `RangeDifference.RIGHT` `RangeDifference.LEFT` `RangeDifference.ANCESTOR` `RangeDifference.ERROR`
Returns:
  whether kind of change is ignored
Since:
  3.5