Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 325ce1a4 authored by Mark Lu's avatar Mark Lu Committed by android-build-merger
Browse files

docs: updates to Buildilng Your First App doc 

am: 08d1bff7

Change-Id: I030bd03c3f83ecc8332165dea75785cc78c3a114
parents 52a11f7c 08d1bff7

docs/html/training/basics/firstapp/building-ui.jd

+65 −123
Original line number Diff line number Diff line
@@ -71,38 +71,31 @@ android.view.View} objects.</p> 
<h2 id="LinearLayout">Create a Linear Layout</h2>



<ol>

<li>In Android Studio, from the <code>res/layout</code> directory, open the {@code content_my.xml}

file.

<p>The BlankActivity template you chose when you created this project includes the

<code>content_my.xml</code> file with a {@link android.widget.RelativeLayout} root view and a

{@link android.widget.TextView} child view.</p>

  <li>From the <code>res/layout/</code> directory, open the

    <code>activity_main.xml</code> file.

    <p>This XML file defines the layout of your activity. It contains the

      default "Hello World" text view.</p>

  </li>

<li>In the <strong>Preview</strong> pane, click the Hide icon <img src="{@docRoot}images/tools/as-hide-side.png"

  style="vertical-align:baseline;margin:0; max-height:1.5em" /> to close the Preview pane.

  <p> In Android Studio, when you open a layout file, you’re first shown

    the Preview pane. Clicking elements in this pane opens the WYSIWYG tools in the Design pane. For

    this lesson, you’re going to work directly with the XML.</p></li>

<li>Delete the {@link android.widget.TextView &lt;TextView>} element.</li>

<li>Change the {@link android.widget.RelativeLayout &lt;RelativeLayout>} element to

{@link android.widget.LinearLayout &lt;LinearLayout>}.</li>

<li>Add the <a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">

{@code android:orientation}</a> attribute and set it to <code>"horizontal"</code>.</li>

<li>Remove the {@code android:padding} attributes and the {@code tools:context} attribute.

</ol>



<p>The result looks like this:</p>



<pre>

&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"

    xmlns:app="http://schemas.android.com/apk/res-auto"

  <li>When you open a layout file, you’re first shown the design editor in the

    <a href="/studio/write/layout-editor.html">Layout Editor</a>. For this lesson,

    you work directly with the XML, so click the <b>Text</b> tab to switch to

    the text editor.

  </li>

  <li>Replace the contents of the file with the following XML:

    <pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;

&lt;LinearLayout

    xmlns:android="http://schemas.android.com/apk/res/android"

    xmlns:tools="http://schemas.android.com/tools"

    android:orientation="horizontal"

    android:layout_width="match_parent"

    android:layout_height="match_parent"

    app:layout_behavior="@string/appbar_scrolling_view_behavior"

    tools:showIn="@layout/activity_my"&gt;

    android:orientation="horizontal"&gt;

&lt;/LinearLayout&gt;

</pre>



  </li>



</ol>



<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
@@ -128,29 +121,25 @@ href="{@docRoot}guide/topics/ui/declaring-layout.html">Layout</a> guide.</p> 


<h2 id="TextInput">Add a Text Field</h2>



<p>As with every {@link android.view.View} object, you must define certain XML attributes to specify

the {@link android.widget.EditText} object's properties.</p>



<ol>

<li>In the <code>content_my.xml</code> file, within the

{@link android.widget.LinearLayout &lt;LinearLayout>} element, define an

{@link android.widget.EditText &lt;EditText>} element with the <code>id</code> attribute

set to <code>@+id/edit_message</code>.</li>

<li>Define the <code>layout_width</code> and <code>layout_height</code> attributes as

<code>wrap_content</code>.</li>

<li>Define a <code>hint</code> attribute as a string object named <code>edit_message</code>.</li>

</ol>



<p>The {@link android.widget.EditText &lt;EditText>} element should read as follows:</p>

<p>In the <code>activity_main.xml</code> file, within the

{@link android.widget.LinearLayout &lt;LinearLayout>} element, add the following

{@link android.widget.EditText &lt;EditText>} element:</p>



<pre>

&lt;EditText android:id="@+id/edit_message"

<pre>&lt;LinearLayout

    xmlns:android="http://schemas.android.com/apk/res/android"

    xmlns:tools="http://schemas.android.com/tools"

    android:layout_width="match_parent"

    android:layout_height="match_parent"

    android:orientation="horizontal"&gt;

    <b>&lt;EditText android:id="@+id/edit_message"

        android:layout_width="wrap_content"

        android:layout_height="wrap_content"

    android:hint="@string/edit_message" />

        android:hint="@string/edit_message" /></b>

&lt;/LinearLayout&gt;

</pre>



<p>Here are the {@link android.widget.EditText &lt;EditText>} attributes you added:</p>

<p>Here is a description of the attributes in the

  {@link android.widget.EditText &lt;EditText>} you added:</p>



<dl>

<dt><a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a></dt>
@@ -222,29 +211,20 @@ the same name does not cause collisions.</p> 
<h2 id="Strings">Add String Resources</h2>



<p>By default, your Android project includes a string resource file at

<code>res/values/strings.xml</code>. Here, you'll add a new string named

<code>"edit_message"</code> and set the value to "Enter a message."</p>

<code>res/values/strings.xml</code>. Here, you'll add two new strings.</p>



<ol>

<li>In Android Studio, from the <code>res/values</code> directory, open <code>strings.xml</code>.</li>

<li>Add a line for a string named <code>"edit_message"</code> with the value, "Enter a message".

</li>

<li>Add a line for a string named <code>"button_send"</code> with the value, "Send".

<p>You'll create the button that uses this string in the next section.</p>

</li>

</ol>



<p>The result for <code>strings.xml</code> looks like this:</p>



<pre>

&lt;?xml version="1.0" encoding="utf-8"?>

<li>From the <code>res/values/</code> directory, open <code>strings.xml</code>.</li>

<li>Add two strings so that your file looks like this:

<pre>&lt;?xml version="1.0" encoding="utf-8"?>

&lt;resources>

    &lt;string name="app_name">My First App&lt;/string>

    &lt;string name="edit_message">Enter a message&lt;/string>

    &lt;string name="button_send">Send&lt;/string>

    &lt;string name="action_settings">Settings&lt;/string>

    <b>&lt;string name="edit_message">Enter a message&lt;/string>

    &lt;string name="button_send">Send&lt;/string></b>

&lt;/resources>

</pre>

</li>

</ol>



<p>For text in the user interface, always specify each string as

a resource. String resources allow you to manage all UI text in a single location,
@@ -260,40 +240,22 @@ class.</p> 


<h2 id="Button">Add a Button</h2>



<ol>

<li>In Android Studio, from the <code>res/layout</code> directory, edit the <code>content_my.xml</code>

file.</li>

<li>Within the

{@link android.widget.LinearLayout &lt;LinearLayout>} element, define a

{@link android.widget.Button &lt;Button>} element immediately following the

{@link android.widget.EditText &lt;EditText>} element.</li>

<li>Set the button's width and height attributes to <code>"wrap_content"</code> so

the button is only as big as necessary to fit the button's text label.</li>

<li>Define the button's text label with the <a

href="{@docRoot}reference/android/widget/TextView.html#attr_android:text">{@code

android:text}</a> attribute; set its value to the <code>button_send</code> string

resource you defined in the previous section.</li>

</ol>



<p>Your {@link android.widget.LinearLayout &lt;LinearLayout>} should look like this:</p>



<pre>

&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"

    xmlns:app="http://schemas.android.com/apk/res-auto"

<p>Go back to the <code>activity_main.xml</code> file and add a button after the

  {@link android.widget.EditText &lt;EditText>}. Your file should look like this:</p>

<pre>&lt;LinearLayout

    xmlns:android="http://schemas.android.com/apk/res/android"

    xmlns:tools="http://schemas.android.com/tools"

    android:orientation="horizontal"

    android:layout_width="match_parent"

    android:layout_height="match_parent"

    app:layout_behavior="@string/appbar_scrolling_view_behavior"

    tools:showIn="@layout/activity_my"&gt;

    android:layout_height="match_parent"&gt;

        &lt;EditText android:id="@+id/edit_message"

          android:layout_width="wrap_content"

          android:layout_height="wrap_content"

          android:hint="@string/edit_message" /&gt;

        &lt;Button

        <b>&lt;Button

          android:layout_width="wrap_content"

          android:layout_height="wrap_content"

          android:text="@string/button_send" /&gt;

          android:text="@string/button_send" /&gt;</b>

&lt;/LinearLayout&gt;

</pre>
@@ -302,7 +264,7 @@ resource you defined in the previous section.</li> 
attribute, because it won't be referenced from the activity code.</p>



<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 Figure 2 shows.

android.widget.Button} widgets are only as big as necessary to fit their content, as figure 2 shows.

</p>



<img src="{@docRoot}images/training/firstapp/edittext_wrap.png" />
@@ -334,53 +296,36 @@ given the space they require.</p> 


<h2 id="Weight">Make the Input Box Fill in the Screen Width</h2>



<p>To fill the remaining space in your layout with the {@link android.widget.EditText} element, do

the following:</p>



<ol>

<li>In the <code>content_my.xml</code> file, assign the

{@link android.widget.EditText &lt;EditText>} element's <code>layout_weight</code> attribute a value

of <code>1</code>.</li>

<li>Also, assign {@link android.widget.EditText &lt;EditText>} element's <code>layout_width</code>

attribute a value of <code>0dp</code>.

<p>In <code>activity_main.xml</code>, modify the

  {@link android.widget.EditText &lt;EditText>} so that the attributes look like

  this:</p>



<pre>

&lt;EditText

    android:layout_weight="1"

    android:layout_width="0dp"

    ... /&gt;

&lt;EditText android:id="@+id/edit_message"

    <b>android:layout_weight="1"

    android:layout_width="0dp"</b>

    android:layout_height="wrap_content"

    android:hint="@string/edit_message" /&gt;

</pre>



<p>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

<p>Setting the width to zero (0dp) 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>



<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 it fills the remaining space in the {@link

android.widget.LinearLayout}.</p>



</li>

</ol>

<p>Here’s how your complete <code>activity_main.xml</code>layout file should now look:</p>



<p>Here’s how your complete <code>content_my.xml</code>layout file should now look:</p>



<pre>

&lt;?xml version="1.0" encoding="utf-8"?>

<pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;

&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"

   xmlns:app="http://schemas.android.com/apk/res-auto"

   xmlns:tools="http://schemas.android.com/tools"

   android:orientation="horizontal"

   android:layout_width="match_parent"

   android:layout_height="match_parent"

   app:layout_behavior="@string/appbar_scrolling_view_behavior"

   tools:showIn="@layout/activity_my"&gt;

   android:layout_height="match_parent"&gt;

    &lt;EditText android:id="@+id/edit_message"

        android:layout_weight="1"

        android:layout_width="0dp"
@@ -407,6 +352,3 @@ that the SDK tools generated when you created the project.</p> 
<p>Continue to the <a href="starting-activity.html">next

lesson</a> to learn how to respond to button presses, read content

from the text field, start another activity, and more.</p>
 
 No newline at end of file

docs/html/training/basics/firstapp/creating-project.jd

+36 −66
Original line number Diff line number Diff line
@@ -14,36 +14,19 @@ next.link=running-app.html 
<div id="tb-wrapper">

<div id="tb">



<h2>This lesson teaches you to</h2>



<ol>

  <li><a href="#Studio">Create a Project with Android Studio</a></li>

</ol>



<h2>You should also read</h2>



<ul>

  <li><a href="{@docRoot}tools/projects/index.html">Managing Projects</a></li>

  <li><a href="{@docRoot}studio/projects/index.html">Projects Overview</a></li>

</ul>





</div>

</div>



<p>An Android project contains all the files that comprise the source code for your Android

app.</p>



<p>This lesson

shows how to create a new project either using Android Studio or using the

SDK tools from a command line.</p>



<p class="note"><strong>Note:</strong> You should already have Android Studio or the Android SDK

command-line tools installed. If not, <a

href="{@docRoot}studio/index.html">download them</a> before you start this

lesson.</p>





<h2 id="Studio">Create a Project with Android Studio</h2>

<p>This lesson shows you how to create a new Android project with

  <a href="{@docRoot}studio/index.html">Android Studio</a> and describes some

  of the files in the project.</p>



<ol>

  <li>In Android Studio, create a new project:
@@ -54,11 +37,12 @@ lesson.</p> 
        Project</strong>. The <em>Create New Project</em> screen appears.</li>

    </ul>

  </li>

  <li>Fill out the fields on the screen, and click <strong>Next</strong>.

    <p>It is easier to follow these lessons if you use the same values as shown.</p>

  <li>Fill out the fields on the screen. For <strong>Application Name</strong>

    use "My First App". For <strong>Company Domain</strong>, use "example.com".

    For the other fields, use the default values and click <strong>Next</strong>

    <p>Here's a brief explanation of each field:</p>

    <ul>

      <li><strong>Application Name</strong> is the app name that appears to users.

          For this project, use "My First App."</li>

      <li><strong>Application Name</strong> is the app name that appears to users.</li>

      <li><strong>Company domain</strong> provides a qualifier that will be appended to the package

        name; Android Studio will remember this qualifier for each new project you create.</li>

      <li><strong>Package name</strong> is the fully qualified name for the project (following the
@@ -70,9 +54,8 @@ lesson.</p> 
        files.</li>

    </ul>

  </li>

  <li>Under <strong>Select the form factors your app will run on</strong>, check the box for <strong>

    Phone and Tablet</strong>.</li>

  <li>For <strong>Minimum SDK</strong>, select <strong>API 8: Android 2.2 (Froyo)</strong>.

  <li>Under <strong>Target Android Devices</strong>, accept the default values

    and click <strong>Next</strong>.

    <p>The Minimum Required SDK is the earliest version of Android that your app supports,

      indicated using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">

      API level</a>. To support as many devices as possible, you should set this to the lowest
@@ -80,8 +63,13 @@ lesson.</p> 
      app is possible only on newer versions of Android and it's not critical to the app's core

      feature set, you can enable the feature only when running on the versions that support it (as

      discussed in <a href="{@docRoot}training/basics/supporting-devices/platforms.html">

      Supporting Different Platform Versions</a>).</p></li>

  <li>Leave all of the other options (TV, Wear, and Glass) unchecked and click <strong>Next.</strong></li>

      Supporting Different Platform Versions</a>).</p>

    </li>



  <li>Under <strong>Add an Activity to Mobile</strong>, select <strong>Empty

    Activity</strong> and click <strong>Next</strong>.

  </li>



  <div class="sidebox-wrapper">

    <div class="sidebox">

      <h3>Activities</h3>
@@ -93,43 +81,25 @@ lesson.</p> 
        Activities</a> for more information.</p>

    </div>

  </div>

  <li>Under <strong>Add an activity to &lt;<em>template</em>&gt;</strong>,

  select <strong>Basic Activity</strong> and click <strong>Next</strong>.

  </li>



  <li>Under <strong>Customize the Activity</strong>, change the

  <strong>Activity Name</strong> to <em>MyActivity</em>. The <strong>Layout

  Name</strong> changes to <em>activity_my</em>, and the <strong>Title</strong>

  to <em>MyActivity</em>. The <strong>Menu Resource Name</strong> is

  <em>menu_my</em>.

  </li>



  <li>Click the <strong>Finish</strong> button to create the project.

  </li>

  <li>Under <strong>Customize the Activity</strong>, accept the default values

    and click <strong>Finish</strong>.

</ol>



<p>Your Android project is now a basic "Hello World" app that contains some default files. Take a

moment to review the most important of these:</p>



<dl>

  <dt><code>app/src/main/res/layout/activity_my.xml</code></dt>

  <dd>This XML layout file is for the activity you added when you created the project

  with Android Studio. Following the New Project workflow, Android Studio presents this file

  with both a text

    view and a preview of the screen UI. The file contains some default interface elements

    from the material design library, including the

    <a href="{@docRoot}training/appbar/index.html">app bar</a> and a floating action button.

    It also includes a separate layout file with the main content.</dd>



  <dt><code>app/src/main/res/layout/content_my.xml</code></dt>

  <dd>This XML layout file resides in {@code activity_my.xml}, and contains some settings and

  a {@code TextView} element that displays the message, "Hello world!".</dd>



  <dt><code>app/src/main/java/com.mycompany.myfirstapp/MyActivity.java</code></dt>

  <dd>A tab for this file appears in Android Studio when the New Project workflow finishes. When you

    select the file you see the class definition for the activity you created. When you build and

    run the app, the {@link android.app.Activity} class starts the activity and loads the layout file

    that says "Hello World!"</dd>

  <dt><code>app/src/main/java/com.example.myfirstapp/MainActivity.java</code></dt>

  <dd>This file appears in Android Studio after the New Project wizard finishes.

    It contains the class definition for the activity you created earlier. When you build

    and run the app, the {@link android.app.Activity} starts and loads the

    layout file that says "Hello World!"</dd>



  <dt><code>app/src/main/res/layout/activity_main.xml</code></dt>

  <dd>This XML file defines the layout of the activity. It contains a {@code TextView}

    element with the text "Hello world!".</dd>



  <dt><code>app/src/main/AndroidManifest.xml</code></dt>

  <dd>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest file</a> describes

    the fundamental characteristics of the app and defines each of its components. You'll revisit
@@ -143,15 +113,15 @@ moment to review the most important of these:</p> 
    <ul>

      <li><code>compiledSdkVersion</code> is the platform version against which you will compile

        your app. By default, this is set to the latest version of Android available in your SDK.

        (It should be Android 4.1 or greater; if you don't have such a version available, you must

        install one using the <a href="{@docRoot}studio/intro/update.html">SDK Manager</a>.)

        By default, this is set to the latest version of Android SDK installed on your

        development machine.

        You can still build your app to support older versions, but setting this to the latest

        version allows you to enable new features and optimize your app for a great user experience

        on the latest devices.</li>

      <li><code>applicationId</code> is the fully qualified package name for your application that

        you specified during the New Project workflow.</li>

        you specified in the New Project wizard.</li>

      <li><code>minSdkVersion</code> is the Minimum SDK version you specified during the New Project

        workflow. This is the earliest version of the Android SDK that your app supports.</li>

        wizard. This is the earliest version of the Android SDK that your app supports.</li>

      <li><code>targetSdkVersion</code> indicates the highest version of Android with which you have

        tested your application. As new versions of Android become available, you should

        test your app on the new version and update this value to match the latest API level and
@@ -172,8 +142,8 @@ moment to review the most important of these:</p> 
    for various <a href="{@docRoot}training/multiscreen/screendensities.html">densities</a>.

</dd>

  <dt><code>layout/</code></dt>

    <dd>Directory for files that define your app's user interface like {@code activity_my.xml},

      discussed above, which describes a basic layout for the {@code MyActivity}

    <dd>Directory for files that define your app's user interface like {@code activity_main.xml},

      discussed above, which describes a basic layout for the {@code MainActivity}

      class.</dd>

  <dt><code>menu/</code></dt>

    <dd>Directory for files that define your app's menu items.</dd>

docs/html/training/basics/firstapp/index.jd

+7 −22
Original line number Diff line number Diff line
@@ -23,25 +23,10 @@ helpoutsWidget=true 


<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>



<h2>Set Up Your Environment</h2>



<p>Before you start this class, be sure you have your development environment set up. You need

to:</p>

<ol>

  <li>Download <a href="{@docRoot}studio/index.html">Android Studio</a>.</li>

  <li>Download the latest SDK tools and platforms using the

  <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li>

</ol>



<p class="note"><strong>Note:</strong> Although most of this training class

expects that you're using Android Studio, some procedures include alternative

instructions for using

the SDK tools from the command line instead.</p>



<p>This class uses a tutorial format to create a small Android app that teaches

you some fundamental concepts about Android development, so it's important that you follow each

step.</p>
 
<p>This class teaches you how to build your first Android app. You’ll learn how

  to create an Android project with Android Studio 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, download and install

  <a href="{@docRoot}studio/index.html">Android Studio</a>.</p>
 
 No newline at end of file

docs/html/training/basics/firstapp/running-app.jd

+41 −61

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/training/basics/firstapp/starting-activity.jd

+147 −430

File changed.

Preview size limit exceeded, changes collapsed.