prefs

Documentation

Overview

Package prefs provides a publish-subscription API for global settinsg management. It exists as a schema-less version of the GSettings API.

Index

• Variables
• func AsyncLoadSaved(ctx context.Context, done func(error))
• func Hide(props ...Prop)
• func LoadData(data []byte) error
• func Order(props ...Prop)
• func OrderBefore(prop, isBefore Prop)
• func ReadSavedData(ctx context.Context) ([]byte, error)
• func RegisterProp(p Prop)
• type Bool
  • func NewBool(v bool, prop PropMeta) *Bool
  • func (b *Bool) AnyPublish(v interface{}) error
  • func (b *Bool) AnyValue() interface{}
  • func (b *Bool) CreateWidget(ctx context.Context, save func()) gtk.Widgetter
  • func (b *Bool) MarshalJSON() ([]byte, error)
  • func (b *Bool) Publish(v bool)
  • func (b *Bool) UnmarshalJSON(blob []byte) error
  • func (b *Bool) Value() bool
  • func (b *Bool) WidgetIsLarge() bool
• type EnumList
  • func NewEnumList[T comparable](def T, prop EnumListMeta[T]) *EnumList[T]
  • func (l *EnumList[T]) CreateWidget(ctx context.Context, save func()) gtk.Widgetter
  • func (l *EnumList[T]) IsValid(str T) bool
  • func (l *EnumList[T]) MarshalJSON() ([]byte, error)
  • func (l *EnumList[T]) Publish(v T)
  • func (l *EnumList[T]) UnmarshalJSON(blob []byte) error
  • func (l *EnumList[T]) Value() T
  • func (l *EnumList[T]) WidgetIsLarge() bool
• type EnumListMeta
• type ID
• type Int
  • func NewInt(v int, meta IntMeta) *Int
  • func (i *Int) CreateWidget(ctx context.Context, save func()) gtk.Widgetter
  • func (i *Int) MarshalJSON() ([]byte, error)
  • func (i *Int) Publish(v int)
  • func (i *Int) UnmarshalJSON(b []byte) error
  • func (i *Int) Value() int
  • func (i *Int) WidgetIsLarge() bool
• type IntMeta
  • func (m IntMeta) Meta() PropMeta
• type ListedSection
  • func ListProperties(ctx context.Context) []ListedSection
• type LocalizedProp
• type Prop
• type PropMeta
  • func (p PropMeta) EnglishName() string
  • func (p PropMeta) EnglishSectionName() string
  • func (p PropMeta) ID() ID
  • func (p PropMeta) Meta() PropMeta
• type Pubsub
  • func NewPubsub() *Pubsub
  • func (p *Pubsub) Publish()
  • func (p *Pubsub) Pubsubber() *Pubsub
  • func (p *Pubsub) Subscribe(f func()) (rm func())
  • func (p *Pubsub) SubscribeInit(f func())
  • func (p *Pubsub) SubscribeWidget(widget gtk.Widgetter, f func())
• type Slug
  • func Slugify(any string) Slug
• type Snapshot
  • func TakeSnapshot() Snapshot
  • func (s Snapshot) JSON() []byte
  • func (s Snapshot) Save(ctx context.Context) error
• type String
  • func NewString(def string, prop StringMeta) *String
  • func (s *String) CreateWidget(ctx context.Context, save func()) gtk.Widgetter
  • func (s *String) MarshalJSON() ([]byte, error)
  • func (s *String) Publish(v string) error
  • func (s *String) UnmarshalJSON(blob []byte) error
  • func (s *String) Value() string
  • func (s *String) WidgetIsLarge() bool
• type StringMeta
  • func (m StringMeta) Meta() PropMeta

Variables

var ErrInvalidAnyType = errors.New("incorrect value type")

ErrInvalidAnyType is returned by a preference property if it has the wrong type.

Functions

func AsyncLoadSaved

func AsyncLoadSaved(ctx context.Context, done func(error))

AsyncLoadSaved asynchronously loads the saved preferences.

func Hide

func Hide(props ...Prop)

Hide hides the given props from showing up in methods that snapshot properties. This is useful for the main application to hide the settings of certain libraries.

Props that are hidden cannot be unhidden, so only call this method during initialization on a constant list of properties.

func LoadData

func LoadData(data []byte) error

LoadData loads the given JSON data (usually returned from ReadSavedData) directly into the global preference values.

func Order

func Order(props ...Prop)

Order registers the given names for ordering properties. It is only valid within the same sections.

func OrderBefore

func OrderBefore(prop, isBefore Prop)

func ReadSavedData

func ReadSavedData(ctx context.Context) ([]byte, error)

ReadSavedData reads the saved preferences from a predetermined location. Users should give the returned byte slice to LoadData. A nil byte slice is a valid value.

func RegisterProp

func RegisterProp(p Prop)

RegisterProp registers a property globally. This function should ideally be called only during init.

Types

type Bool

type Bool struct {
	Pubsub
	PropMeta
	// contains filtered or unexported fields
}

Bool is a preference property of type boolean.

func NewBool

func NewBool(v bool, prop PropMeta) *Bool

NewBool creates a new boolean with the given default value and properties.

func (*Bool) AnyPublish

func (b *Bool) AnyPublish(v interface{}) error

AnyPublish implements Prop.

func (*Bool) AnyValue

func (b *Bool) AnyValue() interface{}

AnyValue implements Prop.

func (*Bool) CreateWidget

func (b *Bool) CreateWidget(ctx context.Context, save func()) gtk.Widgetter

CreateWidget creates a *gtk.Switch.

func (*Bool) MarshalJSON

func (b *Bool) MarshalJSON() ([]byte, error)

func (*Bool) Publish

func (b *Bool) Publish(v bool)

Publish publishes the new boolean.

func (*Bool) UnmarshalJSON

func (b *Bool) UnmarshalJSON(blob []byte) error

func (*Bool) Value

func (b *Bool) Value() bool

Value loads the internal boolean.

func (*Bool) WidgetIsLarge

func (b *Bool) WidgetIsLarge() bool

WidgetIsLarge returns false.

type EnumList

type EnumList[T comparable] struct {
	Pubsub
	EnumListMeta[T]
	// contains filtered or unexported fields
}

EnumList is a preference property of type stringer.

func NewEnumList

func NewEnumList[T comparable](def T, prop EnumListMeta[T]) *EnumList[T]

NewEnumList creates a new EnumList instance.

func (*EnumList[T]) CreateWidget

func (l *EnumList[T]) CreateWidget(ctx context.Context, save func()) gtk.Widgetter

CreateWidget creates either a *gtk.Entry or a *gtk.TextView.

func (*EnumList[T]) IsValid

func (l *EnumList[T]) IsValid(str T) bool

IsValid returns true if the given value is a valid enum value.

func (*EnumList[T]) MarshalJSON

func (l *EnumList[T]) MarshalJSON() ([]byte, error)

func (*EnumList[T]) Publish

func (l *EnumList[T]) Publish(v T)

Publish publishes the new value. If the value isn't within Options, then the method will panic.

func (*EnumList[T]) UnmarshalJSON

func (l *EnumList[T]) UnmarshalJSON(blob []byte) error

func (*EnumList[T]) Value

func (l *EnumList[T]) Value() T

Value gets the current enum value.

func (*EnumList[T]) WidgetIsLarge

func (l *EnumList[T]) WidgetIsLarge() bool

WidgetIsLarge returns false.

type EnumListMeta

type EnumListMeta[T comparable] struct {
	PropMeta
	Validate func(T) error
	Options  []T
}

EnumListMeta is the metadata of an EnumList.

type ID

type ID Slug

ID describes a property ID type.

type Int

type Int struct {
	Pubsub
	IntMeta
	// contains filtered or unexported fields
}

Int is a preference property of type int.

func NewInt

func NewInt(v int, meta IntMeta) *Int

NewInt creates a new int(32) with the given default value and properties.

func (*Int) CreateWidget

func (i *Int) CreateWidget(ctx context.Context, save func()) gtk.Widgetter

CreateWidget creates either a *gtk.Scale or a *gtk.SpinButton.

func (*Int) MarshalJSON

func (i *Int) MarshalJSON() ([]byte, error)

func (*Int) Publish

func (i *Int) Publish(v int)

Publish publishes the new int.

func (*Int) UnmarshalJSON

func (i *Int) UnmarshalJSON(b []byte) error

func (*Int) Value

func (i *Int) Value() int

Value loads the internal int.

func (*Int) WidgetIsLarge

func (i *Int) WidgetIsLarge() bool

WidgetIsLarge is true if Slider is true.

type IntMeta

type IntMeta struct {
	Name        locale.Localized
	Section     locale.Localized
	Description locale.Localized
	Min         int
	Max         int
	Slider      bool
}

IntMeta wraps PropMeta for Int.

func (IntMeta) Meta

func (m IntMeta) Meta() PropMeta

Meta returns the PropMeta for IntMeta. It implements Prop.

type ListedSection

type ListedSection struct {
	Name  string // localized
	Props []LocalizedProp
	// contains filtered or unexported fields
}

ListedSection holds a list of properties returned from ListProperties.

func ListProperties

func ListProperties(ctx context.Context) []ListedSection

ListProperties enumerates all known global properties into a map of

type LocalizedProp

type LocalizedProp struct {
	Prop
	Name        string
	Description string
}

LocalizedProp wraps Prop and localizes its name and description.

type Prop

type Prop interface {
	json.Marshaler
	json.Unmarshaler
	// Meta returns the property's meta.
	Meta() PropMeta
	// Pubsubber returns the internal publisher/subscriber instance.
	Pubsubber() *Pubsub
	// CreateWidget creates the widget containing the value of this property.
	CreateWidget(ctx context.Context, save func()) gtk.Widgetter
	// WidgetIsLarge returns true if the widget created by CreateWidget should
	// take up space and shouldn't be inlined.
	WidgetIsLarge() bool
}

Prop describes a property type.

type PropMeta

type PropMeta struct {
	Name        locale.Localized
	Section     locale.Localized
	Description locale.Localized
}

PropMeta describes the metadata of a preference value.

func (PropMeta) EnglishName

func (p PropMeta) EnglishName() string

EnglishName returns the unlocalized name.

func (PropMeta) EnglishSectionName

func (p PropMeta) EnglishSectionName() string

EnglishSectionName returns the unlocalized section name.

func (PropMeta) ID

func (p PropMeta) ID() ID

PropID implements Prop.

func (PropMeta) Meta

func (p PropMeta) Meta() PropMeta

Meta returns itself. It implements Prop.

type Pubsub

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

Pubsub provides a simple publish-subscribe API. This instance is safe to use concurrently.

func NewPubsub

func NewPubsub() *Pubsub

NewPubsub creates a new Pubsub instance.

func (*Pubsub) Publish

func (p *Pubsub) Publish()

Publish publishes changes to all subscribe routines.

func (*Pubsub) Pubsubber

func (p *Pubsub) Pubsubber() *Pubsub

Pubsubber returns itself.

func (*Pubsub) Subscribe

func (p *Pubsub) Subscribe(f func()) (rm func())

Subscribe adds f into the pubsub's subscription queue. f will always be invoked in the main thread.

func (*Pubsub) SubscribeInit

func (p *Pubsub) SubscribeInit(f func())

SubscribeInit is like Subscribe, except you can't unsubscribe, the callback is not called, and the method is not thread-safe. It is only meant to be called in init() functions.

func (*Pubsub) SubscribeWidget

func (p *Pubsub) SubscribeWidget(widget gtk.Widgetter, f func())

SubscribeWidget subscribes the given widget and callback to changes. If rm is called, then the subscription is removed. The given callback will be called once in the receiving goroutine to signal a change. It is guaranteed for the callback to only be consistently called on that goroutine.

type Slug

type Slug string

Slug describes a particular slug format type.

func Slugify

func Slugify(any string) Slug

Slugify turns any string into an ID string.

type Snapshot

type Snapshot map[string]json.RawMessage

Snapshot describes a snapshot of the preferences state.

func TakeSnapshot

func TakeSnapshot() Snapshot

TakeSnapshot takes a snapshot of the global preferences into a flat map. This function should only be called on the main thread, but the returned snapshot can be used anywhere.

func (Snapshot) JSON

func (s Snapshot) JSON() []byte

JSON marshals the snapshot as JSON. Any error that arises from marshaling the JSON is assumed to be the user tampering with it.

func (Snapshot) Save

func (s Snapshot) Save(ctx context.Context) error

Save atomically saves the snapshot to file.

type String

type String struct {
	Pubsub
	StringMeta
	// contains filtered or unexported fields
}

String is a preference property of type string.

func NewString

func NewString(def string, prop StringMeta) *String

NewString creates a new String instance.

func (*String) CreateWidget

func (s *String) CreateWidget(ctx context.Context, save func()) gtk.Widgetter

CreateWidget creates either a *gtk.Entry or a *gtk.TextView.

func (*String) MarshalJSON

func (s *String) MarshalJSON() ([]byte, error)

func (*String) Publish

func (s *String) Publish(v string) error

Publish publishes the new string value. An error is returned and nothing is published if the string fails the verifier.

func (*String) UnmarshalJSON

func (s *String) UnmarshalJSON(blob []byte) error

func (*String) Value

func (s *String) Value() string

Value returns the internal string value.

func (*String) WidgetIsLarge

func (s *String) WidgetIsLarge() bool

WidgetIsLarge returns true.

type StringMeta

type StringMeta struct {
	Name        locale.Localized
	Section     locale.Localized
	Description locale.Localized
	Placeholder locale.Localized
	Validate    func(string) error
	Multiline   bool
}

StringMeta is the metadata of a string.

func (StringMeta) Meta

func (m StringMeta) Meta() PropMeta

Meta returns the PropMeta for StringMeta. It implements Prop.