2003-05-22

# HSX11 Guide

Alastair
Reid

    alastair@reid-consulting-uk.ltd.uk

1999-2003
Alastair Reid

This document describes HSWin32, the Haskell binding to Win32, version 2.00.

## Introduction

`HSWin32` is a Haskell binding to the popular `Win32` library provided on Microsoft operating systems.

The library aims to provide a direct translation of the Win32 binding into Haskell so the most important pieces of documentation you should read are the `Win32` documents which can be obtained from the Microsoft MSDN website and Charles Petzold's excellent book Programming Windows. 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.

## Changes from Win32 documentation

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.

### Systematic Changes

Naming Conventions

  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.

  For example, we translate some C functions, constants and types as follows:

  C Name | Haskell Name
  `HBRUSH` | `HBRUSH`
  `CreateSolidBrush` | `createSolidBrush`
  `wHITEBRUSH` | `WHITEBRUSH`

Types

  We translate type names as follows...

  `POINT` | `POINT` | `(LONG,LONG)`
  `RECT` | `RECT` | `(LONG,LONG,LONG,LONG)`
  `SIZE` | `SIZE` | `(LONG,LONG)`

  We systematically use a type of the form `ListFoo` as a synonym for `[Foo]` and `MbFoo` as a synonym for `Maybe Foo`. This is an unfortunate side-effect of the tool we used to generate the bindings.

  We named enumeration types so that function types would be easier to understand. For example, we added ... Note that the types are synonyms for `Int` so no extra typesafety was obtained.

Exception Handling

  We consistently raise exceptions when a function returns an error code. This affects most of the functions in the library.

As an example of how these rules are applied in generating a function type, the C function with type:

    COLORREF GetBkColor(
      HDC hdc   // handle to device context
    );

is given the Haskell type:

    getBkColor :: HDC -> IO  COLORREF

### Ad hoc Changes

Finally, we chose to make some changes in the interface to better conform with idiomatic Haskell style or to allow a typesafe interface. These have not yet been documented.