docs: Iterating on Wear docs - Complications am: dcab4687db (f42a132d) · Commits · e / os / android_frameworks_base

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

+122 −106

Original line number	Original line	Diff line number	Diff line
	page.title=Watch Face Complications		page.title=Watch Face Complications
	meta.keywords="wear-preview"		meta.keywords="wear-preview"
	page.tags="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		@jd:body

	<div id="qv-wrapper">		<div id="qv-wrapper">
	<div id="qv">		<div id="qv">
			<h2>In this document</h2>
	<ol>		<ol>
	<li>		<li>
	<a href=		<a href="#adding_complications_to_a_watch_face">Adding
	"#adding_complications_to_a_watch_face">Adding Complications to a Watch Face</a>		Complications to a Watch Face</a>
	</li>		</li>
	<li>		<li>
	<a href=		<a href="#exposing_data_to_complications">Exposing Data to
	"#exposing_data_to_complications">Exposing Data to Complications</a>		Complications</a>
	</li>		</li>
	<li>		<li>
	<a href=		<a href="#using_complication_types">Using Complication Types</a>
	"#using_complication_types">Using Complication Types</a>
	</li>		</li>
	<li>		<li>
	<a href=		<a href="#using_fields_for_complication_data">Using Fields for
	"#using_fields_for_complication_data">Using Fields for Complication Data</a>		Complication Data</a>
	</li>		</li>
	<li>		<li>
	<a href=		<a href="#api_additions">API Additions</a>
	"#api_additions">API Additions</a>
	</li>		</li>
	</ol>		</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>
	</div>		</div>

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

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

	<p>		<p>
	Watch faces can display extra information without needing code for		Watch faces can display extra information without needing code for
	@@ -49,42 +55,45 @@ page.image=images/cards/card-n-sdk_2x.png
	API.		API.
	</p>		</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>		<p>
	Along with reviewing this page, download the Android Wear 2.0 Preview		Along with reviewing this page, download the Android Wear 2.0 Preview
	Reference and review the <a href="#api_additions">API additions</a> in		Reference (see the Complications API <a href=
	the Javadoc for complications.		"#api_additions">additions</a>) and review the Javadoc for complications.
	</p>		</p>

	<p>		<p>
	Apps that provide data to watch faces for complications are called		Apps that provide data to watch faces for complications are called
	"complication data providers." These apps lack control over how their		"complication data providers." These apps are not responsible for controlling
	data is rendered. The consuming watch faces are responsible for drawing		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.		the complications.
	</p>		</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>		<p>
	As indicated in the diagram below, Android Wear mediates the flow of data		As indicated in the diagram below, Android Wear mediates the flow of data
	from providers to watch faces.		from providers to watch faces.
	</p>		</p>

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

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

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

	<p>		<p>
	Include metadata to specify the supported types, update period, and		Include metadata to specify the supported types, update period, and
	configuration action, if required; for details, download the Android Wear		configuration action, if required; for details, download the Android Wear
	2.0 Preview Reference and see the keys listed for the		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>		</p>

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

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

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

	<pre>		<pre>
	METADATA_KEY_PROVIDER_CONFIG_ACTION		METADATA_KEY_PROVIDER_CONFIG_ACTION
	</pre>		</pre>

	<h2 id="using_complication_types">		<h2 id="using_complication_types">
	Using Complication Types		Using Complication Types
	</h2>		</h2>
	@@ -340,6 +348,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
	gauges can be shown without including text.		gauges can be shown without including text.
	</p>		</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">		<h3 id="types_and_fields">
	Types and fields		Types and fields
	@@ -352,16 +370,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

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

	<tr>		<tr>
	<td>		<td>
	LONG_TEXT		ICON
	</td>		</td>
	<td>		<td>
	Long text		Icon
	</td>		</td>
	<td>		<td>
	Long titleIcon*Small image
	</td>		</td>
	<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>		</td>
	</tr>		</tr>

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

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

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

	<table>		<table>
	<tr>		<tr>
	<th scope="col">		<th>
	Type		Type
	</th>		</th>
	<th scope="col">		<th>
	Required fields		Required fields
	</th>		</th>
	<th scope="col">		<th>
	Optional fields		Optional fields
	</th>		</th>
	<th scope="col">		<th>
	Notes		Notes
	</th>		</th>
	</tr>		</tr>
	@@ -514,16 +538,6 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
	</tr>		</tr>
	</table>		</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">		<h2 id="using_fields_for_complication_data">
	Using Fields for Complication Data		Using Fields for Complication Data
	</h2>		</h2>
	@@ -543,10 +557,10 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

	<table>		<table>
	<tr>		<tr>
	<th scope="col">		<th>
	Field		Field
	</th>		</th>
	<th scope="col">		<th>
	Description		Description
	</th>		</th>
	</tr>		</tr>
	@@ -561,6 +575,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
	</td>		</td>
	</tr>		</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>		<tr>
	<td>		<td>
	Short title		Short title
	@@ -624,16 +648,6 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
	</td>		</td>
	</tr>		</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>		<tr>
	<td>		<td>
	Small image		Small image
	@@ -681,8 +695,10 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
	</h2>		</h2>

	<p>		<p>
	The Complications API includes the following new classes in the Wearable		The Complications API includes new classes in the Wearable Support
	Support Library:		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>		</p>

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

	<p>		<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.		testing against the latest platform changes.
	</p>		</p>
	</div>		</div>
	@@ -126,7 +126,7 @@ page.image=images/cards/card-n-sdk_2x.png

	<p>		<p>
	The first three milestones provide an early test and development		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		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		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,		on features and APIs and file compatibility issues — for all of these,