BangleApps/apps/messages/README.md

Messages library

This library handles the passing of messages. It can storess a list of messages and allows them to be retrieved by other apps.

Example

Assuming you are using GadgetBridge and "overlay notifications":

1. Gadgetbridge sends an event to your watch for an incoming message
2. The android app parses the message, and calls require("messages").pushMessage({/** the message */})
3. require("messages") calls Bangle.emit("message", "text", {/** the message */})
4. Overlay Notifications shows the message in an overlay, and marks it as handled
5. The default UI app (Message UI, messagegui) sees the event is marked as handled, so does nothing.
6. The default widget (widmessages) does nothing with handled, and shows a notification icon.
7. You tap the notification, in order to open the full GUI: Overlay Notifications calls require("messages").openGUI({/** the message */})
8. openGUI calls require("messagegui").open(/** copy of the message */).
9. The messagegui library loads the Message UI app.

Events

When a new message arrives, a "message" event is emitted, you can listen for it like this:

myMessageListener = Bangle.on("message", (type, message)=>{
  if (message.handled) return; // another app already handled this message
  // <type> is one of "text", "call", "alarm", "map", or "music"
  // see `messages/lib.js` for possible <message> formats
  // message.t could be "add", "modify" or "remove"
  E.showMessage(`${message.title}\n${message.body}`, `${message.t} ${type} message`);
  // You can prevent the default `message` app from loading by setting `message.handled = true`:
  message.handled = true;
});

Apps can launch the full GUI by calling require("messages").openGUI(), if you want to write your own GUI, it should include boot code that listens for "messageGUI" events:

Bangle.on("messageGUI", message=>{
  if (message.handled) return; // another app already opened it's GUI
  message.handled = true; // prevent other apps form launching
  Bangle.load("my_message_gui.app.js");
})

Requests

Please file any issues on https://github.com/espruino/BangleApps/issues/new?title=[messages]%20library

Creator

Gordon Williams

Contributors

Jeroen Peters

Attributions

Icons used in this app are from https://icons8.com