HGL-3.2.0.2: A simple graphics library based on X11 or Win32

Portability | non-portable (requires concurrency)
Stability | stable
Maintainer | libraries@haskell.org
Safe Haskell | None

Graphics.SOE

Contents

- Getting started
- Windows
  - General windows
- Drawing
  - Color
  - Drawing text
  - Drawing shapes
  - Regions
- User interaction
  - Keyboard events
  - Mouse events
  - General events
- Time

Description

The graphics library used in The Haskell School of Expression, by Paul Hudak, cf http://www.haskell.org/soe/.

Notes:

- This module is called `SOEGraphics` in the book. It is a cut down version of Graphics.HGL, with the interface frozen to match the book.
- In chapters 13, 17 and 19 of the book, there are imports of modules `Win32Misc` and `Word`. These should be omitted, as `timeGetTime` and `word32ToInt` are provided by this module.

Synopsis

- runGraphics :: IO () -> IO ()
- type Title = String
- type Size = (Int, Int)
- data Window
- openWindow :: Title -> Size -> IO Window
- getWindowSize :: Window -> IO Size
- clearWindow :: Window -> IO ()
- drawInWindow :: Window -> Graphic -> IO ()
- drawInWindowNow :: Window -> Graphic -> IO ()
- setGraphic :: Window -> Graphic -> IO ()
- closeWindow :: Window -> IO ()
- openWindowEx :: Title -> Maybe Point -> Maybe Size -> RedrawMode -> Maybe Word32 -> IO Window
- data RedrawMode
- drawGraphic :: RedrawMode
- drawBufferedGraphic :: RedrawMode
- type Graphic = Draw ()
- emptyGraphic :: Graphic
- overGraphic :: Graphic -> Graphic -> Graphic
- overGraphics :: [Graphic] -> Graphic
- data Color
  - = Black
  - | Blue
  - | Green
  - | Cyan
  - | Red
  - | Magenta
  - | Yellow
  - | White
- withColor :: Color -> Graphic -> Graphic
- text :: Point -> String -> Graphic
- type Point = (Int, Int)
- ellipse :: Point -> Point -> Graphic
- shearEllipse :: Point -> Point -> Point -> Graphic
- line :: Point -> Point -> Graphic
- polygon :: [Point] -> Graphic
- polyline :: [Point] -> Graphic
- polyBezier :: [Point] -> Graphic
- type Angle = Double
- arc :: Point -> Point -> Angle -> Angle -> Graphic
- data Region
- createRectangle :: Point -> Point -> Region
- createEllipse :: Point -> Point -> Region
- createPolygon :: [Point] -> Region
- andRegion :: Region -> Region -> Region
- orRegion :: Region -> Region -> Region
- xorRegion :: Region -> Region -> Region
- diffRegion :: Region -> Region -> Region
- drawRegion :: Region -> Graphic
- getKey :: Window -> IO Char
- getLBP :: Window -> IO Point
- getRBP :: Window -> IO Point
- data Event
  - = Key {
    - char :: Char
    - isDown :: Bool
    }
  - | Button {
    - pt :: Point
    - isLeft :: Bool
    - isDown :: Bool
    }
  - | MouseMove {
    - pt :: Point
    }
  - | Resize
  - | Closed
- maybeGetWindowEvent :: Window -> IO (Maybe Event)
- getWindowEvent :: Window -> IO Event
- data Word32
- getWindowTick :: Window -> IO ()
- timeGetTime :: IO Word32
- word32ToInt :: Word32 -> Int

# Getting started

runGraphics :: IO () -> IO ()Source

Initialize the system to do graphics, run an action while collecting user interface events and forwarding them to the action, and then clean up everything else at the end. The other functions of the library may only be used inside `runGraphics`.

# Windows

type Title = String Source

Title of a window.

type Size = (Int, Int)Source

A (width, height) pair, both measured in pixels.

data Window Source

openWindow :: Title -> Size -> IO Window Source

Create a window with the given title and size.

getWindowSize :: Window -> IO Size Source

The current size of the window.

clearWindow :: Window -> IO ()Source

Erase all drawing in the window. (That is, set the `Graphic` held by the window to `emptyGraphic`.)

drawInWindow :: Window -> Graphic -> IO ()Source

Draw the given graphic on the window, on top of anything that is already there. (That is, combine the given `Graphic` and the one held by the window using `overGraphic`, store the result in the window, and display it.)

drawInWindowNow :: Window -> Graphic -> IO ()Source

Another name for `drawInWindow`, retained for backwards compatibility.

setGraphic :: Window -> Graphic -> IO ()Source

Set the current drawing in a window.

closeWindow :: Window -> IO ()Source

Close the window.

## General windows

openWindowEx Source

Arguments

:: Title | the title of the window
-> Maybe Point | the initial position of the window
-> Maybe Size | the initial size of the window
-> RedrawMode | how to display a graphic on the window
-> Maybe Word32 | optionally attach a timer to the window, with the specified time (in milliseconds) between ticks.
-> IO Window |

an extended version of `openWindow`.

data RedrawMode Source

How to draw in a window.

drawGraphic :: RedrawMode Source

Draw directly to the window (slightly faster than `drawBufferedGraphic`, but more prone to flicker).

drawBufferedGraphic :: RedrawMode Source

Use a double buffer to reduce flicker and thus improve the look of animations.

# Drawing

type Graphic = Draw ()Source

An abstract representation of an image.

emptyGraphic :: Graphic Source

An empty drawing.

overGraphic :: Graphic -> Graphic -> Graphic Source

A composite drawing made by overlaying the first argument on the second.

overGraphics :: [Graphic] -> Graphic Source

Overlay a list of drawings.

## Color

data Color Source

Named colors.

Constructors

Black |
Blue |
Green |
Cyan |
Red |
Magenta |
Yellow |
White |

Instances

Bounded Color |
Enum Color |
Eq Color |
Ord Color |
Read Color |
Show Color |
Ix Color |

withColor :: Color -> Graphic -> Graphic Source

Set the default drawing color for a `Graphic`.

## Drawing text

text :: Point -> String -> Graphic Source

Render a `String` positioned relative to the specified `Point`.

## Drawing shapes

type Point = (Int, Int)Source

A position within a window, measured in pixels to the right and down from the top left corner.

ellipse Source

Arguments

:: Point | a corner of the rectangle bounding the ellipse.
-> Point | the opposite corner of the rectangle bounding the ellipse.
-> Graphic | a filled shape

A filled ellipse that fits inside a rectangle defined by two `Point`s on the window.

shearEllipse Source

Arguments

:: Point | a corner of the bounding parallelogram.
-> Point | another corner of the parallelogram, adjacent to the first.
-> Point | another corner of the parallelogram, adjacent to the first and thus opposite to the second.
-> Graphic | a filled shape

A filled sheared ellipse that fits inside a parallelogram defined by three `Point`s on the window. This function is implemented using polygons on both Win32 and X11.

line :: Point -> Point -> Graphic Source

A line between two `Point`s.

polygon :: [Point] -> Graphic Source

A filled polygon defined by a list of `Point`s.

polyline :: [Point] -> Graphic Source

A series of lines through a list of `Point`s.

polyBezier :: [Point] -> Graphic Source

A series of (unfilled) Bezier curves defined by a list of 3n+1 control `Point`s. This function is not supported on X11 (it yields an error message and a `polyline`).

type Angle = Double Source

An angle in degrees (0 to 360).

arc Source

Arguments

:: Point | a corner of the rectangle bounding the ellipse.
-> Point | the opposite corner of the rectangle bounding the ellipse.
-> Angle | the start angle of the arc, measured counter-clockwise from the horizontal.
-> Angle | the extent of the arc, measured counter-clockwise from the start angle.
-> Graphic | a filled shape

A filled arc from an ellipse.

## Regions

data Region Source

createRectangle :: Point -> Point -> Region Source

A rectangular region, with the given points as opposite corners.

createEllipse :: Point -> Point -> Region Source

An elliptical region that fits in the rectangle with the given points as opposite corners.

createPolygon :: [Point] -> Region Source

A polygonal region defined by a list of `Point`s.

andRegion :: Region -> Region -> Region Source

The intersection of two regions.

orRegion :: Region -> Region -> Region Source

The union of two regions.

xorRegion :: Region -> Region -> Region Source

The symmetric difference of two regions.

diffRegion :: Region -> Region -> Region Source

The part of the first region that is not also in the second.

drawRegion :: Region -> Graphic Source

Draw a `Region` in the current color.

# User interaction

## Keyboard events

getKey :: Window -> IO Char Source

Wait until a key is pressed and released, and return the corresponding character.

## Mouse events

getLBP :: Window -> IO Point Source

Wait for a press of the left mouse button, and return the position of the mouse cursor.

getRBP :: Window -> IO Point Source

Wait for a press of the right mouse button, and return the position of the mouse cursor.

## General events

data Event Source

User interface events

Constructors

Key | occurs when a key was pressed or released.

Fields

char :: Char

  character corresponding to the key

isDown :: Bool

  if `True`, the button was pressed; otherwise it was released

  if `True`, the key was pressed; otherwise it was released

Button | occurs when a mouse button is pressed or released.

Fields

pt :: Point

  the position of the mouse cursor

  the position of the mouse cursor

isLeft :: Bool

  if `True`, it was the left button

isDown :: Bool

  if `True`, the button was pressed; otherwise it was released

  if `True`, the key was pressed; otherwise it was released

MouseMove | occurs when the mouse is moved inside the window.

Fields

pt :: Point

  the position of the mouse cursor

  the position of the mouse cursor

Resize | occurs when the window is resized. The new window size can be discovered using `getWindowSize`.
Closed | occurs when the window is closed.

Instances

Show Event |

maybeGetWindowEvent :: Window -> IO (Maybe Event)Source

Return a pending eventin the window, if any.

getWindowEvent :: Window -> IO Event Source

Wait for the next event in the window.

# Time

data Word32

32-bit unsigned integer type

Instances

Bounded Word32 |
Enum Word32 |
Eq Word32 |
Integral Word32 |
Num Word32 |
Ord Word32 |
Read Word32 |
Real Word32 |
Show Word32 |
Ix Word32 |
Bits Word32 |

getWindowTick :: Window -> IO ()Source

Wait for the next tick event from the timer on the given window.

timeGetTime :: IO Word32 Source

The current time of day (in milliseconds).

word32ToInt :: Word32 -> Int Source

An obsolete special case of `fromIntegral`.