diff options
Diffstat (limited to 'docs/html/guide/topics')
45 files changed, 49 insertions, 1990 deletions
diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index f917576..a474498 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -1,4 +1,5 @@ page.title=Device Administration +page.tags="devicepolicymanager","policy","security" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/admin/keychain.jd b/docs/html/guide/topics/admin/keychain.jd deleted file mode 100644 index 2ea2408..0000000 --- a/docs/html/guide/topics/admin/keychain.jd +++ /dev/null @@ -1,4 +0,0 @@ -page.title=Text and Input -@jd:body - -<p>Add contnet here</p> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 93d6c6f..cdbf827 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -1,4 +1,5 @@ page.title=App Widgets +page.tags="home" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/connectivity/bluetooth.jd b/docs/html/guide/topics/connectivity/bluetooth.jd index 832b850..1c55d8b 100644 --- a/docs/html/guide/topics/connectivity/bluetooth.jd +++ b/docs/html/guide/topics/connectivity/bluetooth.jd @@ -1,4 +1,5 @@ page.title=Bluetooth +page.tags="wireless","bluetoothadapter","bluetoothdevice" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/connectivity/sip.jd b/docs/html/guide/topics/connectivity/sip.jd index a5f0e2e..526eb83 100644 --- a/docs/html/guide/topics/connectivity/sip.jd +++ b/docs/html/guide/topics/connectivity/sip.jd @@ -1,4 +1,5 @@ page.title=Session Initiation Protocol +page.tags="sipmanager","sipprofile","sipaudiocall","telephony" @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/connectivity/wifip2p.jd b/docs/html/guide/topics/connectivity/wifip2p.jd index efb3ac7..2167a0f 100644 --- a/docs/html/guide/topics/connectivity/wifip2p.jd +++ b/docs/html/guide/topics/connectivity/wifip2p.jd @@ -1,4 +1,5 @@ page.title=Wi-Fi Direct +page.tags="wireless","WifiP2pManager" @jd:body diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd index 2603a06..385c116 100644 --- a/docs/html/guide/topics/data/data-storage.jd +++ b/docs/html/guide/topics/data/data-storage.jd @@ -1,4 +1,5 @@ page.title=Storage Options +page.tags="database","sharedpreferences","sdcard" @jd:body diff --git a/docs/html/guide/topics/data/install-location.jd b/docs/html/guide/topics/data/install-location.jd index 757cd19..2ec0d5a 100644 --- a/docs/html/guide/topics/data/install-location.jd +++ b/docs/html/guide/topics/data/install-location.jd @@ -1,4 +1,5 @@ page.title=App Install Location +page.tags="sdcard","external" @jd:body diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index 5630e63..469eae2 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -1,6 +1,5 @@ page.title=OpenGL -parent.title=Graphics -parent.link=index.html +page.tags="games" @jd:body <div id="qv-wrapper"> @@ -138,7 +137,7 @@ calling OpenGL APIs using the following classes:</p> <li>{@link android.opengl.GLES10}</li> <li>{@link android.opengl.GLES10Ext}</li> <li>{@link android.opengl.GLES11}</li> - <li>{@link android.opengl.GLES10Ext}</li> + <li>{@link android.opengl.GLES11Ext}</li> </ul> </li> <li>{@link javax.microedition.khronos.opengles} - This package provides the standard @@ -289,13 +288,14 @@ matrices to the coordinates of objects that use this shader. private final String vertexShaderCode = // This matrix member variable provides a hook to manipulate - // the coordinates of objects that use this vertex shader + // the coordinates of objects that use this vertex shader. "uniform mat4 uMVPMatrix; \n" + "attribute vec4 vPosition; \n" + "void main(){ \n" + - - // the matrix must be included as part of gl_Position + // The matrix must be included as part of gl_Position + // Note that the uMVPMatrix factor *must be first* in order + // for the matrix multiplication product to be correct. " gl_Position = uMVPMatrix * vPosition; \n" + "} \n"; diff --git a/docs/html/guide/topics/graphics/prop-animation.jd b/docs/html/guide/topics/graphics/prop-animation.jd index 49d7bb8..22bf769 100644 --- a/docs/html/guide/topics/graphics/prop-animation.jd +++ b/docs/html/guide/topics/graphics/prop-animation.jd @@ -1,6 +1,5 @@ page.title=Property Animation -parent.title=Animation -parent.link=animation.html +page.tags="valueanimator","objectanimator","layouttransition","ViewPropertyAnimator" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/graphics/renderscript/graphics.jd b/docs/html/guide/topics/graphics/renderscript/graphics.jd deleted file mode 100644 index 58676ea..0000000 --- a/docs/html/guide/topics/graphics/renderscript/graphics.jd +++ /dev/null @@ -1,994 +0,0 @@ -page.title=Graphics -parent.title=Renderscript -parent.link=index.html - -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li> - <a href="#creating-graphics-rs">Creating a Graphics Renderscript</a> - <ol> - <li><a href="#creating-native">Creating the Renderscript file</a></li> - <li><a href="#creating-entry">Creating the Renderscript entry point class</a></li> - <li><a href="#creating-view">Creating the view class</a></li> - <li><a href="#creating-activity">Creating the activity class</a></li> - </ol> - </li> - <li> - <a href="#drawing">Drawing</a> - <ol> - <li><a href="#drawing-rsg">Simple drawing</a></li> - <li><a href="#drawing-mesh">Drawing with a mesh</a></li> - </ol> - </li> - <li> - <a href="#shaders">Shaders</a> - <ol> - <li><a href="#shader-bindings">Shader bindings</a></li> - <li><a href="#shader-sampler">Defining a sampler</a></li> - </ol> - </li> - <li> - <a href="#fbo">Rendering to a Framebuffer Object</a> - </li> - </ol> - - <h2>Related Samples</h2> - - <ol> - <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/FountainFbo/index.html">FountainFbo</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello -World</a></li> - - <li><a -href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samples</a></li> - </ol> - </div> - </div> - - <p>Renderscript provides a number of graphics APIs for rendering, both at the Android - framework level as well as at the Renderscript runtime level. For instance, the Android framework APIs let you - create meshes and define shaders to customize the graphical rendering pipeline. The native - Renderscript graphics APIs let you draw the actual meshes to render your scene. You need to - be familiar with both APIs to appropriately render graphics on an Android-powered device.</p> - - <h2 id="creating-graphics-rs">Creating a Graphics Renderscript</h2> - - <p>Renderscript applications require various layers of code, so it is useful to create the following - files to help keep your application organized:</p> - - <dl> - <dt>The Renderscript <code>.rs</code> file</dt> - - <dd>This file contains the logic to do the graphics rendering.</dd> - - <dt>The Renderscript entry point <code>.java</code> class</dt> - - <dd>This class allows the view class to interact with the code defined in the <code>.rs</code> - file. This class contains a Renderscript object (instance of - <code>ScriptC_<em>renderscript_file</em></code>), which allows your Android framework code to - call the Renderscript code. In general, this class does much of the setup for Renderscript - such as shader and mesh building and memory allocation and binding. The SDK samples follow the - convention of naming this file ActivityRS.java, - where Activity is the name of your main activity class.</dd> - - <dt>The view <code>.java</code> class</dt> - - <dd>This class extends {@link android.renderscript.RSSurfaceView} or {@link - android.renderscript.RSTextureView} to provide a surface to render on. A {@link - android.renderscript.RSSurfaceView} consumes a whole window, but a {@link - android.renderscript.RSTextureView} allows you to draw Renderscript graphics inside of a - view and add it to a {@link android.view.ViewGroup} alongside - other views. In this class, you create a {@link android.renderscript.RenderScriptGL} context object - with a call to {@link android.renderscript.RSSurfaceView#createRenderScriptGL - RSSurfaceView.createRenderscriptGL()} or {@link android.renderscript.RSTextureView#createRenderScriptGL - RSTextureView.createRenderscriptGL()}. The {@link android.renderscript.RenderScriptGL} context object - contains information about the current rendering state of Renderscript such as the vertex and - fragment shaders. You pass this context object to the Renderscript entry point class, so that - class can modify the rendering context if needed and bind the Renderscript code to the context. Once bound, - the view class can use the Renderscript code to display graphics. - The view class should also implement callbacks for events inherited from {@link - android.view.View}, such as {@link android.view.View#onTouchEvent onTouchEvent()} and {@link - android.view.View#onKeyDown onKeyDown()} if you want to detect these types of user interactions. - The SDK samples follow the convention of naming this file ActivityView.java, - where Activity is the name of your main activity class</dd> - - <dt>The activity <code>.java</code> class</dt> - - <dd>This class is the main activity class and sets your {@link android.renderscript.RSSurfaceView} as the main content - view for this activity or uses the {@link android.renderscript.RSTextureView} alongside other views.</dd> - </dl> - <p>Figure 1 describes how these classes interact with one another in a graphics Renderscript:</p> - - <img src="{@docRoot}images/rs_graphics.png"> - <p class="img-caption"><strong>Figure 1.</strong> Graphics Renderscript overview</p> - - - <p>The following sections describe how to create an application that uses a graphics Renderscript by using - the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Renderscript Fountain - sample</a> that is provided in the SDK as a guide (some code has been modified from its original - form for simplicity).</p> - - <h3 id="creating-native">Creating the Renderscript file</h3> - - <p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> (headers) files in the - <code><project_root>/src/</code> directory. This code contains the logic to render your - graphics and declares all other necessary items such as variables, structs, - and pointers. Every graphics <code>.rs</code> file generally contains the following items:</p> - - <ul> - <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) that declares - the package name of the <code>.java</code> reflection of this Renderscript.</li> - - <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of Renderscript that - you are using (1 is the only value for now).</li> - - <li>A <code>#include "rs_graphics.rsh"</code> declaration.</li> - - <li>A <code>root()</code> function. This is the main worker function for your Renderscript and - calls Renderscript graphics functions to render scenes. This function is called every time a - frame refresh occurs, which is specified as its return value. A <code>0</code> (zero) specified for - the return value says to only render the frame when a property of the scene that you are - rendering changes. A non-zero positive integer specifies the refresh rate of the frame in - milliseconds. - - <p class="note"><strong>Note:</strong> The Renderscript runtime makes its best effort to - refresh the frame at the specified rate. For example, if you are creating a live wallpaper - and set the return value to 20, the Renderscript runtime renders the wallpaper at 50fps if it has just - enough or more resources to do so. It renders as fast as it can if not enough resources - are available.</p> - - <p>For more information on using the Renderscript graphics functions, see the <a href= - "#drawing">Drawing</a> section.</p> - </li> - - <li>An <code>init()</code> function. This allows you to do initialization of your - Renderscript before the <code>root()</code> function runs, such as assigning values to variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript. Creating this function is optional.</li> - - <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in <code>.rsh</code> files if desired)</li> - </ul> - - <p>The following code shows how the <code>fountain.rs</code> file is implemented:</p> - <pre> -#pragma version(1) - -// Tell which java package name the reflected files should belong to -#pragma rs java_package_name(com.example.android.rs.fountain) - -//declare shader binding -#pragma stateFragment(parent) - -// header with graphics APIs, must include explicitly -#include "rs_graphics.rsh" - -static int newPart = 0; - -// the mesh to render -rs_mesh partMesh; - -// the point representing where a particle is rendered -typedef struct __attribute__((packed, aligned(4))) Point { - float2 delta; - float2 position; - uchar4 color; -} Point_t; -Point_t *point; - -// main worker function that renders particles onto the screen -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - - rsgDrawMesh(partMesh); - return 1; -} - -// adds particles to the screen to render -static float4 partColor[10]; -void addParticles(int rate, float x, float y, int index, bool newColor) -{ - if (newColor) { - partColor[index].x = rsRand(0.5f, 1.0f); - partColor[index].y = rsRand(1.0f); - partColor[index].z = rsRand(1.0f); - } - float rMax = ((float)rate) * 0.02f; - int size = rsAllocationGetDimX(rsGetAllocation(point)); - uchar4 c = rsPackColorTo8888(partColor[index]); - - Point_t * np = &point[newPart]; - float2 p = {x, y}; - while (rate--) { - float angle = rsRand(3.14f * 2.f); - float len = rsRand(rMax); - np->delta.x = len * sin(angle); - np->delta.y = len * cos(angle); - np->position = p; - np->color = c; - newPart++; - np++; - if (newPart >= size) { - newPart = 0; - np = &point[newPart]; - } - } -} -</pre> - - <h3 id="creating-entry">Creating the Renderscript entry point class</h3> - - <p>When you create a Renderscript (<code>.rs</code>) file, it is helpful to create a - corresponding Android framework class that is an entry point into the <code>.rs</code> file. - The most important thing this class does is receive a {@link android.renderscript.RenderScriptGL} rendering context - object from the <a href="#creating-view">view class</a> and binds the actual Renderscript - code to the rendering context. This notifies your view class of the code that it needs - to render graphics. - </p> - - <p>In addition, this class should contain all of the things needed to set up Renderscript. - Some important things that you need to do in this class are:</p> - - <ul> - <li>Create a Renderscript object - <code>ScriptC_<em>rs_filename</em></code>. The Renderscript object is attached to the Renderscript bytecode, which is platform-independent and - gets compiled on the device when the Renderscript application runs. The bytecode is referenced - as a raw resource and is passed into the constructor for the Renderscript object. - For example, this is how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample creates the Renderscript object: - <pre> - RenderScriptGL rs; //obtained from the view class - Resources res; //obtained from the view class - ... - ScriptC_fountain mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - </pre> - </li> - <li>Allocate any necessary memory and bind it to your Renderscript code via the Renderscript object.</li> - <li>Build any necessary meshes and bind them to the Renderscript code via the Renderscript object.</li> - <li>Create any necessary programs and bind them to the Renderscript code via the Renderscript object.</li> - </ul> - - <p>The following code shows how the <a href= - "{@docRoot}resources/samples/RenderScript/Fountain/src/com/example/android/rs/fountain/FountainRS.html"> - FountainRS</a> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.content.res.Resources; -import android.renderscript.*; -import android.util.Log; - -public class FountainRS { - public static final int PART_COUNT = 50000; - - public FountainRS() { - } - - /** - * This provides us with the Renderscript context and resources - * that allow us to create the Renderscript object - */ - private Resources mRes; - private RenderScriptGL mRS; - - // Renderscript object - private ScriptC_fountain mScript; - - // Called by the view class to initialize the Renderscript context and renderer - public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - /** - * Create a shader and bind to the Renderscript context - */ - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - rs.bindProgramFragment(pfb.create()); - - /** - * Allocate memory for the particles to render and create the mesh to draw - */ - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - /** - * Create and bind the Renderscript object to the Renderscript context - */ - mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - mScript.set_partMesh(sm); - mScript.bind_point(points); - mRS.bindRootScript(mScript); - } - - boolean holdingColor[] = new boolean[10]; - - /** - * Calls Renderscript functions (invoke_addParticles) - * via the Renderscript object to add particles to render - * based on where a user touches the screen. - */ - public void newTouchPosition(float x, float y, float pressure, int id) { - if (id >= holdingColor.length) { - return; - } - int rate = (int)(pressure * pressure * 500.f); - if (rate > 500) { - rate = 500; - } - if (rate > 0) { - mScript.invoke_addParticles(rate, x, y, id, !holdingColor[id]); - holdingColor[id] = true; - } else { - holdingColor[id] = false; - } - - } -} -</pre> - - - <h3 id="creating-view">Creating the view class</h3> - - - <p>To display graphics, you need a view to render on. Create a class that extends {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. This class - allows you to create a {@link android.renderscript.RenderScriptGL} context object by calling and - pass it to the Rendscript entry point class to bind the two. Once bound, the content is aware - of the code that it needs to use to render graphics with. If your Renderscript code - depends on any type of information that the view is aware of, such as touches from the user, - you can also use this class to relay that information to the Renderscript entry point class. - The following code shows how the <code>FountainView</code> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.renderscript.RSTextureView; -import android.renderscript.RenderScriptGL; -import android.content.Context; -import android.view.MotionEvent; - -public class FountainView extends RSTextureView { - - public FountainView(Context context) { - super(context); - } - // Renderscript context - private RenderScriptGL mRS; - // Renderscript entry point object that calls Renderscript code - private FountainRS mRender; - - /** - * Create Renderscript context and initialize Renderscript entry point - */ - @Override - protected void onAttachedToWindow() { - super.onAttachedToWindow(); - android.util.Log.e("rs", "onAttachedToWindow"); - if (mRS == null) { - RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig(); - mRS = createRenderScriptGL(sc); - mRender = new FountainRS(); - mRender.init(mRS, getResources()); - } - } - - @Override - protected void onDetachedFromWindow() { - super.onDetachedFromWindow(); - android.util.Log.e("rs", "onDetachedFromWindow"); - if (mRS != null) { - mRS = null; - destroyRenderScriptGL(); - } - } - - - /** - * Use callbacks to relay data to Renderscript entry point class - */ - @Override - public boolean onTouchEvent(MotionEvent ev) - { - int act = ev.getActionMasked(); - if (act == ev.ACTION_UP) { - mRender.newTouchPosition(0, 0, 0, ev.getPointerId(0)); - return false; - } else if (act == MotionEvent.ACTION_POINTER_UP) { - // only one pointer going up, we can get the index like this - int pointerIndex = ev.getActionIndex(); - int pointerId = ev.getPointerId(pointerIndex); - mRender.newTouchPosition(0, 0, 0, pointerId); - } - int count = ev.getHistorySize(); - int pcount = ev.getPointerCount(); - - for (int p=0; p < pcount; p++) { - int id = ev.getPointerId(p); - mRender.newTouchPosition(ev.getX(p), - ev.getY(p), - ev.getPressure(p), - id); - - for (int i=0; i < count; i++) { - mRender.newTouchPosition(ev.getHistoricalX(p, i), - ev.getHistoricalY(p, i), - ev.getHistoricalPressure(p, i), - id); - } - } - return true; - } -} -</pre> - - <h3 id="creating-activity">Creating the activity class</h3> - - <p>Applications that use Renderscript still behave like normal Android applications, so you - need an activity class that handles activity lifecycle callback events appropriately. The activity class - also sets your {@link android.renderscript.RSSurfaceView} view class to be the main content view of the - activity or uses your {@link android.renderscript.RSTextureView} - in a {@link android.view.ViewGroup} alongside other views.</p> - - <p>The following code shows how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample declares its activity class:</p> - <pre> -package com.example.android.rs.fountain; - -import android.app.Activity; -import android.os.Bundle; -import android.util.Log; - -public class Fountain extends Activity { - - private static final String LOG_TAG = "libRS_jni"; - private static final boolean DEBUG = false; - private static final boolean LOG_ENABLED = false; - - private FountainView mView; - - @Override - public void onCreate(Bundle icicle) { - super.onCreate(icicle); - - // Create our Preview view and set it as - // the content of our activity - mView = new FountainView(this); - setContentView(mView); - } - - @Override - protected void onResume() { - Log.e("rs", "onResume"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onResume(); - mView.resume(); - } - - @Override - protected void onPause() { - Log.e("rs", "onPause"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onPause(); - mView.pause(); - - } - - static void log(String message) { - if (LOG_ENABLED) { - Log.v(LOG_TAG, message); - } - } -} -</pre> - -<p>Now that you have an idea of what is involved in a Renderscript graphics application, you can -start building your own. It might be easiest to begin with one of the -<a href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript samples</a> as a starting -point if this is your first time using Renderscript.</p> - - <h2 id="drawing">Drawing</h2> - <p>The following sections describe how to use the graphics functions to draw with Renderscript.</p> - - <h3 id="drawing-rsg">Simple drawing</h3> - - <p>The native Renderscript APIs provide a few convenient functions to easily draw a polygon or text to - the screen. You call these in your <code>root()</code> function to have them render to the {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. These functions are - available for simple drawing and should not be used for complex graphics rendering:</p> - - <ul> - <li><code>rsgDrawRect()</code>: Sets up a mesh and draws a rectangle to the screen. It uses the - top left vertex and bottom right vertex of the rectangle to draw.</li> - - <li><code>rsgDrawQuad()</code>: Sets up a mesh and draws a quadrilateral to the screen.</li> - - <li><code>rsgDrawQuadTexCoords()</code>: Sets up a mesh and draws a quadrilateral to the screen - using the provided coordinates of a texture.</li> - - <li><code>rsgDrawText()</code>: Draws specified text to the screen. Use <code>rsgFontColor()</code> - to set the color of the text.</li> - </ul> - - <h3 id="drawing-mesh">Drawing with a mesh</h3> - - <p>When you want to render complex scenes to the screen, instantiate a {@link - android.renderscript.Mesh} and draw it with <code>rsgDrawMesh()</code>. A {@link - android.renderscript.Mesh} is a collection of allocations that represent vertex data (positions, - normals, texture coordinates) and index data that provides information on how to draw triangles - and lines with the provided vertex data. You can build a Mesh in three different ways:</p> - - <ul> - <li>Build the mesh with the {@link android.renderscript.Mesh.TriangleMeshBuilder} class, which - allows you to specify a set of vertices and indices for each triangle that you want to draw.</li> - - <li>Build the mesh using an {@link android.renderscript.Allocation} or a set of {@link - android.renderscript.Allocation}s with the {@link android.renderscript.Mesh.AllocationBuilder} - class. This approach allows you to build a mesh with vertices already stored in memory, which allows you - to specify the vertices in Renderscript or Android framework code.</li> - - <li>Build the mesh with the {@link android.renderscript.Mesh.Builder} class. You should use - this convenience method when you know the data types you want to use to build your mesh, but - don't want to make separate memory allocations like with {@link - android.renderscript.Mesh.AllocationBuilder}. You can specify the types that you want and this - mesh builder automatically creates the memory allocations for you.</li> - </ul> - - <p>To create a mesh using the {@link android.renderscript.Mesh.TriangleMeshBuilder}, you need to - supply it with a set of vertices and the indices for the vertices that comprise the triangle. For - example, the following code specifies three vertices, which are added to an internal array, - indexed in the order they were added. The call to {@link - android.renderscript.Mesh.TriangleMeshBuilder#addTriangle addTriangle()} draws the triangle with - vertex 0, 1, and 2 (the vertices are drawn counter-clockwise).</p> - <pre> -int float2VtxSize = 2; -Mesh.TriangleMeshBuilder triangles = new Mesh.TriangleMeshBuilder(renderscriptGL, -float2VtxSize, Mesh.TriangleMeshBuilder.COLOR); -triangles.addVertex(300.f, 300.f); -triangles.addVertex(150.f, 450.f); -triangles.addVertex(450.f, 450.f); -triangles.addTriangle(0 , 1, 2); -Mesh smP = triangle.create(true); -script.set_mesh(smP); -</pre> - - <p>To draw a mesh using the {@link android.renderscript.Mesh.AllocationBuilder}, you need to - supply it with one or more allocations that contain the vertex data:</p> - <pre> -Allocation vertices; - -... -Mesh.AllocationBuilder triangle = new Mesh.AllocationBuilder(mRS); -smb.addVertexAllocation(vertices.getAllocation()); -smb.addIndexSetType(Mesh.Primitive.TRIANGLE); -Mesh smP = smb.create(); -script.set_mesh(smP); -</pre> - - <p>In your Renderscript code, draw the built mesh to the screen:</p> - <pre> -rs_mesh mesh; -... - -int root(){ -... -rsgDrawMesh(mesh); -... -return 0; //specify a non zero, positive integer to specify the frame refresh. - //0 refreshes the frame only when the mesh changes. -} -</pre> - - <h2 id="shader">Programs</h2> - - <p>You can attach four program objects to the {@link android.renderscript.RenderScriptGL} context - to customize the rendering pipeline. For example, you can create vertex and fragment shaders in - GLSL or build a raster program object that controls culling. The four programs mirror a - traditional graphical rendering pipeline:</p> - - <table> - <tr> - <th>Android Object Type</th> - - <th>Renderscript Native Type</th> - - <th>Description</th> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramVertex}</td> - - <td>rs_program_vertex</td> - - <td> - <p>The Renderscript vertex program, also known as a vertex shader, describes the stage in - the graphics pipeline responsible for manipulating geometric data in a user-defined way. - The object is constructed by providing Renderscript with the following data:</p> - - <ul> - <li>An {@link android.renderscript.Element} describing its varying inputs or attributes</li> - - <li>GLSL shader string that defines the body of the program</li> - - <li>a {@link android.renderscript.Type} that describes the layout of an - Allocation containing constant or uniform inputs</li> - </ul> - - <p>Once the program is created, bind it to the {@link android.renderscript.RenderScriptGL} - graphics context by calling {@link android.renderscript.RenderScriptGL#bindProgramVertex - bindProgramVertex()}. It is then used for all subsequent draw calls until you bind a new - program. If the program has constant inputs, the user needs to bind an allocation - containing those inputs. The allocation's type must match the one provided during creation. - </p> - - <p>The Renderscript runtime then does all the necessary plumbing to send those constants to - the graphics hardware. Varying inputs to the shader, such as position, normal, and texture - coordinates are matched by name between the input {@link android.renderscript.Element} - and the mesh object that is being drawn. The signatures don't have to be exact or in any - strict order. As long as the input name in the shader matches a channel name and size - available on the mesh, the Renderscript runtime handles connecting the two. Unlike OpenGL - there is no need to link the vertex and fragment programs.</p> - - <p>To bind shader constants to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramVertexFixedFunction.Builder} class also - lets you build a simple vertex shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramFragment}</td> - - <td>rs_program_fragment</td> - - <td> - <p>The Renderscript fragment program, also known as a fragment shader, is responsible for - manipulating pixel data in a user-defined way. It's constructed from a GLSL shader string - containing the program body, texture inputs, and a {@link android.renderscript.Type} - object that describes the constants - used by the program. Like the vertex programs, when an {@link android.renderscript.Allocation} - with constant input - values is bound to the shader, its values are sent to the graphics program automatically. - Note that the values inside the {@link android.renderscript.Allocation} are not explicitly tracked. - If they change between two draw calls using the same program object, notify the runtime of that change by - calling <code>rsgAllocationSyncAll()</code>, so it can send the new values to hardware. Communication - between the vertex and fragment programs is handled internally in the GLSL code. For - example, if the fragment program is expecting a varying input called <code>varTex0</code>, the GLSL code - inside the program vertex must provide it.</p> - - <p>To bind shader constructs to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramFragmentFixedFunction.Builder} class also - lets you build a simple fragment shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramStore}</td> - - <td>rs_program_store</td> - - <td>The Renderscript store program contains a set of parameters that control how the graphics - hardware writes to the framebuffer. It could be used to enable and disable depth writes and - testing, setup various blending modes for effects like transparency and define write masks - for color components.</td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramRaster}</td> - - <td>rs_program_raster</td> - - <td>The Renderscript raster program is primarily used to specify whether point sprites are enabled and to - control the culling mode. By default back faces are culled.</td> - </tr> - </table> - - <p>The following example defines a vertex shader in GLSL and binds it to a Renderscript context object:</p> - <pre> - private RenderScriptGL glRenderer; //rendering context - private ScriptField_Point mPoints; //vertices - private ScriptField_VpConsts mVpConsts; //shader constants - - ... - - ProgramVertex.Builder sb = new ProgramVertex.Builder(glRenderer); - String t = "varying vec4 varColor;\n" + - "void main() {\n" + - " vec4 pos = vec4(0.0, 0.0, 0.0, 1.0);\n" + - " pos.xy = ATTRIB_position;\n" + - " gl_Position = UNI_MVP * pos;\n" + - " varColor = vec4(1.0, 1.0, 1.0, 1.0);\n" + - " gl_PointSize = ATTRIB_size;\n" + - "}\n"; - sb.setShader(t); - sb.addConstant(mVpConsts.getType()); - sb.addInput(mPoints.getElement()); - ProgramVertex pvs = sb.create(); - pvs.bindConstants(mVpConsts.getAllocation(), 0); - glRenderer.bindProgramVertex(pvs); -</pre> - - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a shader without writing GLSL.</p> - - <h3 id="shader-bindings">Program bindings</h3> - - <p>You can also declare four pragmas that control default program bindings to the {@link - android.renderscript.RenderScriptGL} context when the script is executing:</p> - - <ul> - <li><code>stateVertex</code></li> - - <li><code>stateFragment</code></li> - - <li><code>stateRaster</code></li> - - <li><code>stateStore</code></li> - </ul> - - <p>The possible values for each pragma are <code>parent</code> or <code>default</code>. Using - <code>default</code> binds the shaders to the graphical context with the system defaults.</p> - - <p>Using <code>parent</code> binds the shaders in the same manner as it is bound in the calling - script. If this is the root script, the parent state is taken from the bind points that are set - by the {@link android.renderscript.RenderScriptGL} bind methods.</p> - - <p>For example, you can define this at the top of your graphics Renderscript code to have - the vertex and store programs inherent the bind properties from their parent scripts:</p> - <pre> -#pragma stateVertex(parent) -#pragma stateStore(parent) -</pre> - - <h3 id="shader-sampler">Defining a sampler</h3> - - <p>A {@link android.renderscript.Sampler} object defines how data is extracted from textures. - Samplers are bound to a {@link android.renderscript.ProgramFragment} alongside the texture - whose sampling they control. These - objects are used to specify such things as edge clamping behavior, whether mip-maps are used, and - the amount of anisotropy required. There might be situations where hardware does not support the - desired behavior of the sampler. In these cases, the Renderscript runtime attempts to provide the - closest possible approximation. For example, the user requested 16x anisotropy, but only 8x was - set because it's the best available on the hardware.</p> - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a sampler and bind it to a - Fragment program.</p> - - - -<h2 id="fbo">Rendering to a Framebuffer Object</h2> - -<p>Framebuffer objects allow you to render offscreen instead of in the default onscreen -framebuffer. This approach might be useful for situations where you need to post-process a texture before -rendering it to the screen, or when you want to composite two scenes in one such as rendering a rear-view -mirror of a car. There are two buffers associated with a framebuffer object: a color buffer -and a depth buffer. The color buffer (required) contains the actual pixel data of the scene -that you are rendering, and the depth buffer (optional) contains the values necessary to figure -out what vertices are drawn depending on their z-values.</p> - -<p>In general, you need to do the following to render to a framebuffer object:</p> - -<ul> - <li>Create {@link android.renderscript.Allocation} objects for the color buffer and - depth buffer (if needed). Specify the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} usage attribute for these - allocations to notify the Renderscript runtime to use these allocations for the framebuffer - object. For the color buffer allocation, you most likely need to declare the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} usage attribute - to use the color buffer as a texture, which is the most common use of the framebuffer object.</li> - - <li>Tell the Renderscript runtime to render to the framebuffer object instead of the default - framebuffer by calling <code>rsgBindColorTarget()</code> and passing it the color buffer - allocation. If applicable, call <code>rsgBindDepthTarget()</code> passing in the depth buffer - allocation as well.</li> - - <li>Render your scene normally with the <code>rsgDraw</code> functions. The scene will be - rendered into the color buffer instead of the default onscreen framebuffer.</li> - - <li>When done, tell the Renderscript runtime stop rendering to the color buffer and back - to the default framebuffer by calling <code>rsgClearAllRenderTargets()</code>.</li> - - <li>Create a fragment shader and bind a the color buffer to it as a texture.</li> - - <li>Render your scene to the default framebuffer. The texture will be used according - to the way you setup your fragment shader.</li> -</ul> - -<p>The following example shows you how to render to a framebuffer object by modifying the -<a href="{@docRoot}guide/resources/renderscript/Fountain/">Fountain</a> Renderscript sample. The end -result is the <a href="{@docRoot}guide/resources/renderscript/FountainFBO/">FountainFBO</a> sample. -The modifications render the exact same scene into a framebuffer object as it does the default -framebuffer. The framebuffer object is then rendered into the default framebuffer in a small -area at the top left corner of the screen.</p> - -<ol> - <li>Modify <code>fountain.rs</code> and add the following global variables. This creates setter - methods when this file is reflected into a <code>.java</code> file, allowing you to allocate - memory in your Android framework code and binding it to the Renderscript runtime. -<pre> -//allocation for color buffer -rs_allocation gColorBuffer; -//fragment shader for rendering without a texture (used for rendering to framebuffer object) -rs_program_fragment gProgramFragment; -//fragment shader for rendering with a texture (used for rendering to default framebuffer) -rs_program_fragment gTextureProgramFragment; -</pre> - </li> - - <li>Modify the root function of <code>fountain.rs</code> to look like the following code. The - modifications are commented: -<pre> -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - //Tell Renderscript runtime to render to the frame buffer object - rsgBindColorTarget(gColorBuffer, 0); - //Begin rendering on a white background - rsgClearColor(1.f, 1.f, 1.f, 1.f); - rsgDrawMesh(partMesh); - - //When done, tell Renderscript runtime to stop rendering to framebuffer object - rsgClearAllRenderTargets(); - - //Bind a new fragment shader that declares the framebuffer object to be used as a texture - rsgBindProgramFragment(gTextureProgramFragment); - - //Bind the framebuffer object to the fragment shader at slot 0 as a texture - rsgBindTexture(gTextureProgramFragment, 0, gColorBuffer); - //Draw a quad using the framebuffer object as the texture - float startX = 10, startY = 10; - float s = 256; - rsgDrawQuadTexCoords(startX, startY, 0, 0, 1, - startX, startY + s, 0, 0, 0, - startX + s, startY + s, 0, 1, 0, - startX + s, startY, 0, 1, 1); - - //Rebind the original fragment shader to render as normal - rsgBindProgramFragment(gProgramFragment); - - //Render the main scene - rsgDrawMesh(partMesh); - - return 1; -} -</pre> - </li> - - <li>In the <code>FountainRS.java</code> file, modify the <code>init()</code> method to look - like the following code. The modifications are commented: - -<pre> -/* Add necessary members */ -private ScriptC_fountainfbo mScript; -private Allocation mColorBuffer; -private ProgramFragment mProgramFragment; -private ProgramFragment mTextureProgramFragment; - -public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - mScript = new ScriptC_fountainfbo(mRS, mRes, R.raw.fountainfbo); - mScript.set_partMesh(sm); - mScript.bind_point(points); - - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - mProgramFragment = pfb.create(); - mScript.set_gProgramFragment(mProgramFragment); - - /* Second fragment shader to use a texture (framebuffer object) to draw with */ - pfb.setTexture(ProgramFragmentFixedFunction.Builder.EnvMode.REPLACE, - ProgramFragmentFixedFunction.Builder.Format.RGBA, 0); - - /* Set the fragment shader in the Renderscript runtime */ - mTextureProgramFragment = pfb.create(); - mScript.set_gTextureProgramFragment(mTextureProgramFragment); - - /* Create the allocation for the color buffer */ - Type.Builder colorBuilder = new Type.Builder(mRS, Element.RGBA_8888(mRS)); - colorBuilder.setX(256).setY(256); - mColorBuffer = Allocation.createTyped(mRS, colorBuilder.create(), - Allocation.USAGE_GRAPHICS_TEXTURE | - Allocation.USAGE_GRAPHICS_RENDER_TARGET); - - /* Set the allocation in the Renderscript runtime */ - mScript.set_gColorBuffer(mColorBuffer); - - mRS.bindRootScript(mScript); -} -</pre> - -<p class="note"><strong>Note:</strong> This sample doesn't use a depth buffer, but the following code -shows you how to declare an example depth buffer if you need to use -one for your application. The depth buffer must have the same dimensions as the color buffer: - -<pre> -Allocation mDepthBuffer; - -... - -Type.Builder b = new Type.Builder(mRS, Element.createPixel(mRS, DataType.UNSIGNED_16, - DataKind.PIXEL_DEPTH)); -b.setX(256).setY(256); -mDepthBuffer = Allocation.createTyped(mRS, b.create(), -Allocation.USAGE_GRAPHICS_RENDER_TARGET); - -</pre> -</p> -</li> - - <li>Run and use the sample. The smaller, white quad on the top-left corner is using the - framebuffer object as a texture, which renders the same scene as the main rendering.</li> -</ol> diff --git a/docs/html/guide/topics/location/strategies.jd b/docs/html/guide/topics/location/strategies.jd index 6cc8f1a..2f7e6c3 100644 --- a/docs/html/guide/topics/location/strategies.jd +++ b/docs/html/guide/topics/location/strategies.jd @@ -1,6 +1,5 @@ page.title=Location Strategies -parent.title=Location and Maps -parent.link=index.html +page.tags="geolocation","maps","mapview" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/media/audio-capture.jd b/docs/html/guide/topics/media/audio-capture.jd index 75d294b..44c618f 100644 --- a/docs/html/guide/topics/media/audio-capture.jd +++ b/docs/html/guide/topics/media/audio-capture.jd @@ -1,6 +1,5 @@ page.title=Audio Capture -parent.title=Multimedia and Camera -parent.link=index.html +page.tags="mediarecorder" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd index 3fe23f8..8ebb349 100644 --- a/docs/html/guide/topics/media/camera.jd +++ b/docs/html/guide/topics/media/camera.jd @@ -1,6 +1,5 @@ page.title=Camera -parent.title=Multimedia and Camera -parent.link=index.html +page.tags="mediarecorder" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/media/mediaplayer.jd b/docs/html/guide/topics/media/mediaplayer.jd index 45a58a7..fb272d2 100644 --- a/docs/html/guide/topics/media/mediaplayer.jd +++ b/docs/html/guide/topics/media/mediaplayer.jd @@ -1,6 +1,5 @@ page.title=Media Playback -parent.title=Multimedia and Camera -parent.link=index.html +page.tags="mediaplayer","soundpool","audiomanager" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/resources/runtime-changes.jd b/docs/html/guide/topics/resources/runtime-changes.jd index 5f39aa5..45a548a 100644 --- a/docs/html/guide/topics/resources/runtime-changes.jd +++ b/docs/html/guide/topics/resources/runtime-changes.jd @@ -1,6 +1,5 @@ page.title=Handling Runtime Changes -parent.title=Application Resources -parent.link=index.html +page.tags="activity","lifecycle" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/search/adding-custom-suggestions.jd b/docs/html/guide/topics/search/adding-custom-suggestions.jd index 02ee084..47ad2fe 100644 --- a/docs/html/guide/topics/search/adding-custom-suggestions.jd +++ b/docs/html/guide/topics/search/adding-custom-suggestions.jd @@ -1,6 +1,5 @@ page.title=Adding Custom Suggestions -parent.title=Search -parent.link=index.html +page.tags="SearchRecentSuggestionsProvider", @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/search/adding-recent-query-suggestions.jd b/docs/html/guide/topics/search/adding-recent-query-suggestions.jd index 2c9a461..c1d59d4 100644 --- a/docs/html/guide/topics/search/adding-recent-query-suggestions.jd +++ b/docs/html/guide/topics/search/adding-recent-query-suggestions.jd @@ -1,6 +1,6 @@ page.title=Adding Recent Query Suggestions -parent.title=Search -parent.link=index.html +page.tags="SearchRecentSuggestions","SearchRecentSuggestionsProvider" + @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd index e24681a..fc722b2 100644 --- a/docs/html/guide/topics/search/search-dialog.jd +++ b/docs/html/guide/topics/search/search-dialog.jd @@ -1,6 +1,5 @@ page.title=Creating a Search Interface -parent.title=Search -parent.link=index.html +page.tags="searchview" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/search/searchable-config.jd b/docs/html/guide/topics/search/searchable-config.jd index fb689f9..fc13c04 100644 --- a/docs/html/guide/topics/search/searchable-config.jd +++ b/docs/html/guide/topics/search/searchable-config.jd @@ -1,6 +1,5 @@ page.title=Searchable Configuration -parent.title=Search -parent.link=index.html + @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/security/index.jd b/docs/html/guide/topics/security/index.jd deleted file mode 100644 index 775fc03..0000000 --- a/docs/html/guide/topics/security/index.jd +++ /dev/null @@ -1,65 +0,0 @@ -page.title=Security and Permissions -page.landing=true -page.landing.intro=Android's security architecture gives the user full control over what resources are accessible to each app, protecting the system itself and all apps in it. Learn how to use system permissions to request access to the resources your app needs and design your app for optimal security. -page.landing.image= - -@jd:body - -<div style="width=100%;padding-left:1em;"> - - <div style="float:left;clear:both;padding-top:20px;"> - <p style="text-transform:uppercase;"><b style="color:#666;font-size:14px;">Blog Articles</b></p> - - <div class="" style="border-top:2px solid #DDD;margin:1em 0;background-color:#F7F7F7;width:336px"> - - <div style="float:left;padding:8px;padding-right:16px;"> - <img src="/assets/images/resource-article.png"> - </div> - - <div class="caption"> - <p style="margin:0;padding:0;font-weight:bold;"><a href="">Accessibility: Are You Serving All Your Users?</a></p> - <p style="margin:0;padding:0">In the upcoming weeks, some of the older Client Login authentication keys will expire. - If you generated the token you’re currently using to authenticate with the C2DM servers before October 2011, it will stop working.</p> - - <p style="margin:0;padding:0;font-weight:bold;"><a href="">Android C2DM — Client Login key expiration</a></p> - <p style="margin:0;padding:0">Accessibility is about making sure that Android users who have limited vision or other physical impairments can use your application just as well</p> - - <p style="margin:0;padding:0;font-weight:bold;"><a href="">A Faster Emulator with Better Hardware Support</a></p> - <p style="margin:0;padding:0">The Android emulator is a key tool for Android developers in building and testing their apps. - As the power and diversity of Android devices has grown quickly, it’s been hard for the emulator keep pace. </p> - - <a href="">More »</a> - </div> - </div> - </div> - - <div style="float:right;padding-top:20px;"> - <p style="text-transform:uppercase;"><b style="color:#666;font-size:14px;">Training</b></p> - - <div class="" style="border-top:2px solid #DDD;bordddser-top:2px solid #FF8800;margin:1em 0;background-color:#F7F7F7;width:336px"> - - <div style="float:left;padding:8px;padding-right:16px;"> - <img src="/assets/images/resource-tutorial.png"> - </div> - - <div class="caption"> - <p style="margin:0;padding:0;font-weight:bold;"><a href="">Managing the Activity Lifecycle</a></p> - <p style="margin:0;padding:0">This class explains important lifecycle callback methods that each Activity - instance receives and how you can use them so your activity does what the user expects and does not consume system - resources when your activity doesn't need them.</p> - - <p style="margin:0;padding:0;font-weight:bold;"><a href="">Supporting Different Devices</a></p> - <p style="margin:0;padding:0">This class teaches you how to use basic platform features that leverage alternative - resources and other features so your app can provide an optimized user experience on a variety of Android-compatible devices, - using a single application package (APK).</p> - - <p style="margin:0;padding:0;font-weight:bold;"><a href="">Sharing Content</a></p> - <p style="margin:0;padding:0">This class covers some common ways you can send and receive content between - applications using Intent APIs and the ActionProvider object.</p> - - <a href="">More »</a> - </div> - </div> -</div> - -</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/security/security.jd b/docs/html/guide/topics/security/security.jd deleted file mode 100644 index 9cdccae..0000000 --- a/docs/html/guide/topics/security/security.jd +++ /dev/null @@ -1,767 +0,0 @@ -page.title=Designing for Security -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>In this document</h2> -<ol> -<li><a href="#Dalvik">Using Davlik Code</a></li> -<li><a href="#Native">Using Native Code</a></li> -<li><a href="#Data">Storing Data</a></li> -<li><a href="#IPC">Using IPC</a></li> -<li><a href="#Permissions">Using Permissions</a></li> -<li><a href="#Networking">Using Networking</a></li> -<li><a href="#DynamicCode">Dynamically Loading Code</a></li> -<li><a href="#Input">Performing Input Validation</a></li> -<li><a href="#UserData">Handling User Data</a></li> -<li><a href="#Crypto">Using Cryptography</a></li> -</ol> -<h2>See also</h2> -<ol> -<li><a href="http://source.android.com/tech/security/index.html">Android -Security Overview</a></li> -<li><a href="{@docRoot}guide/topics/security/security.html">Android Security -And Permissions</a></li> -</ol> -</div></div> -<p>Android was designed so that most developers will be able to build -applications using the default settings and not be confronted with difficult -decisions about security. Android also has a number of security features built -into the operating system that significantly reduce the frequency and impact of -application security issues.</p> - -<p>Some of the security features that help developers build secure applications -include: -<ul> -<li>The Android Application Sandbox that isolates data and code execution on a -per-application basis.</li> -<li>Android application framework with robust implementations of common -security functionality such as cryptography, permissions, and secure IPC.</li> -<li>Technologies like ASLR, NX, ProPolice, safe_iop, OpenBSD dlmalloc, OpenBSD -calloc, and Linux mmap_min_addr to mitigate risks associated with common memory -management errors</li> -<li>An encrypted filesystem that can be enabled to protect data on lost or -stolen devices.</li> -</ul></p> - -<p>Nevertheless, it is important for developers to be familiar with Android -security best practices to make sure they take advantage of these capabilities -and to reduce the likelihood of inadvertently introducing security issues that -can affect their applications.</p> - -<p>This document is organized around common APIs and development techniques -that can have security implications for your application and its users. As -these best practices are constantly evolving, we recommend you check back -occasionally throughout your application development process.</p> - -<a name="Dalvik"></a> -<h2>Using Dalvik Code</h2> -<p>Writing secure code that runs in virtual machines is a well-studied topic -and many of the issues are not specific to Android. Rather than attempting to -rehash these topics, we’d recommend that you familiarize yourself with the -existing literature. Two of the more popular resources are: -<ul> -<li><a href="http://www.securingjava.com/toc.html"> -http://www.securingjava.com/toc.html</a></li> -<li><a -href="https://www.owasp.org/index.php/Java_Security_Resources"> -https://www.owasp.org/index.php/Java_Security_Resources</a></li> -</ul></p> - -<p>This document is focused on the areas which are Android specific and/or -different from other environments. For developers experienced with VM -programming in other environments, there are two broad issues that may be -different about writing apps for Android: -<ul> -<li>Some virtual machines, such as the JVM or .net runtime, act as a security -boundary, isolating code from the underlying operating system capabilities. On -Android, the Dalvik VM is not a security boundary -- the application sandbox is -implemented at the OS level, so Dalvik can interoperate with native code in the -same application without any security constraints.</li> -<li>Given the limited storage on mobile devices, it’s common for developers -to want to build modular applications and use dynamic class loading. When -doing this consider both the source where you retrieve your application logic -and where you store it locally. Do not use dynamic class loading from sources -that are not verified, such as unsecured network sources or external storage, -since that code can be modified to include malicious behavior.</li> -</ul></p> - -<a name="Native"></a> -<h2>Using Native Code</h2> - -<p>In general, we encourage developers to use the Android SDK for most -application development, rather than using native code. Applications built -with native code are more complex, less portable, and more like to include -common memory corruption errors such as buffer overflows.</p> - -<p>Android is built using the Linux kernel and being familiar with Linux -development security best practices is especially useful if you are going to -use native code. This document is too short to discuss all of those best -practices, but one of the most popular resources is “Secure Programming for -Linux and Unix HOWTO”, available at <a -href="http://www.dwheeler.com/secure-programs"> -http://www.dwheeler.com/secure-programs</a>.</p> - -<p>An important difference between Android and most Linux environments is the -Application Sandbox. On Android, all applications run in the Application -Sandbox, including those written with native code. At the most basic level, a -good way to think about it for developers familiar with Linux is to know that -every application is given a unique UID with very limited permissions. This is -discussed in more detail in the <a -href="http://source.android.com/tech/security/index.html">Android Security -Overview</a> and you should be familiar with application permissions even if -you are using native code.</p> - -<a name="Data"></a> -<h2>Storing Data</h2> - -<h3>Using internal files</h3> - -<p>By default, files created on <a -href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal -storage</a> are only accessible to the application that created the file. This -protection is implemented by Android and is sufficient for most -applications.</p> - -<p>Use of <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> -world writable</a> or <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE">world -readable</a> files for IPC is discouraged because it does not provide -the ability to limit data access to particular applications, nor does it -provide any control on data format. As an alternative, you might consider using -a ContentProvider which provides read and write permissions, and can make -dynamic permission grants on a case-by-case basis.</p> - -<p>To provide additional protection for sensitive data, some applications -choose to encrypt local files using a key that is not accessible to the -application. (For example, a key can be placed in a {@link java.security.KeyStore} and -protected with a user password that is not stored on the device). While this -does not protect data from a root compromise that can monitor the user -inputting the password, it can provide protection for a lost device without <a -href="http://source.android.com/tech/encryption/index.html">file system -encryption</a>.</p> - -<h3>Using external storage</h3> - -<p>Files created on <a -href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">external -storage</a>, such as SD Cards, are globally readable and writable. Since -external storage can be removed by the user and also modified by any -application, applications should not store sensitive information using -external storage.</p> - -<p>As with data from any untrusted source, applications should perform input -validation when handling data from external storage (see Input Validation -section). We strongly recommend that applications not store executables or -class files on external storage prior to dynamic loading. If an application -does retrieve executable files from external storage they should be signed and -cryptographically verified prior to dynamic loading.</p> - -<h3>Using content providers</h3> - -<p>ContentProviders provide a structured storage mechanism that can be limited -to your own application, or exported to allow access by other applications. By -default, a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code> is -<a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">exported -</a> for use by other applications. If you do not intend to provide other -applications with access to your<code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>, mark them as <code><a -href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> -android:exported=false</a></code> in the application manifest.</p> - -<p>When creating a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html">ContentProvider -</a></code> that will be exported for use by other applications, you can specify -a single -<a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission -</a> for reading and writing, or distinct permissions for reading and writing -within the manifest. We recommend that you limit your permissions to those -required to accomplish the task at hand. Keep in mind that it’s usually -easier to add permissions later to expose new functionality than it is to take -them away and break existing users.</p> - -<p>If you are using a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code> for sharing data between applications built by the -same developer, it is preferable to use -<a href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -level permissions</a>. Signature permissions do not require user confirmation, -so they provide a better user experience and more controlled access to the -<code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>.</p> - -<p>ContentProviders can also provide more granular access by declaring the <a -href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> -grantUriPermissions</a> element and using the <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION">FLAG_GRANT_READ_URI_PERMISSION</a></code> -and <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> -flags in the Intent object -that activates the component. The scope of these permissions can be further -limited by the <code><a -href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> -grant-uri-permission element</a></code>.</p> - -<p>When accessing a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>, use parameterized query methods such as <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lang.String)">query()</a></code>, <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#update(android.net.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[])">update()</a></code>, and <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.net.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid -potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL -Injection</a> from untrusted data. Note that using parameterized methods is not -sufficient if the <code>selection</code> is built by concatenating user data -prior to submitting it to the method.</p> - -<p>Do not have a false sense of security about the write permission. Consider -that the write permission allows SQL statements which make it possible for some -data to be confirmed using creative <code>WHERE</code> clauses and parsing the -results. For example, an attacker might probe for presence of a specific phone -number in a call-log by modifying a row only if that phone number already -exists. If the content provider data has predictable structure, the write -permission may be equivalent to providing both reading and writing.</p> - -<a name="IPC"></a> -<h2>Using Interprocess Communication (IPC)</h2> - -<p>Some Android applications attempt to implement IPC using traditional Linux -techniques such as network sockets and shared files. We strongly encourage the -use of Android system functionality for IPC such as Intents, Binders, Services, -and Receivers. The Android IPC mechanisms allow you to verify the identity of -the application connecting to your IPC and set security policy for each IPC -mechanism.</p> - -<p>Many of the security elements are shared across IPC mechanisms. <a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -Broadcast Receivers</a>, <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> -Activities</a>, and <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> -Services</a> are all declared in the application manifest. If your IPC mechanism is -not intended for use by other applications, set the <a -href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> -property to false. This is useful for applications that consist of multiple processes -within the same UID, or if you decide late in development that you do not -actually want to expose functionality as IPC but you don’t want to rewrite -the code.</p> - -<p>If your IPC is intended to be accessible to other applications, you can -apply a security policy by using the <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestPermission"> -Permission</a> tag. If IPC is between applications built by the same developer, -it is preferable to use <a -href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -level permissions</a>. Signature permissions do not require user confirmation, -so they provide a better user experience and more controlled access to the IPC -mechanism.</p> - -<p>One area that can introduce confusion is the use of intent filters. Note -that Intent filters should not be considered a security feature -- components -can be invoked directly and may not have data that would conform to the intent -filter. You should perform input validation within your intent receiver to -confirm that it is properly formatted for the invoked receiver, service, or -activity.</p> - -<h3>Using intents</h3> - -<p>Intents are the preferred mechanism for asynchronous IPC in Android. -Depending on your application requirements, you might use <code><a -href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.content.Intent)">sendBroadcast()</a></code>, -<code><a -href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(android.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, -or direct an intent to a specific application component.</p> - -<p>Note that ordered broadcasts can be “consumed” by a recipient, so they -may not be delivered to all applications. If you are sending an Intent where -delivery to a specific receiver is required, the intent must be delivered -directly to the receiver.</p> - -<p>Senders of an intent can verify that the recipient has a permission -specifying a non-Null Permission upon sending. Only applications with that -Permission will receive the intent. If data within a broadcast intent may be -sensitive, you should consider applying a permission to make sure that -malicious applications cannot register to receive those messages without -appropriate permissions. In those circumstances, you may also consider -invoking the receiver directly, rather than raising a broadcast.</p> - -<h3>Using binder and AIDL interfaces</h3> - -<p><a href="{@docRoot}reference/android/os/Binder.html">Binders</a> are the -preferred mechanism for RPC-style IPC in Android. They provide a well-defined -interface that enables mutual authentication of the endpoints, if required.</p> - -<p>We strongly encourage designing interfaces in a manner that does not require -interface specific permission checks. Binders are not declared within the -application manifest, and therefore you cannot apply declarative permissions -directly to a Binder. Binders generally inherit permissions declared in the -application manifest for the Service or Activity within which they are -implemented. If you are creating an interface that requires authentication -and/or access controls on a specific binder interface, those controls must be -explicitly added as code in the interface.</p> - -<p>If providing an interface that does require access controls, use <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> -to verify whether the -caller of the Binder has a required permission. This is especially important -before accessing a Service on behalf of the caller, as the identify of your -application is passed to other interfaces. If invoking an interface provided -by a Service, the <code><a -href="{@docRoot}reference/android/content/Context.html#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> - invocation may fail if you do not have permission to access the given Service. - If calling an interface provided locally by your own application, it may be -useful to use the <code><a -href="{@docRoot}reference/android/os/Binder.html#clearCallingIdentity()"> -clearCallingIdentity()</a></code> to satisfy internal security checks.</p> - -<h3>Using broadcast receivers</h3> - -<p>Broadcast receivers are used to handle asynchronous requests initiated via -an intent.</p> - -<p>By default, receivers are exported and can be invoked by any other -application. If your <code><a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -BroadcastReceivers</a></code> is intended for use by other applications, you -may want to apply security permissions to receivers using the <code><a -href="{@docRoot}guide/topics/manifest/receiver-element.html"> -<receiver></a></code> element within the application manifest. This will -prevent applications without appropriate permissions from sending an intent to -the <code><a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -BroadcastReceivers</a></code>.</p> - -<h3>Using Services</h3> - -<p>Services are often used to supply functionality for other applications to -use. Each service class must have a corresponding <service> declaration in its -package's AndroidManifest.xml.</p> - -<p>By default, Services are exported and can be invoked by any other -application. Services can be protected using the <a -href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">{@code android:permission}</a> -attribute -within the manifest’s <code><a -href="{@docRoot}guide/topics/manifest/service-element.html"> -<service></a></code> tag. By doing so, other applications will need to declare -a corresponding <code><a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> -</code> element in their own manifest to be -able to start, stop, or bind to the service.</p> - -<p>A Service can protect individual IPC calls into it with permissions, by -calling <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> -before executing -the implementation of that call. We generally recommend using the -declarative permissions in the manifest, since those are less prone to -oversight.</p> - -<h3>Using Activities</h3> - -<p>Activities are most often used for providing the core user-facing -functionality of an application. By default, Activities are exported and -invokable by other applications only if they have an intent filter or binder -declared. In general, we recommend that you specifically declare a Receiver or -Service to handle IPC, since this modular approach reduces the risk of exposing -functionality that is not intended for use by other applications.</p> - -<p>If you do expose an Activity for purposes of IPC, the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">android:permission</a></code> -attribute in the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"> -<activity></a></code> declaration in the application manifest can be used to -restrict access to only those applications which have the stated -permissions.</p> - -<a name="Permissions"></a> -<h2>Using Permissions</h2> - -<h3>Requesting Permissions</h3> - -<p>We recommend minimizing the number of permissions requested by an -application. Not having access to sensitive permissions reduces the risk of -inadvertently misusing those permissions, can improve user adoption, and makes -applications less attractive targets for attackers.</p> - -<p>If it is possible to design your application in a way that does not require -a permission, that is preferable. For example, rather than requesting access -to device information to create an identifier, create a <a -href="{@docRoot}reference/java/util/UUID.html">GUID</a> for your application. -(This specific example is also discussed in Handling User Data) Or, rather than -using external storage, store data in your application directory.</p> - -<p>If a permission is not required, do not request it. This sounds simple, but -there has been quite a bit of research into the frequency of over-requesting -permissions. If you’re interested in the subject you might start with this -research paper published by U.C. Berkeley: <a -href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf"> -http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf</a></p> - -<p>In addition to requesting permissions, your application can use <a -href="{@docRoot}guide/topics/manifest/permission-element.html">permissions</a> -to protect IPC that is security sensitive and will be exposed to other -applications -- such as a <code><a -href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>. In general, we recommend using access controls -other than user confirmed permissions where possible since permissions can -be confusing for users. For example, consider using the <a -href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -protection level</a> on permissions for IPC communication between applications -provided by a single developer.</p> - -<p>Do not cause permission re-delegation. This occurs when an app exposes data -over IPC that is only available because it has a specific permission, but does -not require that permission of any clients of it’s IPC interface. More -details on the potential impacts, and frequency of this type of problem is -provided in this research paper published at USENIX: <a -href="http://www.cs.berkeley.edu/~afelt/felt_usenixsec2011.pdf">http://www.cs.be -rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> - -<h3>Creating Permissions</h3> - -<p>Generally, you should strive to create as few permissions as possible while -satisfying your security requirements. Creating a new permission is relatively -uncommon for most applications, since <a -href="{@docRoot}reference/android/Manifest.permission.html">system-defined -permissions</a> cover many situations. Where appropriate, -perform access checks using existing permissions.</p> - -<p>If you must create a new permission, consider whether you can accomplish -your task with a Signature permission. Signature permissions are transparent -to the user and only allow access by applications signed by the same developer -as application performing the permission check. If you create a Dangerous -permission, then the user needs to decide whether to install the application. -This can be confusing for other developers, as well as for users.</p> - -<p>If you create a Dangerous permission, there are a number of complexities -that you need to consider. -<ul> -<li>The permission must have a string that concisely expresses to a user the -security decision they will be required to make.</li> -<li>The permission string must be localized to many different languages.</li> -<li>Uses may choose not to install an application because a permission is -confusing or perceived as risky.</li> -<li>Applications may request the permission when the creator of the permission -has not been installed.</li> -</ul></p> - -<p>Each of these poses a significant non-technical challenge for an application -developer, which is why we discourage the use of Dangerous permission.</p> - -<a name="Networking"></a> -<h2>Using Networking</h2> - -<h3>Using IP Networking</h3> - -<p>Networking on Android is not significantly different from Linux -environments. The key consideration is making sure that appropriate protocols -are used for sensitive data, such as <a -href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html">HTTPS</a> for -web traffic. We prefer use of HTTPS over HTTP anywhere that HTTPS is -supported on the server, since mobile devices frequently connect on networks -that are not secured, such as public WiFi hotspots.</p> - -<p>Authenticated, encrypted socket-level communication can be easily -implemented using the <code><a -href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code> -class. Given the frequency with which Android devices connect to unsecured -wireless networks using WiFi, the use of secure networking is strongly -encouraged for all applications.</p> - -<p>We have seen some applications use <a -href="http://en.wikipedia.org/wiki/Localhost">localhost</a> network ports for -handling sensitive IPC. We discourage this approach since these interfaces are -accessible by other applications on the device. Instead, use an Android IPC -mechanism where authentication is possible such as a Service and Binder. (Even -worse than using loopback is to bind to INADDR_ANY since then your application -may receive requests from anywhere. We’ve seen that, too.)</p> - -<p>Also, one common issue that warrants repeating is to make sure that you do -not trust data downloaded from HTTP or other insecure protocols. This includes -validation of input in <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> and -any responses to intents issued against HTTP.</p> - -<h3>Using Telephony Networking</h3> - -<p>SMS is the telephony protocol most frequently used by Android developers. -Developers should keep in mind that this protocol was primarily designed for -user-to-user communication and is not well-suited for some application -purposes. Due to the limitations of SMS, we strongly recommend the use of <a -href="http://code.google.com/android/c2dm/">C2DM</a> and IP networking for -sending data messages to devices.</p> - -<p>Many developers do not realize that SMS is not encrypted or strongly -authenticated on the network or on the device. In particular, any SMS receiver -should expect that a malicious user may have sent the SMS to your application --- do not rely on unauthenticated SMS data to perform sensitive commands. -Also, you should be aware that SMS may be subject to spoofing and/or -interception on the network. On the Android-powered device itself, SMS -messages are transmitted as Broadcast intents, so they may be read or captured -by other applications that have the READ_SMS permission.</p> - -<a name="DynamicCode"></a> -<h2>Dynamically Loading Code</h2> - -<p>We strongly discourage loading code from outside of the application APK. -Doing so significantly increases the likelihood of application compromise due -to code injection or code tampering. It also adds complexity around version -management and application testing. Finally, it can make it impossible to -verify the behavior of an application, so it may be prohibited in some -environments.</p> - -<p>If your application does dynamically load code, the most important thing to -keep in mind about dynamically loaded code is that it runs with the same -security permissions as the application APK. The user made a decision to -install your application based on your identity, and they are expecting that -you provide any code run within the application, including code that is -dynamically loaded.</p> - -<p>The major security risk associated with dynamically loading code is that the -code needs to come from a verifiable source. If the modules are included -directly within your APK, then they cannot be modified by other applications. -This is true whether the code is a native library or a class being loaded using -<a href="{@docRoot}reference/dalvik/system/DexClassLoader.html"> -<code>DexClassLoader</code></a>. We have seen many instances of applications -attempting to load code from insecure locations, such as downloaded from the -network over unencrypted protocols or from world writable locations such as -external storage. These locations could allow someone on the network to modify -the content in transit, or another application on a users device to modify the -content, respectively.</p> - - -<h3>Using WebView</h3> - -<p>Since WebView consumes web content that can include HTML and JavaScript, -improper use can introduce common web security issues such as <a -href="http://en.wikipedia.org/wiki/Cross_site_scripting">cross-site-scripting</a -> (JavaScript injection). Android includes a number of mechanisms to reduce -the scope of these potential issues by limiting the capability of WebView to -the minimum functionality required by your application.</p> - -<p>If your application does not directly use JavaScript within a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do -not call -<a href="{@docRoot}reference/android/webkit/WebSettings.html#setJavaScriptEnabled(boolean)"> -<code>setJavaScriptEnabled()</code></a>. We have seen this method invoked -in sample code that might be repurposed in production application -- so -remove it if necessary. By default, <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does -not execute JavaScript so cross-site-scripting is not possible.</p> - -<p>Use <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with -particular care because it allows JavaScript to invoke operations that are -normally reserved for Android applications. Only expose <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to -sources from which all input is trustworthy. If untrusted input is allowed, -untrusted JavaScript may be able to invoke Android methods. In general, we -recommend only exposing <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to -JavaScript that is contained within your application APK.</p> - -<p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if -you are connecting only to a single website that you trust or control, HTTP is -subject to <a -href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks -and interception of data. Sensitive capabilities using <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should -not ever be exposed to unverified script downloaded over HTTP. Note that even -with the use of HTTPS, -<code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> -increases the attack surface of your application to include the server -infrastructure and all CAs trusted by the Android-powered device.</p> - -<p>If your application accesses sensitive data with a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, you -may want to use the <code><a -href="{@docRoot}reference/android/webkit/WebView.html#clearCache(boolean)"> -clearCache()</a></code> method to delete any files stored locally. Server side -headers like no-cache can also be used to indicate that an application should -not cache particular content.</p> - -<a name="Input"></a> -<h2>Performing Input Validation</h2> - -<p>Insufficient input validation is one of the most common security problems -affecting applications, regardless of what platform they run on. Android does -have platform-level countermeasures that reduce the exposure of applications to -input validation issues, you should use those features where possible. Also -note that selection of type-safe languages tends to reduce the likelihood of -input validation issues. We strongly recommend building your applications with -the Android SDK.</p> - -<p>If you are using native code, then any data read from files, received over -the network, or received from an IPC has the potential to introduce a security -issue. The most common problems are <a -href="http://en.wikipedia.org/wiki/Buffer_overflow">buffer overflows</a>, <a -href="http://en.wikipedia.org/wiki/Double_free#Use_after_free">use after -free</a>, and <a -href="http://en.wikipedia.org/wiki/Off-by-one_error">off-by-one errors</a>. -Android provides a number of technologies like ASLR and DEP that reduce the -exploitability of these errors, but they do not solve the underlying problem. -These can be prevented by careful handling of pointers and managing of -buffers.</p> - -<p>Dynamic, string based languages such as JavaScript and SQL are also subject -to input validation problems due to escape characters and <a -href="http://en.wikipedia.org/wiki/Code_injection">script injection</a>.</p> - -<p>If you are using data within queries that are submitted to SQL Database or a -Content Provider, SQL Injection may be an issue. The best defense is to use -parameterized queries, as is discussed in the ContentProviders section. -Limiting permissions to read-only or write-only can also reduce the potential -for harm related to SQL Injection.</p> - -<p>If you are using <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, then -you must consider the possibility of XSS. If your application does not -directly use JavaScript within a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do -not call setJavaScriptEnabled() and XSS is no longer possible. If you must -enable JavaScript then the WebView section provides other security best -practices.</p> - -<p>If you cannot use the security features above, we strongly recommend the use -of well-structured data formats and verifying that the data conforms to the -expected format. While blacklisting of characters or character-replacement can -be an effective strategy, these techniques are error-prone in practice and -should be avoided when possible.</p> - -<a name="UserData"></a> -<h2>Handling User Data</h2> - -<p>In general, the best approach is to minimize use of APIs that access -sensitive or personal user data. If you have access to data and can avoid -storing or transmitting the information, do not store or transmit the data. -Finally, consider if there is a way that your application logic can be -implemented using a hash or non-reversible form of the data. For example, your -application might use the hash of an an email address as a primary key, to -avoid transmitting or storing the email address. This reduces the chances of -inadvertently exposing data, and it also reduces the chance of attackers -attempting to exploit your application.</p> - -<p>If your application accesses personal information such as passwords or -usernames, keep in mind that some jurisdictions may require you to provide a -privacy policy explaining your use and storage of that data. So following the -security best practice of minimizing access to user data may also simplify -compliance.</p> - -<p>You should also consider whether your application might be inadvertently -exposing personal information to other parties such as third-party components -for advertising or third-party services used by your application. If you don't -know why a component or service requires a personal information, don’t -provide it. In general, reducing the access to personal information by your -application will reduce the potential for problems in this area.</p> - -<p>If access to sensitive data is required, evaluate whether that information -must be transmitted to a server, or whether the operation can be performed on -the client. Consider running any code using sensitive data on the client to -avoid transmitting user data.</p> - -<p>Also, make sure that you do not inadvertently expose user data to other -application on the device through overly permissive IPC, world writable files, -or network sockets. This is a special case of permission redelegation, -discussed in the Requesting Permissions section.</p> - -<p>If a GUID is required, create a large, unique number and store it. Do not -use phone identifiers such as the phone number or IMEI which may be associated -with personal information. This topic is discussed in more detail in the <a -href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">Android Developer Blog</a>.</p> - -<p>Application developers should be careful writing to on-device logs. -In Android, logs are a shared resource, and are available -to an application with the -<a href="{@docRoot}reference/android/Manifest.permission.html#READ_LOGS"> -<code>READ_LOGS</code></a> permission. Even though the phone log data -is temporary and erased on reboot, inappropriate logging of user information -could inadvertently leak user data to other applications.</p> - - -<h3>Handling Credentials</h3> - -<p>In general, we recommend minimizing the frequency of asking for user -credentials -- to make phishing attacks more conspicuous, and less likely to be -successful. Instead use an authorization token and refresh it.</p> - -<p>Where possible, username and password should not be stored on the device. -Instead, perform initial authentication using the username and password -supplied by the user, and then use a short-lived, service-specific -authorization token.</p> - -<p>Services that will be accessible to multiple applications should be accessed -using <code> -<a href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code>. If possible, use the <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> class to invoke a cloud-based service and do not store -passwords on the device.</p> - -<p>After using <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> to retrieve an Account, check the <code><a -href="{@docRoot}reference/android/accounts/Account.html#CREATOR">CREATOR</a> -</code> before passing in any credentials, so that you do not inadvertently pass -credentials to the wrong application.</p> - -<p>If credentials are to be used only by applications that you create, then you -can verify the application which accesses the <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> using <code><a -href="{@docRoot}reference/android/content/pm/PackageManager.html#checkSignatures(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. -Alternatively, if only one application will use the credential, you might use a -{@link java.security.KeyStore} for -storage.</p> - -<a name="Crypto"></a> -<h2>Using Cryptography</h2> - -<p>In addition to providing data isolation, supporting full-filesystem -encryption, and providing secure communications channels Android provides a -wide array of algorithms for protecting data using cryptography.</p> - -<p>In general, try to use the highest level of pre-existing framework -implementation that can support your use case. If you need to securely -retrieve a file from a known location, a simple HTTPS URI may be adequate and -require no knowledge of cryptography on your part. If you need a secure -tunnel, consider using -<a href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html"> -<code>HttpsURLConnection</code></a> or <code><a -href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code>, -rather than writing your own protocol.</p> - -<p>If you do find yourself needing to implement your own protocol, we strongly -recommend that you not implement your own cryptographic algorithms. Use -existing cryptographic algorithms such as those in the implementation of AES or -RSA provided in the <code><a -href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> - -<p>Use a secure random number generator ( -<a href="{@docRoot}reference/java/security/SecureRandom.html"> -<code>SecureRandom</code></a>) to initialize any cryptographic keys (<a -href="{@docRoot}reference/javax/crypto/KeyGenerator.html"> -<code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random -number generator significantly weakens the strength of the algorithm, and may -allow offline attacks.</p> - -<p>If you need to store a key for repeated use, use a mechanism like {@link java.security.KeyStore} that -provides a mechanism for long term storage and retrieval of cryptographic -keys.</p> - -<h2>Conclusion</h2> - -<p>Android provides developers with the ability to design applications with a -broad range of security requirements. These best practices will help you make -sure that your application takes advantage of the security benefits provided by -the platform.</p> - -<p>You can receive more information on these topics and discuss security best -practices with other developers in the <a -href="http://groups.google.com/group/android-security-discuss">Android Security -Discuss</a> Google Group</p> diff --git a/docs/html/guide/topics/sensors/sensors_motion.jd b/docs/html/guide/topics/sensors/sensors_motion.jd index b6c3cb4..289c639 100644 --- a/docs/html/guide/topics/sensors/sensors_motion.jd +++ b/docs/html/guide/topics/sensors/sensors_motion.jd @@ -1,6 +1,5 @@ page.title=Motion Sensors -parent.title=Sensors -parent.link=index.html +page.tags="sensorevent","accelerometer","gyroscope","gravity","rotation" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/sensors/sensors_position.jd b/docs/html/guide/topics/sensors/sensors_position.jd index 869109b..55b282b 100644 --- a/docs/html/guide/topics/sensors/sensors_position.jd +++ b/docs/html/guide/topics/sensors/sensors_position.jd @@ -1,6 +1,5 @@ page.title=Position Sensors -parent.title=Sensors -parent.link=index.html +page.tags="sensorevent","orientation","proximity" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/text/copy-paste.jd b/docs/html/guide/topics/text/copy-paste.jd index 6c86f47..b34f0fa 100644 --- a/docs/html/guide/topics/text/copy-paste.jd +++ b/docs/html/guide/topics/text/copy-paste.jd @@ -1,4 +1,5 @@ page.title=Copy and Paste +page.tags="clipboardmanager","clipdata","input" @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/text/creating-input-method.jd b/docs/html/guide/topics/text/creating-input-method.jd index 7086824..7254594 100644 --- a/docs/html/guide/topics/text/creating-input-method.jd +++ b/docs/html/guide/topics/text/creating-input-method.jd @@ -1,5 +1,5 @@ page.title=Creating an Input Method -parent.title=Articles +page.tags="ime","keyboard","inputmethodservice" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/text/spell-checker-framework.jd b/docs/html/guide/topics/text/spell-checker-framework.jd index 7f7a0b8..366f9cc 100644 --- a/docs/html/guide/topics/text/spell-checker-framework.jd +++ b/docs/html/guide/topics/text/spell-checker-framework.jd @@ -1,5 +1,5 @@ page.title=Spelling Checker Framework -parent.title=Articles +page.tags="input","spellcheckerservice" @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/ui/controls/button.jd b/docs/html/guide/topics/ui/controls/button.jd index 8d48e9c..41b67b7 100644 --- a/docs/html/guide/topics/ui/controls/button.jd +++ b/docs/html/guide/topics/ui/controls/button.jd @@ -1,6 +1,5 @@ page.title=Buttons -parent.title=Input Controls -parent.link=../controls.html +page.tags="button","imagebutton" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/checkbox.jd b/docs/html/guide/topics/ui/controls/checkbox.jd index ea70980..99140b5 100644 --- a/docs/html/guide/topics/ui/controls/checkbox.jd +++ b/docs/html/guide/topics/ui/controls/checkbox.jd @@ -1,6 +1,5 @@ page.title=Checkboxes -parent.title=Input Controls -parent.link=../controls.html + @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/pickers.jd b/docs/html/guide/topics/ui/controls/pickers.jd index cf90f1d..a0e7afb 100644 --- a/docs/html/guide/topics/ui/controls/pickers.jd +++ b/docs/html/guide/topics/ui/controls/pickers.jd @@ -1,6 +1,5 @@ -page.title= Pickers -parent.title=Form Controls -parent.link=controls-form.html +page.title=Pickers +page.tags="datepicker","timepicker" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/radiobutton.jd b/docs/html/guide/topics/ui/controls/radiobutton.jd index c96e576..d0c48ed 100644 --- a/docs/html/guide/topics/ui/controls/radiobutton.jd +++ b/docs/html/guide/topics/ui/controls/radiobutton.jd @@ -1,6 +1,5 @@ page.title=Radio Buttons -parent.title=Input Controls -parent.link=../controls.html +page.tags="radiobutton","radiogroup" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/spinner.jd b/docs/html/guide/topics/ui/controls/spinner.jd index deba3e6..85714b6 100644 --- a/docs/html/guide/topics/ui/controls/spinner.jd +++ b/docs/html/guide/topics/ui/controls/spinner.jd @@ -1,6 +1,5 @@ -page.title= Spinners -parent.title=Input Controls -parent.link=../controls.html +page.title=Spinners +page.tags="adapterview","spinneradapter" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/text.jd b/docs/html/guide/topics/ui/controls/text.jd index 654883d..c0b9873 100644 --- a/docs/html/guide/topics/ui/controls/text.jd +++ b/docs/html/guide/topics/ui/controls/text.jd @@ -1,6 +1,5 @@ page.title=Text Fields -parent.title=Input Controls -parent.link=../controls.html +page.tags="edittext","autocompletetextview" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/controls/togglebutton.jd b/docs/html/guide/topics/ui/controls/togglebutton.jd index dd7634b..3119cd9 100644 --- a/docs/html/guide/topics/ui/controls/togglebutton.jd +++ b/docs/html/guide/topics/ui/controls/togglebutton.jd @@ -1,6 +1,5 @@ page.title=Toggle Buttons -parent.title=Input Controls -parent.link=../controls.html +page.tags="switch","togglebutton" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/custom-components.jd b/docs/html/guide/topics/ui/custom-components.jd index be82dbc..703a5ce 100644 --- a/docs/html/guide/topics/ui/custom-components.jd +++ b/docs/html/guide/topics/ui/custom-components.jd @@ -1,6 +1,5 @@ page.title=Custom Components -parent.title=User Interface -parent.link=index.html +page.tags="view","widget" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 28e1418..6398646 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -1,6 +1,5 @@ page.title=Layouts -parent.title=User Interface -parent.link=index.html +page.tags="view","viewgroup" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 3cfed13..7f48eac 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -1,4 +1,6 @@ page.title=Dialogs +page.tags="alertdialog","dialogfragment" + @jd:body diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index 884a1b2..e989374 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -1,6 +1,5 @@ page.title=Drag and Drop -parent.title=User Interface -parent.link=index.html +page.tags="clipdata","dragevent","onlongclicklistener" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd deleted file mode 100644 index 1d15ad6..0000000 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ /dev/null @@ -1,6 +0,0 @@ -page.title=Layouts -parent.title=User Interface -parent.link=index.html -@jd:body - -<p>You should have been redirected to <a href="declaring-layout.html">Layouts</a>.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/layout/gridview.jd b/docs/html/guide/topics/ui/layout/gridview.jd index 84c3dab..bc189c4 100644 --- a/docs/html/guide/topics/ui/layout/gridview.jd +++ b/docs/html/guide/topics/ui/layout/gridview.jd @@ -1,6 +1,5 @@ page.title=Grid View -parent.title=Layouts -parent.link=layout-objects.html +page.tags="gridview" @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/ui/layout/linear.jd b/docs/html/guide/topics/ui/layout/linear.jd index 8e33706..444dc71 100644 --- a/docs/html/guide/topics/ui/layout/linear.jd +++ b/docs/html/guide/topics/ui/layout/linear.jd @@ -1,6 +1,5 @@ page.title=Linear Layout -parent.title=Layouts -parent.link=layout-objects.html +page.tags="linearlayout" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/layout/listview.jd b/docs/html/guide/topics/ui/layout/listview.jd index fee5292..6cdd725 100644 --- a/docs/html/guide/topics/ui/layout/listview.jd +++ b/docs/html/guide/topics/ui/layout/listview.jd @@ -1,6 +1,5 @@ page.title=List View -parent.title=Layouts -parent.link=declaring-layout.html +page.tags="listview" @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/ui/layout/relative.jd b/docs/html/guide/topics/ui/layout/relative.jd index 47f9417..65c5617 100644 --- a/docs/html/guide/topics/ui/layout/relative.jd +++ b/docs/html/guide/topics/ui/layout/relative.jd @@ -1,6 +1,5 @@ page.title=Relative Layout -parent.title=Layouts -parent.link=layout-objects.html +page.tags="relativelayout" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/ui/notifiers/index.jd b/docs/html/guide/topics/ui/notifiers/index.jd deleted file mode 100644 index caf0df7..0000000 --- a/docs/html/guide/topics/ui/notifiers/index.jd +++ /dev/null @@ -1,92 +0,0 @@ -page.title=Notifications -parent.title=User Interface -parent.link=../index.html -@jd:body - -<p>Several types of situations may arise that require you to notify the user -about an event that occurs in your application. Some events require the user to respond -and others do not. For example:</p> -<ul> - <li>When an event such as saving a file is complete, a small message -should appear to confirm that the save was successful.</li> - <li>If the application is running in the background and needs the user's attention, -the application should create a notification that allows the user to respond at -his or her convenience.</li> - <li>If the application is -performing work that the user must wait for (such as loading a file), -the application should show a hovering progress wheel or bar.</li> -</ul> - -<p>Each of these notification tasks can be achieved using a different technique:</p> -<ul> - <li>A <a href="#Toast">Toast Notification</a>, for brief messages that come - from the background.</li> - <li>A <a href="#StatusBar">Status Notification</a>, for persistent reminders - that come from the background and request the user's response.</li> - <li>A <a href="#Dialog">Dialog Notification</a>, for Activity-related notifications.</li> -</ul> - -<p>This document summarizes each of these techniques for notifying the user and includes -links to full documentation.</p> - - -<h2 id="Toast">Toast Notification</h2> - -<img src="{@docRoot}images/toast.png" alt="" style="float:right" /> - -<p>A toast notification is a message that pops up on the surface of the window. -It only fills the amount of space required for the message and the user's current -activity remains visible and interactive. The notification automatically fades in and -out, and does not accept interaction events. Because a toast can be created from a background -{@link android.app.Service}, it appears even if the application isn't visible.</p> - -<p>A toast is best for short text messages, such as "File saved," -when you're fairly certain the user is paying attention -to the screen. A toast can not accept user interaction events; if you'd like -the user to respond and take action, consider using a -<a href="#StatusBar">Status Notification</a> instead.</p> - -<p>For more information, refer to <a href="toasts.html">Toast Notifications</a>.</p> - - -<h2 id="StatusBar">Status Notification</h2> - -<img src="{@docRoot}images/notifications_window.png" alt="" style="float:right; clear:right;" /> - -<p>A status notification adds an icon to the system's status bar -(with an optional ticker-text message) and an expanded message in the "Notifications" window. -When the user selects the expanded message, Android fires an -{@link android.content.Intent} that is defined by the notification (usually to launch an -{@link android.app.Activity}). -You can also configure the notification to alert the user with a sound, a vibration, and flashing -lights on the device.</p> - -<p>This kind of notification is ideal when your application is working in -a background {@link android.app.Service} and needs to -notify the user about an event. If you need to alert the user about an event that occurs -while your Activity is still in focus, consider using a -<a href="#Dialog">Dialog Notification</a> instead.</p> - -<p>For more information, refer to -<a href="notifications.html">Status Notifications</a>.</p> - - -<h2 id="Dialog">Dialog Notification</h2> - -<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" /> - -<p>A dialog is usually a small window that appears in front of the current Activity. -The underlying Activity loses focus and the dialog accepts all user interaction. -Dialogs are normally used -for notifications and short activities that directly relate to the application in progress.</p> - -<p>You should use a dialog when you need to show a progress bar or a short -message that requires confirmation from the user (such as an alert with "OK" and "Cancel" buttons). -You can use also use dialogs as integral components -in your application's UI and for other purposes besides notifications. -For a complete discussion on all the available types of dialogs, -including its uses for notifications, refer to -<a href="{@docRoot}guide/topics/ui/dialogs.html">Dialogs</a>.</p> - - - diff --git a/docs/html/guide/topics/ui/settings.jd b/docs/html/guide/topics/ui/settings.jd index 33e164b..d96447d 100644 --- a/docs/html/guide/topics/ui/settings.jd +++ b/docs/html/guide/topics/ui/settings.jd @@ -1,4 +1,6 @@ page.title=Settings +page.tags="preference","preferenceactivity","preferencefragment" + @jd:body |