release_notes.txt

symbian code: 5th game demo

S60 5th Edition: Solitaire Game Example v1.1
--------------------------------------------

This C++ example application demonstrates a fully touch-optimised application 
using various touch UI features of S60 5th Edition with direct manipulation. 
Besides tapping the cards, the user can drag and drop them using a finger or 
the stylus. The application demonstrates handling pointer events of custom made 
UI controls. Also, tactile feedback using the Touch Feedback API is received. 
Double buffering is used to draw on the screen to avoid flickering. By default, 
the cards are implemented as Scalable Vector Graphics (SVG) icons, but the 
example also provides an option to draw them using methods of the graphics 
context class CWindowGc. In the updated version, major drawing optimisation has 
been done. The example application was developed for S60 5th Edition and 
touch UI.

--------------------------------------------------------------------------------

PREREQUISITES

Symbian C++ basics.
Basics of application UI controls.
Basics of graphics.

--------------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

CTableauControl.h: Main UI container control.

CCard.h: Card data class.

CDeckControl.h: Deck that owns cards and handles pointer events to the deck.

CFoundation.h: Target of the cards.

CStockControl.h: Gives more cards to the game and handles own pointer events.

CGamelogic.h: Solitaire card game logic.

Important classes: CCoeControl, MTouchFeedback, CFbsBitmap, CWindowGc.

--------------------------------------------------------------------------------

TOUCH UI SUPPORT

The CCoeControl::HandlePointerEvent() virtual base class method is implemented 
in all custom UI controls.

The custom-made UI control (CCoeControl) has to implement the base class 
virtual HandlePointerEventL() method for receiving pointer events. This is 
done, for example, in CTableauControl, the main container control. Pointer 
events are automatically redirected from the container control into the 
child UI controls when calling the base class virtual implementation of the 
container control CCoeControl::HandlePointerEventL(aPointerEvent).

Child controls, such as CDeckControl, handle their own pointer events in their 
HandlePointerEventL() method.

CTableauControl listens to drag events. During dragging, it draws the screen 
and its child components.

MTouchFeedback is used to vibrate the device when the user drags cards into 
foundation decks.

--------------------------------------------------------------------------------

GRAPHICS DRAWING

By default, all drawing goes to a back buffer bitmap and the whole back buffer 
is drawn on the screen. This is called double buffering and it is used to avoid 
screen flickering.

When the user starts to drag, the card drawing methods change. The back buffer 
bitmap gets one copy of the whole screen, excluding those cards that are being 
moved. When the dragging event is received, the copied back buffer bitmap is 
drawn on the screen and the moving cards are drawn on top of it.

--------------------------------------------------------------------------------

KNOWN ISSUES

None.

--------------------------------------------------------------------------------

RUNNING THE EXAMPLE

The application runs in full-screen landscape mode to optimise the screen size 
for the game. The user can tap and drag-and-drop the cards using a finger or 
the stylus.
     
--------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

The source code can be compiled on S60 5th Edition SDKs.

To build and install the application on a device:

Extract the example into the same drive as the Symbian SDK and use the command 
prompt to compile the project:

Device:
    To build the application for the target device (GCCE):
    bldmake bldfiles
    abld build gcce urel

Emulator:
    To build for the emulator (WINSCW):
    bldmake bldfiles
    abld build winscw udeb

When the build for the target device is ready:

Go to the folder SolitaireExample\sis and type:
makesis -dS60_5th_SDK_:com.nokia.s60 Solitaire_S60.pkg

You must self-sign the created SIS package, for example: 
signsis Solitaire_S60.sis Solitaire_S60.sisx selfsign.cer selfsign.key

For more information about self-signing, see http://www.symbiansigned.com/.

--------------------------------------------------------------------------------

COMPATIBILITY

S60 5th Edition

Tested on: Nokia 5800 XpressMusic, Nokia N97.

Created and tested using S60 5th Edition SDK v0.9.

--------------------------------------------------------------------------------

CHANGE HISTORY

1.1 Major optimisation to card drawing.
1.0 First version.

--------------------------------------------------------------------------------

RELATED DOCUMENTATION

S60 5th Edition C++ Developer's Library
http://www.forum.nokia.com/info/sw.nokia.com/id/d2d77ad4-b40d-4b81-bdd2-9cbf7407e005/S60_5th_Edition_Cpp_Developers_Library.html

CS001049 - Avoid flickering with double buffering
http://wiki.forum.nokia.com/index.php/CS001049_-_Avoid_flickering_with_double_buffering