release_notes.txt

Open C++: Memory Game Example This Open C++ example application demonstrates a simple memory game

Open C++: Memory Game Example
---------------------------------

This Open C++ example application demonstrates a simple memory game. 
The game engine part has been written in Open C++ and the UI part has 
been written in Symbian C++. The application supports S60 3rd Edition 
and S60 5th Edition devices. Keypad and Touch UI are supported depending on 
the device.


PREREQUISITES
-------------------------------------------------------------------------------

Understanding the basics of C++ and Symbian C++.


IMPORTANT FILES/CLASSES
-------------------------------------------------------------------------------

Observer:
~~~~~~~~~

IMemoryGameObserver
    - S60 CAknAppUi class implements this observer class and receives callbacks
    when the engine state changes.

Engine (Open C++):
~~~~~~~~~~~~~~~~~~

MemoryGameEngine
    - This is the main class that controls all the other engine classes and 
      offers a public interface to UI classes.

MemoryGameTimer
    - This class implements a timer for the game engine.

MemoryCardDeck/MemoryCard   
    - These classes handle memory card states (turned/unturned) and are capable
      of saving and loading memory cards to/from files.

HighScoreList/HighScore
    - These classes handle high scores and are capable of saving and loading 
      high scores to/from files.

UI (Symbian C++):
~~~~~~~~~~~~~~~~~

CMemoryGameTimer
    - This class implements a timer used to update the navi pane and an 
      indicator container with turn and time information.

CMemoryGameScoreModel/CMemoryGameScore
    - These classes are used with listbox in the high-score view to represent
      high scores from the engine. 

CMemoryGameSoundPlayer
    - This class plays the .wav sound files of the game.

The most important Symbian/S60 APIs in this example are:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- RTimer for UI Timer
- CMdaAudioPlayerUtility for playing .wav sound files.
- CAknQueryDialog and CAknMessageQueryDialog for getting user input. 
- CAknRadioButtonSettingPage for a simple radio button selection dialog.
- CEikTextListBox for the high-score list implementation.
- CFbsBitmap for loading and handling memory card bitmap pictures.
- CAknIndicatorContainer for showing game state information to the player using a status pane.

- Open C++: STL vector for high-score list and card deck implementations.

S60 5th Edition-specific API:
- MTouchFeedback tactile feedback interface for UI controls.

Other important files:
~~~~~~~~~~~~~~~~~~~~~~

The memory card pictures are from the Web site http://openclipart.org and have been created by the Gerald_G:

- Gerald_G_Chick_4.png/.svg
- Gerald_G_Crawfish.png
- Gerald_G_Gorilla_with_Colour.png
- Gerald_G_Kitten_(Black).png
- Gerald_G_Mouse_Cartoon.png
- Gerald_G_Pelican.png
- Gerald_G_Puppy_Cartoon.png
- Gerald_G_Raccoon_opening_box.png

The sound files are taken the Web site http://www.freeaudioclips.com/:
- Short beeping sound (bleep.wav)
- A short beep sound (bleep2.wav)

The license for graphic files is included in this package.


TOUCH UI SUPPORT
-------------------------------------------------------------------------------

This application includes a demonstration of the usage of Touch UI. In
devices with Touch UI support, it is possible to use stylus input 
to control applications.

This example application can be compiled in two different ways: with or
without support for tactile feedback, using the definition introduced in the .mmp file.
Touch feedback sends vibration feedback to the user when he or she points the 
controller.

1) No tactile feedback support:
Commenting the CONFIG_TOUCH_UI_SUPPORT_ENABLED definition disables tactile 
feedback support from the compilation and it is possible to compile the project
with the SDK without the touchfeedback.lib library and touchfeedback.h header.

2) Support for tactile feedback:
Uncommenting the CONFIG_TOUCH_UI_SUPPORT_ENABLED definition enables 
tactile feedback support.

From S60 3rd Edition MR SDK onwards, there has been basic Touch UI 
(TUI) support that enables pointer events in S60 5th Edition devices.


KNOWN ISSUES
-------------------------------------------------------------------------------

The class sstream in the current Open C++ plug-in has a known bug that 
prevents the usage of the istringstream class when working with a gcce compiler.
The workaround is to use the C function atoi(), but the alternative C++ way
to convert strings to integers is commented out and can be found in the
HighScoreList.cpp source codes. 
 
The EXPORTUNFROZEN definition in the MemoryGameEngine.mmp file causes many warnings
during compilation. These warnings can be avoided by freezing the 
library when building the memorygame engine part.


RUNNING THE EXAMPLE
-------------------------------------------------------------------------------

The players turn over two cards and try to find pairs.
If a player turns over two cards that do not match, those cards are 
turned face down again. When all pairs have been found, the game ends.
The game keeps track of how fast a player can find all the
matching pairs and how many turns it takes. The best scores are
saved in the high score files. The memory game has three different
game modes: easy (8 pairs/16 cards), medium (18 pairs/36 cards), and
hard (32 pairs/64 cards).

The game supports both portrait and landscape orientations. The options menu
can be accessed normally with the left softkey in the game and in the high-score
view. The right softkey is used for exiting in the game view; in the high-score
view, this softkey takes the user back to the game view.



The game view menu selections:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Start Game  
    - Starts a new game of selected game type (easy, medium, hard).
Reset Game
    - Resets the game by restarting the timer and shuffling the cards. 
Pause Game
    - Pauses the ongoing game.
Continue Game
    - Continues the paused game.
High Scores 
    - Shows a high-score view of the selected game type.
Settings    
    - Shows a selection dialog to choose the game type (easy, medium, hard).
Help
    - Shows the context-sensitive help page.
About
    - Shows the About dialog of the game.

The high-score view menu selections:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clear
    - Clears all high scores of the current game type.
Back
    - Activates the game view.

In devices supporting Touch UI, it is possible to use stylus
input to control the memory game. In other devices, these keys can be used:

Up Arrow: Moves cursor up.
Down Arrow: Moves cursor down.
Left Arrow: Moves cursor left,
Right Arrow: Moves cursor right.
Enter/OK: Turns activated memory game card. 


BUILD & INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

The installation package of the example application does not provide Open C++ runtime.  Open C++ is a preinstalled runtime in S60 5th Edition but on S60 3rd Edition (including FP1 and FP2) devices it needs to be installed prior to installing the application.

Steps for building and installing the application to a device depend on the S60 
platform version:

Mobile device
~~~~~~~~~~~~~

Install the Open C++ runtime according to Open C/C++ Plug-in抯 installation instructions. The plug-in is available for download at:
http://www.forum.nokia.com/info/sw.nokia.com/id/91d89929-fb8c-4d66-bea0-227e42df9053/Open_C_SDK_Plug-In.html

Note: The stdioserver component should not be installed to avoid the console screen popping up.

1. Make sure the paths in .pkg files match those on your system.

2. Compile the example:

    cd group
    bldmake bldfiles
    abld reallyclean gcce
    abld build gcce urel

3. Make the sis:

    cd sis
    createsis create MemoryGame_S60_3_0_v_1_0_0.pkg
    
4. Install the signed .sis file to an S60 3rd/5th Edition device.
   - If you get a "Certificate error" during installation of a self-signed 
     package, check that App.Manager -> Settings -> Software Installation is 
     set to "All."

Emulator (WINSCW)
~~~~~~~~~~~~~~~~~

1. Compile the example:

    cd group
    bldmake bldfiles
    abld reallyclean winscw
    abld build winscw udeb

2. Start the emulator.


COMPATIBILITY
-------------------------------------------------------------------------------

S60 5th Edition
S60 3rd Edition, Feature Pack 2
S60 3rd Edition, Feature Pack 1
S60 3rd Edition

Tested on: Nokia 5800 XpressMusic, Nokia 6220 Classic, Nokia E90 Communicator, Nokia N82.

VERSION HISTORY
-------------------------------------------------------------------------------

1.0    Initial version for S60 3rd Edition / S60 5th Edition.


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=c1c1be75-5447-4325-8f41-ef6dfd414a40/Open_Cpp_Memory_Game_Example_v1_0_en.zip.