Pr/cropper text label support

CHANGELOG.md

@@ -13,6 +13,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Fixed
 - The translation of `Camera` and `Gallery` does not exist in some languages.
 
+## [unreleased 4.2.2]
+### Added
+- Added a helper text on top of crop overlay which moves along with it. [#381](https://github.com/CanHub/Android-Image-Cropper/issues/381)
+### Fixed
+- Crash on click of Sample of CustomActivity option over sample App, added the missing activity declaration on Manifest.xml
+
 ## [4.2.1] - 04/04/2022
 ### Added
 - Added support for optionally displaying an intent chooser when selecting image source. [#325](https://github.com/CanHub/Android-Image-Cropper/issues/325)

cropper/src/main/java/com/canhub/cropper/CropImageContractOptions.kt

@@ -127,6 +127,11 @@ data class CropImageContractOptions @JvmOverloads constructor(
         return this
     }
 
+    fun setShowCropLabel(showCropLabel: Boolean): CropImageContractOptions {
+        cropImageOptions.showCropLabel = showCropLabel
+        return this
+    }
+
     /**
      * if auto-zoom functionality is enabled.<br></br>
      * default: true.

cropper/src/main/java/com/canhub/cropper/CropImageOptions.kt

@@ -83,6 +83,12 @@ open class CropImageOptions : Parcelable {
     @JvmField
     var showCropOverlay: Boolean
 
+    /**
+     * If enabled, show a text label on top of crop overlay UI, which gets moved along with the cropper
+     */
+    @JvmField
+    var showCropLabel: Boolean
+
     /**
      * if to show progress bar when image async loading/cropping is in progress.<br></br>
      * default: true, disable to provide custom progress bar UI.
@@ -311,6 +317,18 @@ open class CropImageOptions : Parcelable {
     @JvmField
     var intentChooserPriorityList: List<String>?
 
+    /** The initial text size of cropper label **/
+    @JvmField
+    var cropperLabelTextSize: Float
+
+    /** The default cropper label text color **/
+    @JvmField
+    var cropperLabelTextColor: Int
+
+    /** The default cropper label text **/
+    @JvmField
+    var cropperLabelText: String? = ""
+
     /** Init options with defaults.  */
     constructor() {
         val dm = Resources.getSystem().displayMetrics
@@ -373,6 +391,9 @@ open class CropImageOptions : Parcelable {
         showIntentChooser = false
         intentChooserTitle = null
         intentChooserPriorityList = listOf()
+        cropperLabelTextSize = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_SP, 20f, dm)
+        cropperLabelTextColor = Color.WHITE
+        showCropLabel = false
     }
 
     /** Create object from parcel.  */
@@ -435,6 +456,10 @@ open class CropImageOptions : Parcelable {
         showIntentChooser = parcel.readByte().toInt() != 0
         intentChooserTitle = parcel.readString()
         intentChooserPriorityList = parcel.createStringArrayList()
+        cropperLabelTextSize = parcel.readFloat()
+        cropperLabelTextColor = parcel.readInt()
+        cropperLabelText = parcel.readString()!!
+        showCropLabel = parcel.readByte().toInt() != 0
     }
 
     override fun writeToParcel(dest: Parcel, flags: Int) {
@@ -496,6 +521,10 @@ open class CropImageOptions : Parcelable {
         dest.writeByte((if (showIntentChooser) 1 else 0).toByte())
         dest.writeString(intentChooserTitle)
         dest.writeStringList(intentChooserPriorityList)
+        dest.writeFloat(cropperLabelTextSize)
+        dest.writeInt(cropperLabelTextColor)
+        dest.writeString(cropperLabelText)
+        dest.writeByte((if (showCropLabel) 1 else 0).toByte())
     }
 
     override fun describeContents(): Int {

cropper/src/main/java/com/canhub/cropper/CropImageView.kt

@@ -5,6 +5,7 @@ import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.Bitmap.CompressFormat
 import android.graphics.BitmapFactory
+import android.graphics.Color
 import android.graphics.Matrix
 import android.graphics.Rect
 import android.graphics.RectF
@@ -105,6 +106,29 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
      */
     private var mShowCropOverlay = true
 
+    /** If true, shows a helper text label over crop overlay UI
+     *  default: false
+     */
+    private var mShowCropLabel = false
+
+    /**
+     * Helper text label over crop overlay UI
+     * default: empty string
+     */
+    private var mCropTextLabel = ""
+
+    /**
+     * Text size for text label over crop overlay UI
+     * default: 20sp
+     */
+    private var mCropLabelTextSize = 20f
+
+    /**
+     * Text color for text label over crop overlay UI
+     * default: White
+     */
+    private var mCropLabelTextColor = Color.WHITE
+
     /**
      * if to show progress bar when image async loading/cropping is in progress.<br></br>
      * default: true, disable to provide custom progress bar UI.
@@ -403,6 +427,35 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
                 setCropOverlayVisibility()
             }
         }
+    /**
+     * If enabled, show a text label on top of crop overlay UI, which gets moved along with the cropper
+     */
+    var isShowCropLabel: Boolean
+        get() = mShowCropLabel
+        set(showCropLabel) {
+            if (mShowCropLabel != showCropLabel) {
+                mShowCropLabel = showCropLabel
+                mCropOverlayView?.setCropperTextLabelVisibility(mShowCropLabel)
+            }
+        }
+    var cropLabelText: String
+        get() = mCropTextLabel
+        set(cropLabelText) {
+            mCropTextLabel = cropLabelText
+            mCropOverlayView?.setCropLabelText(cropLabelText)
+        }
+    var cropLabelTextSize: Float
+        get() = mCropLabelTextSize
+        set(textSize) {
+            mCropLabelTextSize = cropLabelTextSize
+            mCropOverlayView?.setCropLabelTextSize(textSize)
+        }
+    var cropLabelTextColor: Int
+        get() = mCropLabelTextColor
+        set(cropLabelTextColor) {
+            mCropLabelTextColor = cropLabelTextColor
+            mCropOverlayView?.setCropLabelTextColor(cropLabelTextColor)
+        }
     /** Returns the integer of the imageResource  */
     /**
      * Sets a Drawable as the content of the CropImageView.
@@ -1037,7 +1090,7 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
         bundle.putInt("CROP_MAX_ZOOM", mMaxZoom)
         bundle.putBoolean("CROP_FLIP_HORIZONTALLY", mFlipHorizontally)
         bundle.putBoolean("CROP_FLIP_VERTICALLY", mFlipVertically)
-
+        bundle.putBoolean("SHOW_CROP_LABEL", mShowCropLabel)
         return bundle
     }
 
@@ -1088,6 +1141,8 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
                 mMaxZoom = state.getInt("CROP_MAX_ZOOM")
                 mFlipHorizontally = state.getBoolean("CROP_FLIP_HORIZONTALLY")
                 mFlipVertically = state.getBoolean("CROP_FLIP_VERTICALLY")
+                mShowCropLabel = state.getBoolean("SHOW_CROP_LABEL")
+                mCropOverlayView.setCropperTextLabelVisibility(mShowCropLabel)
             }
             super.onRestoreInstanceState(state.getParcelable("instanceState"))
         } else {
@@ -1882,6 +1937,21 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
                         R.styleable.CropImageView_cropFlipHorizontally,
                         options.flipVertically
                     )
+                    options.cropperLabelTextSize = ta.getDimension(
+                        R.styleable.CropImageView_cropperLabelTextSize,
+                        options.cropperLabelTextSize
+                    )
+                    options.cropperLabelTextColor = ta.getInteger(
+                        R.styleable.CropImageView_cropperLabelTextColor,
+                        options.cropperLabelTextColor
+                    )
+                    options.cropperLabelText = ta.getString(
+                        R.styleable.CropImageView_cropperLabelText
+                    )
+                    options.showCropLabel = ta.getBoolean(
+                        R.styleable.CropImageView_cropShowLabel,
+                        options.showCropLabel
+                    )
                     isSaveBitmapToInstanceState = ta.getBoolean(
                         R.styleable.CropImageView_cropSaveBitmapToInstanceState,
                         isSaveBitmapToInstanceState
@@ -1902,6 +1972,8 @@ class CropImageView @JvmOverloads constructor(context: Context, attrs: Attribute
         mScaleType = options.scaleType
         mAutoZoomEnabled = options.autoZoomEnabled
         mMaxZoom = options.maxZoom
+        mCropLabelTextSize = options.cropperLabelTextSize
+        mShowCropLabel = options.showCropLabel
         mShowCropOverlay = options.showCropOverlay
         mShowProgressBar = options.showProgressBar
         mFlipHorizontally = options.flipHorizontally

cropper/src/main/java/com/canhub/cropper/CropOverlayView.kt

@@ -34,6 +34,16 @@ class CropOverlayView
 
     companion object {
 
+        /**
+         * Creates the paint object for drawing text label over crop overlay */
+        private fun getTextPaint(options: CropImageOptions): Paint =
+            Paint().apply {
+                strokeWidth = 1f
+                textSize = options.cropperLabelTextSize
+                style = Paint.Style.FILL
+                textAlign = Paint.Align.CENTER
+                this.color = options.cropperLabelTextColor
+            }
         /** Creates the Paint object for drawing.  */
         private fun getNewPaint(color: Int): Paint =
             Paint().apply {
@@ -92,6 +102,8 @@ class CropOverlayView
     /** The Paint used to darken the surrounding areas outside the crop area.  */
     private var mBackgroundPaint: Paint? = null
 
+    private var textLabelPaint: Paint? = null
+
     /** Used for oval crop window shape or non-straight rotation drawing.  */
     private val mPath = Path()
 
@@ -164,6 +176,14 @@ class CropOverlayView
     var cornerShape: CropImageView.CropCornerShape? = null
         private set
 
+    /** To show the text label over crop overlay **/
+    private var isCropLabelEnabled: Boolean = false
+    /** Text to show over text label over crop overlay */
+    private var cropLabelText: String = ""
+    /** Text color to apply over text label over crop overlay */
+    private var cropLabelTextSize: Float = 20f
+    /** Text color to apply over text label over crop overlay */
+    private var cropLabelTextColor = Color.WHITE
     /** the initial crop window rectangle to set  */
     private val mInitialCropWindowRect = Rect()
 
@@ -253,7 +273,37 @@ class CropOverlayView
             invalidate()
         }
     }
+    /**
+     * Sets the cropper label if it is enabled
+     */
+    fun setCropperTextLabelVisibility(isEnabled: Boolean) {
+        this.isCropLabelEnabled = isEnabled
+        invalidate()
+    }
+
+    /**
+     * Sets the copy text for cropper text
+     */
+    fun setCropLabelText(textLabel: String?) {
+        textLabel?.let {
+            this.cropLabelText = it
+        }
+    }
 
+    /**
+     * Sets the text size for cropper text
+     */
+    fun setCropLabelTextSize(textSize: Float) {
+        this.cropLabelTextSize = textSize
+        invalidate()
+    }
+    /**
+     * Sets the text color for cropper text
+     */
+    fun setCropLabelTextColor(textColor: Int) {
+        this.cropLabelTextColor = textColor
+        invalidate()
+    }
     /**
      * Sets the guidelines for the CropOverlayView to be either on, off, or to show when resizing the
      * application.
@@ -410,6 +460,10 @@ class CropOverlayView
     fun setInitialAttributeValues(options: CropImageOptions) {
         mOptions = options
         mCropWindowHandler.setInitialAttributeValues(options)
+        setCropLabelTextColor(options.cropperLabelTextColor)
+        setCropLabelTextSize(options.cropperLabelTextSize)
+        setCropLabelText(options.cropperLabelText)
+        setCropperTextLabelVisibility(options.showCropLabel)
         setCropCornerRadius(options.cropCornerRadius)
         setCropCornerShape(options.cornerShape)
         setCropShape(options.cropShape)
@@ -430,6 +484,7 @@ class CropOverlayView
             getNewPaintOrNull(options.borderCornerThickness, options.borderCornerColor)
         mGuidelinePaint = getNewPaintOrNull(options.guidelinesThickness, options.guidelinesColor)
         mBackgroundPaint = getNewPaint(options.backgroundColor)
+        textLabelPaint = getTextPaint(options)
     }
 
     /**
@@ -570,10 +625,26 @@ class CropOverlayView
         }
         // To retain the changes in Paint object when the App goes background this is required
         mBorderCornerPaint = getNewPaintOrNull(mOptions?.borderCornerThickness ?: 0.0f, mOptions?.borderCornerColor ?: Color.WHITE)
+        drawCropLabelText(canvas)
         drawBorders(canvas)
         drawCorners(canvas)
     }
 
+    /** Draws a text label (which can acts an helper text) on top of crop overlay **/
+    private fun drawCropLabelText(canvas: Canvas) {
+        if (isCropLabelEnabled) {
+            val rect = mCropWindowHandler.getRect()
+            var xCoordinate = (rect.left + rect.right) / 2
+            var yCoordinate = rect.top - 50
+            textLabelPaint?.apply {
+                textSize = cropLabelTextSize
+                color = cropLabelTextColor
+            }
+            canvas.drawText(cropLabelText, xCoordinate, yCoordinate, textLabelPaint!!)
+            canvas.save()
+        }
+    }
+
     /** Draw shadow background over the image not including the crop area.  */
     private fun drawBackground(canvas: Canvas) {
         val rect = mCropWindowHandler.getRect()

cropper/src/main/res/values/attrs.xml

@@ -54,6 +54,10 @@
         <attr name="cropFlipVertically" format="boolean"/>
         <attr name="cropCornerCircleFillColor" format="color"/>
         <attr name="cropCornerRadius" format="dimension"/>
+        <attr name="cropperLabelTextSize" format="float"/>
+        <attr name="cropperLabelTextColor" format="color"/>
+        <attr name="cropperLabelText" format="string"/>
+        <attr name="cropShowLabel" format="boolean"/>
     </declare-styleable>
 
 </resources>

sample/src/main/AndroidManifest.xml

@@ -20,7 +20,7 @@
         <activity android:name="com.canhub.cropper.sample.SampleResultScreen" />
         <activity android:name="com.canhub.cropper.CropImageActivity" />
         <activity
-            android:name="com.canhub.cropper.sample.extend_activity.app.SExtendActivity"
+            android:name="com.canhub.cropper.sample.SampleCustomActivity"
             android:theme="@style/Theme.SampleNoActionBar" />
 
     </application>

sample/src/main/java/com/canhub/cropper/sample/SampleUsingImageView.kt

@@ -106,6 +106,7 @@ internal class SampleUsingImageView :
             maxZoom = options.maxZoomLvl
             isFlippedHorizontally = options.flipHorizontal
             isFlippedVertically = options.flipVertically
+            isShowCropLabel = options.showCropLabel
         }
 
         if (options.scaleType == CropImageView.ScaleType.CENTER_INSIDE)
@@ -191,6 +192,7 @@ internal class SampleUsingImageView :
         showCropOverlay = true,
         showProgressBar = true,
         flipHorizontal = false,
-        flipVertically = false
+        flipVertically = false,
+        showCropLabel = false
     )
 }