diff options
Diffstat (limited to 'docs/html/training/basics')
| -rw-r--r-- | docs/html/training/basics/firstapp/building-ui.jd | 254 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/creating-project.jd | 212 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/index.jd | 18 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/running-app.jd | 181 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/starting-activity.jd | 370 |
5 files changed, 575 insertions, 460 deletions
diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd index c082642..2668913 100644 --- a/docs/html/training/basics/firstapp/building-ui.jd +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -8,9 +8,9 @@ helpoutsWidget=true <!-- This is the training bar --> -<div id="tb-wrapper"> -<div id="tb"> - +<div id="tb-wrapper"> +<div id="tb"> + <h2>This lesson teaches you to</h2> <ol> @@ -27,16 +27,18 @@ helpoutsWidget=true <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li> </ul> -</div> -</div> - +</div> +</div> +<p>In this lesson, you create a layout in XML that includes a text field and a +button. In the next lesson, your app responds when the button is pressed by sending the +content of the text field to another activity.</p> <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 href="{@docRoot}guide/topics/ui/controls/button.html">buttons</a> or -<a href="{@docRoot}guide/topics/ui/controls/text.html">text fields</a> and {@link -android.view.ViewGroup} objects are +<a href="{@docRoot}guide/topics/ui/controls/text.html">text fields</a>. +{@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> @@ -44,6 +46,8 @@ grid or a vertical list.</p> android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML using a hierarchy of UI elements.</p> +<p>Layouts are subclasses of the {@link android.view.ViewGroup}. In this exercise, you'll work with +a {@link android.widget.LinearLayout}.</p> <div class="sidebox-wrapper"> <div class="sidebox"> @@ -63,33 +67,32 @@ Devices</a>.</p> android.view.ViewGroup} objects form branches in the layout and contain other {@link android.view.View} objects.</p> -<p>In this lesson, you'll create a layout in XML that includes a text 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">Create a Linear Layout</h2> -<p>Open the <code>fragment_main.xml</code> file from the <code>res/layout/</code> -directory.</p> - -<p class="note"><strong>Note:</strong> In Eclipse, when you open a layout file, you’re first shown -the Graphical 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>fragment_main.xml</em> tab at -the bottom of the screen to open the XML editor.</p> - +<ol> +<li>In Android Studio, from the <code>res/layout</code> directory, open the <code>activity_my.xml</code> +file. <p>The BlankActivity template you chose when you created this project includes the -<code>fragment_main.xml</code> file with a {@link -android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.</p> +<code>activity_my.xml</code> file with a {@link android.widget.RelativeLayout} root view and a +{@link android.widget.TextView} child 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 <TextView>} element.</li> +<li>Change the {@link android.widget.RelativeLayout <RelativeLayout>} element to +{@link android.widget.LinearLayout <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>First, delete the {@link android.widget.TextView <TextView>} element and change the {@link - android.widget.RelativeLayout <RelativeLayout>} element to {@link - android.widget.LinearLayout <LinearLayout>}. Then 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>. -The result looks like this:</p> +</p>The result looks like this:</p> +<p class="code-caption">res/layout/activity_my.xml</p> <pre> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" @@ -104,9 +107,9 @@ android.view.ViewGroup}) that lays out child views in either a vertical or horiz 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> +the screen in the order in which it appears in the XML.</p> -<p>The other two attributes, <a +<p>Two other 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 @@ -122,28 +125,47 @@ or height to <em>match</em> the width or height of the parent view.</p> href="{@docRoot}guide/topics/ui/declaring-layout.html">Layout</a> guide.</p> - <h2 id="TextInput">Add a Text Field</h2> -<p>To create a user-editable text field, add an {@link android.widget.EditText -<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}.</p> +<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>activity_my.xml</code> file, within the +{@link android.widget.LinearLayout <LinearLayout>} element, define an +{@link android.widget.EditText <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>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> +<p>The {@link android.widget.EditText <EditText>} element should read as follows:</p> +<p class="code-caption">res/layout/activity_my.xml</p> <pre> - <EditText android:id="@+id/edit_message" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:hint="@string/edit_message" /> +<EditText android:id="@+id/edit_message" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> </pre> +<p>Here are the {@link android.widget.EditText <EditText>} attributes you added:</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 sign (<code>@</code>) is required when you're referring to any resource object from +XML. It is followed by the resource type ({@code id} in this case), a slash, then the resource name +({@code edit_message}).</p> <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, + <h3>Resource Objects</h3> + <p>A resource object is 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 @@ -153,30 +175,18 @@ href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code 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 + <p>The SDK tools generate the {@code R.java} file each time you compile your app. You should never modify this file by hand.</p> <p>For more information, read the guide to <a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</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 sign (<code>@</code>) is required when you're referring to any resource object from -XML. It is followed by the resource type ({@code id} in this case), a slash, then the resource name -({@code edit_message}).</p> - <p>The plus sign (<code>+</code>) before the resource type is needed only when you're defining a resource ID for the first time. When you compile the app, the SDK tools use the ID name to create a new resource ID in your project's {@code gen/R.java} file that refers to the {@link -android.widget.EditText} element. Once the resource ID is declared once this way, +android.widget.EditText} element. With the resource ID declared once this way, other references to the ID do not need the plus sign. Using the plus sign is necessary only when specifying a new resource ID and not needed for concrete resources such as strings or layouts. See the sidebox for @@ -209,26 +219,25 @@ the same name does not cause collisions.</p> </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 as -a resource. String resources allow you to manage all UI text in a single location, -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 resource.</p> - <p>By default, your Android project includes a string resource file at -<code>res/values/strings.xml</code>. Add a new string named -<code>"edit_message"</code> and set the value to "Enter a message." (You can delete -the "hello_world" string.)</p> +<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> -<p>While you’re in this file, also add a "Send" string for the button you’ll soon add, called -<code>"button_send"</code>.</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> +<li>Remove the line for the <code>"hello world"</code> string.</li> +</ol> <p>The result for <code>strings.xml</code> looks like this:</p> +<p class="code-caption">res/values/strings.xml</p> <pre> <?xml version="1.0" encoding="utf-8"?> <resources> @@ -240,35 +249,59 @@ the "hello_world" string.)</p> </resources> </pre> +<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, +which makes the text easier to find and update. Externalizing the strings also allows you to +localize your app to different languages by providing alternative definitions for each +string resource.</p> + <p>For more information about using string resources to localize your app for other languages, see the <a href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Different 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> +<ol> +<li>In Android Studio, from the <code>res/layout</code> directory, edit the <code>activity_my.xml</code> +file.</li> +<li>Within the +{@link android.widget.LinearLayout <LinearLayout>} element, define a +{@link android.widget.Button <Button>} element immediately following the +{@link android.widget.EditText <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 <LinearLayout>} should look like this:</p> +<p class="code-caption">res/layout/activity_my.xml</p> <pre> - <Button +<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" > + <EditText android:id="@+id/edit_message" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@string/button_send" /> + android:hint="@string/edit_message" /> + <Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" /> +</LinearLayout> </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. This button doesn't need the +<p class="note"><strong>Note:</strong> This button doesn't need the <a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute, because it won't be referenced from the activity code.</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> @@ -279,7 +312,7 @@ 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 field, because the user might type -something longer. So, it would be nice to fill the unused screen width +something longer. It would be nice to fill the unused screen width with the text field. You can do this inside a {@link android.widget.LinearLayout} with the <em>weight</em> property, which you can specify using the <a @@ -288,9 +321,9 @@ android:layout_weight}</a> attribute.</p> <p>The weight value is a number that specifies the amount of remaining space each view should consume, -relative to the amount consumed by sibling views. This works kind of like the +relative to the amount consumed by sibling views. This works kind of like the amount of ingredients in a drink recipe: "2 -parts vodka, 1 part coffee liqueur" means two-thirds of the drink is vodka. For example, if you give +parts soda, 1 part syrup" means two-thirds of the drink is soda. 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 fills 2/3 of the remaining space and the second view fills the rest. If you add a third view and give it a weight of 1, then the first view (with weight of 2) now gets 1/2 the remaining space, while the remaining @@ -298,38 +331,49 @@ 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 all views are -given the space they require. So, to fill the remaining space in your layout with the {@link -android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.</p> +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>activity_my.xml</code> file, assign the +{@link android.widget.EditText <EditText>} element's <code>layout_weight</code> attribute a value +of <code>1</code>.</li> +<li>Also, assign {@link android.widget.EditText <EditText>} element's <code>layout_width</code> +attribute a value of <code>0dp</code>. + +<p class="code-caption">res/layout/activity_my.xml</p> <pre> - <EditText - android:layout_weight="1" - ... /> +<EditText + android:layout_weight="1" + android:layout_width="0dp" + ... /> </pre> -<p>In order to improve the layout efficiency when you specify the weight, you should change the +<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 <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 +given all the layout weight, so it fills the remaining space in the {@link android.widget.LinearLayout}.</p> -<p>Here’s how your complete layout file should now look:</p> +</li> +</ol> +<p>Here’s how your complete <code>activity_my.xml</code>layout file should now look:</p> + +<p class="code-caption">res/layout/activity_my.xml</p> <pre> <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" @@ -349,13 +393,16 @@ android.widget.LinearLayout}.</p> </LinearLayout> </pre> +<h2>Run Your App</h2> + <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 +that the SDK tools generated when you created the project. Run the app to see the results:</p> <ul> - <li>In Eclipse, click Run <img src="{@docRoot}images/tools/eclipse-run.png" - style="vertical-align:baseline;margin:0" /> from the toolbar.</li> + <li>In Android Studio, from the toolbar, click <strong>Run</strong> + <img src="{@docRoot}images/tools/as-run.png" + style="vertical-align:baseline;margin:0; max-height:1em" />.</li> <li>Or from a command line, change directories to the root of your Android project and execute: <pre> @@ -364,7 +411,8 @@ 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 +<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> diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd index 418eb68..f33f75f 100644 --- a/docs/html/training/basics/firstapp/creating-project.jd +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -17,7 +17,7 @@ next.link=running-app.html <h2>This lesson teaches you to</h2> <ol> - <li><a href="#Eclipse">Create a Project with Eclipse</a></li> + <li><a href="#Studio">Create a Project with Android Studio</a></li> <li><a href="#CommandLine">Create a Project with Command Line Tools</a></li> </ol> @@ -38,97 +38,145 @@ app. The Android SDK tools make it easy to start a new Android project with a se 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 +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 the Android SDK installed, and if -you're using Eclipse, you should also have the <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT -plugin</a> installed (version 22.6.2 or higher). If you don't have these, follow the guide to <a +you're using Android Studio, you should also have <a href="{@docRoot}sdk/installing/studio.html"> +Android Studio</a> installed. If you don't have these, follow the guide to <a href="{@docRoot}sdk/installing/index.html">Installing the Android SDK</a> before you start this lesson.</p> -<h2 id="Eclipse">Create a Project with Eclipse</h2> +<h2 id="Studio">Create a Project with Android Studio</h2> <ol> - <li>Click <strong>New</strong> <img src="{@docRoot}images/tools/eclipse-new.png" - style="vertical-align:baseline;margin:0" /> in the toolbar.</li> - <li>In the window that appears, open the <strong>Android</strong> folder, - select <strong>Android Application Project</strong>, and click <strong>Next</strong>.</li> - -<div class="figure" style="width:420px"> -<img src="{@docRoot}images/training/firstapp/adt-firstapp-setup.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The New Android App Project wizard in Eclipse.</p> -</div> - - <li>Fill in the form that appears: + <li>In Android Studio, create a new project: <ul> - <li><strong>Application Name</strong> is the app name that appears to users. - For this project, use "My First App."</p></li> - <li><strong>Project Name</strong> is the name of your project directory and the name visible in Eclipse.</li> - <li><strong>Package Name</strong> is 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 generally -best if you use a name that begins with the reverse domain name of your organization or -publisher entity. For this project, you can use something like "com.example.myfirstapp." -However, you cannot publish your app on Google Play using the "com.example" namespace.</li> - <li><strong>Minimum Required SDK</strong> is the lowest 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 version available - that allows your app to provide its core feature set. If any feature of your 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>). - Leave this set to the default value for this project. - </li> - <li><strong>Target SDK</strong> indicates the highest version of Android (also using the - <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels" - >API level</a>) with which you - have tested with your application. - <p>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 - in order to take advantage of new platform features.</p> - </li> - <li><strong>Compile With</strong> 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}sdk/installing/adding-packages.html">SDK Manager</a>). - You can still build your app to -support older versions, but setting the build target 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><strong>Theme</strong> specifies the Android UI style to apply for your app. You can leave - this alone.</li> + <li>If you don't have a project opened, in the <strong>Welcome</strong> screen, click <strong> + New Project</strong>.</li> + <li>If you have a project opened, from the <strong>File</strong> menu, select <strong>New + Project</strong>.</li> </ul> - <p>Click <strong>Next</strong>.</p> </li> - <li>On the next screen to configure the project, leave the default selections and click - <strong>Next</strong>.</li> - <li>The next screen can help you create a launcher icon for your app. - <p>You can customize an icon in several ways and the tool generates an icon for all - screen densities. Before you publish your app, you should be sure your icon meets - the specifications defined in the <a - href="{@docRoot}design/style/iconography.html">Iconography</a> - design guide.</p> - <p>Click <strong>Next</strong>.</p> - </li> - <li>Now you can select an activity template from which to begin building your app. - <p>For this project, select <strong>BlankActivity</strong> and click <strong>Next</strong>.</p> + <div class="figure" style="width:420px"> + <img src="{@docRoot}images/training/firstapp/studio-setup-1.png" alt="" /> + <p class="img-caption"><strong>Figure 1.</strong> Configuring a new project in Android Studio.</p> + </div> + <li>Under <strong>Configure your new project</strong>, fill in the fields as shown in figure 1 + and click <strong>Next</strong>. + <p>It will probably be easier to follow these lessons if you use the same values as shown.</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>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 + same rules as those for naming packages in the Java programming language). Your package name + must be unique across all packages installed on the Android system. You can <strong> + Edit</strong> this value independently from the application name or the company + domain.</li> + <li><strong>Project location</strong> is the directory on your system that holds the project + files.</li> + </ul> </li> - <li>Leave all the details for the activity in their default state and click - <strong>Finish</strong>.</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>. + <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 + version available that allows your app to provide its core feature set. If any feature of your + 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> + <div class="sidebox-wrapper"> + <div class="sidebox"> + <h3>Activities</h3> + <p>An activity is one of the distinguishing features of the Android framework. Activities + provide the user with access to your app, and there may be many activities. An application + will usually have a main activity for when the user launches the application, another + activity for when she selects some content to view, for example, and other activities for + when she performs other tasks within the app. See <a href="{@docRoot}guide/components/activities.html"> + Activities</a> for more information.</p> + </div> + </div> + <li>Under <strong>Add an activity to your project</strong>, select <strong>Blank Activity</strong> + and click <strong>Next</strong>.</li> + <li>Under <strong>Describe the new activity for your project</strong>, leave the fields as they + are and click <strong>Finish</strong>.</li> </ol> -<p>Your Android project is now a basic "Hello World" app that contains some default files. -To run the app, continue to the <a href="running-app.html">next lesson</a>.</p> - - +<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 is the XML layout file 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 includes some default settings and a <code>TextView</code> + 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/res/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 + this file as you follow these lessons and add more components to your app.</dd> + <dt><code>app/build.gradle</code></dt> + <dd>Android Studio uses Gradle to compile and build your app. There is a <code>build.gradle</code> + file for each module of your project, as well as a <code>build.gradle</code> file for the entire + project. Usually, you're only interested in the <code>build.gradle</code> file for the module, + in this case the <code>app</code> or application module. This is where your app's build dependencies + are set, including the <code>defaultConfig</code> settings: + <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}sdk/installing/adding-packages.html">SDK Manager</a>.) + 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> + <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> + <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 + thereby take advantage of new platform features. For more information, read + <a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different + Platform Versions</a>.</li> + </ul> + <p>See <a href="{@docRoot}sdk/installing/studio-build.html">Building Your Project with Gradle</a> + for more information about Gradle.</p></dd> +</dl> + +<p>Note also the <code>/res</code> subdirectories that contain the +<a href="{@docRoot}guide/topics/resources/overview.html">resources</a> for your application:</p> +<dl> + <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. + Here you'll find the ic_launcher.png that appears when you run the default app.</dd> + <dt><code>layout/</code></dt> + <dd>Directory for files that define your app's user interface like activity_my.xml, + discussed above, which describes a basic layout for the MyActivity class.</dd> + <dt><code>values/</code></dt> + <dd>Directory for other XML files that contain a collection of resources, such as + string and color definitions. The strings.xml file defines the "Hello world!" string that + displays when you run the default app.</dd> +</dl> + +<p>To run 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 +<p>If you're not using the Android Studio IDE, you can instead create your project using the SDK tools from a command line:</p> <ol> @@ -136,32 +184,32 @@ using the SDK tools from a command line:</p> <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 +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/adding-packages.html">Adding Platforms - and Packages</a>.</p></li> +Manager tool. See <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK + Packages</a>.</p></li> <li>Execute: <pre class="no-pretty-print"> android create project --target <target-id> --name MyFirstApp \ ---path <path-to-workspace>/MyFirstApp --activity MainActivity \ +--path <path-to-workspace>/MyFirstApp --activity MyActivity \ --package com.example.myfirstapp </pre> -<p>Replace <code><target-id></code> with an id from the list of targets (from the previous step) +<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 a basic "Hello World" app that contains some default files. -To run 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> +<p>Your Android project is now a basic "Hello World" app that contains some default files. +To run the app, continue to the <a href="running-app.html">next lesson</a>.</p> + diff --git a/docs/html/training/basics/firstapp/index.jd b/docs/html/training/basics/firstapp/index.jd index ac8e64a..d5df0b7 100644 --- a/docs/html/training/basics/firstapp/index.jd +++ b/docs/html/training/basics/firstapp/index.jd @@ -15,9 +15,8 @@ helpoutsWidget=true <h2>Dependencies and prerequisites</h2> <ul> - <li><a href="http://developer.android.com/sdk/index.html">Android SDK</a></li> - <li><a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a> 22.6.2 or higher - (if you're using Eclipse)</li> + <li><a href="{@docRoot}sdk/index.html">Android SDK</a></li> + <li><a href="{@docRoot}sdk/installing/studio.html">Android Studio</a></li> </ul> </div> @@ -29,16 +28,19 @@ helpoutsWidget=true 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 the Android SDK.</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> + <li>Download the <a href="{@docRoot}sdk/index.html">Android SDK</a>.</li> + <li>Install <a href="{@docRoot}sdk/installing/studio.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> Make sure you install the most recent versions of the ADT -plugin and the Android SDK before you start this class. The procedures described in this class may +<p class="note"><strong>Note:</strong> Make sure you install the most recent versions of Android +Studio and the Android SDK before you start this class. The procedures described in this class may not apply to earlier versions.</p> <p>If you haven't already done these tasks, start by downloading the diff --git a/docs/html/training/basics/firstapp/running-app.jd b/docs/html/training/basics/firstapp/running-app.jd index 96b7172..50b4fea 100644 --- a/docs/html/training/basics/firstapp/running-app.jd +++ b/docs/html/training/basics/firstapp/running-app.jd @@ -11,9 +11,9 @@ helpoutsWidget=true <!-- This is the training bar --> -<div id="tb-wrapper"> -<div id="tb"> - +<div id="tb-wrapper"> +<div id="tb"> + <h2>This lesson teaches you to</h2> <ol> @@ -28,85 +28,32 @@ helpoutsWidget=true <li><a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a></li> <li><a href="{@docRoot}tools/projects/index.html">Managing Projects</a></li> </ul> - - -</div> -</div> + + +</div> +</div> <p>If you followed the <a href="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 immediately run the app.</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>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 learn about various declarations in this file as you read more training -classes. - <p>One of the most important elements your manifest should include is the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> -element. This declares your app's compatibility with different Android versions using the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> -and <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> -attributes. For your first app, it should look like this:</p> -<pre> -<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... > - <uses-sdk android:minSdkVersion="8" android:targetSdkVersion="19" /> - ... -</manifest> -</pre> -<p>You should always set the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> -as high as possible and test your app on the corresponding platform version. For more information, -read <a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different -Platform Versions</a>.</p> - - </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 <a -href="{@docRoot}guide/topics/resources/overview.html">app resources</a>. 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 app, the default {@link android.app.Activity} -class starts and loads a layout file -that says "Hello World." The result is nothing exciting, but it's -important that you understand how to run your app before you start developing.</p> - - +<p>How you run your app depends on two things: whether you have a real device running Android and +whether you're using Android Studio. 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 Android Studio or the command +line tools.</p> <h2 id="RealDevice">Run on a Real Device</h2> -<p>If you have a real Android-powered device, here's how you can install and run your app:</p> +<p>If you have a device running Android, here's how to install and run your app.</p> + +<h3>Set up your device</h3> <ol> <li>Plug in your device to your development 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}tools/extras/oem-usb.html">OEM USB -Drivers</a> document.</li> + 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}tools/extras/oem-usb.html">OEM + USB Drivers</a> document.</li> <li>Enable <strong>USB debugging</strong> on your device. <ul> <li>On most devices running Android 3.2 or older, you can find the option under @@ -121,19 +68,20 @@ Drivers</a> document.</li> </li> </ol> -<p>To run the app from Eclipse:</p> +<h3>Run the app from Android Studio</h3> <ol> <li>Open one of your project's files and click <strong>Run</strong> <img -src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> +src="{@docRoot}images/tools/as-run.png" style="vertical-align:baseline;margin:0; max-height:1em" /> from the toolbar.</li> - <li>In the <strong>Run as</strong> window that appears, select - <strong>Android Application</strong> and click <strong>OK</strong>.</li> + <li>In the <strong>Choose Device</strong> window that appears, select the + <strong>Choose a running device</strong> radio button, select your device, and click <strong>OK + </strong>.</li> </ol> -<p>Eclipse installs the app on your connected device and starts it.</p> +<p>Android Studio installs the app on your connected device and starts it.</p> -<p>Or to run your app from a command line:</p> +<h3>Run the app from a command line</h3> <ol> <li>Change directories to the root of your Android project and execute: @@ -141,7 +89,7 @@ from the toolbar.</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> + <li>On your device, locate <em>MyFirstApp</em> and open it.</li> </ol> <p>That's how you build and run your Android app on a device! @@ -152,64 +100,67 @@ lesson</a>.</p> <h2 id="Emulator">Run on the Emulator</h2> -<p>Whether you're using Eclipse or the command line, to run your app on the emulator you need to -first create an <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a> (AVD). An -AVD is a device configuration for the Android emulator that allows you to model different -devices.</p> +<p>Whether you're using Android Studio or the command line, to run your app on the emulator you need +to first create an <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a> (AVD). An +AVD is a device configuration for the Android emulator that allows you to model a specific +device.</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> + <img src="{@docRoot}images/screens_support/as-mac-avds-config.png" /> + <p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a virtual device.</p> </div> -<p>To create an AVD:</p> +<h3>Create an AVD</h3> <ol> <li>Launch the Android Virtual Device Manager: - <ol type="a"> - <li>In Eclipse, click Android Virtual Device Manager - <img src="{@docRoot}images/tools/avd_manager.png" -style="vertical-align:baseline;margin:0" /> from the 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> + <ul> + <li>In the Android Studio tool bar, click the Android Virtual Device Manager icon + <img src="{@docRoot}images/tools/avd-manager-studio.png" + style="vertical-align:baseline;margin:0; max-height:1em" />.</li> + <li>From the command line, change directories to <code><sdk>/tools/</code> and execute: + <pre class="no-pretty-print">android avd</pre></li> + </ul> </li> - <li>In the <em>Android Virtual 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> + <li>In the <strong>Android Virtual Device Manager</strong> window, click <strong>Create</strong>.</li> + <li>Enter an <strong>AVD Name</strong>.</li> + <li>Select a <strong>Device</strong> type. + <p>When you select a device type, most of the fields auto-populate.</p> + <li>For <strong>Skin</strong> select <strong>HVGA</strong>.</li> + <li>For <strong>SD Card</strong>, enter something small, like 10 MiB. + <p>It really doesn't matter what you enter here since you're not using any storage. But if you + reuse this AVD, you might have to adjust this setting.</p></li> + <li>Ignore the <strong>Emulation Options</strong> and click <strong>OK</strong>.</li> + <li>In the <strong>Result</strong> screen, click <strong>OK</strong>.</li> + <li>Close the <strong>Android Virtual Device Manager</strong> window.</li> </ol> -<p>To run the app from Eclipse:</p> +<h3>Run the app from Android Studio</h3> <ol> - <li>Open one of your project's files and click -<strong>Run</strong> <img -src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> -from the toolbar.</li> - <li>In the <strong>Run as</strong> window that appears, select - <strong>Android Application</strong> and click <strong>OK</strong>.</li> + <li>In <strong>Android Studio</strong>, select your project and click <strong>Run</strong> + <img src="{@docRoot}images/tools/as-run.png" style="vertical-align:baseline;margin:0; max-height:1em" /> + from the toolbar.</li> + <li>In the <strong>Choose Device</strong> window, click the <strong>Launch emulator</strong> radio + button.</li> + <li>From the <strong>Android virtual device</strong> pull-down menu, select the emulator + you created, and click <strong>OK</strong>.</li> </ol> -<p>Eclipse installs the app on your AVD and starts it.</p> +<p>It can take a few minutes for the emulator to load itself. You may have to unlock the screen. + When you do, My First App appears on the emulator screen.</p> -<p>Or to run your app from the command line:</p> +<h3>Run your app from the command line</h3> <ol> <li>Change directories to the root of your Android project and execute: -<pre class="no-pretty-print">ant debug</pre></li> + <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> + <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>MyFirstApp</em> and open it.</li> </ol> -<p>That's how you build and run your Android app on the emulator! +<p>That's how you build and run your Android app on the emulator! To start developing, 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 index f9dcba4..d672838 100644 --- a/docs/html/training/basics/firstapp/starting-activity.jd +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -19,7 +19,7 @@ helpoutsWidget=true <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="#StartActivity">Start the Second Activity</a></li> --> <li><a href="#CreateActivity">Create the Second Activity</a></li> <li><a href="#ReceiveIntent">Receive the Intent</a></li> <li><a href="#DisplayMessage">Display the Message</a></li> @@ -40,17 +40,20 @@ SDK</a></li> <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 field and a button. In this lesson, you’ll add some -code to <code>MainActivity</code> that +code to <code>MyActivity</code> that starts a new activity when the user clicks 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>fragment_main.xml</code> -layout file and add the <a +<ol> +<li>In Android Studio, from the <code>res/layout</code> directory, edit the <code>activity_my.xml</code> +file.</li> +<li>To the {@link android.widget.Button <Button>} element, 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> +attribute. +<p class="code-caption">res/layout/activity_my.xml</p> <pre> <Button android:layout_width="wrap_content" @@ -63,10 +66,12 @@ attribute to the {@link android.widget.Button <Button>} element:</p> 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 the system calls when the user clicks the button.</p> +</li> +<li>In the <code>java/com.mycompany.myfirstapp</code> directory, open the <code>MyActivity.java</code> file.</li> +<li>Within the <code>MyActivity</code> class, add the {@code sendMessage()} method stub shown +below. -<p>Open the <code>MainActivity</code> class (located in the project's -<code>src/</code> directory) and add the corresponding method:</p> - +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> <pre> /** Called when the user clicks the Send button */ public void sendMessage(View view) { @@ -85,32 +90,40 @@ the signature must be exactly as shown. Specifically, the method must:</p> android.view.View} that was clicked)</li> </ul> +</li> +</ol> + <p>Next, you’ll fill in this method to read the contents of the text field 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 intents 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 DisplayMessageActivity}:</p> +<ol> +<li>In <code>MyActivity.java</code>, inside the {@code sendMessage()} method, create an +{@link android.content.Intent} to start an activity called {@code DisplayMessageActivity} with the +following code: +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> <pre> -Intent intent = new Intent(this, DisplayMessageActivity.class); +public void sendMessage(View view) { + Intent intent = new Intent(this, DisplayMessageActivity.class); +} </pre> -<p>This requires that you import the {@link android.content.Intent} class:</p> -<pre> -import android.content.Intent; -</pre> +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h3>Intents</h3> +<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 intents for a wide +variety of tasks, but most often they’re used to start another activity. For more information, see +<a href="{@docRoot}guide/components/intents-filters.html ">Intents and Intent Filters</a>.</p> +</div> +</div> -<p class="note"><strong>Tip:</strong> In Eclipse, press Ctrl + Shift + O to import missing classes -(Cmd + Shift + O on Mac).</p> +<p class="note"><strong>Note:</strong> The reference to {@code DisplayMessageActivity} +will raise an error if you’re using an IDE such as Android Studio because the class doesn’t exist yet. +Ignore the error for now; you’ll create the class soon.</p> <p>The constructor used here takes two parameters:</p> <ul> @@ -121,6 +134,19 @@ android.app.Activity} class is a subclass of {@link android.content.Context}) the {@link android.content.Intent} (in this case, the activity that should be started) </ul> +<p>Android Studio indicates that you must import the {@link android.content.Intent} class.</p> + +</li> +<li>At the top of the file, import the {@link android.content.Intent} class: +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> +<pre> +import android.content.Intent; +</pre> +<p class="note"><strong>Tip:</strong> In Android Studio, press Alt + Enter (option + return on Mac) + to import missing classes.</p> +</li> + +<!-- I didn't think this was necessary <div class="sidebox-wrapper"> <div class="sidebox"> <h3>Sending an intent to other apps</h3> @@ -134,59 +160,69 @@ as long as it satisfies the meta-data specifications for the action that's speci href="{@docRoot}training/basics/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 it can carry a bundle of data to the -activity as well. Inside the {@code sendMessage()} method, +<li>Inside the {@code sendMessage()} method, use {@link android.app.Activity#findViewById findViewById()} to get the -{@link android.widget.EditText} element and add its text value to the intent:</p> - +{@link android.widget.EditText} element. +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</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); +public void sendMessage(View view) { + Intent intent = new Intent(this, DisplayMessageActivity.class); + EditText editText = (EditText) findViewById(R.id.edit_message); +} </pre> +</li> -<p class="note"><strong>Note:</strong> -You now need an import statement for <code>android.widget.EditText</code>. -You'll define the <code>EXTRA_MESSAGE</code> constant in a moment.</p> +<li>At the top of the file, import the {@link android.widget.EditText} class. + <p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p> +</li> -<p>An {@link android.content.Intent} can carry a collection of various data types as key-value +<li>Assign the text to a local <code>message</code> variable, and use the +{@link android.content.Intent#putExtra putExtra()} method to add its text value to the intent. +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> +<pre> +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); +} +</pre> + +<p>An {@link android.content.Intent} can carry data types as key-value pairs called <em>extras</em>. The {@link android.content.Intent#putExtra putExtra()} method takes the key name in the first parameter and the value in the second parameter.</p> -<p>In order for the next activity to query the extra data, you should define the key -for your intent's extra using a -public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code -MainActivity} class:</p> - +</li> +<li>At the top of the {@code MyActivity} class, add the {@code EXTRA_MESSAGE} definition as +follows: +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> <pre> -public class MainActivity extends ActionBarActivity { - public final static String EXTRA_MESSAGE = "com.example.myfirstapp.MESSAGE"; +public class MyActivity extends ActionBarActivity { + public final static String EXTRA_MESSAGE = "com.mycompany.myfirstapp.MESSAGE"; ... } </pre> -<p>It's generally a good practice to define keys for intent extras using your app's package name -as a prefix. This ensures they are unique, in case your app interacts with other apps.</p> +<p>For the next activity to query the extra data, you should define the key +for your intent's extra using a public constant. It's generally a good practice to define keys for +intent extras using your app's package name as a prefix. This ensures the keys are unique, in case +your app interacts with other apps.</p> +</li> +<!-- <h2 id="StartActivity">Start the Second Activity</h2> --> +<li>In the {@code sendMessage()} method, to finish the intent, call the +{@link android.app.Activity#startActivity startActivity()} method, passing it the +{@link android.content.Intent} object created in step 1. -<h2 id="StartActivity">Start the Second Activity</h2> - -<p>To start an activity, call {@link android.app.Activity#startActivity -startActivity()} and pass it your {@link android.content.Intent}. The system receives this call -and starts an instance of the {@link android.app.Activity} -specified by the {@link android.content.Intent}.</p> +</ol> <p>With this new code, the complete {@code sendMessage()} method that's invoked by the Send button now looks like this:</p> - +<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p> <pre> /** Called when the user clicks the Send button */ public void sendMessage(View view) { @@ -198,70 +234,92 @@ public void sendMessage(View view) { } </pre> -<p>Now you need to create the {@code DisplayMessageActivity} class in order for this to -work.</p> +<p>The system receives this call and starts an instance of the {@link android.app.Activity} +specified by the {@link android.content.Intent}. Now you need to create the +{@code DisplayMessageActivity} class in order for this to work.</p> +</li> +</ol> <h2 id="CreateActivity">Create the Second Activity</h2> +<p>All subclasses of {@link android.app.Activity} must implement the +{@link android.app.Activity#onCreate onCreate()} method. This method is where the activity receives +the intent with the message, then renders the message. Also, the +{@link android.app.Activity#onCreate onCreate()} method must define the activity +layout with the {@link android.app.Activity#setContentView setContentView()} method. This is where +the activity performs the initial setup of the activity components.</p> + +<h3>Create a new activity using Android Studio</h3> + <div class="figure" style="width:400px"> -<img src="{@docRoot}images/training/firstapp/adt-new-activity.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The new activity wizard in Eclipse.</p> +<img src="{@docRoot}images/training/firstapp/studio-new-activity.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The new activity wizard in Android Studio.</p> </div> -<p>To create a new activity using Eclipse:</p> +<p>Android Studio includes a stub for the +{@link android.app.Activity#onCreate onCreate()} method when you create a new activity.</p> <ol> - <li>Click <strong>New</strong> <img src="{@docRoot}images/tools/eclipse-new.png" - style="vertical-align:baseline;margin:0" /> in the toolbar.</li> - <li>In the window that appears, open the <strong>Android</strong> folder - and select <strong>Android Activity</strong>. Click <strong>Next</strong>.</li> - <li>Select <strong>BlankActivity</strong> and click <strong>Next</strong>.</li> - <li>Fill in the activity details: + <li>In Android Studio, in the <code>java</code> directory, select the package, + <strong>com.mycompany.myfirstapp</strong>, right-click, and select + <strong>New > Activity > Blank Activity</strong>.</li> + <li>In the <strong>Choose options</strong> window, fill in the activity details: <ul> - <li><strong>Project</strong>: MyFirstApp</li> <li><strong>Activity Name</strong>: DisplayMessageActivity</li> <li><strong>Layout Name</strong>: activity_display_message</li> - <li><strong>Fragment Layout Name</strong>: fragment_display_message</li> <li><strong>Title</strong>: My Message</li> - <li><strong>Hierarchial Parent</strong>: com.example.myfirstapp.MainActivity</li> - <li><strong>Navigation Type</strong>: None</li> + <li><strong>Hierarchical Parent</strong>: com.mycompany.myfirstapp.MyActivity</li> + <li><strong>Package name</strong>: com.mycompany.myfirstapp</li> </ul> <p>Click <strong>Finish</strong>.</p> </li> -</ol> - -<p>If you're using a different IDE or the command line tools, create a new file named -{@code DisplayMessageActivity.java} in the project's <code>src/</code> directory, next to -the original {@code MainActivity.java} file.</p> -<p>Open the {@code DisplayMessageActivity.java} file. If you used Eclipse to create this -activity:</p> -<ul> - <li>The class -already includes an implementation of the required {@link android.app.Activity#onCreate onCreate()} -method. You will update the implementation of this method later.</li> - <li>There's also an implementation of the {@link android.app.Activity#onCreateOptionsMenu -onCreateOptionsMenu()} method, but -you won't need it for this app so you can remove it.</li> - <li>There's also an implementation of {@link android.app.Activity#onOptionsItemSelected - onOptionsItemSelected()} which handles the behavior for the action bar's <em>Up</em> behavior. - Keep this one the way it is.</li> - <li>There's also a <code>PlaceholderFragment</code> class that extends -{@link android.app.Fragment}. You will not need this class in the final version of this -activity.</li> -</ul> - -<p>Fragments decompose application functionality and UI into reusable modules. For more -information on fragments, see the <a href="{@docRoot}guide/components/fragments.html">Fragments -API Guide</a>. The final version of this activity does not use fragments.</p> +<li>Open the {@code DisplayMessageActivity.java} file. + +<p>The class already includes an implementation of the required +{@link android.app.Activity#onCreate onCreate()} method. You will update the implementation of this +method later. It also includes an implementation of +{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}, which handles the action +bar's <em>Up</em> behavior. Keep these two methods as they are for now.</p> + +<!-- Android Studio does not create a Fragment placeholder +<p>Also, the file includes a <code>PlaceholderFragment</code> class that extends +{@link android.app.Fragment}. This activity does not implement fragments, but you might use this +later in the training. Fragments decompose application functionality and UI into reusable modules. +For more information on fragments, see the +<a href="{@docRoot}guide/components/fragments.html">Fragments API Guide</a> and follow the training, +<a href="{@docRoot}training/basics/fragments/index.html">Building A Dynamic UI with Fragments</a>. +</p> +--> +</li> + +<li> Remove the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method. +<p>You won't need it for this app.</p> +</li> +</ol> +<!-- Not needed for Android Studio <p class="note"><strong>Note:</strong> Your activity may look different if you did not use the latest version of the ADT plugin. Make sure you install the latest version of the <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT plugin</a> to complete this tutorial.</p> +--> + +<p>If you're developing with Android Studio, you can run the app now, but not much happens. +Clicking the Send button starts the second activity, but it uses +a default "Hello world" layout provided by the template. You'll soon update the +activity to instead display a custom text view.</p> + + +<h3>Create the activity without Android Studio</h3> -<p>The {@code DisplayMessageActivity} class should now look like this:</p> +<p>If you're using a different IDE or the command line tools, do the following:</p> + +<ol> +<li>Create a new file named {@code DisplayMessageActivity.java} in the project's <code>src/</code> +directory, next to the original {@code MyActivity.java} file.</li> +<li>Add the following code to the file: <pre> public class DisplayMessageActivity extends ActionBarActivity { @@ -307,63 +365,44 @@ public class DisplayMessageActivity extends ActionBarActivity { } </pre> -<p>If you used an IDE other than Eclipse, update your {@code DisplayMessageActivity} -class with the above code.</p> - -<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. This method is where you must define the activity layout -with the {@link android.app.Activity#setContentView setContentView()} method -and is where you should -perform initial setup for the activity components.</p> - -<p class="note"><strong>Note:</strong> If you are using an IDE other than Eclipse, your project +<p class="note"><strong>Note:</strong> If you are using an IDE other than Android Studio, your project does not contain the {@code activity_display_message} layout that's requested by {@link android.app.Activity#setContentView setContentView()}. That's OK because you will update this method later and won't be using that layout.</p> +</li> -<h3 id="AddTitle">Add the title string</h3> - -<p>If you used Eclipse, you can skip to the <a href="#AddToManifest">next section</a>, -because the template provides -the title string for the new activity.</p> - -<p>If you're using an IDE other than Eclipse, -add the new activity's title to the {@code strings.xml} file:</p> +<li>To your {@code strings.xml} file, add the new activity's title as follows: <pre> <resources> ... <string name="title_activity_display_message">My Message</string> </resources> </pre> +</li> - - -<h3 id="AddToManifest">Add it to the manifest</h3> - -<p>All activities must be declared 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>When you use the Eclipse tools to create the activity, it creates a default entry. If you're -using a different IDE, you need to add the manifest entry yourself. It should -look like this:</p> +<li>In your manifest file, <code>AndroidManifest.xml</code>, within the <code>Application</code> +element, add the +<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element +for your {@code DisplayMessageActivity} class, as follows: <pre> <application ... > ... <activity - android:name="com.example.myfirstapp.DisplayMessageActivity" + android:name="com.mycompany.myfirstapp.DisplayMessageActivity" android:label="@string/title_activity_display_message" - android:parentActivityName="com.example.myfirstapp.MainActivity" > + android:parentActivityName="com.mycompany.myfirstapp.MyActivity" > <meta-data android:name="android.support.PARENT_ACTIVITY" - android:value="com.example.myfirstapp.MainActivity" /> + android:value="com.mycompany.myfirstapp.MyActivity" /> </activity> </application> </pre> +</li> +</ol> + <p>The <a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code android:parentActivityName}</a> attribute declares the name of this activity's parent activity within the app's logical hierarchy. The system uses this value @@ -376,20 +415,16 @@ the <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> element as shown here.</p> <p class="note"><strong>Note:</strong> Your Android SDK should already include -the latest Android Support Library. It's included with the ADT Bundle but if you're using -a different IDE, you should have installed it during the -<a href="{@docRoot}sdk/installing/adding-packages.html">Adding Platforms and Packages</a> step. -When using the templates in Eclipse, the Support Library is automatically added to your app project +the latest Android Support Library, which you installed during the +<a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</a> step. +When using the templates in Android Studio, the Support Library is automatically added to your app project (you can see the library's JAR file listed under <em>Android Dependencies</em>). If you're not using -Eclipse, you need to manually add the library to your project—follow the guide for <a +Android Studio, you need to manually add the library to your project—follow the guide for <a href="{@docRoot}tools/support-library/setup.html">setting up the Support Library</a> then return here.</p> -<p>If you're developing with Eclipse, you can run the app now, but not much happens. -Clicking the Send button starts the second activity but it uses -a default "Hello world" layout provided by the template. You'll soon update the -activity to instead display a custom text view, so if you're using a different IDE, -don't worry that the app won't yet compile.</p> +<p>If you're using a different IDE than Android Studio, don't worry that the app won't yet compile. +You'll soon update the activity to display a custom text view.</p> <h2 id="ReceiveIntent">Receive the Intent</h2> @@ -397,24 +432,55 @@ don't worry that the app won't yet compile.</p> <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 retrieve the 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 MainActivity}:</p> +within the intent.</p> +<ol> +<li>In the <code>java/com.mycompany.myfirstapp</code> directory, edit the + {@code DisplayMessageActivity.java} file.</li> +<li>In the {@link android.app.Activity#onCreate onCreate()} method, remove the following line: +<pre> + setContentView(R.layout.activity_display_message); +</pre> +<li>Get the intent and assign it to a local variable. <pre> Intent intent = getIntent(); -String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE); </pre> - - +</li> +<li>At the top of the file, import the {@link android.content.Intent} class. + <p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p> +</li> +<li>Extract the message delivered by {@code MyActivity} with the +{@link android.content.Intent#getStringExtra getStringExtra()} method. +<pre> +String message = intent.getStringExtra(MyActivity.EXTRA_MESSAGE); +</pre> +</li> +</ol> <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> +<ol> +<li>In the {@link android.app.Activity#onCreate onCreate()} method, create a {@link android.widget.TextView} object. +<pre> +TextView textView = new TextView(this); +</pre> +</li> +<li>Set the text size and message with {@link android.widget.TextView#setText setText()}. +<pre> +textView.setTextSize(40); +textView.setText(message); +</pre> +</li> +<li>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()}. +<pre> +setContentView(textView); +</pre> +</li> +<li>At the top of the file, import the {@link android.widget.TextView} class. + <p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p> +</li> +</ol> <p>The complete {@link android.app.Activity#onCreate onCreate()} method for {@code DisplayMessageActivity} now looks like this:</p> @@ -426,7 +492,7 @@ public void onCreate(Bundle savedInstanceState) { // Get the message from the intent Intent intent = getIntent(); - String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE); + String message = intent.getStringExtra(MyActivity.EXTRA_MESSAGE); // Create the text view TextView textView = new TextView(this); |