From e04c4543027df129cd7c004c1b21b01a7f4928ad Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 18 Jun 2013 21:16:25 -0700 Subject: update action bar guide for support lib ABC Change-Id: Ie4594b3a0e0a686ed37d858788c7c747a1ee09e0 --- docs/html/design/building-blocks/tabs.jd | 2 +- docs/html/design/media/tabs_youtube.png | Bin 28290 -> 26073 bytes docs/html/design/patterns/actionbar.jd | 2 +- docs/html/design/patterns/navigation.jd | 2 +- .../html/guide/topics/manifest/activity-element.jd | 487 +++--- docs/html/guide/topics/ui/actionbar.jd | 1676 ++++++++++---------- .../practices/actionbar-phone-splitaction.png | Bin 19263 -> 18267 bytes .../practices/actionbar-phone-splitaction@2x.png | Bin 0 -> 55045 bytes docs/html/images/ui/actionbar-dropdown.png | Bin 0 -> 13154 bytes docs/html/images/ui/actionbar-dropdown@2x.png | Bin 0 -> 30740 bytes docs/html/images/ui/actionbar-item-withtext.png | Bin 10762 -> 9258 bytes docs/html/images/ui/actionbar-searchview.png | Bin 16780 -> 13153 bytes docs/html/images/ui/actionbar-searchview@2x.png | Bin 0 -> 33585 bytes docs/html/images/ui/actionbar-shareaction.png | Bin 70953 -> 118031 bytes docs/html/images/ui/actionbar-shareaction@2x.png | Bin 0 -> 362277 bytes docs/html/images/ui/actionbar-splitaction.png | Bin 0 -> 23051 bytes docs/html/images/ui/actionbar-splitaction@2x.png | Bin 0 -> 68147 bytes docs/html/images/ui/actionbar-stacked.png | Bin 11616 -> 0 bytes docs/html/images/ui/actionbar-tabs-stacked.png | Bin 0 -> 6622 bytes docs/html/images/ui/actionbar-tabs-stacked@2x.png | Bin 0 -> 16407 bytes docs/html/images/ui/actionbar-tabs.png | Bin 7905 -> 10327 bytes docs/html/images/ui/actionbar-tabs@2x.png | Bin 0 -> 29079 bytes docs/html/images/ui/actionbar-up.png | Bin 0 -> 5961 bytes docs/html/images/ui/actionbar.png | Bin 16685 -> 69537 bytes docs/html/images/ui/actionbar@2x.png | Bin 0 -> 212361 bytes 25 files changed, 1108 insertions(+), 1061 deletions(-) create mode 100644 docs/html/images/practices/actionbar-phone-splitaction@2x.png create mode 100644 docs/html/images/ui/actionbar-dropdown.png create mode 100644 docs/html/images/ui/actionbar-dropdown@2x.png create mode 100644 docs/html/images/ui/actionbar-searchview@2x.png create mode 100644 docs/html/images/ui/actionbar-shareaction@2x.png create mode 100644 docs/html/images/ui/actionbar-splitaction.png create mode 100644 docs/html/images/ui/actionbar-splitaction@2x.png delete mode 100644 docs/html/images/ui/actionbar-stacked.png create mode 100644 docs/html/images/ui/actionbar-tabs-stacked.png create mode 100644 docs/html/images/ui/actionbar-tabs-stacked@2x.png create mode 100644 docs/html/images/ui/actionbar-tabs@2x.png create mode 100644 docs/html/images/ui/actionbar-up.png create mode 100644 docs/html/images/ui/actionbar@2x.png diff --git a/docs/html/design/building-blocks/tabs.jd b/docs/html/design/building-blocks/tabs.jd index 4778400..2bc90ab 100644 --- a/docs/html/design/building-blocks/tabs.jd +++ b/docs/html/design/building-blocks/tabs.jd @@ -53,7 +53,7 @@ to the next/previous view, swipe left or right.

- Tabs in the YouTube app. + Tabs in the Google Play Movies app.
diff --git a/docs/html/design/media/tabs_youtube.png b/docs/html/design/media/tabs_youtube.png index 4ea6c1c..a4c1ae5 100644 Binary files a/docs/html/design/media/tabs_youtube.png and b/docs/html/design/media/tabs_youtube.png differ diff --git a/docs/html/design/patterns/actionbar.jd b/docs/html/design/patterns/actionbar.jd index 6020034..ceb5a4c 100644 --- a/docs/html/design/patterns/actionbar.jd +++ b/docs/html/design/patterns/actionbar.jd @@ -123,7 +123,7 @@ the top bar.

-

Action Buttons

+

Action Buttons

Action buttons on the action bar surface your app's most important activities. Think about which buttons will get used most often, and order them accordingly. Depending on available screen real estate, the system shows your most important actions as action buttons and moves the rest to the diff --git a/docs/html/design/patterns/navigation.jd b/docs/html/design/patterns/navigation.jd index 4da87b9..6f2215a 100644 --- a/docs/html/design/patterns/navigation.jd +++ b/docs/html/design/patterns/navigation.jd @@ -1,5 +1,5 @@ page.title=Navigation with Back and Up -page.tags="navigation","activity","task" +page.tags="navigation","activity","task","up navigation","back navigation" @jd:body diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index adc795d..8df1fdf 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -54,85 +54,85 @@ parent.link=manifest-intro.html
<meta-data>

description:
-
Declares an activity (an {@link android.app.Activity} subclass) that -implements part of the application's visual user interface. All activities -must be represented by {@code <activity>} -elements in the manifest file. Any that are not declared there will not be seen +
Declares an activity (an {@link android.app.Activity} subclass) that +implements part of the application's visual user interface. All activities +must be represented by {@code <activity>} +elements in the manifest file. Any that are not declared there will not be seen by the system and will never be run.
attributes:
{@code android:allowTaskReparenting}
-
Whether or not the activity can move from the task that started it to -the task it has an affinity for when that task is next brought to the -front — "{@code true}" if it can move, and "{@code false}" if it -must remain with the task where it started. +
Whether or not the activity can move from the task that started it to +the task it has an affinity for when that task is next brought to the +front — "{@code true}" if it can move, and "{@code false}" if it +must remain with the task where it started.

-If this attribute is not set, the value set by the corresponding +If this attribute is not set, the value set by the corresponding allowTaskReparenting -attribute of the <application> element +attribute of the <application> element applies to the activity. The default value is "{@code false}".

-Normally when an activity is started, it's associated with the task of -the activity that started it and it stays there for its entire lifetime. -You can use this attribute to force it to be re-parented to the task it -has an affinity for when its current task is no longer displayed. -Typically, it's used to cause the activities of an application to move +Normally when an activity is started, it's associated with the task of +the activity that started it and it stays there for its entire lifetime. +You can use this attribute to force it to be re-parented to the task it +has an affinity for when its current task is no longer displayed. +Typically, it's used to cause the activities of an application to move to the main task associated with that application.

-For example, if an e-mail message contains a link to a web page, clicking -the link brings up an activity that can display the page. That activity -is defined by the browser application, but is launched as part of the e-mail -task. If it's reparented to the browser task, it will be shown when the -browser next comes to the front, and will be absent when the e-mail task +For example, if an e-mail message contains a link to a web page, clicking +the link brings up an activity that can display the page. That activity +is defined by the browser application, but is launched as part of the e-mail +task. If it's reparented to the browser task, it will be shown when the +browser next comes to the front, and will be absent when the e-mail task again comes forward.

-The affinity of an activity is defined by the -taskAffinity attribute. The affinity +The affinity of an activity is defined by the +taskAffinity attribute. The affinity of a task is determined by reading the affinity of its root activity. Therefore, by definition, a root activity is always in a task with the -same affinity. Since activities with "{@code singleTask}" or +same affinity. Since activities with "{@code singleTask}" or "{@code singleInstance}" launch modes can only be at the root of a task, -re-parenting is limited to the "{@code standard}" and "{@code singleTop}" -modes. (See also the launchMode +re-parenting is limited to the "{@code standard}" and "{@code singleTop}" +modes. (See also the launchMode attribute.)

{@code android:alwaysRetainTaskState}
-
Whether or not the state of the task that the activity is in will always -be maintained by the system — "{@code true}" if it will be, and -"{@code false}" if the system is allowed to reset the task to its initial -state in certain situations. The default value is "{@code false}". This -attribute is meaningful only for the root activity of a task; it's ignored +
Whether or not the state of the task that the activity is in will always +be maintained by the system — "{@code true}" if it will be, and +"{@code false}" if the system is allowed to reset the task to its initial +state in certain situations. The default value is "{@code false}". This +attribute is meaningful only for the root activity of a task; it's ignored for all other activities.

-Normally, the system clears a task (removes all activities from the stack -above the root activity) in certain situations when the user re-selects that -task from the home screen. Typically, this is done if the user hasn't visited +Normally, the system clears a task (removes all activities from the stack +above the root activity) in certain situations when the user re-selects that +task from the home screen. Typically, this is done if the user hasn't visited the task for a certain amount of time, such as 30 minutes.

-However, when this attribute is "{@code true}", users will always return -to the task in its last state, regardless of how they get there. This is -useful, for example, in an application like the web browser where there is +However, when this attribute is "{@code true}", users will always return +to the task in its last state, regardless of how they get there. This is +useful, for example, in an application like the web browser where there is a lot of state (such as multiple open tabs) that users would not like to lose.

{@code android:clearTaskOnLaunch}
-
Whether or not all activities will be removed from the task, except for -the root activity, whenever it is re-launched from the home screen — -"{@code true}" if the task is always stripped down to its root activity, and -"{@code false}" if not. The default value is "{@code false}". This attribute -is meaningful only for activities that start a new task (the root activity); +
Whether or not all activities will be removed from the task, except for +the root activity, whenever it is re-launched from the home screen — +"{@code true}" if the task is always stripped down to its root activity, and +"{@code false}" if not. The default value is "{@code false}". This attribute +is meaningful only for activities that start a new task (the root activity); it's ignored for all other activities in the task.

@@ -140,24 +140,24 @@ When the value is "{@code true}", every time users start the task again, they are brought to its root activity regardless of what they were last doing in the task and regardless of whether they used the Back or Home button to leave it. When the value is "{@code false}", the task may be cleared of activities in -some situations (see the -alwaysRetainTaskState attribute), but not always. +some situations (see the +alwaysRetainTaskState attribute), but not always.

-Suppose, for example, that someone launches activity P from the home screen, -and from there goes to activity Q. The user next presses Home, and then returns -to activity P. Normally, the user would see activity Q, since that is what they -were last doing in P's task. However, if P set this flag to "{@code true}", all -of the activities on top of it (Q in this case) were removed when the user pressed -Home and the task went to the background. So the user sees only P when returning +Suppose, for example, that someone launches activity P from the home screen, +and from there goes to activity Q. The user next presses Home, and then returns +to activity P. Normally, the user would see activity Q, since that is what they +were last doing in P's task. However, if P set this flag to "{@code true}", all +of the activities on top of it (Q in this case) were removed when the user pressed +Home and the task went to the background. So the user sees only P when returning to the task.

-If this attribute and allowTaskReparenting -are both "{@code true}", any activities that can be re-parented are moved to -the task they share an affinity with; the remaining activities are then dropped, +If this attribute and allowTaskReparenting +are both "{@code true}", any activities that can be re-parented are moved to +the task they share an affinity with; the remaining activities are then dropped, as described above.

@@ -169,7 +169,7 @@ activity remains running and its {@link android.app.Activity#onConfigurati onConfigurationChanged()} method is called.

Note: Using this attribute should be -avoided and used only as a last-resort. Please read Handling Runtime Changes for more information about how to properly handle a restart due to a configuration change.

@@ -220,11 +220,11 @@ separated by '{@code |}' — for example, "{@code locale|navigation|orientat "{@code uiMode}" The user interface mode has changed — this can be caused when the user places the device into a desk/car dock or when the night mode changes. See {@link -android.app.UiModeManager}. +android.app.UiModeManager}. Added in API level 8. "{@code orientation}" - The screen orientation has changed — the user has rotated the device. + The screen orientation has changed — the user has rotated the device.

Note: If your application targets API level 13 or higher (as declared by the {@code minSdkVersion} and {@code @@ -258,70 +258,70 @@ restart your activity, even when running on an Android 3.2 or higher device).

-All of these configuration changes can impact the resource values seen by the -application. Therefore, when {@link android.app.Activity#onConfigurationChanged -onConfigurationChanged()} is called, it will generally be necessary to again -retrieve all resources (including view layouts, drawables, and so on) to correctly -handle the change. +All of these configuration changes can impact the resource values seen by the +application. Therefore, when {@link android.app.Activity#onConfigurationChanged +onConfigurationChanged()} is called, it will generally be necessary to again +retrieve all resources (including view layouts, drawables, and so on) to correctly +handle the change.

{@code android:enabled}
-
Whether or not the activity can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value +
Whether or not the activity can be instantiated by the system — +"{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}".

-The <application> element has its own -enabled -attribute that applies to all application components, including activities. The -<application> -and {@code <activity>} attributes must both be "{@code true}" (as they both -are by default) for the system to be able to instantiate the activity. If either +The <application> element has its own +enabled +attribute that applies to all application components, including activities. The +<application> +and {@code <activity>} attributes must both be "{@code true}" (as they both +are by default) for the system to be able to instantiate the activity. If either is "{@code false}", it cannot be instantiated.

{@code android:excludeFromRecents}
Whether or not the task initiated by this activity should be excluded from the list of recently used applications ("recent apps"). That is, when this activity is the root activity of a new task, -this attribute determines whether the task should not appear in the list of recent apps. "{@code -true}" if the task should be excluded from the list; "{@code false}" if it should be +this attribute determines whether the task should not appear in the list of recent apps. Set "{@code +true}" if the task should be excluded from the list; set "{@code false}" if it should be included. The default value is "{@code false}".

{@code android:exported}
-
Whether or not the activity can be launched by components of other -applications — "{@code true}" if it can be, and "{@code false}" if not. -If "{@code false}", the activity can be launched only by components of the -same application or applications with the same user ID. +
Whether or not the activity can be launched by components of other +applications — "{@code true}" if it can be, and "{@code false}" if not. +If "{@code false}", the activity can be launched only by components of the +same application or applications with the same user ID.

-The default value depends on whether the activity contains intent filters. The -absence of any filters means that the activity can be invoked only by specifying -its exact class name. This implies that the activity is intended only for -application-internal use (since others would not know the class name). So in +The default value depends on whether the activity contains intent filters. The +absence of any filters means that the activity can be invoked only by specifying +its exact class name. This implies that the activity is intended only for +application-internal use (since others would not know the class name). So in this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the activity +On the other hand, the presence of at least one filter implies that the activity is intended for external use, so the default value is "{@code true}".

This attribute is not the only way to limit an activity's exposure to other -applications. You can also use a permission to limit the external entities that -can invoke the activity (see the -permission +applications. You can also use a permission to limit the external entities that +can invoke the activity (see the +permission attribute).

{@code android:finishOnTaskLaunch}
-
Whether or not an existing instance of the activity should be shut down -(finished) whenever the user again launches its task (chooses the task on the -home screen) — "{@code true}" if it should be shut down, and "{@code false}" +
Whether or not an existing instance of the activity should be shut down +(finished) whenever the user again launches its task (chooses the task on the +home screen) — "{@code true}" if it should be shut down, and "{@code false}" if not. The default value is "{@code false}".

-If this attribute and -allowTaskReparenting -are both "{@code true}", this attribute trumps the other. The affinity of the +If this attribute and +allowTaskReparenting +are both "{@code true}", this attribute trumps the other. The affinity of the activity is ignored. The activity is not re-parented, but destroyed.

@@ -346,58 +346,58 @@ make use of the renderer without errors.

{@code android:icon}
-
An icon representing the activity. The icon is displayed to users when -a representation of the activity is required on-screen. For example, icons -for activities that initiate tasks are displayed in the launcher window. +
An icon representing the activity. The icon is displayed to users when +a representation of the activity is required on-screen. For example, icons +for activities that initiate tasks are displayed in the launcher window. The icon is often accompanied by a label (see the {@code android:label} attribute).

-This attribute must be set as a reference to a drawable resource containing -the image definition. If it is not set, the icon specified for the application -as a whole is used instead (see the -<application> +This attribute must be set as a reference to a drawable resource containing +the image definition. If it is not set, the icon specified for the application +as a whole is used instead (see the +<application> element's icon attribute).

-The activity's icon — whether set here or by the -<application> -element — is also the default icon for all the activity's intent filters (see the -<intent-filter> element's -icon attribute). +The activity's icon — whether set here or by the +<application> +element — is also the default icon for all the activity's intent filters (see the +<intent-filter> element's +icon attribute).

{@code android:label}
-
A user-readable label for the activity. The label is displayed on-screen -when the activity must be represented to the user. It's often displayed along +
A user-readable label for the activity. The label is displayed on-screen +when the activity must be represented to the user. It's often displayed along with the activity icon.

-If this attribute is not set, the label set for the application as a whole is -used instead (see the <application> element's +If this attribute is not set, the label set for the application as a whole is +used instead (see the <application> element's label attribute).

-The activity's label — whether set here or by the -<application> element — is also the -default label for all the activity's intent filters (see the -<intent-filter> element's -label attribute). +The activity's label — whether set here or by the +<application> element — is also the +default label for all the activity's intent filters (see the +<intent-filter> element's +label attribute).

The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string.

{@code android:launchMode}
An instruction on how the activity should be launched. There are four modes -that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) +that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) in {@link android.content.Intent} objects to determine what should happen when the activity is called upon to handle an intent. They are:

@@ -417,7 +417,7 @@ As shown in the table below, the modes fall into two main groups, with An activity with the "{@code standard}" or "{@code singleTop}" launch mode can be instantiated multiple times. The instances can belong to any task and can be located anywhere in the activity stack. Typically, they're -launched into the task that called +launched into the task that called {@link android.content.Context#startActivity startActivity()} (unless the Intent object contains a {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} @@ -433,7 +433,7 @@ Moreover, the device can hold only one instance of the activity at a time

-The "{@code standard}" and "{@code singleTop}" modes differ from each other +The "{@code standard}" and "{@code singleTop}" modes differ from each other in just one respect: Every time there's a new intent for a "{@code standard}" activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. @@ -509,41 +509,41 @@ common and useful launch mode for many types of activities. The other modes — singleTask and singleInstance — are not appropriate for most applications, since they result in an interaction model that is likely to be unfamiliar to -users and is very different from most other applications. +users and is very different from most other applications.

Regardless of the launch mode that you choose, make sure to test the usability of the activity during launch and when navigating back to it from other activities and tasks using the Back button.

For more information on launch modes and their interaction with Intent -flags, see the +flags, see the Tasks and Back Stack document.

{@code android:multiprocess}
-
Whether an instance of the activity can be launched into the process of the component -that started it — "{@code true}" if it can be, and "{@code false}" if not. +
Whether an instance of the activity can be launched into the process of the component +that started it — "{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code false}".

-Normally, a new instance of an activity is launched into the process of the -application that defined it, so all instances of the activity run in the same -process. However, if this flag is set to "{@code true}", instances of the -activity can run in multiple processes, allowing the system to create instances -wherever they are used (provided permissions allow it), something that is almost +Normally, a new instance of an activity is launched into the process of the +application that defined it, so all instances of the activity run in the same +process. However, if this flag is set to "{@code true}", instances of the +activity can run in multiple processes, allowing the system to create instances +wherever they are used (provided permissions allow it), something that is almost never necessary or desirable.

{@code android:name}
-
The name of the class that implements the activity, a subclass of -{@link android.app.Activity}. The attribute value should be a fully qualified -class name (such as, "{@code com.example.project.ExtracurricularActivity}"). -However, as a shorthand, if the first character of the name is a period -(for example, "{@code .ExtracurricularActivity}"), it is appended to the -package name specified in the -<manifest> +
The name of the class that implements the activity, a subclass of +{@link android.app.Activity}. The attribute value should be a fully qualified +class name (such as, "{@code com.example.project.ExtracurricularActivity}"). +However, as a shorthand, if the first character of the name is a period +(for example, "{@code .ExtracurricularActivity}"), it is appended to the +package name specified in the +<manifest> element.

Once you publish your application, you should not @@ -557,9 +557,9 @@ There is no default. The name must be specified.

{@code android:noHistory}
Whether or not the activity should be removed from the activity stack and -finished (its {@link android.app.Activity#finish finish()} -method called) when the user navigates away from it and it's no longer -visible on screen — "{@code true}" if it should be finished, and +finished (its {@link android.app.Activity#finish finish()} +method called) when the user navigates away from it and it's no longer +visible on screen — "{@code true}" if it should be finished, and "{@code false}" if not. The default value is "{@code false}".

@@ -575,14 +575,33 @@ This attribute was introduced in API Level 3.

{@code android:parentActivityName}
-
The class name of the logical parent of the activity. The name here must be formatted - the same as the corresponding activity is declared in its own - android:name. - +
The class name of the logical parent of the activity. The name here must match the class + name given to the corresponding {@code <activity>} element's + android:name attribute. +

The system reads this attribute to determine which activity should be started when the use presses the Up button in the action bar. The system can also use this information to synthesize a back stack of activities with {@link android.app.TaskStackBuilder}.

+

To support API levels 4 - 16, you can also declare the parent activity with a {@code +<meta-data>} element that specifies a value for {@code "android.support.PARENT_ACTIVITY"}. +For example:

+
+<activity
+    android:name="com.example.app.ChildActivity"
+    android:label="@string/title_child_activity"
+    android:parentActivityName="com.example.myfirstapp.MainActivity" >
+    <!-- Parent activity meta-data to support API level 4+ -->
+    <meta-data
+        android:name="android.support.PARENT_ACTIVITY"
+        android:value="com.example.app.MainActivity" />
+</activity>
+
+ +

For more information about declaring the parent activity to support Up navigation, +read Providing Up +Navigation.

+

This attribute was introduced in API Level 16.

@@ -591,63 +610,67 @@ This attribute was introduced in API Level 16.
{@code android:permission}
-
The name of a permission that clients must have to launch the activity -or otherwise get it to respond to an intent. If a caller of +
The name of a permission that clients must have to launch the activity +or otherwise get it to respond to an intent. If a caller of {@link android.content.Context#startActivity startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()} -has not been granted the specified permission, its intent will not be +has not been granted the specified permission, its intent will not be delivered to the activity.

-If this attribute is not set, the permission set by the -<application> +If this attribute is not set, the permission set by the +<application> element's -permission +permission attribute applies to the activity. If neither attribute is set, the activity is not protected by a permission.

-For more information on permissions, see the -Permissions -section in the introduction and another document, +For more information on permissions, see the +Permissions +section in the introduction and another document, Security and Permissions.

{@code android:process}
-
The name of the process in which the activity should run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The <application> element's -process -attribute can set a different default for all components. But each component -can override the default, allowing you to spread your application across +
The name of the process in which the activity should run. Normally, all components of an +application run in a default process name created for the application and you do +not need to use this attribute. But if necessary, you can override the default process +name with this attribute, allowing you to spread your app components across multiple processes.

-If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and +If the name assigned to this attribute begins with a colon (':'), a new +process, private to the application, is created when it's needed and the activity runs in that process. -If the process name begins with a lowercase character, the activity will run +If the process name begins with a lowercase character, the activity will run in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing +This allows components in different applications to share a process, reducing resource usage. -

+

+ +

The <application> element's +process +attribute can set a different default process name for all components. +

{@code android:screenOrientation}
-
The orientation of the activity's display on the device. - +
The orientation of the activity's display on the device. +

The value can be any one of the following strings:

- @@ -736,76 +759,76 @@ control whether your app can be installed when a device supports only certain or
{@code android:stateNotNeeded}
-
Whether or not the activity can be killed and successfully restarted -without having saved its state — "{@code true}" if it can be restarted -without reference to its previous state, and "{@code false}" if its previous +
Whether or not the activity can be killed and successfully restarted +without having saved its state — "{@code true}" if it can be restarted +without reference to its previous state, and "{@code false}" if its previous state is required. The default value is "{@code false}".

-Normally, before an activity is temporarily shut down to save resources, its -{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} -method is called. This method stores the current state of the activity in a -{@link android.os.Bundle} object, which is then passed to -{@link android.app.Activity#onCreate onCreate()} when the activity -is restarted. If this attribute is set to "{@code true}", -{@code onSaveInstanceState()} may not be called and {@code onCreate()} will -be passed {@code null} instead of the Bundle — just as it was when the +Normally, before an activity is temporarily shut down to save resources, its +{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +method is called. This method stores the current state of the activity in a +{@link android.os.Bundle} object, which is then passed to +{@link android.app.Activity#onCreate onCreate()} when the activity +is restarted. If this attribute is set to "{@code true}", +{@code onSaveInstanceState()} may not be called and {@code onCreate()} will +be passed {@code null} instead of the Bundle — just as it was when the activity started for the first time.

-A "{@code true}" setting ensures that the activity can be restarted in the -absence of retained state. For example, the activity that displays the -home screen uses this setting to make sure that it does not get removed if it +A "{@code true}" setting ensures that the activity can be restarted in the +absence of retained state. For example, the activity that displays the +home screen uses this setting to make sure that it does not get removed if it crashes for some reason.

{@code android:taskAffinity}
-
The task that the activity has an affinity for. Activities with +
The task that the activity has an affinity for. Activities with the same affinity conceptually belong to the same task (to the same -"application" from the user's perspective). The affinity of a task -is determined by the affinity of its root activity. +"application" from the user's perspective). The affinity of a task +is determined by the affinity of its root activity.

-The affinity determines two things — the task that the activity is re-parented -to (see the allowTaskReparenting -attribute) and the task that will house the activity when it is launched -with the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} +The affinity determines two things — the task that the activity is re-parented +to (see the allowTaskReparenting +attribute) and the task that will house the activity when it is launched +with the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag.

By default, all activities in an application have the same affinity. You can set this attribute to group them differently, and even place -activities defined in different applications within the same task. To +activities defined in different applications within the same task. To specify that the activity does not have an affinity for any task, set it to an empty string.

-If this attribute is not set, the activity inherits the affinity set -for the application (see the -<application> -element's +If this attribute is not set, the activity inherits the affinity set +for the application (see the +<application> +element's taskAffinity -attribute). The name of the default affinity for an application is -the package name set by the -<manifest> +attribute). The name of the default affinity for an application is +the package name set by the +<manifest> element.

{@code android:theme}
-
A reference to a style resource defining an overall theme for the activity. +
A reference to a style resource defining an overall theme for the activity. This automatically sets the activity's context to use this theme (see -{@link android.content.Context#setTheme setTheme()}, and may also -cause "starting" animations prior to the activity being launched (to better +{@link android.content.Context#setTheme setTheme()}, and may also +cause "starting" animations prior to the activity being launched (to better match what the activity actually looks like).

-If this attribute is not set, the activity inherits the theme set for the -application as a whole — from the -<application> -element's -theme +If this attribute is not set, the activity inherits the theme set for the +application as a whole — from the +<application> +element's +theme attribute. If that attribute is also not set, the default system theme is used. For more information, see the Styles and Themes developer guide. @@ -837,32 +860,32 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar developer guide.<

{@code android:windowSoftInputMode}
-
How the main window of the activity interacts with the window containing -the on-screen soft keyboard. The setting for this attribute affects two -things: +
How the main window of the activity interacts with the window containing +the on-screen soft keyboard. The setting for this attribute affects two +things: -
    -
  • The state of the soft keyboard — whether it is hidden or visible +
      +
    • The state of the soft keyboard — whether it is hidden or visible — when the activity becomes the focus of user attention.
      • -
    • The adjustment made to the activity's main window — whether it is -resized smaller to make room for the soft keyboard or whether its contents -pan to make the current focus visible when part of the window is covered by +
    • The adjustment made to the activity's main window — whether it is +resized smaller to make room for the soft keyboard or whether its contents +pan to make the current focus visible when part of the window is covered by the soft keyboard.

    -The setting must be one of the values listed in the following table, or a -combination of one "{@code state...}" value plus one "{@code adjust...}" -value. Setting multiple values in either group — multiple -"{@code state...}" values, for example — has undefined results. +The setting must be one of the values listed in the following table, or a +combination of one "{@code state...}" value plus one "{@code adjust...}" +value. Setting multiple values in either group — multiple +"{@code state...}" values, for example — has undefined results. Individual values are separated by a vertical bar ({@code |}). For example: 

    <activity android:windowSoftInputMode="stateVisible|adjustResize" . . . >

    -Values set here (other than "{@code stateUnspecified}" and +Values set here (other than "{@code stateUnspecified}" and "{@code adjustUnspecified}") override values set in the theme.

    @@ -872,9 +895,9 @@ Values set here (other than "{@code stateUnspecified}" and
- - - - - - - @@ -938,12 +961,12 @@ This attribute was introduced in API Level 3.
introduced in:
-
API Level 1 for all attributes except for +
API Level 1 for all attributes except for noHistory and -windowSoftInputMode, which were added in API +windowSoftInputMode, which were added in API Level 3.
see also:
-
<application> +
<application>
<activity-alias>
diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index c5bbdbc..23ef518 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -4,6 +4,14 @@ parent.title=User Interface parent.link=index.html @jd:body + + +
+

Design Guide

+

Action Bar

+
+ + -

The action bar is a window feature that identifies the application and user location, and -provides user actions and navigation modes. You should use the action bar in most activities that -need to prominently present user actions or global navigation, because the action bar offers users a -consistent interface across applications and the system gracefully adapts the action bar's -appearance for different screen configurations. You can control the behaviors and visibility of the -action bar with the {@link android.app.ActionBar} APIs, which were added in Android 3.0 (API level -11).

+

The action bar is a window feature that identifies the user location, and +provides user actions and navigation modes. Using the action bar offers your users a +familiar interface across applications that the system gracefully adapts +for different screen configurations.

-

The primary goals of the action bar are to:

+ +

Figure 1. An action bar that includes the [1] app icon, +[2] two action items, and [3] action overflow.

-
"{@code unspecified}" The default value. The system chooses the orientation. The policy it - uses, and therefore the choices made in specific contexts, may differ + uses, and therefore the choices made in specific contexts, may differ from device to device.
"{@code behind}"The same orientation as the activity that's immediately beneath it in + The same orientation as the activity that's immediately beneath it in the activity stack.
"{@code landscape}" Description
"{@code stateUnspecified}"The state of the soft keyboard (whether it is hidden or visible) + The state of the soft keyboard (whether it is hidden or visible) is not specified. The system will choose an appropriate state or - rely on the setting in the theme. + rely on the setting in the theme.

This is the default setting for the behavior of the soft keyboard. @@ -885,32 +908,32 @@ Values set here (other than "{@code stateUnspecified}" and whether visible or hidden, when the activity comes to the fore.
"{@code stateHidden}"The soft keyboard is hidden when the user chooses the activity - — that is, when the user affirmatively navigates forward to the + The soft keyboard is hidden when the user chooses the activity + — that is, when the user affirmatively navigates forward to the activity, rather than backs into it because of leaving another activity.
"{@code stateAlwaysHidden}"The soft keyboard is always hidden when the activity's main window + The soft keyboard is always hidden when the activity's main window has input focus.
"{@code stateVisible}"The soft keyboard is visible when that's normally appropriate + The soft keyboard is visible when that's normally appropriate (when the user is navigating forward to the activity's main window).
"{@code stateAlwaysVisible}"The soft keyboard is made visible when the user chooses the - activity — that is, when the user affirmatively navigates forward - to the activity, rather than backs into it because of leaving another + The soft keyboard is made visible when the user chooses the + activity — that is, when the user affirmatively navigates forward + to the activity, rather than backs into it because of leaving another activity.
"{@code adjustUnspecified}"It is unspecified whether the activity's main window resizes - to make room for the soft keyboard, or whether the contents - of the window pan to make the currentfocus visible on-screen. + It is unspecified whether the activity's main window resizes + to make room for the soft keyboard, or whether the contents + of the window pan to make the current focus visible on-screen. The system will automatically select one of these modes depending - on whether the content of the window has any layout views that - can scroll their contents. If there is such a view, the window - will be resized, on the assumption that scrolling can make all + on whether the content of the window has any layout views that + can scroll their contents. If there is such a view, the window + will be resized, on the assumption that scrolling can make all of the window's contents visible within a smaller area.

@@ -918,14 +941,14 @@ Values set here (other than "{@code stateUnspecified}" and

"{@code adjustResize}"The activity's main window is always resized to make room for + The activity's main window is always resized to make room for the soft keyboard on screen.
"{@code adjustPan}" The activity's main window is not resized to make room for the soft - keyboard. Rather, the contents of the window are automatically + keyboard. Rather, the contents of the window are automatically panned so that the current focus is never obscured by the keyboard - and users can always see what they are typing. This is generally less + and users can always see what they are typing. This is generally less desirable than resizing, because the user may need to close the soft keyboard to get at and interact with obscured parts of the window.