Why is PageItem.resize() unit independent? What other methods are?

Hi Uwe and Jarek,

For the sake of precision I should add that the terms 'RULER SPACE' and 'BOUNDS SPACE' are mine—although there is a trace of these idioms in SDK's hpp headers. But it would be more correct to speak of RULER (resp. BOUNDS) SYSTEMS, since they are not actual coordinate spaces in strict InDesign terms.

As for consideringRulerUnits, the best example I can provide so far is in my boxToRulerMatrix() function at Indiscripts :: Drawing Sine Waves in InDesign

Study the following portion of the code, ref being a Page instance:

// ...

   // Ruler origin --> CS_BOARD (trans)
   // ---
  ro = ref.resolve([[0,0], AP_TOP_LEFT], CS_BOARD, true)[0];

   // Ruler (u,v) --> CS_BOARD (scaling)
   // ---
  rs = ref.resolve([[1,1], AP_TOP_LEFT], CS_BOARD, true)[0];


// ...

The variables ro and rs are computed via the RULER SPACE syntax based on the scheme [ [X,Y], pgAtLocation ], where pgAtLocation is the top left anchor point of the page bounding box seen in its inner space (in short, the actual top-left corner of the page). Contrary to what one might think at first glance, the unique purpose of this argument is to specify a page, that is, the page which contains the anchor point in question, that is, the page ref itself! (The top left corner of a page always belongs to that page, right?) This seems incredibly odd to make such a detour, provided that ref is precisely the client object of the resolve method we are invoking. But the RULER SPACE syntax requires that we provide a page!

Note that I could have used the form [ [X,Y], pgIndex ] as well, since the pgIndex is 0 (zero) in the particular context of my routine—ref being the 1st page of the target spread. But the code I use is more generic in that it doesn't assume that ref index is known. In summary, the pattern:

myPage.resolve( [ [X,Y], AnchorPoint.TOP_LEFT_ANCHOR ], coordSpace, true)[0]

allows to resolve the [X,Y] coordinates relative to myPage itself and with respect to the current units and zero point, into any coordSpace. This is the best way I can see to safely extract this information. Furthermore, that pattern still works in RulerPerSpread or RulerOnSpine modes, because as long as a page is specified consideringRulerUnits is taken into account by the location resolver

Now, what about these [0,0] and [1,1] coordinate pairs in ro and rs? This is the best part:

• Since we are using the RULER SPACE syntax, [0,0] indicates the zero point location (the ruler origin). Hence, ro resolves that location, in points, into the destination space (i.e. the pasteboard coordinate space, in my example).

• For the same reason [1,1] indicates the location [1 hu,1 vu] in the ruler system, where hu (resp. vu) refers to the current horizontal (resp. vertical) unit(s). So rs resolves that location, in points, into the destination space.

Finally, ro and rs allow to compute both a translation and a scaling vector that will contribute in revert-mapping coordinates from the bounding box system into the current ruler system. (The whole routine performs additional matrix calculations through the inner coordinate space, but this stuff is not related to the RULER SPACE syntax.)

The boxToRulerMatrix() function provides a bridge between intuitive bbox coordinates (0..1 ranges along x- and y-axes) and the highly non-intuitive and unstable ruler system, which is unfortunately required in PathPoint specifications and other similar DOM commands. The method I suggest is intended to support any transformation state of the target, any ruler or zero point customization, any unusual context. I don't think I'd have reached my goal by other means…

@+

Marc