Class AbstractDataViewer

java.lang.Object
org.micromanager.display.AbstractDataViewer
All Implemented Interfaces:
DataViewer, EventPublisher

public abstract class AbstractDataViewer extends 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 Details

    • AbstractDataViewer

      protected AbstractDataViewer(DisplaySettings initialDisplaySettings)
      Construct the abstract viewer implementation.
      Parameters:
      initialDisplaySettings - initial display settings
  • Method Details

    • registerForEvents

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

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

      public final void unregisterForEvents(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:
    • postEvent

      protected final void postEvent(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:

      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:
    • 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