ExtendScript's UnitValue

Question

So I can't find, for the life of me, a clear breakdown of the components of ExtendScript's UnitValue object. Every source I found had something to do with Adobe, and didn't explain it. I'd really like to have a full reference on it, but if no one can find one, I need at least a few questions answered concerning it.

First, what are its constructors?
        I've seen UnitValue(10,'px') which makes sense, but I've also seen UnitValue(20,20)
Second, how can you convert from one unit to another?
Third, how can you find its value and its unit?
        I think I've seen uv.value but nothing getting the units

Lastly, as my tags indicate, this is for Adobe, of course, since I've never seen or heard of any other program that uses ExtendScript.

Answer 1

UnitValue is documented in the Adobe JavaScript Tools Guide.

In particular, you create an object with v = new UnitValue(number, unit), where unit is a string value like in (inch), mm (millimeter), pt (point), px (pixel), etc.

To convert a UnitValue to an actual number, use the as method, e.g. v.as("cm") to convert v into centimeters.

Answer 2

Well, no one else seemed to know, and I finally figured some of it out, so I guess I'll answer it myself:

<This site> was a little helpful as a documentation, but I think Adobe functions slightly different from it.

UnitValue's main constructor is:

    UnitValue(numericalvalue,unit)

I've also seen an alternative that accepts one string:

    UnitValue("42 in")

For conversion, UnitValue comes with a handy as method which accepts the unit to convert to (as a string), and then returns its measurement in that unit, i.e.:

    UnitValue(5,'ft').as('in') === 60

(Note, according to the reference I found, I believe the as method should return the UnitValue instance after being converted to the unit indicated; Adobe's implementation, however, seems to instead merely return the value - therefore I'm use the type-equality operator above to show Adobe's method) For getting the numerical value and measurement unit, the following two properties exist:

    UnitValue.value  // number: the numerical value
    UnitValue.type  // string: the unit of measurement

This is all I could find by my research. If someone has a better answer, post it, and I may accept it.

Answer 3

What's really interesting to me is the baseValue property which allows us to change the frame of reference for the conversion. For instance:

var startUnit = UnitValue(500, "px");

startUnit.baseValue = UnitValue(1 / 72, "in"); // from what I can tell this is the default baseUnit value
$.writeln(v.as("in")); // returns 6.94444444444444 which is what 500px @ 72 dpi is as expressed in inches

startUnit.baseValue = UnitValue(1 / 300, "in"); // set to 300dpi
$.writeln(v.as("in")); // returns 1.66666666666667 which is what 500px @ 300 dpi is as expressed in inches

I think the default baseValue is always UnitValue(1/72, "in") even if the app.preferences.rulerUnits is set to any other type of measurement but I haven't really looked into it much