From 8ac0369510210e2c4440d3570497362cc9a598d5 Mon Sep 17 00:00:00 2001 From: Joel Fischer Date: Mon, 22 Jul 2019 16:04:23 -0400 Subject: [PATCH] Accepted Revisions for SDL-0242 Alert Style Subtle (#785) * Accepted Revisions for SDL-0242 Alert Style Subtle * Review fixes * Update proposals/0242-alert-style-subtle.md Remove one comma. ONE COMMA @theresalech. Co-Authored-By: theresalech --- proposals/0242-alert-style-subtle.md | 239 ++++++++++++++++++--------- 1 file changed, 159 insertions(+), 80 deletions(-) diff --git a/proposals/0242-alert-style-subtle.md b/proposals/0242-alert-style-subtle.md index fd15629ae9..1c7cb7ebed 100644 --- a/proposals/0242-alert-style-subtle.md +++ b/proposals/0242-alert-style-subtle.md @@ -6,121 +6,177 @@ * Impacted Platforms: [Core / iOS / Java Suite / HMI / RPC] ## Introduction -This feature adds a new style of alert: the "subtle" alert, which does not take over the entire screen. The current alerts are moved to a style called "prominent." +This feature adds the `SubtleAlert` RPC, which presents a style of alert: the "subtle" alert. This is a "notification style" alert that does not take over the entire screen. ## Motivation Competitive systems in this space often have "notification" style alerts, and user expectations are often set by mobile devices, which have notification alerts that don't take over the screen. To meet user and developer expectations, we should provide both prominent (modal) and subtle (notification) style alerts. -Places where subtle alerts may be useful include messaging apps that notify the user of a new message, a VOIP app notifying the user of an incoming call, or a navigation app notifying the user of an upcoming accident. These should have the ability to be presented outside of the current screen-takeover method. +Subtle Alerts would be especially useful when the app is in the background. Places where subtle alerts may be useful include messaging apps that notify the user of a new message, a VOIP app notifying the user of an incoming call, or a navigation app notifying the user of an upcoming accident. These should have the ability to be presented outside of the current screen-takeover method. ## Proposed solution -The proposed solution is to create a new `AlertStyle` enum that can be sent along with the `Alert` RPC. +The proposed solution is to create a new RPC `SubtleAlert` that can be sent by developers to show a less prominent kind of Alert. -### Functionality -Functionally, this would be identical to the prominent alert style with the following exceptions: +### MOBILE_API Changes -1. It may support a different number of text lines or soft buttons. -2. `progressIndicator` parameter should do nothing. -3. Touching (or otherwise selecting) the alert should open the app. -4. Touching outside of the subtle alert should close the alert. +#### Capabilities Updates +```xml + + + + The first line of the subtle alert text field; applies to `SubtleAlert` `alertText1` + + + The second line of the subtle alert text field; applies to `SubtleAlert` `alertText2` + + + A text field in the soft button of a subtle alert; applies to `SubtleAlert` `softButtons` + + -### MOBILE_API and HMI_API Changes + + + + The image of the subtle alert; applies to `SubtleAlert` `alertImage` + + +``` -#### Capabilities +#### Subtle Alert ```xml - - - - - An array of available alert styles. If this parameter is not provided, only the `PROMINENT` style is assumed to be available. + + Shows an alert which typically consists of text-to-speech message and text on the display. At least either alertText1, alertText2 or TTSChunks need to be provided. + + + The first line of the alert text field + + + + The second line of the alert text field + + + + + Image to be displayed for the corresponding alert. See Image. + If omitted, no (or the default if applicable) icon should be displayed. + - + + + + An array of text chunks of type TTSChunk. See TTSChunk. + The array must have at least one item. + + + + + + Timeout in milliseconds. + Typical timeouts are 3-5 seconds. + If omitted, timeout is set to 5s. + + + + + + App defined SoftButtons. + If omitted on supported displays, the displayed alert shall not have any SoftButtons. + + + + + + An ID for this specific alert to allow cancellation through the `CancelInteraction` RPC. + + + + + + + Sent when the alert itself is touched (outside of a soft button). Touching (or otherwise selecting) the alert should open the app before sending this notification. + + ``` -Alternatively, if this proposal is implemented in a release simultaneously with, or after, [SDL-0216 Widget Support](https://github.com/smartdevicelink/sdl_evolution/blob/master/proposals/0216-widget-support.md), then the `alertStylesAvailable` parameter should be placed within the new `WindowCapabilities` struct, and not the `DisplayCapabilities` struct above. See Alternative 2. +#### Cancel Interaction +```xml + + + + + The ID of the type of interaction the developer wants to dismiss. Only values 10 (PerformInteractionID), 12 (AlertID), 25 (ScrollableMessageID), 26 (SliderID), and XX (SubtleAlertID) are permitted. + + + +``` -#### Alert +### HMI_API Changes ```xml - - How the alert is laid out on screen - - A modal alert style that requires interaction, blocking interaction with any other part of the display. - - - A new alert style like a notification banner that doesn't take over the entire display and allows interaction with the current app. e.g. A navigation alert that lets the user know of an upcoming blockage on the road and asking the user if they wish to reroute. - - + + Request from SDL to show an alert message on the display. + + Array of lines of alert text fields. See TextFieldStruct. Uses subtleAlertText1, subtleAlertText2. + + + Timeout in milliseconds. + + + App defined SoftButtons + + + Defines if only UI or BOTH portions of the Alert request are being sent to HMI Side + + + ID of application requested this RPC. + + - - Shows an alert which typically consists of text-to-speech message and text on the display. At least either alertText1, alertText2 or TTSChunks need to be provided. - - ... - - - Sets the layout of the alert screen. + + + Amount of time (in milliseconds) that SDL must wait before resending an alert. Must be provided if another system event or overlay currently has a higher priority than this alert. + + + + Sent when the alert itself is touched (outside of a soft button). Touching (or otherwise selecting) the alert should open the app before sending this notification. + + ``` -Also note that if [Cancel Interaction](https://github.com/smartdevicelink/sdl_evolution/blob/master/proposals/0184-cancel-interaction.md) is implemented, this would be affected as well. +* Changes may need to be made to the above functions for `CancelInteraction` changes. +* Identical changes will also need to be made to `HMI_API` `TextFieldName` and `ImageFieldName` enums as in the `MOBILE_API` changes above. -### Mockup +### Example Mockup ![Subtle Alert Mockup](../assets/proposals/0242-alert-style-subtle/subtle-alert-mockup.png) +### Notes +* In most other ways, the subtle alert should function similarly to an `Alert`. Responses should be sent at the same time that current `Alert` responses are sent, for example. +* Touching outside of the subtle alert should close the alert. +* Touching (or otherwise selecting) the alert should open the app before sending the `OnSubtleAlertPressed` notification. +* The `softButtonImage` `ImageField` also affect the `SubtleAlert` soft buttons. + ## Potential downsides -Because this is an addition to the `Alert` RPC and not a new separate RPC, policies cannot allow an app to send a "subtle" notification while preventing them from sending a "prominent" notification. This is a significant downside and almost caused the author to change the approach. The author ultimately determined that adding a new non-mandatory parameter was better due to the API similarity, but if the SDLC decides to use Alternative 1 below, that would be acceptable by the author. +Because this is a new RPC and not an addition to `Alert`, this increases the API surface of the `MOBILE_API` and `HMI_API`. ## Impact on existing code This would be a minor version change. ## Alternatives considered -### Alternative 1: Separate RPC -Using a separate RPC allows us to (1) control this alert style separately from `Alert` in policies, and (2) to provide a callback for when the notification is touched. This would permit better control for the app developers than simply opening the app. +### Alternative 1: Within the Same RPC +The original version of this proposal re-used the `Alert` RPC. It was determined that it would be better to make a new RPC in order to enforce policies separately. +#### Capabilities ```xml - - Shows an alert which typically consists of text-to-speech message and text on the display. At least either alertText1, alertText2 or TTSChunks need to be provided. - - - The first line of the alert text field - - - - The second line of the alert text field - - - - - An array of text chunks of type TTSChunk. See TTSChunk. - The array must have at least one item. - - - - - - Timeout in milliseconds. - Typical timeouts are 3-5 seconds. - If omitted, timeout is set to 5s. - - - - - - App defined SoftButtons. - If omitted on supported displays, the displayed alert shall not have any SoftButtons. - - - - - - -``` + + -If [Cancel Interaction](https://github.com/smartdevicelink/sdl_evolution/blob/master/proposals/0184-cancel-interaction.md) is implemented, this would need to be modified to work with that as well. + + An array of available alert styles. If this parameter is not provided, only the `PROMINENT` style is assumed to be available. + + -### Alternative 2: Using `WindowCapabilities` instead of `DisplayCapabilities` -```xml + @@ -128,3 +184,26 @@ If [Cancel Interaction](https://github.com/smartdevicelink/sdl_evolution/blob/ma ``` + +#### Alert Changes +```xml + + How the alert is laid out on screen + + A modal alert style that requires interaction, blocking interaction with any other part of the display. + + + A new alert style like a notification banner that doesn't take over the entire display and allows interaction with the current app. e.g. A navigation alert that lets the user know of an upcoming blockage on the road and asking the user if they wish to reroute. + + + + + Shows an alert which typically consists of text-to-speech message and text on the display. At least either alertText1, alertText2 or TTSChunks need to be provided. + + ... + + + Sets the layout of the alert screen. + + +```