Zfont

You can include Zfont directly in your HTML using the jsDelivr CDN. When included this way, the library is globally available on window.Zfont.

<script src="https://cdn.jsdelivr.net/npm/zfont/dist/zfont.min.js"></script>

After importing or downloading both Zdog and Zfont, you must initialize the Zfont plugin by passing the Zdog object to Zfont.init(). This makes the Zdog.Font, Zdog.Text, and Zdog.TextGroup classes available.

Zfont.init(Zdog);

You can create multiline text in Zdog.Text or Zdog.TextGroup using two methods:

1. Insert newline characters (\n) into the value string.
2. Pass an array of strings to the value option, where each string represents a new line.

// Using newline characters
new Zdog.Text({
  ... 
  value: 'The quick brown fox\njumps over the\nlazy zdog',
});

// Using an array of strings
new Zdog.Text({
  ... 
  value: [
    'The quick brown fox',
    'jumps over the',
    'lazy zdog'
  ]
});

To use Zfont in your project with a module bundler like Webpack or Rollup, install it via npm and import it using either ES6 or CommonJS syntax.

$ npm install zfont --save

// Using ES6 module syntax
import Zfont from 'zfont';

// Using CommonJS modules
const Zfont = require('zfont');

To render text, follow these steps:

1. Initialize Zfont with Zfont.init(Zdog).
2. Create a Zdog.Font instance providing the .ttf URL via the src option.
3. Create a Zdog.Text object, passing the font instance to the font option and specifying the value and fontSize.
4. Add the text object to your Zdog.Illustration using the addTo option.

// Initialize Zfont
Zfont.init(Zdog);

// Create a Zdog illustration
let illo = new Zdog.Illustration({
  element: '.zdog-canvas'
});

// Set up a font to use
let myFont = new Zdog.Font({
  src: './path/to/font.ttf'
});

// Create a text object
new Zdog.Text({
  addTo: illo,
  font: myFont,
  value: 'Hey, Zdog!',
  fontSize: 64,
  color: '#fff'
});

// Animation loop
function animate() {
  illo.updateRenderGraph();
  requestAnimationFrame(animate);
}
animate();

Methods available on a Zdog.Font instance:

• measureText(text, fontSize): Returns an object { width, height, descender, ascender } for the specified string at the given pixel size.
• getTextPath(text, fontSize, x=0, y=0, z=0, alignX='left', alignY='bottom'): Returns an array of Zdog path commands for the text.
• waitForLoad(): Returns a Promise that resolves when the font has finished loading.

While text objects automatically appear once their fonts are ready, you can use Zdog.waitForFonts() to return a Promise that resolves only when all fonts currently added to the scene have finished loading. This is useful for delaying animations until the scene is visually complete.

Zdog.waitForFonts().then(() => {
  // Once the fonts are done, start the animation loop
  animate();
})

The following options and properties are available for Zdog.TextGroup:

• font (Required): A Zdog.Font instance.
• value: The text string (or array of strings for multiline).
• fontSize: Text size in pixels (default: 64).
• textAlign: Horizontal alignment: 'left', 'center', or 'right' (default: 'left').
• textBaseline: Vertical alignment: 'top', 'middle', or 'bottom' (default: 'bottom').
• color: Text color (default: #333).
• fill: Text fill (default: false).
• stroke: Text stroke (inherits from Zdog.Group).

The following options and properties are available for Zdog.Text:

• font (Required): A Zdog.Font instance.
• value: The text string (or array of strings for multiline).
• fontSize: Text size in pixels (default: 64).
• textAlign: Horizontal alignment: 'left', 'center', or 'right' (default: 'left').
• textBaseline: Vertical alignment: 'top', 'middle', or 'bottom' (default: 'bottom').

A class similar to Zdog.Text, but it acts as a Zdog.Group. Each glyph is rendered as its own individual shape, allowing for advanced character-level control.

new Zdog.TextGroup({
  addTo: illo,
  font: font,
  value: 'Hey, Zdog!',
  textAlign: 'center',
  color: '#5222ee',
  stroke: 2,
})

An object used for rendering text. It inherits from Zdog.Shape and adds text-specific properties.

new Zdog.Text({
  addTo: illo,
  font: font,
  value: 'Hey, Zdog!',
  textAlign: 'center',
  textBaseline: 'middle',
  color: '#5222ee',
  stroke: 1,
})

Represents a font that can be used by Zdog.Text or Zdog.TextGroup. You must provide a .ttf or .otf file via the src option.

let font = new Zdog.Font({
  src: './path/to/font.ttf'
})