wallpaper

package
v1.6.5 Latest Latest
Warning

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

Go to latest
Published: Jan 21, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source
const (
	SmartFitPrefKey         = pluginPrefix + "smart_fit_key"          // SmartFitPrefKey is used to set and retrieve the boolean flag for wallpaper smart fit
	SmartFitModePrefKey     = pluginPrefix + "smart_fit_mode_key"     // SmartFitModePrefKey is used to set and retrieve the int smart fit mode
	CacheSizePrefKey        = pluginPrefix + "cache_size_key"         // WallpaperCacheSizePrefKey is used to set and retrieve the int wallpaper cache size
	WallpaperChgFreqPrefKey = pluginPrefix + "wallpaper_chg_freq_key" // WallpaperChgFreqPrefKey is used to set and retrieve the int change frequency for wallpapers
	ImgShufflePrefKey       = pluginPrefix + "img_shuffle_key"        // ImgShufflePrefKey is used to set and retrieve the boolean flag for wallpaper image shuffle
	ChgImgOnStartPrefKey    = pluginPrefix + "chg_img_on_start_key"   // ChgImgOnStartPrefKey is used to set and retrieve the boolean flag for changing wallpaper on startup
	NightlyRefreshPrefKey   = pluginPrefix + "nightly_refresh_key"    // NightlyRefreshPrefKey is used to set and retrieve the boolean flag for nightly refresh
	FaceBoostPrefKey        = pluginPrefix + "face_boost_key"         // FaceBoostPrefKey is used to set and retrieve the boolean flag for face boost
	FaceCropPrefKey         = pluginPrefix + "face_crop_key"          // FaceCropPrefKey is used to set and retrieve the boolean flag for face crop

	// Provider keys (Shared)
	UnsplashTokenPrefKey            = "unsplash_access_token"
	GooglePhotosTokenPrefKey        = "google_photos_access_token"
	GooglePhotosRefreshTokenPrefKey = "google_photos_refresh_token"
	GooglePhotosTokenExpiryPrefKey  = "google_photos_token_expiry"
	WallhavenAPIKeyPrefKey          = "wallhaven_api_key" //nolint:gosec // Preference key, not a secret

	PexelsAPIKeyPrefKey = "pexels_api_key" //nolint:gosec // Preference key, not a secret
)

Preference keys for wallpaper

View Source
const (
	// Cache Directory Segments
	// Structure: FittedRootDir / [Quality|Flexibility] / [Standard|FaceBoost|FaceCrop]
	FittedRootDir = "fitted"

	// Mode Segments
	QualityDir     = "quality"
	FlexibilityDir = "flexibility"

	// Type Segments
	StandardDir              = "standard"
	FaceBoostDir             = "faceboost"
	FaceCropDir              = "facecrop"
	PrcntSeenTillDownload    = 0.8
	MinSeenImagesForDownload = 5
	MinLocalImageBeforePulse = 1
	MaxImageWaitRetry        = 10
	ImageWaitRetryDelay      = 1 * time.Second
	MaxDescLength            = 50
	MaxURLLength             = 255
	MaxFavoritesLimit        = 200
	FavoritesNamespace       = "favorites" // API Namespace
	FavoritesCollection      = "favorite_images"
	FavoritesQueryID         = "favorites://" + FavoritesCollection
)

Internal constants

View Source
const (
	// HTTPClientRequestTimeout is the total time limit for a single HTTP request,
	// including connection, redirects, and reading the response body.
	HTTPClientRequestTimeout = 60 * time.Second

	// HTTPClientDialerTimeout is the timeout for establishing a TCP connection.
	// This is the most critical timeout for handling network issues after sleep.
	HTTPClientDialerTimeout = 15 * time.Second

	// HTTPClientTLSHandshakeTimeout is the time limit for the TLS handshake for HTTPS.
	// This is the time limit for the TLS handshake for HTTPS.
	HTTPClientTLSHandshakeTimeout = 10 * time.Second

	// HTTPClientResponseHeaderTimeout is the time limit for receiving response headers
	// from the server after the request has been successfully sent.
	HTTPClientResponseHeaderTimeout = 15 * time.Second

	// HTTPClientKeepAlive is the duration for TCP keep-alive probes. This helps
	// maintain long-lived connections efficiently.
	HTTPClientKeepAlive = 30 * time.Second

	// NetworkConnectivityCheckTimeout is a short timeout used specifically for
	// the initial, lightweight network availability check.
	NetworkConnectivityCheckTimeout = 4 * time.Second

	// URLValidationTimeout is used when checking if a user-provided URL is valid.
	URLValidationTimeout = 15 * time.Second
)

NetworkTimeouts defines the standard durations for various network operations.

Variables

View Source
var CacheSizeValues = map[CacheSize]int{
	CacheNone:       0,
	Cache100Images:  100,
	Cache200Images:  200,
	Cache300Images:  300,
	Cache500Images:  500,
	Cache1000Images: 1000,
}

CacheSizeValues maps CacheSize to its integer representation.

FrequencyDurations maps a Frequency to its time.Duration

Functions

func CreateAddQueryButton added in v1.1.1

func CreateAddQueryButton(label string, sm setting.SettingsManager, cfg AddQueryConfig, onAdded func()) *widget.Button

CreateAddQueryButton creates a standardized button that opens a modal for adding image queries. It handles input validation, UI feedback, and correctly triggering the SettingsManager apply lifecycle.

func CreateMuseumHeader added in v1.6.0

func CreateMuseumHeader(name, location, licenseText, licenseURL, description, mapURL, webURL, donateURL string, sm setting.SettingsManager) fyne.CanvasObject

CreateMuseumHeader creates a standardized header for museum providers.

func GenerateQueryID added in v0.5.6

func GenerateQueryID(url string) string

GenerateQueryID creates a stable hash ID from a URL string.

func GetCacheSizes

func GetCacheSizes() []fmt.Stringer

GetCacheSizes returns a list of all available cache sizes AS fmt.Stringer.

func GetFrequencies

func GetFrequencies() []fmt.Stringer

GetFrequencies returns a list of all available frequencies AS fmt.Stringer

func GetPath

func GetPath() string

GetPath returns the path to the user's config directory

func GetRegisteredProviders added in v1.1.0

func GetRegisteredProviders() map[string]ProviderFactory

GetRegisteredProviders returns all registered provider factories.

func GetSmartFitModes added in v1.3.0

func GetSmartFitModes() []string

GetSmartFitModes returns a list of available smart fit modes as strings

func LoadPlugin

func LoadPlugin(pm ui.PluginManager)

LoadPlugin loads the wallpaper plugin.

func OpenAddQueryDialog added in v1.4.0

func OpenAddQueryDialog(sm setting.SettingsManager, cfg AddQueryConfig, initialURL, initialDesc string, onAdded func())

OpenAddQueryDialog opens the modal for adding image queries. It allows pre-filling the URL and Description.

func RegisterProvider added in v1.1.0

func RegisterProvider(name string, factory ProviderFactory)

RegisterProvider registers a new image provider factory.

Types

type AddQueryConfig added in v1.1.1

type AddQueryConfig struct {
	Title           string
	Description     string // Optional description for the modal
	URLPlaceholder  string
	URLValidator    string
	URLErrorMsg     string
	DescPlaceholder string
	DescValidator   string
	DescErrorMsg    string

	// ValidateFunc is an optional custom validation logic (e.g., API URL conversion check).
	// It returns an error if validation fails.
	ValidateFunc func(url, desc string) error

	// AddHandler performs the actual addition of the query.
	// It returns the new query ID and an error if it fails.
	AddHandler func(desc, url string, active bool) (string, error)
}

AddQueryConfig defines the configuration for the standardized Add Query modal.

type CacheSize

type CacheSize int

CacheSize represents the predefined cache sizes (in number of images).

const (
	CacheNone CacheSize = iota
	Cache100Images
	Cache200Images
	Cache300Images
	Cache500Images
	Cache1000Images
)

CacheSize constants

func (CacheSize) Size

func (cs CacheSize) Size() int

Size returns the integer value of a CacheSize.

func (CacheSize) String

func (cs CacheSize) String() string

String returns the string representation of a CacheSize.

type ChromeOS added in v1.4.0

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

ChromeOS implements the OS interface for Chrome OS via Bridge.

func (*ChromeOS) GetDesktopDimension added in v1.6.1

func (c *ChromeOS) GetDesktopDimension() (int, int, error)

GetDesktopDimension returns the desktop dimensions.

func (*ChromeOS) RegisterBridge added in v1.4.0

func (c *ChromeOS) RegisterBridge(cb func(string) error)

RegisterBridge registers the callback function.

func (*ChromeOS) SetWallpaper added in v1.6.1

func (c *ChromeOS) SetWallpaper(path string) error

SetWallpaper delegates to the bridge callback.

type CmdType added in v1.2.0

type CmdType int
const (
	CmdMarkSeen CmdType = iota
	CmdRemove
	CmdClear
)

type Config

type Config struct {
	fyne.Preferences
	WallhavenAPIKey string       `json:"wallhaven_api_key"`
	Queries         []ImageQuery `json:"queries"`          // Unified list of image queries
	ImageQueries    []ImageQuery `json:"query_urls"`       // Legacy: List of image queries (Wallhaven)
	UnsplashQueries []ImageQuery `json:"unsplash_queries"` // Legacy: List of Unsplash image queries
	PexelsQueries   []ImageQuery `json:"pexels_queries"`   // Legacy: List of Pexels image queries

	AvoidSet map[string]bool `json:"avoid_set"` // Set of image URLs to avoid

	// Advanced
	LogLevel                string       `json:"logLevel"`
	MaxConcurrentProcessors int          `json:"maxConcurrentProcessors"`
	Tuning                  TuningConfig `json:"tuning"`

	// Callbacks
	QueryRemovedCallback func(queryID string) `json:"-"`
	// contains filtered or unexported fields
}

Config struct to hold all configuration data

func GetConfig

func GetConfig(p fyne.Preferences) *Config

GetConfig returns the singleton instance of Config.

func (*Config) AddArtInstituteChicagoQuery added in v1.6.0

func (c *Config) AddArtInstituteChicagoQuery(description, url string, active bool) (string, error)

AddArtInstituteChicagoQuery adds a new AIC query.

func (*Config) AddFavoritesQuery added in v1.5.0

func (c *Config) AddFavoritesQuery(description, url string, active bool) (string, error)

AddFavoritesQuery adds a new Favorites query.

func (*Config) AddGooglePhotosQuery added in v1.5.0

func (c *Config) AddGooglePhotosQuery(description, url string, active bool) (string, error)

AddGooglePhotosQuery adds a new Google Photos query.

func (*Config) AddImageQuery

func (c *Config) AddImageQuery(desc, url string, active bool) (string, error)

AddImageQuery adds a new Wallhaven image query.

func (*Config) AddMetMuseumQuery added in v1.6.0

func (c *Config) AddMetMuseumQuery(description, url string, active bool) (string, error)

AddMetMuseumQuery adds a new Met Museum query.

func (*Config) AddPexelsQuery added in v1.1.0

func (c *Config) AddPexelsQuery(description, url string, active bool) (string, error)

AddPexelsQuery adds a new Pexels query.

func (*Config) AddProviderQuery added in v1.6.0

func (c *Config) AddProviderQuery(description, url, provider string, active bool) (string, error)

AddProviderQuery is the unified method for adding a query for ANY provider.

func (*Config) AddToAvoidSet

func (c *Config) AddToAvoidSet(id string)

AddToAvoidSet adds the given ID to the avoid set

func (*Config) AddUnsplashQuery added in v1.0.0

func (c *Config) AddUnsplashQuery(description, url string, active bool) (string, error)

AddUnsplashQuery adds a new Unsplash query.

func (*Config) AddWikimediaQuery added in v1.1.0

func (c *Config) AddWikimediaQuery(description, url string, active bool) (string, error)

AddWikimediaQuery adds a new Wikimedia query.

func (*Config) DisableArtInstituteChicagoQuery added in v1.6.0

func (c *Config) DisableArtInstituteChicagoQuery(id string) error

DisableArtInstituteChicagoQuery disables an AIC query.

func (*Config) DisableGooglePhotosQuery added in v1.5.0

func (c *Config) DisableGooglePhotosQuery(id string) error

DisableGooglePhotosQuery disables a Google Photos query.

func (*Config) DisableImageQuery

func (c *Config) DisableImageQuery(id string) error

DisableImageQuery disables the image query with the specified ID

func (*Config) DisableMetMuseumQuery added in v1.6.0

func (c *Config) DisableMetMuseumQuery(id string) error

DisableMetMuseumQuery disables a Met Museum query.

func (*Config) DisablePexelsQuery added in v1.1.0

func (c *Config) DisablePexelsQuery(id string) error

DisablePexelsQuery disables a Pexels query.

func (*Config) DisableUnsplashQuery added in v1.0.0

func (c *Config) DisableUnsplashQuery(id string) error

DisableUnsplashQuery disables an Unsplash query.

func (*Config) EnableArtInstituteChicagoQuery added in v1.6.0

func (c *Config) EnableArtInstituteChicagoQuery(id string) error

EnableArtInstituteChicagoQuery enables an AIC query.

func (*Config) EnableGooglePhotosQuery added in v1.5.0

func (c *Config) EnableGooglePhotosQuery(id string) error

EnableGooglePhotosQuery enables a Google Photos query.

func (*Config) EnableImageQuery

func (c *Config) EnableImageQuery(id string) error

EnableImageQuery enables the image query with the specified ID

func (*Config) EnableMetMuseumQuery added in v1.6.0

func (c *Config) EnableMetMuseumQuery(id string) error

EnableMetMuseumQuery enables a Met Museum query.

func (*Config) EnablePexelsQuery added in v1.1.0

func (c *Config) EnablePexelsQuery(id string) error

EnablePexelsQuery enables a Pexels query.

func (*Config) EnableUnsplashQuery added in v1.0.0

func (c *Config) EnableUnsplashQuery(id string) error

EnableUnsplashQuery enables an Unsplash query.

func (*Config) GetActiveQueries added in v1.1.0

func (c *Config) GetActiveQueries() []ImageQuery

GetActiveQueries returns a copy of all active queries in a thread-safe manner.

func (*Config) GetActiveQueryIDs added in v1.3.0

func (c *Config) GetActiveQueryIDs() map[string]bool

GetActiveQueryIDs returns a map of all currently active query IDs.

func (*Config) GetArtInstituteChicagoQueries added in v1.6.0

func (c *Config) GetArtInstituteChicagoQueries() []ImageQuery

GetArtInstituteChicagoQueries returns a copy of the AIC queries.

func (*Config) GetAssetManager added in v0.6.0

func (c *Config) GetAssetManager() *asset.Manager

GetAssetManager returns the asset manager

func (*Config) GetAvoidSet added in v1.3.1

func (c *Config) GetAvoidSet() map[string]bool

GetAvoidSet returns a copy of the avoid set.

func (*Config) GetCacheSize

func (c *Config) GetCacheSize() CacheSize

GetCacheSize returns the cache size enumeration from the config, or the default value if not set or invalid

func (*Config) GetChgImgOnStart added in v0.3.7

func (c *Config) GetChgImgOnStart() bool

GetChgImgOnStart returns the change image on start preference.

func (*Config) GetFaceBoostEnabled added in v0.6.0

func (c *Config) GetFaceBoostEnabled() bool

GetFaceBoostEnabled returns the face boost preference.

func (*Config) GetFaceCropEnabled added in v0.6.1

func (c *Config) GetFaceCropEnabled() bool

GetFaceCropEnabled returns the face crop preference.

func (*Config) GetGooglePhotosQueries added in v1.5.0

func (c *Config) GetGooglePhotosQueries() []ImageQuery

GetGooglePhotosQueries returns a copy of the Google Photos queries in a thread-safe manner.

func (*Config) GetGooglePhotosRefreshToken added in v1.5.0

func (c *Config) GetGooglePhotosRefreshToken() string

GetGooglePhotosRefreshToken returns the Google Photos Refresh Token from the keyring.

func (*Config) GetGooglePhotosToken added in v1.5.0

func (c *Config) GetGooglePhotosToken() string

GetGooglePhotosToken returns the Google Photos Access Token from the keyring.

func (*Config) GetGooglePhotosTokenExpiry added in v1.5.0

func (c *Config) GetGooglePhotosTokenExpiry() time.Time

GetGooglePhotosTokenExpiry returns the Google Photos Token Expiry from the keyring.

func (*Config) GetImageQueries added in v1.1.0

func (c *Config) GetImageQueries() []ImageQuery

GetImageQueries returns a copy of the Wallhaven queries in a thread-safe manner.

func (*Config) GetImgShuffle

func (c *Config) GetImgShuffle() bool

GetImgShuffle returns the image shuffle preference from the config.

func (*Config) GetMetMuseumQueries added in v1.6.0

func (c *Config) GetMetMuseumQueries() []ImageQuery

GetMetMuseumQueries returns a copy of the Met Museum queries.

func (*Config) GetNightlyRefresh added in v0.4.2

func (c *Config) GetNightlyRefresh() bool

GetNightlyRefresh returns the nightly refresh preference.

func (*Config) GetPexelsAPIKey added in v1.1.0

func (c *Config) GetPexelsAPIKey() string

GetPexelsAPIKey returns the Pexels API key from the config.

func (*Config) GetPexelsQueries added in v1.1.0

func (c *Config) GetPexelsQueries() []ImageQuery

GetPexelsQueries returns a copy of the Pexels queries in a thread-safe manner.

func (*Config) GetQueries added in v1.1.0

func (c *Config) GetQueries() []ImageQuery

GetQueries returns a copy of all queries in a thread-safe manner.

func (*Config) GetQuery added in v1.1.0

func (c *Config) GetQuery(id string) (ImageQuery, bool)

GetQuery returns a query by its ID. uniqueID is required.

func (*Config) GetSmartFit

func (c *Config) GetSmartFit() bool

GetSmartFit returns the smart fit preference from the config.

func (*Config) GetSmartFitMode added in v1.3.0

func (c *Config) GetSmartFitMode() SmartFitMode

func (*Config) GetUnlockAspectRatio added in v1.3.0

func (c *Config) GetUnlockAspectRatio() bool

GetUnlockAspectRatio returns the unlock aspect ratio flag.

func (*Config) GetUnsplashQueries added in v1.1.0

func (c *Config) GetUnsplashQueries() []ImageQuery

GetUnsplashQueries returns a copy of the Unsplash queries in a thread-safe manner.

func (*Config) GetUnsplashToken added in v1.0.0

func (c *Config) GetUnsplashToken() string

GetUnsplashToken returns the Unsplash Access Token from the keyring.

func (*Config) GetWallhavenAPIKey

func (c *Config) GetWallhavenAPIKey() string

GetWallhavenAPIKey returns the Wallhaven API key from the config.

func (*Config) GetWallpaperChangeFrequency

func (c *Config) GetWallpaperChangeFrequency() Frequency

GetWallpaperChangeFrequency returns the wallpaper change frequency enumeration from the config, or the default value if not set or invalid

func (*Config) GetWikimediaQueries added in v1.1.0

func (c *Config) GetWikimediaQueries() []ImageQuery

GetWikimediaQueries returns a copy of the Wikimedia queries in a thread-safe manner.

func (*Config) InAvoidSet

func (c *Config) InAvoidSet(id string) bool

InAvoidSet checks if the given ID is in the avoid set

func (*Config) IsDuplicateID added in v0.5.6

func (c *Config) IsDuplicateID(id string) bool

IsDuplicateID checks if a query ID already exists (exported version).

func (*Config) RemoveGooglePhotosQuery added in v1.5.0

func (c *Config) RemoveGooglePhotosQuery(id string) error

RemoveGooglePhotosQuery removes a Google Photos query from the unified list.

func (*Config) RemoveImageQuery

func (c *Config) RemoveImageQuery(id string) error

RemoveImageQuery removes the image query with the specified ID

func (*Config) RemoveMetMuseumQuery added in v1.6.0

func (c *Config) RemoveMetMuseumQuery(id string) error

RemoveMetMuseumQuery removes a Met Museum query.

func (*Config) RemovePexelsQuery added in v1.1.0

func (c *Config) RemovePexelsQuery(id string) error

RemovePexelsQuery removes a Pexels query from the unified list.

func (*Config) RemoveUnsplashQuery added in v1.0.0

func (c *Config) RemoveUnsplashQuery(id string) error

RemoveUnsplashQuery removes an Unsplash query from the unified list.

func (*Config) ResetAvoidSet

func (c *Config) ResetAvoidSet()

ResetAvoidSet clears the avoid set

func (*Config) SetCacheSize

func (c *Config) SetCacheSize(size CacheSize)

SetCacheSize sets the cache size enumeration and saves it

func (*Config) SetChgImgOnStart added in v0.3.7

func (c *Config) SetChgImgOnStart(enable bool)

SetChgImgOnStart returns the change image on start preference.

func (*Config) SetFaceBoostEnabled added in v0.6.0

func (c *Config) SetFaceBoostEnabled(enable bool)

SetFaceBoostEnabled sets the face boost preference.

func (*Config) SetFaceCropEnabled added in v0.6.1

func (c *Config) SetFaceCropEnabled(enable bool)

SetFaceCropEnabled sets the face crop preference.

func (*Config) SetGooglePhotosRefreshToken added in v1.5.0

func (c *Config) SetGooglePhotosRefreshToken(token string)

SetGooglePhotosRefreshToken sets the Google Photos Refresh Token in the keyring.

func (*Config) SetGooglePhotosToken added in v1.5.0

func (c *Config) SetGooglePhotosToken(token string)

SetGooglePhotosToken sets the Google Photos Access Token in the keyring.

func (*Config) SetGooglePhotosTokenExpiry added in v1.5.0

func (c *Config) SetGooglePhotosTokenExpiry(expiry time.Time)

SetGooglePhotosTokenExpiry sets the Google Photos Token Expiry in the keyring.

func (*Config) SetImgShuffle

func (c *Config) SetImgShuffle(enabled bool)

SetImgShuffle sets the image shuffle preference.

func (*Config) SetNightlyRefresh added in v0.4.2

func (c *Config) SetNightlyRefresh(enable bool)

SetNightlyRefresh sets the nightly refresh preference.

func (*Config) SetPexelsAPIKey added in v1.1.0

func (c *Config) SetPexelsAPIKey(apiKey string)

SetPexelsAPIKey sets the Pexels API key.

func (*Config) SetQueryRemovedCallback added in v1.3.0

func (c *Config) SetQueryRemovedCallback(callback func(queryID string))

SetQueryRemovedCallback sets the callback for when a query is removed.

func (*Config) SetSmartFit

func (c *Config) SetSmartFit(enabled bool)

SetSmartFit sets the smart fit preference.

func (*Config) SetSmartFitMode added in v1.3.0

func (c *Config) SetSmartFitMode(mode SmartFitMode)

SetSmartFitMode sets the smart fit mode.

func (*Config) SetUnlockAspectRatio added in v1.3.0

func (c *Config) SetUnlockAspectRatio(enabled bool)

SetUnlockAspectRatio sets the unlock aspect ratio flag.

func (*Config) SetUnsplashToken added in v1.0.0

func (c *Config) SetUnsplashToken(token string)

SetUnsplashToken sets the Unsplash Access Token in the keyring.

func (*Config) SetWallhavenAPIKey

func (c *Config) SetWallhavenAPIKey(apiKey string)

SetWallhavenAPIKey sets the Wallhaven API key.

func (*Config) SetWallpaperChangeFrequency

func (c *Config) SetWallpaperChangeFrequency(frequency Frequency)

SetWallpaperChangeFrequency sets the frequency enumeration for wallpaper changes and saves it

func (*Config) UpdateImageQuery added in v1.5.0

func (c *Config) UpdateImageQuery(id, description string) error

UpdateImageQuery updates the description of a query.

type DownloadJob added in v1.2.0

type DownloadJob struct {
	Image    provider.Image
	Provider provider.ImageProvider
}

DownloadJob represents a task to download and process an image.

type FaceDetectionStats added in v1.6.1

type FaceDetectionStats struct {
	Found      bool
	Q          float32
	Rect       image.Rectangle
	Scale      int
	Processing time.Duration
}

FaceDetectionStats holds diagnostic data about the last face detection run.

type FileManager added in v1.3.0

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

FileManager handles all file system operations for wallpaper images. It enforces the directory structure for Source + Derivative architecture.

func NewFileManager added in v1.3.0

func NewFileManager(rootDir string) *FileManager

NewFileManager creates a new FileManager with the given root directory. The rootDir is typically ".../wallpaper_downloads".

func (*FileManager) CleanupOrphans added in v1.3.0

func (fm *FileManager) CleanupOrphans(knownIDs map[string]bool)

CleanupOrphans removes files from the root directory and subdirectories that are NOT present in the knownIDs map.

func (*FileManager) DeepDelete added in v1.3.0

func (fm *FileManager) DeepDelete(id string) error

DeepDelete removes the Master image and ALL its derivatives. It searches for files with the given ID in all known directories.

func (*FileManager) DeleteDerivatives added in v1.6.1

func (fm *FileManager) DeleteDerivatives(id string) error

DeleteDerivatives removes ONLY the processed versions of an image, keeping the Master. This is used when invalidating cache due to settings changes (Smart Fit, etc.).

func (*FileManager) EnsureDirs added in v1.3.0

func (fm *FileManager) EnsureDirs() error

EnsureDirs creates necessary subdirectories for derivatives.

func (*FileManager) GetDerivativePath added in v1.3.0

func (fm *FileManager) GetDerivativePath(id string, ext string, derivativeType string) (string, error)

GetDerivativePath returns the path for a processed image based on the type. derivativeType is now a relative path segment (e.g., "fitted/quality/standard")

func (*FileManager) GetDownloadDir added in v1.3.1

func (fm *FileManager) GetDownloadDir() string

GetDownloadDir returns the root directory where images are downloaded.

func (*FileManager) GetMasterPath added in v1.3.0

func (fm *FileManager) GetMasterPath(id string, ext string) (string, error)

GetMasterPath returns the absolute path for the Master (Raw) image. Master images are stored directly in the root directory.

type Frequency

type Frequency int

Frequency represents the frequency of a service

const (
	FrequencyNever Frequency = iota
	Frequency5Minutes
	Frequency15Minutes
	Frequency30Minutes
	FrequencyHourly
	Frequency3Hours
	Frequency6Hours
	FrequencyDaily
	FrequencyInvalid
)

Frequency constants

func (Frequency) Duration

func (f Frequency) Duration() time.Duration

Duration returns the time.Duration of a Frequency

func (Frequency) String

func (f Frequency) String() string

String returns the string representation of a Frequency

type ImageProcessor

type ImageProcessor interface {
	DecodeImage(ctx context.Context, imgBytes []byte, contentType string) (image.Image, string, error)
	EncodeImage(ctx context.Context, img image.Image, contentType string) ([]byte, error)
	FitImage(ctx context.Context, img image.Image) (image.Image, error)
	CheckCompatibility(width, height int) error
}

ImageProcessor interface defines the image processing operations.

type ImageQuery

type ImageQuery struct {
	ID          string `json:"id"`
	Description string `json:"desc"`
	URL         string `json:"url"`
	Active      bool   `json:"active"`
	Provider    string `json:"provider"` // Provider name (e.g., "Wallhaven", "Unsplash", "Pexels")
}

ImageQuery struct to hold the URL of an image and whether it is active

type ImageStore added in v1.2.0

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

ImageStore is a thread-safe storage for wallpaper images.

func NewImageStore added in v1.2.0

func NewImageStore() *ImageStore

func (*ImageStore) Add added in v1.2.0

func (s *ImageStore) Add(img provider.Image) bool

func (*ImageStore) Clear added in v1.2.0

func (s *ImageStore) Clear()

func (*ImageStore) Contains added in v1.3.0

func (s *ImageStore) Contains(id string) bool

func (*ImageStore) Count added in v1.2.0

func (s *ImageStore) Count() int

func (*ImageStore) Get added in v1.2.0

func (s *ImageStore) Get(index int) (provider.Image, bool)

func (*ImageStore) GetByID added in v1.3.0

func (s *ImageStore) GetByID(id string) (provider.Image, bool)

func (*ImageStore) GetKnownIDs added in v1.3.0

func (s *ImageStore) GetKnownIDs() map[string]bool

func (*ImageStore) List added in v1.2.0

func (s *ImageStore) List() []provider.Image

func (*ImageStore) LoadAvoidSet added in v1.3.1

func (s *ImageStore) LoadAvoidSet(avoidSet map[string]bool)

func (*ImageStore) LoadCache added in v1.3.0

func (s *ImageStore) LoadCache() error

func (*ImageStore) MarkSeen added in v1.2.0

func (s *ImageStore) MarkSeen(filePath string)

func (*ImageStore) Remove added in v1.2.0

func (s *ImageStore) Remove(id string) (provider.Image, bool)

func (*ImageStore) RemoveByQueryID added in v1.3.0

func (s *ImageStore) RemoveByQueryID(queryID string)

func (*ImageStore) SaveCache added in v1.3.0

func (s *ImageStore) SaveCache()

func (*ImageStore) SeenCount added in v1.2.0

func (s *ImageStore) SeenCount() int

func (*ImageStore) SetAsyncSave added in v1.3.0

func (s *ImageStore) SetAsyncSave(enabled bool)

func (*ImageStore) SetDebounceDuration added in v1.3.0

func (s *ImageStore) SetDebounceDuration(d time.Duration)

func (*ImageStore) SetFileManager added in v1.3.0

func (s *ImageStore) SetFileManager(fm *FileManager, cacheFile string)

func (*ImageStore) Sync added in v1.3.0

func (s *ImageStore) Sync(limit int, targetFlags map[string]bool, activeQueryIDs map[string]bool)

func (*ImageStore) Update added in v1.3.0

func (s *ImageStore) Update(img provider.Image) bool

func (*ImageStore) Wipe added in v1.3.0

func (s *ImageStore) Wipe()

type OS

type OS interface {
	GetDesktopDimension() (int, int, error)
	SetWallpaper(path string) error
}

OS interface defines the operating system specific operations. OS interface defines the operating system specific operations.

type Pipeline added in v1.2.0

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

Pipeline manages a pool of workers to process image downloads.

func NewPipeline added in v1.2.0

func NewPipeline(cfg *Config, store *ImageStore, processor ProcessFunc) *Pipeline

NewPipeline creates a new pipeline with the given configuration and store.

func (*Pipeline) SendCommand added in v1.2.0

func (p *Pipeline) SendCommand(cmd StateCmd)

SendCommand sends a state mutation command to the pipeline manager.

func (*Pipeline) Start added in v1.2.0

func (p *Pipeline) Start(workerCount int)

Start starts the worker pool.

func (*Pipeline) Stop added in v1.2.0

func (p *Pipeline) Stop()

Stop stops the pipeline and waits for workers to finish.

func (*Pipeline) Submit added in v1.2.0

func (p *Pipeline) Submit(job DownloadJob) bool

Submit submits a job to the pipeline. Returns false if pipeline is stopped or full (though buffer is large).

type Plugin added in v1.0.0

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

Plugin is the main struct for the wallpaper downloader plugin.

func GetInstance added in v0.6.1

func GetInstance() *Plugin

GetInstance returns the singleton instance of the wallpaper plugin.

func (*Plugin) Activate added in v1.0.0

func (wp *Plugin) Activate()

Activate starts the wallpaper rotation.

func (*Plugin) ChangeWallpaperFrequency added in v1.0.0

func (wp *Plugin) ChangeWallpaperFrequency(newFrequency Frequency)

ChangeWallpaperFrequency changes the wallpaper frequency.

func (*Plugin) ClearCache added in v1.3.0

func (wp *Plugin) ClearCache()

ClearCache clears the entire wallpaper cache (memory and disk). This is the "Panic Button" functionality.

func (*Plugin) CreatePrefsPanel added in v1.0.0

func (wp *Plugin) CreatePrefsPanel(sm setting.SettingsManager) *fyne.Container

CreatePrefsPanel creates a preferences widget for wallpaper settings

func (*Plugin) CreateTrayMenuItems added in v1.0.0

func (wp *Plugin) CreateTrayMenuItems() []*fyne.MenuItem

CreateTrayMenuItems creates the menu items for the tray menu

func (*Plugin) Deactivate added in v1.0.0

func (wp *Plugin) Deactivate()

Deactivate stops the wallpaper rotation, any active downloads, and cleans up.

func (*Plugin) DeleteCurrentImage added in v1.0.0

func (wp *Plugin) DeleteCurrentImage()

DeleteCurrentImage deletes the current wallpaper image from the filesystem and updates the history.

func (*Plugin) FocusProviderSettings added in v1.6.0

func (wp *Plugin) FocusProviderSettings(providerName string) error

FocusProviderSettings opens the preferences and focuses the settings for the given provider.

func (*Plugin) GetCurrentImage added in v1.0.0

func (wp *Plugin) GetCurrentImage() provider.Image

GetCurrentImage returns the current wallpaper image information.

func (*Plugin) GetOS added in v1.4.0

func (wp *Plugin) GetOS() OS

GetOS returns the underlying OS interface.

func (*Plugin) GetProviderTitle added in v1.5.0

func (wp *Plugin) GetProviderTitle(providerID string) string

GetProviderTitle returns the display title of a provider, falling back to ID.

func (*Plugin) GetWallhavenURL added in v1.0.0

func (wp *Plugin) GetWallhavenURL(apiURL string) *url.URL

GetWallhavenURL returns the Wallhaven URL for the given API URL.

func (*Plugin) Init added in v1.0.0

func (wp *Plugin) Init(manager ui.PluginManager)

Init initializes the wallpaper plugin with the given PluginManager.

func (*Plugin) IsPaused added in v1.0.0

func (wp *Plugin) IsPaused() bool

IsPaused returns true if the wallpaper change frequency is set to Never.

func (*Plugin) Name added in v1.0.0

func (wp *Plugin) Name() string

Name returns the name of the plugin.

func (*Plugin) OpenAddCollectionUI added in v1.4.0

func (wp *Plugin) OpenAddCollectionUI(urlStr string) error

OpenAddCollectionUI opens the preferences window and prompts to add the collection.

func (*Plugin) ProcessImageJob added in v1.2.0

func (wp *Plugin) ProcessImageJob(ctx context.Context, job DownloadJob) (provider.Image, error)

ProcessImageJob processes a single image download job. It implements the Source + Derivative architecture: 1. Ensure Master (Raw) exists. 2. Ensure Derivative (Processed) exists (generating from Master if needed).

func (*Plugin) RefreshImagesAndPulse added in v1.0.0

func (wp *Plugin) RefreshImagesAndPulse()

RefreshImagesAndPulse refreshes the list of images and pulses the image.

func (*Plugin) SetNextWallpaper added in v1.0.0

func (wp *Plugin) SetNextWallpaper()

SetNextWallpaper sets the next wallpaper, will respect shuffle toggle This is a PUBLIC method acting as a Trigger.

func (*Plugin) SetPauseChangeCallback added in v1.0.0

func (wp *Plugin) SetPauseChangeCallback(callback func(bool))

SetPauseChangeCallback sets the callback function to be called when pause state changes.

func (*Plugin) SetPreviousWallpaper added in v1.0.0

func (wp *Plugin) SetPreviousWallpaper()

SetPreviousWallpaper sets the previous wallpaper in the list. This is a PUBLIC method acting as a Trigger.

func (*Plugin) SetShuffleImage added in v1.0.0

func (wp *Plugin) SetShuffleImage(enable bool)

SetShuffleImage enables or disables random wallpaper selection.

func (*Plugin) SetSmartFit added in v1.0.0

func (wp *Plugin) SetSmartFit(enabled bool)

SetSmartFit enables or disables smart cropping.

func (*Plugin) StartNightlyRefresh added in v1.0.0

func (wp *Plugin) StartNightlyRefresh()

StartNightlyRefresh starts the goroutine for nightly wallpaper refresh.

func (*Plugin) StopNightlyRefresh added in v1.0.0

func (wp *Plugin) StopNightlyRefresh()

StopNightlyRefresh signals the nightly refresh goroutine to stop.

func (*Plugin) ToggleFavorite added in v1.5.0

func (wp *Plugin) ToggleFavorite()

ToggleFavorite adds or removes the current image from the favorites collection.

func (*Plugin) TogglePause added in v1.0.0

func (wp *Plugin) TogglePause()

TogglePause toggles the wallpaper change frequency between paused (Never) and the previous frequency.

func (*Plugin) TogglePauseAction added in v1.0.0

func (wp *Plugin) TogglePauseAction()

TogglePauseAction triggers the UI action for pausing/resuming if available, otherwise toggles logic directly.

func (*Plugin) TriggerFavorite added in v1.5.1

func (wp *Plugin) TriggerFavorite()

TriggerFavorite adds the current image to favorites if supported, respecting Strict Add logic. This is used by the Global Hotkey.

func (*Plugin) TriggerOpenSettings added in v1.5.1

func (wp *Plugin) TriggerOpenSettings()

TriggerOpenSettings is a helper to open the main preferences window. This is used by the Global Hotkey.

func (*Plugin) ViewCurrentImageOnWeb added in v1.0.0

func (wp *Plugin) ViewCurrentImageOnWeb()

ViewCurrentImageOnWeb opens the current image in the default browser.

type ProcessFunc added in v1.2.0

type ProcessFunc func(ctx context.Context, job DownloadJob) (provider.Image, error)

ProcessFunc is the function signature for processing a job.

type ProcessResult added in v1.2.0

type ProcessResult struct {
	Image provider.Image
	Error error
}

ProcessResult represents the result of a processed image.

type ProviderFactory added in v1.1.0

type ProviderFactory func(cfg *Config, client *http.Client) provider.ImageProvider

ProviderFactory defines the function signature for creating a provider.

type SmartFitMode added in v1.3.0

type SmartFitMode int

SmartFitMode defines the behavior of the Smart Fit algorithm

const (
	SmartFitOff        SmartFitMode = 0 // Disabled (Legacy: SmartFit=false)
	SmartFitNormal     SmartFitMode = 1 // Strict Aspect Ratio (Legacy: SmartFit=true, Unlock=false)
	SmartFitAggressive SmartFitMode = 2 // Relaxed Aspect Ratio (Legacy: SmartFit=true, Unlock=true)
)

func ParseSmartFitMode added in v1.3.0

func ParseSmartFitMode(s string) SmartFitMode

ParseSmartFitMode parses a string into a SmartFitMode

func (SmartFitMode) String added in v1.3.0

func (m SmartFitMode) String() string

type SmartImageProcessor added in v1.6.1

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

SmartImageProcessor is an image processor that uses smart cropping.

func NewSmartImageProcessor added in v1.6.1

func NewSmartImageProcessor(os OS, config *Config, pigo *pigo.Pigo) *SmartImageProcessor

NewSmartImageProcessor creates a new processor instance.

func (*SmartImageProcessor) CheckCompatibility added in v1.6.1

func (c *SmartImageProcessor) CheckCompatibility(width, height int) error

CheckCompatibility checks if an image of given dimensions is compatible with Smart Fit settings. CheckCompatibility checks if an image of given dimensions is compatible with Smart Fit settings.

func (*SmartImageProcessor) DecodeImage added in v1.6.1

func (c *SmartImageProcessor) DecodeImage(ctx context.Context, imgBytes []byte, contentType string) (image.Image, string, error)

DecodeImage decodes an image from a byte slice with context awareness.

func (*SmartImageProcessor) EncodeImage added in v1.6.1

func (c *SmartImageProcessor) EncodeImage(ctx context.Context, img image.Image, contentType string) ([]byte, error)

EncodeImage encodes an image to a byte slice with context awareness.

func (*SmartImageProcessor) FitImage added in v1.6.1

func (c *SmartImageProcessor) FitImage(ctx context.Context, img image.Image) (image.Image, error)

FitImage fits an image with context awareness.

func (*SmartImageProcessor) GetLastStats added in v1.6.1

func (c *SmartImageProcessor) GetLastStats() FaceDetectionStats

GetLastStats returns the diagnostics from the last fit operation.

type StateCmd added in v1.2.0

type StateCmd struct {
	Type    CmdType
	Payload interface{}
}

type TuningConfig added in v1.6.2

type TuningConfig struct {
	// Smart Fit 2.0 (Core)
	AspectThreshold      float64 `json:"aspect_threshold"`      // Default: 0.9 (Base tolerance)
	AggressiveMultiplier float64 `json:"aggressive_multiplier"` // Default: 1.9 (Flexibility mode boost)

	// Dual Safety (v1.6.2)
	MinEnergyThreshold           float64 `json:"min_energy_threshold"`             // Default: 0.05
	FeetGuardRatio               float64 `json:"feet_guard_ratio"`                 // Default: 0.5 (Legacy/Simple check)
	FeetGuardSlackThreshold      float64 `json:"feet_guard_slack_threshold"`       // Default: 0.8 (Slack-aware check)
	FeetGuardSlackRelaxed        float64 `json:"feet_guard_slack_relaxed"`         // Default: 1.00 (Fully relaxed for high energy)
	FeetGuardHighEnergyThreshold float64 `json:"feet_guard_high_energy_threshold"` // Default: 0.2 (Trust SmartCrop more)
	EnergyThumbSize              int     `json:"energy_thumb_size"`                // Default: 128 (Performance/Accuracy balance)

	// Face Logic (v1.6.1+)
	FaceRescueQThreshold    float32 `json:"face_rescue_q_threshold"`    // Default: 20.0
	FaceBottomEdgeThreshold float64 `json:"face_bottom_edge_threshold"` // Default: 0.7 (Bottom 30% danger zone)
	FaceBottomEdgeMinQ      float32 `json:"face_bottom_edge_min_q"`     // Default: 20.0 (Req higher Q for edges)
	FaceIoUThreshold        float64 `json:"face_iou_threshold"`         // Default: 0.2 (Clustering)
	FaceScaleFactor         float64 `json:"face_scale_factor"`          // Default: 1.1 (pigo internal)
	FaceDetectConfidence    float64 `json:"face_detect_confidence"`     // Default: 10.0 (Base filter)
	FaceDetectMinSizePct    int     `json:"face_detect_min_size_pct"`   // Default: 1 (1% of min dim)
	FaceDetectShift         float64 `json:"face_detect_shift"`          // Default: 0.1 (Stride)

	// Encoding
	EncodingQuality int `json:"encoding_quality"` // Default: 95
}

TuningConfig holds the internal magic numbers and thresholds for image processing. These are currently static but centralized here to allow for future remote configuration.

func DefaultTuningConfig added in v1.6.2

func DefaultTuningConfig() TuningConfig

DefaultTuningConfig returns the standard values for Spice 1.6.2.

type URLType added in v0.4.0

type URLType int

URLType indicates the type of image source (Search or Collection).

const (
	// Unknown type represents a web URL pattern not recognized nor supported by this application.
	Unknown URLType = iota
	// Search type represents a web search query url pattern.
	Search
	// Favorites type represents a web favorites url pattern.
	Favorites
)

func (URLType) String added in v0.4.0

func (qt URLType) String() string

Directories

Path Synopsis
providers

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址