Stacking Order of pageItems in CS5

Question

I have not been able to get the correct stacking order of pageItems within a layer/page (in CS5). This was simple to do in CS4 as something like this (CurrentPageItem = myPage.pageItems[i];) would return pageItems in the actual stacking order in the document.
With CS5 all textframes come together and all rectangles come together, irrespective of them stacked in any order (TextFrame, Rectangle, TextFrame,.... would come out as TextFrame, TextFrame and Rectangle). Some solutions already in the forum point to changing to older version (6.0), but I don't want to do that.
Can there be a way to determine STACKING ORDER within the layer/page in CS5?

Answer 1

Hi Rich,
The fact is that you are right and we are—partially—wrong. More precisely, the answer is incomplete in that it does not account for another issue: PageItems is a meta-collection which, in fact, target specific sub-collections (Rectangles, Ovals, TextFrames, etc.). Browsing within a PageItems collection by indexes may lead to something very tricky when different kind of underlying objects are involved.
Let's study the following layout:
This is a single-page document having three simple top-level items: a Rectangle, a TextFrame, and an Oval.
Considering the myDoc.PageItems collection, I don't know exactly how the internal indices are managed in that collection, but as it has been said a PageItem.index property returns a z-order, we can check this:
var doc = app.activeDocument;
var pgItems = doc.pageItems; // a PageItems collection
alert( pgItems.everyItem().index );
// => 0,2,1  (depending on the z-order)
// These are indices within the spread.PageItems collection
The resulting order, [0,2,1], indicates that:
pgItems[0] has the z-level 0 (front),
pgItems[1] has the z-level 2 (back)
pgItems[2] has the z-level 1 (middle)
From that we can infer that pgItems[0] refers to the Oval, pgItems[1] refers to the Rectangle, and pgItems[2] refers to the TextFrame.
But, what is really misleading is the following test:
alert([
    pgItems[0].index,
    pgItems[1].index,
    pgItems[2].index
// => 0,0,0 !!
As you can see, pgItems[ i ].index returns 0 (zero) for each item, whereas we just have seen that pgItems.everyItem().index returns [0,2,1]. How is it possible?
In fact, the weird [0,0,0] result reflects indexes within the respective Rectangles, Ovals, TextFrames collections (each has a single element).
In other words, pgItems[ i ].index is actually resolved as pgItems[ i ].getElements()[0].index. This makes it practically very difficult to keep a relevant connection between the everyItem().index Array and the actual z-order of the page items. I think this is the reason for the issue you mention.
So, how to do? As a general rule, never rely on collection indices to identify an element. The only way to unambiguously and unvariantly refer to an object is to use the id property. If you need to deal with z-orders, backup the information in a id-to-zorder structure. Here is an approach:
var zOrderById = {},
    itemZO = pgItems.everyItem().index,
    itemIds = pgItems.everyItem().id,
    i = pgItems.length;
while( i-- )
    zOrderById[itemIds[i]] = itemZO[i];
Then you can use zOrderById[ pgItems[ i ].id ] to retrieve the z-order of the i-indexed item in the pgItems collection:
alert( zOrderById[ pgItems[0].id ] ); // => 0
alert( zOrderById[ pgItems[1].id ] ); // => 2
alert( zOrderById[ pgItems[2].id ] ); // => 1
Of course, given a page item, myItem, you also can directly use: zOrderById[myItem.id].
@+
Marc