diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/html/guide/topics/data/backup.jd | 70 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/actionbar.jd | 22 | ||||
| -rw-r--r-- | docs/html/resources/dashboard/platform-versions.jd | 36 | ||||
| -rw-r--r-- | docs/html/sdk/ndk/index.jd | 326 | ||||
| -rw-r--r-- | docs/html/sdk/ndk/overview.jd | 277 |
5 files changed, 397 insertions, 334 deletions
diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd index 6c02031..623ee22 100644 --- a/docs/html/guide/topics/data/backup.jd +++ b/docs/html/guide/topics/data/backup.jd @@ -7,7 +7,9 @@ page.title=Data Backup <h2>Quickview</h2> <ul> - <li>Back up your data to the cloud in case the user looses it</li> + <li>Back up the user's data to the cloud in case the user loses it</li> + <li>If the user upgrades to a new Android-powered device, your app can restore the user's +data onto the new device</li> <li>Easily back up SharedPreferences and private files with BackupAgentHelper</li> <li>Requires API Level 8</li> </ul> @@ -389,7 +391,7 @@ conceptually a set of key-value pairs.</p> <p>To add an entity to your backup data set, you must:</p> <ol> <li>Call {@link android.app.backup.BackupDataOutput#writeEntityHeader(String,int) -writeEntityheader()}, passing a unique string key for the data you're about to write and the data +writeEntityHeader()}, passing a unique string key for the data you're about to write and the data size.</li> <li>Call {@link android.app.backup.BackupDataOutput#writeEntityData(byte[],int) writeEntityData()}, passing a byte buffer that contains your data and the number of bytes to write @@ -403,8 +405,8 @@ single entity:</p> ByteArrayOutputStream bufStream = new ByteArrayOutputStream(); DataOutputStream outWriter = new DataOutputStream(bufStream); // Write structured data -outWriter.writeString(playerName); -outWriter.writeInt(playerScore); +outWriter.writeUTF(mPlayerName); +outWriter.writeInt(mPlayerScore); // Send the data to the Backup Manager via the BackupDataOutput byte[] buffer = bufStream.toByteArray(); int len = buffer.length; @@ -422,10 +424,10 @@ android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,Pa onBackup()} so you can determine whether another backup is necessary (as handled in step 1). If you do not write the current data state to this file, then {@code oldState} will be empty during the next callback. - <p>Again, the following example saves a representation of the data using the file's -last-modified timestamp:</p> + <p>The following example saves a representation of the current data into {@code newState} using +the file's last-modified timestamp:</p> <pre> -FileOutputStream outstream = new FileOutputStream(stateFile.getFileDescriptor()); +FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor()); DataOutputStream out = new DataOutputStream(outstream); long modified = mDataFile.lastModified(); @@ -493,7 +495,8 @@ onBackup()} is called after the device is restored.</dd> <p>In your implementation of {@link android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) -onRestore()}, you should call {@link android.app.backup.BackupDataInput#readNextHeader()} to iterate +onRestore()}, you should call {@link android.app.backup.BackupDataInput#readNextHeader()} on the +{@code data} to iterate through all entities in the data set. For each entity found, do the following:</p> <ol> @@ -517,6 +520,54 @@ android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,Pa onBackup()}. </ol> +<p>For example, here's how you can restore the data backed up by the example in the previous +section:</p> + +<pre> +@Override +public void onRestore(BackupDataInput data, int appVersionCode, + ParcelFileDescriptor newState) throws IOException { + // There should be only one entity, but the safest + // way to consume it is using a while loop + while (data.readNextHeader()) { + String key = data.getKey(); + int dataSize = data.getDataSize(); + + // If the key is ours (for saving top score). Note this key was used when + // we wrote the backup entity header + if (TOPSCORE_BACKUP_KEY.equals(key)) { + // Create an input stream for the BackupDataInput + byte[] dataBuf = new byte[dataSize]; + data.readEntityData(dataBuf, 0, dataSize); + ByteArrayInputStream baStream = new ByteArrayInputStream(dataBuf); + DataInputStream in = new DataInputStream(baStream); + + // Read the player name and score from the backup data + mPlayerName = in.readUTF(); + mPlayerScore = in.readInt(); + + // Record the score on the device (to a file or something) + recordScore(mPlayerName, mPlayerScore); + } else { + // We don't know this entity key. Skip it. (Shouldn't happen.) + data.skipEntityData(); + } + } + + // Finally, write to the state blob (newState) that describes the restored data + FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor()); + DataOutputStream out = new DataOutputStream(outstream); + out.writeUTF(mPlayerName); + out.writeInt(mPlayerScore); +} +</pre> + +<p>In this example, the {@code appVersionCode} parameter passed to {@link +android.app.backup.BackupAgent#onRestore onRestore()} is not used. However, you might want to use +it if you've chosen to perform backup when the user's version of the application has actually moved +backward (for example, the user went from version 1.5 of your app to 1.0). For more information, see +the section about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</p> + <div class="special"> <p>For an example implementation of {@link android.app.backup.BackupAgent}, see the <a href="{@docRoot}resources/samples/BackupRestore/src/com/example/android/backuprestore/ExampleAgent.html">{@code @@ -592,7 +643,8 @@ public class MyPrefsBackupAgent extends BackupAgentHelper { static final String PREFS_BACKUP_KEY = "prefs"; // Allocate a helper and add it to the backup agent - void onCreate() { + @Override + public void onCreate() { SharedPreferencesBackupHelper helper = new SharedPreferencesBackupHelper(this, PREFS); addHelper(PREFS_BACKUP_KEY, helper); } diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index c3d3482..44d75c1 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -455,7 +455,7 @@ Action Bar.</p> <ol> <li>Create a {@link android.widget.SpinnerAdapter} that provides the list of selectable items for the list and the layout to use when drawing each item in the list.</li> - <li>Implement {@link android.app.ActionBar.NavigationCallback} to define the behavior when the + <li>Implement {@link android.app.ActionBar.OnNavigationListener} to define the behavior when the user selects an item from the list.</li> <li>Turn on navigation mode for the Action Bar with {@link android.app.ActionBar#setNavigationMode setNavigationMode()}. For example: @@ -472,17 +472,17 @@ android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. actionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback); </pre> <p>This method takes your {@link android.widget.SpinnerAdapter} and {@link -android.app.ActionBar.NavigationCallback}. More about these next.</p> +android.app.ActionBar.OnNavigationListener}. More about these next.</p> </li> </ol> <p>That's the basic setup. The {@link android.widget.SpinnerAdapter} and {@link -android.app.ActionBar.NavigationCallback} is where most of the work is done. There are many ways +android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are many ways you can implement these to define the functionality for your drop-down navigation. Implementing various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this document—you should refer to the class refrence for more information about implementing it or extending an existing implementation. However, below is a simple example for a {@link -android.widget.SpinnerAdapter} and {@link android.app.ActionBar.NavigationCallback} to get you +android.widget.SpinnerAdapter} and {@link android.app.ActionBar.OnNavigationListener} to get you started.</p> @@ -520,24 +520,24 @@ defined as a resource looks like this:</p> </pre> -<h3 id="NavigationCallback">Example: simple NavigationCallback</h3> +<h3 id="OnNavigationListener">Example: simple OnNavigationListener</h3> -<p>Your implementation of {@link android.app.ActionBar.NavigationCallback} is where you handle +<p>Your implementation of {@link android.app.ActionBar.OnNavigationListener} is where you handle fragment changes or other modifications to your activity when the user selects an item from the drop-down list. There's only one callback method to implement: {@link -android.app.ActionBar.NavigationCallback#onNavigationItemSelected onNavigationItemSelected()}.</p> +android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}.</p> <p>The {@link -android.app.ActionBar.NavigationCallback#onNavigationItemSelected onNavigationItemSelected()} +android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()} method receives the position of the item in the list and an item ID provided by the {@link android.widget.SpinnerAdapter}.</p> <p>Here's an example that instantiates an anonymous implementation of {@link -android.app.ActionBar.NavigationCallback}, which inserts a {@link android.app.Fragment} into the +android.app.ActionBar.OnNavigationListener}, which inserts a {@link android.app.Fragment} into the layout container identified by {@code R.id.fragment_container}:</p> <pre> -mNavigationCallback = new NavigationCallback() { +mOnNavigationListener = new OnNavigationListener() { // Get the same strings provided for the drop-down's ArrayAdapter String[] strings = getResources().getStringArray(R.array.action_list); @@ -556,7 +556,7 @@ mNavigationCallback = new NavigationCallback() { }; </pre> -<p>This instance of {@link android.app.ActionBar.NavigationCallback} can be given to {@link +<p>This instance of {@link android.app.ActionBar.OnNavigationListener} can be given to {@link android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}, in step 4 from above.</p> diff --git a/docs/html/resources/dashboard/platform-versions.jd b/docs/html/resources/dashboard/platform-versions.jd index cef057e..7416764 100644 --- a/docs/html/resources/dashboard/platform-versions.jd +++ b/docs/html/resources/dashboard/platform-versions.jd @@ -52,9 +52,8 @@ Android Market within a 14-day period ending on the data collection date noted b <div class="dashboard-panel"> <img alt="" height="250" width="460" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:7.9,15.0,0.1,40.8,36.2&chl= -Android%201.5|Android%201.6|Other*|Android%202.1|Android%202.2&chco=c4df9b, -6fad0c" /> +src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:6.3,10.6,0.1,39.6,43.4&chl +=Android%201.5|Android%201.6|Other*|Android%202.1|Android%202.2&chco=c4df9b,6fad0c" /> <table> <tr> @@ -62,13 +61,13 @@ Android%201.5|Android%201.6|Other*|Android%202.1|Android%202.2&chco=c4df9b, <th>API Level</th> <th>Distribution</th> </tr> -<tr><td>Android 1.5</td><td>3</td><td>7.9%</td></tr> -<tr><td>Android 1.6</td><td>4</td><td>15.0%</td></tr> -<tr><td>Android 2.1</td><td>7</td><td>40.8%</td></tr> -<tr><td>Android 2.2</td><td>8</td><td>36.2%</td></tr> +<tr><td>Android 1.5</td><td>3</td><td>6.3%</td></tr> +<tr><td>Android 1.6</td><td>4</td><td>10.6%</td></tr> +<tr><td>Android 2.1</td><td>7</td><td>39.6%</td></tr> +<tr><td>Android 2.2</td><td>8</td><td>43.4%</td></tr> </table> -<p><em>Data collected during two weeks ending on November 1, 2010</em></p> +<p><em>Data collected during two weeks ending on December 1, 2010</em></p> <p style="font-size:.9em">* <em>Other: 0.1% of devices running obsolete versions</em></p> </div><!-- end dashboard-panel --> @@ -97,17 +96,16 @@ Android Market within a 14-day period ending on the date indicated on the x-axis <img alt="" height="250" width="660" style="padding:5px;background:#fff" src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,y,r&chxr=0,0,12|1,0,100|2,0,100& -chxl=0%3A%7C2010/05/01%7C05/15%7C06/01%7C06/15%7C07/01%7C07/15%7C08/01%7C08/15%7C09/01%7C09/15%7C10/ -01%7C10/15%7C2010/11/01%7C1%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C2%3A%7C0%25%7C25%25%7C50%25 -%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:98.9,99.3,100.3,100.8,99.7,99. -8,99.8,99.7,99.8,99.9,99.9,99.9,99.9|61.6,63.1,72.7,76.1,78.4,80.9,84.3,86.5,87.9,89.2,90.2,91.1,92. -0|32.0,34.9,45.9,51.0,54.9,58.8,64.0,68.1,70.3,72.1,73.8,75.3,77.0|0.0,0.0,0.8,1.2,1.8,3.3,4.3,11.3, -27.8,32.1,33.4,34.5,36.2&chm=tAndroid%201.5,7caa36,0,0,15,,t::-5|b,c3df9b,0,1,0|tAndroid%201.6, -5b831d,1,0,15,,t::-5|b,aadb5e,1,2,0|tAndroid%202.1,38540b,2,0,15,,t::-5|b,91da1e,2,3,0|tAndroid%202. -2,131d02,3,7,15,,t::-5|B,6fad0c,3,4,0&chg=7,25&chdl=Android%201.5|Android%201.6|Android%202.1| -Android%202.2&chco=add274,94d134,73ad18,507d08" /> - -<p><em>Last historical dataset collected during two weeks ending on November 1, 2010</em></p> +chxl=0:|2010/06/01|06/15|07/01|07/15|08/01|08/15|09/01|09/15|10/01|10/15|11/01|11/15|2010/12/01|1:|0 +%25|25%25|50%25|75%25|100%25|2:|0%25|25%25|50%25|75%25|100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12& +chxtc=0,5&chd=t:100.3,100.8,99.7,99.8,99.8,99.7,99.8,99.9,99.9,99.9,99.9,99.9,99.9|72.7,76.1,78.4,80 +.9,84.3,86.5,87.9,89.2,90.2,91.1,92.0,92.7,93.6|45.9,51.0,54.9,58.8,64.0,68.1,70.3,72.1,73.8,75.3,77 +.0,79.0,83.0|0.8,1.2,1.8,3.3,4.3,11.3,27.8,32.1,33.4,34.5,36.2,38.3,43.4&chm=tAndroid%201.5,7caa36,0 +,0,15,,t::-5|b,c3df9b,0,1,0|tAndroid%201.6,5b831d,1,0,15,,t::-5|b,aadb5e,1,2,0|tAndroid%202.1,38540b +,2,0,15,,t::-5|b,91da1e,2,3,0|tAndroid%202.2,131d02,3,5,15,,t::-5|B,6fad0c,3,4,0&chg=7,25&chdl= +Android%201.5|Android%201.6|Android%202.1|Android%202.2&chco=add274,94d134,73ad18,507d08" /> + +<p><em>Last historical dataset collected during two weeks ending on December 1, 2010</em></p> </div><!-- end dashboard-panel --> diff --git a/docs/html/sdk/ndk/index.jd b/docs/html/sdk/ndk/index.jd index 0f36345..2c8e4c2 100644 --- a/docs/html/sdk/ndk/index.jd +++ b/docs/html/sdk/ndk/index.jd @@ -67,73 +67,71 @@ padding: .25em 1em; width="9px" /> Android NDK, Revision 5</a> <em>(November 2010)</em> <div class="toggleme"> - <dl> - <dt>NDK r5 notes:</dt> - - <dd> - <p>The r5 release of the NDK includes many new APIs, many of which are introduced to - support native game development and applications that require similar requirements. Most - notably, native activities are now supported, which allow you to write an application - entirely with native code. For detailed information describing the changes in this - release, read the CHANGES.HTML document included in the downloaded NDK package.</p> - </dd> - </dl> - + <p>This release of the NDK includes many new APIs, most of which are introduced to + support the development of games and similar applications that make extensive use + of native code. Using the APIs, developers have direct native access to events, audio, + graphics and window management, assets, and storage. Developers can also implement the + Android application lifecycle in native code with help from the new + {@link android.app.NativeActivity} class. For detailed information describing the changes in this + release, read the CHANGES.HTML document included in the downloaded NDK package. + </p> <dl> <dt>General notes:</dt> - <dd> <ul> - - <li>A new toolchain (based on GCC 4.4.3), which generates better code, and can also now -be used as a standalone cross-compiler, for people who want to build their stuff with -<code>./configure && make</code>. See -docs/STANDALONE-TOOLCHAIN.html for the details. The binaries for GCC 4.4.0 are still provided, -but the 4.2.1 binaries were removed.</li> - - <li>Support for prebuilt static and shared libraries (docs/PREBUILTS.html), module -exports and imports to make sharing and reuse of third-party modules much easier -(docs/IMPORT-MODULE.html explains why).</li> - - <li>A C++ STL implementation (based on STLport) is now provided as a helper module. It -can be used either as a static or shared library (details and usage exemple under -sources/android/stlport/README). <strong>Note:</strong> For now, C++ Exceptions and RTTI are still -not supported.</li> - - <li>Improvements to the <code>cpufeatures</code> helper library to deal with buggy -kernel that incorrectly report they run on an ARMv7 CPU (while the device really is an ARMv6). We -recommend developers that use it to simply rebuild their applications to benefit from it, then -upload to Market.</li> - - <li>Adds support for native activities, which allows you to write completely native - applications.</li> - - <li>Adds an EGL library that lets you create and manage OpenGL ES textures and - services.</li> + <li>Adds support for native activities, which allows you to implement the + Android application lifecycle in native code.</li> <li>Adds native support for the following: <ul> + <li>Input subsystem (such as the keyboard and touch screen)</li> + <li>Access to sensor data (accelerometer, compass, gyroscope, etc).</li> + + <li>Event loop APIs to wait for things such as input and sensor events.</li> + <li>Window and surface subsystem</li> <li>Audio APIs based on the OpenSL ES standard that support playback and recording as well as control over platform audio effects</li> - <li>Event loop APIs to wait for things such as input and sensor events</li> - - <li>Access to assets packaged in the <code>.apk</code></li> - - <li>Access to sensor data (accelerometer, compass, gyroscope, etc.)</li> + <li>Access to assets packaged in an <code>.apk</code> file.</li> + </ul> </li> - <li>New sample applications, <code>native-plasma</code> and - <code>native-activity</code>, to demonstrate how to write a native activity.</li> - - <li>Plus many bugfixes and other small improvements; see docs/CHANGES.html for a more -detailed list of changes.</li> + <li>Includes a new toolchain (based on GCC 4.4.3), which generates better code, and can also now + be used as a standalone cross-compiler, for people who want to build their stuff with + <code>./configure && make</code>. See + docs/STANDALONE-TOOLCHAIN.html for the details. The binaries for GCC 4.4.0 are still provided, + but the 4.2.1 binaries were removed.</li> + + <li>Adds support for prebuilt static and shared libraries (docs/PREBUILTS.html) and module + exports and imports to make sharing and reuse of third-party modules much easier + (docs/IMPORT-MODULE.html explains why).</li> + + <li>Provides a default C++ STL implementation (based on STLport) as a helper module. It can be used either + as a static or shared library (details and usage examples are in sources/android/stlport/README). Prebuilt + binaries for STLport (static or shared) and GNU libstdc++ (static only) are also provided if you choose to + compile against those libraries instead of the default C++ STL implementation. + C++ Exceptions and RTTI are not supported in the default STL implementation. For more information, see + docs/CPLUSPLUS-SUPPORT.HTML.</li> + + <li>Includes improvements to the <code>cpufeatures</code> helper library that improves reporting + of the CPU type (some devices previously reported ARMv7 CPU when the device really was an ARMv6). We + recommend developers that use this library to rebuild their applications then + upload to Market to benefit from the improvements.</li> + + <li>Adds an EGL library that lets you create and manage OpenGL ES textures and + services.</li> + + <li>Adds new sample applications, <code>native-plasma</code> and <code>native-activity</code>, + to demonstrate how to write a native activity.</li> + + <li>Includes many bugfixes and other small improvements; see docs/CHANGES.html for a more + detailed list of changes.</li> </ul> </dd> </dl> @@ -296,14 +294,13 @@ detailed list of changes.</li> <h2 id="installing">Installing the NDK</h2> <p>Installing the NDK on your development computer is straightforward and involves extracting the - NDK from its download package. Unlike previous releases, there is no need to run a host-setup - script.</p> + NDK from its download package.</p> <p>Before you get started make sure that you have downloaded the latest <a href= "{@docRoot}sdk/index.html">Android SDK</a> and upgraded your applications and environment as - needed. The NDK will not work with older versions of the Android SDK. Also, take a moment to - review the <a href="{@docRoot}sdk/ndk/reqs.html">System and Software Requirements</a> for the - NDK, if you haven't already.</p> + needed. The NDK is compatible with older platform versions but not older versions of the SDK tools. + Also, take a moment to review the <a href="{@docRoot}sdk/ndk/reqs.html">System and Software Requirements</a> + for the NDK, if you haven't already.</p> <p>To install the NDK, follow these steps:</p> @@ -318,7 +315,7 @@ detailed list of changes.</li> <code><ndk></code>.</li> </ol> - <p>You are now ready start working with the NDK.</p> + <p>You are now ready to start working with the NDK.</p> <h2 id="gettingstarted">Getting Started with the NDK</h2> @@ -342,8 +339,7 @@ detailed list of changes.</li> <li>Build your native code by running the 'ndk-build' script from your project's directory. It is located in the top-level NDK directory: - <pre class="no-pretty-print"> -cd <project> + <pre class="no-pretty-print">cd <project> <ndk>/ndk-build </pre> @@ -360,220 +356,10 @@ cd <project> <h2 id="samples">Sample Applications</h2> - <p>The NDK includes sample applications that illustrate how to use native code in your Android - applications:</p> - - <ul> - <li><code>hello-jni</code> — a simple application that loads a string from a native - method implemented in a shared library and then displays it in the application UI.</li> - - <li><code>two-libs</code> — a simple application that loads a shared library dynamically - and calls a native method provided by the library. In this case, the method is implemented in a - static library imported by the shared library.</li> - - <li><code>san-angeles</code> — a simple application that renders 3D graphics through the - native OpenGL ES APIs, while managing activity lifecycle with a {@link - android.opengl.GLSurfaceView} object.</li> - - <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES - 2.0 vertex and fragment shaders.</li> - - <li><code>hello-neon</code> — a simple application that shows how to use the - <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics - if supported by the CPU. Specifically, the application implements two versions of a tiny - benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that - support it.</li> - - <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the - pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses - this to generate an old-school "plasma" effect.</li> - - <li><code>native-activity</code> — a simple application that demonstrates how to use the - native-app-glue static library to create a native activity</li> - - <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native - activity.</li> - </ul> - - <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk - and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> - and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> - - <p>You can build the shared libraries for the sample apps by going into - <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. - The generated shared libraries will be located under - <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or - <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> - - <p>Next, build the sample Android applications that use the shared libraries:</p> - - <ul> - <li>If you are developing in Eclipse with ADT, use the New Project Wizard to create a new - Android project for each sample, using the "Import from Existing Source" option and importing - the source from <code><ndk>/apps/<app_name>/project/</code>. Then, set up an AVD, - if necessary, and build/run the application in the emulator. For more information about - creating a new Android project in Eclipse, see <a href= - "{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse</a>.</li> - - <li>If you are developing with Ant, use the <code>android</code> tool to create the build file - for each of the sample projects at <code><ndk>/apps/<app_name>/project/</code>. - Then set up an AVD, if necessary, build your project in the usual way, and run it in the - emulator. For more information, see <a href= - "{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> - </ul> - - <h3 id="hello-jni">Exploring the hello-jni Sample</h3> - - <p>The hello-jni sample is a simple demonstration on how to use JNI from an Android application. - The HelloJni activity receives a string from a simple C function and displays it in a - TextView.</p> - - <p>The main components of the sample include:</p> - - <ul> - <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> - file, a <code>src/</code> and <code>res</code> directories, and a main activity)</li> - - <li>A <code>jni/</code> directory that includes the implemented source file for the native code - as well as the Android.mk file</li> - - <li>A <code>tests/</code> directory that contains unit test code.</li> - </ul> - - <ol> - <li>Create a new project in Eclipse from the existing sample source or use the - <code>android</code> tool to update the project so it generates a build.xml file that you can - use to build the sample. - - <ul> - <li>In Eclipse: - - <ol type="a"> - <li>Click <strong>File > New Android Project...</strong></li> + <p>The NDK includes sample Android applications that illustrate how to use native code in your + Android applications. For more information, see <a href= + "{@docRoot}sdk/ndk/overview.html#samples">Sample Applications</a>.</p> - <li>Select the <strong>Create project from existing source</strong> radio button.</li> - - <li>Select any API level above Android 1.5.</li> - - <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select - the <code><ndk-root>/samples/hello-jni</code> directory.</li> - - <li>Click <strong>Finish</strong>.</li> - </ol> - </li> - - <li>On the command line: - - <ol type="a"> - <li>Change to the <code><ndk-root>/samples/hello-jni</code> directory.</li> - - <li>Run the following command to generate a build.xml file: - <pre class="no-pretty-print"> -android update project -p . -s -</pre> - </li> - </ol> - </li> - </ul> - </li> - - <li>Compile the native code using the <code>ndk-build</code> command. - <pre class="no-pretty-print"> -cd <ndk-root>/samples/hello-jni -<ndk_root>/ndk-build -</pre> - </li> - - <li>Build and install the application as you would a normal Android application. If you are - using Eclipse, run the application to build and install it on a device. If you are using Ant, - run the following commands from the project directory: - <pre class="no-pretty-print"> -ant debug -adb install bin/HelloJni-debug.apk -</pre> - </li> - </ol> - - <p>When you run the application on the device, the string <code>Hello JNI</code> should appear on - your device. You can explore the rest of the samples that are located in the - <code><ndk-root>/samples</code> directory for more examples on how to use the JNI.</p> - - <h3 id="native-activity">Exploring the native-activity Sample Application</h3> - - <p>The native-activity sample provided with the Android NDK demonstrates how to use the - android_native_app_glue static library. This static library makes creating a native activity - easier by providing you with an implementation that handles your callbacks in another thread, so - you do not have to worry about them blocking your main UI thread. The main parts of the sample - are described below:</p> - - <ul> - <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> - file, a <code>src/</code> and <code>res</code> directories). The AndroidManifest.xml declares - that the application is native and specifies the .so file of the native activity. See {@link - android.app.NativeActivity} for the source or see the - <code><ndk_root>/platforms/samples/native-activity/AndroidManifest.xml</code> file.</li> - - <li>A <code>jni/</code> directory contains the native activity, main.c, which uses the - <code>android_native_app_glue.h</code> interface to implement the activity. The Android.mk that - describes the native module to the build system also exists here.</li> - </ul> - - <p>To build this sample application:</p> - - <ol> - <li>Create a new project in Eclipse from the existing sample source or use the - <code>android</code> tool to update the project so it generates a build.xml file that you can - use to build the sample. - - <ul> - <li>In Eclipse: - - <ol type="a"> - <li>Click <strong>File > New Android Project...</strong></li> - - <li>Select the <strong>Create project from existing source</strong> radio button.</li> - - <li>Select any API level above Android 2.3.</li> - - <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select - the <code><ndk-root>/samples/native-activity</code> directory.</li> - - <li>Click <strong>Finish</strong>.</li> - </ol> - </li> - - <li>On the command line: - - <ol type="a"> - <li>Change to the <code><ndk-root>/samples/native-activity</code> directory.</li> - - <li>Run the following command to generate a build.xml file: - <pre class="no-pretty-print"> -android update project -p . -s -</pre> - </li> - </ol> - </li> - </ul> - </li> - - <li>Compile the native code using the <code>ndk-build</code> command. - <pre class="no-pretty-print"> -cd <ndk-root>/platforms/samples/android-9/samples/native-activity -<ndk_root>/ndk-build -</pre> - </li> - - <li>Build and install the application as you would a normal Android application. If you are - using Eclipse, run the application to build and install it on a device. If you are using Ant, - run the following commands in the project directory, then run the application on the device: - <pre class="no-pretty-print"> -ant debug -adb install bin/NativeActivity-debug.apk -</pre> - </li> - </ol> - <h2 id="forum">Discussion Forum and Mailing List</h2> <p>If you have questions about the NDK or would like to read or contribute to discussions about diff --git a/docs/html/sdk/ndk/overview.jd b/docs/html/sdk/ndk/overview.jd index a7ec5d4..f6d148a 100644 --- a/docs/html/sdk/ndk/overview.jd +++ b/docs/html/sdk/ndk/overview.jd @@ -7,10 +7,8 @@ page.title=What is the NDK? <ol> <li><a href="#choosing">When to Develop in Native Code</a></li> - <li> <a href="#contents">Contents of the NDK</a> - <ol> <li><a href="#tools">Development tools</a></li> @@ -19,9 +17,7 @@ page.title=What is the NDK? <li><a href="#samples">Sample applications</a></li> </ol> </li> - <li><a href="#reqs">System and Software Requirements</a></li> - </ol> </div> </div> @@ -102,9 +98,8 @@ page.title=What is the NDK? later.</li> <li> - <p>Write a native activity, which allows you to potentially create an application completely in native - code, because you can implement the lifecycle callbacks natively. The Android SDK provides - the {@link android.app.NativeActivity} class, which is a convenience class that notifies your + <p>Write a native activity, which allows you to implement the lifecycle callbacks in native + code. The Android SDK provides the {@link android.app.NativeActivity} class, which is a convenience class that notifies your native code of any activity lifecycle callbacks (<code>onCreate()</code>, <code>onPause()</code>, <code>onResume()</code>, etc). You can implement the callbacks in your native code to handle these events when they occur. Applications that use native activities must be run on Android @@ -142,6 +137,10 @@ page.title=What is the NDK? <li>libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).</li> <li>A Minimal set of headers for C++ support</li> + + <li>OpenSL ES native audio libraries</li> + + <li>Android native application APIS</li> </ul> <p>The NDK also provides a build system that lets you work efficiently with your sources, without @@ -163,25 +162,18 @@ page.title=What is the NDK? the <code><ndk>/docs/</code> directory. Included are these files:</p> <ul> - <li>INSTALL.HTML — describes how to install the NDK and configure it for your host + <li> + INSTALL.HTML — describes how to install the NDK and configure it for your host system</li> <li>OVERVIEW.HTML — provides an overview of the NDK capabilities and usage</li> - + <li>ANDROID-MK.HTML — describes the use of the Android.mk file, which defines the native sources you want to compile</li> - + <li>APPLICATION-MK.HTML — describes the use of the Application.mk file, which describes - the native sources required by your Android application</li> - - <li>HOWTO.HTML — information about common tasks associated with NDK development.</li> - - <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be - aware of, if you are developing using the NDK.</li> - - <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the - NDK.</li> - + the native sources required by your Android application</li> + <li>CPLUSPLUS-SUPPORT.HTML — describes the C++ support provided in the Android NDK</li> <li>CPU-ARCH-ABIS.HTML — a description of supported CPU architectures and how to target them.</li> @@ -193,6 +185,32 @@ page.title=What is the NDK? instructions.</li> <li>CHANGES.HTML — a complete list of changes to the NDK across all releases.</li> + + <li>DEVELOPMENT.HTML — describes how to modify the NDK and generate release packages for it</li> + + <li>HOWTO.HTML — information about common tasks associated with NDK development</li> + + <li>IMPORT-MODULE.HTML — describes how to share and reuse modules</li> + + <li>LICENSES.HTML — information about the various open source licenses that govern the Android NDK</li> + + <li>NATIVE-ACTIVITY.HTML — describes how to implement native activities</li> + + <li>NDK-BUILD.HTML — describes the usage of the ndk-build script</li> + + <li>NDK-GDB.HTML — describes how to use the native code debugger</li> + + <li>PREBUILTS.HTML — information about how shared and static prebuilt libraries work </li> + + <li>STANDALONE-TOOLCHAIN.HTML — describes how to use Android NDK toolchain as a standalone + compiler (still in beta).</li> + + <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be + aware of, if you are developing using the NDK.</li> + + <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the + NDK.</li> + </ul> <p>Additionally, the package includes detailed information about the "bionic" C library provided @@ -206,9 +224,218 @@ page.title=What is the NDK? <h3 id="samples">Sample applications</h3> - <p>The NDK includes sample Android applications that illustrate how to use native code in your - Android applications. For more information, see <a href= - "{@docRoot}sdk/ndk/installing.html#samples">Sample Applications</a>.</p> +<p>The NDK includes sample applications that illustrate how to use native code in your Android + applications:</p> + + <ul> + <li><code>hello-jni</code> — a simple application that loads a string from a native + method implemented in a shared library and then displays it in the application UI.</li> + + <li><code>two-libs</code> — a simple application that loads a shared library dynamically + and calls a native method provided by the library. In this case, the method is implemented in a + static library imported by the shared library.</li> + + <li><code>san-angeles</code> — a simple application that renders 3D graphics through the + native OpenGL ES APIs, while managing activity lifecycle with a {@link + android.opengl.GLSurfaceView} object.</li> + + <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES + 2.0 vertex and fragment shaders.</li> + + <li><code>hello-neon</code> — a simple application that shows how to use the + <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics + if supported by the CPU. Specifically, the application implements two versions of a tiny + benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that + support it.</li> + + <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the + pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses + this to generate an old-school "plasma" effect.</li> + + <li><code>native-activity</code> — a simple application that demonstrates how to use the + native-app-glue static library to create a native activity</li> + + <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native + activity.</li> + </ul> + + <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk + and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> + and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> + + <p>You can build the shared libraries for the sample apps by going into + <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. + The generated shared libraries will be located under + <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or + <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> + + <p>Next, build the sample Android applications that use the shared libraries:</p> + + <ul> + <li>If you are developing in Eclipse with ADT, use the New Project Wizard to create a new + Android project for each sample, using the "Import from Existing Source" option and importing + the source from <code><ndk>/apps/<app_name>/project/</code>. Then, set up an AVD, + if necessary, and build/run the application in the emulator. For more information about + creating a new Android project in Eclipse, see <a href= + "{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse</a>.</li> + + <li>If you are developing with Ant, use the <code>android</code> tool to create the build file + for each of the sample projects at <code><ndk>/apps/<app_name>/project/</code>. + Then set up an AVD, if necessary, build your project in the usual way, and run it in the + emulator. For more information, see <a href= + "{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> + </ul> + + <h4 id="hello-jni">Exploring the hello-jni Sample</h4> + + <p>The hello-jni sample is a simple demonstration on how to use JNI from an Android application. + The HelloJni activity receives a string from a simple C function and displays it in a + TextView.</p> + + <p>The main components of the sample include:</p> + + <ul> + <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> + file, a <code>src/</code> and <code>res</code> directories, and a main activity)</li> + + <li>A <code>jni/</code> directory that includes the implemented source file for the native code + as well as the Android.mk file</li> + + <li>A <code>tests/</code> directory that contains unit test code.</li> + </ul> + + <ol> + <li>Create a new project in Eclipse from the existing sample source or use the + <code>android</code> tool to update the project so it generates a build.xml file that you can + use to build the sample. + + <ul> + <li>In Eclipse: + + <ol type="a"> + <li>Click <strong>File > New Android Project...</strong></li> + + <li>Select the <strong>Create project from existing source</strong> radio button.</li> + + <li>Select any API level above Android 1.5.</li> + + <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select + the <code><ndk-root>/samples/hello-jni</code> directory.</li> + + <li>Click <strong>Finish</strong>.</li> + </ol> + </li> + + <li>On the command line: + + <ol type="a"> + <li>Change to the <code><ndk-root>/samples/hello-jni</code> directory.</li> + + <li>Run the following command to generate a build.xml file: + <pre class="no-pretty-print">android update project -p . -s</pre> + </li> + </ol> + </li> + </ul> + </li> + + <li>Compile the native code using the <code>ndk-build</code> command. + <pre class="no-pretty-print"> +cd <ndk-root>/samples/hello-jni +<ndk_root>/ndk-build +</pre> + </li> + + <li>Build and install the application as you would a normal Android application. If you are + using Eclipse, run the application to build and install it on a device. If you are using Ant, + run the following commands from the project directory: + <pre class="no-pretty-print"> +ant debug +adb install bin/HelloJni-debug.apk +</pre> + </li> + </ol> + + <p>When you run the application on the device, the string <code>Hello JNI</code> should appear on + your device. You can explore the rest of the samples that are located in the + <code><ndk-root>/samples</code> directory for more examples on how to use the JNI.</p> + + <h4 id="native-activity">Exploring the native-activity Sample Application</h4> + + <p>The native-activity sample provided with the Android NDK demonstrates how to use the + android_native_app_glue static library. This static library makes creating a native activity + easier by providing you with an implementation that handles your callbacks in another thread, so + you do not have to worry about them blocking your main UI thread. The main parts of the sample + are described below:</p> + + <ul> + <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> + file, a <code>src/</code> and <code>res</code> directories). The AndroidManifest.xml declares + that the application is native and specifies the .so file of the native activity. See {@link + android.app.NativeActivity} for the source or see the + <code><ndk_root>/platforms/samples/native-activity/AndroidManifest.xml</code> file.</li> + + <li>A <code>jni/</code> directory contains the native activity, main.c, which uses the + <code>android_native_app_glue.h</code> interface to implement the activity. The Android.mk that + describes the native module to the build system also exists here.</li> + </ul> + + <p>To build this sample application:</p> + + <ol> + <li>Create a new project in Eclipse from the existing sample source or use the + <code>android</code> tool to update the project so it generates a build.xml file that you can + use to build the sample. + + <ul> + <li>In Eclipse: + + <ol type="a"> + <li>Click <strong>File > New Android Project...</strong></li> + + <li>Select the <strong>Create project from existing source</strong> radio button.</li> + + <li>Select any API level above Android 2.3.</li> + + <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select + the <code><ndk-root>/samples/native-activity</code> directory.</li> + + <li>Click <strong>Finish</strong>.</li> + </ol> + </li> + + <li>On the command line: + + <ol type="a"> + <li>Change to the <code><ndk-root>/samples/native-activity</code> directory.</li> + + <li>Run the following command to generate a build.xml file: + <pre class="no-pretty-print"> +android update project -p . -s +</pre> + </li> + </ol> + </li> + </ul> + </li> + + <li>Compile the native code using the <code>ndk-build</code> command. + <pre class="no-pretty-print"> +cd <ndk-root>/platforms/samples/android-9/samples/native-activity +<ndk_root>/ndk-build +</pre> + </li> + + <li>Build and install the application as you would a normal Android application. If you are + using Eclipse, run the application to build and install it on a device. If you are using Ant, + run the following commands in the project directory, then run the application on the device: + <pre class="no-pretty-print"> +ant debug +adb install bin/NativeActivity-debug.apk +</pre> + </li> + </ol> + <h2 id="reqs">System and Software Requirements</h2> @@ -313,7 +540,7 @@ page.title=What is the NDK? to users whose devices are capable of supporting your application. For example: <pre style="margin:1em;"> <manifest> - ... + ... <!-- Declare that the application uses the OpenGL ES 2.0 API and is designed to run only on devices that support OpenGL ES 2.0 or higher. --> <uses-feature android:glEsVersion="0x00020000" /> @@ -331,4 +558,4 @@ page.title=What is the NDK? containing the library can be deployed only to devices running Android 2.2 (API level 8) or higher. To ensure compatibility, make sure that your application declares <code><uses-sdk android:minSdkVersion="8" /></code> attribute value in its manifest.</li> - </ul>
\ No newline at end of file + </ul> |