tgui

package
v0.0.0-...-3581dc8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2022 License: Apache-2.0 Imports: 8 Imported by: 0

README

tgui package

"tgui" stands for TeleGram User Interface. This package contains functionality and utilities for build or use user interfaces like menu or keyboards utilities. It is not a core package, so is NOT necessary for the correct execution of a bot.

Main features

These are the main features of this package:

  • ShowMessage is a function that will display a message to the user by modifying the previous one when called via callback or sending a new one otherwhise.

  • Menu is an interface with currently two implementation:

    PagedMenu that allows to create an inline menu that allows user to navigate between previous and next page InlineMenu that allows to create more complex and nested inline menus

all the pages of the menu are functions that allows to show contents in a dynamic way

  • Shorter type alias like EditOptions (echotron.MessageTextOptions), InlineButton (echotron.InlineKeyboardButton) or KeyButton (echotron.KeyboardButton)

  • Utilities for building and rearranging keyboards, managing options to edit messages or pages or create parrbot commands

Part of the Parr(B)ot framework.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Arrange 

func Arrange[AnyButton InlineButton | KeyButton | InlineMenuItem](columns int, fromList ...AnyButton) (keyboard [][]AnyButton)

Arrange the layout of given buttons in a given number of columns

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var buttons [][]tgui.KeyButton = tgui.Arrange(2, // Arrange following buttons in 2 columns
		tgui.KeyButton{Text: "Hello World!"},
		tgui.KeyButton{Text: "Send your location", RequestLocation: true},
		tgui.KeyButton{Text: "Send me your contact infos", RequestContact: true},
	)

	// First row
	fmt.Println(buttons[0][0].Text)
	fmt.Println(buttons[0][1].Text)

	// Second row
	fmt.Println(buttons[1][0].Text)

}

Output:

Hello World!
Send your location
Send me your contact infos

func Closer 

func Closer(trigger string, alert bool) robot.Command

Closer creates a robot.Command that will reply only at message.CALLBACK_QUERY and given trigger. When it does get called, it deletes the original message and shows a toast notification or alert containg the payload of the callback: the CallbackQuery.Data without the initial trigger

func GenInlineKeyboard 

func GenInlineKeyboard(columns int, fromList ...InlineButton) echotron.InlineKeyboardMarkup

GenInlineKeyboard allows to generate an echotron.ReplyMarkup from a list of inline buttons WARNING: Deprecated

Example 
// Arrange following buttons in 2 columns and generate an InlineKeyboardMarkup
var markup echotron.InlineKeyboardMarkup = tgui.GenInlineKeyboard(2,
	tgui.InlineButton{Text: "Click me", CallbackData: "/command"},
	tgui.InlineButton{Text: "Golang", URL: "https://go.dev"},
	tgui.InlineButton{Text: "I'm on the 2nd row", CallbackData: "/lol"},
)

// First row
fmt.Println(markup.InlineKeyboard[0][0].Text)
fmt.Println(markup.InlineKeyboard[0][1].Text)

// Second row
fmt.Println(markup.InlineKeyboard[1][0].Text)

Output:

Click me
Golang
I'm on the 2nd row

func InlineKeyboard 

func InlineKeyboard(kbd [][]InlineButton) echotron.InlineKeyboardMarkup

InlineKeyboard allows to quickly cast a matrix of inline buttons into a ReplyMarkup

Example 
var markup echotron.InlineKeyboardMarkup = tgui.InlineKeyboard([][]tgui.InlineButton{
	// First row
	{
		{Text: "Click me", CallbackData: "/command"},
		{Text: "Golang", URL: "https://go.dev"},
	},
	// Second row
	{{Text: "I'm on the 2nd row", CallbackData: "/lol"}},
})

fmt.Println(markup.InlineKeyboard[0][0].Text) 

Output:

Click me

func Keyboard 

func Keyboard(disposable bool, inputPlaceholder string, kbd [][]KeyButton) echotron.ReplyKeyboardMarkup

Keyboard allows to quickly cast a matrix of buttons into a ReplyMarkup setting some useful options. Arguments: disposable - after user tap on any button the keyboard will be removed, inputPlaceholder - a text (max 64 chars) that will apper os placeholder on input field kbd - the matrix of buttons that compose the keyboard Resulting ReplyKeyboardMarkup will also have ResizeKeyboard and Selective set to true

Example 
var (
	// After using it keyboard will be removed
	disposable bool = true
	// A text that will appear as placeholder on the message input box
	inputPlaceholder string = "Use the keyboard down below:"
	buttons                 = [][]tgui.KeyButton{
		{{Text: "Hello World!"}, {Text: "Send your location", RequestLocation: true}},
		{{Text: "Send me your contact infos", RequestContact: true}},
	}
)

var markup echotron.ReplyKeyboardMarkup = tgui.Keyboard(disposable, inputPlaceholder, buttons)
fmt.Println(markup.Keyboard[0][0].Text)
// These will be set to: true
fmt.Println(markup.ResizeKeyboard, markup.Selective)
// These will be set to the firsts 2 arguments (disposable and inputPlaceholder)
fmt.Println(markup.OneTimeKeyboard, markup.InputFieldPlaceholder)

Output:

Hello World!
true true
true Use the keyboard down below:

func KeyboardRemover 

func KeyboardRemover(globally bool) echotron.ReplyKeyboardRemove

KeyboardRemover allows to remove a previouly sent keyboard. If globally is false then kwyboard will be removed for user mentioned on the message or on the reply

Example 
var (
	globally   bool                         = true
	kbdRemover echotron.ReplyKeyboardRemove = tgui.KeyboardRemover(globally)
)

fmt.Println(kbdRemover.RemoveKeyboard) 

Output:

func NewAlert 

func NewAlert(text string, cacheTime uint16) *echotron.CallbackQueryOptions

NewAlert generates the option needed to display an alert when answering a callback using the Answer method of a CallbackQuery

Example 
var alert *echotron.CallbackQueryOptions = tgui.NewAlert("Hello World!", 69)

fmt.Println(alert.Text, alert.CacheTime, alert.ShowAlert)

Output:

Hello World! 69 true

func NewToast 

func NewToast(text string, cacheTime uint16) *echotron.CallbackQueryOptions

NewToast generates the option needed to display an toast notification when answering a callback using the Answer method of a CallbackQuery

Example 
var alert *echotron.CallbackQueryOptions = tgui.NewToast("Hello World!", 69)

fmt.Println(alert.Text, alert.CacheTime, alert.ShowAlert)

Output:

Hello World! 69 false

func Replier 

func Replier(trigger, description string, text string, opt *EditOptions) robot.Command

Replier creates a robot.Command that will use the ShowMessage function showing a new message or editing the previous in case of message.CALLBACK_QUERY

func Sender 

func Sender(msg message.Any) robot.CommandFunc

Sender creates a robot.CommandFunc that will always send the given message

func ShowMessage 

func ShowMessage(u message.Update, text string, opt *EditOptions) (sent *message.UpdateMessage, err error)

ShowMessage allows to show a text message editing the incoming in case of CALLBACK_QUERY or sending a new one otherwhise

func ToMessageOptions 

func ToMessageOptions(opt *EditOptions) *echotron.MessageOptions

ToMessageOptions transform a given EditOptions into a echotron.MessageOptions

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var (
		editOpt = &tgui.EditOptions{
			ParseMode:             "HTML",
			DisableWebPagePreview: true,
		}
		opt = tgui.ToMessageOptions(editOpt)
	)

	fmt.Println(tgui.ToMessageOptions(nil))                               

Output:

func UseMenu 

func UseMenu(menu Menu, trigger, description string) robot.Command

UseMenu allows to generate the robot.Command from a given menu to make it work

func Wrap 

func Wrap[T any](elem T) []T

Wrap anything into a slice of the same type. Especially useful when dealing with buttons

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var (
		strings   []string              = tgui.Wrap("Hello")
		buttonRow []tgui.InlineButton   = tgui.Wrap(tgui.InlineButton{Text: "Hello!"})
		buttons   [][]tgui.InlineButton = tgui.Wrap(buttonRow)
	)

	fmt.Println(strings)   

Output:

Types

type EditOptions 

type EditOptions = echotron.MessageTextOptions

EditOptions is a shorter way to indicate an echotron.MessageTextOptions

func DisableWebPagePreview 

func DisableWebPagePreview(opt *EditOptions) *EditOptions

DisableWebPagePreview allows to set DisableWebPagePreview to true when editing a message. When given the function will edit opt and return it or else it will create a new one

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var opt *tgui.EditOptions = tgui.ParseModeOpt(nil, "HTML")
	fmt.Println(tgui.DisableWebPagePreview(opt).DisableWebPagePreview) 

Output:

func EntitiesOpt 

func EntitiesOpt(opt *EditOptions, value []echotron.MessageEntity) *EditOptions

EntitiesOpt allows to change the Entities when editing a message. When given the function will edit opt and return it or else it will create a new one

Example 
var (
	fakeEntities        = []echotron.MessageEntity{{URL: "https://go.dev", Language: "Go"}}
	firstEntityLanguage = func(opts *tgui.EditOptions) string {
		return opts.Entities[0].Language
	}
)

var opt *tgui.EditOptions = tgui.DisableWebPagePreview(nil)
fmt.Println(firstEntityLanguage(tgui.EntitiesOpt(opt, fakeEntities))) 

Output:

func InlineKbdOpt 

func InlineKbdOpt(opt *EditOptions, value [][]InlineButton) *EditOptions

InlineKbdOpt allows to change the Entities when editing a message. When given the function will edit opt and return it or else it will create a new one

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var (
		keyboard = [][]tgui.InlineButton{
			{{Text: "Click me", CallbackData: "/click"}, {Text: "Golang site", URL: "https://go.dev"}},
			{{Text: "Hello World", CallbackData: "/hello"}},
		}
		firstButtonText = func(opt *tgui.EditOptions) string {
			return opt.ReplyMarkup.InlineKeyboard[0][0].Text
		}
	)

	var opt *tgui.EditOptions = tgui.DisableWebPagePreview(nil)
	fmt.Println(firstButtonText(tgui.InlineKbdOpt(opt, keyboard))) 

Output:

func ParseModeOpt 

func ParseModeOpt(opt *EditOptions, value echotron.ParseMode) *EditOptions

ParseModeOpt allows to change the ParseMode when editing a message. When given the function will edit opt and return it or else it will create a new one

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var opt *tgui.EditOptions = tgui.DisableWebPagePreview(nil)
	fmt.Println(tgui.ParseModeOpt(opt, "HTML").ParseMode) 

Output:

func ReplyMarkupOpt 

func ReplyMarkupOpt(opt *EditOptions, value echotron.InlineKeyboardMarkup) *EditOptions

ReplyMarkupOpt allows to change the ReplyMarkup when editing a message. When given the function will edit opt and return it or else it will create a new one

Example 
var markup echotron.InlineKeyboardMarkup = tgui.InlineKeyboard([][]tgui.InlineButton{
	{{Text: "Click me", CallbackData: "/click"}, {Text: "Golang site", URL: "https://go.dev"}},
	{{Text: "Hello World", CallbackData: "/hello"}},
})

var opt *tgui.EditOptions = tgui.ParseModeOpt(nil, "HTML")
fmt.Println(tgui.ReplyMarkupOpt(opt, markup).ReplyMarkup) 

Output:

func WebPagePreviewOpt 

func WebPagePreviewOpt(opt *EditOptions, enable bool) *EditOptions

WebPagePreviewOpt allows to change the WebPagePreview when editing a message. When given the function will edit opt and return it or else it will create a new one

type InlineButton 

type InlineButton = echotron.InlineKeyboardButton

InlineButton is a shorter way to indicate an echotron.InlineKeyboardButton

func InlineCaller 

func InlineCaller(caption, trigger string, payload ...string) InlineButton

InlineCaller creates an inline button that will call the trigger-related command

Example 
package main

import (
	"fmt"

	"github.com/DazFather/parrbot/tgui"
)

func main() {
	var button tgui.InlineButton = tgui.InlineCaller("Click me", "/command", "first", "second")

	fmt.Println(button.Text)         

Output:


func InlineLink(caption, link string) InlineButton

InlineLink creates an inline button that will take the user to a specified link or chat

type InlineMenu 

type InlineMenu struct {
	// The main page of the menu required to work. All the other pages are nested inside
	Home InlineMenuItem

	// The caption of the inline button that allows user to go back to the previous page
	BackCaption string
	// contains filtered or unexported fields
}

InlineMenu is a collection of messages in a tree-like structure. Every message can be seen by pressing the related button.

func (*InlineMenu) Select 

func (m *InlineMenu) Select(payload string) (*Page, error)

Select a page by it's indexes (row and column, converting them into integers) and reset current

func (*InlineMenu) SelectHome 

func (m *InlineMenu) SelectHome() Page

SelectHome allows to get the Home's Page and reset current

func (*InlineMenu) SelectPrevious 

func (m *InlineMenu) SelectPrevious() *Page

SelectPrevious allows to get the parent page of the current and reset current.

func (*InlineMenu) Show 

func (m *InlineMenu) Show(page Page, b *robot.Bot, u *message.Update) error

Show a given page adding the buttons for it's Children

type InlineMenuItem 

type InlineMenuItem struct {
	// The caption of the inline button that when pressed will show Page
	Caption string

	// The actual page that will be shown
	Page Page

	// The pages that will be seen as inline buttons on the bottom when Page will be shown
	Children [][]InlineMenuItem
	// contains filtered or unexported fields
}

InlineMenuItem rapresent an element of the InlineMenu

type KeyButton 

type KeyButton = echotron.KeyboardButton

KeyButton is a shorter way to indicate echotron.KeyboardButton 

type Menu interface {

	// Select the previous page, nil if is not possible. Called when payload = "back"
	SelectPrevious() *Page

	// Select the home page of the menu. Called when payload = ""
	SelectHome() Page

	// Select a generic page specified by pageSelector, the payload after trigger.
	// The error will cause an alert (if possible) and a log on console
	Select(pageSelector string) (*Page, error)

	// Show the selected page on screen. If returned the error will be fatal
	Show(page Page, b *robot.Bot, u *message.Update) error
	// contains filtered or unexported methods
}

Menu represents a generic graphical menu introduced by this package (ex. PagedMenu, InlineMenu) All menus can be triggered by both a MESSAGE and a CALLBACK_QUERY.

type Page 

type Page func(bot *robot.Bot, update *message.Update) (content string, opts *EditOptions)

Page is a function that will return the content that will be shown when a user request that page of the Menu

func StaticPage 

func StaticPage(content string, pageOption *EditOptions) Page

StaticPage returns a Page that will return always the same output

type PagedMenu 

type PagedMenu struct {
	// The collection of pages of the menu, required to work
	Pages []Page

	// The caption of the navigation buttons. You can embed "[INDEX]" inside
	// PreviousCaption and NextCaption to show the number of the related page.
	// By default (if missing or empty string are passed) their values is:
	// "⏭ [INDEX]", "[INDEX] ⏮", "❌".
	NextCaption, PreviousCaption, CloseCaption string
	// contains filtered or unexported fields
}

PagedMenu is a collection of messages in a book-like structure. Every message can be seen by pressing the next or previous button

func (*PagedMenu) Select 

func (m *PagedMenu) Select(pageIndex string) (*Page, error)

Select a page by it's index (converting it into an integer) and reset current

func (*PagedMenu) SelectHome 

func (m *PagedMenu) SelectHome() Page

SelectHome allows to get the first page and reset current

func (*PagedMenu) SelectPrevious 

func (m *PagedMenu) SelectPrevious() *Page

SelectPrevious allows to get the page before the current and reset current. When not possible (current page index = 0) returns nil

func (*PagedMenu) Show 

func (m *PagedMenu) Show(page Page, b *robot.Bot, u *message.Update) error

Show a given page adding the navigation buttons: previous / close / next

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.