add kdoc to enhanced zoom state and modifiers

Author: SmartToolFactory

app/src/main/java/com/smarttoolfactory/composeimage/demo/ZoomableImageDemo.kt

@@ -141,7 +141,6 @@ private fun ZoomableImageDemo(contentScale: ContentScale) {
             .fillMaxWidth()
             .aspectRatio(4 / 3f)
             .zoom(
-                Unit,
                 zoomState = rememberZoomState(
                     limitPan = false,
                     rotationEnabled = true

image/src/main/java/com/smarttoolfactory/image/zoom/EnhancedZoomModifier.kt

@@ -4,35 +4,64 @@ import androidx.compose.foundation.gestures.detectTapGestures
 import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.composed
+import androidx.compose.ui.draw.clipToBounds
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.input.pointer.pointerInput
 import com.smarttoolfactory.gesture.detectTransformGestures
 import com.smarttoolfactory.image.util.update
 import kotlinx.coroutines.launch
 
+/**
+ * Modifier that zooms in or out of Composable set to. This zoom modifier has option
+ * to move back to bounds with an animation or option to have fling gesture when user removes
+ * from screen while velocity is higher than threshold to have smooth touch effect.
+ *
+ * @param key is used for [Modifier.pointerInput] to restart closure when any keys assigned
+ * change
+ * @param consume flag to prevent other gestures such as scroll, drag or transform to get
+ * @param clip when set to true clips to parent bounds. Anything outside parent bounds is not
+ * drawn
+ * empty space on sides or edges of parent.
+ * @param enhancedZoomState State of the zoom that contains option to set initial, min, max zoom,
+ * enabling rotation, pan or zoom and contains current [ZoomData]
+ * event propagations
+ * @param onGestureStart callback to to notify gesture has started and return current
+ * [EnhancedZoomData]  of this modifier
+ * @param onGesture callback to notify about ongoing gesture and return current
+ * [EnhancedZoomData]  of this modifier
+ * @param onGestureEnd callback to notify that gesture finished return current
+ * [EnhancedZoomData]  of this modifier
+ */
 fun Modifier.enhancedZoom(
-    enhancedZoomState: EnhancedZoomState,
     key: Any? = Unit,
-    onDown: ((EnhancedZoomData) -> Unit)? = null,
-    onMove: ((EnhancedZoomData) -> Unit)? = null,
-    onUp: ((EnhancedZoomData) -> Unit)? = null,
+    consume: Boolean = true,
+    clip: Boolean = true,
+    enhancedZoomState: EnhancedZoomState,
+    onGestureStart: ((EnhancedZoomData) -> Unit)? = null,
+    onGesture: ((EnhancedZoomData) -> Unit)? = null,
+    onGestureEnd: ((EnhancedZoomData) -> Unit)? = null,
 ) = composed(
 
     factory = {
 
         val coroutineScope = rememberCoroutineScope()
 
-        val transformModifier = Modifier.pointerInput(key) {
+        val boundPan = enhancedZoomState.limitPan && !enhancedZoomState.rotationEnabled
+        val clipToBounds = (clip || boundPan)
 
+        val transformModifier = Modifier.pointerInput(key) {
+            // Pass size of this Composable this Modifier is attached for constraining operations
+            // inside this bounds
+            enhancedZoomState.size = this.size
             detectTransformGestures(
-                consume = true,
+                consume = consume,
                 onGestureStart = {
-                    onDown?.invoke(enhancedZoomState.enhancedZoomData)
+                    onGestureStart?.invoke(enhancedZoomState.enhancedZoomData)
                 },
                 onGestureEnd = {
                     coroutineScope.launch {
                         enhancedZoomState.onGestureEnd {
-                            onUp?.invoke(enhancedZoomState.enhancedZoomData)
+                            onGestureEnd?.invoke(enhancedZoomState.enhancedZoomData)
                         }
                     }
                 },
@@ -49,17 +78,20 @@ fun Modifier.enhancedZoom(
                         )
                     }
 
-                    onMove?.invoke(enhancedZoomState.enhancedZoomData)
+                    onGesture?.invoke(enhancedZoomState.enhancedZoomData)
                 }
             )
         }
 
         val tapModifier = Modifier.pointerInput(key) {
+            // Pass size of this Composable this Modifier is attached for constraining operations
+            // inside this bounds
+            enhancedZoomState.size = this.size
             detectTapGestures(
                 onDoubleTap = {
                     coroutineScope.launch {
                         enhancedZoomState.onDoubleTap {
-                            onUp?.invoke(enhancedZoomState.enhancedZoomData)
+                            onGestureEnd?.invoke(enhancedZoomState.enhancedZoomData)
                         }
                     }
                 }
@@ -71,7 +103,7 @@ fun Modifier.enhancedZoom(
         }
 
         this.then(
-            Modifier
+            (if (clipToBounds) Modifier.clipToBounds() else Modifier)
                 .then(tapModifier)
                 .then(transformModifier)
                 .then(graphicsModifier)
@@ -80,8 +112,8 @@ fun Modifier.enhancedZoom(
     inspectorInfo = {
         name = "enhancedZoom"
         // add name and value of each argument
-        properties["onDown"] = onDown
-        properties["onMove"] = onMove
-        properties["onUp"] = onUp
+        properties["onDown"] = onGestureStart
+        properties["onMove"] = onGesture
+        properties["onUp"] = onGestureEnd
     }
 )

image/src/main/java/com/smarttoolfactory/image/zoom/EnhancedZoomState.kt

@@ -2,34 +2,48 @@ package com.smarttoolfactory.image.zoom
 
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.IntSize
 
 /**
- * * Create and [remember] the [ZoomState] based on the currently appropriate transform
+ * Create and [remember] the [EnhancedZoomState] based on the currently appropriate transform
  * configuration to allow changing pan, zoom, and rotation.
  *
+ * Allows to change zoom, pan,  translate, or get current state by
+ * calling methods on this object. To be hosted and passed to [Modifier.enhancedZoom].
+ * Also contains [EnhancedZoomData] about current transformation area of Composable and
+ * visible are of image being zoomed, rotated, or panned. If any animation
+ * is going on current [EnhancedZoomState.isAnimationRunning] is true
+ * and [EnhancedZoomData] returns rectangle
+ * that belongs to end of animation.
+ *
  *  [key1] is used to reset remember block to initial calculations. This can be used
  * when image, contentScale or any property changes which requires values to be reset to initial
  * values
- *
  * @param initialZoom zoom set initially
- * @param initialRotation rotation set initially
- * @param minZoom minimum zoom value this Composable can possess
- * @param maxZoom maximum zoom value this Composable can possess
- * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
- * empty space on sides or edges of parent
+ * @param minZoom minimum zoom value
+ * @param maxZoom maximum zoom value
+ * @param flingGestureEnabled when set to true dragging pointer builds up velocity. When last
+ * pointer leaves Composable a movement invoked against friction till velocity drops down
+ * to threshold
+ * @param moveToBoundsEnabled when set to true if image zoom is lower than initial zoom or
+ * panned out of image boundaries moves back to bounds with animation.
+ * ##Note
+ * Currently rotating back to borders is not available
  * @param zoomEnabled when set to true zoom is enabled
  * @param panEnabled when set to true pan is enabled
  * @param rotationEnabled when set to true rotation is enabled
+ * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
+ * empty space on sides or edges of parent
  */
 @Composable
 fun rememberEnhancedZoomState(
     imageSize: IntSize,
-    containerSize: IntSize,
     initialZoom: Float = 1f,
-    initialRotation: Float = 0f,
     minZoom: Float = 1f,
     maxZoom: Float = 5f,
+    flingGestureEnabled: Boolean = false,
+    moveToBoundsEnabled: Boolean = true,
     zoomEnabled: Boolean = true,
     panEnabled: Boolean = true,
     rotationEnabled: Boolean = false,
@@ -39,10 +53,11 @@ fun rememberEnhancedZoomState(
     return remember(key1) {
         EnhancedZoomState(
             imageSize = imageSize,
-            containerSize = containerSize,
             initialZoom = initialZoom,
             minZoom = minZoom,
             maxZoom = maxZoom,
+            flingGestureEnabled = flingGestureEnabled,
+            moveToBoundsEnabled = moveToBoundsEnabled,
             zoomEnabled = zoomEnabled,
             panEnabled = panEnabled,
             rotationEnabled = rotationEnabled,
@@ -52,29 +67,44 @@ fun rememberEnhancedZoomState(
 }
 
 /**
- * * Create and [remember] the [ZoomState] based on the currently appropriate transform
+ * Create and [remember] the [EnhancedZoomState] based on the currently appropriate transform
  * configuration to allow changing pan, zoom, and rotation.
  *
+ * Allows to change zoom, pan,  translate, or get current state by
+ * calling methods on this object. To be hosted and passed to [Modifier.enhancedZoom].
+ * Also contains [EnhancedZoomData] about current transformation area of Composable and
+ * visible are of image being zoomed, rotated, or panned. If any animation
+ * is going on current [EnhancedZoomState.isAnimationRunning] is true
+ * and [EnhancedZoomData] returns rectangle
+ * that belongs to end of animation.
+ *
  *  [key1] or [key2] are used to reset remember block to initial calculations. This can be used
  * when image, contentScale or any property changes which requires values to be reset to initial
  * values
- *
  * @param initialZoom zoom set initially
- * @param minZoom minimum zoom value this Composable can possess
- * @param maxZoom maximum zoom value this Composable can possess
- * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
- * empty space on sides or edges of parent
+ * @param minZoom minimum zoom value
+ * @param maxZoom maximum zoom value
+ * @param flingGestureEnabled when set to true dragging pointer builds up velocity. When last
+ * pointer leaves Composable a movement invoked against friction till velocity drops down
+ * to threshold
+ * @param moveToBoundsEnabled when set to true if image zoom is lower than initial zoom or
+ * panned out of image boundaries moves back to bounds with animation.
+ * ##Note
+ * Currently rotating back to borders is not available
  * @param zoomEnabled when set to true zoom is enabled
  * @param panEnabled when set to true pan is enabled
  * @param rotationEnabled when set to true rotation is enabled
+ * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
+ * empty space on sides or edges of parent
  */
 @Composable
 fun rememberEnhancedZoomState(
     imageSize: IntSize,
-    containerSize: IntSize,
     initialZoom: Float = 1f,
     minZoom: Float = 1f,
     maxZoom: Float = 5f,
+    flingGestureEnabled: Boolean = false,
+    moveToBoundsEnabled: Boolean = true,
     zoomEnabled: Boolean = true,
     panEnabled: Boolean = true,
     rotationEnabled: Boolean = false,
@@ -85,10 +115,11 @@ fun rememberEnhancedZoomState(
     return remember(key1, key2) {
         EnhancedZoomState(
             imageSize = imageSize,
-            containerSize = containerSize,
             initialZoom = initialZoom,
             minZoom = minZoom,
             maxZoom = maxZoom,
+            flingGestureEnabled = flingGestureEnabled,
+            moveToBoundsEnabled = moveToBoundsEnabled,
             zoomEnabled = zoomEnabled,
             panEnabled = panEnabled,
             rotationEnabled = rotationEnabled,
@@ -98,28 +129,44 @@ fun rememberEnhancedZoomState(
 }
 
 /**
- * * Create and [remember] the [ZoomState] based on the currently appropriate transform
+ * Create and [remember] the [EnhancedZoomState] based on the currently appropriate transform
  * configuration to allow changing pan, zoom, and rotation.
  *
+ * Allows to change zoom, pan,  translate, or get current state by
+ * calling methods on this object. To be hosted and passed to [Modifier.enhancedZoom].
+ * Also contains [EnhancedZoomData] about current transformation area of Composable and
+ * visible are of image being zoomed, rotated, or panned. If any animation
+ * is going on current [EnhancedZoomState.isAnimationRunning] is true
+ * and [EnhancedZoomData] returns rectangle
+ * that belongs to end of animation.
+ *
  * @param initialZoom zoom set initially
- * @param minZoom minimum zoom value this Composable can possess
- * @param maxZoom maximum zoom value this Composable can possess
- * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
- * empty space on sides or edges of parent
+ * @param minZoom minimum zoom value
+ * @param maxZoom maximum zoom value
+ * @param flingGestureEnabled when set to true dragging pointer builds up velocity. When last
+ * pointer leaves Composable a movement invoked against friction till velocity drops down
+ * to threshold
+ * @param moveToBoundsEnabled when set to true if image zoom is lower than initial zoom or
+ * panned out of image boundaries moves back to bounds with animation.
+ * ##Note
+ * Currently rotating back to borders is not available
  * @param zoomEnabled when set to true zoom is enabled
  * @param panEnabled when set to true pan is enabled
  * @param rotationEnabled when set to true rotation is enabled
+ * @param limitPan limits pan to bounds of parent Composable. Using this flag prevents creating
+ * empty space on sides or edges of parent
  * @param keys are used to reset remember block to initial calculations. This can be used
  * when image, contentScale or any property changes which requires values to be reset to initial
  * values
  */
 @Composable
 fun rememberEnhancedZoomState(
     imageSize: IntSize,
-    containerSize: IntSize,
     initialZoom: Float = 1f,
     minZoom: Float = 1f,
     maxZoom: Float = 5f,
+    flingGestureEnabled: Boolean = false,
+    moveToBoundsEnabled: Boolean = true,
     zoomEnabled: Boolean = true,
     panEnabled: Boolean = true,
     rotationEnabled: Boolean = false,
@@ -129,14 +176,15 @@ fun rememberEnhancedZoomState(
     return remember(keys) {
         EnhancedZoomState(
             imageSize = imageSize,
-            containerSize = containerSize,
             initialZoom = initialZoom,
             minZoom = minZoom,
             maxZoom = maxZoom,
+            flingGestureEnabled = flingGestureEnabled,
+            moveToBoundsEnabled = moveToBoundsEnabled,
             zoomEnabled = zoomEnabled,
             panEnabled = panEnabled,
             rotationEnabled = rotationEnabled,
             limitPan = limitPan
         )
     }
-}
+}