FontMetrics (font_metrics v0.5.0) View Source

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...

Link to this section 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.

Link to this section Types

Specs

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()
}

Link to this section Functions

Link to this function

ascent(pixels, font_metrics)

View Source

Specs

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

Specs

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

Specs

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

Specs

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 - 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

Specs

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

Specs

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 - The default value is false.

returns {x_position, line_number}

Link to this function

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

View Source

Specs

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 - The default value is false.

  • :terminator - The default value is "…".

returns string

Link to this function

supported?(codepoint, metrics)

View Source

Specs

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

Specs

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 - The default value is false.

returns width

Link to this function

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

View Source

Specs

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 - The default value is false.

returns the wrapped string