fyne_iconkit

README

fyne_iconkit

Shared runtime and code generator behind the Fyne icon packages

• fyne_tabler – Tabler Icons
• fyne_lucide – Lucide
• fyne_flagicons – country flags

You normally use one of those packages. Use fyne_iconkit directly to build your own icon package. Requires Go 1.21+ and Fyne 2.3+.

Icon sets

package myicons

import (
	"embed"
	"image/color"

	"fyne.io/fyne/v2"
	"github.com/timzifer/fyne_iconkit"
)

//go:generate go run github.com/timzifer/fyne_iconkit/cmd/iconconst -dir icons -type icon -prefix Icon -out icons_gen.go

// icon is unexported and only created by the generated variables (IconHome, ...)
// or Lookup, so callers cannot pass names that do not exist.
type icon struct{ name string }

//go:embed icons
var icons embed.FS

// NewStainableSet for monochrome icons using "currentColor",
// NewSet for multi-colored icons that are served as they are.
var set = fyne_iconkit.NewStainableSet(icons, "icons")

func Icon(i icon, stain ...color.Color) fyne.Resource {
	return set.MustIcon(i.name, stain...)
}

func Lookup(name string) (icon, bool) {
	if !set.Has(name) {
		return icon{}, false
	}
	return icon{name}, true
}

A Set is addressed by plain names; wrapping packages hide that behind their icon type. It offers:

Method	Description
Icon(name, stain...)	cached fyne.Resource; stainable sets return a StainableResource (default color: theme foreground)
MustIcon(name, stain...)	like Icon, logs via fyne.LogError and falls back to theme.ErrorIcon()
Source(name) / StainedSource(name, c)	raw or stained SVG bytes
PNG(name, size, stain...)	rasterized PNG, size = longer edge in pixels
Names() / Has(name)	list / check icons

Unknown icons yield errors wrapping fs.ErrNotExist.

Generated icon variables

cmd/iconconst writes one variable per *.svg file, e.g. IconArrowUp = icon{"arrow-up"}. Struct values are used instead of string constants because an untyped string literal would still be accepted wherever a string-based type is expected.

Flag	Default
-dir	icons	directory with the SVG files
-out	icons_gen.go	output file
-pkg	$GOPACKAGE	package name
-type	icon	struct type with a single string field, declared in the package
-prefix	Icon	identifier prefix
-upper	false	gb-eng → FlagGB_ENG instead of FlagGbEng

License

MIT

Documentation

Overview

Package fyne_iconkit provides the shared runtime behind the fyne_* icon packages: loading SVG icons from an fs.FS, caching them as fyne.Resource, staining monochrome icons with an arbitrary color and rasterizing them to PNG.

Icon packages usually wrap a single package-level Set around an embedded directory and generate name constants with cmd/iconconst.

Index

• func Stain(src []byte, c color.Color) []byte
• type Set
  • func NewSet(fsys fs.FS, dir string) *Set
  • func NewStainableSet(fsys fs.FS, dir string) *Set
  • func (s *Set) Has(name string) bool
  • func (s *Set) Icon(name string, stainColor ...color.Color) (fyne.Resource, error)
  • func (s *Set) MustIcon(name string, stainColor ...color.Color) fyne.Resource
  • func (s *Set) Names() []string
  • func (s *Set) PNG(name string, size int, stainColor ...color.Color) ([]byte, error)
  • func (s *Set) Source(name string) ([]byte, error)
  • func (s *Set) StainedSource(name string, c color.Color) ([]byte, error)
• type StainableResource

Functions

func Stain

func Stain(src []byte, c color.Color) []byte

Stain replaces every "currentColor" in src with c. Translucent colors add fill-opacity/stroke-opacity attributes, because SVG attributes do not reliably support colors with alpha.

Types

type Set

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

Set is a collection of SVG icons stored in a directory of an fs.FS. All methods are safe for concurrent use.

func NewSet

func NewSet(fsys fs.FS, dir string) *Set

NewSet returns a Set of multi-colored icons (e.g. flags). Icons are served as they are; stain colors passed to Icon are ignored.

func NewStainableSet

func NewStainableSet(fsys fs.FS, dir string) *Set

NewStainableSet returns a Set of monochrome icons that use "currentColor". Icons are always stained before use; without an explicit color the theme's foreground color at the time of the call is used.

func (*Set) Has

func (s *Set) Has(name string) bool

Has reports whether the set contains an icon with the given name.

func (*Set) Icon

func (s *Set) Icon(name string, stainColor ...color.Color) (fyne.Resource, error)

Icon returns the named icon as a cached fyne.Resource.

For stainable sets the result is a StainableResource colored with the first stain color, or with the current theme foreground color if none is given. For other sets stain colors are ignored.

func (*Set) MustIcon

func (s *Set) MustIcon(name string, stainColor ...color.Color) fyne.Resource

MustIcon is like Icon but logs the error via fyne.LogError and returns theme.ErrorIcon() if the icon cannot be loaded.

func (*Set) Names

func (s *Set) Names() []string

Names returns the sorted names of all icons in the set.

func (*Set) PNG

func (s *Set) PNG(name string, size int, stainColor ...color.Color) ([]byte, error)

PNG rasterizes the named icon to PNG. size is the length of the longer edge in pixels; the aspect ratio of the SVG view box is preserved.

Icons of stainable sets are stained with the first stain color, or black if none is given. For other sets stain colors are ignored.

func (*Set) Source

func (s *Set) Source(name string) ([]byte, error)

Source returns the unmodified SVG content of the named icon. Names are the file names without ".svg". Unknown names yield an error wrapping fs.ErrNotExist.

func (*Set) StainedSource

func (s *Set) StainedSource(name string, c color.Color) ([]byte, error)

StainedSource returns the SVG content of the named icon with every "currentColor" replaced by c.

type StainableResource

type StainableResource interface {
	fyne.Resource

	// StainColor returns the color the resource is currently stained with.
	StainColor() color.Color
	// Stain returns the same icon stained with c.
	Stain(c color.Color) (fyne.Resource, error)
	// MustStain is like Stain but returns theme.ErrorIcon() on failure.
	MustStain(c color.Color) fyne.Resource
}

StainableResource is a monochrome icon resource that can be re-colored.