AbstractDataViewer

java.lang.Object
- org.micromanager.display.AbstractDataViewer

All Implemented Interfaces:

DataViewer, EventPublisher
```
public abstract class AbstractDataViewer
extends java.lang.Object
implements DataViewer
```
Abstract implementation of the DataViewer interface.
Custom data viewer classes should extend this class, rather than directly implement DataViewer.

Warning: Support for custom data viewers is experimental. Future updates may require you to update such code for compatibility.

Constructor Summary

Constructors
Modifier Constructor and Description

protected AbstractDataViewer(DisplaySettings initialDisplaySettings)
Construct the abstract viewer implementation.

Constructors
Modifier	Constructor and Description
`protected`	`AbstractDataViewer(DisplaySettings initialDisplaySettings)` Construct the abstract viewer implementation.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`compareAndSetDisplayPosition(Coords oldPosition, Coords newPosition)` Set the display position only if the current position is the expected one.
`boolean`	`compareAndSetDisplayPosition(Coords oldPosition, Coords newPosition, boolean forceRedisplay)` Implements `compareAndSetDisplayPosition`.
`boolean`	`compareAndSetDisplaySettings(DisplaySettings oldSettings, DisplaySettings newSettings)` Implements `compareAndSetDisplaySettings`.
`protected void`	`dispose()` Must be called by implementation to release resources.
`Datastore`	`getDatastore()` Deprecated. user code should call `getDataProvider`
`Coords`	`getDisplayPosition()` Implements `getDisplayPosition`.
`DisplaySettings`	`getDisplaySettings()` Implements `getDisplaySettings`.
`protected abstract Coords`	`handleDisplayPosition(Coords position)`
`protected abstract DisplaySettings`	`handleDisplaySettings(DisplaySettings requestedSettings)` Arrange to apply new display settings.
`protected void`	`postEvent(java.lang.Object event)` Post an event on the viewer event bus.
`void`	`registerForEvents(java.lang.Object recipient)` Register an object to receive events on the viewer event bus.
`void`	`setDisplayedImageTo(Coords coords)` Deprecated. user code should call `setDisplayPosition`
`void`	`setDisplayPosition(Coords position)` Display the images at the specified coordinates in the data provider.
`void`	`setDisplayPosition(Coords position, boolean forceRedisplay)` Implements `setDisplayPosition`.
`void`	`setDisplaySettings(DisplaySettings settings)` Implements `setDisplaySettings`.
`void`	`unregisterForEvents(java.lang.Object recipient)` Unregister an object from the viewer event bus.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.micromanager.display.DataViewer
addListener, getDataProvider, getDisplayedImages, getName, isClosed, isVisible, removeListener

- Constructor Detail
  - AbstractDataViewer
```
protected AbstractDataViewer(DisplaySettings initialDisplaySettings)
```
    Construct the abstract viewer implementation.
    
    Parameters:
    
    initialDisplaySettings - initial display settings
- Method Detail
  - registerForEvents
```
public final void registerForEvents(java.lang.Object recipient)
```
    Description copied from interface: DataViewer
    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 DataViewer
    
    Specified by:
    
    registerForEvents in interface EventPublisher
    
    Parameters:
    
    recipient - the object to register
    
    See Also:
    
    DataViewer.unregisterForEvents(Object)
  - unregisterForEvents
```
public final void unregisterForEvents(java.lang.Object recipient)
```
    Description copied from interface: EventPublisher
    
    Unregister an object from the viewer event bus.
    
    Specified by:
    
    unregisterForEvents in interface DataViewer
    
    Specified by:
    
    unregisterForEvents in interface EventPublisher
    
    Parameters:
    
    recipient - the object to unregister
    
    See Also:
    
    EventPublisher.registerForEvents(java.lang.Object)
  - postEvent
```
protected final void postEvent(java.lang.Object event)
```
    Post an event on the viewer event bus.
    Implementations should call this method to post required notification events.
    
    Some standard viewer events require that they be posted on the Swing/AWT event dispatch thread. Make sure you are on the right thread when posting such events.
    
    Viewers are required to post the following events:
    - DisplaySettingsChangedEvent (posted by this abstract class)
    - DisplayPositionChangedEvent (posted by this abstract class)
    Parameters:
    
    event - the event to post
  - setDisplaySettings
```
public final void setDisplaySettings(DisplaySettings settings)
```
    Implements setDisplaySettings.
    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 DataViewer.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, DataViewer.getDisplaySettings() will always reflect the most recent settings, even if they have not yet been applied to the UI.
    
    Implementations must override handleNewDisplaySettings in order to respond to new display settings.
    
    Specified by:
    
    setDisplaySettings in interface DataViewer
    
    Parameters:
    
    settings - the new display settings
  - getDisplaySettings
```
public final DisplaySettings getDisplaySettings()
```
    Implements 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 DataViewer.setDisplaySettings(DisplaySettings) or compareAndSetDisplaySettings.
    
    Specified by:
    
    getDisplaySettings in interface DataViewer
    
    Returns:
    
    the current display settings
  - compareAndSetDisplaySettings
```
public final boolean compareAndSetDisplaySettings(DisplaySettings oldSettings,
                                                  DisplaySettings newSettings)
```
    Implements compareAndSetDisplaySettings.
    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));
 
```
    Implementations must override handleNewDisplaySettings in order to respond to new display settings.
    Specified by:
    
    compareAndSetDisplaySettings in interface DataViewer
    
    Parameters:
    
    oldSettings - apply the new settings only if the current settings match this
    
    newSettings - the new settings
    
    Returns:
    
    whether the new settings were applied
  - handleDisplaySettings
```
protected abstract DisplaySettings handleDisplaySettings(DisplaySettings requestedSettings)
```
    Arrange to apply new display settings.
    Override this method to apply new display settings.
    
    This method is called in a thread-synchronized context, so you should avoid time-consuming actions. It is safe to call getDisplaySettings and compare its return value with requestedSettings. However, calling setDisplaySettings will result in infinite recursion; if you need to adjust requestedSettings before accepting it, do so by returning a modified copy from this method. This returned settings is what subsequent calls to getDisplaySettings will return.
    
    Typically, the implementation should record all information needed to make the changes and arrange to apply the changes at a later time (usually on the Swing/AWT event dispatch thread).
    
    Parameters:
    
    requestedSettings - the new display settings requested
    
    Returns:
    
    adjusted display settings that will actually apply
  - setDisplayPosition
```
public final void setDisplayPosition(Coords position,
                                     boolean forceRedisplay)
```
    Implements setDisplayPosition.
    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, DataViewer.getDisplayPosition() will always reflect the most recent position, even if it has not been applied to the UI.
    
    Implementations must override handleNewDisplayPosition in order to respond to new display positions.
    
    Specified by:
    
    setDisplayPosition in interface DataViewer
    
    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:
    
    DataViewer.compareAndSetDisplaySettings(DisplaySettings, DisplaySettings)
  - setDisplayPosition
```
public final void setDisplayPosition(Coords position)
```
    Description copied from interface: DataViewer
    
    Display the images at the specified coordinates in the data provider.
    See DataViewer.setDisplayPosition(Coords, boolean) for details. This method does not force a redisplay if position is the same as the current display position.
    
    Specified by:
    
    setDisplayPosition in interface DataViewer
    
    Parameters:
    
    position - the coordinates of the images to display
  - getDisplayPosition
```
public final Coords getDisplayPosition()
```
    Implements 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 DataViewer.setDisplayPosition(Coords) or compareAndSetDisplayPosition.
    
    Specified by:
    
    getDisplayPosition in interface DataViewer
    
    Returns:
    
    the current coordinates displayed
  - compareAndSetDisplayPosition
```
public final boolean compareAndSetDisplayPosition(Coords oldPosition,
                                                  Coords newPosition,
                                                  boolean forceRedisplay)
```
    Implements compareAndSetDisplayPosition.
    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));
 
```
    Specified by:
    
    compareAndSetDisplayPosition in interface DataViewer
    
    Parameters:
    
    oldPosition - 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
```
public final boolean compareAndSetDisplayPosition(Coords oldPosition,
                                                  Coords newPosition)
```
    Description copied from interface: DataViewer
    
    Set the display position only if the current position is the expected one.
    See DataViewer.compareAndSetDisplayPosition(Coords, Coords, boolean) for details.
    This method will not force a redisplay if newPosition is the same as the current display position.
    
    Specified by:
    
    compareAndSetDisplayPosition in interface DataViewer
    
    Parameters:
    
    oldPosition - Original display position
    
    newPosition - New display position
    
    Returns:
    
    ??
  - handleDisplayPosition
```
protected abstract Coords handleDisplayPosition(Coords position)
```
  - dispose
```
protected void dispose()
```
    Must be called by implementation to release resources.
    This is not a "close" method because the DataViewer interface may apply to viewers that are not windows (e.g. an embeddable component).
    
    This method should be called at an appropriate time to release non-memory resources used by AbstractDataViewer.
  - setDisplayedImageTo
```
@Deprecated
public final void setDisplayedImageTo(Coords coords)
```
    Deprecated. user code should call setDisplayPosition
    
    Implements setDisplayedImageTo by calling setDisplayPosition.
    Obsolete equivalent of DataViewer.setDisplayPosition(Coords).
    
    Specified by:
    
    setDisplayedImageTo in interface DataViewer
    
    Parameters:
    
    coords - Coords of image to be displayed.
  - getDatastore
```
@Deprecated
public final Datastore getDatastore()
```
    Deprecated. user code should call getDataProvider
    
    Implements getDatastore by calling getDataProvider.
    
    Specified by:
    
    getDatastore in interface DataViewer
    
    Returns:
    
    the datastore backing this viewer, or null if this viewer is backed by a data provider that is not a datastore

Class AbstractDataViewer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.micromanager.display.DataViewer

Constructor Detail

AbstractDataViewer

Method Detail

registerForEvents

unregisterForEvents

postEvent

setDisplaySettings

getDisplaySettings

compareAndSetDisplaySettings

handleDisplaySettings

setDisplayPosition

setDisplayPosition

getDisplayPosition

compareAndSetDisplayPosition

compareAndSetDisplayPosition

handleDisplayPosition

dispose

setDisplayedImageTo

getDatastore