tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
base/docs/html/guide/practices/compatibility.jd Normal file
View File

@ -0,0 +1,247 @@
page.title=Android Compatibility
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>See also</h2>
<ol>
<li><a
href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li>
<li><a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing Alternative Resources</a></li>
<li><a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
<li style="margin-top:3px;"><code><a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</code></a></li>
</ol>
</div> </div>
<p>Android is designed to run on many different types of devices. For
developers, the range and number of devices means a huge potential audience: the
more devices that run Android apps, the more users who can access your app. In
exchange, however, it also means that your apps will have to cope with that same
variety of hardware.</p>
<p>Fortunately, Android has built-in tools and support that make it easy for
your apps to do that, while at the same time letting you maintain control of
what types of devices your app is available to. With a bit of forethought and
some minor changes in your app's manifest file, you can ensure that users
whose devices can’t run your app will never see it in the Android Market, and
will not get in trouble by downloading it. This page explains how you can
control which devices have access to your apps, and how to prepare your apps to
make sure they reach the right audience.</p>
<h3 id="defined">What does “compatibility” mean?</h3>
<p>A device is “Android compatible” if it can correctly run apps written for the
<em>Android execution environment</em>. The exact details of the Android execution
environment</em> are defined by the Android Compatibility Definition Document,
but the single most important characteristic of a compatible device is the
ability to install and correctly run an Android <code>.apk</code> file.</p>
<p>There is exactly one Android API for each <a
href="{@docRoot}guide/appendix/api-levels.html">API level</a>, and it’s the same
API no matter what kind of device it’s installed on. No parts of the API are
optional, and you never have to worry about parts of the API missing on some
devices. Every compatible Android device your app will land on will include
every class and every API for that API level.</p>
<p>Of course, some APIs won’t work correctly if a particular device lacks the
corresponding hardware or feature. But that’s not a problem: we also designed
Android to prevent apps from being visible to devices which don’t have features
the apps require. We’ve built support for this right into the SDK tools, and
it’s part of the Android platform itself, as well as Android Market.</p>
<p>As a developer, you have complete control of how and where your apps are
available. Android provides tools as a first-class part of the platform that let
you manage this. You control the availability of your apps, so that they reach
only the devices capable of running them.</p>
<h3 id="how">How does it work?</h3>
<p>You manage your app’s availability through a simple three-step process:</p>
<ol>
<li>You state the features your app requires by declaring <a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code>&lt;uses-feature&gt;</code></a>
elements its manifest file.</li>
<li>Devices are required to declare the features they include to Android
Market.</li>
<li>Android Market uses your app’s stated requirements to filter it from devices
that don’t meet those requirements.</li>
</ol>
<p>This way, users never even see apps that won’t work properly on their
devices. As long as you accurately describe your app’s requirements, you don’t
need to worry about users blaming you for compatibility problems.</p>
<p>If you’re familiar with web development, you may recognize this model as
“capability detection”. Web developers typically prefer this approach to
“browser detection”, because it’s very difficult to keep up as new browsers and
new versions of current browsers are released. By checking for support for
specific required capabilities instead of the current browser, web developers
get better fine-grained control. That’s the same approach Android uses: since
it’s impossible to keep up with all the Android devices being released, you
instead use the fine-grained controls Android provides.</p>
<h3>Filtering for technical reasons</h3>
<div class="sidebox-wrapper">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;">Filtering on Android Market</p>
<p>Android Market filters the applications that are visible to users, so
that users can see and download only those applications that are compatible with
their devices.</p>
<p style="margin-top:1em;">One of the ways Market filters applications is by
feature compatibility. To do this, Market checks the
<code>&lt;uses-feature&gt;</code> elements in each application's manifest, to
establish the app's feature needs. Market then shows or hides the application to
each user, based on a comparison with the features available on the user's
device.
<p style="margin-top:1em;">For information about other filters that you can
use to control the availability of your apps, see the
<a href="{@docRoot}guide/appendix/market-filters.html">Market
Filters</a> document.</p>
</div>
</div>
<p>Android includes support for a lot of features, some hardware and some
software. Examples include compass and accelerometer sensors, cameras, and Live
Wallpapers. However, not every device will support every feature. For instance,
some devices don’t have the hardware horsepower to display Live Wallpapers
well.</p>
<p>To manage this, Android defines <em>feature IDs</em>. Every capability has a
corresponding feature ID defined by the Android platform. For instance, the
feature ID for compass is <code>“android.hardware.sensor.compass”</code>,
while the feature
ID for Live Wallpapers is <code>“android.software.live_wallpapers”</code>. Each of these IDs
also has a corresponding Java-language constant on the
{@link android.content.pm.PackageManager} class that you can use to query whether
feature is supported at runtime. As Android adds support for new features in
future versions, new feature IDs will be added as well.</p>
<p>When you write your application, you specify which features your app requires
by listing their feature IDs in <code>&lt;uses-feature&gt;</code> elements in
the <code>AndroidManifest.xml</code> file. This is the information that Android
Market uses to match your app to devices that can run it. For instance, if you
state that your app requires android.software.live_wallpapers, it won’t be shown
to devices that don’t support Live Wallpapers.</p>
<p>This puts you in total control of your app &mdash; because you don’t have to
declare these features. Consider an example involving cameras.</p>
<p>If you’re building a really impressive next-generation augmented-reality app,
your app won’t function at all without a camera. However, if you’re building a
shopping app that only uses the camera for barcode scanning, users without
cameras might still find it useful even if they can’t scan barcodes. While both
apps need to acquire the permission to access the camera, only the first app
needs to state that it requires a camera. (The shopping app can simply check at
runtime and disable the camera-related features if there’s no camera
present.)</p>
<p>Since only you can say what the best approach is for your app, Android
provides the tools and lets you make your own tradeoff between maximizing
audience size and minimizing development costs.</p>
<h3 id="filtering">Filtering for business reasons</h3>
<p>It’s possible that you may need to restrict your app’s availability for
business or legal reasons. For instance, an app that displays train schedules
for the London Underground is unlikely to be useful to users outside the United
Kingdom. Other apps might not be permitted in certain countries for business or
legal reasons. For cases such as these, Android Market itself provides
developers with filtering options that allow them control their app’s
availability for non-technical reasons.</p>
<p>The help information for Android Market provides full details, but in a
nutshell, developers can use the Market publisher UI to:</p>
<ul>
<li>List the countries an app is available in.</li>
<li>Select which carrier’s users are able to access the app.</li>
</ul>
<p>Filtering for technical compatibility (such as required hardware components)
is always based on information contained within your <code>.apk</code> file. But
filtering for non-technical reasons (such as geographic restrictions) is always
handled in the Market user interface.</p>
<h3 id="futureproofing">Future-proofing</h3>
<p>There’s one additional quirk that we haven’t yet addressed: protecting apps
from changes made to future versions of Android. If the Android platform
introduces a new feature or changes how existing features are handled, what
happens to existing apps that were written without any knowledge of the new
behavior?</p>
<p>Simply put, Android commits to not making existing apps available to devices
where they won’t work properly, even when the platform changes. The best way to
explain this is through examples, so here are two:</p>
<ul>
<li>Android 1.0 through 1.5 required a 2 megapixel camera with auto-focus.
However, with version 1.6, Android devices were permitted to omit the auto-focus
capability, though a (fixed-focus) camera was still required. Some apps such as
barcode scanners do not function as well with cameras that do not auto-focus. To
prevent users from having a bad experience with those apps, existing apps that
obtain permission to use the Camera were assumed by default to require
auto-focus. This allowed Android Market to filter those apps from devices that
lack auto-focus.</li>
<li>Android 2.2, meanwhile, allowed the microphone to be optional on some
devices, such as set-top boxes. Android 2.2 included a new feature ID for the
microphone which allows developers to filter their apps if necessary, but
&mdash; as with camera &mdash; apps that obtain permission to record audio are
assumed to require the microphone feature by default. If your app can use a
microphone but doesn’t strictly need it, you can explicitly state that you don’t
require it; but unless you do that, your app won’t be shown to devices without
microphones.</li>
</ul>
<p>In other words, whenever Android introduces new features or changes existing
ones, we will always take steps to protect existing applications so that they
don’t end up being available to devices where they won’t work.</p>
<p>This is implemented, in part, using the <code>aapt</code> tool in the SDK.
To see which features your app explicitly requires or is implicitly assumed to
require, you can use the command <code>aapt dump badging</code>.</p>
<h3 id="conclusion">Conclusion</h3>
<p>The goal of Android is to create a huge installed base for developers to take
advantage of. One of the ways we will achieve this is through different kinds of
hardware running the same software environment. But we also recognize that only
developers know which kinds of devices their apps make sense on. We’ve built in
tools to the SDK and set up policies and requirements to ensure that developers
remain in control of their apps, today and in the future. With the information
you just read, and the resources listed in the sidebar of this document, you
can publish your app with the confidence that only users who can run it will
see it.</p>
<p>For more information about Android device compatibility, please visit:</p>
<p style="margin-left:2em;"><a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></p>

21
base/docs/html/guide/practices/design/index.jd Normal file
View File

@ -0,0 +1,21 @@
page.title=Application Design Goals
@jd:body
<p>When learning how to build applications on a new platform, you first learn what APIs are available and how to use them. Later, you learn the nuances of the platform. Put another way: first you learn how you <em>can</em> build applications; later, you learn how you <em>should</em> build them, to ensure that your applications offer outstanding performance and a great user experience. </p>
<p>The documents below help you learn the nuances of Android and get started building great applications more quickly, They discuss important aspects of application design that directly influence the user experience of your application, when in the hands of a mobile device user. You should read and consider these design goals as you plan your application and throughout its development, especially if you are new to developing for mobile devices.</p>
<p>Successful mobile applications offer an outstanding user experience, in addition to a compelling technical feature set. The user experience is more than just its visual design or UI flow. It is also influenced by how well the application responds to the user's keypresses and other actions, how it well it interacts with other applications, and how fully and efficiently it uses device and system capabilities.</p>
<p>An outstanding user experience has three key characteristics: it is
<em>fast</em>; it is <em>responsive</em>; and it is <em>seamless</em>. Of course
every platform since the dawn of computing has probably cited those same three
qualities at one time or another. However, each platform achieves them in
different ways; the documents below explain how you can build Android
applications that are fast, responsive, and seamless. </p>
<ul>
<li><a href="performance.html">Designing for Performance</a> (writing efficient Android code)</a></li>
<li><a href="responsiveness.html">Designing for Responsiveness</a> (avoiding ANR)</a></li>
<li><a href="seamlessness.html">Designing for Seamlessness</a> (coexisting with other applications)</a></li>
</ul>

433
base/docs/html/guide/practices/design/performance.jd Normal file
View File

@ -0,0 +1,433 @@
page.title=Designing for Performance
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#optimize_judiciously">Optimize Judiciously</a></li>
<li><a href="#object_creation">Avoid Creating Objects</a></li>
<li><a href="#myths">Performance Myths</a></li>
<li><a href="#prefer_static">Prefer Static Over Virtual</a></li>
<li><a href="#internal_get_set">Avoid Internal Getters/Setters</a></li>
<li><a href="#use_final">Use Static Final For Constants</a></li>
<li><a href="#foreach">Use Enhanced For Loop Syntax</a></li>
<li><a href="#avoid_enums">Avoid Enums Where You Only Need Ints</a></li>
<li><a href="#package_inner">Use Package Scope with Inner Classes</a></li>
<li><a href="#avoidfloat">Use Floating-Point Judiciously</a> </li>
<li><a href="#library">Know And Use The Libraries</a></li>
<li><a href="#native_methods">Use Native Methods Judiciously</a></li>
<li><a href="#closing_notes">Closing Notes</a></li>
</ol>
</div>
</div>
<p>An Android application will run on a mobile device with limited computing
power and storage, and constrained battery life. Because of
this, it should be <em>efficient</em>. Battery life is one reason you might
want to optimize your app even if it already seems to run "fast enough".
Battery life is important to users, and Android's battery usage breakdown
means users will know if your app is responsible draining their battery.</p>
<p>Note that although this document primarily covers micro-optimizations,
these will almost never make or break your software. Choosing the right
algorithms and data structures should always be your priority, but is
outside the scope of this document.</p>
<a name="intro" id="intro"></a>
<h2>Introduction</h2>
<p>There are two basic rules for writing efficient code:</p>
<ul>
<li>Don't do work that you don't need to do.</li>
<li>Don't allocate memory if you can avoid it.</li>
</ul>
<h2 id="optimize_judiciously">Optimize Judiciously</h2>
<p>This document is about Android-specific micro-optimization, so it assumes
that you've already used profiling to work out exactly what code needs to be
optimized, and that you already have a way to measure the effect (good or bad)
of any changes you make. You only have so much engineering time to invest, so
it's important to know you're spending it wisely.
<p>(See <a href="#closing_notes">Closing Notes</a> for more on profiling and
writing effective benchmarks.)
<p>This document also assumes that you made the best decisions about data
structures and algorithms, and that you've also considered the future
performance consequences of your API decisions. Using the right data
structures and algorithms will make more difference than any of the advice
here, and considering the performance consequences of your API decisions will
make it easier to switch to better implementations later (this is more
important for library code than for application code).
<p>(If you need that kind of advice, see Josh Bloch's <em>Effective Java</em>,
item 47.)</p>
<p>One of the trickiest problems you'll face when micro-optimizing an Android
app is that your app is pretty much guaranteed to be running on multiple
hardware platforms. Different versions of the VM running on different
processors running at different speeds. It's not even generally the case
that you can simply say "device X is a factor F faster/slower than device Y",
and scale your results from one device to others. In particular, measurement
on the emulator tells you very little about performance on any device. There
are also huge differences between devices with and without a JIT: the "best"
code for a device with a JIT is not always the best code for a device
without.</p>
<p>If you want to know how your app performs on a given device, you need to
test on that device.</p>
<a name="object_creation"></a>
<h2>Avoid Creating Objects</h2>
<p>Object creation is never free. A generational GC with per-thread allocation
pools for temporary objects can make allocation cheaper, but allocating memory
is always more expensive than not allocating memory.</p>
<p>If you allocate objects in a user interface loop, you will force a periodic
garbage collection, creating little "hiccups" in the user experience.</p>
<p>Thus, you should avoid creating object instances you don't need to. Some
examples of things that can help:</p>
<ul>
<li>When extracting strings from a set of input data, try
to return a substring of the original data, instead of creating a copy.
You will create a new String object, but it will share the char[]
with the data.</li>
<li>If you have a method returning a string, and you know that its result
will always be appended to a StringBuffer anyway, change your signature
and implementation so that the function does the append directly,
instead of creating a short-lived temporary object.</li>
</ul>
<p>A somewhat more radical idea is to slice up multidimensional arrays into
parallel single one-dimension arrays:</p>
<ul>
<li>An array of ints is a much better than an array of Integers,
but this also generalizes to the fact that two parallel arrays of ints
are also a <strong>lot</strong> more efficient than an array of (int,int)
objects. The same goes for any combination of primitive types.</li>
<li>If you need to implement a container that stores tuples of (Foo,Bar)
objects, try to remember that two parallel Foo[] and Bar[] arrays are
generally much better than a single array of custom (Foo,Bar) objects.
(The exception to this, of course, is when you're designing an API for
other code to access; in those cases, it's usually better to trade
correct API design for a small hit in speed. But in your own internal
code, you should try and be as efficient as possible.)</li>
</ul>
<p>Generally speaking, avoid creating short-term temporary objects if you
can. Fewer objects created mean less-frequent garbage collection, which has
a direct impact on user experience.</p>
<a name="myths" id="myths"></a>
<h2>Performance Myths</h2>
<p>Previous versions of this document made various misleading claims. We
address some of them here.</p>
<p>On devices without a JIT, it is true that invoking methods via a
variable with an exact type rather than an interface is slightly more
efficient. (So, for example, it was cheaper to invoke methods on a
<code>HashMap map</code> than a <code>Map map</code>, even though in both
cases the map was a <code>HashMap</code>.) It was not the case that this
was 2x slower; the actual difference was more like 6% slower. Furthermore,
the JIT makes the two effectively indistinguishable.</p>
<p>On devices without a JIT, caching field accesses is about 20% faster than
repeatedly accesssing the field. With a JIT, field access costs about the same
as local access, so this isn't a worthwhile optimization unless you feel it
makes your code easier to read. (This is true of final, static, and static
final fields too.)
<a name="prefer_static" id="prefer_static"></a>
<h2>Prefer Static Over Virtual</h2>
<p>If you don't need to access an object's fields, make your method static.
Invocations will be about 15%-20% faster.
It's also good practice, because you can tell from the method
signature that calling the method can't alter the object's state.</p>
<a name="internal_get_set" id="internal_get_set"></a>
<h2>Avoid Internal Getters/Setters</h2>
<p>In native languages like C++ it's common practice to use getters (e.g.
<code>i = getCount()</code>) instead of accessing the field directly (<code>i
= mCount</code>). This is an excellent habit for C++, because the compiler can
usually inline the access, and if you need to restrict or debug field access
you can add the code at any time.</p>
<p>On Android, this is a bad idea. Virtual method calls are expensive,
much more so than instance field lookups. It's reasonable to follow
common object-oriented programming practices and have getters and setters
in the public interface, but within a class you should always access
fields directly.</p>
<p>Without a JIT, direct field access is about 3x faster than invoking a
trivial getter. With the JIT (where direct field access is as cheap as
accessing a local), direct field access is about 7x faster than invoking a
trivial getter. This is true in Froyo, but will improve in the future when
the JIT inlines getter methods.</p>
<a name="use_final" id="use_final"></a>
<h2>Use Static Final For Constants</h2>
<p>Consider the following declaration at the top of a class:</p>
<pre>static int intVal = 42;
static String strVal = "Hello, world!";</pre>
<p>The compiler generates a class initializer method, called
<code>&lt;clinit&gt;</code>, that is executed when the class is first used.
The method stores the value 42 into <code>intVal</code>, and extracts a
reference from the classfile string constant table for <code>strVal</code>.
When these values are referenced later on, they are accessed with field
lookups.</p>
<p>We can improve matters with the "final" keyword:</p>
<pre>static final int intVal = 42;
static final String strVal = "Hello, world!";</pre>
<p>The class no longer requires a <code>&lt;clinit&gt;</code> method,
because the constants go into static field initializers in the dex file.
Code that refers to <code>intVal</code> will use
the integer value 42 directly, and accesses to <code>strVal</code> will
use a relatively inexpensive "string constant" instruction instead of a
field lookup. (Note that this optimization only applies to primitive types and
<code>String</code> constants, not arbitrary reference types. Still, it's good
practice to declare constants <code>static final</code> whenever possible.)</p>
<a name="foreach" id="foreach"></a>
<h2>Use Enhanced For Loop Syntax</h2>
<p>The enhanced for loop (also sometimes known as "for-each" loop) can be used
for collections that implement the Iterable interface and for arrays.
With collections, an iterator is allocated to make interface calls
to hasNext() and next(). With an ArrayList, a hand-written counted loop is
about 3x faster (with or without JIT), but for other collections the enhanced
for loop syntax will be exactly equivalent to explicit iterator usage.</p>
<p>There are several alternatives for iterating through an array:</p>
<pre> static class Foo {
int mSplat;
}
Foo[] mArray = ...
public void zero() {
int sum = 0;
for (int i = 0; i &lt; mArray.length; ++i) {
sum += mArray[i].mSplat;
}
}
public void one() {
int sum = 0;
Foo[] localArray = mArray;
int len = localArray.length;
for (int i = 0; i &lt; len; ++i) {
sum += localArray[i].mSplat;
}
}
public void two() {
int sum = 0;
for (Foo a : mArray) {
sum += a.mSplat;
}
}
</pre>
<p><strong>zero()</strong> is slowest, because the JIT can't yet optimize away
the cost of getting the array length once for every iteration through the
loop.</p>
<p><strong>one()</strong> is faster. It pulls everything out into local
variables, avoiding the lookups. Only the array length offers a performance
benefit.</p>
<p><strong>two()</strong> is fastest for devices without a JIT, and
indistinguishable from <strong>one()</strong> for devices with a JIT.
It uses the enhanced for loop syntax introduced in version 1.5 of the Java
programming language.</p>
<p>To summarize: use the enhanced for loop by default, but consider a
hand-written counted loop for performance-critical ArrayList iteration.</p>
<p>(See also <em>Effective Java</em> item 46.)</p>
<a name="avoid_enums" id="avoid_enums"></a>
<h2>Avoid Enums Where You Only Need Ints</h2>
<p>Enums are very convenient, but unfortunately can be painful when size
and speed matter. For example, this:</p>
<pre>public enum Shrubbery { GROUND, CRAWLING, HANGING }</pre>
<p>adds 740 bytes to your .dex file compared to the equivalent class
with three public static final ints. On first use, the
class initializer invokes the &lt;init&gt; method on objects representing each
of the enumerated values. Each object gets its own static field, and the full
set is stored in an array (a static field called "$VALUES"). That's a lot of
code and data, just for three integers. Additionally, this:</p>
<pre>Shrubbery shrub = Shrubbery.GROUND;</pre>
<p>causes a static field lookup. If "GROUND" were a static final int,
the compiler would treat it as a known constant and inline it.</p>
<p>The flip side, of course, is that with enums you get nicer APIs and
some compile-time value checking. So, the usual trade-off applies: you should
by all means use enums for public APIs, but try to avoid them when performance
matters.</p>
<p>If you're using <code>Enum.ordinal</code>, that's usually a sign that you
should be using ints instead. As a rule of thumb, if an enum doesn't have a
constructor and doesn't define its own methods, and it's used in
performance-critical code, you should consider <code>static final int</code>
constants instead.</p>
<a name="package_inner" id="package_inner"></a>
<h2>Use Package Scope with Inner Classes</h2>
<p>Consider the following class definition:</p>
<pre>public class Foo {
private int mValue;
public void run() {
Inner in = new Inner();
mValue = 27;
in.stuff();
}
private void doStuff(int value) {
System.out.println("Value is " + value);
}
private class Inner {
void stuff() {
Foo.this.doStuff(Foo.this.mValue);
}
}
}</pre>
<p>The key things to note here are that we define an inner class (Foo$Inner)
that directly accesses a private method and a private instance field
in the outer class. This is legal, and the code prints "Value is 27" as
expected.</p>
<p>The problem is that the VM considers direct access to Foo's private members
from Foo$Inner to be illegal because Foo and Foo$Inner are different classes,
even though the Java language allows an inner class to access an outer class'
private members. To bridge the gap, the compiler generates a couple of
synthetic methods:</p>
<pre>/*package*/ static int Foo.access$100(Foo foo) {
return foo.mValue;
}
/*package*/ static void Foo.access$200(Foo foo, int value) {
foo.doStuff(value);
}</pre>
<p>The inner-class code calls these static methods whenever it needs to
access the "mValue" field or invoke the "doStuff" method in the outer
class. What this means is that the code above really boils down to a case
where you're accessing member fields through accessor methods instead of
directly. Earlier we talked about how accessors are slower than direct field
accesses, so this is an example of a certain language idiom resulting in an
"invisible" performance hit.</p>
<p>We can avoid this problem by declaring fields and methods accessed
by inner classes to have package scope, rather than private scope.
This runs faster and removes the overhead of the generated methods.
(Unfortunately it also means the fields could be accessed directly by other
classes in the same package, which runs counter to the standard
practice of making all fields private. Once again, if you're
designing a public API you might want to carefully consider using this
optimization.)</p>
<a name="avoidfloat" id="avoidfloat"></a>
<h2>Use Floating-Point Judiciously</h2>
<p>As a rule of thumb, floating-point is about 2x slower than integer on
Android devices. This is true on a FPU-less, JIT-less G1 and a Nexus One with
an FPU and the JIT. (Of course, absolute speed difference between those two
devices is about 10x for arithmetic operations.)</p>
<p>In speed terms, there's no difference between <code>float</code> and
<code>double</code> on the more modern hardware. Space-wise, <code>double</code>
is 2x larger. As with desktop machines, assuming space isn't an issue, you
should prefer <code>double</code> to <code>float</code>.</p>
<p>Also, even for integers, some chips have hardware multiply but lack
hardware divide. In such cases, integer division and modulus operations are
performed in software &mdash; something to think about if you're designing a
hash table or doing lots of math.</p>
<a name="library" id="library"></a>
<h2>Know And Use The Libraries</h2>
<p>In addition to all the usual reasons to prefer library code over rolling
your own, bear in mind that the system is at liberty to replace calls
to library methods with hand-coded assembler, which may be better than the
best code the JIT can produce for the equivalent Java. The typical example
here is <code>String.indexOf</code> and friends, which Dalvik replaces with
an inlined intrinsic. Similarly, the <code>System.arraycopy</code> method
is about 9x faster than a hand-coded loop on a Nexus One with the JIT.</p>
<p>(See also <em>Effective Java</em> item 47.)</p>
<a name="native_methods" id="native_methods"></a>
<h2>Use Native Methods Judiciously</h2>
<p>Native code isn't necessarily more efficient than Java. For one thing,
there's a cost associated with the Java-native transition, and the JIT can't
optimize across these boundaries. If you're allocating native resources (memory
on the native heap, file descriptors, or whatever), it can be significantly
more difficult to arrange timely collection of these resources. You also
need to compile your code for each architecture you wish to run on (rather
than rely on it having a JIT). You may even have to compile multiple versions
for what you consider the same architecture: native code compiled for the ARM
processor in the G1 can't take full advantage of the ARM in the Nexus One, and
code compiled for the ARM in the Nexus One won't run on the ARM in the G1.</p>
<p>Native code is primarily useful when you have an existing native codebase
that you want to port to Android, not for "speeding up" parts of a Java app.</p>
<p>(See also <em>Effective Java</em> item 54.)</p>
<a name="closing_notes" id="closing_notes"></a>
<h2>Closing Notes</h2>
<p>One last thing: always measure. Before you start optimizing, make sure you
have a problem. Make sure you can accurately measure your existing performance,
or you won't be able to measure the benefit of the alternatives you try.</p>
<p>Every claim made in this document is backed up by a benchmark. The source
to these benchmarks can be found in the <a href="http://code.google.com/p/dalvik/source/browse/#svn/trunk/benchmarks">code.google.com "dalvik" project</a>.</p>
<p>The benchmarks are built with the
<a href="http://code.google.com/p/caliper/">Caliper</a> microbenchmarking
framework for Java. Microbenchmarks are hard to get right, so Caliper goes out
of its way to do the hard work for you, and even detect some cases where you're
not measuring what you think you're measuring (because, say, the VM has
managed to optimize all your code away). We highly recommend you use Caliper
to run your own microbenchmarks.</p>
<p>You may also find
<a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a> useful
for profiling, but it's important to realize that it currently disables the JIT,
which may cause it to misattribute time to code that the JIT may be able to win
back. It's especially important after making changes suggested by Traceview
data to ensure that the resulting code actually runs faster when run without
Traceview.

140
base/docs/html/guide/practices/design/responsiveness.jd Normal file
View File

@ -0,0 +1,140 @@
page.title=Designing for Responsiveness
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#anr">What Triggers ANR?</a></li>
<li><a href="#avoiding">How to Avoid ANR</a></li>
<li><a href="#reinforcing">Reinforcing Responsiveness</a></li>
</ol>
</div>
</div>
<div class="figure">
<img src="{@docRoot}images/anr.png" alt="Screenshot of ANR dialog box" width="240" height="320"/>
<p><strong>Figure 1.</strong> An ANR dialog displayed to the user.</p>
</div>
<p>It's possible to write code that wins every performance test in the world,
but still sends users in a fiery rage when they try to use the application.
These are the applications that aren't <em>responsive</em> enough &mdash; the
ones that feel sluggish, hang or freeze for significant periods, or take too
long to process input. </p>
<p>In Android, the system guards against applications that are insufficiently
responsive for a period of time by displaying a dialog to the user, called the
Application Not Responding (ANR) dialog, shown at right in Figure 1. The user
can choose to let the application continue, but the user won't appreciate having
to act on this dialog every time he or she uses your application. It's critical
to design responsiveness into your application, so that the system never has
cause to display an ANR dialog to the user. </p>
<p>Generally, the system displays an ANR if an application cannot respond to
user input. For example, if an application blocks on some I/O operation
(frequently a network access), then the main application thread won't be able to
process incoming user input events. After a time, the system concludes that the
application is frozen, and displays the ANR to give the user the option to kill
it. </p>
<p>Similarly, if your application spends too much time building an elaborate in-memory
structure, or perhaps computing the next move in a game, the system will
conclude that your application has hung. It's always important to make
sure these computations are efficient using the techniques above, but even the
most efficient code still takes time to run.</p>
<p>In both of these cases, the recommended approach is to create a child thread and do
most of your work there. This keeps the main thread (which drives the user
interface event loop) running and prevents the system from concluding that your code
has frozen. Since such threading usually is accomplished at the class
level, you can think of responsiveness as a <em>class</em> problem. (Compare
this with basic performance, which was described above as a <em>method</em>-level
concern.)</p>
<p>This document describes how the Android system determines whether an
application is not responding and provides guidelines for ensuring that your
application stays responsive. </p>
<h2 id="anr">What Triggers ANR?</h2>
<p>In Android, application responsiveness is monitored by the Activity Manager
and Window Manager system services. Android will display the ANR dialog
for a particular application when it detects one of the following
conditions:</p>
<ul>
<li>No response to an input event (e.g. key press, screen touch)
within 5 seconds</li>
<li>A {@link android.content.BroadcastReceiver BroadcastReceiver}
hasn't finished executing within 10 seconds</li>
</ul>
<h2 id="avoiding">How to Avoid ANR</h2>
<p>Given the above definition for ANR, let's examine why this can occur in
Android applications and how best to structure your application to avoid ANR.</p>
<p>Android applications normally run entirely on a single (i.e. main) thread.
This means that anything your application is doing in the main thread that
takes a long time to complete can trigger the ANR dialog because your
application is not giving itself a chance to handle the input event or Intent
broadcast.</p>
<p>Therefore any method that runs in the main thread should do as little work
as possible. In particular, Activities should do as little as possible to set
up in key life-cycle methods such as <code>onCreate()</code> and
<code>onResume()</code>. Potentially long running operations such as network
or database operations, or computationally expensive calculations such as
resizing bitmaps should be done in a child thread (or in the case of databases
operations, via an asynchronous request). However, this does not mean that
your main thread should block while waiting for the child thread to
complete &mdash; nor should you call <code>Thread.wait()</code> or
<code>Thread.sleep()</code>. Instead of blocking while waiting for a child
thread to complete, your main thread should provide a {@link
android.os.Handler Handler} for child threads to post back to upon completion.
Designing your application in this way will allow your main thread to remain
responsive to input and thus avoid ANR dialogs caused by the 5 second input
event timeout. These same practices should be followed for any other threads
that display UI, as they are also subject to the same timeouts.</p>
<p>You can use {@link android.os.StrictMode} to help find potentially
long running operations such as network or database operations that
you might accidentally be doing your main thread.</p>
<p>The specific constraint on IntentReceiver execution time emphasizes what
they were meant to do: small, discrete amounts of work in the background such
as saving a setting or registering a Notification. So as with other methods
called in the main thread, applications should avoid potentially long-running
operations or calculations in BroadcastReceivers. But instead of doing intensive
tasks via child threads (as the life of a BroadcastReceiver is short), your
application should start a {@link android.app.Service Service} if a
potentially long running action needs to be taken in response to an Intent
broadcast. As a side note, you should also avoid starting an Activity from an
Intent Receiver, as it will spawn a new screen that will steal focus from
whatever application the user is currently has running. If your application
has something to show the user in response to an Intent broadcast, it should
do so using the {@link android.app.NotificationManager Notification
Manager}.</p>
<h2 id="reinforcing">Reinforcing Responsiveness</h2>
<p>Generally, 100 to 200ms is the threshold beyond which users will perceive
lag (or lack of "snappiness," if you will) in an application. As such, here
are some additional tips beyond what you should do to avoid ANR that will help
make your application seem responsive to users.</p>
<ul>
<li>If your application is doing work in the background in response to
user input, show that progress is being made ({@link
android.widget.ProgressBar ProgressBar} and {@link
android.app.ProgressDialog ProgressDialog} are useful for this).</li>
<li>For games specifically, do calculations for moves in a child
thread.</li>
<li>If your application has a time-consuming initial setup phase, consider
showing a splash screen or rendering the main view as quickly as possible
and filling in the information asynchronously. In either case, you should
indicate somehow that progress is being made, lest the user perceive that
the application is frozen.</li>
</ul>

249
base/docs/html/guide/practices/design/seamlessness.jd Normal file
View File

@ -0,0 +1,249 @@
page.title=Designing for Seamlessness
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#drop">Don't Drop Data</a></li>
<li><a href="#expose">Don't Expose Raw Data</a></li>
<li><a href="#interrupt">Don't Interrupt the User</a></li>
<li><a href="#threads">Got a Lot to Do? Do it in a Thread</a></li>
<li><a href="#multiple-activities">Don't Overload a Single Activity Screen</a></li>
<li><a href="#themes">Extend System Themes</a></li>
<li><a href="#flexui">Design Your UI to Work with Multiple Screen Resolutions</a></li>
<li><a href="#network">Assume the Network is Slow</a></li>
<li><a href="#keyboard">Don't Assume Touchscreen or Keyboard</a></li>
<li><a href="#battery">Do Conserve the Device Battery</a></li>
</ol>
</div>
</div>
<p>Even if your application is fast and responsive, certain design decisions can
still cause problems for users &mdash; because of unplanned interactions with
other applications or dialogs, inadvertent loss of data, unintended blocking,
and so on. To avoid these problems, it helps to understand the context in which
your applications run and the system interactions that can affect your
application. In short, you should strive to develop an application that
interacts seamlessly with the system and with other applications. </p>
<p>A common seamlessness problem is when an application's background process
&mdash; for example, a service or broadcast receiver &mdash; pops up a dialog in
response to some event. This may seem like harmless behavior, especially when
you are building and testing your application in isolation, on the emulator.
However, when your application is run on an actual device, your application may
not have user focus at the time your background process displays the dialog. So
it could end up that your application would display it's dialog behind the
active application, or it could take focus from the current application and
display the dialog in front of whatever the user was doing (such as dialing a
phone call, for example). That behavior would not work for your application or
for the user. </p>
<p>To avoid these problems, your application should use the proper system
facility for notifying the user &mdash; the
{@link android.app.Notification Notification} classes. Using
notifications, your application can signal the user that an event has
taken place, by displaying an icon in the status bar rather than taking
focus and interrupting the user.</p>
<p>Another example of a seamlessness problem is when an activity inadvertently
loses state or user data because it doesn't correctly implement the onPause()
and other lifecycle methods. Or, if your application exposes data intended to be
used by other applications, you should expose it via a ContentProvider, rather
than (for example) doing so through a world-readable raw file or database.</p>
<p>What those examples have in common is that they involve cooperating nicely
with the system and other applications. The Android system is designed to treat
applications as a sort of federation of loosely-coupled components, rather than
chunks of black-box code. This allows you as the developer to view the entire
system as just an even-larger federation of these components. This benefits you
by allowing you to integrate cleanly and seamlessly with other applications, and
so you should design your own code to return the favor.</p>
<p>This document discusses common seamlessness problems and how to avoid them.</p>
<h2 id="drop">Don't Drop Data</h2>
<p>Always keep in mind that Android is a mobile platform. It may seem obvious to
say it, but it's important to remember that another Activity (such as the
"Incoming Phone Call" app) can pop up over your own Activity at any moment.
This will fire the onSaveInstanceState() and onPause() methods, and will likely result in
your application being killed.</p>
<p>If the user was editing data in your application when the other Activity
appeared, your application will likely lose that data when your application is
killed. Unless, of course, you save the work in progress first. The "Android
Way" is to do just that: Android applications that accept or edit input should
override the onSaveInstanceState() method and save their state in some appropriate
fashion. When the user revisits the application, she should be able to
retrieve her data.</p>
<p>A classic example of a good use of this behavior is a mail application. If the
user was composing an email when another Activity started up, the application
should save the in-process email as a draft.</p>
<h2 id="expose">Don't Expose Raw Data</h2>
<p>If you wouldn't walk down the street in your underwear, neither should your
data. While it's possible to expose certain kinds of application to the world
to read, this is usually not the best idea. Exposing raw data requires other
applications to understand your data format; if you change that format, you'll
break any other applications that aren't similarly updated.</p>
<p>The "Android Way" is to create a ContentProvider to expose your data to other
applications via a clean, well-thought-out, and maintainable API. Using a
ContentProvider is much like inserting a Java language interface to split up and
componentize two tightly-coupled pieces of code. This means you'll be able to
modify the internal format of your data without changing the interface exposed
by the ContentProvider, and this without affecting other applications.</p>
<h2 id="interrupt">Don't Interrupt the User</h2>
<p>If the user is running an application (such as the Phone application during a
call) it's a pretty safe bet he did it on purpose. That's why you should avoid
spawning activities except in direct response to user input from the current
Activity.</p>
<p>That is, don't call startActivity() from BroadcastReceivers or Services running in
the background. Doing so will interrupt whatever application is currently
running, and result in an annoyed user. Perhaps even worse, your Activity may
become a "keystroke bandit" and receive some of the input the user was in the
middle of providing to the previous Activity. Depending on what your
application does, this could be bad news.</p>
<p>Instead of spawning Activity UIs directly from the background, you should
instead use the NotificationManager to set Notifications. These will appear in
the status bar, and the user can then click on them at his leisure, to see
what your application has to show him.</p>
<p>(Note that all this doesn't apply to cases where your own Activity is already
in the foreground: in that case, the user expects to see your next Activity in
response to input.)</p>
<h2 id="threads">Got a Lot to Do? Do it in a Thread</h2>
<p>If your application needs to perform some expensive or long-running
computation, you should probably move it to a thread. This will prevent the
dreaded "Application Not Responding" dialog from being displayed to the user,
with the ultimate result being the fiery demise of your application.</p>
<p>By default, all code in an Activity as well as all its Views run in the same
thread. This is the same thread that also handles UI events. For example, when
the user presses a key, a key-down event is added to the Activity's main
thread's queue. The event handler system needs to dequeue and handle that
event quickly; if it doesn't, the system concludes after a few seconds that
the application is hung and offers to kill it for the user.</p>
<p>If you have long-running code, running it inline in your Activity will run it
on the event handler thread, effectively blocking the event handler. This will
delay input processing, and result in the ANR dialogs. To avoid this, move
your computations to a thread. This <a
href="responsiveness.html">Design for Responsiveness</a> document
discusses how to do that..</p>
<h2 id="multiple-activities">Don't Overload a Single Activity Screen</h2>
<p>Any application worth using will probably have several different screens.
When designing the screens of your UI, be sure to make use of multiple Activity
object instances.</p>
<p>Depending on your development background, you may interpret an Activity as
similar to something like a Java Applet, in that it is the entry point for
your application. However, that's not quite accurate: where an Applet subclass
is the single entry point for a Java Applet, an Activity should be thought of
as one of potentially several entry points to your application. The only
difference between your "main" Activity and any others you might have is that
the "main" one just happens to be the only one that expressed an interest in
the "android.intent.action.MAIN" action in your AndroidManifest..xml file.</p>
<p>So, when designing your application, think of your application as a federation
of Activity objects. This will make your code a lot more maintainable in the long
run, and as a nice side effect also plays nicely with Android's application
history and "backstack" model.</p>
<h2 id="themes">Extend System Themes</h2>
<p>When it comes to the look-and-feel of the user interface, it's important to
blend in nicely. Users are jarred by applications which contrast with the user
interface they've come to expect. When designing your UIs, you should try and
avoid rolling your own as much as possible. Instead, use a Theme. You
can override or extend those parts of the theme that you need to, but at least
you're starting from the same UI base as all the other applications. For all
the details, read <a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>
<h2 id="flexui">Design Your UI to Work with Multiple Screen Resolutions</h2>
<p>Different Android-powered devices will support different screen resolutions.
Some will even be able to change resolutions on the fly, such as by switching
to landscape mode. It's important to make sure your layouts and drawables
are flexible enough to display properly on a variety of device screens.</p>
<p>Fortunately, this is very easy to do. In brief, what you must do is
provide different versions of your artwork (if you use any) for the key
resolutions, and then design your layout to accommodate various dimensions.
(For example, avoid using hard-coded positions and instead use relative
layouts.) If you do that much, the system handles the rest, and your
application looks great on any device.</p>
<h2 id="network">Assume the Network is Slow</h2>
<p>Android devices will come with a variety of network-connectivity options. All
will have some data-access provision, though some will be faster than others.
The lowest common denominator, however, is GPRS, the non-3G data service for
GSM networks. Even 3G-capable devices will spend lots of time on non-3G
networks, so slow networks will remain a reality for quite a long time to
come.</p>
<p>That's why you should always code your applications to minimize network
accesses and bandwidth. You can't assume the network is fast, so you should
always plan for it to be slow. If your users happen to be on faster networks,
then that's great &mdash; their experience will only improve. You want to avoid the
inverse case though: applications that are usable some of the time, but
frustratingly slow the rest based on where the user is at any given moment are
likely to be unpopular.</p>
<p>One potential gotcha here is that it's very easy to fall into this trap if
you're using the emulator, since the emulator uses your desktop computer's
network connection. That's almost guaranteed to be much faster than a cell
network, so you'll want to change the settings on the emulator that simulate
slower network speeds. You can do this in Eclipse, in the "Emulator Settings"
tab of your launch configuration or via a <a
href="{@docRoot}guide/developing/tools/emulator.html#netspeed">command-line
option</a> when starting the emulator.</p>
<h2 id="keyboard">Don't Assume Touchscreen or Keyboard</h2>
<p>
Android will support a variety of handset form-factors. That's a fancy way of
saying that some Android devices will have full "QWERTY" keyboards, while
others will have 40-key, 12-key, or even other key configurations. Similarly,
some devices will have touch-screens, but many won't.
</p><p>
When building your applications, keep that in mind. Don't make assumptions
about specific keyboard layouts -- unless, of course, you're really interested
in restricting your application so that it can only be used on those devices.
</p>
<h2 id="battery">Do Conserve the Device Battery</h2>
<p>
A mobile device isn't very mobile if it's constantly plugged into the
wall. Mobile devices are battery-powered, and the longer we can make that
battery last on a charge, the happier everyone is &mdash; especially the user.
Two of the biggest consumers of battery power are the processor, and the
radio; that's why it's important to write your applications to do as little
work as possible, and use the network as infrequently as possible.
</p><p>
Minimizing the amount of processor time your application uses really comes
down to <a href="performance.html">writing efficient
code</a>. To minimize the power drain from using the radio, be sure to handle
error conditions gracefully, and only fetch what you need. For example, don't
constantly retry a network operation if one failed. If it failed once, it's
likely because the user has no reception, so it's probably going to fail again
if you try right away; all you'll do is waste battery power.
</p><p>
Users are pretty smart: if your program is power-hungry, you can count on
them noticing. The only thing you can be sure of at that point is that your
program won't stay installed very long.
</p>

8
base/docs/html/guide/practices/index.html Normal file
View File

@ -0,0 +1,8 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=../index.html">
</head>
<body>
<a href="../index.html">click here</a> if you are not redirected.
</body>
</html>

1438
base/docs/html/guide/practices/screens_support.jd Normal file
View File

File diff suppressed because it is too large Load Diff

1238
base/docs/html/guide/practices/ui_guidelines/activity_task_design.jd Normal file
View File

File diff suppressed because it is too large Load Diff

467
base/docs/html/guide/practices/ui_guidelines/icon_design.jd Normal file
View File

@ -0,0 +1,467 @@
page.title=Icon Design Guidelines
parent.title=UI Guidelines
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>You can use several types of icons in an Android application.</li>
<li>Your icons should follow the general specification in this document.</li>
<li>You should create separate icon sets for high-, medium-, and low-density screens.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#templatespack">Using the Icon Templates Pack</a></li>
<li><a href="#icon-sets">Providing Density-Specific Icon Sets</a></li>
<li><a href="#design-tips">Tips for Designers</a></li>
</ol>
<h2>Topics</h2>
<ol>
<li><a href="icon_design_launcher.html">Launcher Icons</a></li>
<li><a href="icon_design_menu.html">Menu Icons</a></li>
<li><a href="icon_design_status_bar.html">Status Bar Icons</a></li>
<li><a href="icon_design_tab.html">Tab Icons</a></li>
<li><a href="icon_design_dialog.html">Dialog Icons</a></li>
<li><a href="icon_design_list.html">List View Icons</a></li>
</ol>
<h2>Downloads</h2>
<ol>
<li><a href="{@docRoot}shareables/icon_templates-v2.3.zip">Android Icon
Templates Pack, v2.3 &raquo;</a></li>
<li><a href="{@docRoot}shareables/icon_templates-v2.0.zip">Android Icon
Templates Pack, v2.0 &raquo;</a></li>
<li><a href="{@docRoot}shareables/icon_templates-v1.0.zip">Android Icon
Templates Pack, v1.0 &raquo;</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>Creating a unified look and feel throughout a user interface adds value to
your product. Streamlining the graphic style will also make the UI seem more
professional to users.</p>
<p>This document provides information to help you create icons for various parts
of your application’s user interface that match the general styles used by the
Android 2.x framework. Following these guidelines will help you to create a
polished and unified experience for the user.</p>
<p>The following documents discuss detailed guidelines for the common types of
icons used throughout Android applications:</p>
<dl>
<dt><strong><a href="icon_design_launcher.html">Launcher Icons</a></strong></dt>
<dd>A Launcher icon is a graphic that represents your application on the
device's Home screen and in the Launcher window.</dd>
<dt><strong><a href="icon_design_menu.html">Menu Icons</a></strong></dt>
<dd>Menu icons are graphical elements placed in the options menu shown to
users when they press the Menu button.</dd>
<dt><strong><a href="icon_design_status_bar.html">Status Bar Icons</a></strong></dt>
<dd>Status bar icons are used to represent notifications from your
application in the status bar.</dd>
<dt><strong><a href="icon_design_tab.html">Tab Icons</a></strong></dt>
<dd>Tab icons are graphical elements used to represent individual tabs in a
multi-tab interface.</dd>
<dt><strong><a href="icon_design_dialog.html">Dialog Icons</a></strong></dt>
<dd>Dialog icons are shown in pop-up dialog boxes that prompt the user for
interaction.</dd>
<dt><strong><a href="icon_design_list.html">List View Icons</a></strong></dt>
<dd>List view icons are used with {@link android.widget.ListView} to
graphically represent list items. An example is the Settings application.</dd>
</dl>
<p>To get started creating your icons more quickly, you can download
the Android Icon Templates Pack.</p>
<h2 id="templatespack">Using the Android Icon Templates Pack</h2>
<p>The Android Icon Templates Pack is a collection of template designs,
textures, and layer styles that make it easier for you to create icons that
conform to the guidelines given in this document. We recommend downloading the
template pack archive before you start designing your icons.</p>
<p>The icon templates are provided in the Adobe Photoshop file format (.psd),
which preserves the layers and design treatments we used when creating the
standard icons for the Android platform. You can load the template files into
any compatible image-editing program, although your ability to work directly
with the layers and treatments may vary based on the program you are using.</p>
<p>You can obtain the latest Icon Templates Pack archive using the link below:
</p>
<p style="margin-left:2em"><a
href="{@docRoot}shareables/icon_templates-v2.3.zip">Download the Icon Templates
Pack for Android 2.3 &raquo;</a>
<p>For previous versions of the Icon Templates Pack, see the <em>Downloads</em>
section in the box at the top-right corner of this page.</p>
<h2 id="icon-sets">Providing Density-Specific Icon Sets</h2>
<p>Android is designed to run on a variety of devices that offer a range of
screen sizes and resolutions. When you design the icons for your application,
it's important keep in mind that your application may be installed on any of
those devices. As described in the <a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a> document, the Android platform makes it straightforward for you to
provide icons in such a way that they will be displayed properly on any device,
regardless of the device's screen size or resolution.</p>
<p>In general, the recommended approach is to create a separate set of icons for
each of the three generalized screen densities listed in Table 1. Then,
store them in density-specific resource directories in your application. When
your application runs, the Android platform will check the characteristics of
the device screen and load icons from the appropriate density-specific
resources. For more information about how to store density-specific resources in
your application, see <a
href="{@docRoot}guide/practices/screens_support.html#qualifiers">Resource
directory qualifiers for screen size and density</a>. </p>
<p>For tips on how to create and manage icon sets for multiple densities, see
<a href="#design-tips">Tips for Designers</a>.</p>
<p class="table-caption" id="screens-table"><strong>Table 1.</strong> Summary of
finished icon dimensions for each of the three generalized screen densities, by
icon type.</p>
<table>
<tbody>
<tr>
<th>Icon Type</th><th colspan="3">Standard Asset Sizes (in Pixels), for
Generalized Screen Densities</th></tr>
<tr>
<td style="background-color:#f3f3f3"></td>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Low density screen <em>(ldpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Medium density screen <em>(mdpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>High density screen <em>(hdpi)</em><nobr>
</th>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Launcher
</th>
<td>
36 x 36 px
</td>
<td>
48 x 48 px
</td>
<td>
72 x 72 px
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Menu
</th>
<td>
36 x 36 px
</td>
<td>
48 x 48 px
</td>
<td>
72 x 72 px
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Status Bar (Android 2.3 and later)
</th>
<td>
12w x 19h px<br>
(preferred, width may vary)
</td>
<td>
16w x 25h px<br>
(preferred, width may vary)
</td>
<td>
24w x 38h px<br>
(preferred, width may vary)
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Status Bar (Android 2.2 and below)
</th>
<td>
19 x 19 px
</td>
<td>
25 x 25 px
</td>
<td>
38 x 38 px
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Tab
</th>
<td>
24 x 24 px
</td>
<td>
32 x 32 px
</td>
<td>
48 x 48 px
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
Dialog
</th>
<td>
24 x 24 px
</td>
<td>
32 x 32 px
</td>
<td>
48 x 48 px
</td>
</tr>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
List View
</th>
<td>
24 x 24 px
</td>
<td>
32 x 32 px
</td>
<td>
48 x 48 px
</td>
</tr>
</tbody>
</table>
<h2 id="design-tips">Tips for Designers</h2>
<p>Here are some tips that you might find useful as you develop icons or other
drawable assets for your application. The tips assume that you are using
Adobe Photoshop or a similar raster and vector image-editing program.</p>
<h3>Use common naming conventions for icon assets</h3>
<p>Try to name files so that related assets will group together inside a
directory when they are sorted alphabetically. In particular, it helps to use a
common prefix for each icon type. For example:</p>
<table>
<tr>
<th>Asset Type</th>
<th>Prefix</th>
<th>Example</th>
</tr>
<tr>
<td>Icons</td>
<td><code>ic_</code></td>
<td><code>ic_star.png</code></td>
</tr>
<tr>
<td>Launcher icons</td>
<td><code>ic_launcher</code></td>
<td><code>ic_launcher_calendar.png</code></td>
</tr>
<tr>
<td>Menu icons</td>
<td><code>ic_menu</code></td>
<td><code>ic_menu_archive.png</code></td>
</tr>
<tr>
<td>Status bar icons</td>
<td><code>ic_stat_notify</code></td>
<td><code>ic_stat_notify_msg.png</code></td>
</tr>
<tr>
<td>Tab icons</td>
<td><code>ic_tab</code></td>
<td><code>ic_tab_recent.png</code></td>
</tr>
<tr>
<td>Dialog icons</td>
<td><code>ic_dialog</code></td>
<td><code>ic_dialog_info.png</code></td>
</tr>
</table>
<p>Note that you are not required to use a shared prefix of any type &mdash;
doing so is for your convenience only.</p>
<h3>Set up a working space that organizes files for multiple densities</h3>
<p>Supporting multiple screen densities means you must create multiple versions
of the same icon. To help keep the multiple copies of files safe and easier to
find, we recommend creating a directory structure in your working space that
organizes asset files per resolution. For example:</p>
<pre>assets/...
ldpi/...
_pre_production/...
<em>working_file</em>.psd
<em>finished_asset</em>.png
mdpi/...
_pre_production/...
<em>working_file</em>.psd
<em>finished_asset</em>.png
hdpi/...
_pre_production/...
<em>working_file</em>.psd
<em>finished_asset</em>.png</pre>
<p>This structure parallels the density-specific structure in which you will
ultimately store the finished assets in your application's resources. Because
the structure in your working space is similar to that of the application, you
can quickly determine which assets should be copied to each application
resources directory. Separating assets by density also helps you detect any
variances in filenames across densities, which is important because
corresponding assets for different densities must share the same filename.</p>
<p>For comparison, here's the resources directory structure of a typical
application: </p>
<pre>res/...
drawable-ldpi/...
<em>finished_asset</em>.png
drawable-mdpi/...
<em>finished_asset</em>.png
drawable-hdpi/...
<em>finished_asset</em>.png</pre>
<h3>Use vector shapes where possible</h3>
<p>Many image-editing programs such as Adobe Photoshop allow you to use a
combination of vector shapes and raster layers and effects. When possible,
use vector shapes so that if the need arises, assets can be scaled up without
loss of detail and edge crispness.</p>
<p>Using vectors also makes it easy to align edges and corners to pixel
boundaries at smaller resolutions.</li>
<h3>Start with large artboards</h3>
<p>Because you will need to create assets for different screen densities, as
shown in <a href="#screens-table">Table 1</a>, it is best to start your icon
designs on large artboards with dimensions that are multiples of the target icon
sizes. For example, <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html">launcher
icons</a> are 72, 48, or 36 pixels wide, depending on screen density. If you
initially draw launcher icons on an 864x864 artboard, it will be easier and
cleaner to tweak the icons when you scale the artboard down to the target
sizes for final asset creation.</p>
<p>It's also beneficial to add guide lines (also known as guides) to your large
artboard for the recommended safe margins at the highest target density.
Continuing with the example above, per the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html#size5">guidelines</a>,
launcher icon content should be 60x60 pixels (56x56 for square icons) within the
full 72x72 asset, or a safe margin of 6 pixels on each side. On an 864x864
artboard, this corresponds to horizontal and vertical guide lines 72 pixels from
each side of the artboard.</p>
<h3>When scaling, redraw bitmap layers as needed</h3>
<p>If you scaled an image up from a bitmap layer, rather than from a vector
layer, those layers will need to be redrawn manually to appear crisp at higher
densities. For example if a 60x60 circle was painted as a bitmap for
<code>mdpi</code> it will need to be repainted as a 90x90 circle for
<code>hdpi</code>.</p>
<h3>When saving image assets, remove unnecessary metadata</h3>
<p>To help keep each image asset as small as possible, make sure to remove any
unnecessary headers from the file, such as Adobe Fireworks metadata or Adobe
Photoshop headers. To remove the Photoshop header, follow these steps: </p>
<ol>
<li>Under the <strong>File</strong> menu, choose the <strong>Save for Web &amp;
Devices</strong> command </li>
<li>On the "Save for Web &amp; Devices" panel, set the Preset pop-up to
"PNG-24," set the pop-up under Presets to "PNG-24" as well, and select the
Transparency box (if the image uses transparency)</li>
<li>Select <strong>Save</strong>.</li>
</ol>
<p>It is also useful to use PNG file size optimization tools such as <a
href="http://optipng.sourceforge.net/">OptiPNG</a> or <a
href="http://pmt.sourceforge.net/pngcrush/">Pngcrush</a>.
<h3>Make sure that corresponding assets for different densities use the same
filenames</h3>
<p>Corresponding icon asset files for each density <strong>must use the same
filename</strong>, but be stored in density-specific resource directories. This
allows the system to look up and load the proper resource according to the
screen characteristics of the device. For this reason, make sure that the set of
assets in each directory is consistent and that the files do not use
density-specific suffixes.</p>
<p>For more information about density-specific resources
and how the system uses them to meet the needs of different devices, see <a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a>.</p>

9
base/docs/html/guide/practices/ui_guidelines/icon_design_1.html Normal file
View File

@ -0,0 +1,9 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=icon_design.html">
<title>Redirecting...</title>
</head>
<body>
<a href="icon_design.html">click here</a> if you are not redirected.
</body>
</html>

164
base/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd Normal file
View File

@ -0,0 +1,164 @@
page.title=Dialog Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#icon1">All Android Versions</a>
<ol>
<li><a href="#structure1">Structure</a></li>
<li><a href="#style1">Light, effects, and shadows</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>Dialog icons are shown in pop-up dialog boxes that prompt the user for
interaction. They use a light gradient and inner
shadow in order to stand out against a dark background.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icon sets for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See Table 1 for a listing of the recommended finished icon sizes for each
density. Also, see <a href="icon_design.html#design-tips">Tips for Designers</a>
for suggestions on how to work with multiple sets of icons.</p>
<p class="table-caption"><strong>Table 1.</strong> Summary of finished dialog
icon dimensions for each of the three generalized screen densities.</p>
<table>
<tbody>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Low density screen <em>(ldpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Medium density screen <em>(mdpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>High density screen <em>(hdpi)</em><nobr>
</th>
</tr>
<tr>
<td>
24 x 24 px
</td>
<td>
32 x 32 px
</td>
<td>
48 x 48 px
</td>
</tr>
</tbody>
</table>
<p><strong>Final art must be exported as a transparent PNG file. Do not include
a background color</strong>.</p>
<p>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</p>
<h2 id="icon1">All Android Versions</h2>
<p>The following guidelines describe how to design dialog icons for all versions
of the Android platform.</p>
<h3 id="structure1">Structure</h3>
<ul>
<li>Dialog icons have a 1 pixel safeframe. The base shape must fit within the
safeframe, but the anti-alias of a round shape can overlap the safeframe.</li>
<li>All dimensions specified on this page are based on a 32x32 pixel artboard size
in Adobe Photoshop. Keep 1 pixel of padding around the bounding box inside the
Photoshop template.</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/dialog_icon.png" alt="A view of dialog
icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 1. </strong>Safeframe and fill gradient for dialog icons.
Icon size is 32x32.</p>
</div>
</td>
</tr>
</table>
<h3 id="style1">Light, effects, and shadows</h3>
<p>Dialog icons are flat and pictured face-on. In order to stand out against a
dark background, they are built up using a light gradient and inner shadow.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/dialog_light.png" alt="A view of light,
effects, and shadows for dialog icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 2. </strong>Light, effects, and shadows for dialog
icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Front part:</td><td>gradient overlay | angle 90&deg;<br>bottom: r 223 | g 223 | b 223<br>top: r 249 | g 249 | b 249<br>bottom color location: 0%<br>top color location: 75%</td></tr>
<tr><td><em>2.</em></td><td>Inner shadow:</td><td>black | 25% opacity | <br>angle -90&deg; | distance 1px | size 0px</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0;">
<h4 id="steps1">Step by step</h4>
<ol>
<li>Create the basic shapes using a tool like Adobe Illustrator.</li>
<li>Import the shape into a tool like Adobe Photoshop and scale to fit an image
of 32x32 px on a transparent background. </li>
<li>Add the effects seen in Figure 2 for the proper filter.</li>
<li>Export the icon at 32x32 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>

520
base/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd Normal file
View File

@ -0,0 +1,520 @@
page.title=Launcher Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#market">Application Icons in Android Market</a></li>
<li><a href="#icon5">Android 2.0 and Later</a>
<ol>
<li><a href="#style5">Style</a></li>
<li><a href="#size5">Size</a></li>
<li><a href="#materialscolors5">Materials and colors</a></li>
<li><a href="#effects5">Effects</a></li>
<li><a href="#dodonts5">Do's and don'ts</a></li>
<li><a href="#examples5">Example icons</a></li>
</ol>
</li>
<li><a href="#icon1">Android 1.6 and Earlier</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>A Launcher icon is a graphic that represents your application on the device's
Home screen and in the Launcher window.</p>
<p>The user opens the Launcher by touching the icon at the bottom of the Home
screen. The Launcher opens and exposes the icons for all of the installed
applications. The user selects an application and opens it by touching the
Launcher icon or by means of any hardware navigation controls available, such as
a trackball or d-pad.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icons for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See <a href="icon_design.html#design-tips">Tips for Designers</a> for
suggestions on how to work with multiple sets of icons.</p>
<h2 id="market">Application Icons in Android Market</h2>
<p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing
your application on Android Market</a>, you will also need to provide a 512x512
pixel, high-resolution application icon in the <a
href="http://market.android.com/publish">developer console</a> at upload-time.
This icon will be used in various locations in Android Market and does
not replace your launcher icon.</p>
<p>For tips and recommendations on creating high-resolution launcher icons that
can easily be scaled up to 512x512, see
<a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#design-tips">
Tips for Designers</a>.</p>
<p>For information and specifications about high-resolution application
icons in Android Market, see the following article:</p>
<p style="margin-left:2em"><a
href="http://market.android.com/support/bin/answer.py?answer=1078870">
Graphic Assets for your Application (Android Market Help) &raquo;</a>
<h2 id="icon5">Android 2.0 and Later</h2>
<p>Starting with Android 2.0, launcher icons should be front-facing, instead of
at a three-quarter perspective. The following guidelines describe how to design
launcher icons for Android 2.0 (API Level 5) and later.</p>
<h3 id="style5">Style</h3>
<p>The launcher icons that you create should follow the general style principles
below. The guidelines aren't meant to restrict what you can do with your icons,
but rather they are meant to emphasize the common approaches that your icons can
share with others on the device. Figure 1, at right, provides examples. </p>
<div class="figure">
<img src="{@docRoot}images/icon_design/IconGraphic_Icons_i.png"
width="340">
<p class="img-caption">
<strong>Figure 1.</strong> Example launcher icons for Android 2.0 and
greater.
</p>
</div>
<p>Clean and contemporary:</p>
<ul>
<li>Launcher icons should be modern and sometimes quirky; they should not
appear aged or ragged. You should avoid overused symbolic metaphors whenever
possible.</li>
</ul>
<p>Simple and iconic:</p>
<ul>
<li>Android Launcher icons are caricatural in nature; your icons should be
highly simplified and exaggerated, so that they are appropriate for use at small
sizes. Your icons should not be overly complicated. </li>
<li>Try featuring a single part of an application as a symbolic
representation of the whole (for example, the Music icon features a speaker).
</li>
<li>Consider using natural outlines and shapes, both geometric and organic,
with a realistic (but never photorealistic) rendering. </li>
<li>Your icons <em>should not</em> present a cropped view of a larger
image.</li>
</ul>
<p>Tactile and textured:</p>
<ul>
<li>Icons should feature non-glossy, textured material. See
<a href="#materialscolors5">Materials and colors</a>, below, for more
information.</li>
</ul>
<p>Forward-facing and top-lit:</p>
<ul>
<li><em>New for Android 2.0 and later platforms</em>: Android Launcher
icons should be forward-facing, with very little perspective, and they
should be top-lit.</li>
</ul>
<p class="note"><strong>Note:</strong> Android applies separate text labels
using the application name when displaying launcher icons, so you should avoid
embedding text in your icon and instead focus on designing a distinct and
memorable icon.</p>
<h3 id="size5">Size and positioning</h3>
<p>Launcher icons should use a variety of shapes and forms that are scaled and
positioned inside the asset to create consistent visual weight with other
icons.</p>
<p>Figure 2 illustrates various ways of positioning the icon inside the
asset. You should size the icons <em>smaller than the actual bounds of the
asset</em> to create a consistent visual weight and to allow for shadows. If
your icon is square or nearly square, it should be scaled even smaller.</p>
<p>In order to indicate the recommended size for the icon, each example in
Figure 2 includes three different guide rectangles:</p>
<ul>
<li>The red box is the bounding box for the full asset.</li>
<li>The blue box is the recommended bounding box for the actual icon.
The icon box is sized smaller than the full asset box so that there is space to
include shadows and allow for special icon treatments.</li>
<li>The orange box is the recommended bounding box for the actual icon when
the content is square. The box for square icons is smaller than that for other
icons to establish a consistent visual weight across the two types.</li>
</ul>
<table>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Launcher icon dimensions for high-density (<code>hdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 72 x 72 px</li>
<li>Icon: 60 x 60 px</li>
<li>Square Icon: 56 x 56 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/launcher_size_hdpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Launcher icon dimensions for medium-density (<code>mdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 48 x 48 px</li>
<li>Icon: 40 x 40 px</li>
<li>Square Icon: 38 x 38 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/launcher_size_mdpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Launcher icon dimensions for low-density (<code>ldpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 36 x 36 px</li>
<li>Icon: 30 x 30 px</li>
<li>Square Icon: 28 x 28 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/launcher_size_ldpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;"></td>
<td style="border:0;">
<p class="table-caption"><strong>Figure 2.</strong>
Launcher icon sizing and positioning inside the bounds of the
icon asset.</p>
</td>
</tr>
</table>
<h3 id="materialscolors5">Materials and colors</h3>
<p>Launcher icons should make use of tactile, top-lit, textured materials. Even
if your icon is just a simple shape, you should try to render in a way that
makes it appear to be sculpted from some real-world material.</p>
<p>Android launcher icons usually consist of a smaller shape within a
larger base shape and combine one neutral and one primary color. Icons may
use a combination of neutral colors but should maintain a fairly high level of
contrast. Icons should not use more than one primary color per icon, if
possible.</p>
<p>Launcher icons should use a limited color palette that includes a range
of neutral and primary colors. The icons should not be over-saturated.</p>
<p>The recommended color palette to use for Launcher icons is shown in Figure 3.
You can use elements of the palette for both the base color and the highlight
color. You can use the colors of the palette in conjunction with a
white-to-black vertical linear gradient overlay. This creates the impression
that the icon is lit from above and keeps the color less saturated.</p>
<img src="{@docRoot}images/icon_design/IconGraphic_Colors.png" width="530">
<p class="img-caption">
<strong>Figure 3.</strong> Recommended color palette for icons.</p>
<p>When you combine the materials in Figure 4 with a color highlight from the
recommended palette above, you can create materials combinations such as those
shown in Figure 5. To get you started, the
<a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon Templates Pack</a>
includes a Photoshop file (<code>ic_launcher_template/example_materials.psd</code>)
that provides all of the default materials, colors, and gradients. </p>
<table>
<tbody>
<tr>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/IconGraphic_Materials.png" width="450">
<p class="img-caption">
<strong>Figure 4.</strong> Example materials that you can use to create
your icons.</p>
</td>
<td style="border:0;border-left:1px solid #ccc;margin-left:1em;padding-left:1em">
<img src="{@docRoot}images/icon_design/IconGraphic_AccentColor.png" width="450">
<p class="img-caption">
<strong>Figure 5.</strong> Examples of materials combined with base
and highlight colors from the recommended palette.</p>
</td>
</tr>
</tbody>
</table>
<h3 id="effects5">Effects</h3>
<p>Launcher icons are flat and the perspective is straight-on, rather than at an
angle. A drop shadow is used to create a sense of depth. Launcher icons can use
varying textures and lighting effects, but must be lit directly from above
(straight down).</p>
<p>In order to maintain consistency, all launcher icons should use the same
drop shadow effect, as shown in Figure 6.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/launcher_style.png"/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 6. </strong>Style, light and effects for launcher icons.</p>
<div class="image-caption-nested">
<p><em>Note: all pixel dimensions are for medium density and should be scaled appropriately for other densities.</em></p>
<table>
<tr><td><em>1.</em></td><td nowrap>Lighting:</td><td>Top-lit, using appropriate lighting details<br><br></td></tr>
<tr><td><em>2.</em></td><td nowrap>Drop shadow:</td><td><code>#000000</code>, 75% opacity<br>angle 90&deg;<br>distance 1px<br>size 3px<br><br></td></tr>
<tr><td><em>3.</em></td><td nowrap>Textures:</td><td>Tactile, appear to use real-world materials (monochromatic noise in example image)<br><br></td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<h3 id="dodonts5">Do's and don'ts</h3>
<p>Below are some "do and don't" examples to consider when creating icons for
your application. </p>
<table>
<tr>
<td style="border:0;width:50%">
<h4>Android Launcher icons are...</h4>
<ul>
<li>Modern, minimal, matte, tactile, and textured</li>
<li>Forward-facing and top-lit, whole, limited in color
palette</li>
</ul>
</td>
<td style="border:0;width:50%">
<h4>Android Launcher icons are not...</h4>
<ul>
<li>Antique, over-complicated, glossy, flat vector</li>
<li>Rotated, Cropped, Over-Saturated</li>
</ul>
</td>
</tr>
<tr>
</table>
<img src="{@docRoot}images/icon_design/IconGraphic_DosDonts.png"/>
<p class="img-caption">
<strong>Figure 7.</strong> Side-by-side examples of "do's and don'ts" for
Android launcher icons. </p>
<h3 id="examples5">Example icons</h3>
<p>Shown below are examples of high-density launcher icons used by
Android applications. The icons are provided for your reference only &mdash;
please do not reuse these icons in your applications.</code>.</p>
<img src="{@docRoot}images/icon_design/IconGraphic_Icons.png" />
<h2 id="icon1">Android 1.6 and earlier</h2>
<p>The following guidelines describe how to design launcher icons for Android
1.6 (API Level 4) and earlier. Launcher icons for Android 1.6 and below are
simplified 3D icons with a fixed perspective. The required perspective is shown
in Figure 8.</p>
<h3 id="structure1">Structure</h3>
<ul>
<li>The base of a launcher icon can face either the top view or the front
view.</li>
<li>The majority of a launcher icon’s surface should be created using the
launcher icon <a href="#palette1">color palette</a>. To add emphasis, use
one or more bright accent colors to highlight specific characteristics.</li>
<li>All launcher icons must be created with rounded corners to make them look
friendly and simple—as shown in Figure 8.</li>
<li>All dimensions specified are based on a 250x250 pixel artboard size
in a vector graphics editor like Adobe Illustrator, where the icon fits within
the artboard boundaries.</li>
<li><strong>Final art must be scaled down and exported as a transparent PNG file
using a raster image editor such as Adobe Photoshop. Do not include a background
color.</strong></li>
<li>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/launcher_structure.png" alt="A view of
launcher icon corners and perspective angles" />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 8.</strong> Rounded corners and perspective angles for
launcher icons (90° is vertical).</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>92°</td></tr>
<tr><td><em>2.</em></td><td>92°</td></tr>
<tr><td><em>3.</em></td><td>173°</td></tr>
<tr><td><em>4.</em></td><td>171°</td></tr>
<tr><td><em>5.</em></td><td>49°</td></tr>
<tr><td><em>6.</em></td><td>171°</td></tr>
<tr><td><em>7.</em></td><td>64°</td></tr>
<tr><td><em>8.</em></td><td>97°</td></tr>
<tr><td><em>9.</em></td><td>75°</td></tr>
<tr><td><em>10.</em></td><td>93°</td></tr>
<tr><td><em>11.</em></td><td>169°</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<h3 id="style1">Light, effects, and shadows</h3>
<p>Launcher icons are simplified 3D icons using light and shadows for
definition. A light source is placed slightly to the left in front of the icon,
and therefore the shadow expands to the right and back.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/launcher_light.png" alt="A view of
light, effects, and shadows for launcher icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 9. </strong>Light, effects, and shadows for launcher icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Edge highlight:</td><td>white</td></tr>
<tr><td><em>2.</em></td><td>Icon shadow:</td><td>black | 20px blur<br>50% opacity | angle 67°</td></tr>
<tr><td><em>3.</em></td><td>Front part:</td><td>Use light gradient from color palette</td></tr>
<tr><td><em>4.</em></td><td>Detail shadow:</td><td>black | 10px blur<br>75% opacity</td></tr>
<tr><td><em>5.</em></td><td> Side part:</td><td>Use medium gradient from color palette</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="palette1">Launcher icon color palette</h4>
<table>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/launcher_palette_white.png"/></td>
<td class="image-caption-c">White<br>r 255 | g 255 | b 255<br>Used for highlights on edges.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/launcher_palette_gradient_light.png"/></td>
<td class="image-caption-c">Light gradient<br><em>1:&nbsp;&nbsp;</em>r 0 | g 0 | b 0<br><em>2:&nbsp;&nbsp;</em>r 217 | g 217 | b 217<br>Used on the front (lit) part of the icon.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/launcher_palette_gradient_medium.png"/></td>
<td class="image-caption-c">Medium gradient<br><em>1:&nbsp;&nbsp;</em>r 190 | g 190 | b 190<br><em>2:&nbsp;&nbsp;</em>r 115 | g 115 | b 115<br>Used on the side (shaded) part of the icon.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/launcher_palette_gradient_dark.png"/></td>
<td class="image-caption-c">Dark gradient<br><em>1:&nbsp;&nbsp;</em>r 100 | g 100 | b 100<br><em>2:&nbsp;&nbsp;</em>r 25 | g 25 | b 25<br>Used on details and parts in the shade of the icon.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/launcher_palette_black.png"/></td>
<td class="image-caption-c">Black<br>r 0 | g 0 | b 0<br>Used as base color in shadows.</td>
</tr>
</table>
</td>
<td style="border:0">
<h4 id="steps1">Step by step</h4>
<ol>
<li>Create the basic shapes with a tool like Adobe Illustrator, using the
angles described in <a href="#structure1">Launcher icon: structure</a>.
The shapes and effects must fit within a 250x250 pixel artboard.</li>
<li>Add depth to shapes by extruding them and create the rounded corners as
described for the launcher icon structure.</li>
<li>Add details and colors. Gradients should be treated as if there is a light
source placed slightly to the left in front of the icon.</li>
<li>Create the shadows with the correct angle and blur effect.</li>
<li>Import the icon into a tool like Adobe Photoshop and scale to fit an image
size of 48x48 px on a transparent background.</li>
<li>Export the icon at 48x48 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>

163
base/docs/html/guide/practices/ui_guidelines/icon_design_list.jd Normal file
View File

@ -0,0 +1,163 @@
page.title=List View Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#icon1">All Android Versions</a>
<ol>
<li><a href="#structure1">Structure</a></li>
<li><a href="#style1">Light, effects, and shadows</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>List view icons look a lot like dialog icons, but they use an inner shadow
effect where the light source is above the object. They are also designed to be
used only in a {@link android.widget.ListView}. Examples include the Settings
application.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icon sets for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See Table 1 for a listing of the recommended finished icon sizes for each
density. Also, see <a href="icon_design.html#design-tips">Tips for Designers</a>
for suggestions on how to work with multiple sets of icons.</p>
<p class="table-caption"><strong>Table 1.</strong> Summary of finished list view
icon dimensions for each of the three generalized screen densities.</p>
<table>
<tbody>
<tr>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Low density screen <em>(ldpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>Medium density screen <em>(mdpi)</em></nobr>
</th>
<th style="background-color:#f3f3f3;font-weight:normal">
<nobr>High density screen <em>(hdpi)</em><nobr>
</th>
</tr>
<tr>
<td>
24 x 24 px
</td>
<td>
32 x 32 px
</td>
<td>
48 x 48 px
</td>
</tr>
</tbody>
</table>
<p><strong>Final art must be exported as a transparent PNG file. Do not include
a background color</strong>.</p>
<p>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</p>
<h2 id="icon1">All Android Versions</h2>
<p>The following guidelines describe how to design dialog icons for all versions
of the Android platform.</p>
<h3 id="structure1">Structure</h3>
<ul>
<li>A list view icon normally has a 1 px safeframe, but it is OK to use the
safeframe area for the edge of the anti-alias of a round shape.</li>
<li>All dimensions specified are based on a 32x32 pixel artboard size in
Photoshop. Keep 1 pixel of padding around the bounding box inside the template.
</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/listview_icon.png" alt="A view of list
view icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 1. </strong>Safeframe and fill gradient for list view
icons. Icon size is 32x32.</p>
</div>
</td>
</tr>
</table>
<h3 id="style1">Light, effects, and shadows</h3>
<p>List view icons are flat and pictured face-on with an inner shadow. Built up
by a light gradient and inner shadow, they stand out well on a dark
background.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/listview_icon_details.png" alt="A view
of light, effects, and shadows for list view icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 2. </strong>Light, effects, and shadows for list view
icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Inner shadow:</td><td>black | 57 % opacity | angle 120&deg; | blend mode normal | distance 1px | size 1px <td></tr>
<tr><td><em>2.</em></td><td>Background:</td><td>black | standard system color <br>These icons are displayed in list views only.</td></tr>
<tr><td colspan="2">Note: The list view icon sits on 32x32 px artboard in Photoshop, without a safeframe.</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="steps1">Step by step</h4>
<ol>
<li>Add the effects seen in Figure 2 for the proper filter.</li>
<li>Export the icon at 32x32 as a PNG file with transparency enabled.</li>
<li>Create the basic shapes using a tool like Adobe Illustrator.</li>
<li>Import the shape into a tool like Adobe Photoshop and scale to fit an image
of 32x32 px on a transparent background. </li>
</ol>
</td>
</tr>
</table>

349
base/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd Normal file
View File

@ -0,0 +1,349 @@
page.title=Menu Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#icon9">Android 2.3 and Later</a>
<ol>
<li><a href="#size9">Size</a></li>
<li><a href="#style9">Style, colors, and effects</a></li>
<li><a href="#dodonts9">Do's and don'ts</a></li>
<li><a href="#examples9">Example icons</a></li>
</ol>
</li>
<li><a href="#icon1">Android 2.2 and Earlier</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>Menu icons are graphical elements placed in the options menu shown to users
when they press the Menu button. They are drawn in a flat-front perspective and
in greyscale. Elements in a menu icon must not be visualized in 3D or
perspective.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icon sets for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See <a href="icon_design.html#design-tips">Tips for Designers</a>
for suggestions on how to work with multiple sets of icons.</p>
<p><strong>Final art must be exported as a transparent PNG file. Do not include
a background color</strong>.</p>
<p>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</p>
<p class="caution"><strong>Caution:</strong> The style and content sizing of
menu icons have changed in Android 2.3 compared to
<a href="#icon1">previous versions</a>:
<br>
1. Icons have a larger safe frame; icon content is smaller within the full
asset. Final asset sizes have not changed.
<br>
2. The color palette is slightly lighter.
<br>
3. No outer glow effects are applied.
<br>
4. Menu icons can now be rendered on either dark or light backgrounds.
</p>
<h2 id="icon9">Android 2.3 and Later</h2>
<p>The following guidelines describe how to design menu icons for Android
2.3 (API Level 9) and later.</p>
<h3 id="size9">Size and positioning</h3>
<p>Menu icons can use a variety of shapes and forms and must be scaled and
positioned inside the asset to create consistent visual weight with other
icons.</p>
<p>Figure 1 illustrates various ways of positioning the icon inside the
asset. You should size the icons <em>smaller than the actual bounds of the
asset</em>, to create a consistent visual weight. If your icon is square or
nearly square, it should be scaled even smaller.</p>
<p>In order to indicate the recommended size for the icon, each example in
Figure 1 includes three different guide rectangles:</p>
<ul>
<li>The red box is the bounding box for the full asset.</li>
<li>The blue box is the recommended bounding box for the actual icon.
The icon box is sized smaller than the full asset box to allow for
varying icon shapes while maintaining a consistent visual weight.</li>
<li>The orange box is the recommended bounding box for the actual icon when
the content is square. The box for square icons is smaller than that for other
icons to establish a consistent visual weight across the two types.</li>
</ul>
<table>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Menu icon dimensions for high-density (<code>hdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 72 x 72 px</li>
<li>Icon: 48 x 48 px</li>
<li>Square Icon: 44 x 44 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/menu_size_hdpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Menu icon dimensions for medium-density (<code>mdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 48 x 48 px</li>
<li>Icon: 32 x 32 px</li>
<li>Square Icon: 30 x 30 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/menu_size_mdpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Menu icon dimensions for low-density (<code>ldpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 36 x 36 px</li>
<li>Icon: 24 x 24 px</li>
<li>Square Icon: 22 x 22 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/menu_size_ldpi.png" width="450">
</td>
</tr>
<tr>
<td style="border:0;"></td>
<td style="border:0;">
<p class="table-caption"><strong>Figure 1.</strong>
Menu icon sizing and positioning inside the bounds of the
icon asset.</p>
</td>
</tr>
</table>
<h3 id="style9">Style, colors, and effects</h3>
<p>Menu icons are flat, pictured face on, and greyscale. A slight deboss and
some other effects, which are shown below, are used to create depth. Menu icons
should include rounded corners, but only when logically appropriate.</p>
<p>In order to maintain consistency, all menu icons must use the same
color palette and effects, as shown in Figure 2.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/menu_style.png" alt="A view of light, effects, and shadows for menu icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 2. </strong>Style, light and effects for menu icons.</p>
<div class="image-caption-nested">
<p><em>Note: all pixel dimensions are for medium density and should be scaled appropriately for other densities.</em></p>
<table>
<tr><td><em>1.</em></td><td nowrap>Corner rounding:</td><td>2 pixel corner radius, when appropriate<br><br></td></tr>
<tr><td><em>2.</em></td><td nowrap>Fill gradient:</td><td>90&deg;, from <code>#8C8C8C</code> to <code>#B2B2B2</code><br><br></td></tr>
<tr><td><em>3.</em></td><td nowrap>Inner shadow:</td><td><code>#000000</code>, 20% opacity<br>angle 90&deg;<br>distance 2px<br>size 2px<br><br></td></tr>
<tr><td><em>4.</em></td><td nowrap>Inner bevel:</td><td>depth 1%<br>direction down<br>size 0px<br>angle 90&deg;<br>altitude 10&deg;<br>highlight <code>#ffffff</code>, 70% opacity<br>shadow <code>#000000</code>, 25% opacity</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<h3 id="dodonts9">Do's and don'ts</h3>
<p>Below are some "do and don't" examples to consider when creating menu icons for
your application. </p>
<img src="{@docRoot}images/icon_design/do_dont_menuicons.png">
<h3 id="examples9">Example icons</h3>
<p>Shown below are standard high-density menu icons that are used in the Android
platform.</p>
<p class="warning"><strong>Warning:</strong> Because these resources can change
between platform versions, you should not reference these icons using the
Android platform resource IDs (i.e. menu icons under
<code>android.R.drawable</code>). If you want to use any icons or other internal
drawable resources, you should store a local copy of those icons or drawables in
your application resources, then reference the local copy from your application
code. In that way, you can maintain control over the appearance of your icons,
even if the system's copy changes. Note that the grid below is not intended to
be complete.</p>
<img src="{@docRoot}images/icon_design/menu_standard.png" />
<h2 id="icon1">Android 2.2 and Earlier</h2>
<p>The following guidelines describe how to design menu icons for Android 2.2
(API Level 4) and earlier. Menu icons in Android 2.2 and below are drawn in a
flat-front perspective. Elements in a menu icon must not be visualized in 3D or
perspective.</p>
<h3 id="structure1">Structure</h3>
<ul>
<li>In order to maintain consistency, all menu icons must use the same
primary palette and the same effects. For more information, see the
menu icon <a href="#palette1">color palette</a>. </li>
<li>Menu icons should include rounded corners, but only when logically
appropriate. For example, in Figure 3 the logical place for rounded corners is
the roof and not the rest of the building.</span></li>
<li>All dimensions specified on this page are based on a 48x48 pixel artboard
size with a 6 pixel safeframe.</li>
<li>The menu icon effect (the outer glow) described in <a
href="#style1">Light, effects, and shadows</a> can overlap the 6px safeframe,
but only when necessary. The base shape must always stay inside the
safeframe.</li>
<li><strong>Final art must be exported as a transparent PNG file.</strong></li>
<li>Templates for creating menu icons in Adobe Photoshop are available in the
Icon Templates Pack.</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/menu_structure.png" alt="A view of menu
icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 3. </strong>Safeframe and corner-rounding for menu
icons. Icon size is 48x48.</p>
</div>
</td>
</tr>
</table>
<h3 id="style1">Light, effects, and shadows</h3>
<p>Menu icons are flat and pictured face on. A slight deboss and some other
effects, which are shown below, are used to create depth.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/menu_light.png" alt="A view of light, effects, and shadows for launcher icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 4. </strong>Light, effects, and shadows for launcher icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Front part:</td><td>Use fill gradient from primary color palette</td></tr>
<tr><td><em>2.</em></td><td>Inner shadow:</td><td>black | 20 % opacity<br>angle 90° | distance 2px<br>size 2px</td></tr>
<tr><td><em>3.</em></td><td>Outer glow:</td><td>white | 55% opacity <br>spread 10% | size 3px</td></tr>
<tr><td><em>5.</em></td><td>Inner bevel:</td><td>depth 1% | direction down size 0px<br>angle 90° | altitude 10°<br>highlight white 70% opacity<br>shadow black 25% opacity</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="palette1">Color palette</h4>
<table>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/menu_palette_white.png"/></td>
<td class="image-caption-c">White<br>r 255 | g 255 | b 255<br>Used for outer glow and bevel highlight.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/menu_palette_gradient_medium.png"/></td>
<td class="image-caption-c">Fill gradient<br><em>1:&nbsp;&nbsp;</em>r 163 | g 163 | b 163<br><em>2:&nbsp;&nbsp;</em>r 120 | g 120 | b 120<br>Used as color fill.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/menu_palette_black.png"/></td>
<td class="image-caption-c">Black<br>r 0 | g 0 | b 0<br>Used for inner shadow and bevel shadow.</td>
</tr>
</table>
</td>
<td style="border:0">
<h4 id="steps1">Step by step</h4>
<ol>
<li>Create the basic shapes using a tool like Adobe Illustrator.</li>
<li>Import the shape into a tool like Adobe Photoshop and scale to fit an image
of 48x48 px on a transparent background. Mind the safeframe.</li>
<li>Add the effects seen as described in Figure 4.</li>
<li>Export the icon at 48x48 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>

330
base/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd Normal file
View File

@ -0,0 +1,330 @@
page.title=Status Bar Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#icon9">Android 2.3 and Later</a>
<ol>
<li><a href="#size9">Size</a></li>
<li><a href="#style9">Style, color, and effects</a></li>
<li><a href="#dodonts9">Do's and don'ts</a></li>
<li><a href="#examples9">Example icons</a></li>
</ol>
</li>
<li><a href="#icon1">Android 2.2 and Earlier</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>Status bar icons are used to represent notifications from your application in
the status bar.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icon sets for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See <a href="icon_design.html#design-tips">Tips for Designers</a> for
suggestions on how to work with multiple sets of icons.</p>
<p><strong>Final art must be exported as a transparent PNG file. Do not include
a background color</strong>.</p>
<p>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</p>
<p class="warning"><strong>Warning:</strong>
The style and dimensions of status bar icons have changed drastically in
Android 2.3 compared to <a href="#icon1">previous versions</a>. <strong>To
provide support for all Android versions</strong>, developers should:
<br>
1. Place status bar icons for Android 2.3 and higher in the
<code>drawable-hdpi-v9</code>, <code>drawable-mdpi-v9</code>, and <code>drawable-ldpi-v9</code> directories.
<br>
2. Place status bar icons for previous versions in
<code>drawable-hdpi</code>, <code>drawable-mdpi</code>, and <code>drawable-ldpi</code> directories.
</p>
<h2 id="icon9">Android 2.3 and Later</h2>
<p>The following guidelines describe how to design status bar icons for Android
2.3 (API Level 9) and later.</p>
<h3 id="size9">Size and positioning</h3>
<p>Status bar icons should use simple shapes and forms and those must be
scaled and positioned inside the final asset.</p>
<p>Figure 1 illustrates various ways of positioning the icon inside the
asset. You should size the icons <em>smaller than the actual bounds of the
asset</em>. <strong>Status bar icons may vary in width, but only
minimally.</strong></p>
<p>In order to indicate the recommended size for the icon, each example in
Figure 1 includes two different guide rectangles:</p>
<ul>
<li>The red box is the bounding box for the full asset.</li>
<li>The blue box is the recommended bounding box for the actual icon.
The icon box is sized smaller vertically than the full asset box to allow for
varying icon shapes while maintaining a consistent visual weight.</li>
</ul>
<table>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Status bar icon dimensions for high-density (<code>hdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 24w x 38h px (preferred, width may vary)</li>
<li>Icon: 24w x 24h px (preferred, width may vary)</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/statusbar_size_hdpi.png" width="318">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Status bar icon dimensions for medium-density (<code>mdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 16w x 25 px (preferred, width may vary)</li>
<li>Icon: 16w x 16w px (preferred, width may vary)</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/statusbar_size_mdpi.png" width="318">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Status bar icon dimensions for low-density (<code>ldpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 12w x 19h px (preferred, width may vary)</li>
<li>Icon: 12w x 12h px (preferred, width may vary)</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/statusbar_size_ldpi.png" width="318">
</td>
</tr>
<tr>
<td style="border:0;"></td>
<td style="border:0;">
<p class="table-caption"><strong>Figure 1.</strong>
Status bar icon sizing and positioning inside the bounds of the
icon asset.</p>
</td>
</tr>
</table>
<h3 id="style9">Style, colors, and effects</h3>
<p>Status bar icons are flat, matte, and pictured face-on.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/statusbar_style.png" alt="A view of effects for status bar icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 2. </strong>Style and effects for status icons.</p>
<div class="image-caption-nested">
<p><em>Note: all pixel dimensions are for medium density and should be scaled appropriately for other densities.</em></p>
<table>
<tr><td><em>1.</em></td><td nowrap>Fill gradient:</td><td>90&deg;, from <code>#828282</code> to <code>#919191</code><br><br></td></tr>
<tr><td><em>2.</em></td><td nowrap>Inner shadow:</td><td><code>#FFFFFF</code>, 10% opacity<br>angle 90&deg;<br>distance 1px<br>size 0px<br><br></td></tr>
<tr><td><em>3.</em></td><td nowrap>Inner content:</td><td>Inner content should subtract from the outer shape and consist purely of transparent pixels.</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<h3 id="dosdonts9">Do's and don'ts</h3>
<p>Below are some "do and don't" examples to consider when creating status bar icons for
your application. </p>
<img src="{@docRoot}images/icon_design/do_dont_statusicons.png">
<h3 id="examples9">Example icons</h3>
<p>Shown below are standard high-density status bar icons that are used in
the Android platform.</p>
<p class="warning"><strong>Warning:</strong> Because these resources can change
between platform versions, you should not reference these icons using the
Android platform resource IDs (i.e. status bar icons under
<code>android.R.drawable</code>). If you want to use any icons or other internal
drawable resources, you should store a local copy of those icons or drawables in
your application resources, then reference the local copy from your application
code. In that way, you can maintain control over the appearance of your icons,
even if the system's copy changes. Note that the grid below is not intended to
be complete.</p>
<img src="{@docRoot}images/icon_design/statusbar_standard.png" />
<h2 id="icon1">Android 2.2 and Earlier</h2>
<p>The following guidelines describe how to design status bar icons for Android
2.2 (API Level 8) and earlier.</p>
<h3 id="structure1">Structure</h3>
<ul>
<li>Rounded corners must always be applied to the base shape and to the details
of a status bar icon shown Figure 3.</li>
<li>All dimensions specified are based on a 25x25 pixel artboard size with a 2
pixel safeframe.</li>
<li>Status bar icons can overlap the safeframe to the left and right when
necessary, but must not overlap the safeframe at the top and bottom.</li>
<li><strong>Final art must be exported as a transparent PNG file.</strong></li>
<li>Templates for creating status bar icons using Adobe Photoshop are available
in the Icon Templates Pack.</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/statusbar_structure.png" alt="A view of
status bar icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 3. </strong>Safeframe and corner-rounding for status bar
icons. Icon size is 25x25.</p>
</div>
</td>
</tr>
</table>
<h3 id="style1">Light, effects, and shadows</h3>
<p>Status bar icons are slightly debossed, high in contrast, and pictured
face-on to enhance clarity at small sizes.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/statusbar_light.png"/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 4. </strong>Light, effects, and shadows for status bar icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Front part:</td><td>Use fill gradient from primary color palette</td></tr>
<tr><td><em>2.</em></td><td>Inner bevel:</td><td>depth 100% | direction down<br>size 0px | angle 90° |<br>altitude 30°<br>highlight white 75% opacity<br>shadow black 75% opacity</td></tr>
<tr><td><em>3.</em></td><td>Detail:</td><td>white</td></tr>
<tr><td><em>4.</em></td><td>Disabled detail:</td><td>grey gradient from palette<br>+ inner bevel: smooth | depth 1% | direction down | size 0px | angle 117° | <br>altitude 42° | highlight white 70% | no shadow</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="palette1">Color palette</h4>
<p>Only status bar icons related to the phone function use full color; all other status bar icons should remain monochromatic.</p>
<table>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/statusbar_palette_white.png"/></td>
<td class="image-caption-c">White<br>r 255 | g 255 | b 255<br>Used for details within the icons and bevel highlight.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/statusbar_palette_grey.png"/></td>
<td class="image-caption-c">Grey gradient<br><em>1:&nbsp;&nbsp;</em>r 169 | g 169 | b 169<br><em>2:&nbsp;&nbsp;</em>r 126 | g 126 | b 126<br>Used for disabled details within the icon.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/statusbar_palette_fill.png"/></td>
<td class="image-caption-c">Fill gradient<br><em>1:&nbsp;&nbsp;</em>1 r 105 | g 105 | b 105<br><em>2:&nbsp;&nbsp;</em>r 10 | g 10 | b 10<br>Used as color fill.</td>
</tr>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/statusbar_palette_black.png"/></td>
<td class="image-caption-c">Black<br>r 0 | g 0 | b 0<br>Used for bevel shadow.</td>
</tr>
</table>
</td>
<td style="border:0">
<h4 id="steps1">Step by step</h4>
<ol>
<li>In a tool like Adobe Photoshop, create the base shape within a 25x25 px
image on a transparent background. Mind the safeframe, and keep the upper and
lower 2 pixels free.</li>
<li>Add rounded corners as specified in Figure 3.</li>
<li>Add light, effects, and shadows as specified in Figure 4.</li>
<li>Export the icon at 25x25 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>

454
base/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd Normal file
View File

@ -0,0 +1,454 @@
page.title=Tab Icons
parent.title=Icon Design Guidelines
parent.link=icon_design.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#tabstates">Providing Icons for Two Tab States</a>
<li><a href="#icon5">Android 2.0 and Later</a>
<ol>
<li><a href="#size5">Size</a></li>
<li><a href="#style5">Style, colors, and effects</a></li>
<li><a href="#dodonts5">Do's and don'ts</a></li>
<li><a href="#examples5">Example icons</a></li>
</ol>
</li>
<li><a href="#icon1">Android 1.6 and Earlier</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
</ol>
</div>
</div>
<p>Tab icons are graphical elements used to represent individual tabs in a
multi-tab interface. Each tab icon has two states: unselected and selected.</p>
<p>As described in <a href="icon_design.html#icon-sets">Providing
Density-Specific Icon Sets</a>, you should create separate icon sets for low-,
medium-, and high-density screens. This ensures that your icons will display
properly across the range of devices on which your application can be installed.
See <a href="icon_design.html#design-tips">Tips for Designers</a>
for suggestions on how to work with multiple sets of icons.</p>
<p><strong>Final art must be exported as a transparent PNG file. Do not include
a background color</strong>.</p>
<p>Templates for creating icons in Adobe Photoshop are available in the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#templatespack">Icon
Templates Pack</a>.</p>
<p class="warning"><strong>Warning:</strong>
The style of tab icons has changed drastically in
Android 2.0 compared to <a href="#icon1">previous versions</a>. <strong>To
provide support for all Android versions</strong>, developers should:
<br>
1. Place tab icons for Android 2.0 and higher in the
<code>drawable-hdpi-v5</code>, <code>drawable-mdpi-v5</code>, and <code>drawable-ldpi-v5</code> directories.
<br>
2. Place tab icons for previous versions in
<code>drawable-hdpi</code>, <code>drawable-mdpi</code>, and <code>drawable-ldpi</code> directories.
<br>
3. Set <code>android:targetSdkVersion</code> to 5 or higher in the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
in the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">application manifest</a>.
This will inform the system that it should render tabs using the new tab style.
</p>
<h2 id="tabstates">Providing Icons for Two Tab States</h2>
<p>Tab icons should have two states: unselected and selected. To provide icons
with multiple states, developers must create a
<a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state
list drawable</a> for each an icon, which is an XML file that lists which image
to use for the different UI states.</p>
<p>For example, for a tab widget with tabs named 'Friends' and 'Coworkers',
you can use a directory structure similar to the one below:</p>
<pre>res/...
drawable/...
<strong>ic_tab_friends.xml</strong>
<strong>ic_tab_coworkers.xml</strong>
drawable-ldpi/...
ic_tab_friends_selected.png
ic_tab_friends_unselected.png
ic_tab_coworkers_selected.png
ic_tab_coworkers_unselected.png
drawable-mdpi/...
ic_tab_friends_selected.png
ic_tab_friends_unselected.png
ic_tab_coworkers_selected.png
ic_tab_coworkers_unselected.png
drawable-hdpi/...
...
drawable-ldpi-v5/...
...
drawable-mdpi-v5/...
...
drawable-hdpi-v5/...
...</pre>
<p>The contents of the XML files listed above should reference the corresponding
selected and unselected icon drawables. For example, below is the code
for <code>ic_tab_friends.xml</code>:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;selector xmlns:android="http://schemas.android.com/apk/res/android"&gt;
&lt;!-- selected state --&gt;
&lt;item android:drawable="@drawable/ic_tab_friends_selected"
android:state_selected="true"
android:state_pressed="false" /&gt;
&lt;!-- unselected state (default) --&gt;
&lt;item android:drawable="@drawable/ic_tab_friends_unselected" /&gt;
&lt;/selector&gt;
</pre>
<h2 id="icon5">Android 2.0 and Later</h2>
<p>The following guidelines describe how to design tab icons for Android
2.0 (API Level 5) and later.</p>
<h3 id="size5">Size and positioning</h3>
<p>Tab icons should use simple shapes and forms and those must be
scaled and positioned inside the final asset.</p>
<p>Figure 1 illustrates various ways of positioning the icon inside the
asset. You should size the icons <em>smaller than the actual bounds of the
asset</em>.</p>
<p>In order to indicate the recommended size for the icon, each example in
Figure 1 includes three different guide rectangles:</p>
<ul>
<li>The red box is the bounding box for the full asset.</li>
<li>The blue box is the recommended bounding box for the actual icon.
The icon box is sized smaller than the full asset box to allow for
special icon treatments.</li>
<li>The orange box is the recommended bounding box for the actual icon when
the content is square. The box for square icons is smaller than that for other
icons to establish a consistent visual weight across the two types.</li>
</ul>
<table>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Tab icon dimensions for high-density (<code>hdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 48 x 48 px</li>
<li>Icon: 42 x 42 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/tab_size_hdpi.png" width="385">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Tab icon dimensions for medium-density (<code>mdpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 32 x 32 px</li>
<li>Icon: 28 x 28 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/tab_size_mdpi.png" width="385">
</td>
</tr>
<tr>
<td style="border:0;">
<ol class="nolist">
<li>Tab icon dimensions for low-density (<code>ldpi</code>) screens:</li>
<ol class="nolist">
<li>Full Asset: 24 x 24 px</li>
<li>Icon: 22 x 22 px</li>
</ol>
</li>
</ol>
</td>
<td style="border:0;">
<img src="{@docRoot}images/icon_design/tab_size_ldpi.png" width="385">
</td>
</tr>
<tr>
<td style="border:0;"></td>
<td style="border:0;">
<p class="table-caption"><strong>Figure 1.</strong>
Tab icon sizing and positioning inside the bounds of the
icon asset.</p>
</td>
</tr>
</table>
<h3 id="style5">Style, colors, and effects</h3>
<p>Tab icons are flat, matte, and pictured face-on.</p>
<p>Tab icons should have two states: selected and unselected.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_style_unselected.png" alt="A view of effects for unselected tab icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 2. </strong>Style and effects for unselected tab icons.</p>
<div class="image-caption-nested">
<p><em>Note: all pixel dimensions are for medium density and should be scaled appropriately for other densities.</em></p>
<table>
<tr><td><em>1.</em></td><td nowrap>Fill color:</td><td><code>#808080</code><br><br></td></tr>
<tr><td><em>2.</em></td><td nowrap>Inner content:</td><td>Inner content should subtract from the outer shape and consist purely of transparent pixels.</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_style_selected.png" alt="A view of effects for selected tab icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 3. </strong>Style and effects for selected tab icons.</p>
<div class="image-caption-nested">
<p><em>Note: all pixel dimensions are for medium density and should be scaled appropriately for other densities.</em></p>
<table>
<tr><td><em>1.</em></td><td nowrap>Fill color:</td><td><code>#FFFFFF</code><br><br></td></tr>
<tr><td><em>2.</em></td><td nowrap>Inner content:</td><td>Inner content should subtract from the outer shape and consist purely of transparent pixels.<br><br></td></tr>
<tr><td><em>3.</em></td><td nowrap>Outer glow:</td><td><code>#000000</code>, 25% opacity<br>size 3px</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<h3 id="dosdonts5">Do's and don'ts</h3>
<p>Below are some "do and don't" examples to consider when creating tab icons for
your application. </p>
<img src="{@docRoot}images/icon_design/do_dont_tabicons.png">
<h3 id="examples5">Example icons</h3>
<p>Shown below are standard high-density tab icons that are used in
the Android platform.</p>
<p class="warning"><strong>Warning:</strong>
Because these resources can change between platform versions, you
should not reference the system's copy of the resources. If you want to
use any icons or other internal drawable resources, you should store a
local copy of those icons or drawables in your application resources,
then reference the local copy from your application code. In that way, you can
maintain control over the appearance of your icons, even if the system's
copy changes. Note that the grid below is not intended to be complete.</p>
<img src="{@docRoot}images/icon_design/tab_standard.png" />
<h2 id="icon1">Android 1.6 and Earlier</h2>
<p>The following guidelines describe how to design tab icons for Android
1.6 (API Level 4) and earlier.</p>
<h4 id="structure1">Structure</h4>
<ul>
<li>Unselected tab icons have the same fill gradient and effects as
<a href="icon_design_menu.html#icon1">menu icons</a>,
but with no outer glow.</li>
<li>Selected tab icons look just like unselected tab icons, but with a fainter
inner shadow, and have the same front part gradient as
<a href="icon_design_dialog.html#icon1">dialog icons</a>.</li>
<li>Tab icons have a 1 px safeframe which should only be overlapped for the edge
of the anti-alias of a round shape.</li>
<li>All dimensions specified on this page are based on a 32x32 px artboard size.
Keep 1 px of padding around the bounding box inside the Photoshop template.</li>
</ul>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_icon_unselected.png" alt="A view of
unselected tab icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 3. </strong>Safeframe and fill gradient for unselected tab
icons. Icon size is 32x32.</p>
</div>
</td>
</tr>
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_icon_selected.png" alt="A view of
selected tab icon structure." />
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 4. </strong>Safeframe and fill gradient for tab icons in
selected state. Icon size is 32x32.</p>
</div>
</td>
</tr>
</table>
<h3 id="unselectedtabdetails1">Unselected tab icon</h3>
<h4 id="unselectedtablight1">Light, effects, and shadows</h4>
<p>Unselected tab icons look just like the selected tab icons, but with a
fainter inner shadow, and the same front part gradient as the dialog icons.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_unselected_light.png" alt="A view
of light, effects, and shadows for unselected tab icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 5. </strong>Light, effects, and shadows for unselected
tab icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Front part:</td><td>gradient overlay | angle 90°<br>bottom color: r 223 | g 223 | b 223<br>top color: r 249 | g 249 | b 249<br>bottom color location: 0%<br>top color location: 75%</td></tr>
<tr><td><em>2.</em></td><td>Inner shadow:</td><td>black | 10 % opacity | angle 90° distance 2px | size 2px</td></tr>
<tr><td><em>3.</em></td><td>Inner bevel:</td><td>depth 1% | direction down | size 0px | angle 90° | altitude 10°<br>highlight white 70% opacity<br>shadow black 25% opacity</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="unselectedtabsteps1">Step by step</h4>
<ol>
<li>Create the basic shapes using a tool like Adobe Illustrator.</li>
<li>Import the shape to a tool like Adobe Photoshop and scale to fit an image of
32x32 px on a transparent background.</li>
<li>Add the effects seen in Figure 5 for the unselected state filter.</li>
<li>Export the icon at 32x32 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>
<h3 id="selectedtabdetails1">Selected tab icon</h3>
<p>The selected tab icons have the same fill gradient and effects as the menu
icon, but with no outer glow.</p>
<table class="image-caption">
<tr>
<td class="image-caption-i">
<img src="{@docRoot}images/icon_design/tab_selected_light.png" alt="A view of
light, effects, and shadows for selected tab icons."/>
</td>
<td class="image-caption-c">
<div class="caption grad-rule-top">
<p><strong>Figure 6. </strong>Light, effects, and shadows for selected tab
icons.</p>
<div class="image-caption-nested">
<table>
<tr><td><em>1.</em></td><td>Front part:</td><td>Use fill gradient from color palette.</td></tr>
<tr><td><em>2.</em></td><td>Inner shadow:</td><td>black | 20% opacity | <br>angle 90° | distance 2px | <br>size 2px</td></tr>
<tr><td><em>3.</em></td><td>Inner bevel:</td><td>depth 1% | direction down | size 0px | angle 90° | <br>altitude 10°<br>highlight white 70% opacity<br>shadow black 25% opacity</td></tr>
</table>
</div>
</div>
</td>
</tr>
</table>
<table>
<tr>
<td style="border:0">
<h4 id="selectedtabpalette1">Color palette</h4>
<table>
<tr>
<td class="image-caption-i"><img src="{@docRoot}images/icon_design/menu_palette_gradient_medium.png"/></td>
<td class="image-caption-c">Fill gradient<br><em>1:&nbsp;&nbsp;</em>r 163 | g 163 | b 163<br><em>2:&nbsp;&nbsp;</em>r 120 | g 120 | b 120<br>Used as color fill on unselected tab icons.</td>
</tr>
</table>
</td>
<td style="border:0">
<h4 id="selectedtabsteps1">Step by step</h4>
<ol>
<li>Create the basic shape using a tool like Adobe Illustrator.</li>
<li>Import the shape into a tool like Adobe Photoshop and scale to fit a 32x32
px artboard with a transparent background. </li>
<li>Add the effects seen in Figure 6 for the selected state filter.</li>
<li>Export the icon at 32x32 as a PNG file with transparency enabled.</li>
</ol>
</td>
</tr>
</table>

57
base/docs/html/guide/practices/ui_guidelines/index.jd Normal file
View File

@ -0,0 +1,57 @@
page.title=User Interface Guidelines
@jd:body
<img src="{@docRoot}assets/images/uiguidelines1.png" alt="" align="right">
<p>The Android UI team has begun developing guidelines for the interaction and
visual design of Android applications. Look here for articles that describe
these guidelines as we release them.</p>
<dl>
<dt><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon
Design Guidelines</a> and <a
href="{@docRoot}shareables/icon_templates-v2.3.zip">Android Icon Templates Pack
&raquo; </a></dt>
<dd>Your applications need a wide variety of icons, from a launcher icon to
icons in menus, dialogs, tabs, the status bar, and lists. The Icon Guidelines
describe each kind of icon in detail, with specifications for the size, color,
shading, and other details for making all your icons fit in the Android system.
The Icon Templates Pack is an archive of Photoshop and Illustrator templates and
filters that make it much simpler to create conforming icons.</dd>
</dl>
<dl>
<dt><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">Widget Design Guidelines</a> </dt>
<dd>A widget displays an application's most important or timely information
at a glance, on a user's Home screen. These design guidelines describe how to
design widgets that fit with others on the Home screen. They include links to
graphics files and templates that will make your designer's life easier.</dd>
</dl>
<dl>
<dt><a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html">Activity and Task Design Guidelines</a> </dt>
<dd>Activities are the basic, independent building blocks of applications.
As you design your application's UI and feature set, you are free to
re-use activities from other applications as if they were yours,
to enrich and extend your application. These guidelines
describe how activities work, illustrates them with examples, and
describes important underlying principles and mechanisms, such as
multitasking, activity reuse, intents, the activity stack, and
tasks. It covers this all from a high-level design perspective.
</dd>
<dt><a href="{@docRoot}guide/practices/ui_guidelines/menu_design.html">Menu Design Guidelines</a> </dt>
<dd>Android applications make use of Option menus and Context menus
that enable users to perform operations and navigate to other parts
of your application or to other applications. These guidelines describe
the difference between Options and Context menus, how to arrange
menu items, when to put commands on-screen, and other details about
menu design.
</dd>
</dl>

507
base/docs/html/guide/practices/ui_guidelines/menu_design.jd Normal file
View File

@ -0,0 +1,507 @@
page.title=Menu Design Guidelines
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>An Options menu is for any commands that are global to the current activity. </li>
<li>A Context menu is for any commands that apply to the current selection. </li>
<li>Place the most frequently used operations first. </li>
<li>Put only the most important commands fixed on the screen. </li>
<li>The commands on the Context menu that appears when you touch &amp; hold on an item should be duplicated on the activity you get to by a normal press on that item.
</ul>
<h2>In this document</h2>
<ol>
<li><a href=#tour_of_the_menus>Tour of the Menus</a>
<ol>
<li style="padding-top: 4px;"><a href=#options_menu>Options Menu</a></li>
<li style="padding-top: 4px;"><a href=#context_menu>Context Menu</a></li>
<li style="padding-top: 4px;"><a href=#comparison_of_options_and_context_menus>Comparison of Options &amp; Context Menus</a></li>
<li style="padding-top: 4px;"><a href=#commands_fixed>Commands Fixed in an Activity Screen</a></li>
</ol>
</li>
<li><a href=#guidelines>Guidelines</a>
<ol>
<li style="padding-top: 4px;"><a href=#separate_commands>Separate specific from global commands</a></li>
<li style="padding-top: 4px;"><a href=#most_frequently_used>Place most frequently used first</a></li>
<li style="padding-top: 4px;"><a href=#dont_put_commands>Don't put commands <em>only</em> in a Context menu</li>
<li style="padding-top: 4px;"><a href=#first_in_context_menu>First command in Context menu should be most intuitive</li>
<li style="padding-top: 4px;"><a href=#selecting_content_item>Selecting an item should perform most intuitive operation</a></li>
<li style="padding-top: 4px;"><a href=#context_menu_should_identify>A Context menu should identify the selected item</li>
<li style="padding-top: 4px;"><a href=#most_important_commands>Put only most important commands fixed on the screen</a></li>
<li style="padding-top: 4px;"><a href=#short_names>Use short names in Options icon menu</a></li>
<li style="padding-top: 4px;"><a href=#a_dialog_should_not_have_an_options_menu>A dialog should not have Options menu</a></li>
<li style="padding-top: 4px;"><a href=#do_not_substitute_message>If no Options menu, don't display message</a></li>
<li style="padding-top: 4px;"><a href=#dim_hide_menu_items>Dim or hide menu items not available</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="http://android-developers.blogspot.com/2008/12/touch-mode.html">Touch mode</a></li>
<li><a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html">Activity and Task Design</a></li>
</ol>
</div>
</div>
<p>
A menu holds a set of commands (user actions) that are normally hidden, and
are accessible by a button, key, or gesture. Menu commands provide a means
for performing operations and for navigating to other parts of your
application or other applications. Menus are useful for freeing screen space,
as an alternative to placing functionality and navigation, in buttons or other
user controls in the content area of your application.
</p>
<p>
The Android system provides two types of menus you can use to provide
functionality or navigation. Between them, you should be able to organize
the functionality and navigation for your application. Briefly:
<ul>
<li>The <em>Options menu</em> contains primary functionality that applies
globally to the current activity or starts a related activity.
It is typically invoked by a user pressing a hard button, often labeled MENU.</li>
<li>The <em>Context menu</em> contains secondary functionality for the currently
selected item. It is typically invoked by a user's touch &amp; hold
on an item. Like on the Options menu, the operation can run either
in the current or another activity.</li>
</ul>
</p>
<p>
All but the simplest applications have menus. The system automatically
lays the menus out and provides standard ways for users to access them.
In this sense, they are familiar and dependable ways for users to access
functionality across all applications. All menus are panels that "float"
on top of the activity screen and are smaller than full screen, so that the
application is still visible around its edges. This is a visual reminder
that a menu is an intermediary operation that disappears once it's used.
</p>
<p>
Let's start out with a quick tour of the menus.
</p>
<h2 id="tour_of_the_menus">Tour of the Menus</h2>
<p class="note"><strong>Note:</strong> Your menus and screens might not look
like those shown in this document; they may vary from one version of Android
or device to another.
</p>
<h3 id="options_menu">Options Menu</h3>
<p>
The Options menu contains commands that apply globally across the current
activity, or can start another activity. They do not apply to a selected
item in the content (a <a href="#context_menu">Context menu</a> does that).
</p>
<p>
On most devices, a user presses the MENU button to access the Options menu,
as shown in the screenshot below. To close the menu, the user presses
MENU again, or presses the BACK button.
In fact, to cancel out of any menu, press the BACK button. (Pressing the MENU
button or touching outside the menu also works.) Note that how to invoke this
menu may be different on different devices.
</p>
<p>
Each
<a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html#activities">activity</a>
activity has its own set of operations and therefore its own Options menu.
An application with multiple activities would have a different Options menu
for each activity.
</p>
<p>
For example, in the message list view of an email program, the Options menu
might let you search the messages, compose a new message, refresh the list,
or change the email settings. The compose view of an email program would
have a different Options menu, such as adding a CC field, attaching a file,
or discarding the message.
</p>
<p id="options_icon_expanded_menus">
In order to handle a large number of menu items, the Options menu
progressively discloses them in two steps:
</p>
<ul>
<li>
<b>Options icon menu</b> - The first press of the MENU button displays a
non-scrollable grid of icons at the bottom of the screen. (On the G1
phone, up to 6 buttons typically appear.)
</li>
<li>
<b>Options expanded menu</b> - If the activity has more menu items than will
fit on the icon menu, then the last icon is labeled "More" &mdash; selecting it
displays a list that can contain any number of menu items and will scroll
as necessary.
</li>
</ul>
<img src={@docRoot}images/menu_design/MenuDiagram.png>
<p>
On some versions of Android, the user can display keyboard shortcuts in the
icon menu by long pressing the MENU button &mdash; the text in the icon menu
alternates between the command names and their keyboard shortcuts (if any).
</p>
<h3 id="context_menu">Context Menu</h3>
<p>
A Context menu is similar to a right-click context menu in a desktop
operating system. It is normally a shortcut that duplicates commands
found elsewhere.
</p>
<p>
A user can touch &amp; hold on content on the screen to
access a Context menu (if one exists), as shown in the screenshot below.
A Context menu is a list of menu items (commands) that can operate
on the selected content. The command can either be part of the current
activity, or the system can pass the selected content along to
an operation in another activity (by way of an
<a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html#intents">intent</a>).
</p>
<p>
For example, in an email message list, a user can touch &amp; hold on
an email message to open a Context menu containing commands to read,
archive, or delete the message.
</p>
<p id="location">
A user can also touch &amp; hold a <em>location</em> on the screen to
access a Context menu. An example is when the user does touch &amp; hold
on a blank spot on the Home screen, a Context menu appears; selecting
an item from that menu inserts an icon at that location.
</p>
<img src={@docRoot}images/menu_design/ContextMenuDiagram.png>
<h4 id="context_menu_shortcut">Context Menu is a Shortcut</h4>
<p>
In the above example, if the user performs touch &amp; hold on the contact
"Obi Wan Kenobi", a Context menu opens. The commands provided in
this Context menu are the complete set of actions that can be performed
on this contact.
</p>
<p>
A normal touch on an item in the content activates the most intuitive
command for that selection &mdash; in this case, "View contact".
We recommend that the most intuitive command also be listed as the
first item in the Context menu. In this example, selecting the contact
"Obi Wan Kenobi" runs the same command "View contact" that is listed
at the top of the Context menu.
</p>
<p>
Also note, as shown in the following screenshot, the Context menu and the
next screen both hold the same complete set of commands that can be performed
on this contact. The Context menu displays the commands in a list,
while the "View contact" activity splits them into various items in the
Options menu, icon buttons and list items.
</p>
<p>
Because of this duplication, using the Context menu is considered a <em>shortcut</em>
for going to the next screen and performing the operation there. Context menus
are less discoverable than either buttons fixed on-screen or the Options menu.
Many users never discover or use Context menus. It is for this reason that, for
the most part, any command on a Context menu should also appear on the most
intuitive operation's screen. As the next section explains, text operations,
such as "Select text" might appear only on a Context menu. Also, rich
applications, such as browsers, which themselves can contain web applications,
may have commands on Context menus that are not available elsewhere.
</p>
<img src={@docRoot}images/menu_design/ContextMenuViewContactDiagram.png>
<h4>Text Commands in Context Menu</h4>
<p>
Text links and text fields in the content both have system-provided operations
that are common across all applications: operations such as "Select all", "Select text",
"Copy all", and "Add to dictionary". If the text field is editable, it also
has other operations, such as "Cut all" and "Input Method", and if text
is also on the clipboard, it has "Paste". The system automatically inserts
the appropriate menu items into the Context menu of text links and text
fields, as shown in the following screenshot.
</p>
<img src={@docRoot}images/menu_design/TextFieldContextMenuDiagram.png>
<h3 id="comparison_of_options_and_context_menus">Comparison of Options and Context Menus</h3>
<p>
An Options menu holds commands that are global to the activity while a
Context menu holds commands that apply only to an item in the content.
As shown in these diagrams, the user navigates to the menu, then
touches a menu item to perform an action or open a dialog.
</p>
<img src={@docRoot}images/menu_design/TaskFlowDiagram.png>
<p>
For more technical information on menus, see
<a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.
</p>
<h3 id="commands_fixed">Commands Fixed in an Activity Screen</h4>
<p>
Commands can also be fixed directly on screen, typically in
text buttons, graphic buttons, or list items. This placement is by far the most
discoverable location for commands &mdash; a user can immediately see the command
without having to first press a button. This increased visibility needs to be
weighed against the space such user controls take up, or the sense that they
might clutter the visual design.
</p>
<h2 id="guidelines">Guidelines</h2>
<p>
Selecting the right kind of menu to present, and using menus
consistently, are critical factors in good application design. The following
guidelines should assist user experience designers and application developers
toward this end.
</p>
<h3 id="separate_commands">Separate selection-specific commands from global commands</h3>
<p>
Put any commands that are global to the current activity in the Options menu
or place them fixed in an activity screen; put commands that apply to the
current selection in the Context menu. (In any case, the command
could either run as part of this activity or start another activity.)
</p>
<p>
You can determine in which menu to place a command by what it operates on:
If the command acts on selected content (or a particular
<a href="#location">location</a>) on the screen, put the command in the
Context menu for that content. If the command acts on no specific content
or location, put it in the Options menu. This separation of commands
is enforced by the system in the following way. When you press the MENU
button to display the Options menu, the selected content becomes unselected,
and so cannot be operated on. For an explanation
of why the content becomes unselected, see the article on
<a href="http://android-developers.blogspot.com/2008/12/touch-mode.html">Touch mode</a>.
</p>
<p>
An example of a selection-specific Context menu is when a user performs a
touch &amp; hold on a person's name in a list view of a contacts application.
The Context menu would typically contain commands "View contact", "Call contact",
and "Edit contact".
</p>
<h3 id="most_frequently_used">Place the most frequently used operations first</h3>
<p>
Because of limited screen height, some menus may be scrollable, so it's
important to place the most important commands so they can be viewed without
scrolling. In the case of the Options menu, place the most frequently used
operation on its <a href="#options_icon_expanded_menus">icon menu</a>;
the user will have to select "More" to see the rest.
It's also useful to place similar commands in the same location &mdash;
for example, the Search icon might always be the first icon in the Options
menu across several activities that offer search.
</p>
<p>
In a Context menu, the most intuitive command should be first, followed
by commands in order of decreasing use, with the least used command at the bottom.
</p>
<h3 id="dont_put_commands">Don't put commands <em>only</em> in a Context menu</h3>
<p>
If a user can fully access your application without using Context menus,
then it's designed properly! In general, if part of your application is inaccessible
without using Context menus, then you need to duplicate those commands elsewhere.
</p>
<p>
Before opening a Context menu, it has no visual representation that identifies
its presence (whereas the Options menu has the MENU button), and so is not
particularly discoverable.
Therefore, in general, a Context menu should <em>duplicate</em> commands
found in the corresponding activity screen. For example, while it's useful to
let the user call a phone number from a Context menu invoked by touch
&amp; hold on a name in a list of contacts, that operation should <em>also</em>
be available by the user touching the phone number itself when viewing contact details.
See <a href="#context_menu_shortcut">shortcut</a> for an illustration of this example.
</p>
<h3 id="first_in_context_menu">The first command in a Context menu should be the selection's most intuitive command</h3>
<p>
As described under <a href="#context_menu_shortcut">shortcut</a>,
touching on an item in the content should activate the same command as touching
the first item in the Context menu. Both cases should be the most intuitive
operation for that item.
</p>
<h3 id="selecting_content_item">Selecting an item in the content should perform the most intuitive operation</h3>
<p>
In your application, when the user touches any actionable text (such as a link
or list item) or image (such as a photo icon), execute the operation most
likely to be desired by the user.
</p>
<p>
Some examples of primary operations:
</p>
<ul>
<li>Selecting an image executes "View image"</li>
<li>Selecting a media icon or filename executes "Play"</li>
<li>Selecting a URL link executes "Open link"</li>
<li>Selecting an address executes "Go to address" (in a maps application)</li>
</ul>
<p>
Note that selecting the same item in different contexts might invoke
different operations:
</p>
<ul>
<li>In a contact application, selecting a contact executes "View details"</li>
<li>In an IM application, selecting a contact executes "Start chat"</li>
<li>In an Email application, when adding a recipient to the "To" field
through the contact book, selecting a contact executes "Add to recipient
list"</li>
</ul>
<h3 id="context_menu_should_identify">A Context menu should identify the selected item</h3>
<p>
When a user does touch &amp; hold on an item, the Context menu should
contain the name of the selected item. Therefore,
when creating a Context menu, be sure to include a title and the name of the
selected item so that it's clear to the user what the context is.
For example, if a user selects a contact "Joan of Arc", put that name in the
title of the Context menu (using
{@link android.view.ContextMenu#setHeaderTitle(java.lang.CharSequence) setHeaderTitle}).
Likewise, a command to edit the contact should be called "Edit contact",
not just "Edit".
</p>
<h3 id="most_important_commands">Put only the most important commands fixed on the screen</h3>
<p>
By putting commands in menus, you free up the screen to hold more content.
On the other hand, fixing commands in the content area of an activity
makes them more prominent and easy to use.
</p>
<p>
Here are a number of important reasons to place commands fixed on the activity screen:
</p>
<ul>
<li>
To give a command the highest prominence, ensuring the command is obvious and won't be overlooked.<br>
Example: A "Buy" button in a store application.
</li>
<li>
When quick access to the command is important and going to the menu would be
tedious or slow.<br>
Example: Next/Previous buttons or Zoom In/Out buttons in an image viewing application.
</li>
<li>
When in the middle of an operation that needs to be completed.<br>
Example: Save/Discard buttons in an image crop activity.
</li>
<li>
Dialogs and wizards.<br>
Example: OK/Cancel buttons
</li>
<li>
For direct manipulation.<br>
Example: Dragging an icon in the Home screen to the trash
</li>
</ul>
<h3 id="short_names">Use short names in the Options icon menu</h3>
<p>
If a text label in the <a href="#options_icon_expanded_menus">Options icon menu</a>
is too long, the system truncates it in the middle. Thus, "Create Notification"
is truncated to something like "Create…ication". You have no control over
this truncation, so the best bet is to keep the text short. In some versions of Android,
when the icon is highlighted by a navigation key (such as a trackball), the
entire descriptive text may be shown as a marquee, where the words are
readable as they scroll by. <!--For more information, see the Text Guidelines
[update link].-->
</p>
<h3 id="a_dialog_should_not_have_an_options_menu">A dialog should not have an Options menu</h3>
<p>
When a dialog is displayed, pressing the MENU button should do nothing. This also holds true
for activities that look like dialogs. A dialog box is recognizable by being
smaller than full-screen, having zero to three buttons, is non-scrollable, and
possibly a list of selectable items that can include checkboxes or radio buttons.
<!--For examples of dialogs, see Text Guidelines.-->
</p>
<p>
The rationale behind not having a menu is that when a dialog is displayed, the user is in
the middle of a procedure and should not be allowed to start a new global task
(which is what the Option menu provides).
</p>
<h3 id="do_not_substitute_message">If an activity has no Options menu, do not display a message</h3>
<p>
When the user presses the MENU button, if there is no Options menu, the system
currently does nothing. We recommend you do not perform any action (such as
displaying a message). It's a better user experience for this behavior to be
consistent across applications.
</p>
<h3 id="dim_hide_menu_items">Dim or hide menu items that are not available in the current context</h3>
<p>
Sometimes a menu item's action cannot be performed &mdash; for example,
the "Forward" button in a browser cannot work until after the "Back"
button has been pressed. We recommend:
</p>
<ul>
<li>
<b>In Options menu</b> - disable the menu item, which dims the text and icon,
turning it gray. This applies to menu items in both the icon menu and the
"More" menu. It would be disorienting for the icon menu to change from 6
items to 5 items, and we treat the "More" menu the same way.
</li>
<li>
<b>In Context menu</b> - hide the menu item. This makes the menu shorter so the
user sees only available choices (which also reduces any scrolling).
</li>
</ul>
</body>
</html>

274
base/docs/html/guide/practices/ui_guidelines/widget_design.jd Normal file
View File

@ -0,0 +1,274 @@
page.title=Widget Design Guidelines
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Widgets have six standard sizes on the Home screen</li>
<li>Widgets have standards for size, frames, shadows, and file format, which you can copy</li>
<li>A few tricks make it easier to design widgets that fit graphically on the Home screen</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#anatomy">Standard widget anatomy</a></li>
<li><a href="#design">Designing a widget</a></li>
<li><a href="#sizes">Standard widget sizes</a></li>
<li><a href="#frames">Standard widget frames</a></li>
<li><a href="#shadows">Standard widget shadows</a></li>
<li><a href="#tricks">Widget graphics tips and tricks</a></li>
<li><a href="#file">Widget graphics file format</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a></li>
<li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">AppWidgets blog post</a></li>
</ol>
</div>
</div>
<p>Widgets are a feature introduced in Android 1.5. A widget displays an
application's most important or timely information at a glance, on a user's Home
screen. The standard Android system image includes several examples of widgets,
including widgets for Analog Clock, Music, and other applications.</p>
<p>Users pick the widgets they want to display on their Home screens by touching
&amp; holding an empty area of the Home screen, selecting Widgets from the menu,
and then selecting the widget they want.</p>
<p><img src="{@docRoot}images/widget_design/widget_examples.png" alt="Example
Widgets"></p>
<p>This document describes how to design a widget so it fits graphically with
other widgets and with the other elements of the Android Home screen. It also
describes some standards for widget artwork and some widget graphics tips and
tricks from the Android team.<p>
<p>For information about developing widgets, see the <a
href="{@docRoot}guide/topics/appwidgets/index.html">AppWidgets</a> section of
the <em>Developer's Guide</em> and the <a
href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">AppWidgets</a> blog post.</p>
<h2 id="anatomy">Standard widget anatomy</h2>
<p>Typical Android widgets have three main components: A bounding box, a frame,
and the widget's graphical controls and other elements. Well-designed widgets
leave some padding between the edges of the bounding box and the frame, and
between the inner edges of the frame and the widget's controls. Widgets designed
to fit visually with other widgets on the Home screen take cues from the other
elements on the Home screen for alignment; they also use standard shading
effects. All of these details are described in this document.
<p><strong>Standard Widget Sizes in Portrait Orientation</strong><br/>
<img src="{@docRoot}images/widget_design/widget_sizes_portrait.png"
alt="Standard Widget Sizes in Portrait Orientation"></p>
<p>&nbsp;</p>
<p><strong>Standard Widget Sizes in Landscape Orientation</strong><br/>
<img src="{@docRoot}images/widget_design/widget_sizes_landscape.png"
alt="Standard Widget Sizes in Landscape Orientation"></p>
<h2 id="design">Designing a widget</h2>
<ol>
<li><strong>Select a bounding box size for your widget.</strong></li>
<p>The most effective widgets display your application's most useful or timely
data in the smallest widget size. Users will weigh the usefulness or your widget
against the portion of the Home screen it covers, so the smaller the better.</p>
<p>All widgets must fit within the bounding box of one of the six supported
widget sizes, or better yet, within a pair of portrait and landscape orientation
sizes, so your widget looks good when the user switches screen
orientations.</p>
<p><a href="#sizes">Standard widget sizes</a> illustrates the bounding
dimensions of the six widget sizes (three in portrait and three in landscape
orientation).</p>
<li><strong>Select a matching frame.</strong></li>
<p><a href="#frames">Standard widget frames</a> illustrates the standard frames
for the six widget sizes, with links so you can download copies for your own
use. You don't have to use these frames for your widget, but if you do, your
widgets are more likely to fit visually with other widgets.</p>
<li><strong>Apply standard shadow effect to your graphics.</strong></li>
<p>Again, you don't have to use this effect, but <a href="#shadows">Standard
widget shadows</a> shows the Photoshop settings used for standard widgets.</p>
<li><strong>If your widget includes buttons, draw them in three states
(default, pressed, and selected).</strong></li>
<p>You can <a
href="{@docRoot}images/widget_design/Music_widget_button_states.psd">download a
Photoshop file that contains the three states of the Play button</a>, taken from
the Music widget, to analyze the Photoshop settings used for the three standard
button effects.</p>
<p><a href="{@docRoot}images/widget_design/Music_widget_button_states.psd"> <img
src="{@docRoot}images/widget_design/buttons.png" alt="Click to download
Photoshop template"></a></p>
<li><strong>Finish drawing your artwork and then scale and align it to
fit.</strong></li>
<p><a href="#tricks">Widget alignment tips and tricks</a> describes some
techniques for aligning your widget's graphics inside the standard frames, along
with a few other widget graphics tricks.</p>
<li><strong>Save your widget with the correct graphics file
settings.</strong></li>
<p><a href="#file">Windows graphics file format</a> describes the correct
settings for your widget graphics files.</p>
</ol>
<h2 id="sizes">Standard widget sizes</h2>
<p>There are six standard widget sizes, based on a Home screen grid of 4 x 4
(portrait) or 4 x 4 (landscape) cells. These dimensions are the bounding boxes
for the six standard widget sizes. The contents of typical widgets don't draw to
the edge of these dimensions, but fit inside a frame withing the bounding box,
as described in <a href="#design">Designing a widget</a>.</p>
<p>In portrait orientation, each cell is 80 pixels wide by 100 pixels tall (the
diagram shows a cell in portrait orientation). The three supported widget sizes
in portrait orientation are:<p>
<table>
<tr><th>Cells</th><th>Pixels</th></tr>
<tr><td>4 x 1</td><td>320 x 100</td></tr>
<tr><td>3 x 3</td><td>240 x 300</td></tr>
<tr><td>2 x 2</td><td>160 x 200</td></tr>
</table>
<p><img src="{@docRoot}images/widget_design/portrait_sizes.png" alt="Widget
dimensions in portrait orientation"></p>
<p>In landscape orientation, each cell is 106 pixels wide by 74 pixels tall. The
three supported widget sizes in landscape orientation are:</p>
<table>
<tr><th>Cells</th><th>Pixels</th></tr>
<tr><td>4 x 1</td><td>424 x 74</td></tr>
<tr><td>3 x 3</td><td>318 x 222</td></tr>
<tr><td>2 x 2</td><td>212 x 148</td></tr>
</table>
<p><img src="{@docRoot}images/widget_design/landscape_sizes.png" alt="Widget
dimensions in landscape orientation"></p>
<h2 id="frames">Standard widget frames</h2>
<p>For each of the six standard widget sizes there is a standard frame. You can
click the images of the frames in this section to download a Photoshop file for
that frame, which you can use for your own widgets.<p>
<p><a href="{@docRoot}images/widget_design/4x1_Widget_Frame_Portrait.psd"> <img
src="{@docRoot}images/widget_design/4x1_Widget_Frame_Portrait.png" alt="Click to
download"></a><br>4x1_Widget_Frame_Portrait.psd</p>
<p><a href="{@docRoot}images/widget_design/3x3_Widget_Frame_Portrait.psd"> <img
src="{@docRoot}images/widget_design/3x3_Widget_Frame_Portrait.png" alt="Click to
download"></a><br>3x3_Widget_Frame_Portrait.psd</p>
<p><a href="{@docRoot}images/widget_design/2x2_Widget_Frame_Portrait.psd"> <img
src="{@docRoot}images/widget_design/2x2_Widget_Frame_Portrait.png" alt="Click to
download"></a><br>2x2_Widget_Frame_Portrait.psd</p>
<p><a href="{@docRoot}images/widget_design/4x1_Widget_Frame_Landscape.psd"> <img
src="{@docRoot}images/widget_design/4x1_Widget_Frame_Landscape.png" alt="Click
to download"></a><br>4x1_Widget_Frame_Landscape.psd</p>
<p><a href="{@docRoot}images/widget_design/3x3_Widget_Frame_Landscape.psd"> <img
src="{@docRoot}images/widget_design/3x3_Widget_Frame_Landscape.png" alt="Click
to download"></a><br>3x3_Widget_Frame_Landscape.psd</p>
<p><a href="{@docRoot}images/widget_design/2x2_Widget_Frame_Landscape.psd"> <img
src="{@docRoot}images/widget_design/2x2_Widget_Frame_Landscape.png" alt="Click
to download"></a><br>2x2_Widget_Frame_Landscape.psd</p>
<h2 id="shadows">Standard widget shadows</h2>
<p>You can apply a shadow effect to your widget's artwork, so it matches other
standard Android widgets, using the following settings in the Photoshop Layer
Style dialog box.</p>
<p><img src="{@docRoot}images/widget_design/Layer_Style.png" alt="Layer Style
settings for standard shadows"></p>
<h2 id="tricks">Widget graphics tips and tricks</h2>
<p>The Android team has developed a few tricks for aligning widget artwork
within standard widget bounding boxes and frames, so the widget aligns visually
with other widgets and the other elements of the Home screen, as well as other
techniques for creating widgets.
<ul>
<li>Use a screen shot from the Android SDK emulator to align both the shapes and
shadows of your widget controls with the Search widget and with other elements
on the Home screen.</li>
<p>Cut the widget artwork asset" based on the full size of a cell, including any
padding you want. (That is, for a 4 x 1 widget, cut the asset at 320 by 100
pixels.)</p>
<p><img src="{@docRoot}images/widget_design/alignment.png" alt="Aligning widget
graphics" ></p>
<li>To reduce banding when exporting a widget, apply the following Photoshop Add
Noise setting to your graphic.</li>
<p><img src="{@docRoot}images/widget_design/Add_Noise.png" alt="Add Noise
settings for widget graphics" ></p>
<li>Apply 9-patch techniques to shrink the graphic and set the padding of the
content area. (<a href="{@docRoot}guide/developing/tools/draw9patch.html">See
the detailed guide here.</a>)</li>
<p><strong>Note:</strong> The current Android widget templates were designed
using a custom gradient angle, which means the 9-patch techniques can't be used
to optimize the size of the asset. However, 9-patch techniques were used to set
the content area padding.</p>
<li>In some cases, devices have low pixel depths that can cause visual banding
and dithering issues. To solve this, application developers should pass assets
through a "proxy" drawable defined as <code>XML:<nine-patch
android:src="@drawable/background" android:dither="true" /></code>. This
technique references the original artwork, in this case
<code>"background.9.png"</code>, and instructs the device to dither it as
needed.</li>
</ul>
<h2 id="file">Widget graphics file format</h2>
<p>Save your widget artwork using the appropriate bounding box size in PNG-24
format on a transparent background and in 8-bit color.</p>
<p><img src="{@docRoot}images/widget_design/file_format.png" alt="Widget graphics file format" ></p>