DataViewer

All Superinterfaces:

EventPublisher

All Known Subinterfaces:

DisplayWindow

All Known Implementing Classes:

AbstractDataViewer
```
public interface DataViewer
extends EventPublisher
```
General interface for any user interface displaying image data. Implementers: Normally, you should subclass AbstractDataViewer rather than directly implementing this interface. That will allow your implementation to continue to work when methods are added to this interface in the future.
Warning: Support for custom data viewers is experimental. Future updates may require you to update such code for compatibility.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addListener(DataViewerListener listener, int priority)` Listeners will be notified of important events of the DataViewer
`boolean`	`compareAndSetDisplayPosition(Coords originalPosition, Coords newPosition)` Set the display position only if the current position is the expected one.
`boolean`	`compareAndSetDisplayPosition(Coords originalPosition, Coords newPosition, boolean forceRedisplay)` Set the display position only if the current position is the expected one.
`boolean`	`compareAndSetDisplaySettings(DisplaySettings originalSettings, DisplaySettings newSettings)` Set the display settings only if the current settings match the expected one.
`DataProvider`	`getDataProvider()` Retrieve the data provider backing this viewer.
`Datastore`	`getDatastore()` Deprecated. use `getDataProvider()` instead
`java.util.List<Image>`	`getDisplayedImages()` Retrieve the Images currently being displayed.
`Coords`	`getDisplayPosition()` Get the coordinates for the currently displayed images.
`DisplaySettings`	`getDisplaySettings()` Get the current display settings.
`java.lang.String`	`getName()` Return the name of this viewer.
`boolean`	`isClosed()` Return true if this viewer has been closed.
`boolean`	`isVisible()` Return true if this viewer is visible.
`void`	`registerForEvents(java.lang.Object recipient)` Register an object to receive events on the viewer event bus.
`void`	`removeListener(DataViewerListener listener)` No longer notify this listener
`void`	`setDisplayedImageTo(Coords position)` Deprecated. use `setDisplayPosition(Coords)` instead
`void`	`setDisplayPosition(Coords position)` Display the images at the specified coordinates in the data provider.
`void`	`setDisplayPosition(Coords position, boolean forceRedisplay)` Display the images at the specified coordinates in the data provider.
`void`	`setDisplaySettings(DisplaySettings settings)` Set the display settings.
`void`	`unregisterForEvents(java.lang.Object recipient)` Unregister an object from the viewer event bus.

- Method Detail
  - registerForEvents
```
void registerForEvents(java.lang.Object recipient)
```
    Register an object to receive events on the viewer event bus.
    Objects registered by this method will receive viewer events through their methods bearing a com.google.common.eventbus.Subscribe annotation. See Guava Event Bus documentation for how this works.
    Events that can be subscribed to include:
    - DisplaySettingsChangedEvent (on an arbitrary thread)
    - DisplayPositionChangedEvent (on an arbitrary thread)
    - TODO DisplayPositionRenderedEvent (on the EDT)
    - TODO DataViewerClosedEvent (on the EDT)
    Specified by:
    
    registerForEvents in interface EventPublisher
    
    Parameters:
    
    recipient - the object to register
    
    See Also:
    
    unregisterForEvents(Object)
  - unregisterForEvents
```
void unregisterForEvents(java.lang.Object recipient)
```
    Description copied from interface: EventPublisher
    
    Unregister an object from the viewer event bus.
    
    Specified by:
    
    unregisterForEvents in interface EventPublisher
    
    Parameters:
    
    recipient - the object to unregister
    
    See Also:
    
    EventPublisher.registerForEvents(java.lang.Object)
  - setDisplaySettings
```
void setDisplaySettings(DisplaySettings settings)
```
    Set the display settings.
    This method is a good way to set all of the display settings at once, for example to restore a saved set of settings. For changing just part of the settings (for example, in response to the user setting a UI control), see compareAndSetDisplaySettings(DisplaySettings, DisplaySettings).
    This method can be called from any thread. There may be a delay before the new settings are actually reflected in the viewer user interface. However, getDisplaySettings() will always reflect the most recent settings, even if they have not yet been applied to the UI.
    
    Parameters:
    
    settings - the new display settings
  - getDisplaySettings
```
DisplaySettings getDisplaySettings()
```
    Get the current display settings.
    This method can be called from any thread. The return value will be consistent with the most recent call to setDisplaySettings(DisplaySettings) or compareAndSetDisplaySettings.
    
    Returns:
    
    the current display settings
  - compareAndSetDisplaySettings
```
boolean compareAndSetDisplaySettings(DisplaySettings originalSettings,
                                     DisplaySettings newSettings)
```
    Set the display settings only if the current settings match the expected one.
    This method will allow you to make changes to the display settings in a way that is safe if multiple threads are trying to make changes. For example, the following code will set the zoom. If another thread has makes a change to another part of the display settings at the same time (using the same method), all changes will be correctly reflected.
```
 DataViewer viewer = ...;
 do {
    DisplaySettings oldSettings = viewer.getDisplaySettings();
    DisplaySettings newSettings = oldSettings.copy().
          zoom(2.0).build();
 } while (!viewer.compareAndSetDisplaySettings(oldSettings, newSettings));
 
```
    Parameters:
    
    originalSettings - apply the new settings only if the current settings match this
    
    newSettings - the new settings
    
    Returns:
    
    whether the new settings were applied
  - getDataProvider
```
DataProvider getDataProvider()
```
    Retrieve the data provider backing this viewer. This method can be called from any thread. Implementers: This method should be implemented so that it can be called from any thread. Typically, the data provider will be a private final field in your implementation.
    
    Returns:
    
    the data provider backing this viewer
  - getDatastore
```
@Deprecated
Datastore getDatastore()
```
    Deprecated. use getDataProvider() instead
    
    Retrieve the datastore backing this viewer.
    
    Returns:
    
    the datastore backing this viewer, or null if this viewer is backed by a data provider that is not a datastore
  - setDisplayPosition
```
void setDisplayPosition(Coords position,
                        boolean forceRedisplay)
```
    Display the images at the specified coordinates in the data provider.
    The exact interpretation of the position may depend on the viewer implementation: for example, a 3D viewer might ignore the Z slice coordinate passed to this method and instead display a whole volume. If the passed position does not uniquely specify a set of images to display, then the viewer might choose an arbitrary subset of the passed coordinates.
    This method can be called from any thread. There may be a delay before the new position is actually reflected in the viewer user interface. However, getDisplayPosition() will always reflect the most recent position, even if it has not been applied to the UI.
    
    Parameters:
    
    position - the coordinates of the images to display
    
    forceRedisplay - if true, assume the image(s) at the position may have changed even if the position does not differ from the current one
    
    See Also:
    
    compareAndSetDisplaySettings(DisplaySettings, DisplaySettings)
  - setDisplayPosition
```
void setDisplayPosition(Coords position)
```
    Display the images at the specified coordinates in the data provider.
    See setDisplayPosition(Coords, boolean) for details. This method does not force a redisplay if position is the same as the current display position.
    
    Parameters:
    
    position - the coordinates of the images to display
  - getDisplayPosition
```
Coords getDisplayPosition()
```
    Get the coordinates for the currently displayed images.
    This method can be called from any thread. The return value will be consistent with the most recent call to setDisplayPosition(Coords) or compareAndSetDisplayPosition.
    
    Returns:
    
    the current coordinates displayed
  - compareAndSetDisplayPosition
```
boolean compareAndSetDisplayPosition(Coords originalPosition,
                                     Coords newPosition,
                                     boolean forceRedisplay)
```
    Set the display position only if the current position is the expected one.
    This method will allow you to set the display position based on the current position in a way that is safe if multiple threads are trying to make changes. For example, the following code will scroll to the next channel. If the display position is being changed by another thread (perhaps the time points are being animated, or new time points are being added), all changes will be correctly reflected.
```
 DataViewer viewer = ...;
 do {
    Coords oldPos = viewer.getDisplayPosition();
    Coords newPos = oldPos.copy().
          channel((oldPos.getChannel() + 1) % nChannels).build();
 } while (!viewer.compareAndSetDisplayPosition(oldPos, newPos));
 
```
    Parameters:
    
    originalPosition - apply the new position only if the current position matches this one
    
    newPosition - the new display position
    
    forceRedisplay - if true, assume the image(s) at the position may have changed even if the position does not differ from the current one
    
    Returns:
    
    whether the new position was applied
  - compareAndSetDisplayPosition
```
boolean compareAndSetDisplayPosition(Coords originalPosition,
                                     Coords newPosition)
```
    Set the display position only if the current position is the expected one.
    See compareAndSetDisplayPosition(Coords, Coords, boolean) for details.
    This method will not force a redisplay if newPosition is the same as the current display position.
    
    Parameters:
    
    originalPosition -
    
    newPosition -
    
    Returns:
  - setDisplayedImageTo
```
@Deprecated
void setDisplayedImageTo(Coords position)
```
    Deprecated. use setDisplayPosition(Coords) instead
    
    Obsolete equivalent of setDisplayPosition(Coords).
    
    Parameters:
    
    position - the coordinates of the images to display
  - getDisplayedImages
```
java.util.List<Image> getDisplayedImages()
                                  throws java.io.IOException
```
    Retrieve the Images currently being displayed.
    This method can be called from any thread.
    
    Returns:
    
    Every image at the currently-displayed image coordinates.
    
    Throws:
    
    java.io.IOException
  - isVisible
```
boolean isVisible()
```
    Return true if this viewer is visible. It is recommended that this method be called on the Swing/AWT event dispatch thread. If you call it from another thread, make sure that your thread is not obstructing the event dispatch thread (i.e. the event dispatch thread is not waiting for your thread to finish something).
    
    Returns:
    
    whether the viewer is visible on screen
  - isClosed
```
boolean isClosed()
```
    Return true if this viewer has been closed. It is recommended that this method be called on the Swing/AWT event dispatch thread. If you call it from another thread, make sure that your thread is not obstructing the event dispatch thread (i.e. the event dispatch thread is not waiting for your thread to finish something).
    
    Returns:
    
    whether the viewer has been closed
  - getName
```
java.lang.String getName()
```
    Return the name of this viewer. Typically this will include the display number and the name of the dataset. Implementers: An effort should be made to return a unique name (e.g. by adding a suffix) so that the user can distinguish between viewers that would otherwise have the same name (for example, because they are attached to the same dataset).
    
    Returns:
    
    a string labeling this display
  - addListener
```
void addListener(DataViewerListener listener,
                 int priority)
```
    Listeners will be notified of important events of the DataViewer
    
    Parameters:
    
    listener - - that will be notified
    
    priority - - determines the order in which listeners will be called. the lower the number, the earlier the listener will be called. If the priority matches a previously added listener, the previously added listener will be called first
  - removeListener
```
void removeListener(DataViewerListener listener)
```
    No longer notify this listener
    
    Parameters:
    
    listener - - that will no longer be notified

Interface DataViewer

Method Summary

Method Detail

registerForEvents

unregisterForEvents

setDisplaySettings

getDisplaySettings

compareAndSetDisplaySettings

getDataProvider

getDatastore

setDisplayPosition

setDisplayPosition

getDisplayPosition

compareAndSetDisplayPosition

compareAndSetDisplayPosition

setDisplayedImageTo

getDisplayedImages

isVisible

isClosed

getName

addListener

removeListener