x11

package
v0.50.0 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ModShift   = 0x0001
	ModLock    = 0x0002
	ModControl = 0x0004
	ModMod1    = 0x0008 // typically Alt
	ModMod4    = 0x0040 // typically Super / the Meta (⌘/Windows/logo) key
	ModButton1 = 0x0100
	ModButton2 = 0x0200
	ModButton3 = 0x0400
)

Modifier / button state-mask bits carried in pointer and key events.

View Source 
const (
	Button1         = 1 // left
	Button2         = 2 // middle
	Button3         = 3 // right
	ButtonWheelUp   = 4
	ButtonWheelDown = 5
)

Pointer button numbers as reported in a Button event's detail byte.

View Source 
const (
	VisualStaticGray  = xproto.VisualStaticGray
	VisualGrayScale   = xproto.VisualGrayScale
	VisualStaticColor = xproto.VisualStaticColor
	VisualPseudoColor = xproto.VisualPseudoColor
	VisualTrueColor   = xproto.VisualTrueColor
	VisualDirectColor = xproto.VisualDirectColor
)

Visual classes and image byte orders, re-exported so a caller needs only this package to read a Setup it got from this package.

View Source 
const (
	EventMaskKeyPress         = 0x00000001
	EventMaskKeyRelease       = 0x00000002
	EventMaskButtonPress      = 0x00000004
	EventMaskButtonRelease    = 0x00000008
	EventMaskPointerMotion    = 0x00000040
	EventMaskButton1Motion    = 0x00000100
	EventMaskExposure         = 0x00008000
	EventMaskStructureNotify  = 0x00020000
	EventMaskButtonMotionMask = 0x00002000
)

Event-mask bits selected on our window. These are the events the host loop translates into toolkit events plus the structure/exposure notifies needed to drive relayout and repaint.

View Source 
const (
	AtomNone      = 0
	AtomPrimary   = 1
	AtomAtom      = 4
	AtomCardinal  = 6
	AtomString    = 31
	AtomWMName    = 39
	AtomWMClass   = 67
	AtomWMHints   = 35
	AtomWMIconNm  = 37
	AtomWMNormalH = 40
)

Predefined atoms (X11/Xatom.h). Interned atoms (WM_PROTOCOLS, WM_DELETE_WINDOW) are obtained at runtime via InternAtom.

View Source 
const CopyFromParent = 0

CopyFromParent (0) is used for a CreateWindow depth/visual/border so the new window inherits the root's TrueColor visual with no BadMatch risk.

View Source 
const CurrentTime = 0

CurrentTime asks the server to substitute its own clock, which is what a selection request should use when it has no user event to point at.

View Source 
const DefaultEventMask = EventMaskKeyPress | EventMaskKeyRelease |
	EventMaskButtonPress | EventMaskButtonRelease |
	EventMaskPointerMotion | EventMaskButtonMotionMask |
	EventMaskExposure | EventMaskStructureNotify

DefaultEventMask is the mask CreateWindow selects for the host window.

Variables

This section is empty.

Functions

func IsModifier 

func IsModifier(ks uint32) bool

IsModifier reports whether ks is a Shift/Control/Alt modifier keysym, which the host tracks for Event.Ctrl/Event.Shift but does not deliver as a character.

func KeysymName 

func KeysymName(ks uint32) string

KeysymName returns the toolkit key name for a keysym, or "" when the keysym has no named binding (it is either printable — see KeysymRune — or unhandled).

func KeysymRune 

func KeysymRune(ks uint32) (rune, bool)

KeysymRune returns the printable rune a keysym produces and whether it is printable. Latin-1 keysyms (0x20–0xff) are their own codepoint; the 0x01000000-flagged range carries a direct Unicode codepoint. The space key is treated as a named key (KeysymName == "Space"), not a rune, so it is excluded here.

func WrapUnix added in v0.3.0 

func WrapUnix(c *net.UnixConn) io.ReadWriteCloser

WrapUnix wraps a dialed *net.UnixConn as an fd-passing transport, which is what lets this back-end hand the server a shared-memory descriptor with MIT-SHM AttachFd. It is xproto.WrapUnix.

Types

type ByteOrder 

type ByteOrder = xproto.ByteOrder

ByteOrder is the wire byte order negotiated at connection setup.

type Conn 

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

Conn is a connection to an X11 server speaking the core protocol over an arbitrary byte stream. It is transport-agnostic: NewConn wraps any io.ReadWriteCloser (a dialed unix socket in production, one half of a net.Pipe in tests) after the setup handshake has completed.

func Handshake 

func Handshake(rw io.ReadWriteCloser, order ByteOrder, authName string, authData []byte) (*Conn, error)

Handshake runs the connection setup over rw and returns a ready Conn.

The setup exchange itself is xproto.Handshake; what this adds is the Conn around it — the sequence counter, the resource-id allocator and the queue that holds events arriving while a synchronous reply is outstanding. order selects the wire byte order; both are valid and the server adopts the client's choice.

func (*Conn) ChangeProperty 

func (c *Conn) ChangeProperty(window, property, typ uint32, format byte, count int, data []byte) error

ChangeProperty replaces property on window with data of the given type and format (8, 16 or 32 bits per element). count is the number of elements; data must already be laid out in the wire order.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the underlying transport.

func (*Conn) ConvertSelection added in v0.19.0 

func (c *Conn) ConvertSelection(requestor, selection, target, property, time uint32) error

ConvertSelection asks the current owner to write selection, converted to target, into property on requestor. The answer does not come back here: the owner replies with a SelectionNotify event, and the data is read from the property afterwards.

func (*Conn) CreateGC 

func (c *Conn) CreateGC(gc, drawable uint32) error

CreateGC creates a graphics context on drawable with default values.

func (*Conn) CreateWindow 

func (c *Conn) CreateWindow(wid, parent uint32, x, y int16, w, h uint16, backPixel, borderPixel, eventMask uint32) error

CreateWindow creates an InputOutput child of parent that inherits the parent's (root's) TrueColor visual and depth via CopyFromParent, setting only the background pixel, border pixel and event mask. Inheriting the visual sidesteps the BadMatch a differing-visual/colormap window would raise, while still landing on the screen's TrueColor root visual.

func (*Conn) FetchKeymap 

func (c *Conn) FetchKeymap() (*Keymap, error)

FetchKeymap fetches the full keyboard mapping for the server's advertised keycode range.

func (*Conn) GetKeyboardMapping 

func (c *Conn) GetKeyboardMapping(first, count uint8) (*Keymap, error)

GetKeyboardMapping fetches the keysym table for keycodes [first, first+count).

func (*Conn) GetProperty added in v0.19.0 

func (c *Conn) GetProperty(window, property, typ uint32, del bool, maxWords uint32) (retTyp uint32, format byte, data []byte, err error)

GetProperty reads up to maxWords 32-bit words of a property, optionally deleting it. It returns the property's type (0 when the property does not exist), its format in bits, and the raw bytes.

Deleting on read is what the requestor side wants: the property is a mailbox the owner wrote into, and leaving it behind would make the next paste read a stale answer if the owner failed to reply.

func (*Conn) GetSelectionOwner added in v0.19.0 

func (c *Conn) GetSelectionOwner(selection uint32) (uint32, error)

GetSelectionOwner returns the window currently owning selection, or 0 when nobody does — which is the normal state of a fresh session, not an error.

func (*Conn) InternAtom 

func (c *Conn) InternAtom(name string, onlyIfExists bool) (uint32, error)

InternAtom resolves (or, when onlyIfExists is false, creates) an atom by name and returns its id.

func (*Conn) MapWindow 

func (c *Conn) MapWindow(wid uint32) error

MapWindow makes the window visible.

func (*Conn) Monitors added in v0.49.0 

func (c *Conn) Monitors(screen int) ([]Monitor, error)

Monitors lists the displays of the given screen, over RANDR 1.5 with XINERAMA and the whole screen as fallbacks. It never returns an empty list without an error.

func (*Conn) NewID 

func (c *Conn) NewID() uint32

NewID allocates a fresh resource identifier from the server-granted range (base | (n & mask)).

func (*Conn) NextEvent 

func (c *Conn) NextEvent() (Event, error)

NextEvent returns the next input/notify event, blocking on the transport until one arrives. Buffered events (queued during a roundTrip) drain first. Error packets encountered on the stream are returned as *XError.

func (*Conn) Order 

func (c *Conn) Order() ByteOrder

Order returns the negotiated wire byte order.

func (*Conn) PushEvent added in v0.21.0 

func (c *Conn) PushEvent(ev Event)

PushEvent returns an event to the head of the queue, so it is delivered by the next NextEvent.

A synchronous exchange -- asking for a selection and waiting for the reply -- has to read events that are not the reply, and those belong to the application, not to the exchange. Dropping them loses a click; handling them there would re-enter the widget tree from inside a paste. Putting them back is the only option that does neither.

func (*Conn) PutImage 

func (c *Conn) PutImage(p *Presenter, drawable, gc uint32, src []byte, srcStride, sx, sy, w, h, dstX, dstY int) error

PutImage blits the w×h rectangle at (sx, sy) of the RGBA source buffer onto drawable at (dstX, dstY) via one or more ZPixmap PutImage requests, each kept under the server's maximum request length by horizontal banding.

func (*Conn) QueryExtension added in v0.3.0 

func (c *Conn) QueryExtension(name string) (present bool, major, firstEvent, firstError byte, err error)

QueryExtension resolves an extension by name, returning whether the server implements it and, if so, its major opcode plus its first event and error codes. It is the standard gate before using any extension's requests.

func (*Conn) QueryShm added in v0.3.0 

func (c *Conn) QueryShm() (*Shm, error)

QueryShm queries the MIT-SHM extension and its version. It returns (nil, nil) — no error — when the server does not implement the extension, so the caller simply falls back to PutImage. FDCapable additionally requires the connection's transport to support descriptor passing.

func (*Conn) Request added in v0.49.0 

func (c *Conn) Request(op string, opcode, data byte, body []byte) ([]byte, error)

Request sends one request and returns its reply — the 32-byte fixed part followed by its additional data — which is what xproto.Requester asks of a connection. op names the request, so a failure says which one rather than only which opcode.

func (*Conn) SendClientMessage added in v0.32.0 

func (c *Conn) SendClientMessage(window, typeAtom, data uint32) error

SendClientMessage sends a 32-bit-format ClientMessage of type typeAtom to window, carrying data as its first data word.

The event-mask is zero, which is what makes this a message to ourselves: the server delivers a masked SendEvent to the clients selecting for it, and an unmasked one to the window's owner. The delivered event has the SendEvent bit set, so a handler can tell it from anything the server generated on its own.

func (*Conn) SendSelectionNotify added in v0.19.0 

func (c *Conn) SendSelectionNotify(requestor, selection, target, property, time uint32) error

SendSelectionNotify answers a SelectionRequest. property is the one the requestor named once the data has been written there, or 0 to refuse — which is the correct answer for a target we cannot produce, and much better than silence, since a requestor with no reply can only wait.

func (*Conn) Seq 

func (c *Conn) Seq() uint16

Seq returns the sequence number of the most recently sent request.

func (*Conn) SetSelectionOwner added in v0.19.0 

func (c *Conn) SetSelectionOwner(owner, selection, time uint32) error

SetSelectionOwner claims (owner non-zero) or releases (owner zero) a selection. The server sends the previous owner a SelectionClear.

Claiming is not the same as having copied: nothing is transferred here. The owner has to stay alive and answer SelectionRequest events for as long as the text is meant to remain pasteable.

func (*Conn) SetWMClass 

func (c *Conn) SetWMClass(window uint32, instance, class string) error

SetWMClass sets WM_CLASS to the two NUL-separated (and NUL-terminated) instance/class strings.

func (*Conn) SetWMName 

func (c *Conn) SetWMName(window uint32, name string) error

SetWMName sets the window's WM_NAME (an ISO-8859-1 STRING property).

func (*Conn) SetWMProtocols 

func (c *Conn) SetWMProtocols(window, wmProtocols uint32, atoms ...uint32) error

SetWMProtocols sets WM_PROTOCOLS to the given atom list (format 32).

func (*Conn) Setup 

func (c *Conn) Setup() *Setup

Setup returns the parsed server setup.

func (*Conn) SupportsFDPassing added in v0.3.0 

func (c *Conn) SupportsFDPassing() bool

SupportsFDPassing reports whether the connection's transport can pass a file descriptor to the server (required for MIT-SHM AttachFd).

func (*Conn) WaitReadable added in v0.21.0 

func (c *Conn) WaitReadable(d time.Duration) (ready, supported bool)

WaitReadable reports whether the server sent something within d, and whether the transport could answer at all.

It exists because the selection protocol has no timeout. A paste asks whoever owns the clipboard and waits for an event that only arrives if that owner is still alive and still answering; an owner that died between claiming and being asked leaves the asker blocked for ever -- a frozen window, on Ctrl+V, with nothing in any log to say why.

It waits for READABILITY rather than putting a deadline on the read, and the difference matters: a deadline that expires between a packet's header and its body leaves the stream desynchronised, turning a slow paste into a broken connection. Waiting first and reading only when there is something to read cannot cut a packet in half.

func (*Conn) WorkArea added in v0.49.0 

func (c *Conn) WorkArea(root uint32) (x, y, w, h int, ok bool)

WorkArea returns the area of the screen rooted at root that a window manager has left for windows: the full screen minus whatever its panels, docks and task bars reserved through _NET_WM_STRUT.

ok is false when nothing publishes the property — a bare X server, an Xvfb, a session whose window manager is not EWMH-compliant — in which case the caller should treat the whole screen as usable, which it is.

It is stated per VIRTUAL DESKTOP, not per monitor: EWMH has no per-monitor work area at all, and a caller with several monitors has to intersect this rectangle with each one. That is the best the protocol offers, and it is what every toolkit on X11 does.

type Depth 

type Depth = xproto.Depth

Depth groups the visuals available at a given colour depth.

type Event 

type Event struct {
	Code   byte   // event type with the SendEvent bit stripped
	Synth  bool   // set if the SendEvent bit was present
	Detail byte   // keycode (key events) or button number (button events)
	Seq    uint16 // low 16 bits of the sequence number
	Time   uint32
	Window uint32 // event window
	RootX  int16
	RootY  int16
	EventX int16
	EventY int16
	State  uint16 // modifier + button mask
	X      int16  // Expose/ConfigureNotify origin
	Y      int16
	Width  uint16 // Expose/ConfigureNotify extent
	Height uint16
	Count  uint16 // Expose: remaining rectangles
	Atom   uint32 // ClientMessage: message type
	Format byte   // ClientMessage: data format
	Data32 uint32 // ClientMessage: first 32-bit data word (WM_DELETE_WINDOW)

	// Selection events. Requestor is the window asking (SelectionRequest) or
	// asked (SelectionNotify); Property is the one to write the answer into, or
	// 0 in a SelectionNotify that refuses.
	Requestor uint32
	Selection uint32
	Target    uint32
	Property  uint32
}

Event is a decoded X11 event in a flat, protocol-level form. The host layer maps it to a toolkit.Event; keeping this struct free of toolkit types lets the whole decoder be unit-tested with no UI dependency.

type FDSender added in v0.3.0 

type FDSender = xproto.FDSender

FDSender is a transport that can pass a descriptor over SCM_RIGHTS.

type Format 

type Format = xproto.Format

Format is one entry of the server's pixmap-format list.

type Keymap 

type Keymap struct {
	Min     uint8
	PerCode int
	Syms    []uint32
}

Keymap holds a decoded GetKeyboardMapping reply: for each keycode in [Min, Min+len/PerCode) a run of PerCode keysyms, level 0 being the unshifted symbol and level 1 the shifted one.

func (*Keymap) Keysym 

func (k *Keymap) Keysym(keycode uint8, shift bool) uint32

Keysym returns the keysym bound to keycode at the given shift level (false = level 0, true = level 1). A level-1 lookup that resolves to NoSymbol (0) falls back to level 0, matching the core-protocol rule that an absent shifted symbol repeats the unshifted one. Out-of-range keycodes yield 0.

type Monitor added in v0.49.0 

type Monitor = xproto.Monitor

Monitor is one physical display's rectangle inside an X screen. It is a name for xproto.Monitor, not a copy.

type Presenter 

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

Presenter converts a toolkit RGBA framebuffer (R,G,B,A byte order) into the exact ZPixmap wire bytes a given visual + pixmap-format expect, and tiles PutImage requests so none exceeds the server's maximum request length.

Pixel bytes are laid out per the server's image-byte-order (independent of the protocol byte order): each pixel value is assembled from the RGB channels via the visual's masks, then serialised LSB- or MSB-first in bpp/8 bytes.

func NewPresenter 

func NewPresenter(setup *Setup, vis VisualType, depth uint8) (*Presenter, error)

NewPresenter derives the pixel-packing parameters for depth from the screen's visual and the server setup.

func (*Presenter) BytesPerPixel 

func (p *Presenter) BytesPerPixel() int

BytesPerPixel is the on-the-wire size of one pixel.

func (*Presenter) EncodeRectInto added in v0.3.0 

func (p *Presenter) EncodeRectInto(seg []byte, totalW int, src []byte, srcStride, sx, sy, w, h int) error

EncodeRectInto packs the rectangle (sx, sy, w, h) of an RGBA source buffer (srcStride bytes per row) into seg — a shared segment laid out as a totalW-wide ZPixmap image for this visual — at the matching position, so seg mirrors the framebuffer and ShmPutImage can blit any sub-rectangle of it. seg must hold at least SegmentSize(totalW, sy+h) bytes.

func (*Presenter) SegmentSize added in v0.3.0 

func (p *Presenter) SegmentSize(w, h int) int

SegmentSize is the byte size a w×h ZPixmap image occupies in a shared segment for this visual (padded scanlines).

type Screen 

type Screen = xproto.Screen

Screen is one root screen of a Setup.

type Setup 

type Setup = xproto.Setup

Setup is the parsed server connection-setup reply.

type Shm added in v0.3.0 

type Shm struct {
	VerMajor  uint16
	VerMinor  uint16
	SharedPix bool  // server supports shared pixmaps
	PixmapFmt uint8 // pixmap format for shared pixmaps
	FDCapable bool  // AttachFd usable: version >= 1.2 AND transport passes fds
	// contains filtered or unexported fields
}

Shm is a queried, ready-to-use MIT-SHM extension handle: the negotiated major opcode and version, and whether AttachFd (>= 1.2) is usable on this connection.

func (*Shm) AttachFd added in v0.3.0 

func (s *Shm) AttachFd(seg uint32, fd int, readOnly bool) error

AttachFd registers the shared-memory segment named by seg, backed by fd, with the server (MIT-SHM 1.2). The descriptor is passed over SCM_RIGHTS; readOnly declares whether the server may only read the segment. The server takes ownership of the passed descriptor.

func (*Shm) Detach added in v0.3.0 

func (s *Shm) Detach(seg uint32) error

Detach releases a previously attached segment.

func (*Shm) PutImage added in v0.3.0 

func (s *Shm) PutImage(p *Presenter, drawable, gc uint32, seg uint32, offset uint32,
	totalW, totalH, srcX, srcY, w, h, dstX, dstY int) error

PutImage blits a w×h source region located at byte offset in segment seg (whose full geometry is totalW×totalH) onto drawable at (dstX, dstY), taking its top-left from (srcX, srcY) within the segment image. depth and the visual's ZPixmap format come from the Presenter. It is a single fixed-size request regardless of image size — the pixels travel through shared memory.

type VisualType 

type VisualType = xproto.VisualType

VisualType describes a visual and its RGB channel masks.

type XError 

type XError struct {
	Code     byte
	Seq      uint16
	BadValue uint32
	Major    byte
	Minor    uint16
}

XError is a decoded X11 error reply.

func (*XError) Error 

func (e *XError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.