c6a9aa3 · elk · git.iko.soy

git.iko.soy/elk

on master help sign in

Convert to new docs format

c6a9aa3Evan Czaplicki13 years ago

libraries/Graphics/Collage.elm+103−58

compare with master

unifiedsplit

@@ -1,6 +1,35 @@

1−

2module Graphics.Collage where

1module Graphics.Collage where

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.

6+# Unstructured Graphics

7+@docs collage

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+

4import open Basics

33import open Basics

5import List

34import List

6import Either (Either, Left, Right)

35import Either (Either, Left, Right)

@@ -25,16 +54,18 @@ data FillStyle

25 | Texture String

54 | Texture String

26 | Grad Gradient

55 | Grad Gradient

28−-- The shape of the ends of a line.

57+{-| The shape of the ends of a line. -}

29data LineCap = Flat | Round | Padded

58data LineCap = Flat | Round | Padded

31−-- The shape of the “joints” of a line, where each line segment

60+{-| 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

61+meets. `Sharp` takes an argument to limit the length of the joint. This

33−-- defaults to 10.

62+defaults to 10.

63+-}

34data LineJoin = Smooth | Sharp Float | Clipped

64data LineJoin = Smooth | Sharp Float | Clipped

36−-- All of the attributes of a line style. This lets you build up a line style

66+{-| 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.

67+however you want. You can also update existing line styles with record updates.

68+-}

38type LineStyle = {

69type LineStyle = {

39 color : Color,

70 color : Color,

40 width : Float,

71 width : Float,

@@ -44,11 +75,12 @@ type LineStyle = {

44 dashOffset : Int

75 dashOffset : Int

45 }

76 }

47−-- The default line style, which is solid black with flat caps and sharp joints.

78+{-| 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

79+You can use record updates to build the line style you

49−-- want. For example, to make a thicker line, you could say:

80+want. For example, to make a thicker line, you could say:

50−--

81+

51−-- { defaultLine | width <- 10 }

82+ { defaultLine | width <- 10 }

83+-}

52defaultLine : LineStyle

84defaultLine : LineStyle

53defaultLine = {

85defaultLine = {

54 color = black,

86 color = black,

@@ -59,15 +91,15 @@ defaultLine = {

59 dashOffset = 0

91 dashOffset = 0

60 }

92 }

62−-- Create a solid line style with a given color.

94+{-| Create a solid line style with a given color. -}

63solid : Color -> LineStyle

95solid : Color -> LineStyle

64solid clr = { defaultLine | color <- clr }

96solid clr = { defaultLine | color <- clr }

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]`. -}

67dashed : Color -> LineStyle

99dashed : Color -> LineStyle

68dashed clr = { defaultLine | color <- clr, dashing <- [8,4] }

100dashed clr = { defaultLine | color <- clr, dashing <- [8,4] }

101

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]`. -}

71dotted : Color -> LineStyle

103dotted : Color -> LineStyle

72dotted clr = { defaultLine | color <- clr, dashing <- [3,3] }

104dotted clr = { defaultLine | color <- clr, dashing <- [3,3] }

105

@@ -83,113 +115,125 @@ form f = { theta=0, scale=1, x=0, y=0, alpha=1, form=f }

115

84fill style shape = form (FShape (Right style) shape)

116fill style shape = form (FShape (Right style) shape)

117

86−-- Create a filled in shape.

118+{-| Create a filled in shape. -}

87filled : Color -> Shape -> Form

119filled : Color -> Shape -> Form

88filled color shape = fill (Solid color) shape

120filled color shape = fill (Solid color) shape

121

90−-- Create a textured shape. The texture is described by some url and is

122+{-| Create a textured shape. The texture is described by some url and is

91−-- tiled to fill the entire shape.

123+tiled to fill the entire shape.

124+-}

92textured : String -> Shape -> Form

125textured : String -> Shape -> Form

93textured src shape = fill (Texture src) shape

126textured src shape = fill (Texture src) shape

127

95−-- Fill a shape with a [gradient](/docs/Color.elm#linear).

128+{-| Fill a shape with a [gradient](/docs/Color.elm#linear). -}

96gradient : Gradient -> Shape -> Form

129gradient : Gradient -> Shape -> Form

97gradient grad shape = fill (Grad grad) shape

130gradient grad shape = fill (Grad grad) shape

131

99−-- Outline a shape with a given line style.

132+{-| Outline a shape with a given line style. -}

100outlined : LineStyle -> Shape -> Form

133outlined : LineStyle -> Shape -> Form

101outlined style shape = form (FShape (Left style) shape)

134outlined style shape = form (FShape (Left style) shape)

102

135

103−-- Trace a path with a given line style.

136+{-| Trace a path with a given line style. -}

104traced : LineStyle -> Path -> Form

137traced : LineStyle -> Path -> Form

105traced style path = form (FPath style path)

138traced style path = form (FPath style path)

106

139

107−-- Create a sprite from a sprite sheet. It cuts out a rectangle

140+{-| Create a sprite from a sprite sheet. It cuts out a rectangle

108−-- at a given position.

141+at a given position.

142+-}

109sprite : Int -> Int -> (Int,Int) -> String -> Form

143sprite : Int -> Int -> (Int,Int) -> String -> Form

110sprite w h pos src = form (FImage w h pos src)

144sprite w h pos src = form (FImage w h pos src)

111

145

112−-- Turn any `Element` into a `Form`. This lets you use text, gifs, and video

146+{-| 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

147+in your collage. This means you can move, rotate, and scale

114−-- an `Element` however you want.

148+an `Element` however you want.

149+-}

115toForm : Element -> Form

150toForm : Element -> Form

116toForm e = form (FElement e)

151toForm e = form (FElement e)

117

152

118−-- Flatten many forms into a single `Form`. This lets you move and rotate them

153+{-| 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.

154+as a single unit, making it possible to build small, modular components.

155+-}

120group : [Form] -> Form

156group : [Form] -> Form

121group fs = form (FGroup identity fs)

157group fs = form (FGroup identity fs)

122

158

123−-- Flatten many forms into a single `Form` and then apply a matrix

159+{-| Flatten many forms into a single `Form` and then apply a matrix

124−-- transformation.

160+transformation.

161+-}

125groupTransform : Transform2D -> [Form] -> Form

162groupTransform : Transform2D -> [Form] -> Form

126groupTransform matrix fs = form (FGroup matrix fs)

163groupTransform matrix fs = form (FGroup matrix fs)

127

164

128−-- Rotate a form by a given angle. Rotate takes standard Elm angles (radians)

165+{-| 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

166+and turns things counterclockwise. So to turn `form` 30° to the left

130−-- you would say, `(rotate (degrees 30) form)`.

167+you would say, `(rotate (degrees 30) form)`.

168+-}

131rotate : number -> Form -> Form

169rotate : number -> Form -> Form

132rotate t f = { f | theta <- f.theta + t }

170rotate t f = { f | theta <- f.theta + t }

133

171

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

135scale : number -> Form -> Form

174scale : number -> Form -> Form

136scale s f = { f | scale <- f.scale * s }

175scale s f = { f | scale <- f.scale * s }

137

176

138−-- Move a form by the given amount. This is a relative translation so

177+{-| 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

178+`(move (10,10) form)` would move `form` ten pixels up and ten pixels to the

140−-- right.

179+right.

180+-}

141move : (number,number) -> Form -> Form

181move : (number,number) -> Form -> Form

142move (x,y) f = { f | x <- f.x + x, y <- f.y + y }

182move (x,y) f = { f | x <- f.x + x, y <- f.y + y }

143

183

144−-- Move a shape in the x direction. This is relative so `(moveX 10 form)` moves

184+{-| Move a shape in the x direction. This is relative so `(moveX 10 form)` moves

145−-- `form` 10 pixels to the right.

185+`form` 10 pixels to the right.

186+-}

146moveX : number -> Form -> Form

187moveX : number -> Form -> Form

147moveX x f = { f | x <- f.x + x }

188moveX x f = { f | x <- f.x + x }

148

189

149−-- Move a shape in the y direction. This is relative so `(moveY 10 form)` moves

190+{-| Move a shape in the y direction. This is relative so `(moveY 10 form)` moves

150−-- `form` upwards by 10 pixels.

191+`form` upwards by 10 pixels.

192+-}

151moveY : number -> Form -> Form

193moveY : number -> Form -> Form

152moveY y f = { f | y <- f.y + y }

194moveY y f = { f | y <- f.y + y }

153

195

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

155alpha : Float -> Form -> Form

197alpha : Float -> Form -> Form

156alpha a f = { f | alpha <- a }

198alpha a f = { f | alpha <- a }

157

199

158−-- A collage is a collection of 2D forms. There are no strict positioning

200+{-| 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.

201+relationships between forms, so you are free to do all kinds of 2D graphics.

202+-}

160collage : Int -> Int -> [Form] -> Element

203collage : Int -> Int -> [Form] -> Element

161collage = Native.Graphics.Collage.collage

204collage = Native.Graphics.Collage.collage

162

205

163

206

164type Path = [(number,number)]

207type Path = [(number,number)]

165

208

166−-- Create a path that follows a sequence of points.

209+{-| Create a path that follows a sequence of points. -}

167path : [(number,number)] -> Path

210path : [(number,number)] -> Path

168path ps = ps

211path ps = ps

169

212

170−-- Create a path along a given line segment.

213+{-| Create a path along a given line segment. -}

171segment : (number,number) -> (number,number) -> Path

214segment : (number,number) -> (number,number) -> Path

172segment p1 p2 = [p1,p2]

215segment p1 p2 = [p1,p2]

173

216

174type Shape = [(number,number)]

217type Shape = [(number,number)]

175

218

176−-- Create an arbitrary polygon by specifying its corners in order.

219+{-| Create an arbitrary polygon by specifying its corners in order.

177−-- `polygon` will automatically close all shapes, so the given list

220+`polygon` will automatically close all shapes, so the given list

178−-- of points does not need to start and end with the same position.

221+of points does not need to start and end with the same position.

222+-}

179polygon : [(number,number)] -> Shape

223polygon : [(number,number)] -> Shape

180polygon points = points

224polygon points = points

181

225

182−-- A rectangle with a given width and height.

226+{-| A rectangle with a given width and height. -}

183rect : number -> number -> Shape

227rect : number -> number -> Shape

184rect w h = let hw = w/2

228rect w h = let hw = w/2

185 hh = h/2

229 hh = h/2

186 in [ (0-hw,0-hh), (0-hw,hh), (hw,hh), (hw,0-hh) ]

230 in [ (0-hw,0-hh), (0-hw,hh), (hw,hh), (hw,0-hh) ]

187

231

188−-- A square with a given edge length.

232+{-| A square with a given edge length. -}

189square : number -> Shape

233square : number -> Shape

190square n = rect n n

234square n = rect n n

191

235

192−-- An oval with a given width and height.

236+{-| An oval with a given width and height. -}

193oval : number -> number -> Shape

237oval : number -> number -> Shape

194oval w h =

238oval w h =

195 let n = 50

239 let n = 50

@@ -199,15 +243,16 @@ oval w h =

199 f i = (hw * cos (t*i), hh * sin (t*i))

243 f i = (hw * cos (t*i), hh * sin (t*i))

200 in List.map f [0..n-1]

244 in List.map f [0..n-1]

201

245

202−-- A circle with a given radius.

246+{-| A circle with a given radius. -}

203circle : number -> Shape

247circle : number -> Shape

204circle r = oval (2*r) (2*r)

248circle r = oval (2*r) (2*r)

205

249

206−-- A regular polygon with N sides. The first argument specifies the number

250+{-| 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

251+of sides and the second is the radius. So to create a pentagon with radius

208−-- 30 you would say:

252+30 you would say:

209−--

253+

210−-- ngon 5 30

254+ ngon 5 30

255+-}

211ngon : Int -> number -> Shape

256ngon : Int -> number -> Shape

212ngon n r =

257ngon n r =

213 let m = toFloat n

258 let m = toFloat n