Constructor Detail

• SubsamplingScaleImageView

  SubsamplingScaleImageView(Context context, AttributeSet attr)

• SubsamplingScaleImageView

  SubsamplingScaleImageView(Context context)

Method Detail

• getPreferredBitmapConfig

   static Config getPreferredBitmapConfig()

  Get the current preferred configuration for decoding bitmaps. ImageDecoder and instances can read this and use it when decoding images.

  Returns:

  the preferred bitmap configuration, or null if none has been set.

• setPreferredBitmapConfig

   static void setPreferredBitmapConfig(Config preferredBitmapConfig)

  Set a global preferred bitmap config shared by all view instances and applied to new instances initialised after the call is made. This is a hint only; the bundled and ImageRegionDecoder classes all respect this (except when they were constructed with an instance-specific config) but custom decoder classes will not.

  Parameters:

  preferredBitmapConfig - the bitmap configuration to be used by future instances of the view.

• getUri

   Uri getUri()

  Return the uri that has been set.

  Returns:

  If an uri has not been set, return null.

• getOrientation

   final int getOrientation()

  Returns the orientation setting. This can return ORIENTATION_USE_EXIF, in which case it doesn't tell you the applied orientation of the image. For that, use getAppliedOrientation.

  Returns:

  the orientation setting. See static fields.

• setOrientation

   final void setOrientation(int orientation)

  Sets the image orientation. It's best to call this before setting the image file or asset, because it may waste loading of tiles. However, this can be freely called at any time.

  Parameters:

  orientation - orientation to be set.

• getMaxScale

   float getMaxScale()

  Returns the maximum allowed scale.

  Returns:

  the maximum scale as a source/view pixels ratio.

• setMaxScale

   final void setMaxScale(float maxScale)

  Set the maximum scale allowed. A value of 1 means 1:1 pixels at maximum scale. You may wish to set this according to screen density - on a retina screen, 1:1 may still be too small. Consider using setMinimumDpi, which is density aware.

  Parameters:

  maxScale - maximum scale expressed as a source/view pixels ratio.

• getScale

   final float getScale()

  Returns the current scale value.

  Returns:

  the current scale as a source/view pixels ratio.

• getSWidth

   final int getSWidth()

  Get source width, ignoring orientation. If getOrientation returns 90 or 270, you can use getSHeight for the apparent width.

  Returns:

  the source image width in pixels.

• getSHeight

   final int getSHeight()

  Get source height, ignoring orientation. If getOrientation returns 90 or 270, you can use getSWidth for the apparent height.

  Returns:

  the source image height in pixels.

• getMinScale

   final float getMinScale()

  Returns the minimum allowed scale.

  Returns:

  the minimum scale as a source/view pixels ratio.

• setMinScale

   final void setMinScale(float minScale)

  Set the minimum scale allowed. A value of 1 means 1:1 pixels at minimum scale. You may wish to set this according to screen density. Consider using setMaximumDpi, which is density aware.

  Parameters:

  minScale - minimum scale expressed as a source/view pixels ratio.

• setImage

   final void setImage(ImageSource imageSource)

  Set the image source from a bitmap, resource, asset, file or other URI.

  Parameters:

  imageSource - Image source.

• setBitmapAndFileUri

   final void setBitmapAndFileUri(Bitmap bitmap, Uri fileUri)

  Parameters:

  bitmap - 图片bitmap

  fileUri - 超清图片缓存文件Uri,如果没超过GL最大显示限制则不会被使用

• setBitmapFitX

   final void setBitmapFitX(Bitmap bitmap)

  bitmap 展示以X轴为准,填充满X轴

  Parameters:

  bitmap - Bitmap

• setImage

   final void setImage(ImageSource imageSource, ImageViewState state)

  Set the image source from a bitmap, resource, asset, file or other URI, starting with a given orientation setting, scale and center. This is the best method to use when you want scale and center to be restored after screen orientation change; it avoids any redundant loading of tiles in the wrong orientation.

  Parameters:

  imageSource - Image source.

  state - State to be restored.

• setImage

   final void setImage(ImageSource imageSource, ImageSource previewSource)

  Set the image source from a bitmap, resource, asset, file or other URI, providing a preview image to be displayed until the full size image is loaded.

  You must declare the dimensions of the full size image by calling dimensions on the imageSource object. The preview source will be ignored if you don't provide dimensions, and if you provide a bitmap for the full size image.

  Parameters:

  imageSource - Image source.

  previewSource - Optional source for a preview image to be displayed and allow interaction while the full size image loads.

• setImage

   final void setImage(ImageSource imageSource, ImageSource previewSource, ImageViewState state)

  Set the image source from a bitmap, resource, asset, file or other URI, providing a preview image to be displayed until the full size image is loaded, starting with a given orientation setting, scale and center. This is the best method to use when you want scale and center to be restored after screen orientation change; it avoids any redundant loading of tiles in the wrong orientation.

  You must declare the dimensions of the full size image by calling dimensions on the imageSource object. The preview source will be ignored if you don't provide dimensions, and if you provide a bitmap for the full size image.

  Parameters:

  imageSource - Image source.

  previewSource - Optional source for a preview image to be displayed and allow interaction while the full size image loads.

  state - State to be restored.

• setMaxTileSize

   void setMaxTileSize(int maxPixels)

  By default the View automatically calculates the optimal tile size. Set this to override this, and force an upper limit to the dimensions of the generated tiles. Passing TILE_SIZE_AUTO will re-enable the default behaviour.

  Parameters:

  maxPixels - Maximum tile size X and Y in pixels.

• setMaxTileSize

   void setMaxTileSize(int maxPixelsX, int maxPixelsY)

  By default the View automatically calculates the optimal tile size. Set this to override this, and force an upper limit to the dimensions of the generated tiles. Passing TILE_SIZE_AUTO will re-enable the default behaviour.

  Parameters:

  maxPixelsX - Maximum tile width.

  maxPixelsY - Maximum tile height.

• recycle

   void recycle()

  Releases all resources the view is using and resets the state, nulling any fields that use significant memory. After you have called this method, the view can be re-used by setting a new image. Settings are remembered but state (scale and center) is forgotten. You can restore these yourself if required.

• visibleFileRect

   void visibleFileRect(Rect fRect)

  Find the area of the source file that is currently visible on screen, taking into account the current scale, translation, orientation and clipped region. This is a convenience method; see viewToFileRect.

  Parameters:

  fRect - rectangle instance to which the result will be written.

• viewToFileRect

   void viewToFileRect(Rect vRect, Rect fRect)

  Converts a rectangle within the view to the corresponding rectangle from the source file, taking into account the current scale, translation, orientation and clipped region. This can be used to decode a bitmap from the source file.

  This method will only work when the image has fully initialised, after isReady returns true. It is not guaranteed to work with preloaded bitmaps.

  The result is written to the fRect argument. Re-use a single instance for efficiency.

  Parameters:

  vRect - rectangle representing the view area to interpret.

  fRect - rectangle instance to which the result will be written.

• viewToSourceCoord

   final PointF viewToSourceCoord(PointF vxy)

  Convert screen coordinate to source coordinate.

  Parameters:

  vxy - view X/Y coordinate.

  Returns:

  a coordinate representing the corresponding source coordinate.

• viewToSourceCoord

   final PointF viewToSourceCoord(PointF vxy, PointF sTarget)

  Convert screen coordinate to source coordinate.

  Parameters:

  vxy - view coordinates to convert.

  sTarget - target object for result.

  Returns:

  source coordinates. This is the same instance passed to the sTarget param.

• viewToSourceCoord

   final PointF viewToSourceCoord(float vx, float vy, PointF sTarget)

  Convert screen coordinate to source coordinate.

  Parameters:

  vx - view X coordinate.

  vy - view Y coordinate.

  sTarget - target object for result.

  Returns:

  source coordinates. This is the same instance passed to the sTarget param.

• sourceToViewCoord

   final PointF sourceToViewCoord(PointF sxy)

  Convert source coordinate to view coordinate.

  Parameters:

  sxy - source coordinates to convert.

  Returns:

  view coordinates.

• sourceToViewCoord

   final PointF sourceToViewCoord(float sx, float sy)

  Convert source coordinate to view coordinate.

  Parameters:

  sx - source X coordinate.

  sy - source Y coordinate.

  Returns:

  view coordinates.

• sourceToViewCoord

   final PointF sourceToViewCoord(float sx, float sy, PointF vTarget)

  Convert source coordinate to view coordinate.

  Parameters:

  sx - source X coordinate.

  sy - source Y coordinate.

  vTarget - target object for result.

  Returns:

  view coordinates. This is the same instance passed to the vTarget param.

• sourceToViewCoord

   final PointF sourceToViewCoord(PointF sxy, PointF vTarget)

  Convert source coordinate to view coordinate.

  Parameters:

  sxy - source coordinates to convert.

  vTarget - target object for result.

  Returns:

  view coordinates. This is the same instance passed to the vTarget param.

• setRegionDecoderClass

   final void setRegionDecoderClass(Class<out ImageRegionDecoder> regionDecoderClass)

  Swap the default region decoder implementation for one of your own. You must do this before setting the image file or asset, and you cannot use a custom decoder when using layout XML to set an asset name. Your class must have a public default constructor.

  Parameters:

  regionDecoderClass - The ImageRegionDecoder implementation to use.

• setBitmapDecoderClass

   final void setBitmapDecoderClass(Class<out ImageDecoder> bitmapDecoderClass)

  Swap the default bitmap decoder implementation for one of your own. You must do this before setting the image file or asset, and you cannot use a custom decoder when using layout XML to set an asset name. Your class must have a public default constructor.

  Parameters:

  bitmapDecoderClass - The ImageDecoder implementation to use.

• getPanRemaining

   final void getPanRemaining(RectF vTarget)

  Calculate how much further the image can be panned in each direction. The results are set on the supplied RectF and expressed as screen pixels. For example, if the image cannot be panned any further towards the left, the value of left will be set to 0.

  Parameters:

  vTarget - target object for results.

• isReady

   final boolean isReady()

  Call to find whether the view is initialised, has dimensions, and will display an image on the next draw. If a preview has been provided, it may be the preview that will be displayed and the full size image may still be loading. If no preview was provided, this is called once the base layer tiles of the full size image are loaded.

  Returns:

  true if the view is ready to display an image and accept touch gestures.

• setMinimumDpi

   final void setMinimumDpi(int dpi)

  This is a screen density aware alternative to setMaxScale; it allows you to express the maximum allowed scale in terms of the minimum pixel density. This avoids the problem of 1:1 scale still being too small on a high density screen. A sensible starting point is 160 - the default used by this view.

  Parameters:

  dpi - Source image pixel density at maximum zoom.

• setMaximumDpi

   final void setMaximumDpi(int dpi)

  This is a screen density aware alternative to setMinScale; it allows you to express the minimum allowed scale in terms of the maximum pixel density.

  Parameters:

  dpi - Source image pixel density at minimum zoom.

• setScaleAndCenter

   final void setScaleAndCenter(float scale, PointF sCenter)

  Externally change the scale and translation of the source image. This may be used with getCenter() and getScale() to restore the scale and zoom after a screen rotate.

  Parameters:

  scale - New scale to set.

  sCenter - New source image coordinate to center on the screen, subject to boundaries.

• resetScaleAndCenter

   final void resetScaleAndCenter()

  Fully zoom out and return the image to the middle of the screen. This might be useful if you have a view pager and want images to be reset when the user has moved to another page.

• isImageLoaded

   final boolean isImageLoaded()

  Call to find whether the main image (base layer tiles where relevant) have been loaded. Before this event the view is blank unless a preview was provided.

  Returns:

  true if the main image (not the preview) has been loaded and is ready to display.

• getAppliedOrientation

   final int getAppliedOrientation()

  Returns the actual orientation of the image relative to the source file. This will be based on the source file's EXIF orientation if you're using ORIENTATION_USE_EXIF. Values are 0, 90, 180, 270.

  Returns:

  the orientation applied after EXIF information has been extracted. See static fields.

• getState

   final ImageViewState getState()

  Get the current state of the view (scale, center, orientation) for restoration after rotate. Will return null if the view is not ready.

  Returns:

  an ImageViewState instance representing the current position of the image. null if the view isn't ready.

• getCenter

   final PointF getCenter()

  Returns the source point at the center of the view.

  Returns:

  the source coordinates current at the center of the view.

• viewToSourceCoord

   final PointF viewToSourceCoord(float vx, float vy)

  Convert screen coordinate to source coordinate.

  Parameters:

  vx - view X coordinate.

  vy - view Y coordinate.

  Returns:

  a coordinate representing the corresponding source coordinate.

• isZoomEnabled

   final boolean isZoomEnabled()

  Returns true if zoom gesture detection is enabled.

  Returns:

  true if zoom gesture detection is enabled.

• isQuickScaleEnabled

   final boolean isQuickScaleEnabled()

  Returns true if double tap &swipe to zoom is enabled.

  Returns:

  true if double tap &swipe to zoom is enabled.

• isPanEnabled

   final boolean isPanEnabled()

  Returns true if pan gesture detection is enabled.

  Returns:

  true if pan gesture detection is enabled.

• setTileBackgroundColor

   final void setTileBackgroundColor(int tileBgColor)

  Set a solid color to render behind tiles, useful for displaying transparent PNGs.

  Parameters:

  tileBgColor - Background color for tiles.

• setDoubleTapZoomDpi

   final void setDoubleTapZoomDpi(int dpi)

  A density aware alternative to setDoubleTapZoomScale; this allows you to express the scale the image will zoom in to when double tapped in terms of the image pixel density. Values lower than the max scale will be ignored. A sensible starting point is 160 - the default used by this view.

  Parameters:

  dpi - New value for double tap gesture zoom scale.

• hasImage

   boolean hasImage()

  Check if an image has been set. The image may not have been loaded and displayed yet.

  Returns:

  If an image is currently set.

• onTouchEvent

   boolean onTouchEvent(MotionEvent event)

  Handle touch events. One finger pans, and two finger pinch and zoom plus panning.

• animateCenter

   SubsamplingScaleImageView.AnimationBuilder animateCenter(PointF sCenter)

  Creates a panning animation builder, that when started will animate the image to place the given coordinates of the image in the center of the screen. If doing this would move the image beyond the edges of the screen, the image is instead animated to move the center point as near to the center of the screen as is allowed - it's guaranteed to be on screen.

  Parameters:

  sCenter - Target center point

  Returns:

  AnimationBuilder instance. Call start to start the anim.

• animateScale

   SubsamplingScaleImageView.AnimationBuilder animateScale(float scale)

  Creates a scale animation builder, that when started will animate a zoom in or out. If this would move the image beyond the panning limits, the image is automatically panned during the animation.

  Parameters:

  scale - Target scale.

  Returns:

  AnimationBuilder instance. Call start to start the anim.

• animateScaleAndCenter

   SubsamplingScaleImageView.AnimationBuilder animateScaleAndCenter(float scale, PointF sCenter)

  Creates a scale animation builder, that when started will animate a zoom in or out. If this would move the image beyond the panning limits, the image is automatically panned during the animation.

  Parameters:

  scale - Target scale.

  sCenter - Target source center.

  Returns:

  AnimationBuilder instance. Call start to start the anim.

• setRegionDecoderFactory

   final void )>setRegionDecoderFactory(DecoderFactory<? extends ImageRegionDecoder> regionDecoderFactory)

  Swap the default region decoder implementation for one of your own. You must do this before setting the image file or asset, and you cannot use a custom decoder when using layout XML to set an asset name.

  Parameters:

  regionDecoderFactory - The DecoderFactory implementation that produces instances.

• setBitmapDecoderFactory

   final void )>setBitmapDecoderFactory(DecoderFactory<? extends ImageDecoder> bitmapDecoderFactory)

  Swap the default bitmap decoder implementation for one of your own. You must do this before setting the image file or asset, and you cannot use a custom decoder when using layout XML to set an asset name.

  Parameters:

  bitmapDecoderFactory - The DecoderFactory implementation that produces instances.

• setPanLimit

   final void setPanLimit(int panLimit)

  Set the pan limiting style. See static fields. Normally PAN_LIMIT_INSIDE is best, for image galleries.

  Parameters:

  panLimit - a pan limit constant.

• setMinimumScaleType

   final void setMinimumScaleType(int scaleType)

  Set the minimum scale type. See static fields. Normally SCALE_TYPE_CENTER_INSIDE is best, for image galleries.

  Parameters:

  scaleType - a scale type constant.

• setMinimumTileDpi

   void setMinimumTileDpi(int minimumTileDpi)

  By default, image tiles are at least as high resolution as the screen. For a retina screen this may not be necessary, and may increase the likelihood of an OutOfMemoryError. This method sets a DPI at which higher resolution tiles should be loaded. Using a lower number will on average use less memory but result in a lower quality image. 160-240dpi will usually be enough. This should be called before setting the image source, because it affects which tiles get loaded. When using an untiled source image this method has no effect.

  Parameters:

  minimumTileDpi - Tile loading threshold.

• setZoomEnabled

   final void setZoomEnabled(boolean zoomEnabled)

  Enable or disable zoom gesture detection. Disabling zoom locks the the current scale.

  Parameters:

  zoomEnabled - true to enable zoom gestures, false to disable.

• setQuickScaleEnabled

   final void setQuickScaleEnabled(boolean quickScaleEnabled)

  Enable or disable double tap &swipe to zoom.

  Parameters:

  quickScaleEnabled - true to enable quick scale, false to disable.

• setPanEnabled

   final void setPanEnabled(boolean panEnabled)

  Enable or disable pan gesture detection. Disabling pan causes the image to be centered. Pan can still be changed from code.

  Parameters:

  panEnabled - true to enable panning, false to disable.

• setDoubleTapZoomScale

   final void setDoubleTapZoomScale(float doubleTapZoomScale)

  Set the scale the image will zoom in to when double tapped. This also the scale point where a double tap is interpreted as a zoom out gesture - if the scale is greater than 90% of this value, a double tap zooms out. Avoid using values greater than the max zoom.

  Parameters:

  doubleTapZoomScale - New value for double tap gesture zoom scale.

• setDoubleTapZoomStyle

   final void setDoubleTapZoomStyle(int doubleTapZoomStyle)

  Set the type of zoom animation to be used for double taps. See static fields.

  Parameters:

  doubleTapZoomStyle - New value for zoom style.

• setDoubleTapZoomDuration

   final void setDoubleTapZoomDuration(int durationMs)

  Set the duration of the double tap zoom animation.

  Parameters:

  durationMs - Duration in milliseconds.

• setExecutor

   void setExecutor(Executor executor)

  Provide an Executor to be used for loading images. By default, THREAD_POOL_EXECUTOR is used to minimise contention with other background work the app is doing. You can also choose to use SERIAL_EXECUTOR if you want to limit concurrent background tasks. Alternatively you can supply an Executor of your own to avoid any contention. It is strongly recommended to use a single executor instance for the life of your application, not one per view instance.

  Warning: If you are using a custom implementation of ImageRegionDecoder, and you supply an executor with more than one thread, you must make sure your implementation supports multi-threaded bitmap decoding or has appropriate internal synchronization. From SDK 21, Android's android.graphics.BitmapRegionDecoder uses an internal lock so it is thread safe but there is no advantage to using multiple threads.

  Parameters:

  executor - an Executor for image loading.

• setEagerLoadingEnabled

   void setEagerLoadingEnabled(boolean eagerLoadingEnabled)

  Enable or disable eager loading of tiles that appear on screen during gestures or animations, while the gesture or animation is still in progress. By default this is enabled to improve responsiveness, but it can result in tiles being loaded and discarded more rapidly than necessary and reduce the animation frame rate on old/cheap devices. Disable this on older devices if you see poor performance. Tiles will then be loaded only when gestures and animations are completed.

  Parameters:

  eagerLoadingEnabled - true to enable loading during gestures, false to delay loading until gestures end

• setDebug

   final void setDebug(boolean debug)

  Enables visual debugging, showing tile boundaries and sizes.

  Parameters:

  debug - true to enable debugging, false to disable.

• setOnLongClickListener

   void setOnLongClickListener(OnLongClickListener onLongClickListener)

• setOnImageEventListener

   void setOnImageEventListener(SubsamplingScaleImageView.OnImageEventListener onImageEventListener)

  Add a listener allowing notification of load and error events. Extend to simplify implementation.

  Parameters:

  onImageEventListener - an OnImageEventListener instance.

• setOnStateChangedListener

   void setOnStateChangedListener(SubsamplingScaleImageView.OnStateChangedListener onStateChangedListener)

  Add a listener for pan and zoom events. Extend DefaultOnStateChangedListener to simplify implementation.

  Parameters:

  onStateChangedListener - an OnStateChangedListener instance.