PhotoView Deployment and Usage Guide

Prerequisites

Android Development Environment
- Android Studio (recommended) or equivalent IDE
- Android SDK with API level 16+ (Android 4.1 Jelly Bean)
- Java Development Kit (JDK) 8 or higher
Project Dependencies
- Gradle build system
- AndroidX libraries (for AppCompatImageView support)

Installation

Adding to Your Android Project

Add JitPack Repository

Add the JitPack repository to your root build.gradle file (not your module build.gradle):

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

buildscript {
    repositories {
        maven { url "https://www.jitpack.io" }
    }	
}

Add PhotoView Dependency

Add the PhotoView library to your module build.gradle:

dependencies {
    implementation 'com.github.chrisbanes:PhotoView:latest.release.here'
}

Sync Project

Sync your Gradle project to download the dependency.

Cloning the Repository (for Development)

git clone https://github.com/chrisbanes/PhotoView.git
cd PhotoView

Configuration

XML Layout Configuration

Add the PhotoView to your layout XML:

<com.github.chrisbanes.photoview.PhotoView
    android:id="@+id/photo_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Java/Kotlin Configuration

PhotoView photoView = (PhotoView) findViewById(R.id.photo_view);
photoView.setImageResource(R.drawable.image);

Handling ViewGroup Issues

For ViewGroups that use onInterceptTouchEvent (like ViewPager or DrawerLayout), extend them to handle exceptions:

public class HackyProblematicViewGroup extends ProblematicViewGroup {

    public HackyProblematicViewGroup(Context context) {
        super(context);
    }

    @Override
    public boolean onInterceptTouchEvent(MotionEvent ev) {
        try {
            return super.onInterceptTouchEvent(ev);
        } catch (IllegalArgumentException e) {
            return false;
        }
    }
}

Build & Run

Building the Library

Open in Android Studio
- Open the cloned repository in Android Studio
- Let Gradle sync and build the project

Build Commands

# From the project root
./gradlew build

Running the Sample App

Select Sample Module
- In Android Studio, select the sample module from the project structure
Run on Device/Emulator
- Connect an Android device or start an emulator
- Click the "Run" button (green play icon) or use the shortcut: Shift+F10
Sample Features
- The sample demonstrates various PhotoView features including:
  - Basic zooming and panning
  - Matrix change listeners
  - Photo tap detection
  - Single fling detection

Deployment

Publishing Your App with PhotoView

Since PhotoView is a library dependency, deployment follows standard Android app deployment practices:

Build Release APK
```
./gradlew assembleRelease
```
Sign Your APK
- Use Android Studio's Build > Generate Signed Bundle/APK
- Or use Gradle signing configurations
Deploy to App Stores
- Google Play Store: Upload your signed APK through the Google Play Console
- Alternative Stores: Follow respective store guidelines for APK submission

Distribution Options

Google Play Store: Primary distribution channel for Android apps
Direct APK Distribution: Share APK files directly with users
Enterprise Deployment: Use Android Enterprise features for internal app distribution

Troubleshooting

Common Issues and Solutions

1. JitPack Repository Not Found

Issue: Build fails with "Could not find com.github.chrisbanes:PhotoView:latest.release.here" Solution: Ensure JitPack repository is added to both allprojects.repositories and buildscript.repositories in root build.gradle

2. ViewGroup Exceptions with PhotoView

Issue: IllegalArgumentException when using PhotoView inside ViewPager or DrawerLayout Solution: Extend the problematic ViewGroup and catch the exception as shown in the HackyDrawerLayout example

3. Image Not Displaying

Issue: PhotoView shows empty or doesn't load images Solution:

Verify image resource exists and is accessible
Check that PhotoView is properly initialized before setting image
Ensure correct context is used when loading images

4. Zoom Not Working

Issue: Image doesn't zoom when pinched Solution:

Verify PhotoView is properly initialized
Check that the image has sufficient resolution for zooming
Ensure no parent view is intercepting touch events

5. Compatibility Issues

Issue: PhotoView not working on older Android versions Solution:

PhotoView supports API level 16+, ensure your minSdkVersion is set accordingly
Use AppCompatImageView as base class for backward compatibility

6. Fresco Integration

Issue: PhotoView doesn't work with Fresco Solution: Use alternative solutions like PhotoDraweeView for Fresco integration

7. Subsampling Large Images

Issue: Performance issues with very large images Solution: Use subsampling libraries like Subsampling Scale Image View for better performance with large images

Debug Tips

Enable logging to track PhotoView events
Use Android Studio's Layout Inspector to verify PhotoView hierarchy
Test on multiple device configurations to ensure compatibility
Check touch event propagation in complex layouts

Performance Considerations

For very large images, consider using subsampling libraries
Monitor memory usage when loading high-resolution images
Test scrolling performance when PhotoView is in a scrollable container

How to Deploy & Use chrisbanes/PhotoView