# GlanceWearWidget

Artifact: [androidx.glance.wear:wear](https://developer.android.com/jetpack/androidx/releases/glance-wear) [View Source](https://cs.android.com/search?q=file:androidx/glance/wear/GlanceWearWidget.kt+class:androidx.glance.wear.GlanceWearWidget) Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)


```
abstract class GlanceWearWidget
```

<br />

*** ** * ** ***

Object that handles providing the contents of a Wear Widget.

The widget UI is defined by an instance of `https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetData` such as `https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetDocument`, provided in the implementation of `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)`.

An implementation of this class can be associated with a `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidgetService` for receiving content requests and events from the Host.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#GlanceWearWidget()()` |

| ### Public functions |
|---|---|
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#onAdded(android.content.Context,androidx.glance.wear.core.ActiveWearWidgetHandle)(context: https://developer.android.com/reference/android/content/Context.html, widgetHandle: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/ActiveWearWidgetHandle)` Called when a widget provider linked to this widget class is added to the host. |
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#onEvents(android.content.Context,kotlin.collections.List)(context: https://developer.android.com/reference/android/content/Context.html, events: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WearWidgetEvent>)` Called when the system sends a batch of interaction events. |
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#onRemoved(android.content.Context,androidx.glance.wear.core.ActiveWearWidgetHandle)(context: https://developer.android.com/reference/android/content/Context.html, widgetHandle: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/ActiveWearWidgetHandle)` Called when a widget provider linked to this widget class is removed from the host. |
| `abstract suspend https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetData` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)(context: https://developer.android.com/reference/android/content/Context.html, params: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WearWidgetParams)` Override this method to provide data for this Widget. |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#triggerUpdate(android.content.Context,androidx.glance.wear.core.WidgetInstanceId)(context: https://developer.android.com/reference/android/content/Context.html, instanceId: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WidgetInstanceId)` Triggers a content update for the given widget `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#triggerUpdate(android.content.Context,androidx.glance.wear.core.WidgetInstanceId)`, resulting in a call to `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)`, after which the results are pushed to the Host. |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#triggerUpdateAll(android.content.Context)(context: https://developer.android.com/reference/android/content/Context.html)` Triggers a content update for all active widget instances associated with this class, resulting in calls to `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)`, after which the results are pushed to the Host. |

## Public constructors

### GlanceWearWidget

Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)

```
GlanceWearWidget()
```

## Public functions

### onAdded

Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)

```
@MainThread
open suspend fun onAdded(context: Context, widgetHandle: ActiveWearWidgetHandle): Unit
```

Called when a widget provider linked to this widget class is added to the host.

This occurs when a widget is added to the carousel.

This method is called from the main thread.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called |
| `widgetHandle: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/ActiveWearWidgetHandle` | the handle of the active widget. |

### onEvents

```
@MainThread
open suspend fun onEvents(context: Context, events: List<WearWidgetEvent>): Unit
```

Called when the system sends a batch of interaction events. The time between calls to this method may vary; do not depend on it for time-sensitive or critical tasks.

Interaction events represent user direct interaction with a widget, for example when a widget was visible.

This function must complete within 10 seconds of being called. If the timeout is exceeded, the operation will be canceled.

This method is called from the main thread.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called |
| `events: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WearWidgetEvent>` | A list of `https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WearWidgetEvent` representing interactions that occurred. |

### onRemoved

Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)

```
@MainThread
open suspend fun onRemoved(context: Context, widgetHandle: ActiveWearWidgetHandle): Unit
```

Called when a widget provider linked to this widget class is removed from the host.

This occurs when a widget is removed from the carousel.

This method is called from the main thread.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called |
| `widgetHandle: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/ActiveWearWidgetHandle` | the handle of the active widget. |

### provideWidgetData

```
@MainThread
abstract suspend fun provideWidgetData(context: Context, params: WearWidgetParams): WearWidgetData
```

Override this method to provide data for this Widget.

This method is called from the main thread.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called |
| `params: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WearWidgetParams` | the parameters that describe the widget for which the data is being provided. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetData` | the widget data for this Widget. |

### triggerUpdate

Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)

```
suspend fun triggerUpdate(context: Context, instanceId: WidgetInstanceId): Unit
```

Triggers a content update for the given widget `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#triggerUpdate(android.content.Context,androidx.glance.wear.core.WidgetInstanceId)`, resulting in a call to `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)`, after which the results are pushed to the Host.

All `https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WidgetInstanceId` for active widgets associated with this class can be retrieved from GlanceWearWidgetManager.fetchActiveWidgets(KClass).

The coroutine will be canceled if it doesn't complete within 10 seconds of being called.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called. |
| `instanceId: https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WidgetInstanceId` | the ID of the widget instance to update. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the provided `https://developer.android.com/reference/kotlin/androidx/glance/wear/core/WidgetInstanceId` is invalid or not owned by the calling application. |
| `https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetContentTooLargeException` | if the widget content exceeds the maximum size that can be sent to the Host in a single Binder transaction. |

### triggerUpdateAll

Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/glance-wear#1.0.0-alpha22)

```
suspend fun triggerUpdateAll(context: Context): Unit
```

Triggers a content update for all active widget instances associated with this class, resulting in calls to `https://developer.android.com/reference/kotlin/androidx/glance/wear/GlanceWearWidget#provideWidgetData(android.content.Context,androidx.glance.wear.core.WearWidgetParams)`, after which the results are pushed to the Host.

Each individual update coroutine will be canceled if it doesn't complete within 10 seconds of being called.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the context from which this method is called. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/glance/wear/WearWidgetContentTooLargeException` | if the content of any widget instance exceeds the maximum size that can be sent to the Host in a single Binder transaction. Other widget instances are still updated. If several instances fail, the exceptions for the others are attached to the thrown one as `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/index.html`. |