org.micromanager.display

Class 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.

Method Summary

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

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 -

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