diff options
Diffstat (limited to 'docs')
22 files changed, 1571 insertions, 13 deletions
diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd index ff34be6..dc91638 100644 --- a/docs/html/guide/topics/ui/accessibility/apps.jd +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -111,7 +111,7 @@ English language interface:</p> <p>By including the description, speech-based accessibility services can announce "Add note" when a user moves focus to this button or hovers over it.</p> -<p class="note">Note: For {@link android.widget.EditText} fields, provide an +<p class="note"><strong>Note:</strong> For {@link android.widget.EditText} fields, provide an <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">android:hint</a> attribute to help users understand what content is expected.</p> @@ -119,8 +119,10 @@ attribute to help users understand what content is expected.</p> <p>Focus navigation allows users with disabilities to step through user interface controls using a directional controller. Directional controllers can be physical, such as a clickable trackball, -directional pad (D-Pad) or arrow keys, tab key navigation with an attached keyboard or a software -application that provides an on-screen directional control.</p> +directional pad (D-pad) or arrow keys, tab key navigation with an attached keyboard or a software +application, such as the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a>, that provides an on-screen directional control.</p> <p>A directional controller is a primary means of navigation for many users. Verify that all user interface (UI) controls in your application are accessible @@ -566,5 +568,7 @@ option is not available.</p> <p>As part of your accessibility testing, you can test navigation of your application using focus, even if your test devices does not have a directional controller. The <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> provides a -simulated directional controller that you can easily use to test navigation. You can also use the -arrow keys and Enter key on your keyboard with the Emulator to simulate use of a D-pad.</p> +simulated directional controller that you can easily use to test navigation. You can also use a +software-based directional controller, such as the one provided by the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a> to simulate use of a D-pad.</p> diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 4dc915f..8af4a1c 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -194,7 +194,7 @@ contains property types that define the size and position for each child view, a appropriate for the view group. As you can see in figure 1, the parent view group defines layout parameters for each child view (including the child view group).</p> -<img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> +<img src="{@docRoot}images/layoutparams.png" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout parameters associated with each view.</p> diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index 83c8150..45c9ac9 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -51,7 +51,7 @@ as shown in the diagram below. This hierarchy tree can be as simple or complex a can build it up using Android's set of predefined widgets and layouts, or with custom Views that you create yourself.</p> -<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> +<img src="{@docRoot}images/viewgroup.png" alt="" /> <p> In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the diff --git a/docs/html/images/layoutparams.png b/docs/html/images/layoutparams.png Binary files differindex 7473dcc..d99625e 100644 --- a/docs/html/images/layoutparams.png +++ b/docs/html/images/layoutparams.png diff --git a/docs/html/images/training/firstapp/adt-firstapp-setup.png b/docs/html/images/training/firstapp/adt-firstapp-setup.png Binary files differnew file mode 100644 index 0000000..c092562 --- /dev/null +++ b/docs/html/images/training/firstapp/adt-firstapp-setup.png diff --git a/docs/html/images/training/firstapp/edittext_gravity.png b/docs/html/images/training/firstapp/edittext_gravity.png Binary files differnew file mode 100644 index 0000000..f78e676 --- /dev/null +++ b/docs/html/images/training/firstapp/edittext_gravity.png diff --git a/docs/html/images/training/firstapp/edittext_wrap.png b/docs/html/images/training/firstapp/edittext_wrap.png Binary files differnew file mode 100644 index 0000000..156776d --- /dev/null +++ b/docs/html/images/training/firstapp/edittext_wrap.png diff --git a/docs/html/images/training/firstapp/firstapp.png b/docs/html/images/training/firstapp/firstapp.png Binary files differnew file mode 100644 index 0000000..d69cd20 --- /dev/null +++ b/docs/html/images/training/firstapp/firstapp.png diff --git a/docs/html/images/viewgroup.png b/docs/html/images/viewgroup.png Binary files differindex a4c2518..2c86ddb 100644 --- a/docs/html/images/viewgroup.png +++ b/docs/html/images/viewgroup.png diff --git a/docs/html/sdk/ndk/index.jd b/docs/html/sdk/ndk/index.jd index 6f06de3..fddbcc7 100644 --- a/docs/html/sdk/ndk/index.jd +++ b/docs/html/sdk/ndk/index.jd @@ -62,7 +62,7 @@ padding: .25em 1em; <div class="toggleable open"> <a href="#" onclick="return toggleDiv(this)"><img src= "{@docRoot}assets/images/triangle-opened.png" class="toggle-img" height="9px" width="9px"> - Android NDK, Revision 7c</a> <em>(March 2012)</em> + Android NDK, Revision 7c</a> <em>(April 2012)</em> <div class="toggleme"> <p>This release of the NDK includes an important fix for Tegra2-based devices, and a few diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 3aafea9..a70b0f3 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -191,9 +191,7 @@ <span style="display:none" class="zh-TW"></span> </span> <ul> - <li><a href="<?cs var:toroot ?>sdk/ndk/index.html">Android NDK, r7c</a> - <span class="new">new!</span> - </li> + <li><a href="<?cs var:toroot ?>sdk/ndk/index.html">Android NDK, r7c</a></li> <li><a href="<?cs var:toroot ?>sdk/ndk/overview.html">What is the NDK?</a></li> </ul> </li> diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd new file mode 100644 index 0000000..847163a --- /dev/null +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -0,0 +1,363 @@ +page.title=Building a Simple User Interface +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Running Your App +previous.link=running-app.html +next.title=Starting Another Activity +next.link=starting-activity.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#LinearLayout">Use a Linear Layout</a></li> + <li><a href="#TextInput">Add a Text Input Box</a></li> + <li><a href="#Strings">Add String Resources</a></li> + <li><a href="#Button">Add a Button</a></li> + <li><a href="#Weight">Make the Input Box Fill in the Screen Width</a></li> +</ol> + + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li> +</ul> + + +</div> +</div> + + + +<p>The graphical user interface for an Android app is built using a hierarchy of {@link +android.view.View} and {@link android.view.ViewGroup} objects. {@link android.view.View} objects are +usually UI widgets such as a button or text field and {@link android.view.ViewGroup} objects are +invisible view containers that define how the child views are laid out, such as in a +grid or a vertical list.</p> + +<p>Android provides an XML vocabulary that corresponds to the subclasses of {@link +android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML with a +hierarchy of view elements.</p> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h2>Alternative Layouts</h2> + <p>Separating the UI layout into XML files is important for several reasons, +but it's especially important on Android because it allows you to define alternative layouts for +different screen sizes. For example, you can create two versions of a layout and tell +the system to use one on "small" screens and the other on "large" screens. For more information, +see the class about <a +href="{@docRoot}training/supporting-hardware/index.html">Supporting Various Hardware</a>.</p> +</div> +</div> + +<img src="{@docRoot}images/viewgroup.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> Illustration of how {@link +android.view.ViewGroup} objects form branches in the layout and contain {@link +android.view.View} objects.</p> + +<p>In this lesson, you'll create a layout in XML that includes a text input field and a +button. In the following lesson, you'll respond when the button is pressed by sending the +content of the text field to another activity.</p> + + + +<h2 id="LinearLayout">Use a Linear Layout</h2> + +<p>Open the <code>main.xml</code> file from the <code>res/layout/</code> +directory (every new Android project includes this file by default).</p> + +<p class="note"><strong>Note:</strong> In Eclipse, when you open a layout file, you’re first shown +the ADT Layout Editor. This is an editor that helps you build layouts using WYSIWYG tools. For this +lesson, you’re going to work directly with the XML, so click the <em>main.xml</em> tab at +the bottom of the screen to open the XML editor.</p> + +<p>By default, the <code>main.xml</code> file includes a layout with a {@link +android.widget.LinearLayout} root view group and a {@link android.widget.TextView} child view. +You’re going to re-use the {@link android.widget.LinearLayout} in this lesson, but change its +contents and layout orientation.</p> + +<p>First, delete the {@link android.widget.TextView} element and change the value +<a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code +android:orientation}</a> to be <code>"horizontal"</code>. The result looks like this:</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:orientation="horizontal" > +</LinearLayout> +</pre> + +<p>{@link android.widget.LinearLayout} is a view group (a subclass of {@link +android.view.ViewGroup}) that lays out child views in either a vertical or horizontal orientation, +as specified by the <a +href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code +android:orientation}</a> attribute. Each child of a {@link android.widget.LinearLayout} appears on +the screen in the order in which it appears in the XML.</p> + +<p>The other two attributes, <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code +android:layout_width}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code +android:layout_height}</a>, are required for all views in order to specify their size.</p> + +<p>Because the {@link android.widget.LinearLayout} is the root view in the layout, it should fill +the entire screen area that's +available to the app by setting the width and height to +<code>"fill_parent"</code>.</p> + +<p class="note"><strong>Note:</strong> Beginning with Android 2.2 (API level 8), +<code>"fill_parent"</code> has been renamed <code>"match_parent"</code> to better reflect the +behavior. The reason is that if you set a view to <code>"fill_parent"</code> it does not expand to +fill the remaining space after sibling views are considered, but instead expands to +<em>match</em> the size of the parent view no matter what—it will overlap any sibling +views.</p> + +<p>For more information about layout properties, see the <a +href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layout</a> guide.</p> + + + +<h2 id="TextInput">Add a Text Input Box</h2> + +<p>To create a user-editable text box, add an {@link android.widget.EditText +<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}. The {@link +android.widget.EditText} class is a subclass of {@link android.view.View} that displays an editable +text box.</p> + +<p>Like every {@link android.view.View} object, you must define certain XML attributes to specify +the {@link android.widget.EditText} object's properties. Here’s how you should declare it +inside the {@link android.widget.LinearLayout <LinearLayout>} element:</p> + +<pre> + <EditText android:id="@+id/edit_message" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> +</pre> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>About resource objects</h3> + <p>A resource object is simply a unique integer name that's associated with an app resource, +such as a bitmap, layout file, or string.</p> + <p>Every resource has a +corresponding resource object defined in your project's {@code gen/R.java} file. You can use the +object names in the {@code R} class to refer to your resources, such as when you need to specify a +string value for the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code android:hint}</a> +attribute. You can also create arbitrary resource IDs that you associate with a view using the <a +href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute, +which allows you to reference that view from other code.</p> + <p>The SDK tools generate the {@code R.java} each time you compile your app. You should never +modify this file by hand.</p> +</div> +</div> + +<p>About these attributes:</p> + +<dl> +<dt><a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a></dt> +<dd>This provides a unique identifier for the view, which you can use to reference the object +from your app code, such as to read and manipulate the object (you'll see this in the next +lesson). + +<p>The at-symbol (<code>@</code>) is required when you want to refer to a resource object from +XML, followed by the resource type ({@code id} in this case), then the resource name ({@code +edit_message}). (Other resources can use the same name as long as they are not the same +resource type—for example, the string resource uses the same name.)</p> + +<p>The plus-symbol (<code>+</code>) is needed only when you're defining a resource ID for the +first time. It tells the SDK tools that the resource ID needs to be created. Thus, when the app is +compiled, the SDK tools use the ID value, <code>edit_message</code>, to create a new identifier in +your project's {@code gen/R.java} file that is now assiciated with the {@link +android.widget.EditText} element. Once the resource ID is created, other references to the ID do not +need the plus symbol. See the sidebox for more information about resource objects.</p></dd> + +<dt><a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code +android:layout_width}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code +android:layout_height}</a></dt> +<dd>Instead of using specific sizes for the width and height, the <code>"wrap_content"</code> value +specifies that the view should be only as big as needed to fit the contents of the view. If you +were to instead use <code>"fill_parent"</code>, then the {@link android.widget.EditText} +element would fill the screen, because it'd match the size of the parent {@link +android.widget.LinearLayout}. For more information, see the <a +href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a> guide.</dd> + +<dt><a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code +android:hint}</a></dt> +<dd>This is a default string to display when the text box is empty. Instead of using a hard-coded +string as the value, the value given in this example refers to a string resource. When you add the +{@code +"@string/edit_message"} value, you’ll see a compiler error because there’s no matching string +resource by that name. You'll fix this in the next section by defining the string +resource.</dd> +</dl> + + + +<h2 id="Strings">Add String Resources</h2> + +<p>When you need to add text in the user interface, you should always specify each string of text in +a resource file. String resources allow you to maintain a single location for all string +values, which makes it easier to find and update text. Externalizing the strings also allows you to +localize your app to different languages by providing alternative definitions for each +string.</p> + +<p>By default, your Android project includes a string resource file at +<code>res/values/strings.xml</code>. Open this file, delete the existing <code>"hello"</code> +string, and add one for the +<code>"edit_message"</code> string used by the {@link android.widget.EditText <EditText>} +element.</p> + +<p>While you’re in this file, also add a string for the button you’ll soon add, called +<code>"button_send"</code>.</p> + +<p>The result for <code>strings.xml</code> looks like this:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="app_name">My First App</string> + <string name="edit_message">Enter a message</string> + <string name="button_send">Send</string> +</resources> +</pre> + +<p>For more information about using string resources to localize your app for several languages, +see the <a +href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Various Devices</a> +class.</p> + + + + +<h2 id="Button">Add a Button</h2> + +<p>Now add a {@link android.widget.Button <Button>} to the layout, immediately following the +{@link android.widget.EditText <EditText>} element:</p> + +<pre> + <Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" /> +</pre> + +<p>The height and width are set to <code>"wrap_content"</code> so the button is only as big as +necessary to fit the button's text.</p> + + + +<h2 id="Weight">Make the Input Box Fill in the Screen Width</h2> + +<p>The layout is currently designed so that both the {@link android.widget.EditText} and {@link +android.widget.Button} widgets are only as big as necessary to fit their content, as shown in +figure 2.</p> + +<img src="{@docRoot}images/training/firstapp/edittext_wrap.png" /> +<p class="img-caption"><strong>Figure 2.</strong> The {@link android.widget.EditText} and {@link +android.widget.Button} widgets have their widths set to +<code>"wrap_content"</code>.</p> + +<p>This works fine for the button, but not as well for the text box, because the user might type +something longer and there's extra space left on the screen. So, it'd be nice to fill that width +using the text box. +{@link android.widget.LinearLayout} enables such a design with the <em>weight</em> property, which +you can specify using the <a +href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#weight">{@code +android:layout_weight}</a> attribute.</p> + +<p>The weight value allows you to specify the amount of remaining space each view should consume, +relative to the amount consumed by sibling views, just like the ingredients in a drink recipe: "2 +parts vodka, 1 part coffee liquer" means two-thirds of the drink is vodka. For example, if you give +one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view gets 2/3 of +the remaining space and the second view gets the rest. If you give a third view a weight of 1, +then the first view now gets 1/2 the remaining space, while the remaining two each get 1/4.</p> + +<p>The default weight for all views is 0, so if you specify any weight value +greater than 0 to only one view, then that view fills whatever space remains after each view is +given the space it requires. So, to fill the remaining space with the {@link +android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.</p> + +<pre> + <EditText + android:layout_weight="1" + ... /> +</pre> + +<p>In order to improve the layout efficiency when you specify the weight, you should change the +width of the {@link android.widget.EditText} to be +zero (0dp). Setting the width to zero improves layout performance because using +<code>"wrap_content"</code> as the width requires the system to calculate a width that is +ultimately irrelevant because the weight value requires another width calculation to fill the +remaining space.</p> +<pre> + <EditText + android:layout_weight="1" + android:layout_width="0dp" + ... /> +</pre> + +<p>Figure 3 +shows the result when you assign all weight to the {@link android.widget.EditText} element.</p> + +<img src="{@docRoot}images/training/firstapp/edittext_gravity.png" /> +<p class="img-caption"><strong>Figure 3.</strong> The {@link android.widget.EditText} widget is +given all the layout weight, so fills the remaining space in the {@link +android.widget.LinearLayout}.</p> + +<p>Here’s how your complete layout file should now look:</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:orientation="horizontal"> + <EditText android:id="@+id/edit_message" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> + <Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" /> +</LinearLayout> +</pre> + +<p>This layout is applied by the default {@link android.app.Activity} class +that the SDK tools generated when you created the project, so you can now run the app to see the +results:</p> + +<ul> + <li>In Eclipse, click <strong>Run</strong> from the toolbar.</li> + <li>Or from a command line, change directories to the root of your Android project and +execute: +<pre> +ant debug +adb install bin/MyFirstApp-debug.apk +</pre></li> +</ul> + +<p>Continue to the next lesson to learn how you can respond to button presses, read content +from the text field, start another activity, and more.</p> + + + diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd new file mode 100644 index 0000000..5a89f2e --- /dev/null +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -0,0 +1,142 @@ +page.title=Creating an Android Project +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +next.title=Running Your App +next.link=running-app.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#Eclipse">Create a Project with Eclipse</a></li> + <li><a href="#CommandLine">Create a Project with Command Line Tools</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}sdk/installing.html">Installing the +SDK</a></li> + <li><a href="{@docRoot}guide/developing/projects/index.html">Managing Projects</a></li> +</ul> + + +</div> +</div> + +<p>An Android project contains all the files that comprise the source code for your Android +app. The Android SDK tools make it easy to start a new Android project with a set of +default project directories and files.</p> + +<p>This lesson +shows how to create a new project either using Eclipse (with the ADT plugin) or using the +SDK tools from a command line.</p> + +<p class="note"><strong>Note:</strong> You should already have the Android SDK installed, and if +you're using Eclipse, you should have installed the <a +href="{@docRoot}sdk/eclipse-adt.html">ADT plugin</a> as well. If you have not installed +these, see <a href="{@docRoot}sdk/installing.html">Installing the Android SDK</a> and return here +when you've completed the installation.</p> + + +<h2 id="Eclipse">Create a Project with Eclipse</h2> + +<div class="figure" style="width:416px"> +<img src="{@docRoot}images/training/firstapp/adt-firstapp-setup.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The new project wizard in Eclipse.</p> +</div> + +<ol> + <li>In Eclipse, select <strong>File > New > Project</strong>. +The resulting dialog should have a folder labeled <em>Android</em>. (If you don’t see the +<em>Android</em> folder, +then you have not installed the ADT plugin—see <a +href="{@docRoot}sdk/eclipse-adt.html#installing">Installing the ADT Plugin</a>).</li> + <li>Open the <em>Android</em> folder, select <em>Android Project</em> and click +<strong>Next</strong>.</li> + <li>Enter a project name (such as "MyFirstApp") and click <strong>Next</strong>.</li> + <li>Select a build target. This is the platform version against which you will compile your app. +<p>We recommend that you select the latest version possible. You can still build your app to +support older versions, but setting the build target to the latest version allows you to +easily optimize your app for a great user experience on the latest Android-powered devices.</p> +<p>If you don't see any built targets listed, you need to install some using the Android SDK +Manager tool. See <a href="{@docRoot}sdk/installing.html#AddingComponents">step 4 in the +installing guide</a>.</p> +<p>Click <strong>Next</strong>.</p></li> + <li>Specify other app details, such as the: + <ul> + <li><em>Application Name</em>: The app name that appears to the user. Enter "My First +App".</li> + <li><em>Package Name</em>: The package namespace for your app (following the same +rules as packages in the Java programming language). Your package name +must be unique across all packages installed on the Android system. For this reason, it's important +that you use a standard domain-style package name that’s appropriate to your company or +publisher entity. For +your first app, you can use something like "com.example.myapp." However, you cannot publish your +app using the "com.example" namespace.</li> + <li><em>Create Activity</em>: This is the class name for the primary user activity in your +app (an activity represents a single screen in your app). Enter "MyFirstActivity".</li> + <li><em>Minimum SDK</em>: Select <em>4 (Android 1.6)</em>. + <p>Because this version is lower than the build target selected for the app, a warning +appears, but that's alright. You simply need to be sure that you don't use any APIs that require an +<a href="{@docRoot}guide/appendix/api-levels.html">API level</a> greater than the minimum SDK +version without first using some code to verify the device's system version (you'll see this in some +other classes).</p> + </li> + </ul> + <p>Click <strong>Finish</strong>.</p> + </li> +</ol> + +<p>Your Android project is now set up with some default files and you’re ready to begin +building the app. Continue to the <a href="running-app.html">next lesson</a>.</p> + + + +<h2 id="CommandLine">Create a Project with Command Line Tools</h2> + +<p>If you're not using the Eclipse IDE with the ADT plugin, you can instead create your project +using the SDK tools in a command line:</p> + +<ol> + <li>Change directories into the Android SDK’s <code>tools/</code> path.</li> + <li>Execute: +<pre class="no-pretty-print">android list targets</pre> +<p>This prints a list of the available Android platforms that you’ve downloaded for your SDK. Find +the platform against which you want to compile your app. Make a note of the target id. We +recommend that you select the highest version possible. You can still build your app to +support older versions, but setting the build target to the latest version allows you to optimize +your app for the latest devices.</p> +<p>If you don't see any targets listed, you need to +install some using the Android SDK +Manager tool. See <a href="{@docRoot}sdk/installing.html#AddingComponents">step 4 in the +installing guide</a>.</p></li> + <li>Execute: +<pre class="no-pretty-print"> +android create project --target <target-id> --name MyFirstApp \ +--path <path-to-workspace>/MyFirstApp --activity MyFirstActivity \ +--package com.example.myapp +</pre> +<p>Replace <code><target-id></code> with an id from the list of targets (from the previous step) +and replace +<code><path-to-workspace></code> with the location in which you want to save your Android +projects.</p></li> +</ol> + +<p>Your Android project is now set up with several default configurations and you’re ready to begin +building the app. Continue to the <a href="running-app.html">next lesson</a>.</p> + +<p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the +<code>tools/</code> directory to your <code>PATH</code> environment variable.</p> + + + + diff --git a/docs/html/training/basics/firstapp/index.jd b/docs/html/training/basics/firstapp/index.jd new file mode 100644 index 0000000..a95ed8e --- /dev/null +++ b/docs/html/training/basics/firstapp/index.jd @@ -0,0 +1,64 @@ +page.title=Building Your First App + +trainingnavtop=true +startpage=true +next.title=Creating an Android Project +next.link=creating-project.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> + +<ul> + <li>Android 1.6 or higher</li> + <li><a href="http://developer.android.com/sdk/index.html">Android SDK</a></li> +</ul> + +</div> +</div> + +<p>Welcome to Android application development!</p> + +<p>This class teaches you how to build your first Android app. You’ll learn how to create an Android +project and run a debuggable version of the app. You'll also learn some fundamentals of Android app +design, including how to build a simple user interface and handle user input.</p> + +<p>Before you start this class, be sure that you have your development environment set up. You need +to:</p> +<ol> + <li>Download the Android SDK Starter Package.</li> + <li>Install the ADT plugin for Eclipse (if you’ll use the Eclipse IDE).</li> + <li>Download the latest SDK tools and platforms using the SDK Manager.</li> +</ol> + +<p>If you haven't already done this setup, read <a href="{@docRoot}sdk/installing.html">Installing +the SDK</a>. Once you've finished the setup, you're ready to begin this class.</p> + +<p>This class uses a tutorial format that incrementally builds a small Android app in order to teach +you some fundamental concepts about Android development, so it's important that you follow each +step.</p> + +<p><strong><a href="creating-project.html">Start the first lesson ›</a></strong></p> + + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="creating-project.html">Creating an Android Project</a></b></dt> + <dd>Shows how to create a project for an Android app, which includes a set of default +app files.</dd> + + <dt><b><a href="running-app.html">Running Your Application</a></b></dt> + <dd>Shows how to run your app on an Android-powered device or the Android +emulator.</dd> + + <dt><b><a href="building-ui.html">Building a Simple User Interface</a></b></dt> + <dd>Shows how to create a new user interface using an XML file.</dd> + + <dt><b><a href="starting-activity.html">Starting Another Activity</a></b></dt> + <dd>Shows how to respond to a button press, start another activity, send it some +data, then receive the data in the subsequent activity.</dd> +</dl> diff --git a/docs/html/training/basics/firstapp/running-app.jd b/docs/html/training/basics/firstapp/running-app.jd new file mode 100644 index 0000000..2398fa0 --- /dev/null +++ b/docs/html/training/basics/firstapp/running-app.jd @@ -0,0 +1,178 @@ +page.title=Running Your App +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Creating a Project +previous.link=creating-project.html +next.title=Building a Simple User Interface +next.link=building-ui.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#RealDevice">Run on a Real Device</a></li> + <li><a href="#Emulator">Run on the Emulator</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a></li> + <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li> + <li><a href="{@docRoot}guide/developing/projects/index.html">Managing Projects</a></li> +</ul> + + +</div> +</div> + + +<p>If you followed the <a href="{@docRoot}creating-project.html">previous lesson</a> to create an +Android project, it includes a default set of "Hello World" source files that allow you to +run the app right away.</p> + +<p>How you run your app depends on two things: whether you have a real Android-powered device and +whether you’re using Eclipse. This lesson shows you how to install and run your app on a +real device and on the Android emulator, and in both cases with either Eclipse or the command line +tools.</p> + +<p>Before you run your app, you should be aware of a few directories and files in the Android +project:</p> + +<dl> + <dt><code>AndroidManifest.xml</code></dt> + <dd>This manifest file describes the fundamental characteristics of the app and defines each of +its components. You'll learn about various declarations in this file as you read more training +classes.</dd> + <dt><code>src/</code></dt> + <dd>Directory for your app's main source files. By default, it includes an {@link +android.app.Activity} class that runs when your app is launched using the app icon.</dd> + <dt><code>res/</code></dt> + <dd>Contains several sub-directories for app resources. Here are just a few: + <dl style="margin-top:1em"> + <dt><code>drawable-hdpi/</code></dt> + <dd>Directory for drawable objects (such as bitmaps) that are designed for high-density +(hdpi) screens. Other drawable directories contain assets designed for other screen densities.</dd> + <dt><code>layout/</code></dt> + <dd>Directory for files that define your app's user interface.</dd> + <dt><code>values/</code></dt> + <dd>Directory for other various XML files that contain a collection of resources, such as +string and color definitions.</dd> + </dl> + </dd> +</dl> + +<p>When you build and run the default Android project, the default {@link android.app.Activity} +class in the <code>src/</code> directory starts and loads a layout file from the +<code>layout/</code> directory, which includes a "Hello World" message. Not real exciting, but it's +important that you understand how to build and run your app before adding real functionality to +the app.</p> + + + +<h2 id="RealDevice">Run on a Real Device</h2> + +<p>Whether you’re using Eclipse or the command line, you need to:</p> + +<ol> + <li>Plug in your Android-powered device to your machine with a USB cable. +If you’re developing on Windows, you might need to install the appropriate USB driver for your +device. For help installing drivers, see the <a href=”{@docRoot}sdk/oem-usb.html”>OEM USB +Drivers</a> document.</li> + <li>Ensure that <strong>USB debugging</strong> is enabled in the device Settings (open Settings +and navitage to <strong>Applications > Development</strong> on most devices, or select +<strong>Developer options</strong> on Android 4.0 and higher).</li> +</ol> + +<p>To run the app from Eclipse, open one of your project's files and click +<strong>Run</strong> from the toolbar. Eclipse installs the app on your connected device and starts +it.</p> + + +<p>Or to run your app from a command line:</p> + +<ol> + <li>Change directories to the root of your Android project and execute: +<pre class="no-pretty-print">ant debug</pre></li> + <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your +<code>PATH</code> environment variable, then execute: +<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> + <li>On your device, locate <em>MyFirstActivity</em> and open it.</li> +</ol> + +<p>To start adding stuff to the app, continue to the <a href="building-ui.html">next +lesson</a>.</p> + + + +<h2 id="Emulator">Run on the Emulator</h2> + +<p>Whether you’re using Eclipse or the command line, you need to first create an <a +href="{@docRoot}guide/developing/devices/index.html">Android Virtual +Device</a> (AVD). An AVD is a +device configuration for the Android emulator that allows you to model +different device configurations.</p> + +<div class="figure" style="width:457px"> + <img src="{@docRoot}images/screens_support/avds-config.png" alt="" /> + <p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a few virtual +devices.</p> +</div> + +<p>To create an AVD:</p> +<ol> + <li>Launch the Android Virtual Device Manager: + <ol type="a"> + <li>In Eclipse, select <strong>Window > AVD Manager</strong>, or click the <em>AVD +Manager</em> icon in the Eclipse toolbar.</li> + <li>From the command line, change directories to <code><sdk>/tools/</code> and execute: +<pre class="no-pretty-print">./android avd</pre></li> + </ol> + </li> + <li>In the <em>Android Virtual Device Device Manager</em> panel, click <strong>New</strong>.</li> + <li>Fill in the details for the AVD. +Give it a name, a platform target, an SD card size, and a skin (HVGA is default).</li> + <li>Click <strong>Create AVD</strong>.</li> + <li>Select the new AVD from the <em>Android Virtual Device Manager</em> and click +<strong>Start</strong>.</li> + <li>After the emulator boots up, unlock the emulator screen.</li> +</ol> + +<p>To run the app from Eclipse, open one of your project's files and click +<strong>Run</strong> from the toolbar. Eclipse installs the app on your AVD and starts it.</p> + + +<p>Or to run your app from the command line:</p> + +<ol> + <li>Change directories to the root of your Android project and execute: +<pre class="no-pretty-print">ant debug</pre></li> + <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your +<code>PATH</code> environment +variable, then execute: +<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> + <li>On the emulator, locate <em>MyFirstActivity</em> and open it.</li> +</ol> + + +<p>To start adding stuff to the app, continue to the <a href="building-ui.html">next +lesson</a>.</p> + + + + + + + + + + + diff --git a/docs/html/training/basics/firstapp/starting-activity.jd b/docs/html/training/basics/firstapp/starting-activity.jd new file mode 100644 index 0000000..16a6fd8 --- /dev/null +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -0,0 +1,308 @@ +page.title=Starting Another Activity +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Building a Simpler User Interface +previous.link=building-ui.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#RespondToButton">Respond to the Send Button</a></li> + <li><a href="#BuildIntent">Build an Intent</a></li> + <li><a href="#StartActivity">Start the Second Activity</a></li> + <li><a href="#CreateActivity">Create the Second Activity</a> + <ol> + <li><a href="#AddToManifest">Add it to the manifest</a></li> + </ol> + </li> + <li><a href="#ReceiveIntent">Receive the Intent</a></li> + <li><a href="#DisplayMessage">Display the Message</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}sdk/installing.html">Installing the +SDK</a></li> +</ul> + + +</div> +</div> + + + +<p>After completing the <a href="building-ui.html">previous lesson</a>, you have an app that +shows an activity (a single screen) with a text box and a button. In this lesson, you’ll add some +code to <code>MyFirstActivity</code> that +starts a new activity when the user selects the Send button.</p> + + +<h2 id="RespondToButton">Respond to the Send Button</h2> + +<p>To respond to the button's on-click event, open the <code>main.xml</code> layout file and add the +<a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick}</a> +attribute to the {@link android.widget.Button <Button>} element:</p> + +<pre> +<Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" /> +</pre> + +<p>The <a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code +android:onClick}</a> attribute’s value, <code>sendMessage</code>, is the name of a method in your +activity that you want to call when the user selects the button.</p> + +<p>Add the corresponding method inside the <code>MyFirstActivity</code> class:</p> + +<pre> +/** Called when the user selects the Send button */ +public void sendMessage(View view) { + // Do something in response to button +} +</pre> + +<p class="note"><strong>Tip:</strong> In Eclipse, press Ctrl + Shift + O to import missing classes +(Cmd + Shift + O on Mac).</p> + +<p>Note that, in order for the system to match this method to the method name given to <a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick}</a>, +the signature must be exactly as shown. Specifically, the method must:</p> + +<ul> +<li>Be public</li> +<li>Have a void return value</li> +<li>Have a {@link android.view.View} as the only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + +<p>Next, you’ll fill in this method to read the contents of the text box and deliver that text to +another activity.</p> + + + +<h2 id="BuildIntent">Build an Intent</h2> + +<p>An {@link android.content.Intent} is an object that provides runtime binding between separate +components (such as two activities). The {@link android.content.Intent} represents an +app’s "intent to do something." You can use an {@link android.content.Intent} for a wide +variety of tasks, but most often they’re used to start another activity.</p> + +<p>Inside the {@code sendMessage()} method, create an {@link android.content.Intent} to start +an activity called {@code DisplayMessageActvity}:</p> + +<pre> +Intent intent = new Intent(this, DisplayMessageActivity.class); +</pre> + +<p>The constructor used here takes two parameters:</p> +<ul> + <li>A {@link +android.content.Context} as its first parameter ({@code this} is used because the {@link +android.app.Activity} class is a subclass of {@link android.content.Context}) + <li>The {@link java.lang.Class} of the app component to which the system should deliver +the {@link android.content.Intent} (in this case, the activity that should be started) +</ul> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Sending an intent to other apps</h3> + <p>The intent created in this lesson is what's considered an <em>explicit intent</em>, because the +{@link android.content.Intent} +specifies the exact app component to which the intent should be given. However, intents +can also be <em>implicit</em>, in which case the {@link android.content.Intent} does not specify +the desired component, but allows any app installed on the device to respond to the intent +as long as it satisfies the meta-data specifications for the action that's specified in various +{@link android.content.Intent} parameters. For more informations, see the class about <a +href="{@docRoot}training/intents/index.html">Interacting with Other Apps</a>.</p> +</div> +</div> + +<p class="note"><strong>Note:</strong> The reference to {@code DisplayMessageActivity} +will raise an error if you’re using an IDE such as Eclipse because the class doesn’t exist yet. +Ignore the error for now; you’ll create the class soon.</p> + +<p>An intent not only allows you to start another activity, but can carry a bundle of data to the +activity as well. So, use {@link android.app.Activity#findViewById findViewById()} to get the +{@link android.widget.EditText} element and add its message to the intent:</p> + +<pre> +Intent intent = new Intent(this, DisplayMessageActivity.class); +EditText editText = (EditText) findViewById(R.id.edit_message); +String message = editText.getText().toString(); +intent.putExtra(EXTRA_MESSAGE, message); +</pre> + +<p>An {@link android.content.Intent} can carry a collection of various data types as key-value +pairs called <em>extras</em>. The {@link android.content.Intent#putExtra putExtra()} method takes a +string as the key and the value in the second parameter.</p> + +<p>In order for the next activity to query the extra data, you should define your keys using a +public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code +MyFirstActivity} class:</p> + +<pre> +public class MyFirstActivity extends Activity { + public final static String EXTRA_MESSAGE = "com.example.myapp.MESSAGE"; + ... +} +</pre> + +<p>It's generally a good practice to define keys for extras with your app's package name as a prefix +to ensure it's unique, in case your app interacts with other apps.</p> + + +<h2 id="StartActivity">Start the Second Activity</h2> + +<p>To start an activity, you simply need to call {@link android.app.Activity#startActivity +startActivity()} and pass it your {@link android.content.Intent}.</p> + +<p>The system receives this call and starts an instance of the {@link android.app.Activity} +specified by the {@link android.content.Intent}.</p> + +<p>With this method included, the complete {@code sendMessage()} method that's invoked by the Send +button now looks like this:</p> + +<pre> +/** Called when the user selects the Send button */ +public void sendMessage(View view) { + Intent intent = new Intent(this, DisplayMessageActivity.class); + EditText editText = (EditText) findViewById(R.id.edit_message); + String message = editText.getText().toString(); + intent.putExtra(EXTRA_MESSAGE, message); + startActivity(intent); +} +</pre> + +<p>Now you need to create the {@code DisplayMessageActivity} class in order for this to +work.</p> + + + +<h2 id="CreateActivity">Create the Second Activity</h2> + +<p>In your project, create a new class file under the <code>src/<package-name>/</code> +directory called <code>DisplayMessageActivity.java</code>.</p> + +<p class="note"><strong>Tip:</strong> In Eclipse, right-click the package name under the +<code>src/</code> directory and select <strong>New > Class</strong>. +Enter "DisplayMessageActivity" for the name and {@code android.app.Activity} for the superclass.</p> + +<p>Inside the class, add the {@link android.app.Activity#onCreate onCreate()} callback method:</p> + +<pre> +public class DisplayMessageActivity extends Activity { + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + } +} +</pre> + +<p>All subclasses of {@link android.app.Activity} must implement the {@link +android.app.Activity#onCreate onCreate()} method. The system calls this when creating a new +instance of the activity. It is where you must define the activity layout and where you should +initialize essential activity components.</p> + + + +<h3 id="AddToManifest">Add it to the manifest</h3> + +<p>You must declare all activities in your manifest file, <code>AndroidManifest.xml</code>, using an +<a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element.</p> + +<p>Because {@code DisplayMessageActivity} is invoked using an explicit intent, it does not require +any intent filters (such as those you can see in the manifest for <code>MyFirstActivity</code>). So +the declaration for <code>DisplayMessageActivity</code> can be simply one line of code inside the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element:</p> + +<pre> +<application ... > + <activity android:name="com.example.myapp.DisplayMessageActivity" /> + ... +</application> +</pre> + +<p>The app is now runnable because the {@link android.content.Intent} in the +first activity now resolves to the {@code DisplayMessageActivity} class. If you run the app now, +pressing the Send button starts the +second activity, but it doesn't show anything yet.</p> + + +<h2 id="ReceiveIntent">Receive the Intent</h2> + +<p>Every {@link android.app.Activity} is invoked by an {@link android.content.Intent}, regardless of +how the user navigated there. You can get the {@link android.content.Intent} that started your +activity by calling {@link android.app.Activity#getIntent()} and the retrieve data contained +within it.</p> + +<p>In the {@code DisplayMessageActivity} class’s {@link android.app.Activity#onCreate onCreate()} +method, get the intent and extract the message delivered by {@code MyFirstActivity}:</p> + +<pre> +Intent intent = getIntent(); +String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE); +</pre> + + + +<h2 id="DisplayMessage">Display the Message</h2> + +<p>To show the message on the screen, create a {@link android.widget.TextView} widget and set the +text using {@link android.widget.TextView#setText setText()}. Then add the {@link +android.widget.TextView} as the root view of the activity’s layout by passing it to {@link +android.app.Activity#setContentView setContentView()}.</p> + +<p>The complete {@link android.app.Activity#onCreate onCreate()} method for {@code +DisplayMessageActivity} now looks like this:</p> + +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + // Get the message from the intent + Intent intent = getIntent(); + String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE); + + // Create the text view + TextView textView = new TextView(this); + textView.setTextSize(40); + textView.setText(message); + + setContentView(textView); +} +</pre> + +<p>You can now run the app, type a message in the text box, press Send, and view the message on the +second activity.</p> + +<img src="{@docRoot}images/training/firstapp/firstapp.png" /> +<p class="img-caption"><strong>Figure 1.</strong> Both activities in the final app, running +on Android 4.0. + +<p>That's it, you've built your first Android app!</p> + +<p>To learn more about building Android apps, continue to follow the +basic training classes. The next class is <a +href="{@docRoot}training/activity-lifecycle/index.html">Managing the Activity Lifecycle</a>.</p> + + + + diff --git a/docs/html/training/basics/supporting-devices/index.jd b/docs/html/training/basics/supporting-devices/index.jd new file mode 100644 index 0000000..49ea81d --- /dev/null +++ b/docs/html/training/basics/supporting-devices/index.jd @@ -0,0 +1,49 @@ +page.title=Supporting Different Devices + +trainingnavtop=true +startpage=true +next.title=Supporting Multiple Languages +next.link=languages.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 1.6 or higher</li> +</ul> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a></li> + <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li> +</ul> + + +</div> +</div> + +<p>Android devices come in many shapes and sizes all around the world. With a wide range of device +types, you have an opportunity to reach a huge audience with your app. In order to be as successful +as possible on Android, your app needs to adapt to various device configurations. Some of the +important variations that you should consider include different languages, screen sizes, and +versions of the Android platform.</p> + +<p>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> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="languages.html">Supporting Different Languages</a></b></dt> + <dd>Learn how to support multiple languages with alternative string resources.</dd> + <dt><b><a href="screens.html">Supporting Different Screens</a></b></dt> + <dd>Learn how to optimize the user experience for different screen sizes and densities.</dd> + <dt><b><a href="platforms.html">Supporting Different Platform Versions</a></b></dt> + <dd>Learn how to use APIs available in new versions of Android while continuing to support +older versions of Android.</dd> +</dl> + diff --git a/docs/html/training/basics/supporting-devices/languages.jd b/docs/html/training/basics/supporting-devices/languages.jd new file mode 100644 index 0000000..fcc95c2 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/languages.jd @@ -0,0 +1,134 @@ +page.title=Supporting Different Languages +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +next.title=Supporting Different Screens +next.link=screens.html + +@jd:body + + +<div id="tb-wrapper"> + <div id="tb"> + <h2>This class teaches you to</h2> + <ol> + <li><a href="#CreateDirs">Create Locale Directories and String Files</a></li> + <li><a href="#UseString">Use the String Resources</a></li> + </ol> + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/topics/resources/localization.html">Localization</a></li> + </ul> + </div> +</div> + +<p>It’s always a good practice to extract UI strings from your app code and keep them +in an external file. Android makes this easy with a resources directory in each Android +project.</p> + +<p>If you created your project using the Android SDK +Tools (read <a href="{@docRoot}training/basics/firstapp/creating-project.html">Creating an +Android Project</a>), the tools create a <code>res/</code> directory in the top level of +the project. Within this <code>res/</code> directory are subdirectories for various resource +types. There are also a few default files such as <code>res/values/strings.xml</code>, which holds +your string values.</p> + + +<h2 id="CreateDirs">Create Locale Directories and String Files</h2> + +<p>To add support for more languages, create additional <code>values</code> directories inside +<code>res/</code> that include a hyphen and the ISO country code at the end of the +directory name. For example, <code>values-es/</code> is the directory containing simple +resourcess for the Locales with the language code "es". Android loads the appropriate resources +according to the locale settings of the device at run time.</p> + +<p>Once you’ve decided on the languages you will support, create the resource subdirectories and +string resource files. For example:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + values/ + strings.xml + values-es/ + strings.xml + values-fr/ + strings.xml +</pre> + +<p>Add the string values for each locale into the appropriate file.</p> + +<p>At runtime, the Android system uses the appropriate set of string resources based on the +locale currently set for the user's device.</p> + +<p>For example, the following are some different string resource files for different languages.</p> + + +<p>English (default locale), <code>/values/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">My Application</string> + <string name="hello_world">Hello World!</string> +</resources> +</pre> + + +<p>Spanish, <code>/values-es/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">Mi Aplicación</string> + <string name="hello_world">Hola Mundo!</string> +</resources> +</pre> + + +<p>French, <code>/values-fr/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">Ma Application</string> + <string name="hello_world">Bonjour tout le Monde!</string> +</resources> +</pre> + + +<h2 id="UseString">Use the String Resources</h2> + +<p>You can reference your string resources in your source code and other XML files using the +resource name defined by the {@code <string>} element's {@code name} attribute.</p> + +<p>In your source code, you can refer to a string resource with the syntax {@code +R.string.<string_name>}. There are a variety of methods that accept a string resource this +way.</p> + +<p>For example:</p> + +<pre> +// Get a string resource from your app's {@link android.content.res.Resources} +String hello = {@link android.content.Context#getResources()}.getString(R.string.hello_world); + +// Or supply a string resource to a method that requires a string +TextView textView = new TextView(this); +textView.setText(R.string.hello_world); +</pre> + +<p>In other XML files, you can refer to a string resource with the syntax {@code +@string/<string_name>} whenever the XML attribute accepts a string value.</p> + +<p>For example:</p> + +<pre> +<TextView + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/hello_world" /> +</pre> + + + diff --git a/docs/html/training/basics/supporting-devices/platforms.jd b/docs/html/training/basics/supporting-devices/platforms.jd new file mode 100644 index 0000000..0d4e7d9 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/platforms.jd @@ -0,0 +1,138 @@ +page.title=Supporting Different Platform Versions +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +previous.title=Supporting Different Screens +previous.link=screens.html + +@jd:body + + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#sdk-versions">Specify Minimum and Target API Levels</a></li> + <li><a href="#version-codes">Check System Version at Runtime</a></li> + <li><a href="#style-themes">Use Platform Styles and Themes</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a></li> + <li><a +href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a></li> + </ul> + </div> +</div> + +<p>While the latest versions of Android often provide great APIs for your app, you should continue +to support older versions of Android until more devices get updated. This +lesson shows you how to take advantage of the latest APIs while continuing to support older +versions as well.</p> + +<p>The dashboard for <a +href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions</a> +is updated regularly to show the distribution of active +devices running each version of Android, based on the number of devices that visit the Google Play +Store. Generally, it’s a good practice to support about 90% of the active devices, while +targeting your app to the latest version.</p> + +<p class="note"><strong>Tip:</strong> In order to provide the best features and +functionality across several Android versions, you should use the <a +href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a> in your app, +which allows you to use several recent platform APIs on older versions.</p> + + + +<h2 id="sdk-versions">Specify Minimum and Target API Levels</h2> + +<p>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file +describes details about your app and +identifies which versions of Android it supports. Specifically, the <code>minSdkVersion</code> +and <code>targetSdkVersion</code> attributes for the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk}</a> element +identify the lowest API level with which your app is compatible and the highest API level against +which you’ve designed and tested your app.</p> + +<p>For example:</p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... > + <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" /> + ... +</manifest> +</pre> + +<p>As new versions of Android are released, some style and behaviors may change. +To allow your app to take advantage of these changes and ensure that your app fits the style of +each user's device, you should set the +<a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> +value to match the latest Android version +available.</p> + + + +<h2 id="version-codes">Check System Version at Runtime</h2> + +<p>Android provides a unique code for each platform version in the {@link android.os.Build} +constants class. Use these codes within your app to build conditions that ensure the code that +depends on higher API levels is executed only when those APIs are available on the system.</p> + +<pre> +private void setUpActionBar() { + // Make sure we're running on Honeycomb or higher to use ActionBar APIs + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + ActionBar actionBar = getActionBar(); + actionBar.setDisplayHomeAsUpEnabled(true); + } +} +</pre> + + + +<p class="note"><strong>Note:</strong> When parsing XML resources, Android ignores XML +attributes that aren’t supported by the current device. So you can safely use XML attributes that +are only supported by newer versions without worrying about older versions breaking when they +encounter that code. For example, if you set the +<code>targetSdkVersion="11"</code>, your app includes the {@link android.app.ActionBar} by default +on Android 3.0 and higher. To then add menu items to the action bar, you need to set +<code>android:showAsAction="ifRoom"</code> in your menu resource XML. It's safe to do this +in a cross-version XML file, because the older versions of Android simply ignore the +<code>showAsAction</code> attribute (that is, you <em>do not</em> need a separate +version in <code>res/menu-v11/</code>).</p> + + + +<h2 id="style-themes">Use Platform Styles and Themes</h2> + +<p>Android provides user experience themes that give apps the look and feel of the +underlying operating system. These themes can be applied to your app within the +manifest file. By using these built in styles and themes, your app will +naturally follow the latest look and feel of Android with each new release.</p> + +<p>To make your activity look like a dialog box:</p> + +<pre><activity android:theme="@android:style/Theme.Dialog"></pre> + +<p>To make your activity have a transparent background:</p> + +<pre><activity android:theme="@android:style/Theme.Translucent"></pre> + +<p>To apply your own custom theme defined in <code>/res/values/styles.xml</code>:</p> + +<pre><activity android:theme="@style/CustomTheme"></pre> + +<p>To apply a theme to your entire app (all activities), add the <code>android:theme</code> +attribute +to the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> element:</p> + +<pre><application android:theme="@style/CustomTheme"></pre> + +<p>For more about creating and using themes, read the <a +href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</p> + diff --git a/docs/html/training/basics/supporting-devices/screens.jd b/docs/html/training/basics/supporting-devices/screens.jd new file mode 100644 index 0000000..8697cd5 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/screens.jd @@ -0,0 +1,180 @@ +page.title=Supporting Different Screens +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +previous.title=Supporting Different Languages +previous.link=languages.html +next.title=Supporting Different Platform Versions +next.link=platforms.html + +@jd:body + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#create-layouts">Create Different Layouts</a></li> + <li><a href="#create-bitmaps">Create Different Bitmaps</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple +Screens</a></li> + <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a></li> + <li><a href="{@docRoot}design/style/iconography.html">Iconography design guide</a></li> + </ul> + </div> +</div> + +<p>Android categorizes device screens using two general properties: size and density. You should +expect that your app will be installed on devices with screens that range in both size +and density. As such, you should include some alternative resources that optimize your app’s +appearance for different screen sizes and densities.</p> + +<ul> + <li>There are four generalized sizes: small, normal, large, xlarge</li> + <li>And four generalized densities: low (ldpi), medium (mdpi), high (hdpi), extra high +(xhdpi)</li> +</ul> + +<p>To declare different layouts and bitmaps you'd like to use for different screens, you must place +these alternative resources in separate directories, similar to how you do for different language +strings.</p> + +<p>Also be aware that the screens orientation (landscape or portrait) is considered a variation of +screen size, so many apps should revise the layout to optimize the user experience in each +orientation.</p> + + +<h2 id="create-layouts">Create Different Layouts</h2> + +<p>To optimize your user experience on different screen sizes, you should create a unique layout XML +file for each screen size you want to support. Each layout should be +saved into the appropriate resources directory, named with a <code>-<screen_size></code> +suffix. For example, a unique layout for large screens should be saved under +<code>res/layout-large/</code>.</p> + +<p class="note"><strong>Note:</strong> Android automatically scales your layout in order to +properly fit the screen. Thus, your layouts for different screen sizes don't +need to worry about the absolute size of UI elements but instead focus on the layout structure that +affects the user experience (such as the size or position of important views relative to sibling +views).</p> + +<p>For example, this project includes a default layout and an alternative layout for <em>large</em> +screens:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ + main.xml + layout-large/ + main.xml +</pre> + +<p>The file names must be exactly the same, but their contents are different in order to provide +an optimized UI for the corresponding screen size.</p> + +<p>Simply reference the layout file in your app as usual:</p> + +<pre> +@Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> + +<p>The system loads the layout file from the appropriate layout directory based on screen size of +the device on which your app is running. More information about how Android selects the +appropriate resource is available in the <a +href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">Providing Resources</a> +guide.</p> + +<p>As another example, here's a project with an alternative layout for landscape orientation:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ + main.xml + layout-land/ + main.xml +</pre> + +<p>By default, the <code>layout/main.xml</code> file is used for portrait orientation.</p> + +<p>If you want a provide a special layout for landscape, including while on large screens, then +you need to use both the <code>large</code> and <code>land</code> qualifier:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ # default (portrait) + main.xml + layout-land/ # landscape + main.xml + layout-large/ # large (portrait) + main.xml + layout-large-land/ # large landscape + main.xml +</pre> + +<p class="note"><strong>Note:</strong> Android 3.2 and above supports an advanced method of +defining screen sizes that allows you to specify resources for screen sizes based on +the minimum width and height in terms of density-independent pixels. This lesson does not cover +this new technique. For more information, read <a +href="{@docRoot}training/multiscreen/index.html">Designing for Multiple +Screens</a>.</p> + + + +<h2 id="create-bitmaps">Create Different Bitmaps</h2> + +<p>You should always provide bitmap resources that are properly scaled to each of the generalized +density buckets: low, medium, high and extra-high density. This helps you achieve good graphical +quality and performance on all screen densities.</p> + +<p>To generate these images, you should start with your raw resource in vector format and generate +the images for each density using the following size scale:</p> +<ul> +<li>xhdpi: 2.0</li> +<li>hdpi: 1.5</li> +<li>mdpi: 1.0 (baseline)</li> +<li>ldpi: 0.75</li> +</ul> + +<p>This means that if you generate a 200x200 image for xhdpi devices, you should generate the same +resource in 150x150 for hdpi, 100x100 for mdpi, and 75x75 for ldpi devices.</p> + +<p>Then, place the files in the appropriate drawable resource directory:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + drawable-xhdpi/ + awesomeimage.png + drawable-hdpi/ + awesomeimage.png + drawable-mdpi/ + awesomeimage.png + drawable-ldpi/ + awesomeimage.png +</pre> + +<p>Any time you reference <code>@drawable/awesomeimage</code>, the system selects the +appropriate bitmap based on the screen's density.</p> + +<p class="note"><strong>Note:</strong> Low-density (ldpi) resources aren’t always necessary. When +you provide hdpi assets, the system scales them down by one half to properly fit ldpi +screens.</p> + +<p>For more tips and guidelines about creating icon assets for your app, see the +<a href="{@docRoot}design/style/iconography.html">Iconography design guide</a>.</p> + + + diff --git a/docs/html/training/tv/optimizing-layouts-tv.jd b/docs/html/training/tv/optimizing-layouts-tv.jd index 6eac6d3..e4a8e69 100644 --- a/docs/html/training/tv/optimizing-layouts-tv.jd +++ b/docs/html/training/tv/optimizing-layouts-tv.jd @@ -16,7 +16,7 @@ next.link=optimizing-navigation-tv.html <li><a href="#DesignLandscapeLayouts">Design Landscape Layouts</a></li> <li><a href="#MakeTextControlsEasyToSee">Make Text and Controls Easy to See</a></li> <li><a href="#DesignForLargeScreens">Design for High-Density Large Screens</a></li> - <li><a href="#HandleLargeBitmaps">Handle Large Bitmaps in Your Application</a></li> + <li><a href="#HandleLargeBitmaps">Design to Handle Large Bitmaps</a></li> </ol> <h2>You should also read</h2> diff --git a/docs/html/training/tv/optimizing-navigation-tv.jd b/docs/html/training/tv/optimizing-navigation-tv.jd index 8b5878e..bb78258 100644 --- a/docs/html/training/tv/optimizing-navigation-tv.jd +++ b/docs/html/training/tv/optimizing-navigation-tv.jd @@ -5,7 +5,7 @@ parent.link=index.html trainingnavtop=true previous.title=Optimizing Layouts for TV previous.link=optimizing-layouts-tv.html -next.title=Handling features not supported on TV +next.title=Handling Features Not Supported on TV next.link=unsupported-features-tv.html @jd:body |
