git.iko.soy/elk
on 4e88d39 help sign in
elk/libraries/Text.elm
222 lines 5.8 kB history raw
1module Text where
2{-| A library for styling and displaying text. Whlie the `String` library
3focuses on representing and manipulating strings of character strings, the
4`Text` library focuses on how those strings should look on screen. It lets
5you make text bold or italic, set the typeface, set the text size, etc.
7# Creating Text
8@docs toText
10# Creating Elements
12Each of the following functions places `Text` into a box. The function you use
13determines the alignment of the text.
15@docs leftAligned, rightAligned, centered, justified
17# Links and Style
18@docs link, Style, style, defaultStyle, Line
20# Convenience Functions
22There are two convenience functions for creating an `Element` which can be
23useful when debugging or prototyping:
25@docs plainText, asText
27There are also a bunch of functions to set parts of a `Style` individually:
29@docs typeface, monospace, height, color, bold, italic, line
31-}
33import Basics (..)
34import String
35import Color (Color, black)
36import Graphics.Element (Element, Three, Pos, ElementPrim, Properties)
37import Maybe (Maybe, Nothing)
38import JavaScript (JSString)
39import Native.Show
40import Native.Text
42data Text = Text
44{-| Styles for lines on text. This allows you to add an underline, an overline,
45or a strike out text:
47 line Under (toText "underline")
48 line Over (toText "overline")
49 line Through (toText "strike out")
50-}
51data Line = Under | Over | Through
53{-| Representation of all the ways you can style `Text`. If the `typeface` list
54is empty or the `height` is `Nothing`, the users will fall back on their
55browser's default settings. The following `Style` is black, 16 pixel tall,
56underlined, and Times New Roman (assuming that typeface is available on the
57user's computer):
59 { typeface = [ "Times New Roman", "serif" ]
60 , height = Just 16
61 , color = black
62 , bold = False
63 , italic = False
64 , line = Just Under
65 }
66-}
67type Style =
68 { typeface : [String]
69 , height : Maybe Float
70 , color : Color
71 , bold : Bool
72 , italic : Bool
73 , line : Maybe Line
74 }
76{-| Plain black text. It uses the browsers default typeface and text height.
77No decorations are used:
79 { typeface = []
80 , height = Nothing
81 , color = black
82 , bold = False
83 , italic = False
84 , line = Nothing
85 }
86-}
87defaultStyle : Style
88defaultStyle =
89 { typeface = []
90 , height = Nothing
91 , color = black
92 , bold = False
93 , italic = False
94 , line = Nothing
95 }
97{-| Convert a string into text which can be styled and displayed. To show the
98string `"Hello World!"` on screen in italics, you could say:
100 main = leftAligned (italic (toText "Hello World!"))
101-}
102toText : String -> Text
103toText = Native.Text.toText
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
107it to text like this:
109 style footerStyle (toText "the old prince / 2007")
110-}
111style : Style -> Text -> Text
112style = Native.Text.style
114{-| Provide a list of prefered typefaces for some text.
116 ["helvetica","arial","sans-serif"]
118Not every browser has access to the same typefaces, so rendering will use the
119first typeface in the list that is found on the user's computer. If there are
120no matches, it will use their default typeface. This works the same as the CSS
121font-family property.
122-}
123typeface : [String] -> Text -> Text
124typeface = Native.Text.typeface
126{-| Switch to a monospace typeface. Good for code snippets.
128 monospace (toText "foldl (+) 0 [1,2,3]")
129-}
130monospace : Text -> Text
131monospace = Native.Text.monospace
133{-| Create a link by providing a URL and the text of the link:
135 link "http://elm-lang.org" (toText "Elm Website")
136-}
137link : String -> Text -> Text
138link = Native.Text.link
140{-| Set the height of some text:
142 height 40 (toText "Title")
143-}
144height : Float -> Text -> Text
145height = Native.Text.height
147{-| Set the color of some text:
149 color red (toText "Red")
150-}
151color : Color -> Text -> Text
152color = Native.Text.color
154{-| Make text bold:
156 toText "sometimes you want " ++ bold (toText "emphasis")
157-}
158bold : Text -> Text
159bold = Native.Text.bold
161{-| Make text italic:
163 toText "make it " ++ italic (toText "important")
164-}
165italic : Text -> Text
166italic = Native.Text.italic
168{-| Put lines on text:
170 line Under (toText "underlined")
171 line Over (toText "overlined")
172 line Through (toText "strike out")
173-}
174line : Line -> Text -> Text
175line = Native.Text.line
177{-| `Text` is aligned along the left side of the text block. This is sometimes
178known as *ragged right*.
179-}
180leftAligned : Text -> Element
181leftAligned = Native.Text.leftAligned
183{-| `Text` is aligned along the right side of the text block. This is sometimes
184known as *ragged left*.
185-}
186rightAligned : Text -> Element
187rightAligned = Native.Text.rightAligned
189{-| `Text` is centered in the text block. There is equal spacing on either side
190of a line of text.
191-}
192centered : Text -> Element
193centered = Native.Text.centered
195{-| `Text` is aligned along the left and right sides of the text block. Word
196spacing is adjusted to make this possible.
197-}
198justified : Text -> Element
199justified = Native.Text.justified
201{-| Display a string with no styling:
203 plainText string = leftAligned (toText string)
204-}
205plainText : String -> Element
206plainText str =
207 leftAligned (toText str)
209{-| for internal use only -}
210markdown : Element
211markdown = Native.Text.markdown
213{-| Convert anything to its textual representation and make it displayable in
214the browser:
216 asText value = text (monospace (show value))
218Excellent for debugging.
219-}
220asText : a -> Element
221asText value =
222 leftAligned (monospace (toText (Native.Show.show value)))