toast

README

Go-Toasts

A go package for Windows 10 toast notifications.

Installation

go get -t github.com/Shinyhero36/go-toasts

Example

package main

import (
	"fmt"
	"github.com/Shinyhero36/go-toasts"
)

func main() {
	notif := toast.Notification{
		AppID:   "Example App",
		Title:   "A Toast !!",
		Message: "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
	}
	if err := notif.Push(); err != nil {
		fmt.Println(err)
	}
}

More examples are available in examples.

CLI

As well as using go-toast within your Go projects, you can download utilise the CLI here.

pwd=$(pwd)

./toast.exe \
  --app-id "Example App" \
  --title "Hello World" \
  --message "Lorem ipsum dolor sit amet, consectetur adipiscing elit." \
  --icon "${pwd}\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://github.com/Shinyhero36/go-toast/"

Screenshots

Documentation

Index

• Constants
• Variables
• func Audio(name string) (toastAudio, error)
• func Duration(name string) (toastDuration, error)
• type Action
• type Input
• type Notification
  • func (n *Notification) Push() error
• type ProgressBar
• type Selection

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"
)

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

const (
	REMINDER toastScenario = "reminder"
)

Variables

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

Functions

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.

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 recommend 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.

Types

type Action

type Action struct {
	Type        string
	Label       string
	Arguments   string
	HintInputId 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 Input

type Input struct {
	Id           string
	Type         string
	DefaultInput string
	Selections   []Selection
}

type Notification

type Notification struct {
	AppID               string
	Title               string
	Message             string
	Banner              string
	Image               string
	ProgressBar         ProgressBar
	Signature           string
	Icon                string
	ActivationType      string
	Scenario            toastScenario
	ActivationArguments string
	Actions             []Action
	Input               Input
	Audio               toastAudio
	Loop                bool
	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 ProgressBar

type ProgressBar struct {
	Title               string
	Value               float32
	Status              string
	ValueStringOverride string
}

ProgressBar

Defines a progress bar. See https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/toast-progress-bar for more info.

toast.ProgressBar{"Weekly playlist", 0.6, "Downloading", "15/26 songs"}

type Selection

type Selection struct {
	Id      string
	Content string
}