View Source FontMetrics (font_metrics v0.5.2)

FontMetrics works with pre-generated font metrics to explore and calculate various measurements of text in a given font and size.

For example, if you want to know how wide or tall a string of text will be when it is rendered in a given font at a given size, then this can help you out.

This library is intended to be used with the Scenic framework, but doesn't depend on it, so it is usable elsewhere.

Installation

If available in Hex, the package can be installed by adding font_metrics to your list of dependencies in mix.exs:

def deps do
  [
    {:font_metrics, "~> 0.5"}
  ]
end

Generating Metrics

You will need to use another package to compile the font metrics data from a font.

This can be done with the truetype_metrics package. Look for it on hex...

Summary

Functions

Get the ascent of the font scaled to the pixel height

Get the descent of the font scaled to the pixel height

Return a box that would hold the largest character in the font.

Find the gap between to characters given an {x,y} coordinate

Transform point values into pixels

Returns the coordinates just before the given character number.

Shorten a string to fit a given width

Checks if all the characters can be rendered by the font

Measure the width of a string, scaled to a pixel size

Wraps a string to a given width by adding returns.

Types

@type t() :: %FontMetrics{
  ascent: integer(),
  descent: integer(),
  direction: nil,
  kerning: %{required({integer(), integer()}) => number()},
  line_gap: integer(),
  max_box:
    {x_min :: integer(), y_min :: integer(), x_max :: integer(),
     y_max :: integer()},
  metrics: %{required(integer()) => number()},
  smallest_ppem: integer(),
  source: FontMetrics.Source.t(),
  units_per_em: integer(),
  version: String.t()
}

Functions

Link to this function

ascent(pixels, font_metrics)

View Source
@spec ascent(pixels :: number(), metrics :: t()) :: number()

Get the ascent of the font scaled to the pixel height

returns ascent

Link to this function

descent(pixels, font_metrics)

View Source
@spec descent(pixels :: number(), metrics :: t()) :: number()

Get the descent of the font scaled to the pixel height

returns descent

Link to this function

max_box(pixels, font_metrics)

View Source
@spec max_box(pixels :: number(), metrics :: t()) ::
  {x_min :: number(), y_min :: number(), x_max :: number(), y_max :: number()}

Return a box that would hold the largest character in the font.

The response is scaled to the pixel size.

returns {x_min, y_min, x_max, y_max}

Link to this function

nearest_gap(source, pos, pixels, font_metrics, opts \\ [])

View Source
@spec nearest_gap(
  String.t() | [integer()],
  pos :: {number(), number()},
  pixels :: number(),
  metrics :: t(),
  opts :: Keyword.t()
) ::
  {character_number :: integer(), x_position :: number(),
   line_number :: integer()}

Find the gap between to characters given an {x,y} coordinate

Options

Supported options:

  • :kern (boolean/0) - The default value is false.

  • :wrap - The default value is :word.

  • :line_height

returns {character_number, x_position, line_number}

Link to this function

points_to_pixels(points)

View Source
@spec points_to_pixels(pixels :: number()) :: number()

Transform point values into pixels

returns pixels

Link to this function

position_at(source, n, pixels, font_metric, opts \\ [])

View Source
@spec position_at(
  String.t() | [integer()],
  character_index :: number(),
  pixels :: number(),
  metrics :: t(),
  opts :: Keyword.t()
) :: {x :: number(), line :: integer()}

Returns the coordinates just before the given character number.

Options

Supported options:

  • :kern (boolean/0) - The default value is false.

returns {x_position, line_number}

Link to this function

shorten(source, max_width, pixels, font_metrics, opts \\ [])

View Source
@spec shorten(
  String.t() | [integer()],
  max_width :: number(),
  pixels :: number(),
  metrics :: t(),
  opts :: Keyword.t()
) :: String.t() | [integer()]

Shorten a string to fit a given width

Options

Supported options:

  • :kern (boolean/0) - The default value is false.

  • :terminator (String.t/0) - The default value is "…".

returns string

Link to this function

supported?(codepoint, metrics)

View Source
@spec supported?(
  codepoint :: integer() | [integer()] | binary(),
  metrics :: t()
) :: boolean()

Checks if all the characters can be rendered by the font

returns true or false

Link to this function

validate_number(n, name)

View Source
Link to this function

width(source, pixels, font_metrics, opts \\ [])

View Source
@spec width(
  String.t() | integer() | [integer()],
  pixels :: number(),
  metrics :: t(),
  opts :: Keyword.t()
) :: number()

Measure the width of a string, scaled to a pixel size

Options

Supported options:

  • :kern (boolean/0) - The default value is false.

returns width

Link to this function

wrap(source, max_width, pixels, font_metric, opts \\ [])

View Source
@spec wrap(
  String.t() | [integer()],
  max_width :: number(),
  pixels :: number(),
  metrics :: t(),
  opts :: Keyword.t()
) :: String.t() | [integer()]

Wraps a string to a given width by adding returns.

Options

Supported options:

  • :wrap - The default value is :word.

  • :kern (boolean/0) - The default value is false.

returns the wrapped string