feat: request widget update by id

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `requestWidgetUpdateById` function to update single widget
+
 ## [0.12.0] - 2024-03-16
 
 ### Added

docs/docs/api/register-widget-configuration-screen.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # registerWidgetConfigurationScreen

docs/docs/api/request-widget-update-by-id.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 4
+---
+
+# requestWidgetUpdateById
+
+`react-native-android-widget` exports a `requestWidgetUpdateById` function that can be used to request a widget update while the application is open (or with some background task) for a single widget with known id.
+
+This is an alternative to [`requestWidgetUpdate`](./request-widget-update.md) and should be used in special cases when the widget id is known, and you don't want to update the other widgets with the same name.
+
+## Usage
+
+Lets assume we have a `CounterWidget` widget that shows a single number, which it gets as a prop.
+
+If the user has added the `CounterWidget` multiple times, `requestWidgetUpdateById` will update only one widget which corresponds with the given `widgetId`.
+
+If a widget with the given `widgetId` does not exist, the optional callback `widgetNotFound` will be called.
+
+### Example
+
+```jsx title="CounterScreen.tsx"
+import * as React from 'react';
+import { Button, StyleSheet, View, Text } from 'react-native';
+import { requestWidgetUpdateById } from 'react-native-android-widget';
+
+import { CounterWidget } from './CounterWidget';
+
+export function CounterScreen() {
+ const [count, setCount] = React.useState(0);
+
+ React.useEffect(() => {
+ requestWidgetUpdateById({
+ widgetName: 'Counter',
+ widgetId: 1,
+ renderWidget: () => <CounterWidget count={count} />,
+ widgetNotFound: () => {
+ // Called if no widget is present on the home screen
+ },
+ });
+ }, [count]);
+
+ return (
+ <View style={styles.container}>
+ <Text>{count}</Text>
+ <Button title="Increment" onPress={() => setCount(count + 1)} />
+ <Button title="Decrement" onPress={() => setCount(count - 1)} />
+ </View>
+ );
+}
+
+const styles = StyleSheet.create({
+ container: {
+ flex: 1,
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+});
+```
+
+## Types
+
+Check the types in the [Public API](/docs/public-api#requestwidgetupdatebyid) documentation
+
+The `requestWidgetUpdate` function should be called with the properties described with [RequestWidgetUpdateByIdProps](/docs/public-api/interfaces/RequestWidgetUpdateByIdProps)

src/api/request-widget-update-by-id.tsx

@@ -0,0 +1,53 @@
+import { AndroidWidget } from '../AndroidWidget';
+import { buildWidgetTree } from './build-widget-tree';
+import type { WidgetInfo } from './types';
+
+export interface RequestWidgetUpdateByIdProps {
+ /**
+ * The name of the widget to update
+ */
+ widgetName: string;
+ /**
+ * The id of the widget to update
+ */
+ widgetId: number;
+ /**
+ * Callback function that will be called with {@link WidgetInfo}
+ * It should return the JSX of the updated widget
+ */
+ renderWidget: (props: WidgetInfo) => Promise<JSX.Element> | JSX.Element;
+ /**
+ * Callback function that will be called if widget does not exist
+ * It can be used to clean up background tasks that update the widget periodically
+ */
+ widgetNotFound?: () => void;
+}
+
+/**
+ * Request widget update for a given widget name and id
+ * A callback will be called for the widget with the given id
+ *
+ * @param param0 {@link RequestWidgetUpdateByIdProps}
+ */
+export async function requestWidgetUpdateById({
+ widgetName,
+ widgetId,
+ renderWidget,
+ widgetNotFound,
+}: RequestWidgetUpdateByIdProps): Promise<void> {
+ const widgetsInfo = await AndroidWidget.getWidgetInfo(widgetName);
+ const widgetInfo = widgetsInfo.find((widget) => widget.widgetId === widgetId);
+
+ if (!widgetInfo) {
+ widgetNotFound?.();
+ return;
+ }
+
+ const widgetComponent = await renderWidget(widgetInfo);
+
+ AndroidWidget.drawWidgetById(
+ buildWidgetTree(widgetComponent),
+ widgetName,
+ widgetInfo.widgetId
+ );
+}

src/index.ts

@@ -3,6 +3,7 @@ export * from './api/get-widget-info';
 export * from './api/register-widget-configuration-screen';
 export * from './api/register-widget-task-handler';
 export * from './api/request-widget-update';
+export * from './api/request-widget-update-by-id';
 export * from './api/types';
 export * from './config-plugin.type';
 export * from './widgets/FlexWidget';