IconFonts.md

Icon Fonts

Icon fonts in Qooxdoo need some preprocessing, because the layout managers need to know the dimensions of 'images'. In this case, we're extracting this information from the glyph's aspect ratio information encoded in the font.

Additionally we use the information placed in the font (glyph names) to automatically assign the font icon to virtual image names. If you for example include the Ligature Symbols , you can directly use this code

var image = new qx.ui.basic.Image("@Ligature/print");

to show the 'print' symbol.

This mechanism heavily depends on how good the font glyph names are maintained. In some cases (i.e. Font Awesome ), the glyph information is either incomplete or missing. You need to use a custom font map in this case to be able to address all the glyphs by their name/alias.

Defining an icon font

Use the Manifest.json to define the icon font like shown in the example:

{
  ...

  "provides" :
  {
    ...
    "webfonts": [
      {
        "name": "FontAwesome",              // mandatory
        "defaultSize": 40,                  // optional
        "mapping": "project/fontawesome-map.json",   // optional - if you've a map file
        "comparisonString": "\uf26e\uf368", // string to test if font is loaded
        "resources": [
          "project/fontawesome-webfont.ttf",  // mandatory - we need one TTF file for parsing
          "project/fontawesome-webfont.eot",
          "project/fontawesome-webfont.woff2",
          "project/fontawesome-webfont.woff"
        ]
      }
    ]
  }
}

Please note that JSON does not support comments - you'll have to remove them first.

Every map entry in the webfonts array needs to have at least a name and one TTF resources entry. Resources can be local files or HTTP URLs. The name is used to reference the font in the virtual URLs. So if you name it "Jipieh" instead of "FontAwesome", you have to use @Jipieh/<glyphname> instead.

The Qooxdoo-compiler uses fontkit to read the content of the ttf file and will therefore automatically determine all the relevant css properties of the font, like fontFamily, fontWeight, fontStyle and even character names. For some icon fonts the character names are not properly stored or do not match the names users expect to see based on popular css integrations of the font. For these cases you you can provide a json fontmap file.

Creating a map file

As mentioned before, some fonts do not contain proper glyphnames. As a result, we can't generate the mapping for you and you've to provide an own mapping.

The format of the mapping file is just JSON as shown here:

{
  "glyphname": "hex-codepoint",
  ...
}

glpyhname is the name or alias of the character, codepoint is the hexadecimal unicode number for that character in the font.

In case of FontAwesome, for example you could use the following script to generate the maps for the 3 variants of the font from the fa.yml file provided on the fontawesome github repo:

const yaml = require("js-yaml");
const fs = require("fs");

let res = {};
let doc = yaml.safeLoad(fs.readFileSync("fa.yml", "utf8"));
for (let key in doc) {
  doc[key].styles.forEach((style) => {
    if (res[style] == undefined) {
      res[style] = {};
    }
    res[style][key] = doc[key].unicode;
  });
}
for (let key in res) {
  fs.writeFileSync("fa-" + key + "-map.json", JSON.stringify(res[key]));
}

Using the icons

After adding the fonts to the Manifest, they will automatically get loaded and integrated into your Qooxdoo appliaction. It is not necessary to add a separate entry via en entry via qx.Theme.define to load the icon font.

The font icons can now be used in Qooxdoo image widgets like Image or Atom. Just start the image name with a @, followed by the defined font name, a slash and the glyph name:

var atom = new qx.ui.basic.Atom("Look, I'm a font icon", "@FontAwesome/heart");

If you don't have a glyph name (no map file and no definition in the font), you can also use the unicode codepoint (in hex) directly:

var atom = new qx.ui.basic.Atom("Look, I'm a font icon", "@FontAwesome/f004");