xgbsel

README

xgbsel

Easy clipboard/selection manipulation and access with xgb and xgbutil.

Documentation

Overview

Package xgbsel provides easy clipboard/selection manipulation and access with xgb and xgbutil.

Index

• type Claim
  • func NewClaim(window *xwindow.Window, selection xproto.Atom, data Data) *Claim
  • func NewClaimWithTimestamp(window *xwindow.Window, selection xproto.Atom, data Data, ...) *Claim
  • func (claim *Claim) HandleSelectionRequest(connection *xgbutil.XUtil, event xevent.SelectionRequestEvent)
• type Confidence
• type Data
• type Request
  • func NewRequest(requestor Requestor, source, destination xproto.Atom) *Request
  • func (request *Request) HandlePropertyNotify(connection *xgbutil.XUtil, event xevent.PropertyNotifyEvent)
  • func (request *Request) HandleSelectionNotify(connection *xgbutil.XUtil, event xevent.SelectionNotifyEvent)
• type Requestor
• type Target
  • func MimeToTargets(mime string) []Target
  • func (target Target) ToMime() (string, Confidence)

Types

type Claim

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

Claim represents a claim that a window has on a particular selection.

func NewClaim

func NewClaim(window *xwindow.Window, selection xproto.Atom, data Data) *Claim

NewClaim claims ownership of a specified selection, and allows using data passed to it to fulfill requests for the selection's contents. If the claim happens because of a user input event, use NewClaimWithTimestamp instead of this function. See the documentation of NewClaimWithTimestamp for details.

func NewClaimWithTimestamp

func NewClaimWithTimestamp(window *xwindow.Window, selection xproto.Atom, data Data, timestamp xproto.Timestamp) *Claim

NewClaimWithTimestamp claims ownership of a specified selection, and allows using data passed to it to fulfill requests for the selection's contents. The timestamp 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.

func (*Claim) HandleSelectionRequest

func (claim *Claim) HandleSelectionRequest(
	connection *xgbutil.XUtil,
	event xevent.SelectionRequestEvent,
)

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.

type Confidence

type Confidence int

Confidence represents how accurate a conversion from a target to a MIME type is.

const (
	ConfidenceNone Confidence = iota
	ConfidencePartial
	ConfidenceFull
)

type Data

type Data interface {
	// Convert converts the data to the specified target and returns it. If
	// the target is not supported, this behavior will return false for ok.
	Convert(Target) (reader io.ReadSeekCloser, ok bool)

	// Supported returns a slice of targets that Convert can accept. This
	// can just be the result of MimeToTargets.
	Supported() []Target
}

Data represents X selection data.

type Request

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

Request represents an ongoing request for the selection contents.

func NewRequest

func NewRequest(requestor Requestor, source, destination xproto.Atom) *Request

NewRequest sends a new selection request.

func (*Request) HandlePropertyNotify

func (request *Request) HandlePropertyNotify(
	connection *xgbutil.XUtil,
	event xevent.PropertyNotifyEvent,
)

While the selection request is active, HandlePropertyNotify should be called when the requesting window recieves a PropertyNotify event. This must be registered as an event handler manually.

func (*Request) HandleSelectionNotify

func (request *Request) HandleSelectionNotify(
	connection *xgbutil.XUtil,
	event xevent.SelectionNotifyEvent,
)

While the selection request is active, HandleSelectionNotify should be called when the requesting window recieves a SelectionNotify event. This must be registered as an event handler manually.

type Requestor

type Requestor interface {
	// Window returns the window that is requesting the selection data.
	Window() *xwindow.Window

	// Choose picks target from a slice of available targets and returns
	// (target, true). If no target was picket, it returns ("", false).
	Choose(available []Target) (target Target, ok bool)

	// Success is called once the owner responds with data. The data must be
	// closed once it has been read.
	Success(Target, io.ReadCloser)

	// Failure is called if the transfer fails at any point, or if there
	// isn't any data to begin with. In the first case, an error is given.
	// In the second case, the error will be nil.
	Failure(error)
}

Requestor provices details about the request such as the window that is requesting the selection data, and what targets it accepts.

type Target

type Target string

Target represents an X selection target. It defines the type of data stored within an X selection. This data may be a MIME type, or a more specific name that is unique to X. A list of these names can be found here: https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2

func MimeToTargets

func MimeToTargets(mime string) []Target

MimeToTargets returns a slice of targets that correspond to a specified MIME type. The MIME type itself is always the first item of the slice. All targets returned by this function are guaranteed to convert to the given MIME type when ToMime is called on them.

func (Target) ToMime

func (target Target) ToMime() (string, Confidence)

ToMime converts the specified target to a MIME type. Because a single MIME type may correspond to several targets, a confidence value is returned representing how one-to-one of a match it is. If some data is represented by multiple targets, they can each be checked individually and the one with the highest confidence value can be chosen. If a target cannot be converted to a MIME type, ("", ConfidenceNone) is returned.