README.touch
author Sam Lantinga <slouken@libsdl.org>
Wed, 03 Oct 2012 20:49:16 -0700
changeset 6555 f2c03c06d987
parent 4693 2ede56a19f2f
child 6987 7084af936d82
permissions -rw-r--r--
Fixed bug 1614 - SDL for Android does not implement TextInput API

Andrey Isakov 2012-10-03 08:30:25 PDT

I've found out in the process of porting one OS project to Android/SDL2 that
there is no support for TextInput events/APIs on Android.
So I implemented some kind of initial support of that feature, and at the very
least it seems to work fine with latin chars input with soft and hardware
keyboards on my Moto Milestone2. I've also tried playing around with more
complex IMEs, like japanese, logging the process and it seemed to work too. I'm
not sure since the app itself I am working on does not have support for
non-latin input.

The main point of the patch is to place a fake input view in the region
specified by SDL_SetTextInputRect and create a custom InputConnection for it.
The reason to make it a separate view is to support Android's pan&scan on input
feature properly. For details please refer to
http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html
Even though the manual states that SetTextInputRect is used to determine the
IME variants position, I thought this would be a proper use for this too.
jim@4690
     1
===========================================================================
jim@4690
     2
System Specific Notes
jim@4690
     3
===========================================================================
jim@4690
     4
Linux:
jim@4690
     5
The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at jim.tla+sdl_touch@gmail.com and I will help you get support for it.
jim@4690
     6
jim@4690
     7
Mac: 
jim@4690
     8
The Mac and Iphone API's are pretty. If your touch device supports them then you'll be fine. If it doesn't, then there isn't much we can do.
jim@4690
     9
jim@4690
    10
iPhone: 
jim@4690
    11
Works out of box.
jim@4690
    12
slouken@4693
    13
Windows:
jim@4690
    14
Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at jim.tla+sdl_touch@gmail.com
jim@4690
    15
jim@4689
    16
===========================================================================
jim@4689
    17
Events
jim@4689
    18
===========================================================================
jim@4689
    19
SDL_FINGERDOWN:
jim@4689
    20
Sent when a finger (or stylus) is placed on a touch device.
jim@4689
    21
Fields:
jim@4689
    22
event.tfinger.touchId  - the Id of the touch device.
jim@4689
    23
event.tfinger.fingerId - the Id of the finger which just went down.
jim@4689
    24
event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
jim@4689
    25
event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
jim@4689
    26
event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)
jim@4689
    27
jim@4689
    28
SDL_FINGERMOTION:
jim@4689
    29
Sent when a finger (or stylus) is moved on the touch device.
jim@4689
    30
Fields:
jim@4689
    31
Same as FINGERDOWN but with additional:
jim@4690
    32
event.tfginer.dx       - change in x coordinate during this motion event.
jim@4690
    33
event.tfginer.dy       - change in y coordinate during this motion event.
jim@4689
    34
jim@4689
    35
SDL_FINGERMOTION:
jim@4689
    36
Sent when a finger (or stylus) is lifted from the touch device.
jim@4689
    37
Fields:
jim@4689
    38
Same as FINGERDOWN.
jim@4689
    39
jim@4689
    40
jim@4689
    41
===========================================================================
jim@4689
    42
Functions
jim@4689
    43
===========================================================================
jim@4689
    44
SDL provides the ability to access the underlying Touch and Finger structures.
jim@4689
    45
These structures should _never_ be modified.
jim@4689
    46
jim@4689
    47
The following functions are included from SDL_Touch.h
jim@4689
    48
jim@4689
    49
To get a SDL_Touch device call SDL_GetTouch(touchId). 
jim@4689
    50
This returns an SDL_Touch*. 
jim@4689
    51
IMPORTANT: If the touch has been removed, or there is no touch with the given ID, SDL_GetTouch will return null. Be sure to check for this!
jim@4689
    52
jim@4689
    53
An SDL_Touch has the following fields:
jim@4690
    54
>xres,yres,pressures:
jim@4690
    55
	The resolution at which x,y, and pressure values are reported. Currently these will always be equal to 2^15, but this may not always be the case. 
jim@4690
    56
jim@4689
    57
>pressure_max, pressure_min, x_max, x_min, y_max, y_min
jim@4689
    58
	Which give, respectively, the maximum and minumum values that the touch digitizer can return for pressure, x coordiniate, and y coordinate AS REPORTED BY THE OPERATING SYSTEM.
jim@4689
    59
On Mac/iPhone systems _max will always be 0, and _min will always be 1. 
jim@4689
    60
jim@4689
    61
>native_xres,native_yres,native_pressureres:
jim@4689
    62
	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
jim@4689
    63
On Mac/iPhone systems these will always be 1.
jim@4689
    64
jim@4689
    65
>num_fingers:
jim@4689
    66
	The number of fingers currently down on the device.
jim@4689
    67
jim@4689
    68
>fingers:
jim@4689
    69
	An array of pointers to the fingers which are on the device.
jim@4689
    70
jim@4689
    71
jim@4690
    72
The most common reason to access a touch device is to normalize inputs. This would be accomplished by code like the following:
jim@4689
    73
jim@4689
    74
      SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
jim@4690
    75
      if(inTouch == NULL) continue; //The touch has been removed
jim@4689
    76
jim@4689
    77
      float x = ((float)event.tfinger.x)/inTouch->xres;
jim@4690
    78
      float y = ((float)event.tfinger.y)/inTouch->yres;
jim@4690
    79
jim@4689
    80
jim@4689
    81
jim@4689
    82
To get an SDL_Finger, call SDL_GetFinger(touch,fingerId), where touch is a pointer to an SDL_Touch device, and fingerId is the id of the requested finger.
jim@4689
    83
This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
jim@4690
    84
An SDL_Finger is guaranteed to be persistent for the duration of a touch, but it will be de-allocated as soon as the finger is removed. This occurs when the SDL_FINGERUP event is _added_ to the event queue, and thus _before_ the FINGERUP event is polled. 
jim@4689
    85
As a result, be very careful to check for null return values.
jim@4689
    86
jim@4689
    87
An SDL_Finger has the following fields:
jim@4689
    88
>x,y,pressure:
jim@4689
    89
	The current coordinates of the touch.
jim@4689
    90
>xdelta,ydelta: 
jim@4689
    91
	The change in position resulting from the last finger motion.
jim@4689
    92
>last_x, last_y, last_pressure:
jim@4690
    93
	 The previous coordinates of the touch.
jim@4690
    94
jim@4690
    95
===========================================================================
jim@4690
    96
Notes
jim@4690
    97
===========================================================================
jim@4690
    98
For a complete example see test/testgesture.c
jim@4690
    99
jim@4690
   100
Please direct questions/comments to:
slouken@4693
   101
   jim.tla+sdl_touch@gmail.com