README.ds
author Sam Lantinga <slouken@libsdl.org>
Wed, 03 Oct 2012 20:49:16 -0700
changeset 6555 f2c03c06d987
parent 6285 f12649068adb
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.
     1 ================================================================================
     2 Simple DirectMedia Layer for Nintendo DS
     3 ================================================================================
     4 
     5 -Requirements-
     6 * The devkitpro SDK available at http://devkitpro.org.
     7   Read the information at http://devkitpro.org/wiki/Getting_Started/devkitARM
     8   The necessary packages are devkitARM, libnds, libfat and default arm7.
     9 * Optionally, use a DS emulator, such as desmume (http://desmume.org/)
    10   to program and debug.
    11 
    12 -Building SDL-
    13 
    14 After setting the devkitpro environment, cd into your SDL directory and type:
    15   make -f Makefile.ds
    16 
    17 This will compile and install the library and headers into the
    18 devkitpro's portlibs directory (../portlibs/arm/lib/ and
    19 ../portlibs/arm/include/). Additionally it will compile several tests
    20 that you can run either on the DS or with desmume. For instance:
    21   desmume --cflash-path=test/ test/nds-test-progs/testsprite2/testsprite2.nds
    22   desmume --cflash-path=test/ test/nds-test-progs/testspriteminimal/testspriteminimal.nds
    23   desmume --cflash-path=test/ test/nds-test-progs/testscale/testscale.nds 
    24   desmume test/nds-test-progs/general/general.nds
    25 
    26 -Notes-
    27 * The renderer code is based on the gl like engine. It's not using the sprite engine.
    28 * The hardware renderer is using the parts of the libgl2d abstraction library that can be found at:
    29     http://rel.phatcode.net/junk.php?id=117
    30   Used with the author's permission.
    31 * The port is very basic and incomplete:
    32   - SDL currently has to be compiled for either framebuffer mode or renderer mode.
    33      See USE_HW_RENDERER in Makefile.ds.
    34   - some optional renderer functions are not implemented.
    35   - no sound
    36 
    37 -Limitations-
    38 * in hardware renderer mode, don't load too many textures. The internal format is
    39   2 bytes per pixel. And there is only 256KB reserved for the textures. For instance,
    40   testscale won't display sample.bmp, unless it's resized to a smaller picture.
    41 * the screen size is 256 x 384. Anything else won't work.
    42 * there is no 8 bits/pixel mode because SDL 2.0 doesn't support palettes.
    43 
    44 -Joystick mapping-
    45 The Joystick presented to SDL has 2 axes and 8 buttons
    46 
    47  KEY      | Code
    48   A       |   0
    49   B       |   1
    50   X       |   2
    51   Y       |   3
    52   L       |   4
    53   R       |   5
    54   select  |   6
    55   start   |   7
    56 
    57  Left-right is axe 0.
    58  Up-down is axe 1.
    59 
    60 -Mouse mapping-
    61 todo
    62 
    63 -Examples-
    64 Due to memory limitations, to be able to successfully run the testscale example, sample.bmp must be resized to 256x105.