### Complete GalleryActivity Example

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

This example shows how to implement StfalconImageViewer within an Android Activity, configuring various options like transition, background, overlay, margins, padding, status bar visibility, zooming, swipe-to-dismiss, and event listeners.

```kotlin
class GalleryActivity : AppCompatActivity() {

    private var viewer: StfalconImageViewer<Photo>? = null
    private var overlayView: GalleryOverlayView? = null
    private val photos = mutableListOf<Photo>()

    fun openViewer(startPosition: Int, sourceImageView: ImageView) {
        setupOverlayView(startPosition)

        viewer = StfalconImageViewer.Builder<Photo>(this, photos, ::loadImage)
            .withStartPosition(startPosition)
            .withTransitionFrom(sourceImageView)
            .withBackgroundColorResource(R.color.gallery_background)
            .withOverlayView(overlayView)
            .withImagesMargin(R.dimen.gallery_image_margin)
            .withContainerPadding(R.dimen.padding_horizontal, R.dimen.padding_top,
                                  R.dimen.padding_horizontal, R.dimen.padding_bottom)
            .withHiddenStatusBar(true)
            .allowZooming(true)
            .allowSwipeToDismiss(true)
            .withImageChangeListener(::onImageChanged)
            .withDismissListener(::onViewerDismissed)
            .show()
    }

    private fun loadImage(imageView: ImageView, photo: Photo) {
        Glide.with(imageView)
            .load(photo.url)
            .placeholder(R.drawable.placeholder)
            .error(R.drawable.error)
            .into(imageView)
    }

    private fun setupOverlayView(startPosition: Int) {
        overlayView = GalleryOverlayView(this).apply {
            update(photos[startPosition], startPosition, photos.size)

            onShareClick = { sharePhoto(photos[viewer?.currentPosition() ?: 0]) }
            onDeleteClick = { deleteCurrentPhoto() }
            onCloseClick = { viewer?.close() }
        }
    }

    private fun onImageChanged(position: Int) {
        // Update transition for smooth close animation
        viewer?.updateTransitionImage(gridView.getImageViewAt(position))

        // Update overlay content
        overlayView?.update(photos[position], position, photos.size)
    }

    private fun onViewerDismissed() {
        overlayView = null
        // Resume any paused operations
    }

    private fun deleteCurrentPhoto() {
        val position = viewer?.currentPosition() ?: return
        photos.removeAt(position)

        if (photos.isEmpty()) {
            // Viewer will close automatically
            return
        }

        viewer?.updateImages(photos)
        val newPosition = minOf(position, photos.size - 1)
        overlayView?.update(photos[newPosition], newPosition, photos.size)
    }

    private fun sharePhoto(photo: Photo) {
        val intent = Intent(Intent.ACTION_SEND).apply {
            type = "text/plain"
            putExtra(Intent.EXTRA_TEXT, photo.url)
        }
        startActivity(Intent.createChooser(intent, "Share"))
    }
}
```

--------------------------------

### Setting Initial Image Position

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Configures the StfalconImageViewer to open displaying a specific image from the list using the `withStartPosition` method. The default start position is 0.

```kotlin
val images = listOf("url1", "url2", "url3", "url4")

// Open viewer starting at the third image (index 2)
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withStartPosition(2)
    .show()
```

--------------------------------

### Configure StfalconImageViewer Options

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Use this builder pattern to configure all available options for StfalconImageViewer, including start position, background color, image margins, container padding, status bar visibility, gesture controls, transition views, and listeners.

```java
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)
            //.withContainerPaddingPixels(paddingStart, paddingTop, paddingEnd, paddingBottom)
            .withHiddenStatusBar(shouldHideStatusBar)
            .allowZooming(isZoomingAllowed)
            .allowSwipeToDismiss(isSwipeToDismissAllowed)
            .withTransitionFrom(targeImageView)
            .withImageChangeListener(::onImageChanged)
            .withDismissListener(::onViewerDismissed)
            .withDismissListener(::onViewerDismissed)
```

--------------------------------

### ImageViewer with Glide ImageLoader

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Shows how to integrate StfalconImageViewer with Glide by implementing the ImageLoader interface. This example includes placeholder and error image configurations.

```kotlin
// Using Glide as the image loader
val glideImageLoader: ImageLoader<String> = ImageLoader { imageView, imageUrl ->
    Glide.with(imageView.context)
        .load(imageUrl)
        .placeholder(R.drawable.placeholder)
        .error(R.drawable.error)
        .into(imageView)
}

StfalconImageViewer.Builder<String>(this, images, glideImageLoader).show()
```

--------------------------------

### Get or Set Current Image Position

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Control and retrieve the currently displayed image using `currentPosition()` and `setCurrentPosition(position: Int)`. Useful for custom navigation or integrating with thumbnail views.

```kotlin
private var viewer: StfalconImageViewer<String>? = null

fun openViewer() {
    viewer = StfalconImageViewer.Builder<String>(this, images) { view, url ->
        Picasso.get().load(url).into(view)
    }.show()
}

// Navigate to specific image from thumbnail click
fun onThumbnailClick(position: Int) {
    viewer?.setCurrentPosition(position)
}

// Get current position for analytics
fun logCurrentImage() {
    val position = viewer?.currentPosition() ?: -1
    analytics.logImageView(images[position])
}
```

--------------------------------

### Basic ImageViewer Usage with Picasso

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Demonstrates the basic implementation of StfalconImageViewer using Picasso for image loading. Ensure Picasso is added to your project dependencies.

```kotlin
// Basic usage with Picasso
val images = listOf(
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
)

StfalconImageViewer.Builder<String>(this, images) { imageView, imageUrl ->
    Picasso.get().load(imageUrl).into(imageView)
}.show()
```

--------------------------------

### Image Viewer with Transition Animation

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Enable a transition animation when opening the image viewer by specifying the source ImageView.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withTransitionFrom(myImageView).show()
```

--------------------------------

### Basic Image Viewer Usage

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Display a full-screen image viewer with a list of images and a custom Picasso image loader.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.show()
```

--------------------------------

### Add Project Gradle Dependency

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Include the JitPack repository in your project's root build.gradle file to access the library.

```gradle
allprojects {
    repositories {
        ... 
        maven { url "https://jitpack.io" }
    }
}
```

--------------------------------

### Add Module Gradle Dependency

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Add the StfalconImageViewer library dependency to your module's build.gradle file.

```gradle
implementation 'com.github.stfalcon-studio:StfalconImageViewer:v1.0.1'
```

--------------------------------

### withOverlayView(view: View)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Sets a custom overlay view to be displayed on top of the images. This is useful for adding elements like descriptions, sharing buttons, delete actions, or page counters.

```APIDOC
## withOverlayView(view: View)

### Description
Sets a custom overlay view to be displayed on top of the images. Commonly used for image descriptions, sharing buttons, delete actions, or page counters.

### Method
`withOverlayView`

### Parameters
#### Path Parameters
- **view** (View) - Required - The custom overlay view to be displayed.

### Request Example
```kotlin
// Create custom overlay view
class ImageOverlayView(context: Context) : ConstraintLayout(context) {
    var onShareClick: (Int) -> Unit = {}
    var onDeleteClick: (Int) -> Unit = {}

    init {
        inflate(context, R.layout.view_image_overlay, this)
        setBackgroundColor(Color.TRANSPARENT)
    }

    fun update(position: Int, totalCount: Int, description: String) {
        counterText.text = "${position + 1} / $totalCount"
        descriptionText.text = description
        shareButton.setOnClickListener { onShareClick(position) }
        deleteButton.setOnClickListener { onDeleteClick(position) }
    }
}

// Use overlay with viewer
val overlayView = ImageOverlayView(this).apply {
    onShareClick = { position -> shareImage(images[position]) }
    onDeleteClick = { position -> deleteImage(position) }
}

var viewer: StfalconImageViewer<ImageData>? = null

viewer = StfalconImageViewer.Builder<ImageData>(this, images) { view, data ->
    Glide.with(view).load(data.url).into(view)
}
    .withOverlayView(overlayView)
    .withImageChangeListener { position ->
        overlayView.update(position, images.size, images[position].description)
    }
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### Add Maven Dependency

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Alternatively, add the StfalconImageViewer dependency using Maven coordinates.

```xml
<dependency>
  <groupId>com.github.stfalcon</groupId>
  <artifactId>stfalcon-imageviewer</artifactId>
  <version>latest_version</version>
  <type>pom</type>
</dependency>
```

--------------------------------

### close() / dismiss() API

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Provides two methods for programmatically closing the image viewer. `close()` animates the closing transition, while `dismiss()` closes the viewer immediately without any animation.

```APIDOC
## close() / dismiss()

### Description
Programmatically closes the viewer. `close()` uses the transition animation while `dismiss()` closes immediately without animation.

### Method
`close()` (with animation)
`dismiss()` (without animation)

### Parameters
None

### Request Example
```kotlin
// Close with animation
viewer?.close()

// Dismiss immediately
viewer?.dismiss()
```

### Response
None directly from the method call, but the viewer is closed.

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Set Custom Overlay View

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Add a custom view as an overlay on top of the image using `setOverlayView()` and `OnImageChangeListener`.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.setOverlayView(customOverlayView).show()
```

--------------------------------

### Shared Element Transition with ImageView

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Enables a shared element transition animation from a source ImageView to the full-screen viewer. This requires specifying the transition source ImageView using `withTransitionFrom`.

```kotlin
// In a RecyclerView adapter or grid view click handler
fun onImageClick(position: Int, clickedImageView: ImageView) {
    StfalconImageViewer.Builder<String>(context, imageUrls) { view, url ->
        Glide.with(view).load(url).into(view)
    }
        .withStartPosition(position)
        .withTransitionFrom(clickedImageView)
        .show()
}
```

--------------------------------

### allowZooming(enabled: Boolean)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Enables or disables pinch-to-zoom functionality. Enabled by default.

```APIDOC
## allowZooming(enabled: Boolean)

### Description
Enables or disables pinch-to-zoom functionality. Enabled by default.

### Method
`allowZooming`

### Parameters
#### Path Parameters
- **enabled** (Boolean) - Required - Set to `true` to enable zooming, `false` to disable it.

### Request Example
```kotlin
// Disable zooming for simple gallery view
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .allowZooming(false)
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### Set Viewer Background Color with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Customize the viewer's background color using either a color integer or a color resource ID. The background animates fading in and out.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withBackgroundColor(Color.parseColor("#CC000000"))
    .show()
```

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withBackgroundColorResource(R.color.viewer_background)
    .show()
```

--------------------------------

### withContainerPadding Methods

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Sets padding around the image viewing area. Useful when using overlay views that might cover parts of the images.

```APIDOC
## withContainerPadding Methods

### Description
Sets padding around the image viewing area. Useful when using overlay views that might cover parts of the images.

### Method
`withContainerPadding` or `withContainerPaddingPixels`

### Parameters
#### Path Parameters
- **dimenRes** (Int) - Required - The dimension resource ID for uniform padding.
- **paddingStart**, **paddingTop**, **paddingEnd**, **paddingBottom** (Int) - Required - Dimension resource IDs for individual padding sides.
- **pixelsStart**, **pixelsTop**, **pixelsEnd**, **pixelsBottom** (Int) - Required - Padding values in pixels for individual sides.

### Request Example
```kotlin
// Uniform padding using dimension resource
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPadding(R.dimen.viewer_padding)
    .show()

// Different padding for each side using dimension resources
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPadding(
        R.dimen.padding_start,
        R.dimen.padding_top,
        R.dimen.padding_end,
        R.dimen.padding_bottom
    )
    .show()

// Using pixel values directly
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPaddingPixels(16, 48, 16, 100) // Leave space for bottom overlay
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### Enable/Disable Zooming with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Toggle the pinch-to-zoom functionality for images. Zooming is enabled by default.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .allowZooming(false)
    .show()
```

--------------------------------

### Image Change Listener for UI Updates

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Implements `withImageChangeListener` to receive callbacks when the user swipes to a different image. This is useful for updating page indicators or transition targets.

```kotlin
private lateinit var viewer: StfalconImageViewer<Poster>

fun openViewer(startPosition: Int, targetImageView: ImageView) {
    viewer = StfalconImageViewer.Builder<Poster>(this, posters) { view, poster ->
        Glide.with(view).load(poster.url).into(view)
    }
        .withStartPosition(startPosition)
        .withTransitionFrom(targetImageView)
        .withImageChangeListener { position ->
            // Update transition target when image changes
            viewer.updateTransitionImage(gridImageViews[position])

            // Update page indicator
            pageIndicator.text = "${position + 1} / ${posters.size}"
        }
        .show()
}
```

--------------------------------

### Gradle Dependencies for StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Add the StfalconImageViewer library to your Android project by including the necessary repositories and dependencies in your build.gradle files.

```gradle
// In project build.gradle
allprojects {
    repositories {
        maven { url "https://jitpack.io" }
    }
}

// In module build.gradle
dependencies {
    implementation 'com.github.stfalcon-studio:StfalconImageViewer:v1.0.1'
}
```

--------------------------------

### Apache License 2.0

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

The Apache License, Version 2.0, governs the use of this software, outlining permissions and limitations.

```text
Copyright (C) 2018 stfalcon.com

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

--------------------------------

### Programmatically Close Viewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Close the viewer using `close()` for an animated exit or `dismiss()` for an immediate, non-animated closure. `close()` is suitable for user-initiated actions, while `dismiss()` is useful for system events like activity destruction.

```kotlin
private var viewer: StfalconImageViewer<String>? = null

fun openViewer() {
    viewer = StfalconImageViewer.Builder<String>(this, images) { view, url ->
        Picasso.get().load(url).into(view)
    }.show()
}

// Close with animation (e.g., from overlay close button)
fun onCloseButtonClick() {
    viewer?.close()
}

// Dismiss immediately (e.g., when activity is finishing)
override fun onDestroy() {
    viewer?.dismiss()
    super.onDestroy()
}
```

--------------------------------

### withBackgroundColor(color: Int) / withBackgroundColorResource(colorRes: Int)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Sets the background color of the viewer. The background fades in when opening and fades out when closing.

```APIDOC
## withBackgroundColor(color: Int) / withBackgroundColorResource(colorRes: Int)

### Description
Sets the background color of the viewer. The background fades in when opening and fades out when closing.

### Method
`withBackgroundColor` or `withBackgroundColorResource`

### Parameters
#### Path Parameters
- **color** (Int) - Required - The background color as an integer.
- **colorRes** (Int) - Required - The resource ID of the background color.

### Request Example
```kotlin
// Using color int
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withBackgroundColor(Color.parseColor("#CC000000"))
    .show()

// Using color resource
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withBackgroundColorResource(R.color.viewer_background)
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### allowSwipeToDismiss(enabled: Boolean)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Enables or disables the swipe-to-dismiss gesture. Enabled by default.

```APIDOC
## allowSwipeToDismiss(enabled: Boolean)

### Description
Enables or disables the swipe-to-dismiss gesture. Enabled by default.

### Method
`allowSwipeToDismiss`

### Parameters
#### Path Parameters
- **enabled** (Boolean) - Required - Set to `true` to enable swipe-to-dismiss, `false` to disable it.

### Request Example
```kotlin
// Disable swipe to dismiss (user must use back button or overlay close button)
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .allowSwipeToDismiss(false)
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### Set Image Margins with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Control the spacing between images using either a dimension resource or pixel values. This affects the horizontal swipe gallery appearance.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .withImagesMargin(R.dimen.image_margin) // e.g., 16dp
    .show()
```

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .withImageMarginPixels(32)
    .show()
```

--------------------------------

### Set Container Padding with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Adjust the padding around the image viewing area. Supports uniform padding via a dimension resource or individual sides using dimension resources or pixel values.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPadding(R.dimen.viewer_padding)
    .show()
```

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPadding(
        R.dimen.padding_start,
        R.dimen.padding_top,
        R.dimen.padding_end,
        R.dimen.padding_bottom
    )
    .show()
```

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withContainerPaddingPixels(16, 48, 16, 100) // Leave space for bottom overlay
    .show()
```

--------------------------------

### Set Custom Overlay View with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Use withOverlayView to add a custom view for image descriptions or actions. The overlay can be updated with image change events using withImageChangeListener.

```kotlin
class ImageOverlayView(context: Context) : ConstraintLayout(context) {
    var onShareClick: (Int) -> Unit = {}
    var onDeleteClick: (Int) -> Unit = {}

    init {
        inflate(context, R.layout.view_image_overlay, this)
        setBackgroundColor(Color.TRANSPARENT)
    }

    fun update(position: Int, totalCount: Int, description: String) {
        counterText.text = "${position + 1} / $totalCount"
        descriptionText.text = description
        shareButton.setOnClickListener { onShareClick(position) }
        deleteButton.setOnClickListener { onDeleteClick(position) }
    }
}

// Use overlay with viewer
val overlayView = ImageOverlayView(this).apply {
    onShareClick = { position -> shareImage(images[position]) }
    onDeleteClick = { position -> deleteImage(position) }
}

var viewer: StfalconImageViewer<ImageData>? = null

viewer = StfalconImageViewer.Builder<ImageData>(this, images) { view, data ->
    Glide.with(view).load(data.url).into(view)
}
    .withOverlayView(overlayView)
    .withImageChangeListener { position ->
        overlayView.update(position, images.size, images[position].description)
    }
    .show()
```

--------------------------------

### Set Image Margins

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Add spacing between images in the viewer using dimension resources or pixel values.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withImagesMargin(context, R.dimen.image_margin).show()
```

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withImageMarginPixels(16).show()
```

--------------------------------

### Control Status Bar Visibility with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Determine whether the status bar is hidden or shown during image viewing. It is hidden by default.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withHiddenStatusBar(false)
    .show()
```

--------------------------------

### currentPosition() / setCurrentPosition(position: Int) API

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Allows programmatic retrieval and setting of the current image's position within the viewer. This is beneficial for custom navigation controls, such as thumbnail strips or jump-to-image features.

```APIDOC
## currentPosition() / setCurrentPosition(position: Int)

### Description
Gets or sets the current image position programmatically. Useful for implementing custom navigation or thumbnail strips.

### Method
`currentPosition()` (GET)
`setCurrentPosition(position: Int)` (SET)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **position** (Int) - Required (for `setCurrentPosition`) - The index of the image to set as the current one.

### Request Example
```kotlin
// Setting current position
viewer?.setCurrentPosition(position)

// Getting current position
val position = viewer?.currentPosition() ?: -1
```

### Response
- **currentPosition()**: (Int) - The index of the currently displayed image.

#### Success Response (200)
- **position** (Int) - The current image index.

#### Response Example
```json
{
  "position": 5
}
```
```

--------------------------------

### Update Images List Dynamically

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Update the displayed images list while the viewer is active by calling `updateImages()`.

```java
viewer.updateImages(newImages);
```

--------------------------------

### Update Image List at Runtime

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Use `updateImages` to modify the displayed image list dynamically. This is useful for scenarios like pagination or filtering. If the new list is empty, the viewer closes automatically.

```kotlin
private var viewer: StfalconImageViewer<Photo>? = null
private val photos = mutableListOf<Photo>()

fun openViewer() {
    viewer = StfalconImageViewer.Builder<Photo>(this, photos) { view, photo ->
        Glide.with(view).load(photo.url).into(view)
    }.show()
}

// Delete current image
fun deleteCurrentImage() {
    val currentPosition = viewer?.currentPosition() ?: return
    photos.removeAt(currentPosition)
    viewer?.updateImages(photos) // Viewer closes if list becomes empty
}

// Load more images (pagination)
fun loadMoreImages(newPhotos: List<Photo>) {
    photos.addAll(newPhotos)
    viewer?.updateImages(photos)
}
```

--------------------------------

### Change Current Image Programmatically

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Navigate to a specific image in the viewer programmatically using `setCurrentPosition()`.

```java
viewer.setCurrentPosition(newPosition);
```

--------------------------------

### withImagesMargin(dimenRes: Int) / withImageMarginPixels(pixels: Int)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Sets the spacing between images when swiping horizontally through the gallery.

```APIDOC
## withImagesMargin(dimenRes: Int) / withImageMarginPixels(pixels: Int)

### Description
Sets the spacing between images when swiping horizontally through the gallery.

### Method
`withImagesMargin` or `withImageMarginPixels`

### Parameters
#### Path Parameters
- **dimenRes** (Int) - Required - The dimension resource ID for the image margin.
- **pixels** (Int) - Required - The image margin in pixels.

### Request Example
```kotlin
// Using dimension resource
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .withImagesMargin(R.dimen.image_margin) // e.g., 16dp
    .show()

// Using pixel value
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Glide.with(view).load(url).into(view)
}
    .withImageMarginPixels(32)
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### Set Container Padding

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Adjust the padding around the image container using dimension resources or pixel values.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withContainerPadding(context, R.dimen.padding_start, R.dimen.padding_top, R.dimen.padding_end, R.dimen.padding_bottom).show()
```

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withContainerPadding(context, R.dimen.all_sides_padding).show()
```

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withContainerPadding(10, 20, 10, 20).show()
```

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withContainerPadding(20).show()
```

--------------------------------

### Update Transition Target ImageView

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Use `updateTransitionImage(imageView: ImageView)` to set the target ImageView for the transition animation. Call this when the image changes to ensure the close animation correctly targets the corresponding thumbnail.

```kotlin
private lateinit var viewer: StfalconImageViewer<Photo>
private val thumbnailViews: List<ImageView> = // grid of thumbnail ImageViews

fun openViewer(startPosition: Int) {
    viewer = StfalconImageViewer.Builder<Photo>(this, photos) { view, photo ->
        Glide.with(view).load(photo.url).into(view)
    }
        .withStartPosition(startPosition)
        .withTransitionFrom(thumbnailViews[startPosition])
        .withImageChangeListener { position ->
            // Update transition target so close animation goes to correct thumbnail
            viewer.updateTransitionImage(thumbnailViews[position])
        }
        .show()
}
```

--------------------------------

### Set Background Color

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Customize the fading background color of the image viewer using resource ID or integer color value.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.setBackgroundColorRes(R.color.my_color).show()
```

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.setBackgroundColor(Color.parseColor("#FF0000")).show()
```

--------------------------------

### Enable/Disable Swipe to Dismiss with StfalconImageViewer

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Control the swipe-to-dismiss gesture for closing the viewer. This gesture is enabled by default.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .allowSwipeToDismiss(false)
    .show()
```

--------------------------------

### withHiddenStatusBar(hide: Boolean)

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Controls whether the status bar is hidden when the viewer is displayed. Hidden by default (true).

```APIDOC
## withHiddenStatusBar(hide: Boolean)

### Description
Controls whether the status bar is hidden when the viewer is displayed. Hidden by default (true).

### Method
`withHiddenStatusBar`

### Parameters
#### Path Parameters
- **hide** (Boolean) - Required - Set to `true` to hide the status bar, `false` to show it.

### Request Example
```kotlin
// Show status bar while viewing images
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withHiddenStatusBar(false)
    .show()
```

### Response
N/A (This method configures the viewer)
```

--------------------------------

### ImageLoader Interface Definition

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Defines the functional interface for loading images into ImageViews. Implement this to integrate with image loading libraries like Picasso, Glide, or Coil.

```java
public interface ImageLoader<T> {
    void loadImage(ImageView imageView, T image);
}
```

--------------------------------

### Control Status Bar Visibility

Source: https://github.com/stfalcon-studio/stfalconimageviewer/blob/master/README.md

Toggle the visibility of the status bar when the image viewer is displayed. It is hidden by default.

```java
StfalconImageViewer.Builder<Image>(context, images) {
    view, image ->
    Picasso.get().load(image.url).into(view)
}.withHiddenStatusBar(false).show()
```

--------------------------------

### updateImages API

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Updates the list of images displayed in the viewer at runtime. This is useful for scenarios like pagination, filtering, or dynamically removing images. If the updated image list becomes empty, the viewer will automatically close.

```APIDOC
## updateImages(images: List<T>)

### Description
Updates the image list at runtime. Useful for pagination, filtering, or deletion scenarios. If the new list is empty, the viewer closes automatically.

### Method
`updateImages`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **images** (List<T>) - Required - The new list of images to display in the viewer.

### Request Example
```kotlin
// Example of updating images
photos.addAll(newPhotos)
viewer?.updateImages(photos)
```

### Response
None directly from the method call, but the viewer's state is updated.

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Dismiss Listener for Viewer Closure

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Attaches a callback using `withDismissListener` that is triggered when the image viewer is closed, either by gesture or programmatically. Use this to restore application state.

```kotlin
StfalconImageViewer.Builder<String>(this, images) { view, url ->
    Picasso.get().load(url).into(view)
}
    .withDismissListener {
        Toast.makeText(this, "Viewer closed", Toast.LENGTH_SHORT).show()
        // Restore UI state, resume video, etc.
    }
    .show()
```

--------------------------------

### updateTransitionImage(imageView: ImageView) API

Source: https://context7.com/stfalcon-studio/stfalconimageviewer/llms.txt

Updates the target ImageView for the transition animation. This method should be called when the current image changes, ensuring that the closing animation correctly targets the corresponding thumbnail or originating view.

```APIDOC
## updateTransitionImage(imageView: ImageView)

### Description
Updates the transition target ImageView. Call this when the current position changes to ensure the close animation targets the correct thumbnail.

### Method
`updateTransitionImage`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **imageView** (ImageView) - Required - The ImageView to use as the target for the transition animation.

### Request Example
```kotlin
// Inside an image change listener
viewer.updateTransitionImage(thumbnailViews[position])
```

### Response
None directly from the method call, but the viewer's transition target is updated.

#### Success Response (200)
N/A

#### Response Example
N/A
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.