docs: Iterating on Wear docs - Complications (dcab4687) · Commits · e / os / android_frameworks_base

docs/html/wear/preview/features/complications.jd

+122 −106

Original line number	Diff line number	Diff line
		page.title=Watch Face Complications
		meta.keywords="wear-preview"
		page.tags="wear-preview"
		page.image=images/cards/card-n-sdk_2x.png

		page.image=/wear/preview/images/complications-main-image.png
		@jd:body

		<div id="qv-wrapper">
		<div id="qv">
		<h2>In this document</h2>
		<ol>
		<li>
		<a href=
		"#adding_complications_to_a_watch_face">Adding Complications to a Watch Face</a>
		<a href="#adding_complications_to_a_watch_face">Adding
		Complications to a Watch Face</a>
		</li>
		<li>
		<a href=
		"#exposing_data_to_complications">Exposing Data to Complications</a>
		<a href="#exposing_data_to_complications">Exposing Data to
		Complications</a>
		</li>
		<li>
		<a href=
		"#using_complication_types">Using Complication Types</a>
		<a href="#using_complication_types">Using Complication Types</a>
		</li>
		<li>
		<a href=
		"#using_fields_for_complication_data">Using Fields for Complication Data</a>
		<a href="#using_fields_for_complication_data">Using Fields for
		Complication Data</a>
		</li>
		<li>
		<a href=
		"#api_additions">API Additions</a>
		<a href="#api_additions">API Additions</a>
		</li>
		</ol>
		<h2>See Also</h2>
		<ol>
		<li><a class="external-link"
		href="https://github.com/googlesamples/android-WatchFace">Watch
		Face sample app with complications</a></li>
		</ol>
		</div>
		</div>

		<p>
		A complication is a feature of a watch face <a href=
		"https://en.wikipedia.org/wiki/Complication_(horology)">beyond hours and
		minutes</a>. For example, a battery indicator is a complication.
		A complication is any feature in a watch face that displays <a href=
		"https://en.wikipedia.org/wiki/Complication_(horology)">more than hours and
		minutes</a>. For example, a battery indicator is a complication. The
		Complications API is for both watch faces and data provider apps.
		</p>

		<p>
		The Complications API is for both watch faces and data provider apps.
		</p>
		<div class="col-4of10">
		<img src="../images/complications-main-image.png" alt="Complications"
		id="img-split-screen">
		</div>

		<p>
		Watch faces can display extra information without needing code for
		@@ -49,42 +55,45 @@ page.image=images/cards/card-n-sdk_2x.png
		API.
		</p>

		<p>
		For creating or modifying watch faces, see <a href=
		"#adding_complications_to_a_watch_face">Adding complications to a watch
		face</a>.
		</p>

		<p>
		For writing apps that provide data to watch faces, see <a href=
		"#exposing_data_to_complications">Exposing data to complications</a>.
		</p>

		<p>
		Along with reviewing this page, download the Android Wear 2.0 Preview
		Reference and review the <a href="#api_additions">API additions</a> in
		the Javadoc for complications.
		Reference (see the Complications API <a href=
		"#api_additions">additions</a>) and review the Javadoc for complications.
		</p>

		<p>
		Apps that provide data to watch faces for complications are called
		"complication data providers." These apps lack control over how their
		data is rendered. The consuming watch faces are responsible for drawing
		"complication data providers." These apps are not responsible for controlling
		how their data is rendered on the watch face.
		This allows a watch face to integrate the data naturally with the
		watch face design.
		The consuming watch faces are responsible for drawing
		the complications.
		</p>

		<p>
		Watch faces can receive complication data of
		<a href="#using_complication_types">various types</a> (e.g. small text
		data or icon data) and then display it.
		</p>

		<p>
		As indicated in the diagram below, Android Wear mediates the flow of data
		from providers to watch faces.
		</p>

		<img src="../images/complications-data-flow.png" width="" alt="Complications data flow" title=
		"Complications data flow">
		<img src="../images/complications-data-flow.png" width="" alt=
		"Complications data flow" title="Complications data flow">

		<p>
		Through this process, watch faces can receive complication data of
		<a href="#using_complication_types">various types</a> (e.g. small text
		data or icon data) and then display it.
		For creating or modifying watch faces, see <a href=
		"#adding_complications_to_a_watch_face">Adding complications to a watch
		face</a>.
		</p>

		<p>
		For writing apps that provide data to watch faces, see <a href=
		"#exposing_data_to_complications">Exposing data to complications</a>.
		</p>

		<h2 id="adding_complications_to_a_watch_face">
		@@ -205,15 +214,17 @@ android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST
		<p>
		The service's manifest entry should also include an
		<code>android:icon</code> attribute. The provided icon should be a
		single-color white icon. This icon should represent the provider and will
		be shown in the provider chooser.
		single-color white icon. Vector drawables are recommended for the icons.
		An icon should represent the provider and will be shown in the provider
		chooser.
		</p>

		<p>
		Include metadata to specify the supported types, update period, and
		configuration action, if required; for details, download the Android Wear
		2.0 Preview Reference and see the keys listed for the
		<code>ComplicationProviderService</code> class (in the Javadoc).
		<code>ComplicationProviderService</code> class (in the Javadoc; see
		<a href="#api_additions">API Additions</a>).
		</p>

		<h3 id="update_period">
		@@ -266,11 +277,7 @@ android.support.wearable.complications.UPDATE_PERIOD_SECONDS
		<p>
		Then create the configuration activity with an intent filter for that
		action. The configuration activity must reside in the same package as the
		provider.
		</p>

		<p>
		The configuration activity must return <code>RESULT_OK</code> or
		provider. The configuration activity must return <code>RESULT_OK</code> or
		<code>RESULT_CANCELED</code>, to tell the system whether the provider
		should be set.
		</p>
		@@ -281,14 +288,15 @@ android.support.wearable.complications.UPDATE_PERIOD_SECONDS
		</p>

		<p>
		For details, download the Android Wear 2.0 Preview Reference, containing
		the Javadoc, and see the following in the
		<code>ComplicationProviderService</code> class:
		For details, download the Android Wear 2.0 Preview Reference (see
		<a href="#api_additions">API Additions</a>), containing the Javadoc, and
		see the following in the <code>ComplicationProviderService</code> class:
		</p>

		<pre>
		METADATA_KEY_PROVIDER_CONFIG_ACTION
		</pre>

		<h2 id="using_complication_types">
		Using Complication Types
		</h2>
		@@ -340,6 +348,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		gauges can be shown without including text.
		</p>

		<h3 id="examples_of_complication_types">
		Examples of Complication Types
		</h3>

		<p>
		The following shows examples of complication types:
		</p>
		<img src="../images/complication-type-exs.png" width="" alt=
		"Complication types" title="Complications types - examples">


		<h3 id="types_and_fields">
		Types and fields
		@@ -352,16 +370,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

		<table>
		<tr>
		<th scope="col">
		<th>
		Type
		</th>
		<th scope="col">
		<th>
		Required fields
		</th>
		<th scope="col">
		<th>
		Optional fields
		</th>
		<th scope="col">
		<th>
		Notes
		</th>
		</tr>
		@@ -374,7 +392,8 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		Short text
		</td>
		<td>
		IconShort title
		Icon<br>
		Short title
		</td>
		<td>
		Exactly one of Icon/Short title is expected to be shown if either or
		@@ -384,16 +403,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

		<tr>
		<td>
		LONG_TEXT
		ICON
		</td>
		<td>
		Long text
		Icon
		</td>
		<td>
		Long titleIcon*Small image
		</td>
		<td>
		Title is expected to be shown if provided.
		Used when text is not needed.The icon is expected to be single-color,
		and may be tinted by the watch face.
		</td>
		</tr>

		@@ -402,29 +421,34 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		RANGED_VALUE
		</td>
		<td>
		ValueMin valueMax value
		Value<br>
		Min value<br>
		Max value
		</td>
		<td>
		IconShort textShort title
		Icon<br>
		Short text<br>
		Short title
		</td>
		<td>
		Optional fields are not guaranteed to be displayed. Uses include for
		numerical data within bounds, such as for a percentage.
		Optional fields are not guaranteed to be displayed.
		</td>
		</tr>

		<tr>
		<td>
		ICON
		LONG_TEXT
		</td>
		<td>
		Icon
		Long text
		</td>
		<td>
		Long title<br>
		Icon<br>
		Small image
		</td>
		<td>
		Used when text is not needed.The icon is expected to be single-color,
		and may be tinted by the watch face.
		Title is expected to be shown if provided.
		</td>
		</tr>

		@@ -467,16 +491,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

		<table>
		<tr>
		<th scope="col">
		<th>
		Type
		</th>
		<th scope="col">
		<th>
		Required fields
		</th>
		<th scope="col">
		<th>
		Optional fields
		</th>
		<th scope="col">
		<th>
		Notes
		</th>
		</tr>
		@@ -514,16 +538,6 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		</tr>
		</table>

		<h3 id="examples_of_complication_types">
		Examples of Complication Types
		</h3>
		<p>
		The following shows examples of complication types:
		</p>

		<img src="../images/complication-type-exs.png" width=""
		alt="Complication types" title="Complications types - examples">

		<h2 id="using_fields_for_complication_data">
		Using Fields for Complication Data
		</h2>
		@@ -543,10 +557,10 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

		<table>
		<tr>
		<th scope="col">
		<th>
		Field
		</th>
		<th scope="col">
		<th>
		Description
		</th>
		</tr>
		@@ -561,6 +575,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		</td>
		</tr>

		<tr>
		<td>
		Icon
		</td>
		<td>
		A single-color image representing the data or the source of the data.
		Must be tintable. Vector drawables are recommended for this field.
		</td>
		</tr>

		<tr>
		<td>
		Short title
		@@ -624,16 +648,6 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		</td>
		</tr>

		<tr>
		<td>
		Icon
		</td>
		<td>
		A single-color image representing the data or the source of the
		data.Must be tintable.
		</td>
		</tr>

		<tr>
		<td>
		Small image
		@@ -681,8 +695,10 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
		</h2>

		<p>
		The Complications API includes the following new classes in the Wearable
		Support Library:
		The Complications API includes new classes in the Wearable Support
		Library. For more information, download the <a href=
		"{@docRoot}wear/preview/start.html#get_the_preview_reference_documentation">
		Android Wear 2.0 Preview Reference</a>.
		</p>

		<ul>

docs/html/wear/preview/images/complication-type-exs.png

+21.6 KiB (86.6 KiB)

Loading image diff...

docs/html/wear/preview/images/complications-data-flow.png

+50.6 KiB (66.3 KiB)

Loading image diff...

docs/html/wear/preview/images/complications-main-image.png

0 → 100644

+120 KiB

Loading image diff...

docs/html/wear/preview/program.jd

+2 −2

Original line number	Diff line number	Diff line
		@@ -35,7 +35,7 @@ page.image=images/cards/card-n-sdk_2x.png
		</h5>

		<p>
		We’ll provide monthly updates during the preview, so you'll be
		We'll provide frequent updates during the preview, so you'll be
		testing against the latest platform changes.
		</p>
		</div>
		@@ -126,7 +126,7 @@ page.image=images/cards/card-n-sdk_2x.png

		<p>
		The first three milestones provide an early test and development
		environment to helps you identify compatibility issues in your current
		environment to help you identify compatibility issues in your current
		apps and plan migration or feature work needed to target the new
		platform. This is the priority period in which to give us your feedback
		on features and APIs and file compatibility issues — for all of these,