github.com/BurntSushi/xgb@v0.0.0-20210121224620-deaf085860bc/doc.go (about)

     1  /*
     2  Package XGB provides the X Go Binding, which is a low-level API to communicate
     3  with the core X protocol and many of the X extensions.
     4  
     5  It is *very* closely modeled on XCB, so that experience with XCB (or xpyb) is
     6  easily translatable to XGB. That is, it uses the same cookie/reply model
     7  and is thread safe. There are otherwise no major differences (in the API).
     8  
     9  Most uses of XGB typically fall under the realm of window manager and GUI kit
    10  development, but other applications (like pagers, panels, tilers, etc.) may
    11  also require XGB. Moreover, it is a near certainty that if you need to work
    12  with X, xgbutil will be of great use to you as well:
    13  https://github.com/BurntSushi/xgbutil
    14  
    15  Example
    16  
    17  This is an extremely terse example that demonstrates how to connect to X,
    18  create a window, listen to StructureNotify events and Key{Press,Release}
    19  events, map the window, and print out all events received. An example with
    20  accompanying documentation can be found in examples/create-window.
    21  
    22  	package main
    23  
    24  	import (
    25  		"fmt"
    26  		"github.com/BurntSushi/xgb"
    27  		"github.com/BurntSushi/xgb/xproto"
    28  	)
    29  
    30  	func main() {
    31  		X, err := xgb.NewConn()
    32  		if err != nil {
    33  			fmt.Println(err)
    34  			return
    35  		}
    36  
    37  		wid, _ := xproto.NewWindowId(X)
    38  		screen := xproto.Setup(X).DefaultScreen(X)
    39  		xproto.CreateWindow(X, screen.RootDepth, wid, screen.Root,
    40  			0, 0, 500, 500, 0,
    41  			xproto.WindowClassInputOutput, screen.RootVisual,
    42  			xproto.CwBackPixel | xproto.CwEventMask,
    43  			[]uint32{ // values must be in the order defined by the protocol
    44  				0xffffffff,
    45  				xproto.EventMaskStructureNotify |
    46  				xproto.EventMaskKeyPress |
    47  				xproto.EventMaskKeyRelease})
    48  
    49  		xproto.MapWindow(X, wid)
    50  		for {
    51  			ev, xerr := X.WaitForEvent()
    52  			if ev == nil && xerr == nil {
    53  				fmt.Println("Both event and error are nil. Exiting...")
    54  				return
    55  			}
    56  
    57  			if ev != nil {
    58  				fmt.Printf("Event: %s\n", ev)
    59  			}
    60  			if xerr != nil {
    61  				fmt.Printf("Error: %s\n", xerr)
    62  			}
    63  		}
    64  	}
    65  
    66  Xinerama Example
    67  
    68  This is another small example that shows how to query Xinerama for geometry
    69  information of each active head. Accompanying documentation for this example
    70  can be found in examples/xinerama.
    71  
    72  	package main
    73  
    74  	import (
    75  		"fmt"
    76  		"log"
    77  		"github.com/BurntSushi/xgb"
    78  		"github.com/BurntSushi/xgb/xinerama"
    79  	)
    80  
    81  	func main() {
    82  		X, err := xgb.NewConn()
    83  		if err != nil {
    84  			log.Fatal(err)
    85  		}
    86  
    87  		// Initialize the Xinerama extension.
    88  		// The appropriate 'Init' function must be run for *every*
    89  		// extension before any of its requests can be used.
    90  		err = xinerama.Init(X)
    91  		if err != nil {
    92  			log.Fatal(err)
    93  		}
    94  
    95  		reply, err := xinerama.QueryScreens(X).Reply()
    96  		if err != nil {
    97  			log.Fatal(err)
    98  		}
    99  
   100  		fmt.Printf("Number of heads: %d\n", reply.Number)
   101  		for i, screen := range reply.ScreenInfo {
   102  			fmt.Printf("%d :: X: %d, Y: %d, Width: %d, Height: %d\n",
   103  				i, screen.XOrg, screen.YOrg, screen.Width, screen.Height)
   104  		}
   105  	}
   106  
   107  Parallelism
   108  
   109  XGB can benefit greatly from parallelism due to its concurrent design. For
   110  evidence of this claim, please see the benchmarks in xproto/xproto_test.go.
   111  
   112  Tests
   113  
   114  xproto/xproto_test.go contains a number of contrived tests that stress
   115  particular corners of XGB that I presume could be problem areas. Namely:
   116  requests with no replies, requests with replies, checked errors, unchecked
   117  errors, sequence number wrapping, cookie buffer flushing (i.e., forcing a round
   118  trip every N requests made that don't have a reply), getting/setting properties
   119  and creating a window and listening to StructureNotify events.
   120  
   121  Code Generator
   122  
   123  Both XCB and xpyb use the same Python module (xcbgen) for a code generator. XGB
   124  (before this fork) used the same code generator as well, but in my attempt to
   125  add support for more extensions, I found the code generator extremely difficult
   126  to work with. Therefore, I re-wrote the code generator in Go. It can be found
   127  in its own sub-package, xgbgen, of xgb. My design of xgbgen includes a rough
   128  consideration that it could be used for other languages.
   129  
   130  What works
   131  
   132  I am reasonably confident that the core X protocol is in full working form. I've
   133  also tested the Xinerama and RandR extensions sparingly. Many of the other
   134  existing extensions have Go source generated (and are compilable) and are
   135  included in this package, but I am currently unsure of their status. They
   136  *should* work.
   137  
   138  What does not work
   139  
   140  XKB is the only extension that intentionally does not work, although I suspect
   141  that GLX also does not work (however, there is Go source code for GLX that
   142  compiles, unlike XKB). I don't currently have any intention of getting XKB
   143  working, due to its complexity and my current mental incapacity to test it.
   144  
   145  */
   146  package xgb