Collage.Text

A library for styling and displaying text.

While the String library focuses on representing and manipulating strings of characters, the Text library focuses on how those strings should look on screen. It lets you make text bold or italic, set the typeface, set the text size, etc.

Be aware that this module is intended for small chunks of text on one line. Using a newline character in a text chunk will simply have no effect. Alignment and placement should be done using the Collage or Layout modules.

To add some text to your collages, follow the next steps:

Create some text chunk with fromString.
Style it using the functions in this module.
Make a collage out of it, i.e. render it using Collage.rendered. From this point, you cannot style your text any more. What you can do however is...
Transform the collage using the functions in the Collage module: shift it, rotate it, scale it etc. Or use the placement functions in Collage.Layout.

So the most important thing to remember is that after you have turned your text into a collage, you cannot style it anymore!

Note: Function and type names in this module clash with those from Collage and Collage.Layout. Best way to use is a qualified import like:

import Collage.Text as Text exposing (Text, fromString)

Basics
Creating text
Styling text
Measuring text

Basics

type alias Text =

Text Style

Opaque type representing styled text.

Creating text

fromString : String -> Text

Convert a string into text which can be styled and displayed.

To show the string "Hello World!" on screen in large, dark red, italics, you could say:

fromString "Hello World!"
  |> size large
  |> color Color.darkRed
  |> shape Italic
  |> Collage.rendered

empty : Text

Text with nothing in it.

empty = fromString ""

Styling text

Typeface and color

type Typeface

= Serif

| Sansserif

| Monospace

| Font String

Possible typefaces for text.

Serif, Sansserif, and Monospace correspond to the default browser fonts of the user. Use Font to specify a concrete typeface.

typeface : Typeface -> Text -> Text

Set the typeface of some text.

fromString "Text in my favorite font"
  |> typeface (Font "Lato")

color : Color -> Text -> Text

Set the color of some text.

Use the Color module to specify colors.

fromString "Nice blue text"
  |> color Color.blue

Size

The predefined font sizes below are spaced sqrt (sqrt 2) of each other. which gives a balanced view. This idea is bluntly stolen from LaTeX, which does something quite similar. Off course, you can always specify your own font size explicitly.

size : Int -> Text -> Text

Set the size of some text.

fromString "Big text"
  |> size huge

tiny : Int

11 px

small : Int

13 px

normal : Int

16 px

large : Int

19 px

huge : Int

23 px

enormous : Int

27 px

Shape and weight

type Shape

= Upright

| SmallCaps

| Slanted

| Italic

Possible shapes for a piece of text.

shape : Shape -> Text -> Text

Set the shape of some text.

fromString "Italic text"
  |> shape Italic

type Weight

= Thin

| Light

| Regular

| Medium

| SemiBold

| Bold

| Black

Possible weights for a piece of text.

weight : Weight -> Text -> Text

Set the weight of some text.

fromString "Bold text"
  |> weight Bold

Decorations

type Line

= None

| Under

| Over

| Through

Styles for lines on or over some text.

line : Line -> Text -> Text

Put lines on text.

This allows you to add an underline, an overline, or strike out text:

line None (fromString "normal text")


line Under (fromString "underline")


line Over (fromString "overline")


line Through (fromString "strike out")

Creating styles

type alias Style =

{ typeface : Typeface

, size : Int

, color : Color

, shape : Shape

, weight : Weight

, line : Line

}

Specifies the styling (color, typeface, weight, etc.) of text.

style : Style -> Text -> Text

Give some text a predefined style.

For example, if you design a style called heading that is specifically for heading text, you could apply it to text like this:

heading =
  { typeface = Sansserif
  , size = huge
  , color = Color.darkBlue
  , shape = Upright
  , weight = Bold
  , line = Nothing
  }


fromString "Welcome to Elm Collage!"
  |> style heading

defaultStyle : Style

Plain black text.

It uses the browsers default typeface and text height. No decorations are used.

defaultStyle =
  { typeface = Sansserif
  , size = normal
  , color = Color.black
  , shape = Upright
  , weight = Regular
  , line = None
  }

Measuring text

width : Text -> Float

The width of the text when displayed on the user screen.

Warning! Use this function sporadically. Although it should be quite fast, it calls methods of the canvas object (yes really) on the client which can take some time...

height : Text -> Float

The height of the text when displayed on the user screen.

This is equal to the text size:

fromString "Hello World!"
  |> size 16
  |> height
  == 16

(Now you know why newlines are a bad idea...)

timjs/elm-collage/2.0.2