git.iko.soy/elk
on master help sign in
Add more documentation
1bec0caEvan Czaplicki
libraries/Text.elm+86−13
compare with master
unifiedsplit
@@ -1,15 +1,21 @@
1module Text where
1module Text where
2−
3−{-| Functions for displaying text
2+{-| A library for styling and displaying text. Whlie the `String` library
3+focuses on representing and manipulating strings of character strings, the
4+`Text` library focuses on how those strings should look on screen. It lets
5+you make text bold or italic, set the typeface, set the text size, etc.
4
6
5# Creating Text
7# Creating Text
6@docs toText
8@docs toText
7
9
8# Creating Elements
10# Creating Elements
11+
12+Each of the following functions places `Text` into a box. The function you use
13+determines the alignment of the text.
14+
9@docs leftAligned, rightAligned, centered, justified
15@docs leftAligned, rightAligned, centered, justified
10
16
11# Links and Style
17# Links and Style
12−@docs link, Style, style, Line, defaultStyle
18+@docs link, Style, style, defaultStyle, Line
13
19
14# Convenience Functions
20# Convenience Functions
15
21
@@ -35,9 +41,28 @@ import Native.Text
35
41
36data Text = Text
42data Text = Text
37
43
44+{-| Styles for lines on text. This allows you to add an underline, an overline,
45+or a strike out text:
46+
47+ line Under (toText "underline")
48+ line Over (toText "overline")
49+ line Through (toText "strike out")
50+-}
38data Line = Under | Over | Through
51data Line = Under | Over | Through
39
52
40−{-| Representation of all the ways you can style `Text`.
53+{-| Representation of all the ways you can style `Text`. If the `typeface` list
54+is empty or the `height` is `Nothing`, the users will fall back on their
55+browser's default settings. The following `Style` is black, 16 pixel tall,
56+underlined, and Times New Roman (assuming that typeface is available on the
57+user's computer):
58+
59+ { typeface = [ "Times New Roman", "serif" ]
60+ , height = Just 16
61+ , color = black
62+ , bold = False
63+ , italic = False
64+ , line = Just Under
65+ }
41-}
66-}
42type Style =
67type Style =
43 { typeface : [String]
68 { typeface : [String]
@@ -69,11 +94,19 @@ defaultStyle =
69 , line = Nothing
94 , line = Nothing
70 }
95 }
71
96
72−{-| Convert a string into text which can be styled and displayed. -}
97+{-| Convert a string into text which can be styled and displayed. To show the
98+string `"Hello World!"` on screen in italics, you could say:
99+
100+ main = leftAligned (italic (toText "Hello World!"))
101+-}
73toText : String -> Text
102toText : String -> Text
74toText = Native.Text.toText
103toText = Native.Text.toText
75
104
76−{-| Set the style of some text.
105+{-| Set the style of some text. For example, if you design a `Style` called
106+`footerStyle` that is specifically for the bottom of your page, you could apply
107+it to text like this:
108+
109+ style footerStyle (toText "the old prince / 2007")
77-}
110-}
78style : Style -> Text -> Text
111style : Style -> Text -> Text
79style = Native.Text.style
112style = Native.Text.style
@@ -82,53 +115,93 @@ style = Native.Text.style
82
115
83 ["helvetica","arial","sans-serif"]
116 ["helvetica","arial","sans-serif"]
84
117
85−Not everyone has access to the same typefaces, so rendering will use the first
118+Not every browser has access to the same typefaces, so rendering will use the
86−typeface in the list that is found on the user's computer. If there are no
119+first typeface in the list that is found on the user's computer. If there are
87−matches, it will use their default typeface. Works the same as the CSS
120+no matches, it will use their default typeface. This works the same as the CSS
88font-family property.
121font-family property.
89-}
122-}
90typeface : [String] -> Text -> Text
123typeface : [String] -> Text -> Text
91typeface = Native.Text.typeface
124typeface = Native.Text.typeface
92
125
93−{-| Switch to a monospace typeface. Good for code snippets. -}
126+{-| Switch to a monospace typeface. Good for code snippets.
127+
128+ monospace (toText "foldl (+) 0 [1,2,3]")
129+-}
94monospace : Text -> Text
130monospace : Text -> Text
95monospace = Native.Text.monospace
131monospace = Native.Text.monospace
96
132
97−{-| Create a link.
133+{-| Create a link by providing a URL and the text of the link:
98
134
99 link "http://elm-lang.org" (toText "Elm Website")
135 link "http://elm-lang.org" (toText "Elm Website")
100-}
136-}
101link : String -> Text -> Text
137link : String -> Text -> Text
102link = Native.Text.link
138link = Native.Text.link
103
139
140+{-| Set the height of some text:
141+
142+ height 40 (toText "Title")
143+-}
104height : Float -> Text -> Text
144height : Float -> Text -> Text
105height = Native.Text.height
145height = Native.Text.height
106
146
147+{-| Set the color of some text:
148+
149+ color red (toText "Red")
150+-}
107color : Color -> Text -> Text
151color : Color -> Text -> Text
108color = Native.Text.color
152color = Native.Text.color
109
153
154+{-| Make text bold:
155+
156+ toText "sometimes you want " ++ bold (toText "emphasis")
157+-}
110bold : Text -> Text
158bold : Text -> Text
111bold = Native.Text.bold
159bold = Native.Text.bold
112
160
161+{-| Make text italic:
162+
163+ toText "make it " ++ italic (toText "important")
164+-}
113italic : Text -> Text
165italic : Text -> Text
114italic = Native.Text.italic
166italic = Native.Text.italic
115
167
168+{-| Put lines on text:
169+
170+ line Under (toText "underlined")
171+ line Over (toText "overlined")
172+ line Through (toText "strike out")
173+-}
116line : Line -> Text -> Text
174line : Line -> Text -> Text
117line = Native.Text.line
175line = Native.Text.line
118
176
177+{-| `Text` is aligned along the left side of the text block. This is sometimes
178+known as *ragged right*.
179+-}
119leftAligned : Text -> Element
180leftAligned : Text -> Element
120leftAligned = Native.Text.leftAligned
181leftAligned = Native.Text.leftAligned
121
182
183+{-| `Text` is aligned along the right side of the text block. This is sometimes
184+known as *ragged left*.
185+-}
122rightAligned : Text -> Element
186rightAligned : Text -> Element
123rightAligned = Native.Text.rightAligned
187rightAligned = Native.Text.rightAligned
124
188
189+{-| `Text` is centered in the text block. There is equal spacing on either side
190+of a line of text.
191+-}
125centered : Text -> Element
192centered : Text -> Element
126centered = Native.Text.centered
193centered = Native.Text.centered
127
194
195+{-| `Text` is aligned along the left and right sides of the text block. Word
196+spacing is adjusted to make this possible.
197+-}
128justified : Text -> Element
198justified : Text -> Element
129justified = Native.Text.justified
199justified = Native.Text.justified
130
200
131−{-| Display a plain string. -}
201+{-| Display a string with no styling:
202+
203+ plainText string = leftAligned (toText string)
204+-}
132plainText : String -> Element
205plainText : String -> Element
133plainText str =
206plainText str =
134 leftAligned (toText str)
207 leftAligned (toText str)
@@ -140,7 +213,7 @@ markdown = Native.Text.markdown
140{-| Convert anything to its textual representation and make it displayable in
213{-| Convert anything to its textual representation and make it displayable in
141the browser:
214the browser:
142
215
143− asText == text . monospace . show
216+ asText value = text (monospace (show value))
144
217
145Excellent for debugging.
218Excellent for debugging.
146-}
219-}