S60 Platform: Image Converter Example v3.0
------------------------------------------------------------
This example demonstrates how to use the image conversion APIs available in
the S60 platform (Image Conversion Library, ICL). These APIs include important
classes such as CBitmapRotator and CBitmapScaler to be used for rotating and scaling
images, respectively. CImageEncoder and CImageDecoder classes are used to access image
encoders and decoders available in the ICL.
With this example an image can be opened either from the device memory or a memory card
(if present). Once opened, the image can be rotated, scaled, and saved in the same or a
different format (for example, a JPG image can be converted into a GIF image).
The UI of the updated application has been optimized for touch. For example, long taps and tactile feedback are supported. The example project supports building for both S60 5th Edition with touch UI and S60 3rd Edition with a traditional keypad.
-------------------------------------------------------------------------------
PREREQUISITES
- Symbian OS key concepts
--------------------------------------------------------------------------------
IMPORTANT FILES AND CLASSES
CImageConverterEngine | The main engine class, handles image conversion operations (rotating,
| scaling, encoding, and decoding) by using ICL classes CBitmapRotator,
| CBitmapScaler, CImageEncoder, and CImageDecoder. The engine class is an
| active object, since image conversion operations are asynchronous by nature.
CBitmapRotator and CBitmapScaler are active objects and rotate/scale bitmaps asynchronously.
CImageDecoder and CImageEncoder create the bitmap CFbsBitmap class from an image file and vice versa, respectively.
CShowInfoDialog is a custom query dialog derived from CAknQueryDialog. The dialog shows detailed information about the active image.
CAknLongTapDetector is used to listen for long taps in touch UI. MTouchFeedback enables tactile feedback. See section Touch UI Support for further information.
--------------------------------------------------------------------------------
TOUCH UI SUPPORT
The __TUI_SUPPORTED__ flags are defined in ImageConverter.mmp to enable pointer events. These features are available in the S60 5th Edition SDK. Comment these flags when compiling for S60 3rd Edition devices.
Dragging is enabled in CImageConverterContainer::ConstructL() with
CCoeControl::EnableDragEvents().
Listening for pointer events is implemented in CImageConverterContainer::HandlePointerEventL(). In these kind of custom controls the base class virtual method has to be implemented to receive pointer events. AVKON-based controls have implemented this method and they receive and handle pointer events.
CAknLongTapDetector is used for listening for long taps. After a long tap, the user
can move the picture on the screen. Long tap is deactivated on pen up event.
MTouchFeedback is touch feedback to user. It is used to vibrate the device
when the user taps the screen.
--------------------------------------------------------------------------------
KNOWN ISSUES
- Some S60 3rd Edition devices might not handle the FILENULL (FN) option in the .pkg file
correctly. That is why it is not used in this example.
- Opening a JPEG image in a S60 3rd Edition device/emulator may result in the "Not enough memory" error (error code -4). This can be avoided by increasing the size of the heap memory. This known issue is explained in more detail in the Forum Nokia Knowledge Base at http://wiki.forum.nokia.com/index.php/KIS000334_-_Not_enough_memory_-_error_when_decoding_progressive_JPEG_images.
- The application status pane has been set to empty ( R_AVKON_STATUS_PANE_LAYOUT_EMPTY ) in the application resource file in order to avoid the default theme to appear at the bottom of the screen between the softkey labels in the landscape orientation (detected only on S60 5th Edition SDK emulator and Nokia 5800 XpressMusic). Note that because of this, CBA locations are not correctly defined with AknLayoutUtils::CbaLocation() on the S60 5th Edition SDK, v0.9 emulator. This works correctly on the device.
--------------------------------------------------------------------------------
RUNNING THE EXAMPLE
The application loads automatically all images from the c:\data\images folder.
The image can be changed with the right and left arrow keys or on the touch UI, by dragging the image to the left/right.
The image can be scaled with the up and down arrow keys or on the touch UI, by dragging up/down.
The image can be rotated with the 1 and 3 keys or on the touch UI, by drawing a semi-circle that is open to the left/right, or selecting Options -> Rotate.
The application automatically follows the orientation of the display. Thus in certain devices you can rotate the application by turning the device to use a different orientation. You can also manually set the fixed orientation for the application by selecting Options -> Change Orientation. However, when the orientation is defined manually, the application keeps that orientation regardless of the display's orientation. The orientation locking is released in application exit.
An image from any other location can be viewed by selecting Options -> Open. If a memory card is present on the device, a dialog prompting to choose the memory to be used appears. If the memory
card is not present, the device memory will be used by default (the contents of the folder C:\Data are shown). If the memory card is selected, the contents of its root folder are shown.
The properties of the current image can be viewed by selecting Options -> Image Details.
The image in its current orientation and size can be saved by selecting Options -> Save As. This will trigger a list of supported image formats to be shown to the user. Choose the preferred format by
selecting it from the list and pressing OK. Then you can name the image.
Note: The file extension will be appended automatically to the file name according to the selected image format. For example, if you chose the JPEG format and type in a file name "MyImage", the
file will be named "MyImage.JPEG".
The application contains context-sensitive help.
--------------------------------------------------------------------------------
BUILD & INSTALLATION INSTRUCTIONS
The example project supports building to both S60 5th Edition with touch UI and S60 3rd Edition with keypad. By default, the project includes touch UI functionality. When building for S60 3rd Edition devices, disable touch UI pointer events by commenting the __TUI_SUPPORTED__ flags in ImageConverter.mmp.
Otherwise, you can use the same project for both editions.
There are two different self-signed versions of installation packages for S60 3rd Edition and S60 5th Edition included in the package.
MOBILE DEVICE (S60 3rd Edition / S60 5th Edition)
------------------
Go to /ImageConverterExample/group
bldmake bldfiles
abld build gcce urel
Go to /ImageConverterExample/sis
Edit the ImageConverter.pkg's paths to match those on your system.
makesis ImageConverter.pkg
Sign the SIS package:
Sign the sis file (find out more about signing the sis file and
developer certificate from www.symbiansigned.com):
signsis ImageConverter.sis ImageConverter_selfs.sis YourCertificate.cer
YourKey.key YourPassword
Install the signed .sis file to an S60 3rd Edition device.
- If you get a "Certificate error" during the installation of a self-signed
package, check that App.Manager -> Settings -> Software Installation is
set to "All".
EMULATOR
------------------
Go to /ImageConverterExample/group
bldmake bldfiles
abld build winscw udeb
Start the emulator.
--------------------------------------------------------------------------------
COMPATIBILITY
S60 5th Edition
S60 3rd Edition, FP1
S60 3rd Edition, FP2
S60 3rd Edition
TESTED WITH Nokia 5800 XpressMusic, Nokia E90 Communicator, and Nokia N95.
Created / tested with S60 3rd Edition, MR SDK and S60 5th Edition SDK.
--------------------------------------------------------------------------------
VERSION HISTORY
3.0 Help file added. Application icon
added. UI and usability improved.
3.0 Beta Major update. Touch UI support with direct manipulation added. Many new features and improved usability of viewing images.
2.0 Support for S60 3rd Edition added. Slight modifications to CImageConverterAppUi::HandleSaveAsL
so that the correct file extension will be added automatically when an image is being saved.
Furthermore, info messages are now shown to the user using CAknGlobalNote::ShowNoteL() instead
of CEikonEnv::InfoMsg().
1.0 First release.
--------------------------------------------------------------------------------
EVALUATE THIS RESOURCE
Please spare a moment to help us improve documentation quality and
recognize the examples you find most valuable, by rating this resource at
http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=2335766d-03b8-436a-9886-e39224f32b98/S60_Platform_Image_Converter_Example_v3_0_en.zip.