| Graphics Libraries (HGL package) | Contents | Index

Graphics.SOE

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

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
Word32
getWindowTick :: Window -> IO ()
timeGetTime :: IO Word32
word32ToInt :: Word32 -> Int

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

:: 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
Ix Color
Ord Color
Read Color
Show 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

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

:: 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
A line between two `Point`s.
polygon :: [Point] -> Graphic
A filled polygon defined by a list of `Point`s.
polyline :: [Point] -> Graphic
A series of lines through a list of `Point`s.
polyBezier :: [Point] -> Graphic
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
An angle in degrees (0 to 360).
arc

:: 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 `Point`s.
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.

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.

pt :: Point | 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

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

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
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`.
Produced by Haddock version 0.7