dgwidgets

README

dg-widgets

Make widgets with embeds and reactions

Example usage

func (s *discordgo.Session, m *discordgo.Message) {
	p := dgwidgets.NewPaginator(s, m.ChannelID)

	// Add embed pages to paginator
	p.Add(&discordgo.MessageEmbed{Description: "Page one"}, 
		  &discordgo.MessageEmbed{Description: "Page two"},
		  &discordgo.MessageEmbed{Description: "Page three"})

	// Sets the footers of all added pages to their page numbers.
	p.SetPageFooters()

	// When the paginator is done listening set the colour to yellow
	p.ColourWhenDone = 0xffff

	// Stop listening for reaction events after five minutes
	p.Widget.Timeout = time.Minute * 5

	// Add a custom handler for the gun reaction.
	p.Widget.Handle("🔫", func(w *dgwidgets.Widget, r *discordgo.MessageReaction) {
		s.ChannelMessageSend(m.ChannelID, "Bang!")
	})

	p.Spawn()
}

Documentation

Index

• Constants
• Variables
• func EmbedsFromString(txt string, chunkLen int) []*discordgo.MessageEmbed
• type Index
  • func (i *Index) AddSub(s ...Sub)
  • func (i *Index) Decr()
  • func (i *Index) Incr()
  • func (i *Index) Set(in int)
• type Paginator
  • func NewPaginator(ses *discordgo.Session, channelID string) *Paginator
  • func (p *Paginator) Add(embeds ...*discordgo.MessageEmbed)
  • func (p *Paginator) Goto(index int) error
  • func (p *Paginator) NextPage() error
  • func (p *Paginator) Page() (*discordgo.MessageEmbed, error)
  • func (p *Paginator) PreviousPage() error
  • func (p *Paginator) Running() bool
  • func (p *Paginator) SetPageFooters()
  • func (p *Paginator) Spawn() error
  • func (p *Paginator) Update() error
• type Sub
• type Widget
  • func NewWidget(ses *discordgo.Session, channelID string, embed *discordgo.MessageEmbed) *Widget
  • func (w *Widget) Handle(emojiName string, handler WidgetHandler) error
  • func (w *Widget) LockToUsers(userIDs ...string) error
  • func (w *Widget) QueryInput(prompt string, userID string, timeout time.Duration) (*discordgo.Message, error)
  • func (w *Widget) RefreshTimeout() error
  • func (w *Widget) Reset(d time.Duration) error
  • func (w *Widget) Running() bool
  • func (w *Widget) Spawn() error
  • func (w *Widget) Stop() error
  • func (w *Widget) UpdateEmbed(embed *discordgo.MessageEmbed) (*discordgo.Message, error)
• type WidgetHandler

Constants

const (
	NavPlus        = "➕"
	NavPlay        = "▶"
	NavPause       = "⏸"
	NavStop        = "⏹"
	NavRight       = "➡"
	NavLeft        = "⬅"
	NavUp          = "⬆"
	NavDown        = "⬇"
	NavEnd         = "⏩"
	NavBeginning   = "⏪"
	NavNumbers     = "🔢"
	NavInformation = "ℹ"
	NavSave        = "💾"
)

emoji constants

Variables

var (
	ErrAlreadyRunning   = errors.New("err: Widget already running")
	ErrIndexOutOfBounds = errors.New("err: Index is out of bounds")
	ErrNilMessage       = errors.New("err: Message is nil")
	ErrNilEmbed         = errors.New("err: embed is nil")
	ErrNotRunning       = errors.New("err: not running")
	ErrTickerNotSet     = errors.New("err: Timeout ticker is not set")
)

error vars

Functions

func EmbedsFromString

func EmbedsFromString(txt string, chunkLen int) []*discordgo.MessageEmbed

EmbedsFromString splits a string into a slice of MessageEmbeds.

txt     : text to split
chunkLen: How long the text in each embed should be
          (if set to 0 or less, it defaults to 2048)

Types

type Index

type Index struct {
	// contains filtered or unexported fields
}

Index implements observer pattern for handling events on Paginator index change

func (*Index) AddSub

func (i *Index) AddSub(s ...Sub)

AddSub adds subscribers to the list

func (*Index) Decr

func (i *Index) Decr()

Decr decrements index and notifies all subscribers

func (*Index) Incr

func (i *Index) Incr()

Incr increments index and notifies all subscribers

func (*Index) Set

func (i *Index) Set(in int)

Set sets index at given number in and notifies all subscribers

type Paginator

type Paginator struct {
	sync.Mutex
	Pages []*discordgo.MessageEmbed
	Index Index

	// Loop back to the beginning or end when on the first or last page.
	Loop   bool
	Widget *Widget

	Ses *discordgo.Session

	DeleteMessageWhenDone   bool
	DeleteReactionsWhenDone bool
	ColourWhenDone          int
	// contains filtered or unexported fields
}

Paginator provides a method for creating a navigatable embed

func NewPaginator

func NewPaginator(ses *discordgo.Session, channelID string) *Paginator

NewPaginator returns a new Paginator

ses      : discordgo session
channelID: channelID to spawn the paginator on

func (*Paginator) Add

func (p *Paginator) Add(embeds ...*discordgo.MessageEmbed)

Add a page to the paginator

embed: embed page to add.

func (*Paginator) Goto

func (p *Paginator) Goto(index int) error

Goto jumps to the requested page index

index: The index of the page to go to

func (*Paginator) NextPage

func (p *Paginator) NextPage() error

NextPage sets the page index to the next page

func (*Paginator) Page

func (p *Paginator) Page() (*discordgo.MessageEmbed, error)

Page returns the page of the current index

func (*Paginator) PreviousPage

func (p *Paginator) PreviousPage() error

PreviousPage sets the current page index to the previous page.

func (*Paginator) Running

func (p *Paginator) Running() bool

Running returns the running status of the paginator

func (*Paginator) SetPageFooters

func (p *Paginator) SetPageFooters()

SetPageFooters sets the footer of each embed to Be its page number out of the total length of the embeds.

func (*Paginator) Spawn

func (p *Paginator) Spawn() error

Spawn spawns the paginator in channel p.ChannelID

func (*Paginator) Update

func (p *Paginator) Update() error

Update updates the message with the current state of the paginator

type Sub

type Sub interface {
	OnNotify(index int)
}

Sub is a subscriber interface

type Widget

type Widget struct {
	sync.Mutex
	Embed     *discordgo.MessageEmbed
	Message   *discordgo.Message
	Ses       *discordgo.Session
	ChannelID string
	Timeout   time.Duration
	Close     chan bool

	// Handlers binds emoji names to functions
	Handlers map[string]WidgetHandler
	// keys stores the handlers keys in the order they were added
	Keys []string

	// Delete reactions after they are added
	DeleteReactions bool
	// Refresh timer after action on a widget
	RefreshAfterAction bool
	// Only allow listed users to use reactions.
	UserWhitelist []string
	// contains filtered or unexported fields
}

Widget is a message embed with reactions for buttons. Accepts custom handlers for reactions.

func NewWidget

func NewWidget(ses *discordgo.Session, channelID string, embed *discordgo.MessageEmbed) *Widget

NewWidget returns a pointer to a Widget object

ses      : discordgo session
channelID: channelID to spawn the widget on

func (*Widget) Handle

func (w *Widget) Handle(emojiName string, handler WidgetHandler) error

Handle adds a handler for the given emoji name

emojiName: The unicode value of the emoji
handler  : handler function to call when the emoji is clicked
           func(*Widget, *discordgo.MessageReaction)

func (*Widget) LockToUsers

func (w *Widget) LockToUsers(userIDs ...string) error

LockToUsers adds defined userIDs to the UserWhitelist locking the widget to them

func (*Widget) QueryInput

func (w *Widget) QueryInput(prompt string, userID string, timeout time.Duration) (*discordgo.Message, error)

QueryInput queries the user with ID `id` for input

prompt : Question prompt
userID : UserID to get message from
timeout: How long to wait for the user's response

func (*Widget) RefreshTimeout

func (w *Widget) RefreshTimeout() error

RefreshTimeout refreshes timeout ticker by Widget's timeout. Returns ErrTickerNotSet when ticker is nil

func (*Widget) Reset

func (w *Widget) Reset(d time.Duration) error

Reset resets timeout ticker by duration. Returns ErrTickerNotSet when ticker is nil

d: New ticker duration

func (*Widget) Running

func (w *Widget) Running() bool

Running returns w.running

func (*Widget) Spawn

func (w *Widget) Spawn() error

Spawn spawns the widget in channel w.ChannelID

func (*Widget) Stop

func (w *Widget) Stop() error

Stop stops timeout ticker. Returns ErrTickerNotSet when ticker is nil

func (*Widget) UpdateEmbed

func (w *Widget) UpdateEmbed(embed *discordgo.MessageEmbed) (*discordgo.Message, error)

UpdateEmbed updates the embed object and edits the original message

embed: New embed object to replace w.Embed

type WidgetHandler

type WidgetHandler func(*Widget, *discordgo.MessageReaction)

WidgetHandler ...