💥 Change behavior of send_banner

Author: alicerunsonfedora

CHANGELOG.changes

@@ -10,6 +10,7 @@
 - Adds new CHANGELOG file to builds.
 - Updates design language of notification banners in NotificationKit.
 - Updates ScreenKit to new Candella design language.
+- Changes behavior of CAApplication.send_banner to include automatic and manual modes.
 
 [v21.02-refs/tags/21.02-beta1]
 - Initial beta release.

docs/03-candella-app.md

@@ -179,19 +179,36 @@ Send an alert with respect to the user's settings.
 
 - response (any): The response from the alert, if any. This response is also emitted as a signal.
 
-### `CAApplication.send_banner(title, supporting, callback=Return('didClickRespond'))`
+### `CAApplication.send_banner(title, supporting, callback=Return('didClickRespond'))` {label:updated}
 Send a notification banner with respect to the user's settings.
 
+The banner request can be used in one of two ways: automatic, which utilizes the CANotificationBanner class
+    to create a notification banner, and manual, which uses keyword arguments at call time to generate a
+    banner on the fly. In most cases, it is recommended to use the automatic mode since the
+    CANotificationBanner class offers more granular control over the appearance of the banner such as the
+    action button text.
+
 **Arguments**
 
-- title (str): The title of the banner.
-- supporting (str): The supporting text for the banner.
-- callback (callable): The response callback function to run when clicking the 'Respond' button.
+- mode (str): The means of sending the request. 'automatic' utilizes the [`CANotificationBanner`](./11-notifications.md#creating-modular-banners-labelnew) class to
+    create a banner, and 'manual' uses to the old style. By default, this method uses manual mode to
+    ensure backwards-compatibility with AliceOS and older Candella versions.
+
+**Keyword Arguments**
+
+- banner (CANotificationBanner): The banner object to send through this app. Required in automatic
+    mode.
+- title (str): The title of the banner. Required in manual mode.
+- supporting (str): The supporting text for the banner. Required in manual mode.
+- callback (callable): The response callback function to run when clicking the 'Respond' button. Required
+    in manual mode.
 
 **Returns**
 
-- response (any): The response from the banner request, if any. This response is also emitted as a signal.
+- response (any): The response from the banner request, if any.
 
+!!! warning "Add keyword arguments"
+    For Candella apps that use the manual mode or have supplied the contents of the banner as arguments, make sure that these are changed to keyword arguments, appropriately.
 ## Sending app signals
 
 Apps can send information to other services and even other apps. Candella apps adopt the Observable framework, which allows for signal emission.

docs/11-notifications.md

@@ -0,0 +1,43 @@
+# NotificationKit Changes
+
+Candella includes a few improvements to the NotificationKit framework that adds more functionality and modularity to creating notifications with AppKit and NotificationKit screens.
+
+## Notification banner design
+
+Banners in Candella have been moved to the right side of the screen and take up less screen space. They take on the light theme present in the rest of Candella via ScreenKit and use the same fonts. Banners have been positioned so they sit just underneath the top bar in Celeste Shell but also look great in-game.
+
+![Banners in Candella](./images/design/banner.png)
+
+## Creating modular banners {label:new}
+
+Notification banners can be generated automatically using the `CANotificationBanner` class, rather than at call time when invoking `CANotification.send_banner`. This class offers more control over the appearance of the banner and is typically easier to use than the manual mode in previous releases.
+
+To create a banner using `CANotificationBanner`, create an instance of the object with specified details:
+
+```py
+banner = CANotificationBanner(
+    "Message not sent.", "The message could not be delivered to the recipient.")
+```
+
+There are three arguments that must be supplied when creating a new banner:
+
+- message (str): The primary message of the banner.
+- details (str): Supporting text for the banner. This could further explain the main message, or provide additional context.
+- callback (any): The callback to execute when clicking on the action button. Defaults to `Return('didClickRespond')`.
+
+To invoke this banner in a banner request, pass it as a keyword argument in [`CAApplication.send_banner`](./03-candella-app.md#caapplicationsend_bannertitle-supporting-callbackreturndidclickrespond-labelupdated) and set the mode to `automatic`:
+
+```py
+response = CANotification.send_banner(mode='automatic', banner=banner)
+```
+
+### Customizing banners
+
+The following attributes are present in `CANotificationBanner` to let developers customize banners:
+
+| Attribute | Type | What it does |
+| :-------- | :--- | ------------ |
+| message | `str` | The primary message of the banner. |
+| details | `str` | The supporting text for the banner. Generally, this explains the primary message or adds additional context. |
+| callback | `callable` | A Ren'Py callback function to execute when clicking the action button on the banner. Defaults to `Return('didClickRespond')`. |
+| callback_text | `str` | The text for the action button. Defaults to `"Respond"`. |

docs/images/design/banner.png

@@ -18,9 +18,11 @@ init 5 python:
             return True
 
         def applicationWillLaunch(self):
-            self.send_banner(
+            banner = CANotificationBanner(
                 "Messages app functionality not implemented.",
                 "You will still be able to receive message notifications from characters in-game."
             )
+            banner.callback_text = "Dismiss"
+            self.send_banner("automatic", banner=banner)
 
     messages = ASMessages()

game/System/Applications/Messages.aosapp/Messages.rpy

@@ -175,18 +175,40 @@ init python:
             self.application_did_terminate()
             self.emit_signal("application_terminated")
 
-        def send_banner(self, title, supporting, callback=Return('didClickRespond')):
+        def send_banner(self, mode='manual', **kwargs):
             """Send a notification banner with respect to the user's settings.
 
+            The banner request can be used in one of two ways: automatic, which utilizes the CANotificationBanner class
+                to create a notification banner, and manual, which uses keyword arguments at call time to generate a
+                banner on the fly. In most cases, it is recommended to use the automatic mode since the
+                CANotificationBanner class offers more granular control over the appearance of the banner such as the
+                action button text.
+
             Arguments:
-                title (str): The title of the banner.
-                supporting (str): The supporting text for the banner.
-                callback (callable): The response callback function to run when clicking the 'Respond' button.
+                mode (str): The means of sending the request. 'automatic' utilizes the CANotificationBanner class to
+                    create a banner, and 'manual' uses to the old style. By default, this method uses manual mode to
+                    ensure backwards-compatibility with AliceOS and older Candella versions.
+
+            Keyword Arguments:
+                banner (CANotificationBanner): The banner object to send through this app. Required in automatic
+                    mode.
+                title (str): The title of the banner. Required in manual mode.
+                supporting (str): The supporting text for the banner. Required in manual mode.
+                callback (callable): The response callback function to run when clicking the 'Respond' button. Required
+                    in manual mode.
 
             Returns:
                 response (any): The response from the banner request, if any.
             """
-            response = self.application_will_request_notification(title, supporting, response_callback=callback)
+
+            if mode not in ["automatic", "manual"]:
+                raise TypeError("mode must be 'automatic' or 'manual, but received %s" % (mode))
+
+            if mode == "automatic" and self.application_should_request_notification():
+                response = kwargs['banner']._send(self)
+            else:
+                response = self.application_will_request_notification(
+                    kwargs["title"], kwargs["supporting"], response_callback=kwargs["callback"])
             self.application_did_request_notification()
             self.emit_signal("banner_sent", response=response)
             return response

game/System/Frameworks/AppKit.aosframework/CAApplication.rpy

@@ -6,7 +6,7 @@
 # Copyright © 2019 ProjectAliceDev. All rights reserved.
 #
 
-init screen ASNotificationBanner(applet=None, message, withDetails, responseCallback=Return('didClickRespond')):
+init screen ASNotificationBanner(applet=None, message, withDetails, r_text="Respond", responseCallback=Return('didClickRespond')):
     tag ASNotificationBanner
     zorder 100
     style_prefix "ASNotificationBanner"
@@ -35,7 +35,7 @@ init screen ASNotificationBanner(applet=None, message, withDetails, responseCall
                     add _app_icon
                     text "[_app_name]":
                         style "ASNotificationBannerSource"
-                textbutton _("Respond") action [Hide("ASNotificationBanner"), responseCallback]:
+                textbutton _("[r_text]") action [Hide("ASNotificationBanner"), responseCallback]:
                     style "ASNotificationBannerButton"
                     xalign 1.0
 

game/System/Frameworks/NotificationKit.aosframework/ASNotificationBanner.rpy

@@ -0,0 +1,37 @@
+#
+# CSNotificationBanner.rpy
+# Candella
+#
+# Created by Marquis Kurt on 03/08/21.
+# Copyright © 2021 Marquis Kurt. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+#
+
+init offset = -10
+
+init python:
+    class CANotificationBanner():
+        def __init__(self, message, details, callback=Return('didClickRespond')):
+            self.message = message
+            self.details = details
+            self.callback = callback
+            self.callback_text = "Respond"
+
+
+        def __str__(self):
+            return "CANotificationBanner(%s, %s, callback='%s')" % (self.message, self.details, self.callback_text)
+
+
+        def _send(self, reference=None):
+            return renpy.invoke_in_new_context(
+                renpy.call_screen,
+                "ASNotificationBanner",
+                applet=reference,
+                message=self.message,
+                withDetails=self.details,
+                r_text=self.callback_text,
+                responseCallback=self.callback
+            )