Interface DataViewer
- All Superinterfaces:
EventPublisher
- All Known Subinterfaces:
DisplayWindow
- All Known Implementing Classes:
AbstractDataViewer
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
Modifier and TypeMethodDescriptionvoidaddListener(DataViewerListener listener, int priority) Listeners will be notified of important events of the DataViewer.booleancompareAndSetDisplayPosition(Coords originalPosition, Coords newPosition) Set the display position only if the current position is the expected one.booleancompareAndSetDisplayPosition(Coords originalPosition, Coords newPosition, boolean forceRedisplay) Set the display position only if the current position is the expected one.booleancompareAndSetDisplaySettings(DisplaySettings originalSettings, DisplaySettings newSettings) Set the display settings only if the current settings match the expected one.Retrieve the data provider backing this viewer.Deprecated.Retrieve the Images currently being displayed.Get the coordinates for the currently displayed images.Get the current display settings.getName()Return the name of this viewer.booleanisClosed()Return true if this viewer has been closed.booleanReturn true if this viewer is visible.voidregisterForEvents(Object recipient) Register an object to receive events on the viewer event bus.voidremoveListener(DataViewerListener listener) No longer notify this listener.voidsetDisplayedImageTo(Coords position) Deprecated.usesetDisplayPosition(Coords)insteadvoidsetDisplayPosition(Coords position) Display the images at the specified coordinates in the data provider.voidsetDisplayPosition(Coords position, boolean forceRedisplay) Display the images at the specified coordinates in the data provider.voidsetDisplaySettings(DisplaySettings settings) Set the display settings.voidunregisterForEvents(Object recipient) Unregister an object from the viewer event bus.
-
Method Details
-
registerForEvents
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.Subscribeannotation. 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:
registerForEventsin interfaceEventPublisher- Parameters:
recipient- the object to register- See Also:
-
unregisterForEvents
Description copied from interface:EventPublisherUnregister an object from the viewer event bus.- Specified by:
unregisterForEventsin interfaceEventPublisher- Parameters:
recipient- the object to unregister- See Also:
-
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
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)orcompareAndSetDisplaySettings.- Returns:
- the current display settings
-
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));- Parameters:
originalSettings- apply the new settings only if the current settings match thisnewSettings- 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 finalfield in your implementation.- Returns:
- the data provider backing this viewer
-
getDatastore
Deprecated.usegetDataProvider()insteadRetrieve the datastore backing this viewer.- Returns:
- the datastore backing this viewer, or
nullif this viewer is backed by a data provider that is not a datastore
-
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,
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 displayforceRedisplay- 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:
-
setDisplayPosition
Display the images at the specified coordinates in the data provider.See
setDisplayPosition(Coords, boolean)for details. This method does not force a redisplay ifpositionis 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)orcompareAndSetDisplayPosition.- 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 onenewPosition- the new display positionforceRedisplay- 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
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
newPositionis the same as the current display position.- Parameters:
originalPosition- Original display positionnewPosition- New display position- Returns:
- ??
-
setDisplayedImageTo
Deprecated.usesetDisplayPosition(Coords)insteadObsolete equivalent ofsetDisplayPosition(Coords).- Parameters:
position- the coordinates of the images to display
-
getDisplayedImages
Retrieve the Images currently being displayed.This method can be called from any thread.
- Returns:
- Every image at the currently-displayed image coordinates.
- Throws:
IOException- can happen with disk based data providers.
-
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
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
Listeners will be notified of important events of the DataViewer.- Parameters:
listener- - that will be notifiedpriority- - 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
No longer notify this listener.- Parameters:
listener- - that will no longer be notified
-
getDataProvider()instead