@@ -1,5 +1,8 @@
1−
21module Graphics.Element where
2+{-| Graphical elements that snap together to build complex widgets and layouts.
3+Each Element is a rectangle with a known width and height, making them easy to
4+combine and position.
5+-}
36
47import open Basics
58import Native.Utils
@@ -22,19 +25,19 @@ type Properties = {
2225
2326type Element = { props : Properties, element : ElementPrim }
2427
25−-- Get the width of an Element
28+{-| Get the width of an Element -}
2629widthOf : Element -> Int
2730widthOf e = e.props.width
2831
29−-- Get the height of an Element
32+{-| Get the height of an Element -}
3033heightOf : Element -> Int
3134heightOf e = e.props.height
3235
33−-- Get the width and height of an Element
36+{-| Get the width and height of an Element -}
3437sizeOf : Element -> (Int,Int)
3538sizeOf e = (e.props.width, e.props.height)
3639
37−-- Create an `Element` with a given width.
40+{-| Create an `Element` with a given width. -}
3841width : Int -> Element -> Element
3942width nw e =
4043 let p = e.props
@@ -44,7 +47,7 @@ width nw e =
4447 _ -> p
4548 in { element=e.element, props={ props | width <- nw } }
4649
47−-- Create an `Element` with a given height.
50+{-| Create an `Element` with a given height. -}
4851height : Int -> Element -> Element
4952height nh e =
5053 let p = e.props
@@ -53,30 +56,32 @@ height nh e =
5356 _ -> p
5457 in { element=e.element, props={ p | height <- nh} }
5558
56−-- Create an `Element` with a new width and height.
59+{-| Create an `Element` with a new width and height. -}
5760size : Int -> Int -> Element -> Element
5861size w h e = height h (width w e)
5962
60−-- Create an `Element` with a given opacity. Opacity is a number between 0 and 1
61−-- where 0 means totally clear.
63+{-| Create an `Element` with a given opacity. Opacity is a number between 0 and 1
64+where 0 means totally clear.
65+-}
6266opacity : Float -> Element -> Element
6367opacity o e = let p = e.props in { element=e.element, props={p| opacity <- o} }
6468
65−-- Create an `Element` with a given background color.
69+{-| Create an `Element` with a given background color. -}
6670color : Color -> Element -> Element
6771color c e = let p = e.props in
6872 { element = e.element
6973 , props = { p | color <- Just c}
7074 }
7175
72−-- Create an `Element` with a tag. This lets you link directly to it.
73−-- The element `(tag "all-about-badgers" thirdParagraph)` can be reached
74−-- with a link lik this: `/facts-about-animals.elm#all-about-badgers`
76+{-| Create an `Element` with a tag. This lets you link directly to it.
77+The element `(tag "all-about-badgers" thirdParagraph)` can be reached
78+with a link lik this: `/facts-about-animals.elm#all-about-badgers`
79+-}
7580tag : String -> Element -> Element
7681tag name e = let p = e.props in
7782 { element=e.element, props={p | tag <- JS.fromString name} }
7883
79−-- Create an `Element` that is a hyper-link.
84+{-| Create an `Element` that is a hyper-link. -}
8085link : String -> Element -> Element
8186link href e = let p = e.props in
8287 { element=e.element, props={p | href <- JS.fromString href} }
@@ -95,20 +100,22 @@ data ElementPrim
95100
96101data ImageStyle = Plain | Fitted | Cropped (Int,Int) | Tiled
97102
98−-- Create an image given a width, height, and image source.
103+{-| Create an image given a width, height, and image source. -}
99104image : Int -> Int -> String -> Element
100105image w h src = newElement w h (Image Plain w h (JS.fromString src))
101106
102−-- Create a fitted image given a width, height, and image source.
103−-- This will crop the picture to best fill the given dimensions.
107+{-| Create a fitted image given a width, height, and image source.
108+This will crop the picture to best fill the given dimensions.
109+-}
104110fittedImage : Int -> Int -> String -> Element
105111fittedImage w h src = newElement w h (Image Fitted w h (JS.fromString src))
106112
107−-- Create a cropped image. Take a rectangle out of the picture starting
108−-- at the given top left coordinate. If you have a 140-by-140 image,
109−-- the following will cut a 100-by-100 square out of the middle of it.
110−--
111−-- croppedImage (20,20) 100 100 "yogi.jpg"
113+{-| Create a cropped image. Take a rectangle out of the picture starting
114+at the given top left coordinate. If you have a 140-by-140 image,
115+the following will cut a 100-by-100 square out of the middle of it.
116+
117+ croppedImage (20,20) 100 100 "yogi.jpg"
118+-}
112119croppedImage : (Int,Int) -> Int -> Int -> String -> Element
113120croppedImage pos w h src =
114121 newElement w h (Image (Cropped pos) w h (JS.fromString src))
@@ -121,31 +128,34 @@ data Three = P | Z | N
121128data Pos = Absolute Int | Relative Float
122129type Position = { horizontal : Three, vertical : Three, x : Pos, y : Pos }
123130
124−-- Put an element in a container. This lets you position the element really
125−-- easily, and there are tons of ways to set the `Position`.
126−-- To center `element` exactly in a 300-by-300 square you would say:
127−--
128−-- container 300 300 middle element
129−--
130−-- By setting the color of the container, you can create borders.
131+{-| Put an element in a container. This lets you position the element really
132+easily, and there are tons of ways to set the `Position`.
133+To center `element` exactly in a 300-by-300 square you would say:
134+
135+ container 300 300 middle element
136+
137+By setting the color of the container, you can create borders.
138+-}
131139container : Int -> Int -> Position -> Element -> Element
132140container w h pos e = newElement w h (Container pos e)
133141
134−-- Create an empty box. This is useful for getting your spacing right and
135−-- for making borders.
142+{-| Create an empty box. This is useful for getting your spacing right and
143+for making borders.
144+-}
136145spacer : Int -> Int -> Element
137146spacer w h = newElement w h Spacer
138147
139148data Direction = DUp | DDown | DLeft | DRight | DIn | DOut
140149
141−-- Have a list of elements flow in a particular direction.
142−-- The `Direction` starts from the first element in the list.
143−--
144−-- flow right [a,b,c]
145−--
146−-- +---+---+---+
147−-- | a | b | c |
148−-- +---+---+---+
150+{-| Have a list of elements flow in a particular direction.
151+The `Direction` starts from the first element in the list.
152+
153+ flow right [a,b,c]
154+
155+ +---+---+---+
156+ | a | b | c |
157+ +---+---+---+
158+-}
149159flow : Direction -> [Element] -> Element
150160flow dir es =
151161 let ws = List.map widthOf es
@@ -161,33 +171,37 @@ flow dir es =
161171 DIn -> newFlow (List.maximum ws) (List.maximum hs)
162172 DOut -> newFlow (List.maximum ws) (List.maximum hs)
163173
164−-- Stack elements vertically. To put `a` above `b` you would say:
165−--
166−-- a `above` b
174+{-| Stack elements vertically. To put `a` above `b` you would say:
175+
176+ a `above` b
177+-}
167178above : Element -> Element -> Element
168179above hi lo =
169180 newElement (max (widthOf hi) (widthOf lo))
170181 (heightOf hi + heightOf lo)
171182 (Flow DDown [hi,lo])
172183
173−-- Stack elements vertically. To put `a` below `b` you would say:
174−--
175−-- a `below` b
184+{-| Stack elements vertically. To put `a` below `b` you would say:
185+
186+ a `below` b
187+-}
176188below : Element -> Element -> Element
177189below lo hi =
178190 newElement (max (widthOf hi) (widthOf lo))
179191 (heightOf hi + heightOf lo)
180192 (Flow DDown [hi,lo])
181193
182−-- Put elements beside each other horizontally.
194+{-| Put elements beside each other horizontally.
195+-}
183196beside : Element -> Element -> Element
184197beside lft rht =
185198 newElement (widthOf lft + widthOf rht)
186199 (max (heightOf lft) (heightOf rht))
187200 (Flow right [lft,rht])
188201
189−-- Layer elements on top of each other, starting from the bottom.
190−-- `(layers == flow outward)`
202+{-| Layer elements on top of each other, starting from the bottom.
203+`(layers == flow outward)`
204+-}
191205layers : [Element] -> Element
192206layers es =
193207 let ws = List.map widthOf es