Graphics.SOE

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.

Getting started

runGraphics :: IO () -> IO ()

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

Title of a window.

type Size = (Int, Int)

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

data Window

openWindow :: Title -> Size -> IO Window

Create a window with the given title and size.

getWindowSize :: Window -> IO Size

The current size of the window.

clearWindow :: Window -> IO ()

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

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

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 ()

Another name for drawInWindow, retained for backwards compatibility.

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

Set the current drawing in a window.

closeWindow :: Window -> IO ()

Close the window.

General windows

openWindowEx

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

How to draw in a window.

drawGraphic :: RedrawMode

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

drawBufferedGraphic :: RedrawMode

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

Drawing

type Graphic = Draw ()

An abstract representation of an image.

emptyGraphic :: Graphic

An empty drawing.

overGraphic :: Graphic -> Graphic -> Graphic

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

overGraphics :: [Graphic] -> Graphic

Overlay a list of drawings.

Color

data Color

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

Set the default drawing color for a Graphic.

Drawing text

text :: Point -> String -> Graphic

Render a String positioned relative to the specified Point.

Drawing shapes

type Point = (Int, Int)

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

ellipse

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 Points on the window.

shearEllipse

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 Points on the window. This function is implemented using polygons on both Win32 and X11.

line :: Point -> Point -> Graphic

A line between two Points.

polygon :: [Point] -> Graphic

A filled polygon defined by a list of Points.

polyline :: [Point] -> Graphic

A series of lines through a list of Points.

polyBezier :: [Point] -> Graphic

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

type Angle = Double

An angle in degrees (0 to 360).

arc

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

createRectangle :: Point -> Point -> Region

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

createEllipse :: Point -> Point -> Region

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

createPolygon :: [Point] -> Region

A polygonal region defined by a list of Points.

andRegion :: Region -> Region -> Region

The intersection of two regions.

orRegion :: Region -> Region -> Region

The union of two regions.

xorRegion :: Region -> Region -> Region

The symmetric difference of two regions.

diffRegion :: Region -> Region -> Region

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

drawRegion :: Region -> Graphic

Draw a Region in the current color.

User interaction

Keyboard events

getKey :: Window -> IO Char

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

Mouse events

getLBP :: Window -> IO Point

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

getRBP :: Window -> IO Point

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

General events

data Event

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 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

isLeft :: Bool

if True, it was the left button

isDown :: Bool

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

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)

Return a pending eventin the window, if any.

getWindowEvent :: Window -> IO Event

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 ()

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

timeGetTime :: IO Word32

The current time of day (in milliseconds).

word32ToInt :: Word32 -> Int

An obsolete special case of fromIntegral.