toast

README

Toast

A go package for Windows 10 toast notifications.

As seen in jacobmarshall/pokevision-cli.

CLI

As well as using go-toast within your Go projects, you can also utilise the CLI - for any of your projects.

Download 64bit or 32bit

C:\Users\Example\Downloads\toast64.exe \
  --app-id "Example App" \
  --title "Hello World" \
  --message "Lorem ipsum dolor sit amet, consectetur adipiscing elit." \
  --icon "C:\Users\Example\Pictures\icon.png" \
  --audio "default" --loop \
  --duration "long" \
  --activation-arg "https://google.com" \
  --action "Open maps" --action-arg "bingmaps:?q=sushi" \
  --action "Open browser" --action-arg "http://..."

Example

package main

import (
    "log"

    "github.com/DeltaLaboratory/toast"
)

func main() {
    notification := toast.Notification{
        AppID: "Example App",
        Title: "My notification",
        Message: "Some message about how important something is...",
        Icon: "go.png", // This file must exist (remove this line if it doesn't)
        Actions: []toast.Action{
            {"protocol", "I'm a button", ""},
            {"protocol", "Me too!", ""},
        },
    }
    err := notification.Push()
    if err != nil {
        log.Fatalln(err)
    }
}

Screenshots

Documentation

Index

• Constants
• Variables
• type Action
• type Notification
  • func (n *Notification) Push() error
• type ToastAudio
  • func Audio(name string) (ToastAudio, error)
• type ToastDuration
  • func Duration(name string) (ToastDuration, error)

Constants

const (
	Default        ToastAudio = "ms-winsoundevent:Notification.Default"
	IM                        = "ms-winsoundevent:Notification.IM"
	Mail                      = "ms-winsoundevent:Notification.Mail"
	Reminder                  = "ms-winsoundevent:Notification.Reminder"
	SMS                       = "ms-winsoundevent:Notification.SMS"
	LoopingAlarm              = "ms-winsoundevent:Notification.Looping.Alarm"
	LoopingAlarm2             = "ms-winsoundevent:Notification.Looping.Alarm2"
	LoopingAlarm3             = "ms-winsoundevent:Notification.Looping.Alarm3"
	LoopingAlarm4             = "ms-winsoundevent:Notification.Looping.Alarm4"
	LoopingAlarm5             = "ms-winsoundevent:Notification.Looping.Alarm5"
	LoopingAlarm6             = "ms-winsoundevent:Notification.Looping.Alarm6"
	LoopingAlarm7             = "ms-winsoundevent:Notification.Looping.Alarm7"
	LoopingAlarm8             = "ms-winsoundevent:Notification.Looping.Alarm8"
	LoopingAlarm9             = "ms-winsoundevent:Notification.Looping.Alarm9"
	LoopingAlarm10            = "ms-winsoundevent:Notification.Looping.Alarm10"
	LoopingCall               = "ms-winsoundevent:Notification.Looping.Call"
	LoopingCall2              = "ms-winsoundevent:Notification.Looping.Call2"
	LoopingCall3              = "ms-winsoundevent:Notification.Looping.Call3"
	LoopingCall4              = "ms-winsoundevent:Notification.Looping.Call4"
	LoopingCall5              = "ms-winsoundevent:Notification.Looping.Call5"
	LoopingCall6              = "ms-winsoundevent:Notification.Looping.Call6"
	LoopingCall7              = "ms-winsoundevent:Notification.Looping.Call7"
	LoopingCall8              = "ms-winsoundevent:Notification.Looping.Call8"
	LoopingCall9              = "ms-winsoundevent:Notification.Looping.Call9"
	LoopingCall10             = "ms-winsoundevent:Notification.Looping.Call10"
	Silent                    = "silent"
)

Variables

var (
	ErrorInvalidAudio    = errors.New("toast: invalid audio")
	ErrorInvalidDuration = errors.New("toast: invalid duration")
)

Types

type Action

type Action struct {
	Type      string
	Label     string
	Arguments string
}

Action

Defines an actionable button. See https://msdn.microsoft.com/en-us/windows/uwp/controls-and-patterns/tiles-and-notifications-adaptive-interactive-toasts for more info.

Only protocol type action buttons are actually useful, as there's no way of receiving feedback from the user's choice. Examples of protocol type action buttons include: "bingmaps:?q=sushi" to open up Windows 10's maps app with a pre-populated search field set to "sushi".

toast.Action{"protocol", "Open Maps", "bingmaps:?q=sushi"}

type Notification

type Notification struct {
	// The name of your app. This value shows up in Windows 10's Action Centre, so make it
	// something readable for your users. It can contain spaces, however special characters
	// (eg. é) are not supported.
	AppID string

	// The main title/heading for the toast notification.
	Title string

	// The single/multi line message to display for the toast notification.
	Message string

	// An optional path to an image on the OS to display to the left of the title & message.
	Icon string

	// The type of notification level action (like toast.Action)
	ActivationType string

	// The activation/action arguments (invoked when the user clicks the notification)
	ActivationArguments string

	// Optional action buttons to display below the notification title & message.
	Actions []Action

	// The audio to play when displaying the toast
	Audio ToastAudio

	// Whether to loop the audio (default false)
	Loop bool

	// How long the toast should show up for (short/long)
	Duration ToastDuration
}

Notification

The toast notification data. The following fields are strongly recommended;

• AppID
• Title

If no toastAudio is provided, then the toast notification will be silent. You can set the toast to have a default audio by setting "Audio" to "toast.Default", or if your go app takes user-provided input for audio, call the "toast.Audio(name)" func.

The AppID is shown beneath the toast message (in certain cases), and above the notification within the Action Center - and is used to group your notifications together. It is recommended that you provide a "pretty" name for your app, and not something like "com.example.MyApp".

If no Title is provided, but a Message is, the message will display as the toast notification's title - which is a slightly different font style (heavier).

The Icon should be an absolute path to the icon (as the toast is invoked from a temporary path on the user's system, not the working directory).

If you would like the toast to call an external process/open a webpage, then you can set ActivationArguments to the uri you would like to trigger when the toast is clicked. For example: "https://google.com" would open the Google homepage when the user clicks the toast notification. By default, clicking the toast just hides/dismisses it.

The following would show a notification to the user letting them know they received an email, and opens gmail.com when they click the notification. It also makes the Windows 10 "mail" sound effect.

toast := toast.Notification{
    AppID:               "Google Mail",
    Title:               email.Subject,
    Message:             email.Preview,
    Icon:                "C:/Program Files/Google Mail/icons/logo.png",
    ActivationArguments: "https://gmail.com",
    Audio:               toast.Mail,
}

err := toast.Push()

func (*Notification) Push

func (n *Notification) Push() error

Push builds the Windows PowerShell script & invokes it, causing the toast to display.

Note: Running the PowerShell script is by far the slowest process here, and can take a few seconds in some cases.

notification := toast.Notification{
    AppID: "Example App",
    Title: "My notification",
    Message: "Some message about how important something is...",
    Icon: "go.png",
    Actions: []toast.Action{
        {"protocol", "I'm a button", ""},
        {"protocol", "Me too!", ""},
    },
}
err := notification.Push()
if err != nil {
    log.Fatalln(err)
}

type ToastAudio

type ToastAudio string

func Audio

func Audio(name string) (ToastAudio, error)

Audio returns a toastAudio given a user-provided input (useful for cli apps).

If the "name" doesn't match, then the default toastAudio is returned, along with ErrorInvalidAudio.

The following names are valid;

• default
• im
• mail
• reminder
• sms
• loopingalarm
• loopimgalarm[2-10]
• loopingcall
• loopingcall[2-10]
• silent

Handle the error appropriately according to how your app should work.

type ToastDuration

type ToastDuration string

const (
	Short ToastDuration = "short"
	Long                = "long"
)

func Duration

func Duration(name string) (ToastDuration, error)

Duration returns a toastDuration given a user-provided input (useful for cli apps).

The default duration is short. If the "name" doesn't match, then the default toastDuration is returned, along with ErrorInvalidDuration. Most of the time "short" is the most appropriate for a toast notification, and Microsoft recommends not using "long", but it can be useful for important dialogs or looping sound toasts.

The following names are valid;

• short
• long

Handle the error appropriately according to how your app should work.