Graphics.X11.Xft

Interface to the Xft library based on the X11-xft binding by Clemens Fruhwirth. This library builds upon the X11 binding to Xlib (Graphics.X11) and cannot be used with any other. A tiny part of Xrender is also exposed, as no Haskell interface exists as of this writing.

The spirit of this binding is to hide away the fact that the underlying implementation is accessed via the FFI, and create a Haskell-like interface that does not expose many artifacts of the C implementation. To that end, the only numeric types exposed are high-level (no CInts), and facilities for integrating resource cleanup with the Haskell garbage collector have been defined (see XftMgr).

Another priority has been robustness. Many naively written FFI bindings to not properly check the return values of the C functions they call. In particular, null pointers are often assumed to never exist, and oftentimes impossible to check by the user as the underlying pointer is not visible across the module boundary. In this binding, any Xft function that can return null has been translated into a Haskell function that returns a Maybe value.

Two kinds of allocator functions are provided: some that use the nomenclature new and some that uses open (for example newColorName versus openColorName). The former require that you explicitly call the corresponding deallocator (freeColor in this case), while the latter takes an XftMgr as an additional argument, and automatically calls the deallocator when the value is garbage-collected. It is an error to call a deallocator on an automatically managed value.

Xft management

data XftMgr

A central staging point for Xft object creation. All Xft object creation functions take as argument an XftMgr value that keeps track of lifetime information. You are required to manually free the XftMgr via freeXftMgr when you are done with it.

newXftMgr

Arguments

:: Display

-> Screen

-> IO ()

Executed before deallocations.

-> IO ()

Executed after deallocations.

-> IO XftMgr

Create an XftMgr whose objects will be used on the given screen and display. As Xlib is not re-entrant, a synchronisation mechanism must be used, so the XftMgr includes actions for obtaining and releasing atomic access to the display via two IO actions. These will be executed before and after objects allocated via the manager are released. It is recommended to use an MVar to implement a mutex for synchronising the access, but if you are absolutely certain that there will not be any concurrent attempts to access the display, the actions can merely be return ().

freeXftMgr :: XftMgr -> IO ()

Free the manager and reclaim any objects associated with it. After an XftMgr has been freed, it is invalid to use any objects created through it. The lock must currently be held by the thread calling freeXftMgr, and it will be repeatedly released and reacquired throughout deallocating any remaining objects in the manager. When the command returns, the lock will once again be held.

Color handling

data Color

An Xft colour.

Instances

Param SindreX11M Color

pixel :: Color -> Pixel

The core X11 colour contained in an Xft colour.

newColorName :: Display -> Visual -> Colormap -> String -> IO (Maybe Color)

Create a new Xft colour based on a name. The name may be either a human-readable colour such as red, white or darkslategray (all core X colour names are supported) or a hexidecimal name such as . Names are not case-sensitive. Returns Nothing if the given name is not recognised as a colour.

newColorValue :: Display -> Visual -> Colormap -> RenderColor -> IO (Maybe Color)

As newColorName, but instead of a name, an XRender color value is used.

freeColor :: Display -> Visual -> Colormap -> Color -> IO ()

Free a colour that has been allocated with newColorName or newColorValue.

openColorName :: XftMgr -> Visual -> Colormap -> String -> IO (Maybe Color)

As newColorName, but automatically freed through the given Xft manager when no longer accessible.

openColorValue :: XftMgr -> Visual -> Colormap -> RenderColor -> IO (Maybe Color)

As newColorValue, but automatically freed through the given Xft manager when no longer accessible.

Drawable handling

data Draw

An Xft drawable.

display :: Draw -> Display

The display for the Xft drawable.

colormap :: Draw -> Colormap

The colormap for the Xft drawable.

visual :: Draw -> Visual

The visual for the Xft drawable.

drawable :: Draw -> Drawable

The X11 drawable underlying the Xft drawable.

changeDraw :: Draw -> Drawable -> IO ()

Change the X11 drawable underlying the Xft drawable.

newDraw :: Display -> Drawable -> Visual -> Colormap -> IO (Maybe Draw)

Create a new Xft drawable on the given display, using the provided Drawable to draw on. Will return Nothing if the call to XftDrawCreate fails, which it will usually only do if memory cannot be allocated. The Draw has to be manually freed with freeDraw once you are done with it.

newDrawBitmap :: Display -> Pixmap -> IO (Maybe Draw)

Behaves as newDraw, except that it uses a Pixmap of color depth 1 instead of a Drawable.

newDrawAlpha :: Integral a => Display -> Pixmap -> a -> IO (Maybe Draw)

Behaves as newDraw, except that it uses a Pixmap of the given depth instead of a Drawable.

freeDraw :: Draw -> IO ()

Free a Draw created with newDraw. Do not free Draws created with openDraw, these are automatically managed.

openDraw :: XftMgr -> Drawable -> Visual -> Colormap -> IO (Maybe Draw)

As newDraw, but automatically freed when no longer used.

openDrawBitmap :: XftMgr -> Drawable -> IO (Maybe Draw)

As newDrawBitmap, but automatically freed when no longer used.

openDrawAlpha :: Integral a => XftMgr -> Drawable -> a -> IO (Maybe Draw)

As newDrawBitmap, but automatically freed when no longer used.

Font handling

data Font

An Xft font.

Instances

Param SindreX11M Font

ascent :: Integral a => Font -> a

The ascent (vertical distance upwards from the baseline) of a character in the font.

descent :: Integral a => Font -> a

The descent (vertical distance downwards from the baseline) of a character in the font.

height :: Integral a => Font -> a

The ascent plus descent of a character in the font.

maxAdvanceWidth :: Integral a => Font -> a

The greatest horizontal width of a character in the font.

newFontName :: Display -> Screen -> String -> IO (Maybe Font)

newFontName dpy scr s, where s is a Fontconfig pattern string, finds the best match for s and returns a font that can be used to draw on the given screen. This function very rarely returns Nothing, and seems to return some default font even if you feed it utter garbage (or an empty string).

newFontXlfd :: Display -> Screen -> String -> IO (Maybe Font)

As newFontName, except that the name should be an X Logical Font Description (the usual fourteen elements produced by xfontsel).

freeFont :: Display -> Font -> IO ()

Close the given Xft font.

openFontName :: XftMgr -> String -> IO (Maybe Font)

As newFontName, but automatically freed when no longer used.

openFontXlfd :: XftMgr -> String -> IO (Maybe Font)

As newFontXfld, but automatically freed when no longer used.

lockFace :: Font -> IO ()

Lock the file underlying the Xft font. I am not certain when you would need this. The return value is supposed to be an FT_TYPE from Freetype, but that binding has not been written yet.

unlockFace :: Font -> IO ()

Unlock a face locked by lockFontFace.

Drawing

textExtents :: Display -> Font -> String -> IO GlyphInfo

Note that the 'glyphWidth'/'glyphHeight' fields are the number of pixels you should advance after drawing a string of this size.

textWidth :: Integral a => Display -> Font -> String -> IO a

Shortcut for calling textExtents and picking out the glyphWidth field of the GlyphInfo.

textHeight :: Integral a => Display -> Font -> String -> IO a

Shortcut for calling textExtents and picking out the glyphHeight field of the GlyphInfo.

drawString :: (Integral x, Integral y) => Draw -> Color -> Font -> x -> y -> String -> IO ()

Draw a string on the given drawable in the specified colour and font. Drawing begins at the baseline of the string.

drawGlyphs :: (Integral x, Integral y, Integral c) => Draw -> Color -> Font -> x -> y -> [c] -> IO ()

Draw a sequence of glyphs on the given drawable in the specified colour and font. Drawing begins at the baseline of the string.

drawRect :: (Integral x, Integral y, Integral w, Integral h) => Draw -> Color -> x -> y -> w -> h -> IO ()

drawRect d c x y w h draws a solid rectangle on d with colour c, with its upper left corner at (x,y), width w and height h.

XRender bits

data RenderColor

The XRenderColor from the XRender library. Note that the colour channels are only interpreted as 16-bit numbers when actually used.

Constructors

RenderColor

Fields

red :: Int

green :: Int

blue :: Int

alpha :: Int

Instances

Storable RenderColor

data GlyphInfo

The size of some glyph(s). Note that there's a difference between the logical size, which may include some blank pixels, and the actual bitmap.

Constructors

GlyphInfo

Fields

glyphImageWidth :: Int

glyphImageHeight :: Int

glyphImageX :: Int

glyphImageY :: Int

glyphWidth :: Int

glyphHeight :: Int

Instances

Storable GlyphInfo