alaric-oxp-utilities.js

"use strict";

this.name        = "alaric-oxp-utilities";
this.author      = "Alaric";
this.copyright   = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence     = "CC BY-NC-SA 3.0 AU";




/**
 * Trims a length of text to fit in the avilable width. If the text is truncated,
 * an ellipses (U+2026) will be appended unless <ellipses> is false. If <ellipses>
 * is omitted from the call, it defaults to true.
 *
 * text             - The text to trim
 * emDisplayWidth   - The available width, in Em, to display the text
 * ellipses         - optional (default: true)
 *
 * Returns the new, trimmed, string.
 */
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
    var font = defaultFont;
    var chPadding = String.fromCharCode(31);
    var ellipsesText = "\u2026";
    var emEllipsesText = font.measureString(ellipsesText);
    var emPaddingText = font.measureString(chPadding);

    var chWidth = [0, text.length];
    var emWidth = [font.measureString(text), 0];

    // use default for ellipses if not supplied
    if (ellipses === null || ellipses === undefined) ellipses = true;

    // if the text already fits, just return it.
    if (emWidth[0] <= emDisplayWidth) return text;

    // if the display width is too short for ellipses, disable ellipses
    if (emEllipsesText >= emDisplayWidth) ellipses = false;

    // subtract ellipses with from display width if ellipses is true
    emDisplayWidth -= (ellipses) ? emEllipsesText : 0;

    while (chWidth[0] != chWidth[1])
    {
        // get Em width of text at length midway between chWidth[0] and chWidth[1]
        var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
        var emPivot = font.measureString(text.substring(0, chPivot));

        // update for next split point based on the text being too long or too short
        var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

        chWidth[flagDirection] = chPivot - flagDirection;
        emWidth[flagDirection] = emPivot;
    }

    // At this point, chWidth[0] and emWidth[0] contain the trimmed width in
    // characters and Em respectively. Return the text, appending ellipses if
    // <ellipses> is true. The space for ellipses has already been accounted
    // for.

    return (ellipses)
        ? text.substring(0, chWidth[0]) + ellipsesText
        : text.substring(0, chWidth[0])
        ;
}





/*
 * Builds tabular (columns aligned) text for use in mission screens/MFDs.
 *
 * Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
 * objects with the following properties:
 *
 * Required properties:
 *  text:   The text to display in this column
 *  width:  The width of the column in em. Text will be truncated if too long.
 *
 * Optional properties:
 *  alignment:  LEFT, RIGHT or CENTER. Default: LEFT
 *  elipses:    Display elipses for truncated text? Default: true.
 *
 * Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
 *
 */
this._buildTabularText = function(rows)
{
    var padCharacter = String.fromCharCode(31);
    var padWidth = defaultFont.measureString(padCharacter);
    var tabularText = "";
    var row;

    for (row = 0; row < rows.length; ++row)
    {
        if (row > 0) tabularText += "\n";

        var i;

        var currentEm0 = 0;
        var currentEm1 = 0;
        var columns = rows[row];
        var rowText = "";

        for (i = 0; i < columns.length; ++i)
        {

            currentEm0 = defaultFont.measureString(rowText);
            var leading = (currentEm1 - currentEm0);
            currentEm1 = currentEm1 + columns[i].width;

            var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
            var width = defaultFont.measureString(text);


            var padding = (currentEm1 - currentEm0) - width;

            switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
            {

                case "LEFT" : padding = 0; break;
                case "RIGHT" : leading = 0; break;
                case "CENTER" : padding = padding / 2; break;

                default:
                    log(this.name, "invalid alignment '" + columns[i].alignment + "'");
                    padding = 0; break;

            }

            padding = Math.floor((leading + padding) / padWidth);

            rowText += (padding >= 1)
                ? new Array(padding).join(padCharacter) + text
                : text
                ;
        }

        tabularText += rowText;
    }

    return tabularText;
}