com.nokia.mid.imagescale
Class ImageScaler

java.lang.Object
  com.nokia.mid.imagescale.ImageScaler

public class ImageScaler
extends java.lang.Object

ImageScaler provide the capability of scaling image. Upscaling is not completely supported due to uncontrollable memory use. See the method definition for details. Considering security, file path might be limited. File read and write permission should be checked as well.

There are two ways to scale image:

• scale image according to width and height
• scale image according to file size

ImageScaler Event

To receive events, an object must implement the ImageScalerListener interface and use the addListener method to register.

Simple ImageScaler Example

 
   scale image per width, height will follow width
 

    ImageScaler is = new ImageScaler("file:///Phone/big.jpg", "file:///Phone/small.jpg");
    is.setJpegQuality(70);
    is.scaleImage(480, -1, true);
 

 
   scale image per height, width will follow height
 

    ImageScaler is = new ImageScaler("file:///Phone/big.jpg", "file:///Phone/small.jpg");
    is.scaleImage(-1, 480, true);
 

 
   scale image per width and height, not keep aspect ratio
 

    ImageScaler is = new ImageScaler("file:///Phone/big.jpg", "file:///Phone/small.jpg");
    is.scaleImage(320, 480, false);
 

 
   scale image per width and height, height will keep original value, not keep aspect ratio
 

    ImageScaler is = new ImageScaler("file:///Phone/big.jpg", "file:///Phone/small.jpg");
    is.scaleImage(320, 0, false);
 

 
   scale image per file size which is less than or equals to 100k
 

    ImageScaler is = new ImageScaler("file:///Phone/big.jpg", "file:///Phone/small.jpg");
    is.scaleImage(100);
 


 

Constructor Summary

ImageScaler(java.lang.String srcPath, java.lang.String destPath)
constructor.

Method Summary

void	addListener(ImageScalerListener listener) add a image scaler listener to be notified when scaling operation is finished.
void	cancel(int requestId) cancel scale request.
void	removeDestFile() the dest file is not used any more and can be removed.
void	removeListener(ImageScalerListener listener) remove a image scaler listener to be notified when scaling operation is finished.
int	scaleImage(int maxFileSize) Scale source image file into dest image file per file size.
int	scaleImage(int width, int height, boolean keepAspectRatio) Scale source image file into dest image file per width and height pixels.
void	setAutoOrientation(boolean autoOrientation) set flag for handling orientation info automatically.
void	setJpegQuality(int qual) set quality for jpeg image.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ImageScaler

public ImageScaler(java.lang.String srcPath,
                   java.lang.String destPath)

constructor.

Throws:

java.lang.IllegalArgumentException - if either the source or dest path is invalid.

java.lang.SecurityException - if either the source or dest path can not be accessed.

Method Detail

setJpegQuality

public void setJpegQuality(int qual)

set quality for jpeg image. Be sure to call it before calling scaleImage. Otherwise, it does not make sense.

Parameters:

qual - Value 0-100, 0 for keeping the original quality.

setAutoOrientation

public void setAutoOrientation(boolean autoOrientation)

set flag for handling orientation info automatically. Its default value is false. Be sure to call it before calling scaleImage. Otherwise, it does not make sense. After it is set to true, scaleImage will handle orientation info automatically.

Parameters:

autoOrientation - whether handle orientation info automatically or not.

scaleImage

public int scaleImage(int width,
                      int height,
                      boolean keepAspectRatio)
               throws ImageScalerException

Scale source image file into dest image file per width and height pixels. Dest width/height can be set larger than source width/height, but due to system performance limitation, they can not be set too big. Any width/height value larger than 10000 will cause exception. It is an asynchronous operation. Scaling finish or error will notify the caller by registered listener.

Parameters:

width - width pixels, 0 for the original width, -1: not given

height - height pixels, 0 for the original height, -1: not given

keepAspectRatio - Whether keep aspect radio or not. if keepAspectRatio is true then the other resolution will follow the given resolution. If keepAspectRatio is false, leave the not given resolution to its original value If both resolutions are given and keepAspectRatio is true, the scaler will reduce the shorter dimension to maintain aspect ratio.

Returns:

the image scale request id, 0 for error.

Throws:

ImageScalerException - if some basic errors occur such as the source file cannot be found, or dest file is in use, or file type can not be supported, or width/height is minus but not -1, or width/height is larger than 10000, etc

java.lang.SecurityException - if the application does not have read access to the source file or does not have write access to the dest file directory

scaleImage

public int scaleImage(int maxFileSize)
               throws ImageScalerException

Scale source image file into dest image file per file size. Attention: The method does not support upscaling. It is an asynchronous operation. Scaling finish or error will notify the caller by registered listener.

Parameters:

maxFileSize - Max file size in kilobytes, scope: 1 <= maxFileSize < source image file size
when maxFileSize is 1, it will be adjusted to 2 since too small size cannot be supported due to platform limit.
when maxFileSize is out of the above scope, ImageScalerException will be thrown due to invalid parameter.
Usually 100%-70% of requested size can be accepted, but it might be not always true for small dest size.

Returns:

the image scale request id, 0 for error.

Throws:

ImageScalerException - if some direct errors occur such as the source file cannot be found, or dest file is in use, or file type can not be supported, etc

java.lang.SecurityException - if the application does not have read access to the source file or does not have write access to the dest file directory

cancel

public void cancel(int requestId)

cancel scale request.

removeDestFile

public void removeDestFile()
                    throws java.io.IOException

the dest file is not used any more and can be removed. It is recommended to call the method to save space. Or the application can delete the file by itself. If the dest file is not removed, then it will be removed when the instance releases.

Throws:

java.io.IOException - if the dest file cannot be removed.

java.lang.SecurityException - if the application does not have write access to the dest file directory

addListener

public void addListener(ImageScalerListener listener)

add a image scaler listener to be notified when scaling operation is finished.

Parameters:

listener - the listener to add. If null is used, the request will be ignored.

removeListener

public void removeListener(ImageScalerListener listener)

remove a image scaler listener to be notified when scaling operation is finished.

Parameters:

listener - the listener to remove. If null is used, the request will be ignored.