Interface 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 Details

    • registerForEvents

      void registerForEvents(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:

      Specified by:
      registerForEvents in interface EventPublisher
      Parameters:
      recipient - the object to register
      See Also:
    • unregisterForEvents

      void unregisterForEvents(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:
    • 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:
    • 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 - Original display position
      newPosition - New display position
      Returns:
      ??
    • setDisplayedImageTo

      @Deprecated void setDisplayedImageTo(Coords position)
      Deprecated.
      Obsolete equivalent of setDisplayPosition(Coords).
      Parameters:
      position - the coordinates of the images to display
    • getDisplayedImages

      List<Image> getDisplayedImages() throws 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:
      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

      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