git.iko.soy/elk
on ab17521 help sign in
elk/libraries/Text.elm
221 lines 5.7 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 Native.Show
39import Native.Text
41data Text = Text
43{-| Styles for lines on text. This allows you to add an underline, an overline,
44or a strike out text:
46 line Under (toText "underline")
47 line Over (toText "overline")
48 line Through (toText "strike out")
49-}
50data Line = Under | Over | Through
52{-| Representation of all the ways you can style `Text`. If the `typeface` list
53is empty or the `height` is `Nothing`, the users will fall back on their
54browser's default settings. The following `Style` is black, 16 pixel tall,
55underlined, and Times New Roman (assuming that typeface is available on the
56user's computer):
58 { typeface = [ "Times New Roman", "serif" ]
59 , height = Just 16
60 , color = black
61 , bold = False
62 , italic = False
63 , line = Just Under
64 }
65-}
66type Style =
67 { typeface : [String]
68 , height : Maybe Float
69 , color : Color
70 , bold : Bool
71 , italic : Bool
72 , line : Maybe Line
73 }
75{-| Plain black text. It uses the browsers default typeface and text height.
76No decorations are used:
78 { typeface = []
79 , height = Nothing
80 , color = black
81 , bold = False
82 , italic = False
83 , line = Nothing
84 }
85-}
86defaultStyle : Style
87defaultStyle =
88 { typeface = []
89 , height = Nothing
90 , color = black
91 , bold = False
92 , italic = False
93 , line = Nothing
94 }
96{-| Convert a string into text which can be styled and displayed. To show the
97string `"Hello World!"` on screen in italics, you could say:
99 main = leftAligned (italic (toText "Hello World!"))
100-}
101toText : String -> Text
102toText = Native.Text.toText
104{-| Set the style of some text. For example, if you design a `Style` called
105`footerStyle` that is specifically for the bottom of your page, you could apply
106it to text like this:
108 style footerStyle (toText "the old prince / 2007")
109-}
110style : Style -> Text -> Text
111style = Native.Text.style
113{-| Provide a list of prefered typefaces for some text.
115 ["helvetica","arial","sans-serif"]
117Not every browser has access to the same typefaces, so rendering will use the
118first typeface in the list that is found on the user's computer. If there are
119no matches, it will use their default typeface. This works the same as the CSS
120font-family property.
121-}
122typeface : [String] -> Text -> Text
123typeface = Native.Text.typeface
125{-| Switch to a monospace typeface. Good for code snippets.
127 monospace (toText "foldl (+) 0 [1,2,3]")
128-}
129monospace : Text -> Text
130monospace = Native.Text.monospace
132{-| Create a link by providing a URL and the text of the link:
134 link "http://elm-lang.org" (toText "Elm Website")
135-}
136link : String -> Text -> Text
137link = Native.Text.link
139{-| Set the height of some text:
141 height 40 (toText "Title")
142-}
143height : Float -> Text -> Text
144height = Native.Text.height
146{-| Set the color of some text:
148 color red (toText "Red")
149-}
150color : Color -> Text -> Text
151color = Native.Text.color
153{-| Make text bold:
155 toText "sometimes you want " ++ bold (toText "emphasis")
156-}
157bold : Text -> Text
158bold = Native.Text.bold
160{-| Make text italic:
162 toText "make it " ++ italic (toText "important")
163-}
164italic : Text -> Text
165italic = Native.Text.italic
167{-| Put lines on text:
169 line Under (toText "underlined")
170 line Over (toText "overlined")
171 line Through (toText "strike out")
172-}
173line : Line -> Text -> Text
174line = Native.Text.line
176{-| `Text` is aligned along the left side of the text block. This is sometimes
177known as *ragged right*.
178-}
179leftAligned : Text -> Element
180leftAligned = Native.Text.leftAligned
182{-| `Text` is aligned along the right side of the text block. This is sometimes
183known as *ragged left*.
184-}
185rightAligned : Text -> Element
186rightAligned = Native.Text.rightAligned
188{-| `Text` is centered in the text block. There is equal spacing on either side
189of a line of text.
190-}
191centered : Text -> Element
192centered = Native.Text.centered
194{-| `Text` is aligned along the left and right sides of the text block. Word
195spacing is adjusted to make this possible.
196-}
197justified : Text -> Element
198justified = Native.Text.justified
200{-| Display a string with no styling:
202 plainText string = leftAligned (toText string)
203-}
204plainText : String -> Element
205plainText str =
206 leftAligned (toText str)
208{-| for internal use only -}
209markdown : Element
210markdown = Native.Text.markdown
212{-| Convert anything to its textual representation and make it displayable in
213the browser:
215 asText value = text (monospace (show value))
217Excellent for debugging.
218-}
219asText : a -> Element
220asText value =
221 leftAligned (monospace (toText (Native.Show.show value)))