Snooze/dismiss support in toast button builders (#3694)

msftbot[bot] · web-flow · commit 10fbbad019d8 · 2021-02-09T19:50:53.000Z
## Fixes #3614   The toast button builders we added in 7.0 so far didn't support snooze/dismiss activation, it makes sense to have a single way of constructing a button regardless of the activation type. Additionally, this helps us converge on using `Uri` types for images rather than `string` as mentioned in issue #3614. ## PR Type What kind of change does this PR introduce?   - Feature       ## What is the current behavior?  Had to use a separate button type previously... ```csharp new ToastContentBuilder() .AddButton(new ToastButton() .SetContent("Delete") .SetImageUri(new Uri("delete.png")) .AddArgument("action", "delete") .SetBackgroundActivation() .AddButton(new ToastButtonDismiss() { ImageUri = "dismiss.png" }); ``` ## What is the new behavior?  Can use the same button builder, and the image consistently uses `Uri` type. ```csharp new ToastContentBuilder() .AddButton(new ToastButton() .SetContent("Delete") .SetImageUri(new Uri("delete.png")) .AddArgument("action", "delete") .SetBackgroundActivation() .AddButton(new ToastButton() .SetImageUri(new Uri("dismiss.png")) .SetDismissActivation()); ``` ## PR Checklist Please check if your PR fulfills the following requirements: - [x] Tested code with current [supported SDKs](../readme.md#supported) - [x] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link:  - [x] Sample in sample app has been added / updated (for bug fixes / features) - [x] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets) - [x] New major technical changes in the toolkit have or will be added to the [Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) e.g. build changes, source generators, testing infrastructure, sample creation changes, etc... - [x] Tests for the changes have been added (for bug fixes / features) (if applicable) - [x] Header has been added to all new source files (run *build/UpdateHeaders.bat*) - [x] Contains **NO** breaking changes  ## Other information
diff --git a/Microsoft.Toolkit.Uwp.Notifications/Toasts/Builder/ToastContentBuilder.Actions.cs b/Microsoft.Toolkit.Uwp.Notifications/Toasts/Builder/ToastContentBuilder.Actions.cs
@@ -112,7 +112,7 @@ public ToastContentBuilder AddButton(string content, ToastActivationType activat
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
         public ToastContentBuilder AddButton(IToastButton button)
         {
-            if (button is ToastButton toastButton && toastButton.Content == null)
+            if (button is ToastButton toastButton && toastButton.Content == null && toastButton.NeedsContent())
             {
                 throw new InvalidOperationException("Content is required on button.");
             }
diff --git a/Microsoft.Toolkit.Uwp.Notifications/Toasts/ToastButton.cs b/Microsoft.Toolkit.Uwp.Notifications/Toasts/ToastButton.cs
@@ -20,6 +20,17 @@ public sealed class ToastButton :
 
         private bool _usingCustomArguments;
 
+        private bool _usingSnoozeActivation;
+        private string _snoozeSelectionBoxId;
+
+        private bool _usingDismissActivation;
+
+        internal bool NeedsContent()
+        {
+            // Snooze/dismiss buttons don't need content (the system will auto-add the localized strings).
+            return !_usingDismissActivation && !_usingSnoozeActivation;
+        }
+
         /// <summary>
         /// Initializes a new instance of the <see cref="ToastButton"/> class.
         /// </summary>
@@ -213,6 +224,11 @@ private ToastButton AddArgumentHelper(string key, string value)
                 throw new InvalidOperationException("You cannot use the AddArgument methods when using protocol activation.");
             }
 
+            if (_usingDismissActivation || _usingSnoozeActivation)
+            {
+                throw new InvalidOperationException("You cannot use the AddArgument methods when using dismiss or snooze activation.");
+            }
+
             bool alreadyExists = _arguments.ContainsKey(key);
 
             _arguments[key] = value;
@@ -314,6 +330,48 @@ public ToastButton SetAfterActivationBehavior(ToastAfterActivationBehavior after
             return this;
         }
 
+        /// <summary>
+        /// Configures the button to use system snooze activation when the button is clicked, using the default system snooze time.
+        /// </summary>
+        /// <returns>The current instance of <see cref="ToastButton"/></returns>
+        public ToastButton SetSnoozeActivation()
+        {
+            return SetSnoozeActivation(null);
+        }
+
+        /// <summary>
+        /// Configures the button to use system snooze activation when the button is clicked, with a snooze time defined by the specified selection box.
+        /// </summary>
+        /// <param name="selectionBoxId">The ID of an existing <see cref="ToastSelectionBox"/> which allows the user to pick a custom snooze time. The ID's of the <see cref="ToastSelectionBoxItem"/>s inside the selection box must represent the snooze interval in minutes. For example, if the user selects an item that has an ID of "120", then the notification will be snoozed for 2 hours. When the user clicks this button, if you specified a SelectionBoxId, the system will parse the ID of the selected item and snooze by that amount of minutes.</param>
+        /// <returns>The current instance of <see cref="ToastButton"/></returns>
+        public ToastButton SetSnoozeActivation(string selectionBoxId)
+        {
+            if (_arguments.Count > 0)
+            {
+                throw new InvalidOperationException($"{nameof(SetSnoozeActivation)} cannot be used in conjunction with ${nameof(AddArgument)}.");
+            }
+
+            _usingSnoozeActivation = true;
+            _snoozeSelectionBoxId = selectionBoxId;
+
+            return this;
+        }
+
+        /// <summary>
+        /// Configures the button to use system dismiss activation when the button is clicked (the toast will simply dismiss rather than activating).
+        /// </summary>
+        /// <returns>The current instance of <see cref="ToastButton"/></returns>
+        public ToastButton SetDismissActivation()
+        {
+            if (_arguments.Count > 0)
+            {
+                throw new InvalidOperationException($"{nameof(SetDismissActivation)} cannot be used in conjunction with ${nameof(AddArgument)}.");
+            }
+
+            _usingDismissActivation = true;
+            return this;
+        }
+
         /// <summary>
         /// Sets an identifier used in telemetry to identify your category of action. This should be something like "Delete", "Reply", or "Archive". In the upcoming toast telemetry dashboard in Dev Center, you will be able to view how frequently your actions are being clicked.
         /// </summary>
@@ -349,7 +407,7 @@ public ToastButton SetTextBoxId(string textBoxId)
 
         internal bool CanAddArguments()
         {
-            return ActivationType != ToastActivationType.Protocol && !_usingCustomArguments;
+            return ActivationType != ToastActivationType.Protocol && !_usingCustomArguments && !_usingDismissActivation && !_usingSnoozeActivation;
         }
 
         internal bool ContainsArgument(string key)
@@ -362,13 +420,44 @@ internal Element_ToastAction ConvertToElement()
             var el = new Element_ToastAction()
             {
                 Content = Content,
-                Arguments = Arguments,
-                ActivationType = Element_Toast.ConvertActivationType(ActivationType),
                 ImageUri = ImageUri,
                 InputId = TextBoxId,
                 HintActionId = HintActionId
             };
 
+            if (_usingSnoozeActivation)
+            {
+                el.ActivationType = Element_ToastActivationType.System;
+                el.Arguments = "snooze";
+
+                if (_snoozeSelectionBoxId != null)
+                {
+                    el.InputId = _snoozeSelectionBoxId;
+                }
+
+                // Content needs to be specified as empty for auto-generated Snooze content
+                if (el.Content == null)
+                {
+                    el.Content = string.Empty;
+                }
+            }
+            else if (_usingDismissActivation)
+            {
+                el.ActivationType = Element_ToastActivationType.System;
+                el.Arguments = "dismiss";
+
+                // Content needs to be specified as empty for auto-generated Dismiss content
+                if (el.Content == null)
+                {
+                    el.Content = string.Empty;
+                }
+            }
+            else
+            {
+                el.ActivationType = Element_Toast.ConvertActivationType(ActivationType);
+                el.Arguments = Arguments;
+            }
+
             ActivationOptions?.PopulateElement(el);
 
             return el;
diff --git a/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Toast/ToastCode.bind b/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Toast/ToastCode.bind
@@ -13,7 +13,9 @@ private void PopToast()
                                          ("60", "1 hour"),        
                                          ("240", "4 hours"),        
                                          ("1440", "1 day"))        
-        .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })        
-        .AddButton(new ToastButtonDismiss())
+        .AddButton(new ToastButton()
+            .SetSnoozeActivation("snoozeTime"))        
+        .AddButton(new ToastButton()
+            .SetDismissActivation())
         .Show();
 }
diff --git a/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Toast/ToastPage.xaml.cs b/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Toast/ToastPage.xaml.cs
@@ -40,8 +40,10 @@ public static ToastContent GenerateToastContent()
                                                  ("60", "1 hour"),
                                                  ("240", "4 hours"),
                                                  ("1440", "1 day"))
-                .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })
-                .AddButton(new ToastButtonDismiss());
+                .AddButton(new ToastButton()
+                    .SetSnoozeActivation("snoozeTime"))
+                .AddButton(new ToastButton()
+                    .SetDismissActivation());
 
             return builder.Content;
         }
diff --git a/UnitTests/UnitTests.Notifications.Shared/TestToastContentBuilder.cs b/UnitTests/UnitTests.Notifications.Shared/TestToastContentBuilder.cs
@@ -405,6 +405,36 @@ public void ToastButtonBuilders_InvalidProtocolAfterArguments_ReturnSelf()
                 .SetProtocolActivation(new Uri("https://msn.com"));
         }
 
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidDismissAfterArguments_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("View")
+                .AddArgument("action", "view")
+                .SetDismissActivation();
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidSnoozeAfterArguments_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("View")
+                .AddArgument("action", "view")
+                .SetSnoozeActivation();
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidSnoozeWithIdAfterArguments_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("View")
+                .AddArgument("action", "view")
+                .SetSnoozeActivation("snoozeId");
+        }
+
         [TestMethod]
         [ExpectedException(typeof(InvalidOperationException))]
         public void ToastButtonBuilders_InvalidArgumentsAfterProtocol_ReturnSelf()
@@ -424,6 +454,36 @@ public void ToastButtonBuilders_InvalidArgumentsAfterCustomArguments_ReturnSelf(
             button.AddArgument("action", "view");
         }
 
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidArgumentsAfterSnooze_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("Later")
+                .SetSnoozeActivation()
+                .AddArgument("action", "later");
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidArgumentsAfterSnoozeWithId_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("Later")
+                .SetSnoozeActivation("myId")
+                .AddArgument("action", "later");
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(InvalidOperationException))]
+        public void ToastButtonBuilders_InvalidArgumentsAfterDismissActivation_ReturnSelf()
+        {
+            new ToastButton()
+                .SetContent("Later")
+                .SetDismissActivation()
+                .AddArgument("action", "later");
+        }
+
         [TestMethod]
         public void SetToastDurationTest_WithCustomToastDuration_ReturnSelfWithCustomToastDurationSet()
         {
diff --git a/UnitTests/UnitTests.Notifications.Shared/Test_Toast_Xml.cs b/UnitTests/UnitTests.Notifications.Shared/Test_Toast_Xml.cs
@@ -977,6 +977,37 @@ public void Test_Toast_Xml_Actions_SixTotal()
             Assert.Fail("Exception should have been thrown, only 5 actions are allowed.");
         }
 
+        [TestMethod]
+        public void Test_Toast_Xml_Actions_SnoozeAndDismissUsingBuilders()
+        {
+            AssertActionsPayload("<actions><action content='' activationType='system' arguments='snooze'/><action content='' activationType='system' arguments='dismiss'/><action content='Hide' activationType='system' arguments='dismiss'/><action content='Later' activationType='system' arguments='snooze'/><action content='Remind me' activationType='system' arguments='snooze' hint-inputId='snoozePicker'/></actions>", new ToastActionsCustom()
+            {
+                Buttons =
+                {
+                    // Allowing system to auto-generate text content
+                    new ToastButton()
+                        .SetSnoozeActivation(),
+
+                    // Allowing system to auto-generate text content
+                    new ToastButton()
+                        .SetDismissActivation(),
+
+                    // Specifying specific content
+                    new ToastButton()
+                        .SetContent("Hide")
+                        .SetDismissActivation(),
+
+                    new ToastButton()
+                        .SetContent("Later")
+                        .SetSnoozeActivation(),
+
+                    new ToastButton()
+                        .SetContent("Remind me")
+                        .SetSnoozeActivation("snoozePicker")
+                }
+            });
+        }
+
         [TestMethod]
         public void Test_Toast_Xml_Actions_TwoContextMenuItems()
         {

Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@ public ToastContentBuilder AddButton(string content, ToastActivationType activat`
`112`	`112`	`/// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>`
`113`	`113`	`public ToastContentBuilder AddButton(IToastButton button)`
`114`	`114`	`{`
`115`		`- if (button is ToastButton toastButton && toastButton.Content == null)`
	`115`	`+ if (button is ToastButton toastButton && toastButton.Content == null && toastButton.NeedsContent())`
`116`	`116`	`{`
`117`	`117`	`throw new InvalidOperationException("Content is required on button.");`
`118`	`118`	`}`