haven/nexgb/doc.go

145 lines
4.4 KiB
Go
Raw Normal View History

2012-05-07 10:09:19 +02:00
/*
Package nexgb provides the X Go Binding, which is a low-level API to communicate
2012-05-07 10:09:19 +02:00
with the core X protocol and many of the X extensions.
It is *very* closely modeled on XCB, so that experience with XCB (or xpyb) is
easily translatable to neXGB. That is, it uses the same cookie/reply model
2012-05-07 10:09:19 +02:00
and is thread safe. There are otherwise no major differences (in the API).
Most uses of neXGB typically fall under the realm of window manager and GUI kit
2012-05-07 10:09:19 +02:00
development, but other applications (like pagers, panels, tilers, etc.) may
also require neXGB.
2012-05-07 10:09:19 +02:00
Example
This is an extremely terse example that demonstrates how to connect to X,
2013-01-26 18:51:48 +01:00
create a window, listen to StructureNotify events and Key{Press,Release}
events, map the window, and print out all events received. An example with
2012-05-07 10:09:19 +02:00
accompanying documentation can be found in examples/create-window.
package main
import (
"fmt"
2018-09-08 19:57:27 +02:00
xgb "janouch.name/haven/nexgb"
"janouch.name/haven/nexgb/xproto"
2012-05-07 10:09:19 +02:00
)
func main() {
X, err := xgb.NewConn()
if err != nil {
fmt.Println(err)
return
}
wid, _ := xproto.NewWindowId(X)
screen := xproto.Setup(X).DefaultScreen(X)
xproto.CreateWindow(X, screen.RootDepth, wid, screen.Root,
2012-05-07 10:09:19 +02:00
0, 0, 500, 500, 0,
xproto.WindowClassInputOutput, screen.RootVisual,
xproto.CwBackPixel | xproto.CwEventMask,
2012-05-07 10:09:19 +02:00
[]uint32{ // values must be in the order defined by the protocol
0xffffffff,
xproto.EventMaskStructureNotify |
xproto.EventMaskKeyPress |
xproto.EventMaskKeyRelease})
2012-05-07 10:09:19 +02:00
xproto.MapWindow(X, wid)
2012-05-07 10:09:19 +02:00
for {
ev, xerr := X.WaitForEvent()
if ev == nil && xerr == nil {
fmt.Println("Both event and error are nil. Exiting...")
return
}
if ev != nil {
fmt.Printf("Event: %s\n", ev)
}
if xerr != nil {
fmt.Printf("Error: %s\n", xerr)
}
}
}
Xinerama Example
This is another small example that shows how to query Xinerama for geometry
information of each active head. Accompanying documentation for this example
can be found in examples/xinerama.
package main
import (
"fmt"
"log"
2018-09-08 19:57:27 +02:00
xgb "janouch.name/haven/nexgb"
"janouch.name/haven/nexgb/xinerama"
2012-05-07 10:09:19 +02:00
)
func main() {
X, err := xgb.NewConn()
if err != nil {
log.Fatal(err)
}
// Initialize the Xinerama extension.
// The appropriate 'Init' function must be run for *every*
// extension before any of its requests can be used.
err = xinerama.Init(X)
2012-05-07 10:09:19 +02:00
if err != nil {
log.Fatal(err)
}
reply, err := xinerama.QueryScreens(X).Reply()
2012-05-07 10:09:19 +02:00
if err != nil {
log.Fatal(err)
}
fmt.Printf("Number of heads: %d\n", reply.Number)
for i, screen := range reply.ScreenInfo {
fmt.Printf("%d :: X: %d, Y: %d, Width: %d, Height: %d\n",
i, screen.XOrg, screen.YOrg, screen.Width, screen.Height)
}
}
Parallelism
neXGB can benefit greatly from parallelism due to its concurrent design. For
2012-05-27 00:22:25 +02:00
evidence of this claim, please see the benchmarks in xproto/xproto_test.go.
2012-05-07 10:09:19 +02:00
Tests
2013-01-26 18:51:48 +01:00
xproto/xproto_test.go contains a number of contrived tests that stress
particular corners of neXGB that I presume could be problem areas. Namely:
2013-01-26 18:51:48 +01:00
requests with no replies, requests with replies, checked errors, unchecked
errors, sequence number wrapping, cookie buffer flushing (i.e., forcing a round
trip every N requests made that don't have a reply), getting/setting properties
2012-05-27 00:22:25 +02:00
and creating a window and listening to StructureNotify events.
2012-05-07 10:09:19 +02:00
Code Generator
Both XCB and xpyb use the same Python module (xcbgen) for a code generator.
neXGB (before BurntSushi's fork) used the same code generator as well, but in my
attempt to add support for more extensions, I found the code generator extremely
difficult to work with. Therefore, I re-wrote the code generator in Go. It can
be found in its own sub-package, xgbgen, of xgb. My design of xgbgen includes a
rough consideration that it could be used for other languages.
2012-05-07 10:09:19 +02:00
What works
I am reasonably confident that the core X protocol is in full working form. I've
also tested the Xinerama and RandR extensions sparingly. Many of the other
2013-01-26 18:51:48 +01:00
existing extensions have Go source generated (and are compilable) and are
included in this package, but I am currently unsure of their status. They
2012-05-07 10:09:19 +02:00
*should* work.
What does not work
XKB is the only extension that intentionally does not work, although I suspect
that GLX also does not work (however, there is Go source code for GLX that
2013-01-26 18:51:48 +01:00
compiles, unlike XKB). I don't currently have any intention of getting XKB
2012-05-07 10:09:19 +02:00
working, due to its complexity and my current mental incapacity to test it.
*/
package nexgb