diff -r 80ef3a206772 -r 48780e181b38 Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita --- a/Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita Fri Jul 16 17:23:46 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita Tue Jul 20 12:00:49 2010 +0100 @@ -1,262 +1,188 @@ - - - - - Advanced Pointer Tutorial -This tutorial provides step-by-step instructions and sample -code to help you write applications using advanced pointers. - - - - -

Variant: ScreenPlay. Target audience: Application developers.

-
Required background

This topic builds -on the material in the following topics:

    -

  • Advanced Pointer -Overview

    • -

  • Advanced Pointer -States and Event Communication

    • -
-
Using advanced pointers

This topic covers -the following:

    -

  • Enabling multiple pointers for a window

    • -

  • Getting Z coordinates from TPointerEvent

    • -

  • Pinch zooming

    • -
-
Enabling -multiple pointers in a window
    -

  1. RWindow provides a handle to a standard window. Call RWindow to create an instance of a window.

    -RWindow window(ws); - -User::LeaveIfError(window.Construct(wg, reinterpret_cast<TUint32>(&wg) + 1)); -
    2. -

  2. Call RWindow::EnableAdvancedPointers() to enable -advanced pointers. Then call RWindowBase::Activate() to display the -window and enable the window to receive events. RWindow inherits from RWindowBase, so you can call the Activate() function -on RWindow.

    -window.EnableAdvancedPointers(); -window.Activate(); -

    When an application needs to receive advanced pointer -events in a window, it must call RWindowBase::EnableAdvancedPointers() for the window before it is activated.

    If advanced -pointers are not enabled for a window, it receives only standard TPointerEvent information from a single pointer with no pressure and proximity -data. The single pointer environment rules describe the way in which -pointer events coming from many pointers in the multiple pointer model -are transformed into events of one pointer. They are necessary to -ensure that old single-pointer applications work in a multiple pointer -environment intuitively and as expected by the user.

    However, the new TPointerEvent types, EEnterCloseProximity, EExitCloseProximity, EEnterHighPressure and EExitHighPressure, are delivered to all -windows, even to those that do not enable advanced pointers.

    3. -
-
Getting -Z coordinates from TPointerEvent
    -

  1. Call TPointerEvent::AdvancedPointerEvent() on -a TPointerEvent to return a pointer to a TAdvancedPointerEvent.

    -TZType aZType; -TPointerEvent& aPointerEvent; -TInt* aZ; -TInt* aPoint3D; - -TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent(); -

    TPointerEvent is a struct that contains -details of a pointer event. TZType is a struct provided -by the programmer containing members to hold proximity, pressure, -and "proximity and pressure" data.

    2. -

  2. Now we need -to test whether the pointer event contains advanced pointer data. -If it is not an advanced pointer, the code leaves.

    If it is -an advanced pointer, we call functions to detect proximity, pressure, -"proximity and pressure" data and coordinates.

    -if(!advancedP) - { - // The TPointerEvent isn't an instance of TAdvancedPointerEvent - User::Leave(KErrArgument); - } - -switch(aZType) - { - case EZTypeProximity: - aZ = advancedP->Proximity(); - aPoint3D = advancedP->Proximity3D(); - break; - case EZTypePressure: - aZ = advancedP->Pressure(); - aPoint3D = advancedP->Pressure3D(); - break; - case EZTypeProximityAndPressure: - aZ = advancedP->ProximityAndPressure(); - aPoint3D = advancedP->ProximityAndPressure3D(); - break; - default: - User::Leave(KErrArgument); - break; - } -
      -

    • TAdvancedPointerEvent::Proximity() returns -the proximity.

      • -

    • TAdvancedPointerEvent::Pressure() returns -the pressure.

      • -

    • TAdvancedPointerEvent::ProximityAndPressure() returns the proximity and pressure combined.

      • -

    • TAdvancedPointerEvent:: Position3D() returns -the proximity and the X, Y and Z coordinates.

      • -

    • TAdvancedPointerEvent::Pressure3D() returns -the pressure and the X and Y coordinates.

      • -

    Proximity is always negative and pressure is always positive. Internally they are combined together as a Z coordinate. -When Z > 0, the proximity is 0 and the Z value represents the pressure. -When Z < 0, the pressure is 0 and the Z value represents the proximity. -Some APIs use only a Z coordinate (such as the threshold getters and -setters and TAdvancedPointerEvent::ProximityAndPressure()). In these, the Z coordinate is interpreted in terms of pressure -and proximity.

    3. -
- Relationships between the pointer proximity, pressure and -Z coordinate -
-
Pinch -zooming

This example shows an easy way to pinch zoom an -image when the screen receives pointer events from two pointers. There -are two functions in this code that must be implemented by the programmer: BitmapCoordinates() and MoveBitmap(). They -are not included in the example because they involve complex calculations -that are not related to advanced pointers.

The high-level -steps to perform pinch zooming are:

    -

  1. Define the coordinates, -equivalent to the given on-screen coordinates. In the code example, -this is done using the function BitmapCoordinates().

    2. -

  2. Define the ID -of the pointer by using TAdvancedPointerEvent::PointerNumber(). -If the device can handle two pointers (two fingers) at the same time, -their numbers are 0 and 1. The pointer number enables you to distinguish -a given pointer from other pointers.

    3. -

  3. For each pointer -assign its coordinates to a local variable. We assume there are only -two pointers handled by the system here.

    4. -

  4. Use the MoveBitmap() function to achieve the zoom effect.

    -/** -Receives pointer events from two pointers to perform Pinch Zoom of the image. -Function will finish when EButton1Up is received for any of the pointers. -@param aPointer1 Coordinates of pointer number 1 when zoom is started -@param aPointer2 Coordinates of pointer number 2 when zoom is started -*/ - -void PinchZoom(TPoint aPointer1, TPoint aPointer2) - { - TPoint actualP1 = aPointer1; - TPoint actualP2 = aPointer2; - - // translate on-screen pointer coordinates to coordinates of displayed bitmap - TPoint bitmapCatching1 = BitmapCoordinates(aPointer1); - TPoint bitmapCatching2 = BitmapCoordinates(aPointer2); - - TBool repaint = EFalse; - - while (ETrue) - { - TAdvancedPointerEvent event = GetNextPointerEvent(); - - if (event.iType == TPointerEvent::EDrag) - { - if (event.PointerNumber() == 1) - { - actualP1 = event.iPosition; - repaint = ETrue; - } - else if (event.PointerNumber() == 2) - { - actualP2 = event.iPosition; - repaint = ETrue; - } - } - else if (event.iType == TPointerEvent::EButton1Up) - { - break; - } - - if (repaint) - { - // move bitmap on the screen in the way that - // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate, - // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate. - MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2); - repaint = EFalse; - } - } - } -
    5. -
- - -Advanced Pointer Overview -Advanced Pointer States and Event Communication - - - - + + + + + + Advanced Pointer TutorialThis tutorial provides step-by-step instructions and sample +code to help you write applications using advanced pointers. +

Variant: ScreenPlay. Target audience: Application developers.

+
Required background

This topic builds +on the material in the following topics:

    +

  • Advanced Pointer +Overview

    • +

  • Advanced Pointer +States and Event Communication

    • +
+
Using advanced pointers

This topic covers +the following:

    +

  • Enabling multiple pointers in a window

    • +

  • Getting Z coordinates from TPointerEvent

    • +

  • Pinch zooming

    • +
+
Enabling +multiple pointers in a window
    +

  1. RWindow provides +a handle to a standard window. Call RWindow to create +an instance of a window.

    +RWindow window(ws); + +User::LeaveIfError(window.Construct(wg, reinterpret_cast<TUint32>(&wg) + 1)); +
    2. +

  2. Call RWindow::EnableAdvancedPointers() to enable advanced pointers. +Then call RWindowBase::Activate() to display the +window and enable the window to receive events. RWindow inherits from RWindowBase, so you can call the Activate() function on RWindow.

    +window.EnableAdvancedPointers(); +window.Activate(); +

    When an application needs to receive advanced pointer +events in a window, it must call RWindowBase::EnableAdvancedPointers() for the window before it is activated.

    If advanced +pointers are not enabled for a window, it receives only standard TPointerEvent information from a single pointer with no +pressure and proximity data. The single pointer environment rules +describe the way in which pointer events coming from many pointers +in the multiple pointer model are transformed into events of one pointer. +They are necessary to ensure that old single-pointer applications +work in a multiple pointer environment intuitively and +as expected by the user.

    However, the new TPointerEvent types, EEnterCloseProximity, EExitCloseProximity, EEnterHighPressure and EExitHighPressure, are delivered to all windows, even to those that do not enable +advanced pointers.

    3. +
+
Getting +Z coordinates from TPointerEvent
    +

  1. Call TPointerEvent::AdvancedPointerEvent() on a TPointerEvent to return a pointer to a TAdvancedPointerEvent.

    +TZType aZType; +TPointerEvent& aPointerEvent; +TInt* aZ; +TInt* aPoint3D; + +TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent(); +

    TPointerEvent is a struct that contains +details of a pointer event. TZType is a struct provided +by the programmer containing members to hold proximity, pressure, +and "proximity and pressure" data.

    2. +

  2. Now we need +to test whether the pointer event contains advanced pointer data. +If it is not an advanced pointer, the code leaves.

    If it is +an advanced pointer, we call functions to detect proximity, pressure, +"proximity and pressure" data and coordinates.

    +if(!advancedP) + { + // The TPointerEvent isn't an instance of TAdvancedPointerEvent + User::Leave(KErrArgument); + } + +switch(aZType) + { + case EZTypeProximity: + aZ = advancedP->Proximity(); + aPoint3D = advancedP->Proximity3D(); + break; + case EZTypePressure: + aZ = advancedP->Pressure(); + aPoint3D = advancedP->Pressure3D(); + break; + case EZTypeProximityAndPressure: + aZ = advancedP->ProximityAndPressure(); + aPoint3D = advancedP->ProximityAndPressure3D(); + break; + default: + User::Leave(KErrArgument); + break; + } +
      +

    • TAdvancedPointerEvent::Proximity() returns the proximity.

      • +

    • TAdvancedPointerEvent::Pressure() returns the pressure.

      • +

    • TAdvancedPointerEvent::ProximityAndPressure() returns the proximity and pressure combined.

      • +

    • TAdvancedPointerEvent:: +Position3D() returns the proximity and the X, Y and Z coordinates.

      • +

    • TAdvancedPointerEvent::Pressure3D() returns the pressure and the X and Y coordinates.

      • +

    Proximity is always negative and pressure is always positive. Internally they are combined together as a Z coordinate. +When Z > 0, the proximity is 0 and the Z value represents the pressure. +When Z < 0, the pressure is 0 and the Z value represents the proximity. +Some APIs use only a Z coordinate (such as the threshold getters and +setters and TAdvancedPointerEvent::ProximityAndPressure()). In these, the Z coordinate is interpreted in terms of pressure +and proximity.

    3. +
+ Relationships between the pointer proximity, pressure and +Z coordinate + +
+
Pinch +zooming

This example shows an easy way to pinch zoom an +image when the screen receives pointer events from two pointers. There +are two functions in this code that must be implemented by the programmer: BitmapCoordinates() and MoveBitmap(). They +are not included in the example because they involve complex calculations +that are not related to advanced pointers.

The high-level +steps to perform pinch zooming are:

    +

  1. Define the coordinates, +equivalent to the given on-screen coordinates. In the code example, +this is done using the function BitmapCoordinates().

    2. +

  2. Define the ID +of the pointer by using TAdvancedPointerEvent::PointerNumber(). If the device can handle two pointers (two fingers) at the same +time, their numbers are 0 and 1. The pointer number enables you to +distinguish a given pointer from other pointers.

    3. +

  3. For each pointer +assign its coordinates to a local variable. We assume there are only +two pointers handled by the system here.

    4. +

  4. Use the MoveBitmap() function to achieve the zoom effect.

    +/** +Receives pointer events from two pointers to perform Pinch Zoom of the image. +Function will finish when EButton1Up is received for any of the pointers. +@param aPointer1 Coordinates of pointer number 1 when zoom is started +@param aPointer2 Coordinates of pointer number 2 when zoom is started +*/ + +void PinchZoom(TPoint aPointer1, TPoint aPointer2) + { + TPoint actualP1 = aPointer1; + TPoint actualP2 = aPointer2; + + // translate on-screen pointer coordinates to coordinates of displayed bitmap + TPoint bitmapCatching1 = BitmapCoordinates(aPointer1); + TPoint bitmapCatching2 = BitmapCoordinates(aPointer2); + + TBool repaint = EFalse; + + while (ETrue) + { + TAdvancedPointerEvent event = GetNextPointerEvent(); + + if (event.iType == TPointerEvent::EDrag) + { + if (event.PointerNumber() == 1) + { + actualP1 = event.iPosition; + repaint = ETrue; + } + else if (event.PointerNumber() == 2) + { + actualP2 = event.iPosition; + repaint = ETrue; + } + } + else if (event.iType == TPointerEvent::EButton1Up) + { + break; + } + + if (repaint) + { + // move bitmap on the screen in the way that + // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate, + // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate. + MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2); + repaint = EFalse; + } + } + } +
    5. +
+ +Advanced +Pointer Overview +Advanced +Pointer States and Event Communication + \ No newline at end of file