Portability | portable |
---|---|
Stability | provisional |
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 CInt
s), 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.
- data XftMgr
- newXftMgr :: Display -> Screen -> IO () -> IO () -> IO XftMgr
- freeXftMgr :: XftMgr -> IO ()
- data Color
- pixel :: Color -> Pixel
- newColorName :: Display -> Visual -> Colormap -> String -> IO (Maybe Color)
- newColorValue :: Display -> Visual -> Colormap -> RenderColor -> IO (Maybe Color)
- freeColor :: Display -> Visual -> Colormap -> Color -> IO ()
- openColorName :: XftMgr -> Visual -> Colormap -> String -> IO (Maybe Color)
- openColorValue :: XftMgr -> Visual -> Colormap -> RenderColor -> IO (Maybe Color)
- data Draw
- display :: Draw -> Display
- colormap :: Draw -> Colormap
- visual :: Draw -> Visual
- drawable :: Draw -> Drawable
- changeDraw :: Draw -> Drawable -> IO ()
- newDraw :: Display -> Drawable -> Visual -> Colormap -> IO (Maybe Draw)
- newDrawBitmap :: Display -> Pixmap -> IO (Maybe Draw)
- newDrawAlpha :: Integral a => Display -> Pixmap -> a -> IO (Maybe Draw)
- freeDraw :: Draw -> IO ()
- openDraw :: XftMgr -> Drawable -> Visual -> Colormap -> IO (Maybe Draw)
- openDrawBitmap :: XftMgr -> Drawable -> IO (Maybe Draw)
- openDrawAlpha :: Integral a => XftMgr -> Drawable -> a -> IO (Maybe Draw)
- data Font
- ascent :: Integral a => Font -> a
- descent :: Integral a => Font -> a
- height :: Integral a => Font -> a
- maxAdvanceWidth :: Integral a => Font -> a
- newFontName :: Display -> Screen -> String -> IO (Maybe Font)
- newFontXlfd :: Display -> Screen -> String -> IO (Maybe Font)
- freeFont :: Display -> Font -> IO ()
- openFontName :: XftMgr -> String -> IO (Maybe Font)
- openFontXlfd :: XftMgr -> String -> IO (Maybe Font)
- lockFace :: Font -> IO ()
- unlockFace :: Font -> IO ()
- textExtents :: Display -> Font -> String -> IO GlyphInfo
- textWidth :: Integral a => Display -> Font -> String -> IO a
- textHeight :: Integral a => Display -> Font -> String -> IO a
- drawString :: (Integral x, Integral y) => Draw -> Color -> Font -> x -> y -> String -> IO ()
- drawGlyphs :: (Integral x, Integral y, Integral c) => Draw -> Color -> Font -> x -> y -> [c] -> IO ()
- drawRect :: (Integral x, Integral y, Integral w, Integral h) => Draw -> Color -> x -> y -> w -> h -> IO ()
- data RenderColor = RenderColor {}
- data GlyphInfo = GlyphInfo {
- glyphImageWidth :: Int
- glyphImageHeight :: Int
- glyphImageX :: Int
- glyphImageY :: Int
- glyphWidth :: Int
- glyphHeight :: Int
Xft management
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.
:: 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
Control.Concurrent.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 ()Source
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
newColorName :: Display -> Visual -> Colormap -> String -> IO (Maybe Color)Source
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)Source
As newColorName
, but instead of a name, an XRender color value
is used.
freeColor :: Display -> Visual -> Colormap -> Color -> IO ()Source
Free a colour that has been allocated with newColorName
or newColorValue
.
openColorName :: XftMgr -> Visual -> Colormap -> String -> IO (Maybe Color)Source
As newColorName
, but automatically freed through the given Xft
manager when no longer accessible.
openColorValue :: XftMgr -> Visual -> Colormap -> RenderColor -> IO (Maybe Color)Source
As newColorValue
, but automatically freed through the given Xft
manager when no longer accessible.
Drawable handling
openDraw :: XftMgr -> Drawable -> Visual -> Colormap -> IO (Maybe Draw)Source
As newDraw
, but automatically freed when no longer used.
openDrawBitmap :: XftMgr -> Drawable -> IO (Maybe Draw)Source
As newDrawBitmap
, but automatically freed when no longer used.
openDrawAlpha :: Integral a => XftMgr -> Drawable -> a -> IO (Maybe Draw)Source
As newDrawBitmap
, but automatically freed when no longer used.
Font handling
ascent :: Integral a => Font -> aSource
The ascent (vertical distance upwards from the baseline) of a character in the font.
descent :: Integral a => Font -> aSource
The descent (vertical distance downwards from the baseline) of a character in the font.
maxAdvanceWidth :: Integral a => Font -> aSource
The greatest horizontal width of a character in the font.
newFontName :: Display -> Screen -> String -> IO (Maybe Font)Source
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)Source
As newFontName
, except that the name should be an X Logical
Font Description (the usual fourteen elements produced by
xfontsel
).
openFontName :: XftMgr -> String -> IO (Maybe Font)Source
As newFontName
, but automatically freed when no longer used.
openFontXlfd :: XftMgr -> String -> IO (Maybe Font)Source
As newFontXfld
, but automatically freed when no longer used.
lockFace :: Font -> IO ()Source
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 ()Source
Unlock a face locked by lockFontFace
.
Drawing
textExtents :: Display -> Font -> String -> IO GlyphInfoSource
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 aSource
Shortcut for calling textExtents
and picking out the
glyphWidth
field of the GlyphInfo
.
textHeight :: Integral a => Display -> Font -> String -> IO aSource
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 ()Source
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 ()Source
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 ()Source
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 Source
The XRenderColor
from the XRender library. Note that the
colour channels are only interpreted as 16-bit numbers when
actually used.
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.
GlyphInfo | |
|