WidgetManager.UpdateWidget(WidgetUpdateRequestOptions) Method

Definition

Namespace:

Microsoft.Windows.Widgets.Providers

Provides updated content for a widget to the widget host.

public:
 virtual void UpdateWidget(WidgetUpdateRequestOptions ^ widgetUpdateRequestOptions) = UpdateWidget;

void UpdateWidget(WidgetUpdateRequestOptions const& widgetUpdateRequestOptions);

public void UpdateWidget(WidgetUpdateRequestOptions widgetUpdateRequestOptions);

function updateWidget(widgetUpdateRequestOptions)

Public Sub UpdateWidget (widgetUpdateRequestOptions As WidgetUpdateRequestOptions)

Parameters

widgetUpdateRequestOptions

WidgetUpdateRequestOptions

A WidgetUpdateRequestOptions object that contains the content with which to update the widget.

Implements

UpdateWidget(WidgetUpdateRequestOptions)

Examples

The following code example demonstrates a typical usage of UpdateWidget. WidgetManager.GetWidgetInfos() is called to get the list of WidgetInfo objects for the active widgets associated with the widget provider. For each widget, a visual template and data template are generated and passed to the UpdateWidget call in a WidgetUpdateRequestOptions object.

using namespace winrt;
using namespace Microsoft::Windows::Widgets;
using namespace Microsoft::Windows::Widgets::Providers;

class WidgetManagerOperations
{
    void InitializeWidgets(hstring myWidgetId)
    {
        WidgetManager widgetManager = WidgetManager::GetDefault();
        com_array<WidgetInfo> widgetInfos = widgetManager.GetWidgetInfos();

        for (const auto& widgetInfo : widgetInfos)
        {
            if (widgetInfo.WidgetContext().IsActive())
            {
                WidgetUpdateRequestOptions options{myWidgetId};
                options.Template(LR"({
                    "type": "AdaptiveCard",
                    "version": "1.5",
                    "body": [
                        {
                            "type": "TextBlock",
                            "text": "${greeting}"
                        }
                    ]
                })");

                options.Data(LR"({
                    "greeting": "Hello"
                })");

                widgetManager.UpdateWidget(options);
            }
        }
    }
}

Remarks

Any variable not set in the WidgetUpdateRequestOptions class will not be updated. For example, if you are only interested in updating the widget's data but you want to keep the existing visual template and custom state, then by setting only the WidgetUpdateRequestOptions.Data property, the widget's data will be updated but the template and custom state will not be modified.

UpdateWidget can also be used to clear any stored value by setting an empty string for the value to be cleared. For example, if you want to clear the widget's stored custom state you can set the WidgetUpdateRequestOptions.CustomState property to an empty string, which will erase the stored custom state once UpdateWidget is called.

Calling this function to update a widget that has been deleted, a widget not associated with your app, or using a widget ID that does not exist will result in the update being ignored.