icontheme

README

icontheme — go-freedesktop

Pure-Go (CGO_ENABLED=0) implementation of the freedesktop.org Icon Theme Specification lookup algorithm. It resolves an icon name (such as the Icon= value of a .desktop entry) to a concrete file path on disk at a requested pixel size and scale.

To the best of our knowledge this is the first pure-Go implementation of the full spec lookup; the mature references are the Rust oknozor/freedesktop-icons and the D FreeSlave/icontheme.

Features

• Parses index.theme: Inherits, Directories/ScaledDirectories, and each directory's Size, Scale, Context, Type (Fixed/Scalable/Threshold), MinSize, MaxSize, Threshold, with spec defaults for absent keys.
• Full FindIcon/LookupIcon chain: exact directory-size match, then closest by DirectorySizeDistance, walked across the theme's inheritance chain, then the implicit hicolor base theme, then unthemed pixmaps, then a generic name-truncation fallback.
• Standard search path via github.com/adrg/xdg: $HOME/.icons, $XDG_DATA_HOME/icons, each $XDG_DATA_DIRS/icons, and /usr/share/pixmaps.
• @2x (and any Scale) directories via the spec's scale rules.
• Extension preference png → svg → xpm.
• In-memory caches of parsed indexes and per-(name,size,scale) results; safe for concurrent use.

Scope

This package returns a path only. Rasterising the file (PNG/XPM decode or SVG render) is the caller's job — in the wasmdesk stack that is done by go-widgets / go-opentype. It does not read pixels, so it stays fast and dependency-light.

Install

go get github.com/go-freedesktop/icontheme

Quickstart

package main

import (
	"fmt"

	"github.com/go-freedesktop/icontheme"
)

func main() {
	theme := icontheme.New("Adwaita") // falls back through Inherits, then hicolor

	// Resolve a single name at 48px, scale 1.
	path, err := theme.Lookup("text-editor", 48, 1)
	if err != nil {
		fmt.Println("not found:", err)
		return
	}
	fmt.Println(path) // e.g. /usr/share/icons/Adwaita/48x48/apps/text-editor.png

	// Try a list of candidate names (Icon= value plus fallbacks), HiDPI scale 2.
	path, err = theme.FindIcon([]string{"org.example.App", "application-x-executable"}, 24, 2)
	fmt.Println(path, err)
}

API

• New(name string) *Theme — theme using the standard XDG base directories.
• NewWithBaseDirs(name string, baseDirs []string) *Theme — inject a custom search path.
• DefaultBaseDirs() []string — the standard ordered base directories.
• (*Theme) Lookup(name string, size, scale int) (string, error) — resolve one name.
• (*Theme) FindIcon(names []string, size, scale int) (string, error) — first name that resolves.
• ErrNotFound — returned when nothing matches.

Tests & coverage

CGO_ENABLED=0 go test ./... — 100% statement coverage, including every error branch, driven by fixtures under testdata/. CI additionally cross-builds and runs the suite on the six supported 64-bit targets (amd64/arm64 natively, riscv64/loong64/ppc64le/s390x under qemu-user).

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package icontheme is a pure-Go (CGO_ENABLED=0) implementation of the freedesktop.org Icon Theme Specification lookup algorithm.

It resolves an icon name (such as the value of a .desktop file's Icon= key) to a concrete file path on disk at a requested pixel size and scale, following the specification exactly: it parses index.theme files, honours theme inheritance (with an implicit fall back to the hicolor base theme), and applies the DirectoryMatchesSize / DirectorySizeDistance rules to pick the best directory before falling back to unthemed pixmaps and, finally, a generic name-truncation fallback.

The package returns a path only; rasterising the file (PNG/XPM/SVG) is the caller's responsibility. It never rasterises, decodes or otherwise inspects the pixels, so it stays dependency-light and fast.

Specification: https://specifications.freedesktop.org/icon-theme/latest/

Index

• Constants
• Variables
• func DefaultBaseDirs() []string
• type Theme
  • func New(name string) *Theme
  • func NewWithBaseDirs(name string, baseDirs []string) *Theme
  • func (t *Theme) FindIcon(names []string, size, scale int) (string, error)
  • func (t *Theme) Lookup(name string, size, scale int) (string, error)

Constants

const HicolorTheme = "hicolor"

HicolorTheme is the name of the base theme every icon theme implicitly inherits from, as mandated by the specification.

Variables

var ErrNotFound = errors.New("icontheme: icon not found")

ErrNotFound is returned by Lookup and FindIcon when no matching icon file can be located anywhere in the search path.

Functions

func DefaultBaseDirs

func DefaultBaseDirs() []string

DefaultBaseDirs returns the ordered list of icon base directories per the specification: $HOME/.icons, $XDG_DATA_HOME/icons, each $XDG_DATA_DIRS/icons, and finally /usr/share/pixmaps.

Types

type Theme

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

Theme resolves icon names for a chosen icon theme. It parses and caches the index.theme of the theme and every theme it inherits from, and memoises individual lookups. A Theme is safe for concurrent use by multiple goroutines.

func New

func New(name string) *Theme

New returns a Theme for the named icon theme using the standard base directories derived from the XDG base-directory specification, plus $HOME/.icons and /usr/share/pixmaps.

func NewWithBaseDirs

func NewWithBaseDirs(name string, baseDirs []string) *Theme

NewWithBaseDirs returns a Theme for the named icon theme that searches the supplied base directories in order. It is the injection seam used for testing and for callers that manage their own icon search path.

func (*Theme) FindIcon

func (t *Theme) FindIcon(names []string, size, scale int) (string, error)

FindIcon resolves the first of the candidate names that can be found, searching them in order. It is a convenience for a .desktop Icon= value followed by generic fallbacks. It returns ErrNotFound if none match.

func (*Theme) Lookup

func (t *Theme) Lookup(name string, size, scale int) (string, error)

Lookup resolves icon name at the requested size (in device-independent pixels) and scale, returning the path to the best matching file. It searches the theme's inheritance chain, then hicolor, then unthemed pixmaps, then a generic fallback that strips trailing "-" separated components. It returns ErrNotFound if no file matches.