Package com.flowingcode.vaadin.addons.imagecrop

Class ImageCrop

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.react.ReactAdapterComponent
com.flowingcode.vaadin.addons.imagecrop.ImageCrop
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasStyle, Serializable
@NpmPackage(value="react-image-crop", version="11.0.6") @JsModule("./src/image-crop.tsx") @Tag("image-crop") @CssImport("react-image-crop/dist/ReactCrop.css") @CssImport("./styles/image-crop-styles.css") public class ImageCrop extends ReactAdapterComponent
Component for cropping images based on react-image-crop library. This component allows users to define and manipulate crop areas on images.
Author:
Paola De Bartolo / Flowing Code
See Also:

  • Constructor Details

    • ImageCrop

      public ImageCrop(String src)
      Constructs an ImageCrop component with the given image URL.
      Parameters:
      src - the URL of the image to be cropped

    • ImageCrop

      public ImageCrop(DownloadHandler downloadHandler)
      Constructs an ImageCrop component whose image is served by the given DownloadHandler. See setImageSrc(DownloadHandler) for the conditions under which the image is served.
      Parameters:
      downloadHandler - the handler that serves the image to be cropped
      See Also:

  • Method Details

    • addCroppedImageListener

      protected Registration addCroppedImageListener(ComponentEventListener<CroppedImageEvent> listener)
      Adds a listener for the CroppedImageEvent fired when the cropped image is updated.
      Parameters:
      listener - the listener to be added
      Returns:
      a registration for the listener, which can be used to remove the listener

    • onAttach

      protected void onAttach(AttachEvent attachEvent)
      Overrides:
      onAttach in class Component

    • setImageSrc

      public void setImageSrc(String imageSrc)
      Sets the source of the image to be cropped.
      Parameters:
      imageSrc - the image source

    • setImageSrc

      public void setImageSrc(DownloadHandler downloadHandler)
      Sets the source of the image to be cropped to a resource served by the given DownloadHandler.

      The handler is registered to this component, so the image is served while this component is attached and visible, independently of any other component. Requests are also rejected while this component is disabled or inert (for instance, behind a modal dialog), unless the handler overrides ElementRequestHandler.getDisabledUpdateMode() or ElementRequestHandler.isAllowInert().

      Use an inline() handler, since the image is displayed rather than downloaded. When the output MIME type is not set, it is detected from the file extension of the handler's URL postfix; handlers without one (such as DownloadHandler.fromInputStream(...)) fall back to image/png.

      As with any DownloadHandler set on an element, this method must be called while a UI is current.

      Parameters:
      downloadHandler - the handler that serves the image to be cropped

    • getImageSrc

      public String getImageSrc()
      Gets the source of the image being cropped.

      When the source was set with a DownloadHandler, this returns the internal URL of the registered resource. Passing that URL back to setImageSrc(String) unregisters the handler, so the URL stops being served.

      Returns:
      the image source

    • setImageAlt

      public void setImageAlt(String imageAlt)
      Sets the alternative information of the image to be cropped.
      Parameters:
      imageAlt - the image alternative information

    • getImageAlt

      public String getImageAlt()
      Gets the alternative information of the image being cropped.
      Returns:
      the image alternative information

    • setCrop

      public void setCrop(Crop crop)
      Defines the crop dimensions.

      A % crop is resolution-independent and is recommended for programmatic use. A px crop is interpreted in the image's source (natural) pixels, so the cropped output has a deterministic size regardless of how the image is scaled on screen (see issue #33). Note that this differs from the min/max crop constraints, which are expressed in rendered (on-screen) pixels.

      The configured x/y are only honored when the crop is set after the image has loaded. On the initial load the selection is centered on the image and its configured position is discarded; its size and the configured aspect ratio are honored in both cases.

      A % crop is measured against the image's natural size when the output is generated, but against its rendered box when the selection is drawn. Both agree as long as the rendered image keeps the source's aspect ratio; forcing both a width and a height on the image (or an object-fit that crops or stretches it) makes the on-screen selection diverge from the exported region.

      Parameters:
      crop - the crop dimensions

    • getCrop

      public Crop getCrop()
      Gets the crop dimensions.

      Once the image has loaded, the crop is normalized to a percentage of the image's natural size, so the returned unit is % even when setCrop(Crop) was given a px crop. Because Crop holds integer values, those percentages are rounded to whole units, which on a large image is coarser than the configured pixel values.

      Returns:
      the crop dimensions

    • setAspect

      public void setAspect(double aspect)
      Sets the aspect ratio of the crop. For example, 1 for a square or 16/9 for landscape.
      Parameters:
      aspect - the aspect ratio of the crop

    • getAspect

      public double getAspect()
      Gets the aspect ratio of the crop.
      Returns:
      the aspect ratio

    • setCircularCrop

      public void setCircularCrop(boolean circularCrop)
      Sets whether the crop area should be shown as a circle. If the aspect ratio is not 1, the circle will be warped into an oval shape. Defaults to false.
      Parameters:
      circularCrop - true to show the crop area as a circle, false otherwise

    • isCircularCrop

      public boolean isCircularCrop()
      Gets whether the crop area is shown as a circle.
      Returns:
      true if the crop area is a circle, false otherwise

    • setKeepSelection

      public void setKeepSelection(boolean keepSelection)
      Sets whether the selection can't be disabled if the user clicks outside the selection area. Defaults to false.
      Parameters:
      keepSelection - true so selection can't be disabled if the user clicks outside the selection area, false otherwise.

    • isKeepSelection

      public boolean isKeepSelection()
      Gets whether the selection is enabled.
      Returns:
      true if the selection is enabled, false otherwise

    • setDisabled

      public void setDisabled(boolean disabled)
      Sets whether the user cannot resize or draw a new crop. Defaults to false.
      Parameters:
      disabled - true to disable crop resizing and drawing, false otherwise

    • isDisabled

      public boolean isDisabled()
      Gets whether the crop resizing and drawing is disabled.
      Returns:
      true if disabled, false otherwise

    • setLocked

      public void setLocked(boolean locked)
      Sets whether the user cannot create or resize a crop, but can still drag the existing crop around. Defaults to false.
      Parameters:
      locked - true to lock the crop, false otherwise

    • isLocked

      public boolean isLocked()
      Gets whether the crop is locked.
      Returns:
      true if the crop is locked, false otherwise

    • setCropMinWidth

      public void setCropMinWidth(Integer minWidth)
      Sets a minimum crop width, in rendered (on-screen) pixels.

      This constraint is applied by react-image-crop in the image's displayed pixels, unlike a px crop, which is expressed in source (natural) pixels.

      Parameters:
      minWidth - the minimum crop width

    • getCropMinWidth

      public Integer getCropMinWidth()
      Gets the minimum crop width, in pixels.
      Returns:
      the minimum crop width

    • setCropMinHeight

      public void setCropMinHeight(Integer minHeight)
      Sets a minimum crop height, in pixels.
      Parameters:
      minHeight - the minimum crop height

    • getCropMinHeight

      public Integer getCropMinHeight()
      Gets the minimum crop height, in pixels.
      Returns:
      the minimum crop height

    • setCropMaxWidth

      public void setCropMaxWidth(Integer maxWidth)
      Sets a maximum crop width, in pixels.
      Parameters:
      maxWidth - the maximum crop width

    • getCropMaxWidth

      public Integer getCropMaxWidth()
      Gets the maximum crop width, in pixels.
      Returns:
      the maximum crop width

    • setCropMaxHeight

      public void setCropMaxHeight(Integer maxHeight)
      Sets a maximum crop height, in pixels.
      Parameters:
      maxHeight - the maximum crop height

    • getCropMaxHeight

      public Integer getCropMaxHeight()
      Gets the maximum crop height, in pixels.
      Returns:
      the maximum crop height

    • setRuleOfThirds

      public void setRuleOfThirds(boolean ruleOfThirds)
      Sets whether to show rule of thirds lines in the cropped area. Defaults to false.
      Parameters:
      ruleOfThirds - true to show rule of thirds lines, false otherwise

    • isRuleOfThirds

      public boolean isRuleOfThirds()
      Gets whether rule of thirds lines are shown in the cropped area.
      Returns:
      true if rule of thirds lines are shown, false otherwise

    • setOutputMimeType

      public void setOutputMimeType(String outputMimeType)
      Sets the MIME type used to encode the cropped image (for example "image/jpeg" or "image/png"). Supported types are image/png, image/jpeg and image/webp; any other or unsupported value falls back to image/png.

      When left unset, the output format is auto-detected from the image source (its data URL MIME type or file extension). Circular crops are always encoded in a transparency-capable format regardless of this setting.

      Parameters:
      outputMimeType - the MIME type used to encode the cropped image

    • getOutputMimeType

      public String getOutputMimeType()
      Gets the MIME type used to encode the cropped image, or null if it is auto-detected from the image source.
      Returns:
      the configured output MIME type, or null

    • setOutputQuality

      public void setOutputQuality(double outputQuality)
      Sets the encoding quality used for lossy output formats such as image/jpeg and image/webp. Ignored for image/png. Defaults to 1.0.
      Parameters:
      outputQuality - a value between 0 and 1
      Throws:
      IllegalArgumentException - if outputQuality is NaN or is outside the range [0, 1]

    • getOutputQuality

      public double getOutputQuality()
      Gets the encoding quality used for lossy output formats.
      Returns:
      the output quality, between 0 and 1

    • getCroppedImageDataUri

      public String getCroppedImageDataUri()
      Returns the cropped image data URI.

      When the component is created with a DownloadHandler, this is null until the image is cropped for the first time.

      Returns:
      the cropped image data URI, or null if not available yet

    • setImageFullHeight

      public void setImageFullHeight(Boolean fullHeight)
      Sets the image to occupy the full viewport height when enabled. If fullHeight is true, applies a CSS class that sets the image height to 100vh. If false, removes the class to revert to the default height.
      Parameters:
      fullHeight - whether the image should fill the viewport height

    • getCroppedImageBase64

      public byte[] getCroppedImageBase64()
      Decodes the cropped image data URI and returns it as a byte array. If the image data URI is not in the format "data:image/*;base64,", it will be decoded assuming it is a Base64 encoded string.

      This method incorporates work licensed under MIT. Copyright 2021-2023 David "F0rce" Dodlek https://github.com/F0rce/cropper

      Returns:
      byte[] the decoded byte array of the cropped image