Package icccm

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

Overview ▾

Package icccm provides an API for a portion of the ICCCM, namely, getters and setters for many of the properties specified in the ICCCM. There is also a smattering of support for other protocols specified by ICCCM. For example, to satisfy the WM_DELETE_WINDOW protocol, package icccm provides 'IsDeleteProtocol' which returns whether a ClientMessage event satisfies the WM_DELETE_WINDOW protocol.

If a property has values that aren't simple strings or integers, struct types are provided to organize the data. In particular, WM_NORMAL_HINTS and WM_HINTS.

Also note that properties like WM_NORMAL_HINTS and WM_HINTS contain a 'Flags' field (a bit mask) that specifies which values are "active". This is of importance when setting and reading WM_NORMAL_HINTS and WM_HINTS; one must make sure the appropriate bit is set in Flags.

For example, you might want to check if a window has specified a resize increment in the WM_NORMAL_HINTS property. The values in the corresponding NormalHints struct are WidthInc and HeightInc. So to check if such values exist *and* should be used:

normalHints, err := icccm.WmNormalHintsGet(XUtilValue, window-id)
if err != nil {
	// handle error
}
if normalHints.Flags&icccm.SizeHintPResizeInc > 0 {
	// Use normalHints.WidthInc and normalHints.HeightInc
}

When you should use icccm

Although the ICCCM is extremely old, a lot of it is still used. In fact, the EWMH spec itself specifically states that the ICCCM should still be used unless otherwise noted by the EWMH. For example, WM_HINTS and WM_NORMAL_HINTS are still used, but _NET_WM_NAME replaces WM_NAME.

With that said, many applications (like xterm or LibreOffice) have not been updated to be fully EWMH compliant. Therefore, code that finds a window's name often looks like this:

winName, err := ewmh.WmNameGet(XUtilValue, window-id)
if err != nil || winName == "" {
	winName, err = icccm.WmNameGet(XUtilValue, window-id)
	if err != nill || winName == "" {
		winName = "N/A"
	}
}

Something similar can be said for the _NET_WM_ICON and the IconPixmap field in WM_HINTS.

Naming scheme

The naming scheme is precisely the same as the one found in the ewmh package. The documentation for the ewmh package describes the naming scheme in more detail. The only difference (currently) is that the icccm package only contains functions ending in "Get" and "Set". It is planned to add "Req" functions. (An example of a Req function would be to send a ClientMessage implementing the WM_DELETE_WINDOW protocol to a client window.)

Index ▾

Constants
func IsDeleteProtocol(X *xgbutil.XUtil, ev xevent.ClientMessageEvent) bool
func IsFocusProtocol(X *xgbutil.XUtil, ev xevent.ClientMessageEvent) bool
func WmClassSet(xu *xgbutil.XUtil, win xproto.Window, class *WmClass) error
func WmClientMachineGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)
func WmClientMachineSet(xu *xgbutil.XUtil, win xproto.Window, client string) error
func WmColormapWindowsGet(xu *xgbutil.XUtil, win xproto.Window) ([]xproto.Window, error)
func WmColormapWindowsSet(xu *xgbutil.XUtil, win xproto.Window, windows []xproto.Window) error
func WmHintsSet(xu *xgbutil.XUtil, win xproto.Window, hints *Hints) error
func WmIconNameGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)
func WmIconNameSet(xu *xgbutil.XUtil, win xproto.Window, name string) error
func WmIconSizeSet(xu *xgbutil.XUtil, win xproto.Window, icondim *IconSize) error
func WmNameGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)
func WmNameSet(xu *xgbutil.XUtil, win xproto.Window, name string) error
func WmNormalHintsSet(xu *xgbutil.XUtil, win xproto.Window, nh *NormalHints) error
func WmProtocolsGet(xu *xgbutil.XUtil, win xproto.Window) ([]string, error)
func WmProtocolsSet(xu *xgbutil.XUtil, win xproto.Window, atomNames []string) error
func WmStateSet(xu *xgbutil.XUtil, win xproto.Window, state *WmState) error
func WmTransientForGet(xu *xgbutil.XUtil, win xproto.Window) (xproto.Window, error)
func WmTransientForSet(xu *xgbutil.XUtil, win xproto.Window, transient xproto.Window) error
type Hints
    func WmHintsGet(xu *xgbutil.XUtil, win xproto.Window) (hints *Hints, err error)
type IconSize
    func WmIconSizeGet(xu *xgbutil.XUtil, win xproto.Window) (*IconSize, error)
type NormalHints
    func WmNormalHintsGet(xu *xgbutil.XUtil, win xproto.Window) (nh *NormalHints, err error)
type WmClass
    func WmClassGet(xu *xgbutil.XUtil, win xproto.Window) (*WmClass, error)
type WmState
    func WmStateGet(xu *xgbutil.XUtil, win xproto.Window) (*WmState, error)

Package files

doc.go icccm.go protocols.go

Constants

const (
    HintInput = (1 << iota)
    HintState
    HintIconPixmap
    HintIconWindow
    HintIconPosition
    HintIconMask
    HintWindowGroup
    HintMessage
    HintUrgency
)
const (
    SizeHintUSPosition = (1 << iota)
    SizeHintUSSize
    SizeHintPPosition
    SizeHintPSize
    SizeHintPMinSize
    SizeHintPMaxSize
    SizeHintPResizeInc
    SizeHintPAspect
    SizeHintPBaseSize
    SizeHintPWinGravity
)
const (
    StateWithdrawn = iota
    StateNormal
    StateZoomed
    StateIconic
    StateInactive
)

func IsDeleteProtocol

func IsDeleteProtocol(X *xgbutil.XUtil, ev xevent.ClientMessageEvent) bool

IsDeleteProtocol checks whether a ClientMessage event satisfies the WM_DELETE_WINDOW protocol. Namely, the format must be 32, the type must be the WM_PROTOCOLS atom, and the first data item must be the atom WM_DELETE_WINDOW.

Note that if you're using the xwindow package, you should use the WMGracefulClose method instead of directly using IsDeleteProtocol.

func IsFocusProtocol

func IsFocusProtocol(X *xgbutil.XUtil, ev xevent.ClientMessageEvent) bool

IsFocusProtocol checks whether a ClientMessage event satisfies the WM_TAKE_FOCUS protocol.

func WmClassSet

func WmClassSet(xu *xgbutil.XUtil, win xproto.Window, class *WmClass) error

WM_CLASS set

func WmClientMachineGet

func WmClientMachineGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)

WM_CLIENT_MACHINE get

func WmClientMachineSet

func WmClientMachineSet(xu *xgbutil.XUtil, win xproto.Window,
    client string) error

WM_CLIENT_MACHINE set

func WmColormapWindowsGet

func WmColormapWindowsGet(xu *xgbutil.XUtil,
    win xproto.Window) ([]xproto.Window, error)

WM_COLORMAP_WINDOWS get

func WmColormapWindowsSet

func WmColormapWindowsSet(xu *xgbutil.XUtil, win xproto.Window,
    windows []xproto.Window) error

WM_COLORMAP_WINDOWS set

func WmHintsSet

func WmHintsSet(xu *xgbutil.XUtil, win xproto.Window, hints *Hints) error

WM_HINTS set Make sure to set the flags in the Hints struct correctly!

func WmIconNameGet

func WmIconNameGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)

WM_ICON_NAME get

func WmIconNameSet

func WmIconNameSet(xu *xgbutil.XUtil, win xproto.Window, name string) error

WM_ICON_NAME set

func WmIconSizeSet

func WmIconSizeSet(xu *xgbutil.XUtil, win xproto.Window,
    icondim *IconSize) error

WM_ICON_SIZE set

func WmNameGet

func WmNameGet(xu *xgbutil.XUtil, win xproto.Window) (string, error)

WM_NAME get

func WmNameSet

func WmNameSet(xu *xgbutil.XUtil, win xproto.Window, name string) error

WM_NAME set

func WmNormalHintsSet

func WmNormalHintsSet(xu *xgbutil.XUtil, win xproto.Window,
    nh *NormalHints) error

WM_NORMAL_HINTS set Make sure to set the flags in the NormalHints struct correctly!

func WmProtocolsGet

func WmProtocolsGet(xu *xgbutil.XUtil, win xproto.Window) ([]string, error)

WM_PROTOCOLS get

func WmProtocolsSet

func WmProtocolsSet(xu *xgbutil.XUtil, win xproto.Window,
    atomNames []string) error

WM_PROTOCOLS set

func WmStateSet

func WmStateSet(xu *xgbutil.XUtil, win xproto.Window, state *WmState) error

WM_STATE set

func WmTransientForGet

func WmTransientForGet(xu *xgbutil.XUtil,
    win xproto.Window) (xproto.Window, error)

WM_TRANSIENT_FOR get

func WmTransientForSet

func WmTransientForSet(xu *xgbutil.XUtil, win xproto.Window,
    transient xproto.Window) error

WM_TRANSIENT_FOR set

type Hints

type Hints struct {
    Flags                   uint
    Input, InitialState     uint
    IconX, IconY            int
    IconPixmap, IconMask    xproto.Pixmap
    WindowGroup, IconWindow xproto.Window
}

Hints is a struct that organizes information related to the WM_HINTS property. Once again, I refer you to the ICCCM spec for documentation.

func WmHintsGet

func WmHintsGet(xu *xgbutil.XUtil,
    win xproto.Window) (hints *Hints, err error)

WM_HINTS get

type IconSize

type IconSize struct {
    MinWidth, MinHeight, MaxWidth, MaxHeight, WidthInc, HeightInc uint
}

IconSize is a struct the organizes information related to the WM_ICON_SIZE property. Mostly info about its dimensions.

func WmIconSizeGet

func WmIconSizeGet(xu *xgbutil.XUtil, win xproto.Window) (*IconSize, error)

WM_ICON_SIZE get

type NormalHints

type NormalHints struct {
    Flags                                                   uint
    X, Y                                                    int
    Width, Height, MinWidth, MinHeight, MaxWidth, MaxHeight uint
    WidthInc, HeightInc                                     uint
    MinAspectNum, MinAspectDen, MaxAspectNum, MaxAspectDen  uint
    BaseWidth, BaseHeight, WinGravity                       uint
}

NormalHints is a struct that organizes the information related to the WM_NORMAL_HINTS property. Please see the ICCCM spec for more details.

func WmNormalHintsGet

func WmNormalHintsGet(xu *xgbutil.XUtil,
    win xproto.Window) (nh *NormalHints, err error)

WM_NORMAL_HINTS get

type WmClass

type WmClass struct {
    Instance, Class string
}

WmClass struct contains two data points: the instance and a class of a window.

func WmClassGet

func WmClassGet(xu *xgbutil.XUtil, win xproto.Window) (*WmClass, error)

WM_CLASS get

type WmState

type WmState struct {
    State uint
    Icon  xproto.Window
}

WmState is a struct that organizes information related to the WM_STATE property. Namely, the state (corresponding to a State* constant in this file) and the icon window (probably not used).

func WmStateGet

func WmStateGet(xu *xgbutil.XUtil, win xproto.Window) (*WmState, error)

WM_STATE get