Change README to point to v2

README.md

@@ -1,5 +1,6 @@
 # xgbsel
 
-[![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/tomo/xgbsel.svg)](https://pkg.go.dev/git.tebibyte.media/tomo/xgbsel)
+[![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/tomo/xgbsel/v2.svg)](https://pkg.go.dev/git.tebibyte.media/tomo/xgbsel/v2)
 
-Easy clipboard/selection manipulation and access with xgb and xgbutil.
+Easy clipboard/selection manipulation and access with xgb and xgbutil. Please
+use v2 of this module.

v2/claim.go

@@ -1,6 +1,7 @@
 package xgbsel
 
 import "io"
+import "errors"
 import "github.com/jezek/xgb"
 import "github.com/jezek/xgbutil"
 import "github.com/jezek/xgb/xproto"
@@ -8,11 +9,33 @@ import "github.com/jezek/xgbutil/xprop"
 import "github.com/jezek/xgbutil/xevent"
 import "github.com/jezek/xgbutil/xwindow"
 
+const format8bit       byte = 8
+const format16bit      byte = 16
+const format32bit      byte = 32
+const propertyNewValue byte = 0
+const propertyDelete   byte = 1
+
+type claimRequest struct {
+	reader io.ReadSeekCloser
+	ty     xproto.Atom
+	event  xevent.SelectionRequestEvent
+}
+
+type claimRequestKey struct {
+	property  xproto.Atom
+	requestor xproto.Window
+}
+
 // Claim represents a claim that a window has on a particular selection.
 type Claim struct {
+	open      bool
+	incr      bool
 	window    *xwindow.Window
 	data      Data
 	selection xproto.Atom
+	timestamp xproto.Timestamp
+
+	requests map[claimRequestKey] *claimRequest
 }
 
 // NewClaim claims ownership of a specified selection, and allows using data
@@ -20,7 +43,7 @@ type Claim struct {
 // should be set to that of the event that triggered the claim, such as a Ctrl+C
 // event, or a mouse motion that led to text being selected. If the claim was
 // not triggered by an event, specify xproto.TimeCurrentTime.
-func NewClaim (window *xwindow.Window, selection xproto.Atom, data Data, timestamp xproto.Timestamp) *Claim {
+func NewClaim (window *xwindow.Window, selection xproto.Atom, data Data, timestamp xproto.Timestamp) (*Claim, error) {
 	// Follow:
 	// https://tronche.com/gui/x/icccm/sec-2.html#s-2.1
 	
@@ -39,18 +62,24 @@ func NewClaim (window *xwindow.Window, selection xproto.Atom, data Data, timesta
 	err := xproto.SetSelectionOwnerChecked (
 		window.X.Conn(),
 		window.Id, selection, timestamp).Check()
-	if err != nil { return nil }
+	if err != nil { return nil, err }
 
 	ownerReply, err := xproto.GetSelectionOwner (
 		window.X.Conn(), selection).Reply()
-	if err != nil { return nil }
-	if ownerReply.Owner != window.Id { return nil }
+	if err != nil { return nil, err }
+	if ownerReply.Owner != window.Id {
+		return nil, errors.New("someone else took the selection")
+	}
 
 	return &Claim {
+		open:      true,
+		incr:      false, // TODO change to enable INCR once its done
 		window:    window,
 		data:      data,
 		selection: selection,
-	}
+		timestamp: timestamp,
+		requests:  make(map[claimRequestKey] *claimRequest),
+	}, nil
 }
 
 func (claim *Claim) refuseSelectionRequest (request xevent.SelectionRequestEvent) {
@@ -81,12 +110,10 @@ func (claim *Claim) fulfillSelectionRequest (
 	// property on the requestor window and should set the property's type
 	// to some appropriate value, which need not be the same as the
 	// specified target.
-	err := xproto.ChangePropertyChecked (
-		claim.window.X.Conn(),
+	err := claim.changePropertyChecked (
 		xproto.PropModeReplace, request.Requestor,
 		request.Property,
-		ty, format,
-		uint32(len(data) / (int(format) / 8)), data).Check()
+		ty, format, data)
 	if err != nil { die() }
 
 	// If the property is successfully stored, the owner should acknowledge
@@ -104,6 +131,19 @@ func (claim *Claim) fulfillSelectionRequest (
 		false, request.Requestor, 0, string(event))
 }
 
+func (claim *Claim) changePropertyChecked (
+	mode     byte,
+	window   xproto.Window,
+	property xproto.Atom,
+	ty       xproto.Atom,
+	format   byte,
+	data     []byte,
+) error {
+	return xproto.ChangePropertyChecked (
+		claim.window.X.Conn(), mode, window, property, ty, format,
+		uint32(len(data) / (int(format) / 8)), data).Check()
+}
+
 // While the selection claim is active, HandleSelectionRequest should be called
 // when the owner window recieves a SelectionRequest event. This must be
 // registered as an event handler manually.
@@ -111,6 +151,10 @@ func (claim *Claim) HandleSelectionRequest (
 	connection *xgbutil.XUtil,
 	event xevent.SelectionRequestEvent,
 ) {
+	// do not fulfill *new* selection requests after the claim has been
+	// relinquished
+	if !claim.open { return }
+
 	// Follow:
 	// https://tronche.com/gui/x/icccm/sec-2.html#s-2.2
 
@@ -158,16 +202,185 @@ func (claim *Claim) HandleSelectionRequest (
 		// send that list to the requestor
 		atomAtom, err := xprop.Atm(claim.window.X, "ATOM")
 		if err != nil { die(); return }
-		claim.fulfillSelectionRequest(data, 32, atomAtom, event)
+		claim.fulfillSelectionRequest(data, format32bit, atomAtom, event)
 
 	default:
+		incr, err := xprop.Atm(claim.window.X, "INCR")
+		if err != nil { die(); return }
+	
 		// respond with data
 		reader, ok := claim.data.Convert(Target(targetName))
 		if !ok { die(); return }
+
+		if claim.incr {
+			// TODO: we need to subscribe to PropertyNotify events
+			// on the destination window. apparently event masks as
+			// set by ChangeWindowAttributes are client-specific.
+			// we also need to clean up afterwards.
+			// https://tronche.com/gui/x/xlib/window/XChangeWindowAttributes.html
+			
+			request := &claimRequest {
+				reader: reader,
+				ty:     event.Target,
+				event:  event,
+			}
+
+			// Requestors may receive a property of type INCR in
+			// response to any target that results in selection
+			// data. This indicates that the owner will send the
+			// actual data incrementally. The contents of the INCR
+			// property will be an integer, which represents a lower
+			// bound on the number of bytes of data in the
+			// selection.
+
+			data := [4]byte { }
+			xgb.Put32(data[:], 1)
+			err := claim.changePropertyChecked (
+				xproto.PropModeReplace, event.Requestor,
+				event.Property, incr, format32bit, data[:])
+			if err != nil { die() }
+
+			claim.requests[claimRequestKey {
+				property:  event.Property,
+				requestor: event.Requestor,
+			}] = request
+		} else {
 			reader.Seek(0, io.SeekStart)
 			data, err := io.ReadAll(reader)
 			reader.Close()
 			if err != nil { die() }
-		claim.fulfillSelectionRequest(data, 8, event.Target, event)
+			claim.fulfillSelectionRequest(data, format8bit, event.Target, event)
+		}
 	}
 }
+
+// While the selection claim is active, HandlePropertyNotify should be called
+// when the requesting window recieves a PropertyNotify event. This must be
+// registered as an event handler manually.
+func (claim *Claim) HandlePropertyNotify (
+	connection *xgbutil.XUtil,
+	event xevent.PropertyNotifyEvent,
+) {
+	// The selection requestor starts the transfer process by deleting the
+	// (type==INCR) property forming the reply to the selection.
+	// 
+	// The selection owner then:
+	// ... Waits between each append for a PropertyNotify (state==Deleted)
+	// event that shows that the requestor has read the data. The reason for
+	// doing this is to limit the consumption of space in the server.
+	if event.State != propertyDelete { return }
+
+	// if the request does not exist, the property was either modified in
+	// error or the request has already finished. either way, we simply
+	// exit.
+	key := claimRequestKey {
+		property:  event.Atom,
+		requestor: event.Window,
+	}
+	request, ok := claim.requests[key]
+	if !ok { return }
+
+	done := func () {
+		request.reader.Close()
+		delete(claim.requests, key)
+	}
+	
+	die := func () {
+		done()
+		claim.refuseSelectionRequest(request.event)
+	}
+
+	// FIXME change the length of this if maximum-request-size is smaller
+	buffer := [1024]byte { }
+	size, err := request.reader.Read(buffer[:])
+	if err != nil { die(); return }
+	dataRead := buffer[:size]
+
+	if len(dataRead) > 0 {
+		// there is more data to send
+		
+		// ... Appends the data in suitable-size chunks to the same property on
+		// the same window as the selection reply with a type corresponding to
+		// the actual type of the converted selection. The size should be less
+		// than the maximum-request-size in the connection handshake.
+		err := claim.changePropertyChecked (
+			xproto.PropModeReplace,
+			request.event.Requestor, request.event.Property,
+			request.ty, format8bit, dataRead)
+		if err != nil { die(); return }
+		
+	} else {
+		// all data has been sent
+	
+		// ... Waits (after the entire data has been transferred to the
+		// server) until a PropertyNotify (state==Deleted) event that
+		// shows that the data has been read by the requestor and then
+		// writes zero-length data to the property.
+		err := claim.changePropertyChecked (
+			xproto.PropModeReplace,
+			request.event.Requestor, request.event.Property,
+			request.ty, format8bit, nil)
+		if err != nil { die(); return }
+
+		done()
+	}
+}
+
+// While the selection claim is active, HandleSelectionClear should be called
+// when the requesting window recieves a SelectionClear event. This must be
+// registered as an event handler manually.
+func (claim *Claim) HandleSelectionClear (
+	connection *xgbutil.XUtil,
+	event xevent.SelectionClearEvent,
+) {
+	// When some other client acquires a selection, the previous owner
+	// receives a SelectionClear event. The timestamp argument is the time
+	// at which the ownership changed hands, and the owner argument is the
+	// window the previous owner specified in its SetSelectionOwner request.
+	// If an owner loses ownership while it has a transfer in progress (that
+	// is, before it receives notification that the requestor has received
+	// all the data), it must continue to service the ongoing transfer until
+	// it is complete.
+	claim.open = false
+}
+
+// Prune checks for requests that cannot continue and removes them. If this
+// claim is to be held for an extended period of time, this method should be
+// called every so often.
+func (claim *Claim) Prune () {
+	// TODO
+	// check all active requests to see if anyone's window has closed, and
+	// if it has, close the request
+}
+
+// Open returns false if the claim has been relinquished, either from recieving
+// a SelectionClear event or with the Close method.
+func (claim *Claim) Open () bool {
+	return claim.open
+}
+
+// Active returns true if requests are currently being fulfilled. While this is
+// true, the claim should still be forwarded events regardless if it is closed
+// or not. It is safe to forward the same event to multiple claims.
+func (claim *Claim) Active () bool {
+	return len(claim.requests) > 0
+}
+
+// Close voluntarily relinquishes the selection claim. This will inform the X
+// server that the selection is being voluntarily given up, and cause the claim
+// to stop fulfilling new requests.
+func (claim *Claim) Close () error {
+	if !claim.open { return nil }
+	claim.open = false
+
+	// To relinquish ownership of a selection voluntarily, a client should
+	// execute a SetSelectionOwner request for that selection atom, with
+	// owner specified as None and the time specified as the timestamp that
+	// was used to acquire the selection. 
+	err := xproto.SetSelectionOwnerChecked (
+		claim.window.X.Conn(),
+		0, claim.selection, claim.timestamp).Check()
+	if err != nil { return err }
+
+	return nil
+}

v2/examples/copy/main.go

@@ -62,11 +62,13 @@ func main () {
 	// obtain claim on CLIPBOARD
 	log.Println("obtaining claim")
 	clipboard, _ := xprop.Atm(X, "CLIPBOARD")
-	claim := xgbsel.NewClaim(window, clipboard, data, xproto.TimeCurrentTime)
+	claim,     _ := xgbsel.NewClaim(window, clipboard, data, xproto.TimeCurrentTime)
 
 	// listen for events
 	window.Listen(xproto.EventMaskPropertyChange)
+	xevent.PropertyNotifyFun(claim.HandlePropertyNotify).Connect(X, window.Id)
 	xevent.SelectionRequestFun(claim.HandleSelectionRequest).Connect(X, window.Id)
+	xevent.SelectionClearFun(claim.HandleSelectionClear).Connect(X, window.Id)
 	
 	log.Println("running main event loop")
 	xevent.Main(X)

v2/examples/paste/main.go

@@ -79,10 +79,11 @@ func main () {
 	log.Println("creating request")
 	clipboard, _ := xprop.Atm(X, "CLIPBOARD")
 	property,  _ := xprop.Atm(X, "DESTINATION")
-	request := xgbsel.NewRequest (
+	request,   _ := xgbsel.NewRequest (
 		requestor { window: window },
 		clipboard,
-		property)
+		property,
+		xproto.TimeCurrentTime)
 
 	// listen for events
 	window.Listen(xproto.EventMaskPropertyChange)

v2/request.go

@@ -45,20 +45,25 @@ type Request struct {
 	destination xproto.Atom
 	incrBuffer  []byte
 	incrTarget  Target
+	timestamp   xproto.Timestamp
 }
 
-// NewRequest sends a new selection request.
-func NewRequest (requestor Requestor, source, destination xproto.Atom) *Request {
+// NewRequest sends a new selection request. The timestamp should be set to that
+// of the event that triggered the request, such as a Ctrl+V event, or a mouse
+// button event that led to text being pasted. If the claim was not triggered by
+// an event, and *only* in this scenario, specify xproto.TimeCurrentTime.
+func NewRequest (requestor Requestor, source, destination xproto.Atom, timestamp xproto.Timestamp) (*Request, error) {
 	request := &Request {
 		source:      source,
 		destination: destination,
 		requestor:   requestor,
+		timestamp:   timestamp,
 	}
 
 	targets, err := xprop.Atm(requestor.Window().X, "TARGETS")
-	if err != nil { request.die(err); return nil }
+	if err != nil { return nil, err }
 	request.convertSelection(targets, selReqStateAwaitTargets)
-	return request
+	return request, nil
 }
 
 func (request *Request) convertSelection (target xproto.Atom, switchTo selReqState) {
@@ -86,17 +91,14 @@ func (request *Request) convertSelection (target xproto.Atom, switchTo selReqSta
 	// to a window that it created; the owner will place the reply property
 	// there. The requestor should set the time argument to the timestamp on
 	// the event that triggered the request for the selection value. Note
-	// that clients should not specify CurrentTime*.
+	// that clients should not specify CurrentTime.
 	err = xproto.ConvertSelectionChecked (
 		request.requestor.Window().X.Conn(),
 		request.requestor.Window().Id,
 		request.source,
 		target,
 		request.destination,
-		// TODO: *possibly replace this zero with an actual timestamp
-		// received from the server. this is non-trivial as we cannot
-		// rely on the timestamp of the last received event.
-		0).Check()
+		request.timestamp).Check()
 	if err != nil { request.die(err); return }
 	
 	request.state = switchTo
@@ -255,6 +257,10 @@ func (request *Request) HandlePropertyNotify (
 	connection *xgbutil.XUtil,
 	event xevent.PropertyNotifyEvent,
 ) {
+	// ignore events that don't apply to our window's destination property
+	if event.Window != request.requestor.Window().Id { return }
+	if event.Atom   != request.destination           { return }
+
 	// the only valid state that we can process a PropertyNotify event in
 	if request.state != selReqStateAwaitChunk { return }
 	if event.State != xproto.PropertyNewValue { return }