repository·master·Indexed 24 days ago
https://github.com/stfalcon-studio/stfalconimageviewerA customizable full-screen image viewer for Android that supports pinch-to-zoom, swipe-to-dismiss, and shared element transitions. The library is designed to be agnostic of the image loading library used, requiring an implementation of the ImageLoader interface (e.g., Picasso, Glide, Coil). It features a Builder pattern for configuring starting positions, background colors, container padding, image margins, and custom overlay views.
To install the library using Gradle, first add the JitPack repository to your project-level build.gradle file. Then, add the dependency to your module-level build.gradle file.
// Project build.gradle
allprojects {
repositories {
...
maven { url "https://jitpack.io" }
}
}
// Module build.gradle
implementation 'com.github.stfalcon-studio:StfalconImageViewer:v1.0.1'You can also install the library using Maven by adding the following dependency to your pom.xml file. Replace latest_version with the current version available on Bintray.
<dependency>
<groupId>com.github.stfalcon</groupId>
<artifactId>stfalcon-imageviewer</artifactId>
<version>latest_version</version>
<type>pom</type>
</dependency>To display the image viewer, use StfalconImageViewer.Builder. You must provide the context, a list or array of image objects, and an implementation of the ImageLoader interface to handle the actual image loading (e.g., using Picasso, Glide, etc.).
StfalconImageViewer.Builder<Image>(context, images) {
view, image -> Picasso.get().load(image.url).into(view)
}.show()This example demonstrates how to chain multiple configuration options when building the StfalconImageViewer instance.
StfalconImageViewer.Builder<String>(this, images, ::loadImage)
.withStartPosition(startPosition)
.withBackgroundColor(color)
//.withBackgroundColorResource(R.color.color)
.withOverlayView(view)
.withImagesMargin(R.dimen.margin)
//.withImageMarginPixels(margin)
.withContainerPadding(R.dimen.padding)
//.withContainerPadding(R.dimen.paddingStart, R.dimen.paddingTop, R.dimen.paddingEnd, R.dimen.paddingBottom)
.withContainerPaddingPixels(padding)
.withHiddenStatusBar(shouldHideStatusBar)
.allowZooming(isZoomingAllowed)
.allowSwipeToDismiss(isSwipeToDismissAllowed)
.withTransitionFrom(targeImageView)
.withImageChangeListener(::onImageChanged)
.withDismissListener(::onViewerDismissed)To show content over the image (like share buttons or descriptions), use setOverlayView(customView). You can bind the overlay to the viewer's lifecycle using withImageChangeListener(ImageViewer.OnImageChangeListener).
Set the background color of the fading background using:
setBackgroundColorRes(colorRes) for a color resource.setBackgroundColor(colorInt) for a color integer.You can modify the viewer's state while it is running:
updateImages(images) to replace or update the current list of images (useful for pagination or deletions).setCurrentPosition(position) to programmatically jump to a specific image in the list.withImagesMargin(context, dimenRes) for dimension resources or withImageMarginPixels(int) for pixel values.withContainerPadding(context, start, top, end, bottom) or withContainerPadding(context, dimen) for even padding. Pixel-based variants are also available (e.g., withContainerPaddingPixels(...)).withHiddenStatusBar(boolean) (defaults to true).allowSwipeToDismiss(boolean) and allowZooming(boolean).withTransitionFrom(myImageView) method. Pass the ImageView that the user clicked on to initiate the animation.withOverlayView(view). This is useful for displaying metadata, action buttons (like delete), or custom controls. When the image changes, you should manually update the overlay view's content within the withImageChangeListener callback.To display images in a viewer, use StfalconImageViewer.Builder. You must provide the context, the list of data items, and an image loading function. You can further customize the experience by setting a starting position, defining a transition from a specific ImageView, and adding an image change listener to handle transitions between images.
Key methods:
Builder<T>(context, items, imageLoader): Initializes the builder with the context, the data list, and the function used to load images into ImageViews..withStartPosition(position: Int): Sets the initial index of the image to be displayed..withTransitionFrom(view: ImageView): Configures a transition animation starting from a specific view..withImageChangeListener { ... }: Provides a callback when the image index changes, allowing you to update transitions or UI elements..show(): Displays the viewer.viewer = StfalconImageViewer.Builder<Poster>(this, Demo.posters, ::loadPosterImage)
.withStartPosition(startPosition)
.withTransitionFrom(target)
.withImageChangeListener {
viewer.updateTransitionImage(postersGridView.imageViews[it])
}
.show()To launch the image viewer with custom configurations, use the StfalconImageViewer.Builder class. You must provide the context, a list of items (e.g., your data models), and an image loading function. The builder allows you to customize transitions, margins, zooming behavior, and overlays.
Key builder methods include:
withStartPosition(position: Int): Sets the initial image index.withImageChangeListener(listener: (Int) -> Unit): Callback triggered when the image position changes.withDismissListener(listener: () -> Unit): Callback triggered when the viewer is dismissed.withHiddenStatusBar(hidden: Boolean): Toggles the status bar visibility.withImagesMargin(margin: Int): Sets the margin between images.withContainerPadding(padding: Int): Sets the padding for the viewer container.withTransitionFrom(view: View): Enables a transition animation starting from a specific view.allowSwipeToDismiss(enabled: Boolean): Enables or disables swipe-to-dismiss gesture.allowZooming(enabled: Boolean): Enables or disables zooming functionality.withOverlayView(view: View): Attaches a custom overlay view to the viewer.withBackgroundColor(color: Int): Sets a custom background color.show(): Finalizes the configuration and displays the viewer.To launch the image viewer with advanced features like transitions and listeners, use the StfalconImageViewer.Builder. You must provide the context, a list of items (e.g., Poster), and a function to load the image into an ImageView.
Key builder methods:
withTransitionFrom(view: View?): Specifies the view from which the transition starts (e.g., the thumbnail clicked by the user).withStartPosition(position: Int): Sets the initial index of the image to display.withImageChangeListener(listener: (Int) -> Unit): Provides a callback that receives the current position whenever the image changes. This is useful for updating transition targets dynamically.withDismissListener(listener: () -> Unit): Provides a callback when the viewer is dismissed.show(isDialog: Boolean): Displays the viewer. Use true to show it as a dialog.viewer = StfalconImageViewer.Builder<Poster>(this, Demo.posters, ::loadPosterImage)
.withTransitionFrom(getTransitionTarget(startPosition))
.withStartPosition(startPosition)
.withImageChangeListener {
currentPosition = it
viewer.updateTransitionImage(getTransitionTarget(it))
}
.withDismissListener { isDialogShown = false }
.show(!isDialogShown)