Package xprop

import "github.com/BurntSushi/xgbutil/xprop"
Overview
Index

Overview ▾

Package xprop provides a cache for interning atoms and helper functions for dealing with GetProperty and ChangeProperty X requests.

Atoms

Atoms in X are interned, meaning that strings are assigned unique integer identifiers. This minimizes the amount of data transmitted over an X connection.

Once atoms have been interned, they are never changed while the X server is running. xgbutil takes advantage of this invariant and will only issue an intern atom request once and cache the result.

To use the xprop package to intern an atom, use Atom:

atom, err := xprop.Atom(XUtilValue, "THE_ATOM_NAME", false)
if err == nil {
	println("The atom number: ", atom.Atom)
}

The 'false' parameter corresponds to the 'only_if_exists' parameter of the X InternAtom request. When it's false, the atom being interned always returns a non-zero atom number---even if the string being interned hasn't been interned before. If 'only_if_exists' is true, the atom being interned will return a 0 atom number if it hasn't already been interned.

The typical case is to set 'only_if_exists' to false. To this end, xprop.Atm is an alias that always sets this value to false.

The reverse can also be done: getting an atom string if you have an atom number. This can be done with the xprop.AtomName function.

Properties

The other facility of xprop is to help with the use of GetProperty and ChangeProperty. Please see the source code of the ewmh package for plenty of examples.

func Atm

func Atm(xu *xgbutil.XUtil, name string) (xproto.Atom, error)

Atm is a short alias for Atom in the common case of interning an atom. Namely, interning the atom always succeeds. (If the atom does not already exist, a new one is created.)

func Atom

func Atom(xu *xgbutil.XUtil, name string,
    onlyIfExists bool) (xproto.Atom, error)

Atom interns an atom and panics if there is any error.

func AtomName

func AtomName(xu *xgbutil.XUtil, aid xproto.Atom) (string, error)

AtomName fetches a string representation of an ATOM given its integer id.

func AtomToUint

func AtomToUint(ids []xproto.Atom) []uint

AtomToInt is a covenience function for converting []xproto.Atom to []uint.

func ChangeProp

func ChangeProp(xu *xgbutil.XUtil, win xproto.Window, format byte, prop string,
    typ string, data []byte) error

ChangeProperty abstracts the semi-nastiness of xgb.ChangeProperty.

func ChangeProp32

func ChangeProp32(xu *xgbutil.XUtil, win xproto.Window, prop string, typ string,
    data ...uint) error

ChangeProperty32 makes changing 32 bit formatted properties easier by constructing the raw X data for you.

func GetProperty

func GetProperty(xu *xgbutil.XUtil, win xproto.Window, atom string) (
    *xproto.GetPropertyReply, error)

GetProperty abstracts the messiness of calling xgb.GetProperty.

func PropValAtom

func PropValAtom(xu *xgbutil.XUtil, reply *xproto.GetPropertyReply,
    err error) (string, error)

PropValAtom transforms a GetPropertyReply struct into an ATOM name. The property reply must be in 32 bit format.

func PropValAtoms

func PropValAtoms(xu *xgbutil.XUtil, reply *xproto.GetPropertyReply,
    err error) ([]string, error)

PropValAtoms is the same as PropValAtom, except that it returns a slice of atom names. Also must be 32 bit format. This is a method of an XUtil struct, unlike the other 'PropVal...' functions.

func PropValNum

func PropValNum(reply *xproto.GetPropertyReply, err error) (uint, error)

PropValNum transforms a GetPropertyReply struct into an unsigned integer. Useful when the property value is a single integer.

func PropValNum64

func PropValNum64(reply *xproto.GetPropertyReply, err error) (int64, error)

PropValNum64 transforms a GetPropertyReply struct into a 64 bit integer. Useful when the property value is a single integer.

func PropValNums

func PropValNums(reply *xproto.GetPropertyReply, err error) ([]uint, error)

PropValNums is the same as PropValNum, except that it returns a slice of integers. Also must be 32 bit format.

func PropValStr

func PropValStr(reply *xproto.GetPropertyReply, err error) (string, error)

PropValStr transforms a GetPropertyReply struct into a string. Useful when the property value is a null terminated string represented by integers. Also must be 8 bit format.

func PropValStrs

func PropValStrs(reply *xproto.GetPropertyReply, err error) ([]string, error)

PropValStrs is the same as PropValStr, except that it returns a slice of strings. The raw byte string is a sequence of null terminated strings, which is translated into a slice of strings.

func PropValWindow

func PropValWindow(reply *xproto.GetPropertyReply,
    err error) (xproto.Window, error)

PropValWindow transforms a GetPropertyReply struct into an X resource window identifier. The property reply must be in 32 bit format.

func PropValWindows

func PropValWindows(reply *xproto.GetPropertyReply,
    err error) ([]xproto.Window, error)

PropValWindows is the same as PropValWindow, except that it returns a slice of identifiers. Also must be 32 bit format.

func StrToAtoms

func StrToAtoms(xu *xgbutil.XUtil, atomNames []string) ([]uint, error)

StrToAtoms is a convenience function for converting []string to []uint32 atoms. NOTE: If an atom name in the list doesn't exist, it will be created.

func WindowToInt

func WindowToInt(ids []xproto.Window) []uint

WindowToUint is a covenience function for converting []xproto.Window to []uint.