@@ -1,6 +1,35 @@
1−
21module Graphics.Collage where
32
3+{-| The collage API is for freeform graphics. You can move, rotate, scale, etc.
4+all sorts of forms including lines, shapes, images, and elements.
5+
6+# Unstructured Graphics
7+@docs collage
8+
9+# Creating Forms
10+@docs toForm, filled, textured, gradient, outlined, traced
11+
12+# Transforming Forms
13+@docs move, moveX, moveY, scale, rotate, alpha
14+
15+# Grouping Forms
16+Grouping forms makes it easier to write modular graphics code. You can create
17+a form that is a composite of many subforms. From there it is easy to transform
18+it as a single unit.
19+
20+@docs group, groupTransform
21+
22+# Shapes
23+@docs rect, oval, square, circle, ngon, polygon
24+
25+# Paths
26+@docs segment, path
27+
28+# Line Styles
29+@docs solid, dashed, dotted, LineStyle, LineCap, LineJoin, defaultLine
30+
31+-}
32+
433import open Basics
534import List
635import Either (Either, Left, Right)
@@ -25,16 +54,18 @@ data FillStyle
2554 | Texture String
2655 | Grad Gradient
2756
28−-- The shape of the ends of a line.
57+{-| The shape of the ends of a line. -}
2958data LineCap = Flat | Round | Padded
3059
31−-- The shape of the “joints” of a line, where each line segment
32−-- meets. `Sharp` takes an argument to limit the length of the joint. This
33−-- defaults to 10.
60+{-| The shape of the “joints” of a line, where each line segment
61+meets. `Sharp` takes an argument to limit the length of the joint. This
62+defaults to 10.
63+-}
3464data LineJoin = Smooth | Sharp Float | Clipped
3565
36−-- All of the attributes of a line style. This lets you build up a line style
37−-- however you want. You can also update existing line styles with record updates.
66+{-| All of the attributes of a line style. This lets you build up a line style
67+however you want. You can also update existing line styles with record updates.
68+-}
3869type LineStyle = {
3970 color : Color,
4071 width : Float,
@@ -44,11 +75,12 @@ type LineStyle = {
4475 dashOffset : Int
4576 }
4677
47−-- The default line style, which is solid black with flat caps and sharp joints.
48−-- You can use record updates to build the line style you
49−-- want. For example, to make a thicker line, you could say:
50−--
51−-- { defaultLine | width <- 10 }
78+{-| The default line style, which is solid black with flat caps and sharp joints.
79+You can use record updates to build the line style you
80+want. For example, to make a thicker line, you could say:
81+
82+ { defaultLine | width <- 10 }
83+-}
5284defaultLine : LineStyle
5385defaultLine = {
5486 color = black,
@@ -59,15 +91,15 @@ defaultLine = {
5991 dashOffset = 0
6092 }
6193
62−-- Create a solid line style with a given color.
94+{-| Create a solid line style with a given color. -}
6395solid : Color -> LineStyle
6496solid clr = { defaultLine | color <- clr }
6597
66−-- Create a dashed line style with a given color. Dashing equals `[8,4]`.
98+{-| Create a dashed line style with a given color. Dashing equals `[8,4]`. -}
6799dashed : Color -> LineStyle
68100dashed clr = { defaultLine | color <- clr, dashing <- [8,4] }
69101
70−-- Create a dotted line style with a given color. Dashing equals `[3,3]`.
102+{-| Create a dotted line style with a given color. Dashing equals `[3,3]`. -}
71103dotted : Color -> LineStyle
72104dotted clr = { defaultLine | color <- clr, dashing <- [3,3] }
73105
@@ -83,113 +115,125 @@ form f = { theta=0, scale=1, x=0, y=0, alpha=1, form=f }
83115
84116fill style shape = form (FShape (Right style) shape)
85117
86−-- Create a filled in shape.
118+{-| Create a filled in shape. -}
87119filled : Color -> Shape -> Form
88120filled color shape = fill (Solid color) shape
89121
90−-- Create a textured shape. The texture is described by some url and is
91−-- tiled to fill the entire shape.
122+{-| Create a textured shape. The texture is described by some url and is
123+tiled to fill the entire shape.
124+-}
92125textured : String -> Shape -> Form
93126textured src shape = fill (Texture src) shape
94127
95−-- Fill a shape with a [gradient](/docs/Color.elm#linear).
128+{-| Fill a shape with a [gradient](/docs/Color.elm#linear). -}
96129gradient : Gradient -> Shape -> Form
97130gradient grad shape = fill (Grad grad) shape
98131
99−-- Outline a shape with a given line style.
132+{-| Outline a shape with a given line style. -}
100133outlined : LineStyle -> Shape -> Form
101134outlined style shape = form (FShape (Left style) shape)
102135
103−-- Trace a path with a given line style.
136+{-| Trace a path with a given line style. -}
104137traced : LineStyle -> Path -> Form
105138traced style path = form (FPath style path)
106139
107−-- Create a sprite from a sprite sheet. It cuts out a rectangle
108−-- at a given position.
140+{-| Create a sprite from a sprite sheet. It cuts out a rectangle
141+at a given position.
142+-}
109143sprite : Int -> Int -> (Int,Int) -> String -> Form
110144sprite w h pos src = form (FImage w h pos src)
111145
112−-- Turn any `Element` into a `Form`. This lets you use text, gifs, and video
113−-- in your collage. This means you can move, rotate, and scale
114−-- an `Element` however you want.
146+{-| Turn any `Element` into a `Form`. This lets you use text, gifs, and video
147+in your collage. This means you can move, rotate, and scale
148+an `Element` however you want.
149+-}
115150toForm : Element -> Form
116151toForm e = form (FElement e)
117152
118−-- Flatten many forms into a single `Form`. This lets you move and rotate them
119−-- as a single unit, making it possible to build small, modular components.
153+{-| Flatten many forms into a single `Form`. This lets you move and rotate them
154+as a single unit, making it possible to build small, modular components.
155+-}
120156group : [Form] -> Form
121157group fs = form (FGroup identity fs)
122158
123−-- Flatten many forms into a single `Form` and then apply a matrix
124−-- transformation.
159+{-| Flatten many forms into a single `Form` and then apply a matrix
160+transformation.
161+-}
125162groupTransform : Transform2D -> [Form] -> Form
126163groupTransform matrix fs = form (FGroup matrix fs)
127164
128−-- Rotate a form by a given angle. Rotate takes standard Elm angles (radians)
129−-- and turns things counterclockwise. So to turn `form` 30° to the left
130−-- you would say, `(rotate (degrees 30) form)`.
165+{-| Rotate a form by a given angle. Rotate takes standard Elm angles (radians)
166+and turns things counterclockwise. So to turn `form` 30° to the left
167+you would say, `(rotate (degrees 30) form)`.
168+-}
131169rotate : number -> Form -> Form
132170rotate t f = { f | theta <- f.theta + t }
133171
134−-- Scale a form by a given factor. Scaling by 2 doubles the size.
172+{-| Scale a form by a given factor. Scaling by 2 doubles the size.
173+-}
135174scale : number -> Form -> Form
136175scale s f = { f | scale <- f.scale * s }
137176
138−-- Move a form by the given amount. This is a relative translation so
139−-- `(move (10,10) form)` would move `form` ten pixels up and ten pixels to the
140−-- right.
177+{-| Move a form by the given amount. This is a relative translation so
178+`(move (10,10) form)` would move `form` ten pixels up and ten pixels to the
179+right.
180+-}
141181move : (number,number) -> Form -> Form
142182move (x,y) f = { f | x <- f.x + x, y <- f.y + y }
143183
144−-- Move a shape in the x direction. This is relative so `(moveX 10 form)` moves
145−-- `form` 10 pixels to the right.
184+{-| Move a shape in the x direction. This is relative so `(moveX 10 form)` moves
185+`form` 10 pixels to the right.
186+-}
146187moveX : number -> Form -> Form
147188moveX x f = { f | x <- f.x + x }
148189
149−-- Move a shape in the y direction. This is relative so `(moveY 10 form)` moves
150−-- `form` upwards by 10 pixels.
190+{-| Move a shape in the y direction. This is relative so `(moveY 10 form)` moves
191+`form` upwards by 10 pixels.
192+-}
151193moveY : number -> Form -> Form
152194moveY y f = { f | y <- f.y + y }
153195
154−-- Set the alpha of a `Form`. The default is 1, and 0 is totally transparent.
196+{-| Set the alpha of a `Form`. The default is 1, and 0 is totally transparent. -}
155197alpha : Float -> Form -> Form
156198alpha a f = { f | alpha <- a }
157199
158−-- A collage is a collection of 2D forms. There are no strict positioning
159−-- relationships between forms, so you are free to do all kinds of 2D graphics.
200+{-| A collage is a collection of 2D forms. There are no strict positioning
201+relationships between forms, so you are free to do all kinds of 2D graphics.
202+-}
160203collage : Int -> Int -> [Form] -> Element
161204collage = Native.Graphics.Collage.collage
162205
163206
164207type Path = [(number,number)]
165208
166−-- Create a path that follows a sequence of points.
209+{-| Create a path that follows a sequence of points. -}
167210path : [(number,number)] -> Path
168211path ps = ps
169212
170−-- Create a path along a given line segment.
213+{-| Create a path along a given line segment. -}
171214segment : (number,number) -> (number,number) -> Path
172215segment p1 p2 = [p1,p2]
173216
174217type Shape = [(number,number)]
175218
176−-- Create an arbitrary polygon by specifying its corners in order.
177−-- `polygon` will automatically close all shapes, so the given list
178−-- of points does not need to start and end with the same position.
219+{-| Create an arbitrary polygon by specifying its corners in order.
220+`polygon` will automatically close all shapes, so the given list
221+of points does not need to start and end with the same position.
222+-}
179223polygon : [(number,number)] -> Shape
180224polygon points = points
181225
182−-- A rectangle with a given width and height.
226+{-| A rectangle with a given width and height. -}
183227rect : number -> number -> Shape
184228rect w h = let hw = w/2
185229 hh = h/2
186230 in [ (0-hw,0-hh), (0-hw,hh), (hw,hh), (hw,0-hh) ]
187231
188−-- A square with a given edge length.
232+{-| A square with a given edge length. -}
189233square : number -> Shape
190234square n = rect n n
191235
192−-- An oval with a given width and height.
236+{-| An oval with a given width and height. -}
193237oval : number -> number -> Shape
194238oval w h =
195239 let n = 50
@@ -199,15 +243,16 @@ oval w h =
199243 f i = (hw * cos (t*i), hh * sin (t*i))
200244 in List.map f [0..n-1]
201245
202−-- A circle with a given radius.
246+{-| A circle with a given radius. -}
203247circle : number -> Shape
204248circle r = oval (2*r) (2*r)
205249
206−-- A regular polygon with N sides. The first argument specifies the number
207−-- of sides and the second is the radius. So to create a pentagon with radius
208−-- 30 you would say:
209−--
210−-- ngon 5 30
250+{-| A regular polygon with N sides. The first argument specifies the number
251+of sides and the second is the radius. So to create a pentagon with radius
252+30 you would say:
253+
254+ ngon 5 30
255+-}
211256ngon : Int -> number -> Shape
212257ngon n r =
213258 let m = toFloat n