Class UIImage2

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.UIComp
com.iizix.prop.ui.UIImage2
All Implemented Interfaces:
EventListener, IFocusComp, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IUIComp, IUIContextMenuOwner, IUIFocusComp, IVSComponentListener, IVSComponentState, IVSFieldListener, Cloneable
Direct Known Subclasses:
EUIImage2
public class UIImage2 extends UIComp implements IUIFocusComp, IUIContextMenuOwner
Image Crop and Upload UI component.

The image file the user picks or drops is uploaded over HTTPS through the upload service of the client session, as the original file, as soon as it passes the pixel check: the client raises the remote event REMOTE_REQUEST with the upload channel's request, which this component reserves for one PNG or JPEG file no larger than the maximum file size, narrowed to UPLOAD_TYPES so that a disguised file fails verification. When the file has been received and verified, the client raises event 1 naming the reservation, and the listeners' IUIImage2Listener.onImageSelection(UIImage2, String, ImageType, byte[], int, int, ImageOrientation, double, GRect, boolean) is called with the bytes of the verified file, which is then deleted. Crop, zoom and orientation are properties and never upload again. The upload in flight is cancelled when the value is replaced from the server (REASON_REPLACED) and when the component is disposed of (REASON_DISPOSED).

Where the client session cannot upload - the server does not allow uploads ($upload.allow), or the client has no upload channel - the client sends the file over the WebSocket as the value of the component, as before, and it is accepted only there, bounded by the maximum file size.

Author:
Christopher Mindus

  • Field Details

    • DEFAULT_VIEWPORT_SIZE

      public static final GSize DEFAULT_VIEWPORT_SIZE
      The default viewport size: 100x100.

    • DEFAULT_SUPPORTED_IMAGE_TYPES

      public static final String DEFAULT_SUPPORTED_IMAGE_TYPES
      The default supported image types and file etensions: ".jpg,.jpeg,image/jpeg,.png,image/png".
      See Also:

    • REMOTE_REQUEST

      public static final int REMOTE_REQUEST
      The remote event of the client asking to upload the image file the user picked: its parameters are the upload channel's request (UploadChannelProps.encodeReserve(int, List, boolean, String)). Event 1 (image selected) and event 2 (crop, zoom or orientation changed) are older.
      See Also:

    • UPLOAD_TYPES

      public static final String UPLOAD_TYPES
      The media types an image file is uploaded as, whatever the supported image types say: "image/png,image/jpeg". The reservation is narrowed to them on the verified type.
      See Also:

    • REASON_REPLACED

      public static final String REASON_REPLACED
      The reason the upload in flight is cancelled with when the value of the component is replaced from the server, by code or a VirtualSpace: "replaced".
      See Also:

    • REASON_DISPOSED

      public static final String REASON_DISPOSED
      The reason the upload in flight is cancelled with when the component is disposed of: "disposed".
      See Also:

  • Constructor Details

    • UIImage2

      public UIImage2()
      Creates the component without a name. The name must be set in all cases using the setPropertyAtom call.

    • UIImage2

      public UIImage2(Atom propertyAtom)
      Creates the component with the specified name. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - the name of the component, unique within it's parent.

    • UIImage2

      public UIImage2(Atom propertyAtom, GProp<?>[] newValue) throws PropException
      Creates the component with the specified name, initialized to contain the GProp items. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - The name of the component, unique within it's parent.
      newValue - The array of all properties the component should have.
      Throws:
      PropException - when at least one of the properties to initialize the component with is invalid.

  • Method Details

    • clone

      public UIImage2 clone()
      Creates a clone out of this property. The cloning is overridden by the subclasses in order to handle cloning of its class variables appropriately.

      Cloning is used for "virtualization" of a property tree in the server. Client property classes will therefore throw CloneNotSupportedException.

      Once a tree has been cloned, the change-flag is reset, and the create-flag is set. All listeners are also removed! The new cloned property is an orphan, i.e. has no parent set. All children properties are also (deep) cloned.

      Note that the cloning process is done WITHOUT thread synchronization for performance reasons, thus no modifications should be done to the tree!

      Overrides:
      clone in class UIComp

    • shouldSerializeToXML

      protected boolean shouldSerializeToXML(int programType, GProp<?> childProp)
      Method used to check for child property serialization to XML. Override this method and return false to avoid writing the child property to XML. The default is to write all properties.
      Overrides:
      shouldSerializeToXML in class PropCnr
      Parameters:
      programType - From PropFactory.getProgramType(): 0=PropFactory.CLIENT, 1=PropFactory.SERVER or 2=PropFactory.EDITOR.
      childProp - The child property.
      Returns:
      true (default if not VOLATILE) to save to XML, false to avoid writing the property to XML.

    • getDeviceType

      public final int getDeviceType()
      Gets the device type: -1=mobile, 0=both, 1=desktop.
      Specified by:
      getDeviceType in interface IUIComp

    • isMobileContextMenuSupported

      public boolean isMobileContextMenuSupported()
      Returns if the component can show the context menu in mobile mode.
      Specified by:
      isMobileContextMenuSupported in interface IUIContextMenuOwner
      Returns:
      Image crop and upload component does NOT support context menus for mobile.

    • onEventSelf

      public void onEventSelf(GEvent event)
      Self events.
      Specified by:
      onEventSelf in interface IGProp<GProp<?>[]>
      Overrides:
      onEventSelf in class UIComp
      Parameters:
      event - The event.

    • onRemoteEvent

      public void onRemoteEvent(RemoteEvent event)
      Called when a remote property event should be processed by this property.
      Specified by:
      onRemoteEvent in interface IGProp<GProp<?>[]>
      Overrides:
      onRemoteEvent in class UIComp
      Parameters:
      event - The remote event.

    • getUploadAPI

      protected IClientUploadAPI getUploadAPI()
      Gets the file upload API of the client session this component belongs to.
      Returns:
      The API, or null if the component is not in the panel tree of a server client session.

    • getUploadChannel

      protected UploadChannelProps getUploadChannel()
      Gets the upload channel of the client session this component belongs to: where a request that cannot be read is answered, since no UploadRequest exists to refuse.
      Returns:
      The channel, or null if the client created none or the component is not in the panel tree of a client session.

    • onPropDispose

      protected void onPropDispose()
      Called when a property is disposed of by delete/remove in a container, or by the dispose method.

      The upload in flight is cancelled with the reason REASON_DISPOSED (ruling row 16): the crop, the zoom and the listeners belong to this instance. A received file the client has not selected is deleted, and the link of this component is removed from the upload API.

      Overrides:
      onPropDispose in class UIComp

    • mustHaveWidth

      public boolean mustHaveWidth()
      Does this component require a width?
      Overrides:
      mustHaveWidth in class UIComp
      Returns:
      true if the width must be defined and non-zero, false otherwise.

    • mustHaveHeight

      public boolean mustHaveHeight()
      Does this component require a height?
      Overrides:
      mustHaveHeight in class UIComp
      Returns:
      true if the height must be defined and non-zero, false otherwise.

    • mustHaveExplicitWidth

      public boolean mustHaveExplicitWidth()
      Does this component require an explicitly defined width?
      Overrides:
      mustHaveExplicitWidth in class UIComp
      Returns:
      true if the width must be defined and non-zero, false otherwise.

    • mustHaveExplicitHeight

      public boolean mustHaveExplicitHeight()
      Does this component require an explicitly defined height?
      Overrides:
      mustHaveExplicitHeight in class UIComp
      Returns:
      true if the height must be defined and non-zero, false otherwise.

    • hasImplicitAlignFillX

      public boolean hasImplicitAlignFillX()
      Returns if the component has implicit component horizontal fill.
      Overrides:
      hasImplicitAlignFillX in class UIComp
      Returns:
      Always true: true means component will always fill the space in X.

    • hasImplicitAlignFillY

      public boolean hasImplicitAlignFillY()
      Returns if the component has implicit component vertical fill.
      Overrides:
      hasImplicitAlignFillY in class UIComp
      Returns:
      Always: true means component will always fill the space in Y.

    • canAlignX

      public boolean canAlignX()
      Returns if the component can be aligned left, right, center, or horizontal fill.
      Overrides:
      canAlignX in class UIComp
      Returns:
      false, swap container takes up entire width.

    • canAlignY

      public boolean canAlignY()
      Returns if the component can be aligned top, bottom, middle or vertical fill.
      Overrides:
      canAlignY in class UIComp
      Returns:
      false, swap container takes up entire height.

    • getApproximateSize

      public Size getApproximateSize()
      Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method. The size is calculated from the font of the component and default or defined values (such as character length or number of lines for text area).
      Specified by:
      getApproximateSize in class UIComp
      Returns:
      The size of the image and when no image is set 64x64.

    • addListener

      public boolean addListener(IUIImage2Listener listener)
      Adds a new listener for changes in this image property. Calling this method multiple times with the same listener will have no effect (but to return false).
      Parameters:
      listener - The listener to add.
      Returns:
      true if the listener was added, false otherwise.
      Throws:
      NullPointerException - If the listener is null.

    • removeListener

      public boolean removeListener(IUIImage2Listener listener)
      Removes a listener for changes in this image property.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if listener is successfully removed, false otherwise.

    • getImage

      public IImageTarget getImage()
      Gets the image.
      Returns:
      An image, null for none.

    • setImage

      public boolean setImage(IImageTarget image)
      Sets the image.

      When setting the image (assuming image is not null):

      1. the image width, height, user selected image file data is cleared.
      2. The file type will match the set image file name extension as "jpeg"/"jpg" or "png".
      3. The image orientation will be reset to default "NO_CHANGE".
      4. The user selected original file name will also be cleared.
      5. Crop points will be reset.
      Parameters:
      image - The image, null for none.
      Returns:
      true for changed (or the original file name is cleared, or the file image data is cleared), false for no change.
      Throws:
      IllegalArgumentException - If image type is not of bitmap type, i.e. it's an SVG or FontIcon.

    • setViewport

      public boolean setViewport(GSize size)
      Sets the viewport size.
      Parameters:
      size - The viewport size, or null for default 100x100.
      Returns:
      true if changed, false otherwise.
      Throws:
      IllegalArgumentException - If any size is less than 10 or larger than 99999.

    • getViewport

      public GSize getViewport()
      Gets the viewport size.
      Returns:
      The viewport size.

    • getZoomFactor

      public double getZoomFactor()
      Gets the image zoom factor.
      Returns:
      A double value for the zoom, greater than zero, defaults to 1d.

    • setZoomFactor

      public boolean setZoomFactor(double zoomFactor)
      Sets the image zoom factor.
      Parameters:
      zoomFactor - A double value for the zoom, greater than zero, defaults to 1d.
      Returns:
      true if changed, false otherwise.
      Throws:
      IllegalArgumentException - If the zoom factor is zero or less.

    • isCircle

      public boolean isCircle()
      Gets if the selected cropping area is a circle or of rectangular shape.
      Returns:
      true if circular, false if rectangular shaped.

    • setCircle

      public boolean setCircle(boolean isCircle)
      Gets if the selected cropping area is a circle or of rectangular shape.
      Parameters:
      isCircle - Flag for circle cropping area: true if circular, false if rectangular shaped.
      Returns:
      true if changed, false for no change.

    • isShowProgress

      public boolean isShowProgress()
      Gets if the upload progress bar is shown: a thin bar along the bottom edge while the image file the user picked is uploaded, so that the crop area stays usable.
      Returns:
      true (default) if shown.

    • setShowProgress

      public boolean setShowProgress(boolean isShown)
      Sets if the upload progress bar is shown.
      Parameters:
      isShown - true (default) to show it.
      Returns:
      true if changed, false for no change.

    • getMinimumWidthOrHeight

      public int getMinimumWidthOrHeight()
      Gets the minimum width or height allowed for a user selected image.
      Returns:
      The minimum width or height, zero for no minimum, default is 50.

    • getMaximumWidthOrHeight

      public int getMaximumWidthOrHeight()
      Gets the maximum width or height allowed for a user selected image.
      Returns:
      The maximum width or height, zero for no maximum, default is 4096.

    • setMinMaxWidthOrHeight

      public boolean setMinMaxWidthOrHeight(int min, int max)
      Sets the minimum and maximum width or height allowed for a user selected image.
      Parameters:
      min - The minimum width or height, zero for no minimum, default is 50.
      max - The maximum width or height, zero for no maximum, default is 4096.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If min or max is less than zero, or if min is larger than max.

    • getMaximumFileSize

      public int getMaximumFileSize()
      Gets the maximum file size of an image.
      Returns:
      The maximum file size, default 5 MB (5_242_880 bytes).

    • setMaximumFileSize

      public boolean setMaximumFileSize(int size)
      Sets the maximum file size of an image.
      Parameters:
      size - The maximum file size, default 5 MB (5_242_880 bytes).
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If size is zero or less, or larger than 8 MB (8_388_608 bytes).

    • getImageFileData

      public byte[] getImageFileData()
      Gets the image file data.

      An image the user picks is uploaded through the upload service and handed to IUIImage2Listener.onImageSelection(UIImage2, String, ImageType, byte[], int, int, ImageOrientation, double, GRect, boolean) only: it is not kept as the value of the component, so this method returns null for it (ruling UU-21). It returns the data set with setImageFileData(String, byte[]), and the data of an image the client sent over the WebSocket where the client session cannot upload.

      Returns:
      The file data byte array, null if image source is not user selected.

    • setImageFileData

      public boolean setImageFileData(String fileName, byte[] data)
      Sets the image file data and the original file name (path is removed). Only valid file extensions can be specified.

      The image replaces the one shown as a fresh image: the previous IImageTarget, and the size, orientation, crop points and zoom of the image that went are removed with the data, as they are when the data is cleared, so that the client binds the new image centred with the zoom limits of its own size (UIIMAGE2-REPLACE-KEEPS-OLD-TRANSFORM).

      Parameters:
      fileName - The file name (ignored if data is null.
      data - The file data byte array, null to clear it so that the user can select an image.
      Returns:
      true for changed (original file name, file image data, previous IImageTarget, width, height, orientation, crop points and/or zoom), false for no change.
      Throws:
      IllegalArgumentException - If the file extension is not '.png', '.jpg' or '.jpeg', or if the image cannot be decoded in the media formats 'image/jpeg' or 'image/png'.
      NullPointerException - If the fileName is null and data is present.

    • getImageWidth

      public int getImageWidth()
      Gets the image width.
      Returns:
      The image width, zero if image source is not user selected.

    • getImageHeight

      public int getImageHeight()
      Gets the image height.
      Returns:
      The image height, zero if image source is not user selected.

    • getImageType

      public ImageType getImageType()
      Gets the image type.
      Returns:
      The image type, UNKNOWN for none.

    • getSupportedImageTypes

      public String getSupportedImageTypes()
      Gets the supported image formats.
      Returns:
      A string with supported image formats separated by comma. It is a combination of file extensions if the string starts with a '.' (dot). Otherwise it is a media file type such as 'image/jpeg' and/or 'image/png'. The default is list is:
      • .jpg
      • .jpeg
      • image/jpeg
      • .png
      • image/png

    • setSupportedImageTypes

      public boolean setSupportedImageTypes(String types)
      Sets the supported image types.
      Parameters:
      types - The string with supported image formats separated by comma. It is a combination of file extensions if the string starts with a '.' (dot). Otherwise it is a media file type such as 'image/jpeg' and/or 'image/png'. Accepted values are case sensitive and are:
      • .jpg
      • .jpeg
      • image/jpeg
      • .png
      • image/png

      A null or empty string will set the default types.

      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If an invalid image media type is found, or a file extension is invalid, or if the string is not in lower case.

    • getImageOrientation

      public ImageOrientation getImageOrientation()
      Gets the image orientation.
      Returns:
      The image orientation.

    • getOriginalImageFileName

      public String getOriginalImageFileName()
      Gets the original image file name when the user selected the image.
      Returns:
      The file name, null if image source is not user selected.

    • verify

      public boolean verify(PropVerification verification)
      Verifies this property container. The check performed is the extension of classes and that no circular reference is present.
      Specified by:
      verify in interface IGProp<GProp<?>[]>
      Overrides:
      verify in class UIComp
      Parameters:
      verification - The property verification class.
      Returns:
      true if verification should proceed, false if disposed of and verification should not take place.