libghc-hgl-doc 3.2.0.5-1 / usr / share / doc / libghc-hgl-doc / html / HGL.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A simple graphics library based on X11 or Win32
--   
--   A simple graphics library, designed to give the programmer access to
--   most interesting parts of the Win32 Graphics Device Interface and X11
--   library without exposing the programmer to the pain and anguish
--   usually associated with using these interfaces.
--   
--   The library also includes a module Graphics.SOE providing the
--   interface used in <a>The Haskell School of Expression</a>, by Paul
--   Hudak, cf <a>http://www.haskell.org/soe/</a>.
@package HGL
@version 3.2.0.5


-- | The <a>Draw</a> monad, with graphical objects as a special case.
module Graphics.HGL.Draw.Monad

-- | An abstract representation of an image.
type Graphic = Draw ()

-- | Monad for sequential construction of images.
data Draw a

-- | Embed an <a>IO</a> action in a drawing action.
ioToDraw :: IO a -> Draw a

-- | Wrap a drawing action in initialization and finalization actions.
bracket :: Draw a -> (a -> Draw b) -> (a -> Draw c) -> Draw c

-- | A variant of <a>bracket</a> in which the inner drawing action does not
--   use the result of the pre-operation.
bracket_ :: Draw a -> (a -> Draw b) -> Draw c -> Draw c


-- | Abstract representation of keys.
module Graphics.HGL.Key
data Key

-- | Converts a character key to a character.
keyToChar :: Key -> Char
isCharKey :: Key -> Bool
isBackSpaceKey :: Key -> Bool
isTabKey :: Key -> Bool
isClearKey :: Key -> Bool
isReturnKey :: Key -> Bool
isEscapeKey :: Key -> Bool
isDeleteKey :: Key -> Bool
isHomeKey :: Key -> Bool
isLeftKey :: Key -> Bool
isUpKey :: Key -> Bool
isRightKey :: Key -> Bool
isDownKey :: Key -> Bool
isPriorKey :: Key -> Bool
isPageUpKey :: Key -> Bool
isNextKey :: Key -> Bool
isPageDownKey :: Key -> Bool
isEndKey :: Key -> Bool
isShiftLKey :: Key -> Bool
isShiftRKey :: Key -> Bool
isControlLKey :: Key -> Bool
isControlRKey :: Key -> Bool


-- | Running graphical actions.
module Graphics.HGL.Run

-- | 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 <a>runGraphics</a>.
runGraphics :: IO () -> IO ()


-- | Types for units in a simple graphics library.
module Graphics.HGL.Units

-- | A position within a window, measured in pixels to the right and down
--   from the top left corner.
type Point = (Int, Int)

-- | A (width, height) pair, both measured in pixels.
type Size = (Int, Int)

-- | An angle in degrees (0 to 360).
type Angle = Double

-- | Time, measured in milliseconds.
type Time = Integer


-- | Drawing various shapes.
module Graphics.HGL.Draw.Picture

-- | A filled arc from an ellipse.
arc :: Point -> Point -> Angle -> Angle -> Graphic

-- | A filled ellipse that fits inside a rectangle defined by two
--   <a>Point</a>s on the window.
ellipse :: Point -> Point -> Graphic

-- | A filled sheared ellipse that fits inside a parallelogram defined by
--   three <a>Point</a>s on the window. This function is implemented using
--   polygons on both Win32 and X11.
shearEllipse :: Point -> Point -> Point -> Graphic

-- | A line between two <a>Point</a>s.
line :: Point -> Point -> Graphic

-- | A series of lines through a list of <a>Point</a>s.
polyline :: [Point] -> Graphic

-- | A filled polygon defined by a list of <a>Point</a>s.
polygon :: [Point] -> Graphic

-- | A series of (unfilled) Bezier curves defined by a list of 3<i>n</i>+1
--   control <a>Point</a>s. This function is not supported on X11 (it
--   yields an error message and a <a>polyline</a>).
polyBezier :: [Point] -> Graphic


-- | Drawing text.
module Graphics.HGL.Draw.Text

-- | Render a <a>String</a> positioned relative to the specified
--   <a>Point</a>.
text :: Point -> String -> Graphic

-- | <tt><a>textInfo</a> s</tt> returns:
--   
--   <ol>
--   <li>The offset at which the string would be drawn according to the
--   current text alignment (e.g., <tt>(<a>Center</a>,
--   <a>Baseline</a>)</tt> will result in an offset of (-width/2,0))</li>
--   <li>The size at which the text would be drawn using the current
--   font.</li>
--   </ol>
textInfo :: String -> Draw (Point, Size)

-- | A color, comprising red, green and blue components.
data RGB
RGB :: Word8 -> Word8 -> Word8 -> RGB

-- | Set the foreground color for drawing text, returning the previous
--   value.
setTextColor :: RGB -> Draw RGB

-- | Set the background color for drawing text, returning the previous
--   value. The background color is ignored when the mode is
--   <a>Transparent</a>.
setBkColor :: RGB -> Draw RGB

-- | Background mode for drawing text.
data BkMode

-- | Draw text on a bounding rectangle filled with the current background
--   color.
Opaque :: BkMode

-- | Draw text without a background rectangle.
Transparent :: BkMode

-- | Set the background mode for drawing text, returning the previous
--   value.
setBkMode :: BkMode -> Draw BkMode

-- | How strings drawn with <a>text</a> are positioned relative to the
--   specified reference point.
type Alignment = (HAlign, VAlign)

-- | Horizontal alignment of text. Names have a tick to distinguish them
--   from <a>Prelude</a> names.
data HAlign

-- | align the left edge of the text with the reference point
Left' :: HAlign

-- | center the text with the reference point
Center :: HAlign

-- | align the right edge of the text with the reference point
Right' :: HAlign

-- | Vertical alignment of text.
data VAlign

-- | align the top edge of the text with the reference point
Top :: VAlign

-- | align the baseline of the text with the reference point
Baseline :: VAlign

-- | align the bottom edge of the text with the reference point
Bottom :: VAlign

-- | Set the alignment for drawing text, returning the previous value.
setTextAlignment :: Alignment -> Draw Alignment


-- | Brushes, used for filling shapes.
module Graphics.HGL.Draw.Brush
data Brush

-- | Create a <a>Brush</a>.
createBrush :: RGB -> IO Brush

-- | Destroy a <a>Brush</a> created with <a>createBrush</a>.
deleteBrush :: Brush -> IO ()

-- | Set the <a>Brush</a> for subsequent drawing, returning the previous
--   setting.
selectBrush :: Brush -> Draw Brush

-- | Create a <a>Brush</a> locally to a drawing.
mkBrush :: RGB -> (Brush -> Draw a) -> Draw a


-- | Pens, used for drawing lines.
--   
--   Portability notes:
--   
--   <ul>
--   <li>On Win32, the pen is also used to draw a line round all the filled
--   shapes --- so the pen color also affects how polygons, ellipses and
--   regions are drawn.</li>
--   <li>On Win32, the <a>Style</a> is ignored (i.e. treated as
--   <a>Solid</a>) for pens of width greater than 1. This problem does not
--   apply to X11.</li>
--   </ul>
module Graphics.HGL.Draw.Pen
data Pen

-- | The style of line drawn by a pen.
data Style
Solid :: Style
Dash :: Style
Dot :: Style
DashDot :: Style
DashDotDot :: Style
Null :: Style
InsideFrame :: Style

-- | Create a <a>Pen</a>.
createPen :: Style -> Int -> RGB -> IO Pen

-- | Destroy a <a>Pen</a> created with <a>createPen</a>.
deletePen :: Pen -> IO ()

-- | Set the <a>Pen</a> for subsequent drawing, returning the previous
--   setting.
selectPen :: Pen -> Draw Pen

-- | Create a <a>Pen</a> locally to a drawing.
mkPen :: Style -> Int -> RGB -> (Pen -> Draw a) -> Draw a


-- | An efficient representation of sets of pixels.
module Graphics.HGL.Draw.Region
data Region

-- | An empty region. This is not supported on Win32. It is possible to use
--   an empty rectangle region instead.
emptyRegion :: Region

-- | A rectangular region, with the given points as opposite corners.
rectangleRegion :: Point -> Point -> Region

-- | An elliptical region that fits in the rectangle with the given points
--   as opposite corners.
ellipseRegion :: Point -> Point -> Region

-- | A polygonal region defined by a list of <a>Point</a>s.
polygonRegion :: [Point] -> Region

-- | The intersection of two regions.
intersectRegion :: Region -> Region -> Region

-- | The union of two regions.
unionRegion :: Region -> Region -> Region

-- | The part of the first region that is not also in the second.
subtractRegion :: Region -> Region -> Region

-- | The symmetric difference of two regions.
xorRegion :: Region -> Region -> Region

-- | Fill a <a>Region</a> using the current <a>Brush</a>.
regionToGraphic :: Region -> Graphic


-- | Text fonts.
--   
--   Portability notes:
--   
--   <ul>
--   <li>X11 does not directly support font rotation so <a>createFont</a>
--   and <a>mkFont</a> always ignore the rotation angle argument in the X11
--   implementation of this library.</li>
--   <li>Many of the font families typically available on Win32 are not
--   available on X11 (and <i>vice-versa</i>). In our experience, the font
--   families <i>courier</i>, <i>helvetica</i> and <i>times</i> are
--   somewhat portable.</li>
--   </ul>
module Graphics.HGL.Draw.Font
data Font

-- | Create a font. The rotation angle is ignored if the font is not a
--   "TrueType" font (e.g., a <tt>System</tt> font on Win32).
createFont :: Size -> Angle -> Bool -> Bool -> String -> IO Font

-- | Delete a font created with <a>createFont</a>.
deleteFont :: Font -> IO ()

-- | Set the font for subsequent text, and return the previous font.
selectFont :: Font -> Draw Font

-- | Generate a font for use in a drawing, and delete it afterwards. The
--   rotation angle is ignored if the font is not a "TrueType" font (e.g.,
--   a <tt>System</tt> font on Win32).
mkFont :: Size -> Angle -> Bool -> Bool -> String -> (Font -> Draw a) -> Draw a


-- | Drawing in a simple graphics library.
module Graphics.HGL.Draw


-- | Windows in a simple graphics library.
module Graphics.HGL.Window
data Window

-- | Title of a window.
type Title = String

-- | How to draw in a window.
data RedrawMode

-- | use a <i>double buffer</i> to reduce flicker. You should probably use
--   this for animations.
DoubleBuffered :: RedrawMode

-- | draw directly to the window. This runs slightly faster but is more
--   prone to flicker.
Unbuffered :: RedrawMode

-- | General window creation.
openWindowEx :: Title -> Maybe Point -> Size -> RedrawMode -> Maybe Time -> IO Window

-- | The position of the top left corner of the window on the screen, and
--   the size of the window.
getWindowRect :: Window -> IO (Point, Size)

-- | Close the window.
closeWindow :: Window -> IO ()

-- | Set the current drawing in a window.
setGraphic :: Window -> Graphic -> IO ()

-- | Get the current drawing in a window.
getGraphic :: Window -> IO Graphic

-- | Update the drawing for a window. Note that this does not force a
--   redraw.
modGraphic :: Window -> (Graphic -> Graphic) -> IO ()
directDraw :: Window -> Graphic -> IO ()

-- | A user interface event.
--   
--   Notes:
--   
--   <ul>
--   <li>Programmers should assume that the <a>Event</a> datatype will be
--   extended in the not-too-distant future and that individual events may
--   change slightly. As a minimum, you should add a "match anything"
--   alternative to any function which pattern matches against
--   <a>Event</a>s.</li>
--   <li>X11 systems typically have three button mice. Button 1 is used as
--   the left button, button 3 as the right button and button 2 (the middle
--   button) is ignored.</li>
--   </ul>
data Event

-- | a properly translated character, sent after a key press.
Char :: Char -> Event

-- | the character represented by a key combination
char :: Event -> Char

-- | occurs when a key was pressed or released.
Key :: Key -> Bool -> Event

-- | representation of the keyboard keys pressed
keysym :: Event -> Key

-- | if <a>True</a>, the button was pressed; otherwise it was released
--   
--   if <a>True</a>, the key was pressed; otherwise it was released
isDown :: Event -> Bool

-- | occurs when a mouse button is pressed or released.
Button :: Point -> Bool -> Bool -> Event

-- | the position of the mouse cursor after the movement
--   
--   the position of the mouse cursor
pt :: Event -> Point

-- | if <a>True</a>, it was the left button
isLeft :: Event -> Bool

-- | if <a>True</a>, the button was pressed; otherwise it was released
--   
--   if <a>True</a>, the key was pressed; otherwise it was released
isDown :: Event -> Bool

-- | occurs when the mouse is moved inside the window.
MouseMove :: Point -> Event

-- | the position of the mouse cursor after the movement
--   
--   the position of the mouse cursor
pt :: Event -> Point

-- | occurs when the window is resized.
Resize :: Event

-- | occurs when the window is closed.
Closed :: Event

-- | Wait for the next event on the given window.
getWindowEvent :: Window -> IO Event

-- | Check for a pending event on the given window.
maybeGetWindowEvent :: Window -> IO (Maybe Event)

-- | Wait for the next tick event from the timer on the given window.
getWindowTick :: Window -> IO ()

-- | Time in milliseconds since some arbitrary epoch.
getTime :: IO Integer


-- | Core functions of a simple graphics library.
module Graphics.HGL.Core


-- | Utility functions for a simple graphics library.
module Graphics.HGL.Utils

-- | Create a window with the given title and size.
openWindow :: Title -> Size -> IO Window

-- | Erase all drawing in the window. (That is, set the <a>Graphic</a> held
--   by the window to <a>emptyGraphic</a>.)
clearWindow :: Window -> IO ()

-- | Draw the given graphic on the window, on top of anything that is
--   already there. (That is, combine the given <a>Graphic</a> and the one
--   held by the window using <a>overGraphic</a>, store the result in the
--   window, and display it.)
drawInWindow :: Window -> Graphic -> IO ()

-- | Run an action inside a new window, ensuring that the window is
--   destroyed on exit.
withWindow :: Title -> Size -> (Window -> IO a) -> IO a

-- | A variant of <a>withWindow</a> that ignores the result of the action.
withWindow_ :: Title -> Size -> (Window -> IO a) -> IO ()

-- | A combination of <a>runGraphics</a> and <a>withWindow_</a>.
runWindow :: Title -> Size -> (Window -> IO a) -> IO ()

-- | The current size of the window.
getWindowSize :: Window -> IO Size

-- | Wait for a press of the left mouse button, and return the position of
--   the mouse cursor.
getLBP :: Window -> IO Point

-- | Wait for a press of the right mouse button, and return the position of
--   the mouse cursor.
getRBP :: Window -> IO Point

-- | Wait for a mouse button to be pressed or released, and return the
--   position of the mouse cursor.
getButton :: Window -> Bool -> Bool -> IO Point

-- | Wait until a key is pressed and released.
getKey :: Window -> IO Key

-- | Wait until a key is pressed (if the second argument is <a>True</a>) or
--   released (otherwise).
getKeyEx :: Window -> Bool -> IO Key

-- | Wait for a translated character (from a key press). Use in preference
--   to <a>getKey</a> if the aim is to read text.
wGetChar :: Window -> IO Char

-- | An empty drawing.
emptyGraphic :: Graphic

-- | A composite drawing made by overlaying the first argument on the
--   second.
overGraphic :: Graphic -> Graphic -> Graphic

-- | Overlay a list of drawings.
overGraphics :: [Graphic] -> Graphic

-- | Set the default font for a drawing.
withFont :: Font -> Graphic -> Graphic

-- | Set the default color for drawing text.
withTextColor :: RGB -> Graphic -> Graphic

-- | Set the default alignment of text in a drawing.
withTextAlignment :: Alignment -> Graphic -> Graphic

-- | Set the default background color for drawing text with background mode
--   <a>Opaque</a>. The background color is ignored when the mode is
--   <a>Transparent</a>.
withBkColor :: RGB -> Graphic -> Graphic

-- | Set the default background mode for drawing text.
withBkMode :: BkMode -> Graphic -> Graphic

-- | Set the default pen for drawing lines.
withPen :: Pen -> Graphic -> Graphic

-- | Set the default brush for filling shapes.
withBrush :: Brush -> Graphic -> Graphic

-- | A convenience function that sets the brush, pen and text colors to the
--   same value.
withRGB :: RGB -> Graphic -> Graphic

-- | Named colors.
data Color
Black :: Color
Blue :: Color
Green :: Color
Cyan :: Color
Red :: Color
Magenta :: Color
Yellow :: Color
White :: Color

-- | A mapping of <a>Color</a> names to <a>RGB</a> triples.
colorList :: [(Color, RGB)]

-- | A mapping of <a>Color</a> names to <a>RGB</a> triples.
colorTable :: Array Color RGB

-- | Set the default drawing color for a <a>Graphic</a>.
withColor :: Color -> Graphic -> Graphic

-- | Run two <a>IO</a> actions in parallel and terminate when both actions
--   terminate.
par :: IO a -> IO b -> IO (a, b)

-- | Run two <a>IO</a> actions in parallel and terminate when both actions
--   terminate, discarding the results of the actions.
par_ :: IO a -> IO b -> IO ()

-- | Run several <a>IO</a> actions in parallel and terminate when all
--   actions terminate, discarding the results of the actions.
parMany :: [IO ()] -> IO ()
instance Eq Color
instance Ord Color
instance Bounded Color
instance Enum Color
instance Ix Color
instance Show Color
instance Read Color


-- | A simple graphics library.
module Graphics.HGL


-- | The graphics library used in <i>The Haskell School of Expression</i>,
--   by Paul Hudak, cf <a>http://www.haskell.org/soe/</a>.
--   
--   <i>Notes:</i>
--   
--   <ul>
--   <li>This module is called <tt>SOEGraphics</tt> in the book. It is a
--   cut down version of <a>Graphics.HGL</a>, with the interface frozen to
--   match the book.</li>
--   <li>In chapters 13, 17 and 19 of the book, there are imports of
--   modules <tt>Win32Misc</tt> and <tt>Word</tt>. These should be omitted,
--   as <a>timeGetTime</a> and <a>word32ToInt</a> are provided by this
--   module.</li>
--   </ul>
module Graphics.SOE

-- | 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 <a>runGraphics</a>.
runGraphics :: IO () -> IO ()

-- | Title of a window.
type Title = String

-- | A (width, height) pair, both measured in pixels.
type Size = (Int, Int)
data Window

-- | Create a window with the given title and size.
openWindow :: Title -> Size -> IO Window

-- | The current size of the window.
getWindowSize :: Window -> IO Size

-- | Erase all drawing in the window. (That is, set the <a>Graphic</a> held
--   by the window to <a>emptyGraphic</a>.)
clearWindow :: Window -> IO ()

-- | Draw the given graphic on the window, on top of anything that is
--   already there. (That is, combine the given <a>Graphic</a> and the one
--   held by the window using <a>overGraphic</a>, store the result in the
--   window, and display it.)
drawInWindow :: Window -> Graphic -> IO ()

-- | Another name for <a>drawInWindow</a>, retained for backwards
--   compatibility.
drawInWindowNow :: Window -> Graphic -> IO ()

-- | Set the current drawing in a window.
setGraphic :: Window -> Graphic -> IO ()

-- | Close the window.
closeWindow :: Window -> IO ()

-- | an extended version of <a>openWindow</a>.
openWindowEx :: Title -> Maybe Point -> Maybe Size -> RedrawMode -> Maybe Word32 -> IO Window

-- | How to draw in a window.
data RedrawMode

-- | Draw directly to the window (slightly faster than
--   <a>drawBufferedGraphic</a>, but more prone to flicker).
drawGraphic :: RedrawMode

-- | Use a <i>double buffer</i> to reduce flicker and thus improve the look
--   of animations.
drawBufferedGraphic :: RedrawMode

-- | An abstract representation of an image.
type Graphic = Draw ()

-- | An empty drawing.
emptyGraphic :: Graphic

-- | A composite drawing made by overlaying the first argument on the
--   second.
overGraphic :: Graphic -> Graphic -> Graphic

-- | Overlay a list of drawings.
overGraphics :: [Graphic] -> Graphic

-- | Named colors.
data Color
Black :: Color
Blue :: Color
Green :: Color
Cyan :: Color
Red :: Color
Magenta :: Color
Yellow :: Color
White :: Color

-- | Set the default drawing color for a <a>Graphic</a>.
withColor :: Color -> Graphic -> Graphic

-- | Render a <a>String</a> positioned relative to the specified
--   <a>Point</a>.
text :: Point -> String -> Graphic

-- | A position within a window, measured in pixels to the right and down
--   from the top left corner.
type Point = (Int, Int)

-- | A filled ellipse that fits inside a rectangle defined by two
--   <a>Point</a>s on the window.
ellipse :: Point -> Point -> Graphic

-- | A filled sheared ellipse that fits inside a parallelogram defined by
--   three <a>Point</a>s on the window. This function is implemented using
--   polygons on both Win32 and X11.
shearEllipse :: Point -> Point -> Point -> Graphic

-- | A line between two <a>Point</a>s.
line :: Point -> Point -> Graphic

-- | A filled polygon defined by a list of <a>Point</a>s.
polygon :: [Point] -> Graphic

-- | A series of lines through a list of <a>Point</a>s.
polyline :: [Point] -> Graphic

-- | A series of (unfilled) Bezier curves defined by a list of 3<i>n</i>+1
--   control <a>Point</a>s. This function is not supported on X11 (it
--   yields an error message and a <a>polyline</a>).
polyBezier :: [Point] -> Graphic

-- | An angle in degrees (0 to 360).
type Angle = Double

-- | A filled arc from an ellipse.
arc :: Point -> Point -> Angle -> Angle -> Graphic
data Region

-- | A rectangular region, with the given points as opposite corners.
createRectangle :: Point -> Point -> Region

-- | An elliptical region that fits in the rectangle with the given points
--   as opposite corners.
createEllipse :: Point -> Point -> Region

-- | A polygonal region defined by a list of <a>Point</a>s.
createPolygon :: [Point] -> Region

-- | The intersection of two regions.
andRegion :: Region -> Region -> Region

-- | The union of two regions.
orRegion :: Region -> Region -> Region

-- | The symmetric difference of two regions.
xorRegion :: Region -> Region -> Region

-- | The part of the first region that is not also in the second.
diffRegion :: Region -> Region -> Region

-- | Draw a <a>Region</a> in the current color.
drawRegion :: Region -> Graphic

-- | Wait until a key is pressed and released, and return the corresponding
--   character.
getKey :: Window -> IO Char

-- | Wait for a press of the left mouse button, and return the position of
--   the mouse cursor.
getLBP :: Window -> IO Point

-- | Wait for a press of the right mouse button, and return the position of
--   the mouse cursor.
getRBP :: Window -> IO Point

-- | User interface events
data Event

-- | occurs when a key was pressed or released.
Key :: Char -> Bool -> Event

-- | character corresponding to the key
char :: Event -> Char

-- | if <a>True</a>, the button was pressed; otherwise it was released
--   
--   if <a>True</a>, the key was pressed; otherwise it was released
isDown :: Event -> Bool

-- | occurs when a mouse button is pressed or released.
Button :: Point -> Bool -> Bool -> Event

-- | the position of the mouse cursor
--   
--   the position of the mouse cursor
pt :: Event -> Point

-- | if <a>True</a>, it was the left button
isLeft :: Event -> Bool

-- | if <a>True</a>, the button was pressed; otherwise it was released
--   
--   if <a>True</a>, the key was pressed; otherwise it was released
isDown :: Event -> Bool

-- | occurs when the mouse is moved inside the window.
MouseMove :: Point -> Event

-- | the position of the mouse cursor
--   
--   the position of the mouse cursor
pt :: Event -> Point

-- | occurs when the window is resized. The new window size can be
--   discovered using <a>getWindowSize</a>.
Resize :: Event

-- | occurs when the window is closed.
Closed :: Event

-- | Return a pending eventin the window, if any.
maybeGetWindowEvent :: Window -> IO (Maybe Event)

-- | Wait for the next event in the window.
getWindowEvent :: Window -> IO Event

-- | 32-bit unsigned integer type
data Word32 :: *

-- | Wait for the next tick event from the timer on the given window.
getWindowTick :: Window -> IO ()

-- | The current time of day (in milliseconds).
timeGetTime :: IO Word32

-- | An obsolete special case of <a>fromIntegral</a>.
word32ToInt :: Word32 -> Int
instance Show Event