javax.microedition.amms.control.camera
Interface SnapshotControl

All Superinterfaces:
Control

public interface SnapshotControl
extends Control

SnapshotControl controls burst shooting with the camera. With this Control, it is possible to shoot multiple pictures with one method call in an efficient way.

SnapshotControl stores the captured pictures in the file system. Initially, before any setDirectory method calls the storage directory is pointing to the default image store location of the implementing platform. That directory can be queried by getDirectory before setting a new directory.

Images will be stored in the files system only if the application has rights to create files to the given directory. Rights are checked when the setDirectory method is called but it is possible that the rights are changed after that. In that case, a STORAGE_ERROR event will be posted if the application has no file creation rights when an attempt is made to store the captured image in the file system.

The structure of the generated file name is prefixauto generated stringsuffix

where prefix is a user given prefix String. auto generated string is a String generated automatically by the implementation. The generated String is a zero padded four digit running number starting from 0. Therefore, the sequence of generated Strings is "0000", "0001", "0002" etc. The length of the String increases if more digits are needed to represent the number so "9999" will be followed by "10000". suffix is a user given suffix String. Wanted file extension, like ".jpg", is part of the suffix.

File name generation runs through the lifetime of the Player. In other words, it is not necessary to set the prefix before each call of the start method. Notice that it is likely that the naming method defined here differs from the naming system of the native imaging applications of the device.

If the directory, where the files are stored, contains a file with the same name as the generated image file, the generated image file will not be written anywhere. A STORAGE_ERROR message with a the name of the file, whose writing failed, will be sent and capturing of the images will stop. Changing directory, prefix and suffix are effective when start is called. On-going burst shooting is not affected.

Format of the stored pictures is set by ImageFormatControl. The default format is JPEG if it's supported.

Since:
BlackBerry API 5.0.0

Field Summary
static int FREEZE
          Takes one snapshot, freezes the viewfinder, and unfreezes it again after some time.
static int FREEZE_AND_CONFIRM
          Freezes the viewfinder and keeps it frozen until unfreeze is called.
static String SHOOTING_STOPPED
          Posted to PlayerListener when the burst shooting stops and the files have been stored into the file system.
static String STORAGE_ERROR
          Posted to PlayerListener when there has been an error while storing the files into the file system.
static String WAITING_UNFREEZE
          Posted to PlayerListener when shooting has been started as FREEZE_AND_CONFIRM.
 
Method Summary
 String getDirectory()
          Gets the storage directory.
 String getFilePrefix()
          Gets the filename prefix.
 String getFileSuffix()
          Gets the filename suffix.
 void setDirectory(String directory)
          Sets the file directory where the images will be stored.
 void setFilePrefix(String prefix)
          Sets the filename prefix.
 void setFileSuffix(String suffix)
          Sets the filename suffix.
 void start(int maxShots)
          Starts burst shooting.
 void stop()
          Stops burst shooting.
 void unfreeze(boolean save)
          Unfreezes the viewfinder and saves the snapshot depending on the parameter.
 



Field Detail

SHOOTING_STOPPED

static final String SHOOTING_STOPPED
Posted to PlayerListener when the burst shooting stops and the files have been stored into the file system. When this event is received, the eventData parameter is a String containing the name of the last generated file.

Value SHOOTING_STOPPED is assigned to SHOOTING_STOPPED.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

STORAGE_ERROR

static final String STORAGE_ERROR
Posted to PlayerListener when there has been an error while storing the files into the file system. Shooting of the images is stopped but SHOOTING_STOPPED event will not be posted. When this event is received, the eventData parameter is a String containing the name of the file whose writing failed.

Value STORAGE_ERROR is assigned to STORAGE_ERROR.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

WAITING_UNFREEZE

static final String WAITING_UNFREEZE
Posted to PlayerListener when shooting has been started as FREEZE_AND_CONFIRM. At this point, the implementation is waiting that unfreeze will be called. If the application is waiting for the user to choose whether the picture should be saved or not, the query should be done in a separate thread and this method should return as quickly as possible.

When this event is received, the eventData parameter will be null.

Value WAITING_UNFREEZE is assigned to WAITING_UNFREEZE.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

FREEZE

static final int FREEZE
Takes one snapshot, freezes the viewfinder, and unfreezes it again after some time. The time the viewfinder is frozen is in the range of seconds and the exact time is implementation specific.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

FREEZE_AND_CONFIRM

static final int FREEZE_AND_CONFIRM
Freezes the viewfinder and keeps it frozen until unfreeze is called. Takes a snapshot depending on the parameter of the unfreeze method.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

setDirectory

void setDirectory(String directory)
Sets the file directory where the images will be stored.

The directory name is given as a String which can contain the trailing slash "/" in the directory name but it is not required.

For example, both "/SDCard/" and "/SDCard" set the directory to the root of the SDCard in a platform implementing FileConnection of JSR-75. In case of FileConnection of JSR-75 the return value of FileConnection.getPath() can be used as it is as a parameter for this method.

New directory is effective when start is called. Directory for on-going burst shooting is not changed.

Parameters:
directory - the storage directory
Throws:
IllegalArgumentException - if the given directory does not exist or it is null
SecurityException - if the creation of files to the given location is not allowed
Since:
BlackBerry API 5.0.0

getDirectory

String getDirectory()
Gets the storage directory. If setDirectory has not been called the directory points to the default image storing location.

Returns:
the current storage directory with the trailing slash "/"
Since:
BlackBerry API 5.0.0

setFilePrefix

void setFilePrefix(String prefix)
Sets the filename prefix.

New prefix is effective when start is called. Prefix for on-going burst shooting is not changed.

Parameters:
prefix - the prefix String for the files to be created
Throws:
IllegalArgumentException - if the given prefix cannot be set or if it is null
Since:
BlackBerry API 5.0.0

getFilePrefix

String getFilePrefix()
Gets the filename prefix.

Returns:
the filename prefix
Since:
BlackBerry API 5.0.0

setFileSuffix

void setFileSuffix(String suffix)
Sets the filename suffix.

New suffix is effective when start is called. Suffix for on-going burst shooting is not changed.

Throws:
IllegalArgumentException - if the given suffix cannot be set or if it is null
Since:
BlackBerry API 5.0.0

getFileSuffix

String getFileSuffix()
Gets the filename suffix.

Returns:
the filename suffix
Since:
BlackBerry API 5.0.0

start

void start(int maxShots)
           throws SecurityException
Starts burst shooting.

Parameters:
maxShots - the maximum number of shots that are going to be taken or FREEZE or FREEZE_AND_CONFIRM. Integer.MAX_VALUE will take as many shots as possible. Calling the method overrides the previous call when burst shooting is going on.
Throws:
IllegalArgumentException - if maxShots is less than one, and not FREEZE or FREEZE_AND_CONFIRM.
IllegalStateException - if prefix and suffix have not been set or the Player is not in STARTED state.
SecurityException - if the application does not have permission to take snapshots
Since:
BlackBerry API 5.0.0

stop

void stop()
Stops burst shooting.

Since:
BlackBerry API 5.0.0

unfreeze

void unfreeze(boolean save)
Unfreezes the viewfinder and saves the snapshot depending on the parameter. The method does not do anything if start(FREEZE_AND_CONFIRM) has not been called.

Parameters:
save - true to save the snapshot, false not to save the snapshot (and not to post the SHOOTING_STOPPED event)
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.