en/devices/tech/settings/patterns-components.html - platform/docs/source.android.com - Git at Google

 <html devsite>
   <head>
     <title>Patterns and Components</title>
     <meta name="project_path" value="/_project.yaml" />
     <meta name="book_path" value="/_book.yaml" />
   </head>
   <body>
   <!--
       Copyright 2017 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.
   -->

 <p>
 In Android 8.0, the Settings menu gains several components and widgets that
 cover common uses. Device manufacturers and developers are encouraged to use the
 common components when extending the Settings app so new user interfaces stay
 consistent with the existing Settings UI.
 </p>

 <p>
 Here is a summary of improvements:
 </p>

 <ul>
 <li>Divider behavior change in support library Preference framework. Divider is
 now drawn between categories.</li>
 <li>ActionBar theme change. The ActionBar now uses light color theme, with
 accent color text.</li>
 <li>New preference layout. The space for icons remains even when a preference
 has no icon.</li>
 </ul>

 <p>
 New widgets:
 </p>

 <ul>
 <li>A header widget for application details. Displays app icon, app label and
 other information.</li>
 <li>An expand button on some pages. Page can start as collapsed and hide less
 important items until user clicks expand button.</li>
 <li>Default app picker UI:
   <ul>
   <li>The UI for choosing default browser, default phone app, etc.</li>
   <li>Formerly a dialog, now it's a full screen radio button-based UI.</li>
   </ul>
 <li>A "MasterSwitch" style preference. This is a preference with two click
 targets. Left target leads to a subsetting fragment or intent. Right target is a
 switch toggle, controlling on/off for the entire page.</li>
 </ul>

 <h2 id="examples-and-source">Examples and source</h2>
 <ul>
 <li>Divider behavior
   <ul>
   <li>All pages in Settings are modified to use the new divider behavior.</li>
   <li>The divider behavior is defined as a ThemeOverlay in:<br>
 <code>packages/apps/Settings/res/values/styles_preference.xml</code></li>
   </ul>
 </li>
 <li>ActionBar theme change
   <ul>
   <li>All pages in Settings are modified to use the new ActionBar theme.</li>
   <li>The theme is defined in Theme.DeviceDefault.Settings</li>
   </ul>
 </li>
 <li>New preference layout
   <ul>
   <li>Many pages in Settings are now using the new preference layout.</li>
   <li>You can find the code in:<br>
 <code>packages/apps/Settings/res/values/styles_preference.xml</code></li>
   </ul>
 </li>
 <li>App header widget
   <ul>
   <li>Most application information pages in Settings are already implementing the
 new App header.</li>
   <li>Examples and code can be found at:<br>
 <code>packages/apps/Settings/src/com/android/settings/applications/AppHeaderController.java</code></li>
   </ul>
 </li>
 <li>Expand button
   <ul>
   <li>Examples and code can be found at:<br>
 <code>packages/apps/Settings/src/com/android/settings/dashboard/ProgressiveDisclosureMixin.java</code>
 <p class="note"><strong>Note:</strong> This component must be used together with
 DashboardFragment. (See more details about DashboardFragment in <a
 href="info-architecture.html">Updated Information Architecture</a>.)</p>
   </li>
   </ul>
 <li>Default app picker
   <ul>
   <li>You can find the code for base class in:<br>
 <code>packages/apps/Settings/src/com/android/settings/applications/defaultapps/DefaultAppPickerFragment.java</code>  </li>
   <li>There are several subclasses of DefaultAppPickerFragment, each implementing
 a picker for different intent.</li>
   </ul>
 </li>
 <li><em>MasterSwitch</em> style preference
   <ul>
   <li>Code is at:
 <code>packages/apps/Settings/src/com/android/settings/widget/MasterSwitchPreference.java</code></li>
   <li>An example use case is Wi-Fi master switch. You can find an example at:
 <code>packages/apps/Settings/src/com/android/settings/wifi/WifiMasterSwitchPreferenceController.java</code></li>
   </ul>
 </li>
 </ul>

 <h2 id="implementation">Implementation</h2>

 <p>
 Device manufacturers can start using all of the new components out of the box.
 If OEMs decide to implement a new "MasterSwitch" style preference or default app
 picker, they should follow the examples in this document and the reference files
 (Javadoc) written with each component for more details.
 </p>

 <h2 id="customizing">Customizing</h2>

 <ul>
 <li>Divider behavior. To change how divider is drawn, update the style for Settings dividers and
 change the value for the following:
   <ul>
   <li>allowDividerAbove</li>
   <li>allowDividerBelow</li>
   <li>allowDividerAfterLastItem</li>
   </ul>
 </li>
 <li>ActionBar theme color. Activities should use <code>Theme.DeviceDefault.Settings</code> as their theme, or
 create a custom theme using <code>Theme.DeviceDefault.Settings</code> as parent.
 </li>
 <li>App header widget. Use setters in AppHeaderController to customize each field and call build()
 once all fields are set.
 </li>
 <li>Expand button:
   <ul>
   <li>To fully disable the functionality, override the constructor for
 ProgressiveDisclosureMixin and set keepExpanded to true.</li>
   <li>To customize how many items to show initially, call the
 <code>ProgressiveDisclosureMixin.setTileLimit()</code> method during fragment's
 <code>onAttach(Context)</code> method.</li>
   </ul>
 </li>
 </ul>
 </body>
 </html>
	<html devsite>
	<head>
	<title>Patterns and Components</title>
	<meta name="project_path" value="/_project.yaml" />
	<meta name="book_path" value="/_book.yaml" />
	</head>
	<body>
	<!--
	Copyright 2017 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.
	-->

	<p>
	In Android 8.0, the Settings menu gains several components and widgets that
	cover common uses. Device manufacturers and developers are encouraged to use the
	common components when extending the Settings app so new user interfaces stay
	consistent with the existing Settings UI.
	</p>

	<p>
	Here is a summary of improvements:
	</p>

	<ul>
	<li>Divider behavior change in support library Preference framework. Divider is
	now drawn between categories.</li>
	<li>ActionBar theme change. The ActionBar now uses light color theme, with
	accent color text.</li>
	<li>New preference layout. The space for icons remains even when a preference
	has no icon.</li>
	</ul>

	<p>
	New widgets:
	</p>

	<ul>
	<li>A header widget for application details. Displays app icon, app label and
	other information.</li>
	<li>An expand button on some pages. Page can start as collapsed and hide less
	important items until user clicks expand button.</li>
	<li>Default app picker UI:
	<ul>
	<li>The UI for choosing default browser, default phone app, etc.</li>
	<li>Formerly a dialog, now it's a full screen radio button-based UI.</li>
	</ul>
	<li>A "MasterSwitch" style preference. This is a preference with two click
	targets. Left target leads to a subsetting fragment or intent. Right target is a
	switch toggle, controlling on/off for the entire page.</li>
	</ul>

	<h2 id="examples-and-source">Examples and source</h2>
	<ul>
	<li>Divider behavior
	<ul>
	<li>All pages in Settings are modified to use the new divider behavior.</li>
	<li>The divider behavior is defined as a ThemeOverlay in:<br>
	<code>packages/apps/Settings/res/values/styles_preference.xml</code></li>
	</ul>
	</li>
	<li>ActionBar theme change
	<ul>
	<li>All pages in Settings are modified to use the new ActionBar theme.</li>
	<li>The theme is defined in Theme.DeviceDefault.Settings</li>
	</ul>
	</li>
	<li>New preference layout
	<ul>
	<li>Many pages in Settings are now using the new preference layout.</li>
	<li>You can find the code in:<br>
	<code>packages/apps/Settings/res/values/styles_preference.xml</code></li>
	</ul>
	</li>
	<li>App header widget
	<ul>
	<li>Most application information pages in Settings are already implementing the
	new App header.</li>
	<li>Examples and code can be found at:<br>
	<code>packages/apps/Settings/src/com/android/settings/applications/AppHeaderController.java</code></li>
	</ul>
	</li>
	<li>Expand button
	<ul>
	<li>Examples and code can be found at:<br>
	<code>packages/apps/Settings/src/com/android/settings/dashboard/ProgressiveDisclosureMixin.java</code>
	<p class="note"><strong>Note:</strong> This component must be used together with
	DashboardFragment. (See more details about DashboardFragment in <a
	href="info-architecture.html">Updated Information Architecture</a>.)</p>
	</li>
	</ul>
	<li>Default app picker
	<ul>
	<li>You can find the code for base class in:<br>
	<code>packages/apps/Settings/src/com/android/settings/applications/defaultapps/DefaultAppPickerFragment.java</code> </li>
	<li>There are several subclasses of DefaultAppPickerFragment, each implementing
	a picker for different intent.</li>
	</ul>
	</li>
	<li><em>MasterSwitch</em> style preference
	<ul>
	<li>Code is at:
	<code>packages/apps/Settings/src/com/android/settings/widget/MasterSwitchPreference.java</code></li>
	<li>An example use case is Wi-Fi master switch. You can find an example at:
	<code>packages/apps/Settings/src/com/android/settings/wifi/WifiMasterSwitchPreferenceController.java</code></li>
	</ul>
	</li>
	</ul>

	<h2 id="implementation">Implementation</h2>

	<p>
	Device manufacturers can start using all of the new components out of the box.
	If OEMs decide to implement a new "MasterSwitch" style preference or default app
	picker, they should follow the examples in this document and the reference files
	(Javadoc) written with each component for more details.
	</p>

	<h2 id="customizing">Customizing</h2>

	<ul>
	<li>Divider behavior. To change how divider is drawn, update the style for Settings dividers and
	change the value for the following:
	<ul>
	<li>allowDividerAbove</li>
	<li>allowDividerBelow</li>
	<li>allowDividerAfterLastItem</li>
	</ul>
	</li>
	<li>ActionBar theme color. Activities should use <code>Theme.DeviceDefault.Settings</code> as their theme, or
	create a custom theme using <code>Theme.DeviceDefault.Settings</code> as parent.
	</li>
	<li>App header widget. Use setters in AppHeaderController to customize each field and call build()
	once all fields are set.
	</li>
	<li>Expand button:
	<ul>
	<li>To fully disable the functionality, override the constructor for
	ProgressiveDisclosureMixin and set keepExpanded to true.</li>
	<li>To customize how many items to show initially, call the
	<code>ProgressiveDisclosureMixin.setTileLimit()</code> method during fragment's
	<code>onAttach(Context)</code> method.</li>
	</ul>
	</li>
	</ul>
	</body>
	</html>