XHB

WARNING: XHB is a work-in-progress, and this page is a WIP, too.

What is XHB?

XHB is short for X Haskell Binding. XHB serves the purpose of XCB [1] for Haskell programs.

XHB is deemed to be used for all sorts of X11 application programming. Why not use traditional Xlib?

• Xlib bindings are incomplete, and seem to be hard to get right
• Xlib has its share of sharp edges which XCB tries to smooth out [2]

Getting started

NOTE: this tutorial is based on [3]

Introduction

The X Window System employs a client-server model for all its interactions, thus X applications are event-driven clients of an X server, which manages some system-wide resources (windows, input devices, etc.) and sends event notifications to clients.

Every client (X application) can basically perform two things:

• send requests (e.g., generate events, etc.)
• receive replies (e.g., event notifications, etc.)

An example

A client may connect to the server, request that it draws a window (or several windows), and ask the server to send it any input the user sends to these windows. Thus, several clients may connect to a single X server (one might be running mail software, one running a WWW browser, etc.). When input is sent by the user to some window, the server sends a message to the client controlling this window for processing. The client decides what to do with this input, and sends the server requests for drawing in the window.

The X protocol

The whole session is carried out using the X message protocol. This protocol was originally carried over the TCP/IP protocol suite, allowing the client to run on any machine connected to the same network that the server is. Later on, the X servers were extended to allow clients running on the local machine with more optimized access to the server (note that an X protocol message may be several hundreds of KB in size), such as using shared memory, or using Unix domain sockets (a method for creating a logical channel on a Unix system between two processes).

The GUI programming model

A GUI program mostly sits idle, waiting for events sent by the X server, and then acts upon these events. An event may say "The user pressed the 1st button mouse in spot (x,y)", or "The window you control needs to be redrawn". In order for the program to be responsive to the user input, as well as to refresh requests, it needs to handle each event in a rather short period of time (e.g. less that 200 milliseconds, as a rule of thumb)

This also implies that the program may not perform operations that might take a long time while handling an event (such as opening a network connection to some remote server, or connecting to a database server, or even performing a long file copy operation). Instead, it needs to perform all these operations in an asynchronous manner. This may be done by using various asynchronous models to perform the longish operations, or by performing them in a different process or thread.

So the way a GUI program looks is something imperative in the lines of:

 1. Open a connection to the X server.
 2. Either poll or wait for events (an event pumping loop)
    1. Receive the next event from the X server.
    2. Handle the event, possibly generating more events or requests (e.g., sending various drawing requests to the X server)
    3. If the event was a quit message, exit the loop
 3. Close the connection to the X server

Note that we omitted program initialization and other boring stuff.

Basic XHB notions

XHB has been created to eliminate the need for programs to actually implement the X protocol layer. This library gives a program a very low-level access to any X server. Since the protocol is standardized, a client using any implementation of XHB may talk with any X server (the same occurs for Xlib, of course). We now give a brief description of the basic XHB notions. They will be detailed later.

• The X server connection which abstracts request and reply queues.
• Requests and replies which are the means of communicating between X server and client.
• The graphics context which holds the current state of graphics variables (what foreground and background colors to use, what font to use when drawing some text, etc.). Actually, this is how we reduce bandwidth consumption.
• Events with additional information (e.g., position on the screen where event was generated, mouse button associated with the event, etc.).

What is really interesting here, is that XHB is non-blocking (asynchronous). That is, it doesn't force you to wait for reply on your request. When sending a request, XHB returns immediately (with a cookie, "a promise"), even if the reply is not yet available; while Xlib, for instance, locks your program waiting for X server to reply. This can be very slow (and it is, in fact).

Note that Lazy evaluation is good at hiding latency of this sort.

Obtaining XHB

If you feel adventurous, then try the following at the nearest terminal:

cabal install xcb-types
darcs get http://community.haskell.org/~aslatter/xhb
cd xhb
bash generate.sh
bash cabalize.sh
cabal configure
cabal haddock