204 lines
6.2 KiB
Markdown
204 lines
6.2 KiB
Markdown
[](https://travis-ci.org/devongovett/font-manager)
|
|
|
|
# font-manager
|
|
|
|
A C++ module for Node.js providing access to the system font catalog.
|
|
|
|
## Features
|
|
|
|
* List all available fonts
|
|
* Find fonts with specified characteristics
|
|
* Font substitution when characters are missing
|
|
|
|
## Platforms
|
|
|
|
* Mac OS X 10.5 and later supported via [CoreText](https://developer.apple.com/library/mac/documentation/Carbon/reference/CoreText_Framework_Ref/_index.html)
|
|
* Windows 7 and later supported via [DirectWrite](http://msdn.microsoft.com/en-us/library/windows/desktop/dd368038(v=vs.85).aspx)
|
|
* Linux supported via [fontconfig](http://www.freedesktop.org/software/fontconfig)
|
|
|
|
## Installation
|
|
|
|
Installation of the `font-manager` module is via npm:
|
|
|
|
npm install font-manager
|
|
|
|
On Linux, you also may need to install the `libfontconfig-dev` package, for example:
|
|
|
|
sudo apt-get install libfontconfig-dev
|
|
|
|
## API
|
|
|
|
You load the `font-manager` module using `require` as with all Node modules:
|
|
|
|
```javascript
|
|
var fontManager = require('font-manager');
|
|
```
|
|
|
|
All of the methods exported by `font-manager` have both synchronous and asynchronous versions available.
|
|
You should generally prefer the asynchronous version as it will allow your program to continue doing other
|
|
processing while a request for fonts is processing in the background, which may be expensive depending on
|
|
the platform APIs that are available.
|
|
|
|
* [`getAvailableFonts()`](#getavailablefonts)
|
|
* [`findFonts(fontDescriptor)`](#findfontsfontdescriptor)
|
|
* [`findFont(fontDescriptor)`](#findfontfontdescriptor)
|
|
* [`substituteFont(postscriptName, text)`](#substitutefontpostscriptname-text)
|
|
|
|
### getAvailableFonts()
|
|
|
|
Returns an array of all [font descriptors](#font-descriptor) available on the system.
|
|
|
|
```javascript
|
|
// asynchronous API
|
|
fontManager.getAvailableFonts(function(fonts) { ... });
|
|
|
|
// synchronous API
|
|
var fonts = fontManager.getAvailableFontsSync();
|
|
|
|
// output
|
|
[ { path: '/Library/Fonts/Arial.ttf',
|
|
postscriptName: 'ArialMT',
|
|
family: 'Arial',
|
|
style: 'Regular',
|
|
weight: 400,
|
|
width: 5,
|
|
italic: false,
|
|
monospace: false },
|
|
... ]
|
|
```
|
|
|
|
### findFonts(fontDescriptor)
|
|
|
|
Returns an array of [font descriptors](#font-descriptor) matching a query
|
|
[font descriptor](#font-descriptor).
|
|
The returned array may be empty if no fonts match the font descriptor.
|
|
|
|
```javascript
|
|
// asynchronous API
|
|
fontManager.findFonts({ family: 'Arial' }, function(fonts) { ... });
|
|
|
|
// synchronous API
|
|
var fonts = fontManager.findFontsSync({ family: 'Arial' });
|
|
|
|
// output
|
|
[ { path: '/Library/Fonts/Arial.ttf',
|
|
postscriptName: 'ArialMT',
|
|
family: 'Arial',
|
|
style: 'Regular',
|
|
weight: 400,
|
|
width: 5,
|
|
italic: false,
|
|
monospace: false },
|
|
{ path: '/Library/Fonts/Arial Bold.ttf',
|
|
postscriptName: 'Arial-BoldMT',
|
|
family: 'Arial',
|
|
style: 'Bold',
|
|
weight: 700,
|
|
width: 5,
|
|
italic: false,
|
|
monospace: false } ]
|
|
```
|
|
|
|
### findFont(fontDescriptor)
|
|
|
|
Returns a single [font descriptors](#font-descriptor) matching a query
|
|
[font descriptors](#font-descriptor) as well as possible. This method
|
|
always returns a result (never `null`), so sometimes the output will not
|
|
exactly match the input font descriptor if not all input parameters
|
|
could be met.
|
|
|
|
```javascript
|
|
// asynchronous API
|
|
fontManager.findFont({ family: 'Arial', weight: 700 }, function(font) { ... });
|
|
|
|
// synchronous API
|
|
var font = fontManager.findFontSync({ family: 'Arial', weight: 700 });
|
|
|
|
// output
|
|
{ path: '/Library/Fonts/Arial Bold.ttf',
|
|
postscriptName: 'Arial-BoldMT',
|
|
family: 'Arial',
|
|
style: 'Bold',
|
|
weight: 700,
|
|
width: 5,
|
|
italic: false,
|
|
monospace: false }
|
|
```
|
|
|
|
### substituteFont(postscriptName, text)
|
|
|
|
Substitutes the font with the given `postscriptName` with another font
|
|
that contains the characters in `text`. If a font matching `postscriptName`
|
|
is not found, a font containing the given characters is still returned. If
|
|
a font matching `postscriptName` *is* found, its characteristics (bold, italic, etc.)
|
|
are used to find a suitable replacement. If the font already contains the characters
|
|
in `text`, it is not replaced and the font descriptor for the original font is returned.
|
|
|
|
```javascript
|
|
// asynchronous API
|
|
fontManager.substituteFont('TimesNewRomanPSMT', '汉字', function(font) { ... });
|
|
|
|
// synchronous API
|
|
var font = fontManager.substituteFontSync('TimesNewRomanPSMT', '汉字');
|
|
|
|
// output
|
|
{ path: '/Library/Fonts/Songti.ttc',
|
|
postscriptName: 'STSongti-SC-Regular',
|
|
family: 'Songti SC',
|
|
style: 'Regular',
|
|
weight: 400,
|
|
width: 5,
|
|
italic: false,
|
|
monospace: false }
|
|
```
|
|
|
|
### Font Descriptor
|
|
|
|
Font descriptors are normal JavaScript objects that describe characteristics of
|
|
a font. They are passed to the `findFonts` and `findFont` methods and returned by
|
|
all of the methods. Any combination of the fields documented below can be used to
|
|
find fonts, but all methods return full font descriptors.
|
|
|
|
Name | Type | Description
|
|
---------------- | ------- | -----------
|
|
`path` | string | The path to the font file in the filesystem. **(not applicable for queries, only for results)**
|
|
`postscriptName` | string | The PostScript name of the font (e.g `'Arial-BoldMT'`). This uniquely identities a font in most cases.
|
|
`family` | string | The font family name (e.g `'Arial'`)
|
|
`style` | string | The font style name (e.g. `'Bold'`)
|
|
`weight` | number | The font weight (e.g. `400` for normal weight). Should be a multiple of 100, between 100 and 900. See [below](#weights) for weight documentation.
|
|
`width` | number | The font width (e.g. `5` for normal width). Should be an integer between 1 and 9. See [below](#widths) for width documentation.
|
|
`italic` | boolean | Whether the font is italic or not.
|
|
`monospace` | boolean | Whether the font is monospace or not.
|
|
|
|
#### Weights
|
|
|
|
Value | Name
|
|
----- | -------------------------
|
|
100 | Thin
|
|
200 | Ultra Light
|
|
300 | Light
|
|
400 | Normal
|
|
500 | Medium
|
|
600 | Semi Bold
|
|
700 | Bold
|
|
800 | Ultra Bold
|
|
900 | Heavy
|
|
|
|
#### Widths
|
|
|
|
Value | Name
|
|
----- | -----------------------------
|
|
1 | Ultra Condensed
|
|
2 | Extra Condensed
|
|
3 | Condensed
|
|
4 | Semi Condensed
|
|
5 | Normal
|
|
6 | Semi Expanded
|
|
7 | Expanded
|
|
8 | Extra Expanded
|
|
9 | Ultra Expanded
|
|
|
|
## License
|
|
|
|
MIT
|