diff options
Diffstat (limited to 'en/devices')
57 files changed, 489 insertions, 35 deletions
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-interfaces.yaml index 83f54d8e..7fb6b5c2 100644 --- a/en/devices/_toc-interfaces.yaml +++ b/en/devices/_toc-interfaces.yaml @@ -164,21 +164,21 @@ toc: - title: Latency section: - title: Overview - path: /devices/audio/latency + path: /devices/audio/latency/latency - title: Contributors - path: /devices/audio/latency_contrib + path: /devices/audio/latency/contrib - title: Design - path: /devices/audio/latency_design + path: /devices/audio/latency/design - title: Measure - path: /devices/audio/latency_measure + path: /devices/audio/latency/measure - title: Light Testing Circuit - path: /devices/audio/testing_circuit + path: /devices/audio/latency/testing_circuit - title: Audio Loopback Dongle - path: /devices/audio/loopback + path: /devices/audio/latency/loopback - title: Measurements - path: /devices/audio/latency_measurements + path: /devices/audio/latency/measurements - title: Applications - path: /devices/audio/latency_app + path: /devices/audio/latency/app - title: Priority Inversion path: /devices/audio/avoiding_pi - title: Sample Rate Conversion diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml index c30d4570..632c6778 100644 --- a/en/devices/_toc-tech.yaml +++ b/en/devices/_toc-tech.yaml @@ -243,6 +243,8 @@ toc: path: /devices/tech/settings/personalized - title: Universal Search path: /devices/tech/settings/universal-search + - title: Design Guidelines + path: /devices/tech/settings/settings-guidelines - title: Testing Infrastructure section: - title: Overview @@ -260,4 +262,4 @@ toc: - title: An End-to-End Example path: /devices/tech/test_infra/tradefed/full_example - title: Package Index - path: /reference/tradefed/
\ No newline at end of file + path: /reference/tradefed/ diff --git a/en/devices/architecture/hidl-java/index.html b/en/devices/architecture/hidl-java/index.html index c4218160..45eefc7d 100644 --- a/en/devices/architecture/hidl-java/index.html +++ b/en/devices/architecture/hidl-java/index.html @@ -68,8 +68,9 @@ The static version of the library is also available as <pre class="prettyprint"> import android.hardware.foo.V1_0.IFoo; ... -IFoo server = IFoo.getService(); // throws exception if not available -IFoo anotherServer = IFoo.getService("second_impl"); +// retry to wait until the service starts up if it is in the manifest +IFoo server = IFoo.getService(true /* retry */); // throws NoSuchElementException if not available +IFoo anotherServer = IFoo.getService("second_impl", true /* retry */); server.doSomething(…); </pre> </li> @@ -82,6 +83,9 @@ callbacks from HALs.</p> <p class=warning><strong>Warning</strong>: Do not implement a driver (HAL) in Java. We strongly recommend you implement drivers in C++.</p> +<p class=warning><strong>Warning</strong>: Java drivers must be in a separate +process from their clients (same process communication is not supported).</p> + <p>For interface <code>IFooCallback</code> in version 1.0 of package <code>android.hardware.foo</code>, you can implement your interface in Java using the following steps:</p> @@ -142,7 +146,7 @@ class FooCallback extends IFooCallback.Stub { .... // Get the service you will be receiving callbacks from. // This also starts the threadpool for your callback service. -IFoo server = IFoo.getService(); // throws exception if not available +IFoo server = IFoo.getService(true /* retry */); // throws NoSuchElementException if not available .... // This must be a persistent instance variable, not local, // to avoid premature garbage collection. @@ -173,7 +177,7 @@ interface IBetterFoo extends IFoo { extended interface:</p> <pre class="prettyprint"> -IFoo baseService = Foo.getService(); +IFoo baseService = IFoo.getService(true /* retry */); // throws NoSuchElementException if not available IBetterFoo extendedService = IBetterFoo.castFrom(baseService); if (extendedService != null) { // The service implements the extended interface. diff --git a/en/devices/architecture/hidl/services.html b/en/devices/architecture/hidl/services.html index 805bc800..1d2deccb 100644 --- a/en/devices/architecture/hidl/services.html +++ b/en/devices/architecture/hidl/services.html @@ -53,10 +53,10 @@ version, calling <code>getService</code> on the desired HAL class:</p> <pre class="prettyprint"> // C++ sp<V1_1::IFooService> service = V1_1::IFooService::getService(); -sp<V1_1::IFooService> alternateService = 1_1::IFooService::getService("another_foo_service"); +sp<V1_1::IFooService> alternateService = V1_1::IFooService::getService("another_foo_service"); // Java V1_1.IFooService; service = V1_1.IFooService.getService(true /* retry */); -V1_1.IFooService; alternateService = 1_1.IFooService.getService("another", true /* retry */); +V1_1.IFooService; alternateService = V1_1.IFooService.getService("another", true /* retry */); </pre> <p>Each version of a HIDL interface is treated as a separate interface. Thus, diff --git a/en/devices/architecture/hidl/threading.html b/en/devices/architecture/hidl/threading.html index 5b8fa038..26c2cc12 100644 --- a/en/devices/architecture/hidl/threading.html +++ b/en/devices/architecture/hidl/threading.html @@ -48,11 +48,11 @@ available, it blocks until one is available.</p> <p>If the server has only one thread, then calls into the server are completed in order. A server with more than one thread may complete calls out of order -even if the client has only one thread. As <code>oneway</code> calls do not -block the client, multiple <code>oneway</code> calls may be processed -simultaneously or out of order by a server with more than one thread, and -<code>oneway</code> calls may be processed concurrently with a subsequent -blocking call.</p> +even if the client has only one thread. However, for a given interface object, +<code>oneway</code> calls are guaranteed to be ordered (see +<a href="#model">Server threading model</a>). For a multi-threaded server that +hosts multiple interfaces, <code>oneway</code> calls to different interfaces +may be processed concurrently with each other or other blocking calls.</p> <p>Multiple nested calls will be sent on the same hwbinder thread. For instance, if a process (A) makes a synchronous call from a hwbinder thread into process (B), @@ -160,7 +160,19 @@ server returns a <code>Return<void></code> object.</p> <h3 id=oneway>Oneway calls</h3> <p>When a function is marked <code>oneway</code>, the client returns immediately -and does not wait for the server to complete its function call invocation.</p> +and does not wait for the server to complete its function call invocation. At the +surface (and in aggregate), this means the function call takes half the +time because it is executing half the code, but when writing implementations that +are performance sensitive, this has some scheduling implications. Normally, +using a oneway call causes the callee to continue to be scheduled whereas +using a normal synchronous call causes the scheduler to immediately transfer +from the callee to the caller process. This is a performance optimization in +binder. For services where the oneway call must be executed in the target process +with a high priority, the scheduling policy of the receiving service can be +changed. In C++, using <code>libhidltransport</code>'s method +<code>setMinSchedulerPolicy</code> with the scheduler priorities and policies +defined in <code>sched.h</code> ensures that all calls into the service run at +least at the set scheduling policy and priority.</p> </body> </html> diff --git a/en/devices/audio/latency_app.html b/en/devices/audio/latency/app.html index 61a1c56f..7fb1e7fd 100644 --- a/en/devices/audio/latency_app.html +++ b/en/devices/audio/latency/app.html @@ -131,7 +131,7 @@ This Venn diagram shows the relationship between Android native audio and OpenSL ES 1.0.1. </p> -<img src="images/venn.png" alt="Venn diagram" id="figure1" /> +<img src="/devices/audio/images/venn.png" alt="Venn diagram" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Venn diagram </p> diff --git a/en/devices/audio/latency_contrib.html b/en/devices/audio/latency/contrib.html index 62fce5c2..62fce5c2 100644 --- a/en/devices/audio/latency_contrib.html +++ b/en/devices/audio/latency/contrib.html diff --git a/en/devices/audio/latency_design.html b/en/devices/audio/latency/design.html index 59ab47e0..59ab47e0 100644 --- a/en/devices/audio/latency_design.html +++ b/en/devices/audio/latency/design.html diff --git a/en/devices/audio/latency.html b/en/devices/audio/latency/latency.html index 03dabb64..03dabb64 100644 --- a/en/devices/audio/latency.html +++ b/en/devices/audio/latency/latency.html diff --git a/en/devices/audio/loopback.html b/en/devices/audio/latency/loopback.html index 359f45a5..bef46c69 100644 --- a/en/devices/audio/loopback.html +++ b/en/devices/audio/latency/loopback.html @@ -37,7 +37,7 @@ via the Larsen effect (feedback loop). <h2 id="loopbackCircuit">Circuit</h2> -<img src="images/loopback_circuit.png" alt="circuit" id="figure1" /> +<img src="/devices/audio/images/loopback_circuit.png" alt="circuit" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> circuit diagram </p> @@ -51,7 +51,7 @@ the audio loopback dongle is a US/CTIA pinout Tip Ring Ring Shield (TRRS) plug. <h2 id="loopbackAssembled">Assembled</h2> -<img src="images/loopback_assembled.jpg" alt="fully assembled" id="figure2" /> +<img src="/devices/audio/images/loopback_assembled.jpg" alt="fully assembled" id="figure2" /> <p class="img-caption"> <strong>Figure 2.</strong> Assembled </p> diff --git a/en/devices/audio/latency_measure.html b/en/devices/audio/latency/measure.html index 691502e6..aa703140 100644 --- a/en/devices/audio/latency_measure.html +++ b/en/devices/audio/latency/measure.html @@ -144,7 +144,7 @@ located in the <code>audio_utils</code> library. should not be extrapolated. </p> -<img src="images/round_trip.png" alt="round-trip measurement" id="figure1" /> +<img src="/devices/audio/images/round_trip.png" alt="round-trip measurement" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Round-trip measurement </p> diff --git a/en/devices/audio/latency_measurements.html b/en/devices/audio/latency/measurements.html index 80a8bd54..b5372248 100644 --- a/en/devices/audio/latency_measurements.html +++ b/en/devices/audio/latency/measurements.html @@ -31,7 +31,7 @@ defined as the time it takes for an audio signal to enter the input of a mobile device, be processed by an app running on the application processor, and exit the output.</p> -<img src="images/round_trip_on_device.png" alt="Round-trip audio latency on +<img src="/devices/audio/images/round_trip_on_device.png" alt="Round-trip audio latency on device" id="figure1" /> <p class="img-caption"><strong>Figure 1.</strong> Round-trip audio latency on device: T<sub>output</sub> - T<sub>input</sub></p> @@ -72,7 +72,7 @@ algorithmic delay and near-zero computational delay.</p> <p>We measure round-trip latency via the headset connector for several reasons: </p> -<img src="images/round_trip_via_headset_connector.png" alt="Round-trip latency +<img src="/devices/audio/images/round_trip_via_headset_connector.png" alt="Round-trip latency via headset connector" id="figure2" /> <p class="img-caption"><strong>Figure 2.</strong> Round-trip latency via headset connector: T<sub>output</sub> - T<sub>input</sub></p> diff --git a/en/devices/audio/testing_circuit.html b/en/devices/audio/latency/testing_circuit.html index 118fc09a..9e34b2f0 100644 --- a/en/devices/audio/testing_circuit.html +++ b/en/devices/audio/latency/testing_circuit.html @@ -63,17 +63,17 @@ We supply it to encourage your continued attention to audio performance. These photos show the circuit in action. </p> -<img style="margin:1.5em auto" src="images/breadboard.jpg" alt="breadboard prototype" id="figure1" /> +<img style="margin:1.5em auto" src="/devices/audio/images/breadboard.jpg" alt="breadboard prototype" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Breadboard prototype </p> -<img style="margin:1.5em auto" src="images/pcb.jpg" alt="an early run of the PCB" id="figure2" /> +<img style="margin:1.5em auto" src="/devices/audio/images/pcb.jpg" alt="an early run of the PCB" id="figure2" /> <p class="img-caption"> <strong>Figure 2.</strong> An early run of the PCB </p> -<img style="margin:1.5em auto" src="images/display.jpg" alt="example display" id="figure3" /> +<img style="margin:1.5em auto" src="/devices/audio/images/display.jpg" alt="example display" id="figure3" /> <p class="img-caption"> <strong>Figure 3.</strong> Example display </p> diff --git a/en/devices/graphics/implement-vulkan.html b/en/devices/graphics/implement-vulkan.html index 509ce7fd..7b71c3d2 100644 --- a/en/devices/graphics/implement-vulkan.html +++ b/en/devices/graphics/implement-vulkan.html @@ -198,7 +198,7 @@ requested by the swapchain consumer when allocating buffers.</p> <p>An earlier version of this function is called by Android 7.x. In Android 8.0 it is deprecated but will still be called if -<code>vkGetSwapchainGrallocUsage2ANDROID</code> isn't provided by the driver: + <code>vkGetSwapchainGrallocUsage2ANDROID</code> isn't provided by the driver:</p> <pre class="devsite-click-to-copy"> VkResult VKAPI vkGetSwapchainGrallocUsageANDROID( @@ -207,7 +207,7 @@ VkResult VKAPI vkGetSwapchainGrallocUsageANDROID( VkImageUsageFlags imageUsage, int* grallocUsage ); -<pre> +</pre> <p>This earlier version does not support swapchain usage flags or extended gralloc usage flags.</p> diff --git a/en/devices/input/keyboard-devices.html b/en/devices/input/keyboard-devices.html index 34f3575b..19ec746a 100644 --- a/en/devices/input/keyboard-devices.html +++ b/en/devices/input/keyboard-devices.html @@ -3250,7 +3250,7 @@ than are indicated here.</p> <td>0x0c 0x0045</td> <td>Menu Right</td> <td>0x0181</td> -<td>KEY_RADIO</td> +<td>KEY_RIGHT</td> <td></td> <td></td> <td></td> diff --git a/en/devices/tech/debug/index.html b/en/devices/tech/debug/index.html index 90922b0b..7d995454 100644 --- a/en/devices/tech/debug/index.html +++ b/en/devices/tech/debug/index.html @@ -100,8 +100,8 @@ Tombstone written to: /data/tombstones/tombstone_06 unwind with line number information by pasting the stack into <code>development/scripts/stack</code>:</p> -<p class="key-point"><strong>Tip:</strong> For convenience, if you've run <code>lunch</code> -<code>stack</code> will be on your $PATH already so you don't need to give the +<p class="key-point"><strong>Tip:</strong> For convenience, if you've run <code>lunch</code>, +then <code>stack</code> will be on your $PATH already so you don't need to give the full path.</p> <pre class="devsite-terminal devsite-click-to-copy"> diff --git a/en/devices/tech/settings/images/settings-guidelines01.png b/en/devices/tech/settings/images/settings-guidelines01.png Binary files differnew file mode 100644 index 00000000..1f266486 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines01.png diff --git a/en/devices/tech/settings/images/settings-guidelines02.png b/en/devices/tech/settings/images/settings-guidelines02.png Binary files differnew file mode 100644 index 00000000..c8b4f38a --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines02.png diff --git a/en/devices/tech/settings/images/settings-guidelines03.png b/en/devices/tech/settings/images/settings-guidelines03.png Binary files differnew file mode 100644 index 00000000..eaa5c1dc --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines03.png diff --git a/en/devices/tech/settings/images/settings-guidelines04.png b/en/devices/tech/settings/images/settings-guidelines04.png Binary files differnew file mode 100644 index 00000000..5ca8d9f9 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines04.png diff --git a/en/devices/tech/settings/images/settings-guidelines05.png b/en/devices/tech/settings/images/settings-guidelines05.png Binary files differnew file mode 100644 index 00000000..1f266486 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines05.png diff --git a/en/devices/tech/settings/images/settings-guidelines06.png b/en/devices/tech/settings/images/settings-guidelines06.png Binary files differnew file mode 100644 index 00000000..ab48475a --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines06.png diff --git a/en/devices/tech/settings/images/settings-guidelines07.png b/en/devices/tech/settings/images/settings-guidelines07.png Binary files differnew file mode 100644 index 00000000..5bed7874 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines07.png diff --git a/en/devices/tech/settings/images/settings-guidelines08.png b/en/devices/tech/settings/images/settings-guidelines08.png Binary files differnew file mode 100644 index 00000000..62c549a5 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines08.png diff --git a/en/devices/tech/settings/images/settings-guidelines09.png b/en/devices/tech/settings/images/settings-guidelines09.png Binary files differnew file mode 100644 index 00000000..2a7e0eda --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines09.png diff --git a/en/devices/tech/settings/images/settings-guidelines10.png b/en/devices/tech/settings/images/settings-guidelines10.png Binary files differnew file mode 100644 index 00000000..ed1aefe5 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines10.png diff --git a/en/devices/tech/settings/images/settings-guidelines11.png b/en/devices/tech/settings/images/settings-guidelines11.png Binary files differnew file mode 100644 index 00000000..ab9838bf --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines11.png diff --git a/en/devices/tech/settings/images/settings-guidelines12.png b/en/devices/tech/settings/images/settings-guidelines12.png Binary files differnew file mode 100644 index 00000000..9ca7163e --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines12.png diff --git a/en/devices/tech/settings/images/settings-guidelines13.png b/en/devices/tech/settings/images/settings-guidelines13.png Binary files differnew file mode 100644 index 00000000..ba7a059c --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines13.png diff --git a/en/devices/tech/settings/images/settings-guidelines14.png b/en/devices/tech/settings/images/settings-guidelines14.png Binary files differnew file mode 100644 index 00000000..247c53d7 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines14.png diff --git a/en/devices/tech/settings/images/settings-guidelines15.png b/en/devices/tech/settings/images/settings-guidelines15.png Binary files differnew file mode 100644 index 00000000..cbdd2b93 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines15.png diff --git a/en/devices/tech/settings/images/settings-guidelines16.png b/en/devices/tech/settings/images/settings-guidelines16.png Binary files differnew file mode 100644 index 00000000..62c549a5 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines16.png diff --git a/en/devices/tech/settings/images/settings-guidelines17.png b/en/devices/tech/settings/images/settings-guidelines17.png Binary files differnew file mode 100644 index 00000000..5bed7874 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines17.png diff --git a/en/devices/tech/settings/images/settings-guidelines18.png b/en/devices/tech/settings/images/settings-guidelines18.png Binary files differnew file mode 100644 index 00000000..c0e06ed7 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines18.png diff --git a/en/devices/tech/settings/images/settings-guidelines19.png b/en/devices/tech/settings/images/settings-guidelines19.png Binary files differnew file mode 100644 index 00000000..53ccd593 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines19.png diff --git a/en/devices/tech/settings/images/settings-guidelines20.png b/en/devices/tech/settings/images/settings-guidelines20.png Binary files differnew file mode 100644 index 00000000..a6db6612 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines20.png diff --git a/en/devices/tech/settings/images/settings-guidelines21.png b/en/devices/tech/settings/images/settings-guidelines21.png Binary files differnew file mode 100644 index 00000000..868000a3 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines21.png diff --git a/en/devices/tech/settings/images/settings-guidelines22.png b/en/devices/tech/settings/images/settings-guidelines22.png Binary files differnew file mode 100644 index 00000000..5aba7e59 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines22.png diff --git a/en/devices/tech/settings/images/settings-guidelines23.png b/en/devices/tech/settings/images/settings-guidelines23.png Binary files differnew file mode 100644 index 00000000..c7a9aaf2 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines23.png diff --git a/en/devices/tech/settings/images/settings-guidelines24.png b/en/devices/tech/settings/images/settings-guidelines24.png Binary files differnew file mode 100644 index 00000000..4b88a93f --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines24.png diff --git a/en/devices/tech/settings/images/settings-guidelines25.png b/en/devices/tech/settings/images/settings-guidelines25.png Binary files differnew file mode 100644 index 00000000..431897a3 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines25.png diff --git a/en/devices/tech/settings/images/settings-guidelines26.png b/en/devices/tech/settings/images/settings-guidelines26.png Binary files differnew file mode 100644 index 00000000..72474016 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines26.png diff --git a/en/devices/tech/settings/images/settings-guidelines27.png b/en/devices/tech/settings/images/settings-guidelines27.png Binary files differnew file mode 100644 index 00000000..cb52487d --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines27.png diff --git a/en/devices/tech/settings/images/settings-guidelines28.png b/en/devices/tech/settings/images/settings-guidelines28.png Binary files differnew file mode 100644 index 00000000..4647ed76 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines28.png diff --git a/en/devices/tech/settings/images/settings-guidelines29.png b/en/devices/tech/settings/images/settings-guidelines29.png Binary files differnew file mode 100644 index 00000000..115ebea2 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines29.png diff --git a/en/devices/tech/settings/images/settings-guidelines30.png b/en/devices/tech/settings/images/settings-guidelines30.png Binary files differnew file mode 100644 index 00000000..b698a9b7 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines30.png diff --git a/en/devices/tech/settings/images/settings-guidelines31.png b/en/devices/tech/settings/images/settings-guidelines31.png Binary files differnew file mode 100644 index 00000000..b7e1dd32 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines31.png diff --git a/en/devices/tech/settings/images/settings-guidelines32.png b/en/devices/tech/settings/images/settings-guidelines32.png Binary files differnew file mode 100644 index 00000000..86759462 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines32.png diff --git a/en/devices/tech/settings/images/settings-guidelines33.png b/en/devices/tech/settings/images/settings-guidelines33.png Binary files differnew file mode 100644 index 00000000..2a7e0eda --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines33.png diff --git a/en/devices/tech/settings/images/settings-guidelines34.png b/en/devices/tech/settings/images/settings-guidelines34.png Binary files differnew file mode 100644 index 00000000..e5cdf024 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines34.png diff --git a/en/devices/tech/settings/images/settings-guidelines35.png b/en/devices/tech/settings/images/settings-guidelines35.png Binary files differnew file mode 100644 index 00000000..3cf8360d --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines35.png diff --git a/en/devices/tech/settings/images/settings-guidelines36.png b/en/devices/tech/settings/images/settings-guidelines36.png Binary files differnew file mode 100644 index 00000000..62c549a5 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines36.png diff --git a/en/devices/tech/settings/images/settings-guidelines37.png b/en/devices/tech/settings/images/settings-guidelines37.png Binary files differnew file mode 100644 index 00000000..a6748117 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines37.png diff --git a/en/devices/tech/settings/images/settings-guidelines38.png b/en/devices/tech/settings/images/settings-guidelines38.png Binary files differnew file mode 100644 index 00000000..e6a05bba --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines38.png diff --git a/en/devices/tech/settings/images/settings-guidelines39.png b/en/devices/tech/settings/images/settings-guidelines39.png Binary files differnew file mode 100644 index 00000000..d2602693 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines39.png diff --git a/en/devices/tech/settings/images/settings-guidelines40.png b/en/devices/tech/settings/images/settings-guidelines40.png Binary files differnew file mode 100644 index 00000000..3b267193 --- /dev/null +++ b/en/devices/tech/settings/images/settings-guidelines40.png diff --git a/en/devices/tech/settings/settings-guidelines.md b/en/devices/tech/settings/settings-guidelines.md new file mode 100644 index 00000000..be948b69 --- /dev/null +++ b/en/devices/tech/settings/settings-guidelines.md @@ -0,0 +1,436 @@ +Project: /_project.yaml +Book: /_book.yaml + +<!-- + Copyright 2018 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +# Android Settings Design Guidelines + +This document highlights the principles and guidelines for anyone who is either +designing Android platform settings, GMS core settings (Google Settings) or any +developers designing settings for their Android app. + +## Design principles + +### Provide a good overview + +Users should be able to glance at settings screens and understand all of the +individual settings and their values. + +<img src="images/settings-guidelines01.png" width="250" class="screenshot"> + +**Figure 1:** Settings and their current values are presented on the top-level +screen + +### Organize items intuitively + +Place frequently used settings at the top of the screen. Limit the number of +settings on one screen. Showing more than 10-15 items can be overwhelming. +Create intuitive menus by moving some settings to a separate screen. + +<img src="images/settings-guidelines02.png" width="250" class="screenshot"> + +**Figure 2:** Common settings are at the top of the screen + +### Make settings easy to find + +In some cases, it may be helpful to duplicate an individual setting on two +different screens. Different situations can trigger users to change a setting, +so including the setting in multiple places will help users find this item. + +For duplicate settings, create a separate screen for the setting and have entry +points from different places. + +<table class="columns"> + <tr> + <td><img src="images/settings-guidelines03.png" width="250" class="screenshot"></td> + <td><img src="images/settings-guidelines04.png" width="250" class="screenshot"></td> + </tr> +</table> + +**Figure 3 & 4:** "Default notification sound" appears on both the +"Notification" and "Sound" screens + +### Use a clear title and status + +Make your settings' titles brief and meaningful. Avoid using vague titles like +"General settings." Below the title, show the status to highlight the value of +the setting. Show the specific details instead of just describing the title. + +Titles should: + ++ Put the most important text of your label first. ++ Rephrase negative words like "don't" or "never" into neutral terms such as + "block." ++ Use impersonal labels like "Notifications" instead of "Notify me." + Exception: If referring to the user is necessary for understanding the + setting, use the second person ("you") rather than the first person ("I"). + +Titles should avoid: + ++ Generic terms, such as set, change, edit, modify, manage, use, select, or + choose. ++ Repeating words from the section divider or subscreen title. ++ Technical jargon. + +## Page types + +### Settings list + +This is the most common type of screen. It allows multiple settings to be placed +together. Settings lists can be a mix of controls, like switches, menus, and +sliders. + +If there are many settings in one category, they can be grouped together. See +[Grouping & dividers](#grouping_dividers) for more details. + +<img src="images/settings-guidelines05.png" width="250" class="screenshot"> + +**Figure 5**: Example of settings list + +### List view + +The list view is used to show a list of items like apps, accounts, devices, and +more. Controls to filter or sort can be added to the screen. + +<img src="images/settings-guidelines06.png" width="250" class="screenshot"> + +**Figure 6**: Example of List view + +### Entity screen + +The entity screen is used to present settings of a distinct item like an app, +account, device, Wi-Fi network, etc. + +Visually, the entity is shown at the top with an icon, title, and subtitle. All +settings on this screen must be related to this entity. + +<img src="images/settings-guidelines07.png" width="250" class="screenshot"> + +**Figure 7**: Example of Entity screen used in App info + +<img src="images/settings-guidelines08.png" width="250" class="screenshot"> + +**Figure 8**: Example of Entity screen used in Storage + +### Master setting + +The master setting is best used when an entire feature can be turned on or off, +such as Wi-Fi or Bluetooth. By using a switch at the top of the screen, the user +can easily control this feature. Using the master setting to disable the feature +disables all other related settings. + +If a feature needs a longer text description, the master setting can be used as +this screen type allows for longer footer text. + +If a setting needs to be duplicated or linked from multiple screens, use the +master setting. Since the master setting is a separate screen, you'll avoid +having multiple switches in different places for the same setting. + +<img src="images/settings-guidelines09.png" width="250" class="screenshot"> + +**Figure 9**: Example of master setting used in App notifications screen; +turning off the master toggle will turn of the entire feature for this app + +<img src="images/settings-guidelines10.png" width="250" class="screenshot"> + +**Figure 10**: Example of master setting used in App notifications screen with +master toggle turned off + +### Radio button selection screen + +This screen is used when the user needs to make a selection for a setting. Radio +buttons can either be shown in a dialog or on a separate screen. Radio buttons +should not be used alongside sliders, menus, or switches. + +A radio button screen can contain an image at the top and footer text at the +bottom. The individual radio buttons can have subtext along with a title. + +<img src="images/settings-guidelines11.png" width="250" class="screenshot"> + +**Figure 11:** Radio buttons should not be used in settings list + +<img src="images/settings-guidelines12.png" width="250" class="screenshot"> + +**Figure 12:** This is how to use radio buttons correctly in settings + +## Components + +### Header + +Starting in Android 8.0, the action toolbar presents search and help along with +other related actions. Overflow menus are discouraged as users may not discover +actions hidden in these menus. + +**For toolbars with no screen-specific actions**: Show search and help actions. + +<img src="images/settings-guidelines13.png" width="250" class="screenshot"> + +**Figure 13:** Toolbar with search and help actions + +**For toolbars with one action**: Present the action before search. + +<img src="images/settings-guidelines14.png" width="250" class="screenshot"> + +**Figure 14:** Toolbar with one action before the search and help actions + +**For toolbars with more than 1 action**: Consider placing the primary action +before search, while putting advanced actions in the overflow menu. + +If all actions are advanced or only useful for a small set of users, consider +placing all actions in the overflow menu. + +<img src="images/settings-guidelines15.png" width="250" class="screenshot"> + +**Figure 15:** Toolbar with an overflow menu for actions + +### Entity header + +The entity header can show a heading only, or heading with subtext (multiple +lines are allowed for the subtext). The action below is optional. You can have a +maximum of two actions. + +<img src="images/settings-guidelines16.png" width="250" class="screenshot"> + +**Figure 16:** Entity header + +The icon and heading (App1) part will scroll under the header (App info). + +<img src="images/settings-guidelines17.png" width="250" class="screenshot"> + +**Figure 17:** App info title here is part of the toolbar, while the rest of the +screen will scroll under it + +### Menu link + +The title is mandatory. You should also show subtext that highlights the status +of the setting. Using an icon is optional. + +Try to keep title text concise. If titles are long, they can continue on the +next line instead of being truncated. Don't enable menus or actions on long +press. + +Examples: + +<img src="images/settings-guidelines18.png" width="250" class="screenshot"> + +**Figure 18:** Menu link with icon, title, and subtext + +<img src="images/settings-guidelines19.png" width="250" class="screenshot"> + +**Figure 19:** Menu link with title and subtext + +<img src="images/settings-guidelines20.png" width="250" class="screenshot"> + +**Figure 20:** Menu link with title only + +**Menu link with icon, title, subtext and a separate hit target on the right** + +Other tap targets should use the theme color. + +<img src="images/settings-guidelines21.png" width="250" class="screenshot"> + +**Figure 21:** Example of two-tap target menu + +**Menu link with icon, title, subtext and stats/number/alert icon** + +Numerical values like percentage and time can be shown on the right along with +the subtext, while a bar graph can be shown below. + +Usually, the numerical values are presented on the right so users can easily +glance and compare them. + +<img src="images/settings-guidelines22.png" width="250" class="screenshot"> + +**Figure 22:** Example of menu with icon, title, stat and graph + +### Grouping & dividers + +If a screen has many settings, they can be grouped and separated by a divider. +Unlike older Android versions, dividers are now used to cluster settings in a +group, rather than separating individual settings. + +If the settings in a group are closely related, you can add a group heading. If +you use a group heading, you should always include a divider. + +<img src="images/settings-guidelines23.png" width="250" class="screenshot"> + +**Figure 23:** Settings grouped with dividers + +### Switch + +**Switch with icon, title, and subtext** + +<img src="images/settings-guidelines24.png" width="250" class="screenshot"> + +**Figure 24:** Switch with icon, title, and subtext + +**Switch with title and subtext** + +<img src="images/settings-guidelines25.png" width="250" class="screenshot"> + +**Figure 25:** Switch with title and subtext + +**Switch with title only** + +Titles can be accompanied by an icon on the left. + +<img src="images/settings-guidelines26.png" width="250" class="screenshot"> + +**Figure 26:** Switch with title only + +### List item + switch + +You can combine a list item with a switch. Tapping on the left side of the +vertical line acts like a link and takes the user to the next screen. The right +side behaves like a standard switch. + +For the list item on the left side, a title is mandatory. The icon and subtext +are optional. + +<img src="images/settings-guidelines27.png" width="250" class="screenshot"> + +**Figure 27:** List item and a switch + +### Slider + +The icon is optional in the slider. + +<img src="images/settings-guidelines28.png" width="250" class="screenshot"> + +**Figure 28:** Slider + +### On-screen button + +Positive actions use the theme color while negative actions are gray. Positive +actions may include opening an app, installing an app, adding a new item, etc. +Negative actions include clearing data, uninstalling an app, deleting items, +etc. + +<img src="images/settings-guidelines29.png" width="250" class="screenshot"> + +**Figure 29:** Gray buttons for "Uninstall" and "Force stop" + +<img src="images/settings-guidelines30.png" width="250" class="screenshot"> + +**Figure 30:** Blue button for "Turn on now" + +### Progressive disclosure (Advanced) + +Settings that are not frequently used should be hidden. Use "Advanced" only when +there are at least 3 items to hide. + +Here, the subtext shows the titles of the settings that are hidden. The subtext +should be only one line. Additional text gets truncated with an ellipsis. + +<img src="images/settings-guidelines31.png" width="250" class="screenshot"> + +**Figure 31:** Advanced used on the "Display'" screen + +### Drop-down menu + +Drop-down menus are available, but ideally you should use a dialog or radio +button selection screen instead. This is recommended to simplify settings, as +there are currently three different patterns for single selection. + +If needed, drop-down menus can be used in cases where the setting has simple +options. + +<img src="images/settings-guidelines32.png" width="250" class="screenshot"> + +**Figure 32:** Drop-down menu + +### Checkbox + +Use switches over checkboxes when possible. + +Checkboxes can be used: + ++ For negative actions like restricting apps or blocking a service. ++ To avoid having too many switches on the screen. + +<img src="images/settings-guidelines33.png" width="250" class="screenshot"> + +**Figure 33**: Checkboxes are used to reduce the number of switches on this +screen + +### Links + +Using links in settings is not recommended. Only use links where absolutely +necessary. Links should use an accent color with no underline. + +<img src="images/settings-guidelines34.png" width="250" class="screenshot"> + +**Figure 34:** Link used in settings + +### Footer + +Footer text can be used to add explanatory content. The footer should always +have a divider at the top. The footer is shown at the bottom of the screen. +Footers can have links, if needed. + +<img src="images/settings-guidelines35.png" width="250" class="screenshot"> + +**Figure 35:** Footer text + +## Patterns + +### Data + +Critical data can be shown in a graph like a bar or pie chart. This data can be +shown in the entity header. Examples include mobile data and storage. + +Other less critical data can be presented by using a regular list view. + +<img src="images/settings-guidelines36.png" width="250" class="screenshot"> + +**Figure 36:** Example showing Storage + +<img src="images/settings-guidelines37.png" width="250" class="screenshot"> + +**Figure 37:** Example showing Network + +### User education + +Some features may need an explanation or user education. You can use an +animation or image along with text. The animation or image should be presented +at the top of the screen, while the footer text can be used to add an +explanation. + +<img src="images/settings-guidelines38.png" width="250" class="screenshot"> + +**Figure 38:** Setting using animation and footer text + +### Forms + +If the form has one input field, use a normal dialog. This provides an easy way +for users to enter a single input. + +However, if the form has several fields, consider using a [full-screen dialog](https://material.io/design/components/dialogs.html#full-screen-dialog). +This provides more screen space to arrange the fields in a clear pattern. + +<img src="images/settings-guidelines39.png" width="250" class="screenshot"> + +**Figure 39:** Form with a normal dialog + +### Search results + +Search results show the title, subtext (if available), and the breadcrumb +location of the setting. + +<img src="images/settings-guidelines40.png" width="250" class="screenshot"> + +**Figure 40:** Search result |
