libraries/Graphics/Element.elm · elk

git.iko.soy/elk

on 63243ca help sign in

elk/libraries/Graphics/Element.elm

312 lines 9.9 kB history raw

1module Graphics.Element where

2{-| Graphical elements that snap together to build complex widgets and layouts.

3Each Element is a rectangle with a known width and height, making them easy to

4combine and position.

6# Images

7@docs image, fittedImage, croppedImage, tiledImage

9# Styling

10@docs width, height, size, color, opacity, link, tag

12# Inspection

13@docs widthOf, heightOf, sizeOf

15# Layout

16@docs flow, up, down, left, right, inward, outward

18## Layout Aliases

19There are also some convenience functions for working

20with `flow` in specific cases:

22@docs layers, above, below, beside

24# Positioning

25@docs empty, spacer, container

27## Specific Positions

29To create a `Position` you can use any of the built-in positions

30which cover nine common positions.

31@docs middle, midTop, midBottom, midLeft, midRight, topLeft, topRight,

32 bottomLeft, bottomRight

34If you need more precision, you can create custom positions.

36@docs absolute, relative, middleAt, midTopAt, midBottomAt, midLeftAt,

37 midRightAt, topLeftAt, topRightAt, bottomLeftAt, bottomRightAt

38-}

40import open Basics

41import Native.Utils

42import JavaScript as JS

43import JavaScript (JSString)

44import List as List

45import open Color

46import Maybe (Maybe, Just, Nothing)

48type Properties = {

49 id : Int,

50 width : Int,

51 height : Int,

52 opacity : Float,

53 color : Maybe Color,

54 href : JSString,

55 tag : JSString,

56 hover : ()

57 }

59type Element = { props : Properties, element : ElementPrim }

61{-| An Element that takes up no space. Good for things that appear conditionally:

63 flow down [ img1, if showMore then img2 else empty ]

64-}

65empty : Element

66empty = spacer 0 0

68{-| Get the width of an Element -}

69widthOf : Element -> Int

70widthOf e = e.props.width

72{-| Get the height of an Element -}

73heightOf : Element -> Int

74heightOf e = e.props.height

76{-| Get the width and height of an Element -}

77sizeOf : Element -> (Int,Int)

78sizeOf e = (e.props.width, e.props.height)

80{-| Create an `Element` with a given width. -}

81width : Int -> Element -> Element

82width nw e =

83 let p = e.props

84 props = case e.element of

85 Image _ w h _ -> {p| height <- round (toFloat h / toFloat w * toFloat nw) }

86 RawHtml -> {p| height <- snd (Native.Utils.htmlHeight nw e.element) }

87 _ -> p

88 in { element=e.element, props={ props | width <- nw } }

90{-| Create an `Element` with a given height. -}

91height : Int -> Element -> Element

92height nh e =

93 let p = e.props

94 props = case e.element of

95 Image _ w h _ -> {p| width <- round (toFloat w / toFloat h * toFloat nh) }

96 _ -> p

97 in { element=e.element, props={ p | height <- nh} }

99{-| Create an `Element` with a new width and height. -}

100size : Int -> Int -> Element -> Element

101size w h e = height h (width w e)

102

103{-| Create an `Element` with a given opacity. Opacity is a number between 0 and 1

104where 0 means totally clear.

105-}

106opacity : Float -> Element -> Element

107opacity o e = let p = e.props in { element=e.element, props={p| opacity <- o} }

108

109{-| Create an `Element` with a given background color. -}

110color : Color -> Element -> Element

111color c e = let p = e.props in

112 { element = e.element

113 , props = { p | color <- Just c}

114 }

115

116{-| Create an `Element` with a tag. This lets you link directly to it.

117The element `(tag "all-about-badgers" thirdParagraph)` can be reached

118with a link like this: `/facts-about-animals.elm#all-about-badgers`

119-}

120tag : String -> Element -> Element

121tag name e = let p = e.props in

122 { element=e.element, props={p | tag <- JS.fromString name} }

123

124{-| Create an `Element` that is a hyper-link. -}

125link : String -> Element -> Element

126link href e = let p = e.props in

127 { element=e.element, props={p | href <- JS.fromString href} }

128

129emptyStr = JS.fromString ""

130newElement w h e =

131 { props = Properties (Native.Utils.guid ()) w h 1 Nothing emptyStr emptyStr (), element = e }

132

133data ElementPrim

134 = Image ImageStyle Int Int JSString

135 | Container Position Element

136 | Flow Direction [Element]

137 | Spacer

138 | RawHtml

139 | Custom -- for custom Elements implemented in JS, see collage for example

140

141data ImageStyle = Plain | Fitted | Cropped (Int,Int) | Tiled

142

143{-| Create an image given a width, height, and image source. -}

144image : Int -> Int -> String -> Element

145image w h src = newElement w h (Image Plain w h (JS.fromString src))

146

147{-| Create a fitted image given a width, height, and image source.

148This will crop the picture to best fill the given dimensions.

149-}

150fittedImage : Int -> Int -> String -> Element

151fittedImage w h src = newElement w h (Image Fitted w h (JS.fromString src))

152

153{-| Create a cropped image. Take a rectangle out of the picture starting

154at the given top left coordinate. If you have a 140-by-140 image,

155the following will cut a 100-by-100 square out of the middle of it.

156

157 croppedImage (20,20) 100 100 "yogi.jpg"

158-}

159croppedImage : (Int,Int) -> Int -> Int -> String -> Element

160croppedImage pos w h src =

161 newElement w h (Image (Cropped pos) w h (JS.fromString src))

162

163tiledImage : Int -> Int -> String -> Element

164tiledImage w h src =

165 newElement w h (Image Tiled w h (JS.fromString src))

166

167data Three = P | Z | N

168data Pos = Absolute Int | Relative Float

169type Position = { horizontal : Three, vertical : Three, x : Pos, y : Pos }

170

171{-| Put an element in a container. This lets you position the element really

172easily, and there are tons of ways to set the `Position`.

173To center `element` exactly in a 300-by-300 square you would say:

174

175 container 300 300 middle element

176

177By setting the color of the container, you can create borders.

178-}

179container : Int -> Int -> Position -> Element -> Element

180container w h pos e = newElement w h (Container pos e)

181

182{-| Create an empty box. This is useful for getting your spacing right and

183for making borders.

184-}

185spacer : Int -> Int -> Element

186spacer w h = newElement w h Spacer

187

189

190{-| Have a list of elements flow in a particular direction.

191The `Direction` starts from the first element in the list.

192

193 flow right [a,b,c]

194

195 +---+---+---+

196 | a | b | c |

197 +---+---+---+

198-}

199flow : Direction -> [Element] -> Element

200flow dir es =

201 let ws = List.map widthOf es

202 hs = List.map heightOf es

203 newFlow w h = newElement w h (Flow dir es)

204 in

205 if es == [] then empty else

206 case dir of

207 DUp -> newFlow (List.maximum ws) (List.sum hs)

208 DDown -> newFlow (List.maximum ws) (List.sum hs)

209 DLeft -> newFlow (List.sum ws) (List.maximum hs)

210 DRight -> newFlow (List.sum ws) (List.maximum hs)

211 DIn -> newFlow (List.maximum ws) (List.maximum hs)

212 DOut -> newFlow (List.maximum ws) (List.maximum hs)

213

214{-| Stack elements vertically.

215To put `a` above `b` you would say: ``a `above` b``

216-}

217above : Element -> Element -> Element

218above hi lo =

219 newElement (max (widthOf hi) (widthOf lo))

220 (heightOf hi + heightOf lo)

221 (Flow DDown [hi,lo])

222

223{-| Stack elements vertically.

224To put `a` below `b` you would say: ``a `below` b``

225-}

226below : Element -> Element -> Element

227below lo hi =

228 newElement (max (widthOf hi) (widthOf lo))

229 (heightOf hi + heightOf lo)

230 (Flow DDown [hi,lo])

231

232{-| Put elements beside each other horizontally.

233To put `a` beside `b` you would say: ``a `beside` b``

234-}

235beside : Element -> Element -> Element

236beside lft rht =

237 newElement (widthOf lft + widthOf rht)

238 (max (heightOf lft) (heightOf rht))

239 (Flow right [lft,rht])

240

241{-| Layer elements on top of each other, starting from the bottom:

242`layers == flow outward`

243-}

244layers : [Element] -> Element

245layers es =

246 let ws = List.map widthOf es

247 hs = List.map heightOf es

248 in newElement (List.maximum ws) (List.maximum hs) (Flow DOut es)

249

250

251-- Repetitive things --

252

253absolute : Int -> Pos

254absolute = Absolute

255relative : Float -> Pos

256relative = Relative

257

258middle : Position

259middle = { horizontal=Z, vertical=Z, x=Relative 0.5, y=Relative 0.5 }

260topLeft : Position

261topLeft = { horizontal=N, vertical=P, x=Absolute 0, y=Absolute 0 }

262topRight : Position

263topRight = { topLeft | horizontal <- P }

264bottomLeft : Position

265bottomLeft = { topLeft | vertical <- N }

266bottomRight : Position

267bottomRight = { bottomLeft | horizontal <- P }

268midLeft : Position

269midLeft = { middle | horizontal <- N, x <- Absolute 0 }

270midRight : Position

271midRight = { midLeft | horizontal <- P }

272midTop : Position

273midTop = { middle | vertical <- P, y <- Absolute 0 }

274midBottom : Position

275midBottom = { midTop | vertical <- N }

276

277middleAt : Pos -> Pos -> Position

278middleAt x y = { horizontal = Z, vertical = Z, x = x, y = y }

279topLeftAt : Pos -> Pos -> Position

280topLeftAt x y = { horizontal = N, vertical = P, x = x, y = y }

281topRightAt : Pos -> Pos -> Position

282topRightAt x y = { horizontal = P, vertical = P, x = x, y = y }

283bottomLeftAt : Pos -> Pos -> Position

284bottomLeftAt x y = { horizontal = N, vertical = N, x = x, y = y }

285bottomRightAt : Pos -> Pos -> Position

286bottomRightAt x y = { horizontal = P, vertical = N, x = x, y = y }

287midLeftAt : Pos -> Pos -> Position

288midLeftAt x y = { horizontal = N, vertical = Z, x = x, y = y }

289midRightAt : Pos -> Pos -> Position

290midRightAt x y = { horizontal = P, vertical = Z, x = x, y = y }

291midTopAt : Pos -> Pos -> Position

292midTopAt x y = { horizontal = Z, vertical = P, x = x, y = y }

293midBottomAt : Pos -> Pos -> Position

294midBottomAt x y = { horizontal = Z, vertical = N, x = x, y = y }

295

296up : Direction

297up = DUp

298

299down : Direction

300down = DDown

301

302left : Direction

303left = DLeft

304

305right : Direction

306right = DRight

307

308inward : Direction

309inward = DIn

310

311outward : Direction

312outward = DOut