diff options
Diffstat (limited to 'docs/html/guide/topics')
17 files changed, 338 insertions, 290 deletions
diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index a474498..2d02e51 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -28,12 +28,6 @@ page.tags="devicepolicymanager","policy","security" <li>{@link android.app.admin.DevicePolicyManager}</li> <li>{@link android.app.admin.DeviceAdminInfo}</li> </ol> - <h2>Related samples</h2> - <ol> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> -DeviceAdminSample</a></li> -</ol> </div> </div> @@ -232,18 +226,12 @@ Administration API lets you do the following:</p> <ul> <h2 id="sample">Sample Application</h2> -<p>The examples used in this document are based on the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> -Device Administration API -sample</a>, which is included in the SDK samples. For information on downloading and -installing the SDK samples, see <a -href="{@docRoot}resources/samples/get.html"> -Getting the Samples</a>. Here is the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> -complete code</a> for -the sample. </p> -<p>The -sample application offers a demo of device admin features. It presents users +<p>The examples used in this document are based on the Device Administration API +sample, which is included in the SDK samples (available through the +Android SDK Manager) and located on your system as +<code><sdk_root>/ApiDemos/app/src/main/java/com/example/android/apis/app/DeviceAdminSample.java</code>.</p> + +<p>The sample application offers a demo of device admin features. It presents users with a user interface that lets them enable the device admin application. Once they've enabled the application, they can use the buttons in the user interface to do the following:</p> @@ -676,7 +664,8 @@ mDPM.setMaximumTimeToLock(mDeviceAdminSample, timeMs); <p>You can also programmatically tell the device to lock immediately:</p> <pre> DevicePolicyManager mDPM; -mDPM.lockNow();</pre> +mDPM.lockNow(); +</pre> @@ -692,12 +681,12 @@ wiped after a specific number of failed password attempts.</p> <pre> DevicePolicyManager mDPM; mDPM.wipeData(0);</pre> -<p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of -additional options. Currently the value must be 0. </p> +<p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its + parameter a bit mask of additional options. Currently the value must be 0. </p> <h4>Disable camera</h4> <p>Beginning with Android 4.0, you can disable the camera. Note that this doesn't have to be a permanent disabling. The camera can be enabled/disabled dynamically based on context, time, and so on. </p> -<p>You control whether the camera is disabled by using the +<p>You control whether the camera is disabled by using the {@link android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) setCameraDisabled()} method. For example, this snippet sets the camera to be enabled or disabled based on a checkbox setting:</p> <pre>private CheckBoxPreference mDisableCameraCheckbox; @@ -708,8 +697,8 @@ mDPM.setCameraDisabled(mDeviceAdminSample, mDisableCameraCheckbox.isChecked());< </pre> -<h4 id=storage">Storage encryption</h4> -<p>Beginning with Android 3.0, you can use the +<h4 id="storage">Storage encryption</h4> +<p>Beginning with Android 3.0, you can use the {@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} method to set a policy requiring encryption of the storage area, where supported.</p> @@ -722,5 +711,5 @@ ComponentName mDeviceAdminSample; mDPM.setStorageEncryption(mDeviceAdminSample, true); </pre> <p> -See the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> Device Administration API sample</a> for a complete -example of how to enable storage encryption.</p> +See the Device Administration API sample for a complete example of how to enable storage encryption. +</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/connectivity/nfc/nfc.jd b/docs/html/guide/topics/connectivity/nfc/nfc.jd index 5011872..520f520 100644 --- a/docs/html/guide/topics/connectivity/nfc/nfc.jd +++ b/docs/html/guide/topics/connectivity/nfc/nfc.jd @@ -105,8 +105,8 @@ or more records ({@link android.nfc.NdefRecord}). Each NDEF record must be well- the specification of the type of record that you want to create. Android also supports other types of tags that do not contain NDEF data, which you can work with by using the classes in the {@link android.nfc.tech} package. To learn more -about these technologies, see the <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced -NFC</a> topic. Working with these other types of tags involves +about these technologies, see the <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html +">Advanced NFC</a> topic. Working with these other types of tags involves writing your own protocol stack to communicate with the tags, so we recommend using NDEF when possible for ease of development and maximum support for Android-powered devices. </p> @@ -477,8 +477,8 @@ tag from the intent. Intents can contain the following extras depending on the t <li>{@link android.nfc.NfcAdapter#EXTRA_TAG} (required): A {@link android.nfc.Tag} object representing the scanned tag.</li> <li>{@link android.nfc.NfcAdapter#EXTRA_NDEF_MESSAGES} (optional): An array of NDEF messages -parsed from the tag. This extra is mandatory on {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED -intents.</li> +parsed from the tag. This extra is mandatory on +{@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intents.</li> <li>{@link android.nfc.NfcAdapter#EXTRA_ID} (optional): The low-level ID of the tag.</li></ul> <p>To obtain these extras, check to see if your activity was launched with one of @@ -513,7 +513,8 @@ contain the payload and allow you to enumerate the tag's technologies:</p> <p>This section describes how to create common types of NDEF records to help you when writing to NFC tags or sending data with Android Beam. Starting with Android 4.0 (API level 14), the {@link android.nfc.NdefRecord#createUri createUri()} method is available to help you create -URI records automatically. Starting in Android 4.1 (API level 16), {@link android.nfc.NdefRecord#createExternal createExternal()} +URI records automatically. Starting in Android 4.1 (API level 16), +{@link android.nfc.NdefRecord#createExternal createExternal()} and {@link android.nfc.NdefRecord#createMime createMime()} are available to help you create MIME and external type NDEF records. Use these helper methods whenever possible to avoid mistakes when manually creating NDEF records.</p> @@ -528,7 +529,8 @@ record of the NDEF message that you are writing to a tag or beaming.</p> <a href="#well-known-uri"><code>RTD_URI</code></a> type instead of {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI}, because it is more efficient.</p> -<p>You can create a {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record in the following way:</p> +<p>You can create a {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record in the following way +:</p> <pre> NdefRecord uriRecord = new NdefRecord( @@ -549,7 +551,8 @@ NdefRecord uriRecord = new NdefRecord( </pre> <h3 id="mime">TNF_MIME_MEDIA</h3> -<p>You can create a {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record in the following ways.</p> +<p>You can create a {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record in the following ways: +</p> <p>Using the {@link android.nfc.NdefRecord#createMime createMime()} method:</p> <pre> @@ -576,7 +579,8 @@ NdefRecord mimeRecord = new NdefRecord( <h3 id="well-known-text">TNF_WELL_KNOWN with RTD_TEXT</h3> -<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following way:</p> +<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following way: +</p> <pre> public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) { byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII")); @@ -606,7 +610,8 @@ public NdefRecord createTextRecord(String payload, Locale locale, boolean encode <h3 id="well-known-uri">TNF_WELL_KNOWN with RTD_URI</h3> -<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following ways.</p> +<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following ways: +</p> <p>Using the {@link android.nfc.NdefRecord#createUri(String)} method:</p> <pre> @@ -642,7 +647,8 @@ NdefRecord rtdUriRecord = new NdefRecord( </pre> <h3 id="ext-type">TNF_EXTERNAL_TYPE</h3> -<p>You can create a {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record in the following ways:</p> +<p>You can create a {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record in the following +ways:</p> <p>Using the {@link android.nfc.NdefRecord#createExternal createExternal()} method: <pre> @@ -681,19 +687,19 @@ android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} have a canonical format of: declares that the <code>urn:nfc:ext:</code> portion of the URN must be ommitted from the NDEF record. So all you need to provide is the domain (<code>example.com</code> in the example) and type (<code>externalType</code> in the example) separated by a colon. -When dispatching TNF_EXTERNAL_TYPE, Android converts the <code>urn:nfc:ext:example.com:externalType</code> URN to a -<code>vnd.android.nfc://ext/example.com:externalType</code> URI, which is what the intent filter in the example -declares.</p> +When dispatching TNF_EXTERNAL_TYPE, Android converts the <code>urn:nfc:ext:example.com:externalType +</code> URN to a <code>vnd.android.nfc://ext/example.com:externalType</code> URI, which is what the +intent filter in the example declares.</p> <h3 id="aar">Android Application Records</h3> <p> Introduced in Android 4.0 (API level 14), an Android Application Record (AAR) provides a stronger certainty that your application is started when an NFC tag is scanned. An AAR has the package name -of an application embedded inside an NDEF record. You can add an AAR to any NDEF record of your NDEF message, -because Android searches the entire NDEF message for AARs. If it finds an AAR, it starts the application based -on the package name inside the AAR. If the application is not present on the device, -Google Play is launched to download the application.</p> +of an application embedded inside an NDEF record. You can add an AAR to any NDEF record of your NDEF +message, because Android searches the entire NDEF message for AARs. If it finds an AAR, it starts +the application based on the package name inside the AAR. If the application is not present on the +device, Google Play is launched to download the application.</p> <p>AARs are useful if you want to prevent other applications from filtering for the same intent and potentially handling specific tags that you have deployed. AARs are only supported at the @@ -717,11 +723,11 @@ application based on the AAR.</li> </p> -<p class="note"><strong>Note:</strong> You can override AARs and the intent dispatch system with the <a -href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground dispatch -system</a>, which allows a foreground activity to have priority when an NFC tag is discovered. -With this method, the activity must be in the foreground to -override AARs and the intent dispatch system.</p> +<p class="note"><strong>Note:</strong> You can override AARs and the intent dispatch system with the + <ahref="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground + dispatch system</a>, which allows a foreground activity to have priority when an NFC tag is + discovered. With this method, the activity must be in the foreground to override AARs and the + intent dispatch system.</p> <p>If you still want to filter for scanned tags that do not contain an AAR, you can declare intent filters as normal. This is useful if your application is interested in other tags @@ -799,9 +805,9 @@ API level 14 (Android 4.0) and later.</li> <p class="note"><strong>Note:</strong> If your activity enables Android Beam and is in the foreground, the standard intent dispatch system is disabled. However, if your activity also -enables <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground -dispatching</a>, then it can still scan tags that match the intent filters set in the foreground -dispatching.</p> +enables <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch"> +foreground dispatching</a>, then it can still scan tags that match the intent filters set in the +foreground dispatching.</p> <p>To enable Android Beam:</p> diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index d842cb9..4b5a121 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -32,7 +32,7 @@ APIs</a></li> </div> </div> -<p>The Android framework APIs provides a set 2D drawing APIs that allow you to render your own +<p>The Android framework APIs provides a set of 2D-drawing APIs that allow you to render your own custom graphics onto a canvas or to modify existing Views to customize their look and feel. When drawing 2D graphics, you'll typically do so in one of two ways:</p> @@ -515,4 +515,4 @@ Notice how the width and height of the button varies with the text, and the back stretches to accommodate it. </p> -<img src="{@docRoot}images/ninepatch_examples.png" alt=""/>
\ No newline at end of file +<img src="{@docRoot}images/ninepatch_examples.png" alt=""/> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index eb37b9a..7c71e99 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -5,7 +5,8 @@ parent.link=manifest-intro.html <dl class="xml"> <dt>syntax:</dt> -<dd><pre class="stx"><activity android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] +<dd><pre class="stx"><activity android:<a href="#embedded">allowEmbedded</a>=["true" | "false"] + android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"] android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale", @@ -62,6 +63,17 @@ by the system and will never be run. <dt>attributes:</dt> <dd><dl class="attr"> +<dt><a name="embedded"></a>{@code android:allowEmbedded}</dt> +<dd> + Indicate that the activity can be launched as the embedded child of another + activity. Particularly in the case where the child lives in a container + such as a Display owned by another activity. For example, activities + that are used for Wear custom notifications must declare this so + Wear can display the activity in it's context stream, which resides + in another process. + + <p>The default value of this attribute is <code>false</code>. +</dd> <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> <dd>Whether or not the activity can move from the task that started it to the task it has an affinity for when that task is next brought to the @@ -441,7 +453,7 @@ Similarly, a new instance of a "{@code singleTop}" activity may also be created to handle a new intent. However, if the target task already has an existing instance of the activity at the top of its stack, that instance will receive the new intent (in an -<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call); +{@link android.app.Activity#onNewIntent onNewIntent()} call); a new instance is not created. In other circumstances — for example, if an existing instance of the "{@code singleTop}" activity is in the target task, but not at the top of @@ -449,6 +461,22 @@ the stack, or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack. </p> +<p>Similarly, if you +<a href="{@docRoot}training/implementing-navigation/ancestral.html">navigate +up</a> to an activity on the current stack, the behavior is determined by the +parent activity's launch mode. If the parent activity has launch mode {@code +singleTop} (or the <code>up</code> intent contains {@link +android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the parent is brought to the +top of the stack, and its state is preserved. The navigation intent is received +by the parent activity's {@link android.app.Activity#onNewIntent onNewIntent()} +method. If the parent activity has launch mode {@code standard} (and the +<code>up</code> intent does not contain {@link +android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the current activity and its +parent are both popped off the stack, and a new instance of the parent activity +is created to receive the navigation intent. +</p> + + <p> The "{@code singleTask}" and "{@code singleInstance}" modes also differ from each other in only one respect: A "{@code singleTask}" activity allows other diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 814396c..ca954fe 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -584,9 +584,14 @@ is sensitive to delays or lag in sound input or output.</td> </tr> <tr> <td><code>android.hardware.camera.any</code></td> - <td>The application uses at least one camera facing in any direction. Use this -in preference to <code>android.hardware.camera</code> if a back-facing camera is -not required.</td> + <td>The application uses at least one camera facing in any direction, or an +external camera device if one is connected. Use this in preference to +<code>android.hardware.camera</code> if a back-facing camera is not required. + </td> +</tr> +<tr> + <td><code>android.hardware.camera.external</code></td> + <td>The application uses an external camera device if one is connected.</td> </tr> <tr> @@ -1099,4 +1104,4 @@ filtering based on the <code>CAMERA</code> permission, you would add this <td><code>android.hardware.wifi</code></td> <!-- <td></td> --> </tr> -</table>
\ No newline at end of file +</table> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index c62510b..100894c 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -157,8 +157,7 @@ precision (such as SIMD CPU instructions).</p> <ul> <li><strong>{@link android.renderscript}</strong> - The APIs in this class package are - available on devices running Android 3.0 (API level 11) and higher. These are the original APIs - for RenderScript and are not currently being updated.</li> + available on devices running Android 3.0 (API level 11) and higher. </li> <li><strong>{@link android.support.v8.renderscript}</strong> - The APIs in this package are available through a <a href="{@docRoot}tools/support-library/features.html#v8">Support Library</a>, which allows you to use them on devices running Android 2.2 (API level 8) and @@ -166,8 +165,8 @@ precision (such as SIMD CPU instructions).</p> </ul> <p>We strongly recommend using the Support Library APIs for accessing RenderScript because they - include the latest improvements to the RenderScript compute framework and provide a wider range - of device compatibility.</p> + provide a wider range of device compatibility. Developers targeting specific versions of + Android can use {@link android.renderscript} if necessary.</p> <h3 id="ide-setup">Using the RenderScript Support Library APIs</h3> @@ -308,4 +307,4 @@ function launches as necessary.</li> <li><strong>Tear down the RenderScript context.</strong> The RenderScript context can be destroyed with {@link android.renderscript.RenderScript#destroy} or by allowing the RenderScript context object to be garbage collected. This will cause any further use of any object belonging to that -context to throw an exception.</li> </ol>
\ No newline at end of file +context to throw an exception.</li> </ol> diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd index e86d4c9..1ee6606 100644 --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -402,8 +402,7 @@ that Android makes available:</p> resolution and density of the device screen may differ, which could affect
the display of strings and drawables in your UI.</p>
-<p>To change the locale on a device, use the Settings application (Home >
-Menu > Settings > Locale & text > Select locale). </p>
+<p>To change the locale or language on a device, use the Settings application.</p>
<h3 id="emulator">Testing on an Emulator</h3>
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index aec7fa7..6d9527f 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -389,7 +389,7 @@ should be the actual smallest dimension <em>required by your layout</em> (usuall <ul> <li>240x320 ldpi (QVGA handset)</li> <li>320x480 mdpi (handset)</li> - <li>480x800 hdpi (high density handset)</li> + <li>480x800 hdpi (high-density handset)</li> </ul> </li> <li>480, for screens such as 480x800 mdpi (tablet/handset).</li> @@ -483,20 +483,20 @@ Multiple Screens</a> developer guide.</p> <ul class="nolist"> <li>{@code small}: Screens that are of similar size to a low-density QVGA screen. The minimum layout size for a small screen - is approximately 320x426 dp units. Examples are QVGA low density and VGA high + is approximately 320x426 dp units. Examples are QVGA low-density and VGA high density.</li> <li>{@code normal}: Screens that are of similar size to a medium-density HVGA screen. The minimum layout size for a normal screen is approximately 320x470 dp units. Examples - of such screens a WQVGA low density, HVGA medium density, WVGA - high density.</li> + of such screens a WQVGA low-density, HVGA medium-density, WVGA + high-density.</li> <li>{@code large}: Screens that are of similar size to a medium-density VGA screen. The minimum layout size for a large screen is approximately 480x640 dp units. - Examples are VGA and WVGA medium density screens.</li> + Examples are VGA and WVGA medium-density screens.</li> <li>{@code xlarge}: Screens that are considerably larger than the traditional medium-density HVGA screen. The minimum layout size for an xlarge screen - is approximately 720x960 dp units. In most cases, devices with extra large + is approximately 720x960 dp units. In most cases, devices with extra-large screens would be too large to carry in a pocket and would most likely be tablet-style devices. <em>Added in API level 9.</em></li> </ul> @@ -562,6 +562,7 @@ which indicates the current device orientation.</p> <code>desk</code><br/> <code>television<br/> <code>appliance</code> + <code>watch</code> </td> <td> <ul class="nolist"> @@ -573,8 +574,9 @@ which indicates the current device orientation.</p> non-pointer interaction</li> <li>{@code appliance}: Device is serving as an appliance, with no display</li> + <li>{@code watch}: Device has a display and is worn on the wrist</li> </ul> - <p><em>Added in API level 8, television added in API 13.</em></p> + <p><em>Added in API level 8, television added in API 13, watch added in API 20.</em></p> <p>For information about how your app can respond when the device is inserted into or removed from a dock, read <a href="{@docRoot}training/monitoring-device-state/docking-monitoring.html">Determining @@ -611,6 +613,8 @@ application during runtime.</p> <code>mdpi</code><br/> <code>hdpi</code><br/> <code>xhdpi</code><br/> + <code>xxhdpi</code><br/> + <code>xxxhdpi</code><br/> <code>nodpi</code><br/> <code>tvdpi</code> </td> @@ -620,8 +624,14 @@ application during runtime.</p> <li>{@code mdpi}: Medium-density (on traditional HVGA) screens; approximately 160dpi.</li> <li>{@code hdpi}: High-density screens; approximately 240dpi.</li> - <li>{@code xhdpi}: Extra high-density screens; approximately 320dpi. <em>Added in API + <li>{@code xhdpi}: Extra-high-density screens; approximately 320dpi. <em>Added in API Level 8</em></li> + <li>{@code xxhdpi}: Extra-extra-high-density screens; approximately 480dpi. <em>Added in API +Level 16</em></li> + <li>{@code xxxhdpi}: Extra-extra-extra-high-density uses (launcher icon only, see the + <a href="{@docRoot}guide/practices/screens_support.html#xxxhdpi-note">note</a> + in <em>Supporting Multiple Screens</em>); approximately 640dpi. <em>Added in API +Level 18</em></li> <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled to match the device density.</li> <li>{@code tvdpi}: Screens somewhere between mdpi and hdpi; approximately 213dpi. This is @@ -629,8 +639,9 @@ not considered a "primary" density group. It is mostly intended for televisions apps shouldn't need it—providing mdpi and hdpi resources is sufficient for most apps and the system will scale them as appropriate. This qualifier was introduced with API level 13.</li> </ul> - <p>There is a 3:4:6:8 scaling ratio between the four primary densities (ignoring the -tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p> + <p>There is a 3:4:6:8:12:16 scaling ratio between the six primary densities (ignoring the +tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi, 24x24 in xhdpi and so on. +</p> <p>If you decide that your image resources don't look good enough on a television or other certain devices and want to try tvdpi resources, the scaling factor is 1.33*mdpi. For example, a 100px x 100px image for mdpi screens should be 133px x 133px for tvdpi.</p> diff --git a/docs/html/guide/topics/text/creating-input-method.jd b/docs/html/guide/topics/text/creating-input-method.jd index 7254594..8b75cc8 100644 --- a/docs/html/guide/topics/text/creating-input-method.jd +++ b/docs/html/guide/topics/text/creating-input-method.jd @@ -4,6 +4,30 @@ page.tags="ime","keyboard","inputmethodservice" <div id="qv-wrapper"> <div id="qv"> +<h2>In This Document</h2> +<ol> + <li> + <a href="#InputMethodLifecycle">The IME Lifecycle</a> + </li> + <li> + <a href="#DefiningIME">Declaring IME Components in the Manifest</a> + </li> + <li> + <a href="#IMEAPI">The Input Method API</a> + </li> + <li> + <a href="#IMEUI">Designing the Input Method UI</a> + </li> + <li> + <a href="#SendText">Sending Text to the Application</a> + </li> + <li> + <a href="#IMESubTypes">Creating an IME Subtype</a> + </li> + <li> + <a href="#GeneralDesign">General IME Considerations</a> + </li> +</ol> <h2>See also</h2> <ol> <li> @@ -16,29 +40,20 @@ page.tags="ime","keyboard","inputmethodservice" </div> </div> <p> - An input method editor (IME) is a user control that enables users to enter text. Android - provides an extensible input method framework that allows applications to provide users - alternative input methods, such as on-screen keyboards or even speech input. Once installed, - users can select which IME they want to use from the system settings and use it across the + An input method editor (IME) is a user control that enables users to enter text. Android + provides an extensible input method framework that allows applications to provide users + alternative input methods, such as on-screen keyboards or even speech input. Once installed, + users can select which IME they want to use from the system settings and use it across the entire system; only one IME may be enabled at a time. </p> <p> To add an IME to the Android system, you create an Android application - containing a class that extends {@link android.inputmethodservice.InputMethodService}. In + containing a class that extends {@link android.inputmethodservice.InputMethodService}. In addition, you usually create a "settings" activity that passes options to the IME service. You can also define a settings UI that's displayed as part of the system settings. </p> -<p>This article covers the following:</p> -<ul> - <li>The IME lifecycle.</li> - <li>Declaring IME components in the application manifest.</li> - <li>The IME API.</li> - <li>Designing an IME UI.</li> - <li>Sending text from an IME to an application.</li> - <li>Working with IME subtypes.</li> -</ul> <p> - If you haven't worked with IMEs before, you should read the introductory article + If you haven't worked with IMEs before, you should read the introductory article <a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> first. Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify to start building your own IME. @@ -59,16 +74,16 @@ page.tags="ime","keyboard","inputmethodservice" <h2 id="DefiningIME">Declaring IME Components in the Manifest</h2> <p> In the Android system, an IME is an Android application that contains a special IME service. - The application's manifest file must declare the service, request the necessary permissions, - provide an intent filter that matches the action <code>action.view.InputMethod</code>, and + The application's manifest file must declare the service, request the necessary permissions, + provide an intent filter that matches the action <code>action.view.InputMethod</code>, and provide metadata that defines characteristics of the IME. In addition, to provide a settings interface that allows the user to modify the behavior of the IME, you can define a "settings" activity that can be launched from System Settings. </p> <p> The following snippet declares IME service. It requests the permission {@link - android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to - the system, sets up an intent filter that matches the action + android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to + the system, sets up an intent filter that matches the action <code>android.view.InputMethod</code>, and defines metadata for the IME: </p> <pre> @@ -88,7 +103,7 @@ page.tags="ime","keyboard","inputmethodservice" for the IME application:</p> <pre> <!-- Optional: an activity for controlling the IME settings --> - <activity android:name="FastInputIMESettings" + <activity android:name="FastInputIMESettings" android:label="@string/fast_input_settings"> <intent-filter> <action android:name="android.intent.action.MAIN"/> @@ -105,12 +120,12 @@ page.tags="ime","keyboard","inputmethodservice" handling keyboard characters. </p> <p> - The central part of an IME is a service component, a class that extends - {@link android.inputmethodservice.InputMethodService}. In addition to implementing the - normal service lifecycle, this class has callbacks for providing your IME's UI, handling user + The central part of an IME is a service component, a class that extends + {@link android.inputmethodservice.InputMethodService}. In addition to implementing the + normal service lifecycle, this class has callbacks for providing your IME's UI, handling user input, and delivering text to the field that currently has focus. By default, the - {@link android.inputmethodservice.InputMethodService} class provides most of the implementation - for managing the state and visibility of the IME and communicating with the current + {@link android.inputmethodservice.InputMethodService} class provides most of the implementation + for managing the state and visibility of the IME and communicating with the current input field. </p> <p> @@ -122,13 +137,13 @@ page.tags="ime","keyboard","inputmethodservice" Defines the communication channel from an {@link android.view.inputmethod.InputMethod} back to the application that is receiving its input. You use it to read text around the cursor, commit text to the text box, and send raw key events to the application. - Applications should extend this class rather than implementing the base interface + Applications should extend this class rather than implementing the base interface {@link android.view.inputmethod.InputConnection}. </dd> <dt>{@link android.inputmethodservice.KeyboardView}</dt> <dd> An extension of {@link android.view.View} that renders a keyboard and responds to user - input events. The keyboard layout is specified by an instance of + input events. The keyboard layout is specified by an instance of {@link android.inputmethodservice.Keyboard}, which you can define in an XML file. </dd> </dl> @@ -141,40 +156,40 @@ page.tags="ime","keyboard","inputmethodservice" <h3 id="InputView">Input view</h3> <p> The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or - gestures. When the iIME is displayed for the first time, the system calls the + gestures. When the iIME is displayed for the first time, the system calls the {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your implementation of this method, you create the layout you want to display in the IME window and return the layout to the system. This snippet is an example of implementing the {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: <pre> - @Override - public View onCreateInputView() { - MyKeyboardView inputView = + @Override + public View onCreateInputView() { + MyKeyboardView inputView = (MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null); - - inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); - - return mInputView; - } + + inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); + + return mInputView; + } </pre> <p> - In this example, {@code MyKeyboardView} is an instance of a custom implementation of - {@link android.inputmethodservice.KeyboardView} that renders a - {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, - see the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample + In this example, {@code MyKeyboardView} is an instance of a custom implementation of + {@link android.inputmethodservice.KeyboardView} that renders a + {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, + see the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample app</a> for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class. </p> <h3 id="CandidateView">Candidates view</h3> <p> The candidates view is the UI where the IME displays potential word corrections or - suggestions for the user to select. In the IME lifecycle, the system calls - {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready + suggestions for the user to select. In the IME lifecycle, the system calls + {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready to display the candidate view. In your implementation of this method, return a layout that shows word suggestions, or return null if you don’t want to show anything (a null response is the default behavior, so you don’t have to implement this if you don’t provide suggestions).</p> <p> - For an example implementation that provides user suggestions, see the - Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample + For an example implementation that provides user suggestions, see the + Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample app</a>. </p> <h3 id="DesignConsiderations">UI design considerations</h3> @@ -209,10 +224,10 @@ page.tags="ime","keyboard","inputmethodservice" <strong>Figure 2.</strong> Latin IME input types. </p> <p> - When an input field receives focus and your IME starts, the system calls + When an input field receives focus and your IME starts, the system calls {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) - onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that - contains details about the input type and other attributes of the text field. In this object, + onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that + contains details about the input type and other attributes of the text field. In this object, the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input type. </p> @@ -223,7 +238,7 @@ page.tags="ime","keyboard","inputmethodservice" this: </p> <pre> -inputType & InputType.TYPE_MASK_CLASS +inputType & InputType.TYPE_MASK_CLASS </pre> <p> The input type bit pattern can have one of several values, including: @@ -248,7 +263,7 @@ The input type bit pattern can have one of several values, including: </dd> </dl> <p> - These constants are described in more detail in the reference documentation for + These constants are described in more detail in the reference documentation for {@link android.text.InputType}. </p> <p> @@ -287,8 +302,8 @@ The input type bit pattern can have one of several values, including: <p> As the user inputs text with your IME, you can send text to the application by sending individual key events or by editing the text around the cursor in the application's text - field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} - to deliver the text. To get this instance, call + field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} + to deliver the text. To get this instance, call {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection InputMethodService.getCurrentInputConnection()}. </p> @@ -336,18 +351,18 @@ The input type bit pattern can have one of several values, including: </p> <pre> InputConnection ic = getCurrentInputConnection(); - + ic.deleteSurroundingText(4, 0); - + ic.commitText("Hello", 1); - + ic.commitText("!", 1); </pre> <h3 id="ComposeThenCommit">Composing text before committing</h3> <p> If your IME does text prediction or requires multiple steps to compose a glyph or word, you can show the progress in the text field until the user commits the word, and then you - can replace the partial composition with the completed text. You may give special treatment to + can replace the partial composition with the completed text. You may give special treatment to the text by adding a "span" to it when you pass it to InputConnection#setComposingText(). </p> <p> @@ -385,10 +400,10 @@ The input type bit pattern can have one of several values, including: selection during composition. You may also want to trap the back key to dismiss any popups originating from the input method window.</p> <p> - To intercept hardware keys, override + To intercept hardware keys, override {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()} - and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. - See the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample + and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. + See the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample app</a> for an example. </p> <p> @@ -396,7 +411,7 @@ The input type bit pattern can have one of several values, including: </p> <h2 id="IMESubTypes">Creating an IME Subtype</h2> <p> - Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A + Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A subtype can represent: </p> <ul> @@ -414,13 +429,13 @@ The input type bit pattern can have one of several values, including: <p> Subtype information is used for an IME switcher dialog that's available from the notification bar and also for IME settings. The information also allows the framework to bring up a - specific subtype of an IME directly. When you build an IME, use the subtype facility, because + specific subtype of an IME directly. When you build an IME, use the subtype facility, because it helps the user identify and switch between different IME languages and modes. </p> <p> You define subtypes in one of the input method's XML resource files, using the - <code><subtype></code> element. The following snippet defines an IME with two - subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the + <code><subtype></code> element. The following snippet defines an IME with two + subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the French language locale for France: </p> <pre> @@ -457,8 +472,8 @@ The input type bit pattern can have one of several values, including: android:imeSubtypeMode="keyboard" /> </pre> <p> - The next snippet is part of the IME's <code>strings.xml</code> file. The string - resource <code>label_subtype_generic</code>, which is used by the input method UI definition to + The next snippet is part of the IME's <code>strings.xml</code> file. The string + resource <code>label_subtype_generic</code>, which is used by the input method UI definition to set the subtype's label, is defined as: </p> <pre> @@ -487,9 +502,9 @@ The input type bit pattern can have one of several values, including: <h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3> <p> A user can control how subtypes are used in the “Language & input” settings panel in the - System Settings area. In the Soft Keyboard sample, the file - <code>InputMethodSettingsFragment.java</code> contains an implementation that - facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in + System Settings area. In the Soft Keyboard sample, the file + <code>InputMethodSettingsFragment.java</code> contains an implementation that + facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in the Android SDK for more information about how to support Input Method Subtypes in your IME. </p> <img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt="" @@ -497,6 +512,7 @@ The input type bit pattern can have one of several values, including: <p class="img-caption"> <strong>Figure 6.</strong> Choosing a language for the IME. </p> + <h2 id="GeneralDesign">General IME Considerations</h2> <p> Here are some other things to consider as you're implementing your IME: @@ -506,22 +522,22 @@ The input type bit pattern can have one of several values, including: Provide a way for users to set options directly from the IME's UI. </li> <li> - Because multiple IMEs may be installed on the device, provide a way for the user to switch to a + Because multiple IMEs may be installed on the device, provide a way for the user to switch to a different IME directly from the input method UI. </li> <li> - Bring up the IME's UI quickly. Preload or load on demand any large resources so that users - see the IME as soon as they tap on a text field. Cache resources and views for subsequent + Bring up the IME's UI quickly. Preload or load on demand any large resources so that users + see the IME as soon as they tap on a text field. Cache resources and views for subsequent invocations of the input method. </li> <li> - Conversely, you should release large memory allocations soon after the input method window is + Conversely, you should release large memory allocations soon after the input method window is hidden, so that applications can have sufficient memory to run. Consider using a delayed message to release resources if the IME is in a hidden state for a few seconds. -</li> +</li> <li> - Make sure that users can enter as many characters as possible for the language or locale - associated with the IME. Remember that users may use punctuation in passwords or user + Make sure that users can enter as many characters as possible for the language or locale + associated with the IME. Remember that users may use punctuation in passwords or user names, so your IME has to provide many different characters to allow users to enter a password and get access to the device. </li> diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd index 4bd752f..d69af9f 100644 --- a/docs/html/guide/topics/ui/accessibility/services.jd +++ b/docs/html/guide/topics/ui/accessibility/services.jd @@ -71,23 +71,30 @@ accessibility service.</p> <h3 id="service-declaration">Accessibility service declaration</h3> -<p>In order to be treated as an accessibility service, your application must include the +<p>In order to be treated as an accessibility service, you must include a {@code service} element (rather than the {@code activity} element) within the {@code application} -element in its manifest. In addition, within the {@code service} element, you must also include an +element in your manifest. In addition, within the {@code service} element, you must also include an accessibility service intent filter. For compatiblity with Android 4.1 and higher, the manifest must also request the {@link android.Manifest.permission#BIND_ACCESSIBILITY_SERVICE} permission as shown in the following sample:</p> <pre> -<application> - <service android:name=".MyAccessibilityService" - android:label="@string/accessibility_service_label"> - <intent-filter> - <action android:name="android.accessibilityservice.AccessibilityService" /> - </intent-filter> - </service> - <uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE" /> -</application> +<manifest> + ... + <uses-permission ... /> + ... + <application> + ... + <service android:name=".MyAccessibilityService" + android:label="@string/accessibility_service_label" + android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + </service> + <uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE" /> + </application> +</manifest> </pre> <p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index f01d4bf..215d658 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -1427,7 +1427,7 @@ href="#ActionView">action views</a>.</dd> <p>Here's an example that defines a custom theme for an activity, {@code CustomActivityTheme}, that includes several styles to customize the action bar.</p> -<p>Notice that there are two version for each action bar style property. The first one +<p>Notice that there are two versions for each action bar style property. The first one includes the {@code android:} prefix on the property name to support API levels 11 and higher that include these properties in the framework. The second version does <em>not</em> include the {@code android:} prefix and is for older versions of the platform, on which diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 6586c2f..e1d51e6 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -31,7 +31,7 @@ page.tags="view","viewgroup" <li>{@link android.view.ViewGroup}</li> <li>{@link android.view.ViewGroup.LayoutParams}</li> </ol> - + <h2>See also</h2> <ol> <li><a href="{@docRoot}training/basics/firstapp/building-ui.html">Building a Simple User @@ -43,9 +43,9 @@ href="{@docRoot}guide/components/activities.html">activity</a> or <a href="{@docRoot}guide/topics/appwidgets/index.html">app widget</a>. You can declare a layout in two ways:</p> <ul> -<li><strong>Declare UI elements in XML</strong>. Android provides a straightforward XML +<li><strong>Declare UI elements in XML</strong>. Android provides a straightforward XML vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts.</li> -<li><strong>Instantiate layout elements at runtime</strong>. Your +<li><strong>Instantiate layout elements at runtime</strong>. Your application can create View and ViewGroup objects (and manipulate their properties) programmatically. </li> </ul> @@ -55,12 +55,12 @@ application can create View and ViewGroup objects (and manipulate their properti <div class="sidebox"> <ul> <li>The <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT - Plugin for Eclipse</a> offers a layout preview of your XML — + Plugin for Eclipse</a> offers a layout preview of your XML — with the XML file opened, select the <strong>Layout</strong> tab.</li> - <li>You should also try the - <a href="{@docRoot}tools/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, - for debugging layouts — it reveals layout property values, - draws wireframes with padding/margin indicators, and full rendered views while + <li>You should also try the + <a href="{@docRoot}tools/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, + for debugging layouts — it reveals layout property values, + draws wireframes with padding/margin indicators, and full rendered views while you debug on the emulator or device.</li> <li>The <a href="{@docRoot}tools/debugging/debugging-ui.html#layoutopt">layoutopt</a> tool lets you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> @@ -68,10 +68,10 @@ application can create View and ViewGroup objects (and manipulate their properti </div> <p>The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're -interested in instantiating View objects at runtime, refer to the {@link android.view.ViewGroup} and +interested in instantiating View objects at runtime, refer to the {@link android.view.ViewGroup} and {@link android.view.View} class references.</p> -<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. However, note that not all vocabulary is identical. In some cases, there are slight naming differences. For +<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given XML element. However, note that not all vocabulary is identical. In some cases, there are slight naming differences. For example, the EditText element has a <code>text</code> attribute that corresponds to <code>EditText.setText()</code>. </p> @@ -88,8 +88,8 @@ to hold a {@link android.widget.TextView} and a {@link android.widget.Button}:</ <pre> <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:orientation="vertical" > <TextView android:id="@+id/text" android:layout_width="wrap_content" @@ -102,7 +102,7 @@ to hold a {@link android.widget.TextView} and a {@link android.widget.Button}:</ </LinearLayout> </pre> -<p>After you've declared your layout in XML, save the file with the <code>.xml</code> extension, +<p>After you've declared your layout in XML, save the file with the <code>.xml</code> extension, in your Android project's <code>res/layout/</code> directory, so it will properly compile. </p> <p>More information about the syntax for a layout XML file is available in the <a @@ -111,11 +111,11 @@ href="{@docRoot}guide/topics/resources/layout-resource.html">Layout Resources</a <h2 id="load">Load the XML Resource</h2> <p>When you compile your application, each XML layout file is compiled into a -{@link android.view.View} resource. You should load the layout resource from your application code, in your +{@link android.view.View} resource. You should load the layout resource from your application code, in your {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} callback implementation. -Do so by calling <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, -passing it the reference to your layout resource in the form of: -<code>R.layout.<em>layout_file_name</em></code> +Do so by calling <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, +passing it the reference to your layout resource in the form of: +<code>R.layout.<em>layout_file_name</em></code>. For example, if your XML layout is saved as <code>main_layout.xml</code>, you would load it for your Activity like so:</p> <pre> @@ -126,7 +126,7 @@ public void onCreate(Bundle savedInstanceState) { </pre> <p>The <code>onCreate()</code> callback method in your Activity is called by the Android framework when -your Activity is launched (see the discussion about lifecycles, in the +your Activity is launched (see the discussion about lifecycles, in the <a href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> document).</p> @@ -136,18 +136,18 @@ document).</p> <p>Every View and ViewGroup object supports their own variety of XML attributes. Some attributes are specific to a View object (for example, TextView supports the <code>textSize</code> attribute), but these attributes are also inherited by any View objects that may extend this class. -Some are common to all View objects, because they are inherited from the root View class (like -the <code>id</code> attribute). And, other attributes are considered "layout parameters," which are +Some are common to all View objects, because they are inherited from the root View class (like +the <code>id</code> attribute). And, other attributes are considered "layout parameters," which are attributes that describe certain layout orientations of the View object, as defined by that object's parent ViewGroup object.</p> <h3 id="id">ID</h3> <p>Any View object may have an integer ID associated with it, to uniquely identify the View within the tree. -When the application is compiled, this ID is referenced as an integer, but the ID is typically +When the application is compiled, this ID is referenced as an integer, but the ID is typically assigned in the layout XML file as a string, in the <code>id</code> attribute. This is an XML attribute common to all View objects -(defined by the {@link android.view.View} class) and you will use it very often. +(defined by the {@link android.view.View} class) and you will use it very often. The syntax for an ID, inside an XML tag is:</p> <pre>android:id="@+id/my_button"</pre> @@ -170,7 +170,7 @@ resources class, rather than the local resources class.</p> android:text="@string/my_button_text"/> </pre> </li> - <li>Then create an instance of the view object and capture it from the layout + <li>Then create an instance of the view object and capture it from the layout (typically in the <code>{@link android.app.Activity#onCreate(Bundle) onCreate()}</code> method): <pre> Button myButton = (Button) findViewById(R.id.my_button); @@ -178,16 +178,16 @@ Button myButton = (Button) findViewById(R.id.my_button); </li> </ol> <p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}. -In a relative layout, sibling views can define their layout relative to another sibling view, +In a relative layout, sibling views can define their layout relative to another sibling view, which is referenced by the unique ID.</p> <p>An ID need not be unique throughout the entire tree, but it should be -unique within the part of the tree you are searching (which may often be the entire tree, so it's best +unique within the part of the tree you are searching (which may often be the entire tree, so it's best to be completely unique when possible).</p> <h3 id="layout-params">Layout Parameters</h3> -<p>XML layout attributes named <code>layout_<em>something</em></code> define +<p>XML layout attributes named <code>layout_<em>something</em></code> define layout parameters for the View that are appropriate for the ViewGroup in which it resides.</p> <p>Every ViewGroup class implements a nested class that extends {@link @@ -201,7 +201,7 @@ view group defines layout parameters for each child view (including the child vi parameters associated with each view.</p> <p>Note that every LayoutParams subclass has its own syntax for setting -values. Each child element must define LayoutParams that are appropriate for its parent, +values. Each child element must define LayoutParams that are appropriate for its parent, though it may also define different LayoutParams for its own children. </p> <p>All view groups include a width and height (<code>layout_width</code> and @@ -214,15 +214,15 @@ set the width or height: </p> <ul> <li><var>wrap_content</var> tells your view to size itself to the dimensions -required by its content</li> - <li><var>fill_parent</var> (renamed <var>match_parent</var> in API Level 8) +required by its content.</li> + <li><var>match_parent</var> (named <var>fill_parent</var> before API Level 8) tells your view to become as big as its parent view group will allow.</li> </ul> <p>In general, specifying a layout width and height using absolute units such as pixels is not recommended. Instead, using relative measurements such as density-independent pixel units (<var>dp</var>), <var>wrap_content</var>, or -<var>fill_parent</var>, is a better approach, because it helps ensure that +<var>match_parent</var>, is a better approach, because it helps ensure that your application will display properly across a variety of device screen sizes. The accepted measurement types are defined in the <a href="{@docRoot}guide/topics/resources/available-resources.html#dimension"> @@ -236,17 +236,17 @@ Available Resources</a> document.</p> two dimensions, expressed as a width and a height. The unit for location and dimensions is the pixel. </p> - + <p> It is possible to retrieve the location of a view by invoking the methods {@link android.view.View#getLeft()} and {@link android.view.View#getTop()}. The former returns the left, or X, coordinate of the rectangle representing the view. The latter returns the top, or Y, coordinate of the rectangle representing the view. These methods both return the location of the view relative to its parent. For instance, - when getLeft() returns 20, that means the view is located 20 pixels to the + when <code>getLeft()</code> returns 20, that means the view is located 20 pixels to the right of the left edge of its direct parent. </p> - + <p> In addition, several convenience methods are offered to avoid unnecessary computations, namely {@link android.view.View#getRight()} and {@link android.view.View#getBottom()}. @@ -254,14 +254,14 @@ Available Resources</a> document.</p> rectangle representing the view. For instance, calling {@link android.view.View#getRight()} is similar to the following computation: <code>getLeft() + getWidth()</code>. </p> - + <h2 id="SizePaddingMargins">Size, Padding and Margins</h2> <p> The size of a view is expressed with a width and a height. A view actually possess two pairs of width and height values. </p> - + <p> The first pair is known as <em>measured width</em> and <em>measured height</em>. These dimensions define how big a view wants to be @@ -269,27 +269,27 @@ Available Resources</a> document.</p> measured dimensions can be obtained by calling {@link android.view.View#getMeasuredWidth()} and {@link android.view.View#getMeasuredHeight()}. </p> - + <p> The second pair is simply known as <em>width</em> and <em>height</em>, or sometimes <em>drawing width</em> and <em>drawing height</em>. These dimensions define the actual size of the view on screen, at drawing time and after layout. These values may, but do not have to, be different from the measured width and height. The width and height can be obtained by calling - {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. + {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. </p> - + <p> To measure its dimensions, a view takes into account its padding. The padding is expressed in pixels for the left, top, right and bottom parts of the view. - Padding can be used to offset the content of the view by a specific amount of + Padding can be used to offset the content of the view by a specific number of pixels. For instance, a left padding of 2 will push the view's content by 2 pixels to the right of the left edge. Padding can be set using the {@link android.view.View#setPadding(int, int, int, int)} method and queried by calling {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, - {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. + {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. </p> - + <p> Even though a view can define a padding, it does not provide any support for margins. However, view groups provide such a support. Refer to @@ -297,13 +297,13 @@ Available Resources</a> document.</p> {@link android.view.ViewGroup.MarginLayoutParams} for further information. </p> - <p>For more information about dimensions, see + <p>For more information about dimensions, see <a href="{@docRoot}guide/topics/resources/more-resources.html#Dimension">Dimension Values</a>. </p> - - - + + + <style type="text/css"> @@ -332,7 +332,7 @@ layout to acheive your UI design, you should strive to keep your layout hierarch possible. Your layout draws faster if it has fewer nested layouts (a wide view hierarchy is better than a deep view hierarchy).</p> -<!-- +<!-- <h2 id="framelayout">FrameLayout</h2> <p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout object. It's basically a blank space on your screen that you can @@ -375,7 +375,7 @@ alt="" /></a> <p>When the content for your layout is dynamic or not pre-determined, you can use a layout that subclasses {@link android.widget.AdapterView} to populate the layout with views at runtime. A subclass of the {@link android.widget.AdapterView} class uses an {@link android.widget.Adapter} to -bind data to its layout. The {@link android.widget.Adapter} behaves as a middle-man between the data +bind data to its layout. The {@link android.widget.Adapter} behaves as a middleman between the data source and the {@link android.widget.AdapterView} layout—the {@link android.widget.Adapter} retrieves the data (from a source such as an array or a database query) and converts each entry into a view that can be added into the {@link android.widget.AdapterView} layout.</p> @@ -417,7 +417,7 @@ android.widget.TextView}. android.widget.ListView}, initialize a new {@link android.widget.ArrayAdapter} using a constructor to specify the layout for each string and the string array:</p> <pre> -ArrayAdapter adapter = new ArrayAdapter<String>(this, +ArrayAdapter<String> adapter = new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myStringArray); </pre> <p>The arguments for this constructor are:</p> @@ -453,14 +453,14 @@ numbers. You then create a string array specifying which columns from the {@link android.database.Cursor} you want in the layout for each result and an integer array specifying the corresponding views that each column should be placed:</p> <pre> -String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME, +String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME, ContactsContract.CommonDataKinds.Phone.NUMBER}; int[] toViews = {R.id.display_name, R.id.phone_number}; </pre> <p>When you instantiate the {@link android.widget.SimpleCursorAdapter}, pass the layout to use for each result, the {@link android.database.Cursor} containing the results, and these two arrays:</p> <pre> -SimpleCursorAdapter adapter = new SimpleCursorAdapter(this, +SimpleCursorAdapter adapter = new SimpleCursorAdapter(this, R.layout.person_name_and_number, cursor, fromColumns, toViews, 0); ListView listView = getListView(); listView.setAdapter(adapter); @@ -490,7 +490,7 @@ private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { } }; -listView.setOnItemClickListener(mMessageClickedHandler); +listView.setOnItemClickListener(mMessageClickedHandler); </pre> diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index e989374..9a6b0e9 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -873,7 +873,7 @@ imageView.setOnDragListener(mDragListen); ... -protected class myDragEventListener implements View.OnDragEventListener { +protected class myDragEventListener implements View.OnDragListener { // This is the method that the system calls when it dispatches a drag event to the // listener. @@ -899,18 +899,15 @@ protected class myDragEventListener implements View.OnDragEventListener { v.invalidate(); // returns true to indicate that the View can accept the dragged data. - return(true); + return true; - } else { + } - // Returns false. During the current drag and drop operation, this View will - // not receive events again until ACTION_DRAG_ENDED is sent. - return(false); + // Returns false. During the current drag and drop operation, this View will + // not receive events again until ACTION_DRAG_ENDED is sent. + return false; - } - break; - - case DragEvent.ACTION_DRAG_ENTERED: { + case DragEvent.ACTION_DRAG_ENTERED: // Applies a green tint to the View. Return true; the return value is ignored. @@ -919,79 +916,70 @@ protected class myDragEventListener implements View.OnDragEventListener { // Invalidate the view to force a redraw in the new tint v.invalidate(); - return(true); - - break; + return true; - case DragEvent.ACTION_DRAG_LOCATION: + case DragEvent.ACTION_DRAG_LOCATION: // Ignore the event - return(true); - - break; - - case DragEvent.ACTION_DRAG_EXITED: - - // Re-sets the color tint to blue. Returns true; the return value is ignored. - v.setColorFilter(Color.BLUE); - - // Invalidate the view to force a redraw in the new tint - v.invalidate(); + return true; - return(true); + case DragEvent.ACTION_DRAG_EXITED: - break; - - case DragEvent.ACTION_DROP: + // Re-sets the color tint to blue. Returns true; the return value is ignored. + v.setColorFilter(Color.BLUE); - // Gets the item containing the dragged data - ClipData.Item item = event.getClipData().getItemAt(0); + // Invalidate the view to force a redraw in the new tint + v.invalidate(); - // Gets the text data from the item. - dragData = item.getText(); + return true; - // Displays a message containing the dragged data. - Toast.makeText(this, "Dragged data is " + dragData, Toast.LENGTH_LONG); + case DragEvent.ACTION_DROP: - // Turns off any color tints - v.clearColorFilter(); + // Gets the item containing the dragged data + ClipData.Item item = event.getClipData().getItemAt(0); - // Invalidates the view to force a redraw - v.invalidate(); + // Gets the text data from the item. + dragData = item.getText(); - // Returns true. DragEvent.getResult() will return true. - return(true); + // Displays a message containing the dragged data. + Toast.makeText(this, "Dragged data is " + dragData, Toast.LENGTH_LONG); - break; + // Turns off any color tints + v.clearColorFilter(); - case DragEvent.ACTION_DRAG_ENDED: + // Invalidates the view to force a redraw + v.invalidate(); - // Turns off any color tinting - v.clearColorFilter(); + // Returns true. DragEvent.getResult() will return true. + return true; - // Invalidates the view to force a redraw - v.invalidate(); + case DragEvent.ACTION_DRAG_ENDED: - // Does a getResult(), and displays what happened. - if (event.getResult()) { - Toast.makeText(this, "The drop was handled.", Toast.LENGTH_LONG); + // Turns off any color tinting + v.clearColorFilter(); - } else { - Toast.makeText(this, "The drop didn't work.", Toast.LENGTH_LONG); + // Invalidates the view to force a redraw + v.invalidate(); - }; + // Does a getResult(), and displays what happened. + if (event.getResult()) { + Toast.makeText(this, "The drop was handled.", Toast.LENGTH_LONG); - // returns true; the value is ignored. - return(true); + } else { + Toast.makeText(this, "The drop didn't work.", Toast.LENGTH_LONG); - break; + } - // An unknown action type was received. - default: - Log.e("DragDrop Example","Unknown action type received by OnDragListener."); + // returns true; the value is ignored. + return true; + // An unknown action type was received. + default: + Log.e("DragDrop Example","Unknown action type received by OnDragListener."); break; - }; - }; + } + + return false; + } }; </pre> diff --git a/docs/html/guide/topics/ui/layout/grid.jd b/docs/html/guide/topics/ui/layout/grid.jd index 52f453b..c2f1321 100644 --- a/docs/html/guide/topics/ui/layout/grid.jd +++ b/docs/html/guide/topics/ui/layout/grid.jd @@ -41,8 +41,8 @@ result, with cell borders displayed as dotted lines (added for visual effect). < <pre> <?xml version="1.0" encoding="utf-8"?> <TableLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:stretchColumns="1"> <TableRow> <TextView @@ -82,8 +82,8 @@ documentation for more details. </p> <pre> <?xml version="1.0" encoding="utf-8"?> <TableLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:stretchColumns="1"> <TableRow> diff --git a/docs/html/guide/topics/ui/layout/gridview.jd b/docs/html/guide/topics/ui/layout/gridview.jd index bc189c4..b7dd94d 100644 --- a/docs/html/guide/topics/ui/layout/gridview.jd +++ b/docs/html/guide/topics/ui/layout/gridview.jd @@ -43,10 +43,10 @@ into the project's <li>Open the <code>res/layout/main.xml</code> file and insert the following: <pre> <?xml version="1.0" encoding="utf-8"?> -<GridView xmlns:android="http://schemas.android.com/apk/res/android" +<GridView xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/gridview" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:columnWidth="90dp" android:numColumns="auto_fit" android:verticalSpacing="10dp" diff --git a/docs/html/guide/topics/ui/layout/linear.jd b/docs/html/guide/topics/ui/layout/linear.jd index 444dc71..fb55165 100644 --- a/docs/html/guide/topics/ui/layout/linear.jd +++ b/docs/html/guide/topics/ui/layout/linear.jd @@ -82,21 +82,21 @@ share the rest equally.</p> <pre> <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:paddingLeft="16dp" android:paddingRight="16dp" android:orientation="vertical" > <EditText - android:layout_width="fill_parent" + android:layout_width="match_parent" android:layout_height="wrap_content" android:hint="@string/to" /> <EditText - android:layout_width="fill_parent" + android:layout_width="match_parent" android:layout_height="wrap_content" android:hint="@string/subject" /> <EditText - android:layout_width="fill_parent" + android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" android:gravity="top" diff --git a/docs/html/guide/topics/ui/layout/relative.jd b/docs/html/guide/topics/ui/layout/relative.jd index 65c5617..145c838 100644 --- a/docs/html/guide/topics/ui/layout/relative.jd +++ b/docs/html/guide/topics/ui/layout/relative.jd @@ -82,13 +82,13 @@ view declared in the hierarchy. The example below demonstrates such a scenario.< <pre> <?xml version="1.0" encoding="utf-8"?> <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" + android:layout_width="match_parent" + android:layout_height="match_parent" android:paddingLeft="16dp" android:paddingRight="16dp" > <EditText android:id="@+id/name" - android:layout_width="fill_parent" + android:layout_width="match_parent" android:layout_height="wrap_content" android:hint="@string/reminder" /> <Spinner @@ -114,4 +114,4 @@ view declared in the hierarchy. The example below demonstrates such a scenario.< </pre> <p>For details about all the layout attributes available to each child view of a {@link -android.widget.RelativeLayout}, see {@link android.widget.RelativeLayout.LayoutParams}.</p>
\ No newline at end of file +android.widget.RelativeLayout}, see {@link android.widget.RelativeLayout.LayoutParams}.</p> |