Permalink
Browse files

[project @ 2004-08-16 19:59:48 by panne]

XMLification
  • Loading branch information...
1 parent c2ae8c4 commit 53988be86d221034c75e718c4260c870c9fb0604 panne committed Aug 16, 2004
Showing with 336 additions and 347 deletions.
  1. +0 −343 doc/HSX11.sgml
  2. +335 −0 doc/HSX11.xml
  3. +1 −4 doc/Makefile
View
@@ -1,343 +0,0 @@
-<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!entity the-index SYSTEM "genindex.sgml">
-]>
-
-<book id="HSX11">
- <bookinfo>
- <date>2003-5-22</date>
- <title>HSX11 Guide</title>
- <author>
- <firstname>Alastair</firstname>
- <surname>Reid</surname>
- </author>
- <address><email>alastair@reid-consulting-uk.ltd.uk</email></address>
- <copyright>
- <year>1999-2003</year>
- <holder>Alastair Reid</holder>
- </copyright>
- <abstract>
- <para>This document describes HSX11, the Haskell binding to X11,
- version 1.00.</para>
- </abstract>
- </bookinfo>
-
- <!-- Table of contents -->
- <toc></toc>
-
-<!-- Introduction --------------------------------------------------------- -->
-
- <chapter id="introduction">
- <title>Introduction</title>
-
- <para> <literal/HSX11/ is a Haskell binding to the popular
- <literal/X11/ library.
-
- <para>The library aims to provide a direct translation of the X
- binding into Haskell so the most important pieces of documentation
- you should read are the <literal/X11/ documents which can be
- obtained from the <ULink
- url="http://www.xfree86.org/support.html">XFree86 website</ULink>.
- Let me say that again because it is very important. Get hold of this
- documentation and read it: it tells you almost everything you need
- to know to use this library.
-
- </chapter>
-
- <chapter id="changes">
- <title>Changes from X11 documentation</title>
-
- <para>In making a Haskell binding to a C library, there are certain
- necessary and/or desirable changes in the interface.
-
- These can be divided into systematic changes which are applied
- uniformly throughout the library and ad-hoc changes which are
- applied to particular parts of the interface.
-
- <Sect1 id="systematic-changes"><Title>Systematic Changes</Title>
-
- <VariableList>
-
- <VarListEntry><term/Naming Conventions/
- <ListItem>
- <Para>
- In translating the library, we had to change names to conform with
- Haskell's lexical syntax: function names and names of constants must
- start with a lowercase letter; type names must start with an
- uppercase letter.
- </para>
- <para>
- In addition, we chose to take advantage of Haskell's module system
- to allow us to drop common prefixes (<literal/X/, <literal/XA_/,
- etc.) attached to X11 identifiers. For example, we translate some C
- functions, constants and types as follows:
-
- <InformalTable>
- <TGroup cols="2">
- <ColSpec Colname="one" Align="Left" Colsep="0">
- <ColSpec Colname="two" Align="Left" Colsep="0">
- <TBody>
-
- <Row>
- <Entry>C Name</Entry>
- <Entry>Haskell Name</Entry>
- </Row>
-
- <Row>
- <Entry><function/XWindowEvent/</Entry>
- <Entry><function/windowEvent/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XCheckWindowEvent/</Entry>
- <Entry><function/checkWindowEvent/</Entry>
- </Row>
-
- <Row>
- <Entry><function/QueuedAlready/</Entry>
- <Entry><function/queuedAlready/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XA_WM_ICON_NAME/</Entry>
- <Entry><function/wM_ICON_NAME/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XA_WM_ICON_SIZE/</Entry>
- <Entry><function/wM_ICON_SIZE/</Entry>
- </Row>
-
- </TBody>
-
- </TGroup>
- </InformalTable>
-
-
- </Para>
- </ListItem>
- </VarListEntry>
-
- <VarListEntry><term/Types/
- <ListItem>
- <Para>
- We translate type names as follows...
-
- <InformalTable>
- <TGroup cols="3">
- <ColSpec Colname="one" Align="Left" Colsep="0">
- <ColSpec Colname="two" Align="Left" Colsep="0">
- <ColSpec Colname="three" Align="Left" Colsep="0">
- <TBody>
-
- <Row>
- <Entry>C Type</Entry>
- <Entry>Haskell Type</Entry>
- <Entry>Haskell Expansion</Entry>
- </Row>
-
- <Row>
- <Entry><function/Display*/</Entry>
- <Entry><function/Display/</Entry>
- </Row>
-
- <Row>
- <Entry><function/Screen*/</Entry>
- <Entry><function/Screen/</Entry>
- </Row>
-
- <Row>
- <Entry><function/Visual*/</Entry>
- <Entry><function/Visual/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XFontStruct*/</Entry>
- <Entry><function/FontStruct/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XPoint/</Entry>
- <Entry><function/Point/</Entry>
- <Entry><function/(Position,Position)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XSegment/</Entry>
- <Entry><function/Segment/</Entry>
- <Entry><function/(Position,Position,Position,Position)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XRectangle/</Entry>
- <Entry><function/Rectangle/</Entry>
- <Entry><function/(Position,Position,Dimension,Dimension)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XArc/</Entry>
- <Entry><function/Arc/</Entry>
- <Entry><function/(Position,Position,Dimension,Dimension,Int,Int)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/XColor/</Entry>
- <Entry><function/Color/</Entry>
- <Entry><function/(Pixel,Word16, Word16, Word16, Word8)/</Entry>
- </Row>
-
- </TBody>
-
- </TGroup>
- </InformalTable>
-
- </Para>
- <Para>
- We systematically use a type of the form <literal/ListFoo/ as a
- synonym for <literal/[Foo]/ and <literal/MbFoo/ as a synonym for
- <literal/Maybe Foo/. This is an unfortunate side-effect of the tool
- we used to generate the bindings.
- </Para>
- <Para>
- We named enumeration types so that function types would be easier to
- understand. For example, we added ... Note that the types are
- synonyms for <literal/Int/ so no extra typesafety was obtained.
- </Para>
- </ListItem>
- </VarListEntry>
-
- <VarListEntry><term/Exception Handling/
- <ListItem>
- <Para>
- We consistently raise exceptions when a function returns an error
- code. In practice, this only affects the following functions
- because most Xlib functions do not return error codes.
-<ProgramListing>
-allocColor
-allocNamedColor
-fetchBuffer
-fetchBytes
-fontFromGC
-getGeometry
-getIconName
-iconifyWindow
-loadQueryFont
-lookupColor
-openDisplay
-parseColor
-queryBestCursor
-queryBestSize
-queryBestStipple
-queryBestTile
-rotateBuffers
-selectInput
-storeBuffer
-storeBytes
-withdrawWindow
-</ProgramListing>
- The Xlib library reports most errors by invoking a user-provided
- error handler. The function
-<ProgramListing>
-setDefaultErrorHandler :: IO ()
-</ProgramListing>
-installs this error handler.
-<ProgramListing>
-int defaultErrorHandler(Display *d, XErrorEvent *ev)
-{
- char buffer[1000];
- XGetErrorText(d,ev->error_code,buffer,1000);
- printf("Error: %s\n", buffer);
- return 0;
-}
-</ProgramListing>
- </Para>
- </ListItem>
- </VarListEntry>
-
- </VariableList>
-
- <Para>
- As an example of how these rules are applied in generating a
- function type, the C function with type:
-<ProgramListing>
-XDrawPoints(Display *display,
- Drawable d,
- GC gc,
- XPoint *points,
- int npoints,
- int mode)
-
-</ProgramListing>
- is given the Haskell type:
-<ProgramListing>
-drawPoints :: Display
- -> Drawable
- -> GC
- -> [Point]
- -> CoordinateMode
- -> IO ()
-</ProgramListing>
-
- </Para>
-
- </sect1>
-
- <Sect1 id="adhoc-changes"><Title>Ad hoc Changes</Title>
-
- <para>
- Finally, we chose to make some changes in the interface to better
- conform with idiomatic Haskell style or to allow a typesafe interface.
-
- <VariableList>
-
- <VarListEntry><term/waitForEvent/
- <ListItem>
- <Para>
-The function
-<ProgramListing>
-waitForEvent :: Display -> Word32 -> IO Bool
-</ProgramListing>
-reads an event with a timeout (in microseconds).
-%
-It is sometimes useful in conjunction with this function:
-<ProgramListing>
-gettimeofday_in_milliseconds :: IO Integer
-</ProgramListing>
- </Para>
- </ListItem>
- </VarListEntry>
-
- <VarListEntry><term/WindowAttribute operations/
- <ListItem>
- <Para>
-We provide the following operations on WindowsAttributes:
-<ProgramListing>
-set_background_pixmap :: XSetWindowAttributesPtr -> Pixmap -> IO ()
-set_background_pixel :: XSetWindowAttributesPtr -> Pixel -> IO ()
-set_border_pixmap :: XSetWindowAttributesPtr -> Pixmap -> IO ()
-set_border_pixel :: XSetWindowAttributesPtr -> Pixel -> IO ()
-set_bit_gravity :: XSetWindowAttributesPtr -> BitGravity -> IO ()
-set_win_gravity :: XSetWindowAttributesPtr -> WindowGravity -> IO ()
-set_backing_store :: XSetWindowAttributesPtr -> BackingStore -> IO ()
-set_backing_planes :: XSetWindowAttributesPtr -> Pixel -> IO ()
-set_backing_pixel :: XSetWindowAttributesPtr -> Pixel -> IO ()
-set_save_under :: XSetWindowAttributesPtr -> Bool -> IO ()
-set_event_mask :: XSetWindowAttributesPtr -> EventMask -> IO ()
-set_do_not_propagate_mask :: XSetWindowAttributesPtr -> EventMask -> IO ()
-set_override_redirect :: XSetWindowAttributesPtr -> Bool -> IO ()
-set_colormap :: XSetWindowAttributesPtr -> Colormap -> IO ()
-set_cursor :: XSetWindowAttributesPtr -> Cursor -> IO ()
-</ProgramListing>
- </Para>
- </ListItem>
- </VarListEntry>
-
-
- </VariableList>
-
- </sect1>
-
- </chapter>
-
- &the-index
-
-</book>
Oops, something went wrong.

0 comments on commit 53988be

Please sign in to comment.