From 7250e52f84bf50fa6e25196b639e2879f7e52044 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Fri, 2 Nov 2012 02:37:49 -0700
Subject: [PATCH] Updated the Android project template and README.android Added
 information on how to customize your application name and icon. Added
 information on using STL with an Android application Increased the minimum
 API level to 10, because that's the lowest API that currently has an emulator
 image for testing.

---
 README.Platforms                              |   3 +-
 README.android                                |  76 +++++++++--
 android-project/AndroidManifest.xml           |  47 ++++++-
 android-project/ant.properties                |  17 +++
 android-project/build.xml                     | 128 +++++++++++-------
 android-project/default.properties            |   2 +-
 android-project/jni/Application.mk            |   4 +
 android-project/local.properties              |   2 +-
 android-project/proguard-project.txt          |  20 +++
 android-project/project.properties            |  14 ++
 .../src/org/libsdl/app/SDLActivity.java       |   2 +-
 11 files changed, 248 insertions(+), 67 deletions(-)
 create mode 100644 android-project/ant.properties
 create mode 100644 android-project/jni/Application.mk
 create mode 100644 android-project/proguard-project.txt
 create mode 100644 android-project/project.properties

diff --git a/README.Platforms b/README.Platforms
index a766e0e30..32fb0d083 100644
--- a/README.Platforms
+++ b/README.Platforms
@@ -11,13 +11,12 @@ Windows 7
 Mac OS X 10.4+
 Linux 2.6+
 iOS 3.1.3+
-Android 1.6+
+Android 2.1+
 
 Unofficially supported platforms
 ================================
 (code compiles, but not thoroughly tested)
 ================================
-Windows CE
 FreeBSD
 NetBSD
 OpenBSD
diff --git a/README.android b/README.android
index 2e02dc2d2..30948f5dc 100644
--- a/README.android
+++ b/README.android
@@ -39,18 +39,16 @@ src/main/android/SDL_android_main.cpp
 
 Instructions:
 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
-2. Move this SDL directory into the <project>/jni directory and then copy
-SDL_config_android.h to SDL_config.h inside the include folder
-3. Place your application source files in the <project>/jni/src directory
-4. Edit <project>/jni/src/Android.mk to include your source files
-5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
+2. Move or symlink this SDL directory into the <project>/jni directory
+3. Edit <project>/jni/src/Android.mk to include your source files
+4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
 
 If you want to use the Eclipse IDE, skip to the Eclipse section below.
 
-6. Edit <project>/local.properties to point to the Android SDK directory
-7. Run 'ant debug' in android/project. This compiles the .java and eventually 
+5. Edit <project>/local.properties to point to the Android SDK directory
+6. Run 'ant debug' in android/project. This compiles the .java and eventually 
 creates a .apk with the native code embedded
-8. 'ant install' will push the apk to the device or emulator (if connected)
+7. 'ant install' will push the apk to the device or emulator (if connected)
 
 Here's an explanation of the files in the Android project, so you can customize them:
 
@@ -73,6 +71,58 @@ android-project/
 	src/org/libsdl/app/SDLActivity.java	- the Java class handling the initialization and binding to SDL.  Be very careful changing this, as the SDL library relies on this implementation.
 
 
+================================================================================
+ Customizing your application name
+================================================================================
+
+To customize your application name, edit AndroidManifest.xml and replace
+"org.libsdl.app" with an identifier for your product package.
+
+Then create a Java class extending SDLActivity and place it in a directory
+under src matching your package, e.g.
+	src/com/gamemaker/game/MyGame.java
+
+Here's an example of a minimal class file:
+--- MyGame.java --------------------------
+package com.gamemaker.game;
+
+import org.libsdl.app.SDLActivity; 
+import android.os.*; 
+
+/* 
+ * A sample wrapper class that just calls SDLActivity 
+ */ 
+
+public class MyGame extends SDLActivity { 
+    protected void onCreate(Bundle savedInstanceState) { 
+	super.onCreate(savedInstanceState); 
+    } 
+   
+    protected void onDestroy() { 
+	super.onDestroy(); 
+    } 
+}
+------------------------------------------
+
+Then replace "SDLActivity" in AndroidManifest.xml with the name of your
+class, .e.g. "MyGame"
+
+================================================================================
+ Customizing your application icon
+================================================================================
+
+Conceptually changing your icon is just replacing the icon.png files in the
+drawable directories under the res directory.
+
+The easiest way to create a set of icons for your project is to remove all
+the existing icon.png files, and then use the Eclipse IDE to create a dummy
+project.  During the process of doing this Eclipse will prompt you to create
+an icon. Then just copy the drawable directories it creates over to your
+res directory.
+
+You may need to change the name of your icon in AndroidManifest.xml to match
+the filename used by Eclipse.
+
 ================================================================================
  Pause / Resume behaviour
 ================================================================================
@@ -105,6 +155,16 @@ Android_JNI_SetupThread before doing anything else otherwise SDL will attach
 your thread automatically anyway (when you make an SDL call), but it'll never
 detach it.
 
+================================================================================
+ Using STL
+================================================================================
+
+You can use STL in your project by creating an Application.mk file in the jni
+folder and adding the following line:
+APP_STL := stlport_static
+
+For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
+
 ================================================================================
  Additional documentation
 ================================================================================
diff --git a/android-project/AndroidManifest.xml b/android-project/AndroidManifest.xml
index 8fbb3e6af..f9a30fde3 100644
--- a/android-project/AndroidManifest.xml
+++ b/android-project/AndroidManifest.xml
@@ -1,12 +1,44 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    <!-- Replace org.libsdl.app with the identifier of your game, e.g.
+         com.gamemaker.game
+     -->
       package="org.libsdl.app"
       android:versionCode="1"
-      android:versionName="1.0">
+      android:versionName="1.0"
+      android:installLocation="auto">
 
-    <uses-sdk android:minSdkVersion="5" />
+    <!-- Create a Java class extending SDLActivity and place it in a
+         directory under src matching the package, e.g.
+         	src/com/gamemaker/game/MyGame.java
 
-    <application android:label="@string/app_name" android:icon="@drawable/icon">
+        /**********************************************************/
+	package com.gamemaker.game;
+
+	import org.libsdl.app.SDLActivity; 
+	import android.os.*; 
+
+	/* 
+	 * A sample wrapper class that just calls SDLActivity 
+	 */ 
+
+	public class MyGame extends SDLActivity { 
+	    protected void onCreate(Bundle savedInstanceState) { 
+	        super.onCreate(savedInstanceState); 
+	    } 
+	   
+	    protected void onDestroy() { 
+	        super.onDestroy(); 
+	    } 
+	}
+        /**********************************************************/
+
+         then replace "SDLActivity" in the XML below with the name of
+         your class, e.g. "MyGame" ...
+    -->
+    <application android:label="@string/app_name"
+                 android:icon="@drawable/icon"
+	         android:theme="@android:style/Theme.NoTitleBar.Fullscreen">
         <activity android:name="SDLActivity"
                   android:label="@string/app_name">
             <intent-filter>
@@ -15,4 +47,13 @@
             </intent-filter>
         </activity>
     </application>
+
+    <!-- Android 2.1 -->
+    <uses-sdk android:minSdkVersion="10" /> 
+
+    <!-- OpenGL ES 2.0 -->
+    <uses-feature android:glEsVersion="0x00020000" /> 
+
+    <!-- Allow writing to external storage -->
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 
 </manifest> 
diff --git a/android-project/ant.properties b/android-project/ant.properties
new file mode 100644
index 000000000..b0971e891
--- /dev/null
+++ b/android-project/ant.properties
@@ -0,0 +1,17 @@
+# This file is used to override default values used by the Ant build system.
+#
+# This file must be checked into Version Control Systems, as it is
+# integral to the build system of your project.
+
+# This file is only used by the Ant script.
+
+# You can use this to override default values such as
+#  'source.dir' for the location of your java source folder and
+#  'out.dir' for the location of your output folder.
+
+# You can also use it define how the release builds are signed by declaring
+# the following properties:
+#  'key.store' for the location of your keystore and
+#  'key.alias' for the name of the key to use.
+# The password will be asked during the build when you use the 'release' target.
+
diff --git a/android-project/build.xml b/android-project/build.xml
index 37b376807..9f19a077b 100644
--- a/android-project/build.xml
+++ b/android-project/build.xml
@@ -1,67 +1,93 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project name="SDLApp" default="help">
+<!-- This should be changed to the name of your project -->
+<project name="SDLActivity" default="help">
 
     <!-- The local.properties file is created and updated by the 'android' tool.
-         It contains the path to the SDK. It should *NOT* be checked in in Version
-         Control Systems. -->
+         It contains the path to the SDK. It should *NOT* be checked into
+         Version Control Systems. -->
     <property file="local.properties" />
 
-    <!-- The build.properties file can be created by you and is never touched
-         by the 'android' tool. This is the place to change some of the default property values
-         used by the Ant rules.
+    <!-- The ant.properties file can be created by you. It is only edited by the
+         'android' tool to add properties to it.
+         This is the place to change some Ant specific build properties.
          Here are some properties you may want to change/update:
 
-         application.package
-             the name of your application package as defined in the manifest. Used by the
-             'uninstall' rule.
          source.dir
-             the name of the source directory. Default is 'src'.
+             The name of the source directory. Default is 'src'.
          out.dir
-             the name of the output directory. Default is 'bin'.
+             The name of the output directory. Default is 'bin'.
 
-         Properties related to the SDK location or the project target should be updated
-          using the 'android' tool with the 'update' action.
+         For other overridable properties, look at the beginning of the rules
+         files in the SDK, at tools/ant/build.xml
 
-         This file is an integral part of the build system for your application and
-         should be checked in in Version Control Systems.
+         Properties related to the SDK location or the project target should
+         be updated using the 'android' tool with the 'update' action.
+
+         This file is an integral part of the build system for your
+         application and should be checked into Version Control Systems.
 
          -->
-    <property file="build.properties" />
-
-    <!-- The default.properties file is created and updated by the 'android' tool, as well
-         as ADT.
-         This file is an integral part of the build system for your application and
-         should be checked in in Version Control Systems. -->
-    <property file="default.properties" />
-
-    <!-- Custom Android task to deal with the project target, and import the proper rules.
-         This requires ant 1.6.0 or above. -->
-    <path id="android.antlibs">
-        <pathelement path="${sdk.dir}/tools/lib/anttasks.jar" />
-        <pathelement path="${sdk.dir}/tools/lib/sdklib.jar" />
-        <pathelement path="${sdk.dir}/tools/lib/androidprefs.jar" />
-        <pathelement path="${sdk.dir}/tools/lib/apkbuilder.jar" />
-        <pathelement path="${sdk.dir}/tools/lib/jarutils.jar" />
-    </path>
-
-    <taskdef name="setup"
-        classname="com.android.ant.SetupTask"
-        classpathref="android.antlibs" />
-
-    <!-- Execute the Android Setup task that will setup some properties specific to the target,
-         and import the build rules files.
-
-         The rules file is imported from
-            <SDK>/platforms/<target_platform>/templates/android_rules.xml
-
-         To customize some build steps for your project:
-         - copy the content of the main node <project> from android_rules.xml
-         - paste it in this build.xml below the <setup /> task.
-         - disable the import by changing the setup task below to <setup import="false" />
-
-         This will ensure that the properties are setup correctly but that your customized
-         build steps are used.
+    <property file="ant.properties" />
+
+    <!-- if sdk.dir was not set from one of the property file, then
+         get it from the ANDROID_HOME env var.
+         This must be done before we load project.properties since
+         the proguard config can use sdk.dir -->
+    <property environment="env" />
+    <condition property="sdk.dir" value="${env.ANDROID_HOME}">
+        <isset property="env.ANDROID_HOME" />
+    </condition>
+
+    <!-- The project.properties file is created and updated by the 'android'
+         tool, as well as ADT.
+
+         This contains project specific properties such as project target, and library
+         dependencies. Lower level build properties are stored in ant.properties
+         (or in .classpath for Eclipse projects).
+
+         This file is an integral part of the build system for your
+         application and should be checked into Version Control Systems. -->
+    <loadproperties srcFile="project.properties" />
+
+    <!-- quick check on sdk.dir -->
+    <fail
+            message="sdk.dir is missing. Make sure to generate local.properties using 'android update project' or to inject it through the ANDROID_HOME environment variable."
+            unless="sdk.dir"
+    />
+
+    <!--
+        Import per project custom build rules if present at the root of the project.
+        This is the place to put custom intermediary targets such as:
+            -pre-build
+            -pre-compile
+            -post-compile (This is typically used for code obfuscation.
+                           Compiled code location: ${out.classes.absolute.dir}
+                           If this is not done in place, override ${out.dex.input.absolute.dir})
+            -post-package
+            -post-build
+            -pre-clean
+    -->
+    <import file="custom_rules.xml" optional="true" />
+
+    <!-- Import the actual build file.
+
+         To customize existing targets, there are two options:
+         - Customize only one target:
+             - copy/paste the target into this file, *before* the
+               <import> task.
+             - customize it to your needs.
+         - Customize the whole content of build.xml
+             - copy/paste the content of the rules files (minus the top node)
+               into this file, replacing the <import> task.
+             - customize to your needs.
+
+         ***********************
+         ****** IMPORTANT ******
+         ***********************
+         In all cases you must update the value of version-tag below to read 'custom' instead of an integer,
+         in order to avoid having your file be overridden by tools such as "android update project"
     -->
-    <setup />
+    <!-- version-tag: 1 -->
+    <import file="${sdk.dir}/tools/ant/build.xml" />
 
 </project>
diff --git a/android-project/default.properties b/android-project/default.properties
index dbf05f24f..9d135cb85 100644
--- a/android-project/default.properties
+++ b/android-project/default.properties
@@ -8,4 +8,4 @@
 # project structure.
 
 # Project target.
-target=android-5
+target=android-7
diff --git a/android-project/jni/Application.mk b/android-project/jni/Application.mk
new file mode 100644
index 000000000..05cf0c31c
--- /dev/null
+++ b/android-project/jni/Application.mk
@@ -0,0 +1,4 @@
+
+# Uncomment this if you're using STL in your project
+# See CPLUSPLUS-SUPPORT.html in the NDK documentation for more information
+# APP_STL := stlport_static 
diff --git a/android-project/local.properties b/android-project/local.properties
index 2818bb832..be9e6313d 100644
--- a/android-project/local.properties
+++ b/android-project/local.properties
@@ -7,4 +7,4 @@
 # location of the SDK. This is only used by Ant
 # For customization when using a Version Control System, please read the
 # header note.
-sdk.dir=/Users/hercules/eclipse/android-sdk-mac_86
+sdk.dir=/Users/slouken/android-sdk-macosx
diff --git a/android-project/proguard-project.txt b/android-project/proguard-project.txt
new file mode 100644
index 000000000..f2fe1559a
--- /dev/null
+++ b/android-project/proguard-project.txt
@@ -0,0 +1,20 @@
+# To enable ProGuard in your project, edit project.properties
+# to define the proguard.config property as described in that file.
+#
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in ${sdk.dir}/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the ProGuard
+# include property in project.properties.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
diff --git a/android-project/project.properties b/android-project/project.properties
new file mode 100644
index 000000000..b7c2081d5
--- /dev/null
+++ b/android-project/project.properties
@@ -0,0 +1,14 @@
+# This file is automatically generated by Android Tools.
+# Do not modify this file -- YOUR CHANGES WILL BE ERASED!
+#
+# This file must be checked in Version Control Systems.
+#
+# To customize properties used by the Ant build system edit
+# "ant.properties", and override values to adapt the script to your
+# project structure.
+#
+# To enable ProGuard to shrink and obfuscate your code, uncomment this (available properties: sdk.dir, user.home):
+#proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt
+
+# Project target.
+target=android-10
diff --git a/android-project/src/org/libsdl/app/SDLActivity.java b/android-project/src/org/libsdl/app/SDLActivity.java
index 1b60de2dd..d5fda76ab 100644
--- a/android-project/src/org/libsdl/app/SDLActivity.java
+++ b/android-project/src/org/libsdl/app/SDLActivity.java
@@ -734,7 +734,7 @@ public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
         ic = new SDLInputConnection(this, true);
 
         outAttrs.imeOptions = EditorInfo.IME_FLAG_NO_EXTRACT_UI
-                | EditorInfo.IME_FLAG_NO_FULLSCREEN;
+                | 33554432 /* API 11: EditorInfo.IME_FLAG_NO_FULLSCREEN */;
 
         return ic;
     }