Skip to content

Spreads, Pages and Layers

Jump to bottom
maria121206 edited this page Nov 26, 2014 · 11 revisions

Spreads, Pages and Layers are document objects that are used for placing graphics on them. Spreads provide а visual collection of pages that are meant to be placed side by side. Pages, in uEdit, are the actual containers of the graphics. Layers are logical collections of document graphics that can be visible or invisible. When a layer is invisible, all elements included in it become invisible. This allows the user to implement themes or versioning very easily. Layers also group boxes by z-order, where the boxes of a higher layer will always be higher than lower layers.

The following explains about the uEdit object model objects representing spreads, pages and layers. Some discussion of the related application (view) functionality is provided too. The Sample: Adding Pages and Boxes entry is used to demonstrate some of the functionality discussed here.

Spreads and UEditSpread

The UEditSpread type represents the spreads of a uEdit document. A spread has the following main properties:

  1. pages (array of UEditPage) - pages of the spread. In XLIM implementations, there is just one page per spread.
  2. master (UEditMaster) - reference to the master spread. The master spread determines the spread pages width and height, as well as margin dimensions.
  3. madiaValue,mediaADOR (string) - for later printing, setting this up will determine a particular media for this spread to be printed on. mediaValue is the static or current value for this spread media. To set up variable media, use mediaADOR and set it up with the matching ADOR name. If mediaADOR is set up to a valid ADOR name, then mediaValue will have the previewed value for the current record.
  4. visibilityADOR (string), visible (boolean) - Visibility ADOR may be assigned to a spread to make it turn on and off between recipients. When used, visible property will have its current visibility indication.

Manipulating the pages array directly to add/remove/move pages in the spread is not desirable since such changes do not trigger events, and, therefore, may not be responded to by the uEdit application. Instead, use the methods available with UEditSpread:

  1. insertPage(inIndex,inPage) - insert a page to a spread. inIndex marks the position in the array, inPage is the page object to add.
  2. deletePage(inPage) - delete a page from a spread. inPage is the page object to delete
  3. movePageInSpread(inPage,inPageToBeAfter) - change page order in a spread. Normally, this would not be required, as spreads in XLIM are 1 page per spread. However, if ever makes sense, use this method to change the order of pages. inPage is the page to move so that it will be after inPageToBeAfter. Passing null for inPageToBeAfter will place the page at the end of the spread.

You can also move pages between spreads. This is done through the page object (UEditPage) movePage(inPageToBeAfter) method. inPageToBeAfter is the page object that should be after this page, where 'null' means that this page should be at the end of the pages list). If inPageToBeAfter belongs to a different spread than this page, this page would leave its current owner spread and would become a child of that spread.

Spreads in the Document

The spreads of the document are available through the spreads collection of a UEditDocument object. To manipulate this collection, use the following methods:

  1. insertSpread(inSpread,inIndex). Insert a spread to the document spread list. This will assign a default master if one is not already assigned to the spread.
  2. deleteSpread(inSpread). Delete a spread from the document list.
  3. moveSpread(inSpread,inSpreadToBeAfter). Move a spread to be before inSpreadToBeAfter. If null is passed, spread would be placed at the end of the spreads list

UEditSpreadView, UEditDocumentView and Lock Aware Methods

UEditSpreadView is a type used in uEdit application to represent the application appearance and behavior of a UEditSpread. It is mostly not interesting to an API user, other than its lock aware methods. These methods match similar methods on UEditSpread but adhere to locks. For example, if insertPage is called on UEditSpread, it is allowed always and the page is inserted. However, if it is called on UEditSpreadView and there's a LockFlags.kPageCreate active on the document, it will not be carried out.

To get a UEditSpreadView for a UEditSpread object of the document displayed in uEdit, use the findSpreadView method of UEditDocumentView. For example, the following gets the spread view for the first spread:

uEditObject().getDocumentView().findSpreadView(uEditObject().getDocument().spreads[0]);

The following lists the lock aware methods and the locks that affect them:

  1. insertPage(inIndex,inPage,inIgnoreLocks) - LockFlags.kPageCreate
  2. deletePage(inPage,inIgnoreLocks) - LockFlags.kPageDelete
  3. movePageInSpread(inPage,inPageToBeAfter,inIgnoreLocks) - LockFlags.kPageOrder

Note that the signature for all methods is pretty much the same as the matching document methods, other than an addition inIgnoreLocks parameter. This parameter allows you to sometimes ignore the locks when calling this method.

Similar methods exist in UEditDocumentView for manipulating the spreads list:

  1. insertSpread(inSpread,inIndex,inIgnoreLocks) - LockFlags.kPageCreate
  2. deleteSpread(inSpread,inIgnoreLocks) - LockFlags.kPageDelete
  3. moveSpread(inSpread,inSpreadToBeAfter,inIgnoreLocks) - LockFlags.kPageOrder

Pages and UEditPage

Pages function in uEdit as containers of graphics. They appear as white rectangles, and whatever contained boxes they own are displayed on them. The type representing pages in uEdit is UEditPage.

Accessing the pages of the document is possible in either of two ways:

  1. Direct - through the pages array of an owner UEditSpread object.
  2. Indirect - through the getPages method of UEditDocument. This method returns an array which is an accumulation of the pages of the document.

The page dimensions are set indirectly through the master referenced by the spread containing the page. You can get the page dimensions by using its getWidth and getHeight methods, which will grab that info from the referenced master.

The Page Boxes

The most interesting property of uEditPage is boxes, which is an array of the contained boxes, each of type UEditBox. The order of the boxes in the array provides their Z order. You can use the following uEditPage methods to alter the order of boxes:

  1. sendToBack(inBox) - move a box to the bottom of its layer. Note that this does not necessarily mean the back of the page, if there is more than one layer to the document.
  2. bringToFront(inBox) - make this box the top of its layer. Note that this does not necessarily mean the top of the page, if there is more than one layer to the document.
  3. sendBackward(inBox) - replace the order of the input box with the one below it. If the box is already at the bottom of its layer nothing will be done.
  4. sendForward(inBox) - replace the order of the input box with the one on top of it. If the box is already at the top of its layer nothing will be done.

You may also wish to change the order of boxes by changing what layer they belong to. You can do this through modifying the value of a box layer property.

Adding boxes is done with attachBox(inBox). Provide to it an instance of UEditBox object. It is preferred that you set up the box properties (such as dimensions, content etc.) prior to adding it to the page, though this is not necessary. Removing a box from a page is done with detachBox(inBox).

Attaching and detaching boxes to a page through the document model methods is not lock-aware. Using the matching methods of UEditPageView (attachBox(inBox) and detachBox(inBox)) will block these functions if matching locks exist - LockFlags.kBoxCreate for attaching a box, and LockFlags.kBoxDelete for detaching a box. To get a page view for a page, use the uEdit plug-in getPageViewData(inPageIndex) method which accepts a page index and provides the matching UEditPageView object.

UEditDocument Methods Related to Pages

Other than getPages method of UEditDocument that returns a list of the document pages, there are also other methods in UEditDocument that allow simplified access to pages, to allow skipping the UEditSpread hierarchy. They are:

  1. getPageWidth(inPageIndex) - get a page width through its index.
  2. getPageHeight(inPageIndex) - get a page height through its index.
  3. getVisiblePagesCount() - get the number of visible pages. Pages may become invisible if their owner spreads are invisible.
  4. fromActualPageIndexToVisiblePageIndex(inIndex) - move from an index in the page list, to an index of visible pages. For example, if the first page is visible, the 2nd one invisible and 3rd one visible, then calling this method with 2 will return 1. This is because 2 is the index of the 3rd page, however it is the 2nd page if looking just at visible pages.
  5. fromVisiblePageIndexToActualIndex(inIndex) - move from an index of a visible page to an index in the page list.

Pages in uEdit Application

The uEdit jQuery plug-in provides some methods that allow inspecting and manipulating the appearance of the pages in the document opened in uEdit:

  1. goToPage(inPageIndex) - scrolls to a page. Input index is according to visible pages.
  2. goToActualPage(inPageIndex - scrolls to a page. Input index is according to the index of the page in the full document page list, both visible and invisible.
  3. fitToPage() - changes the zoom level of the application so that the current page is centered and completely in view.
  4. fillWithPage() - changes the zoom level of the application so that the current page fills the view.
  5. getPageInView() - gets the index of the page currently in view. Returned value is according to the list of visible pages.
  6. getActualPageInView() - gets the index of the page currently in view. Returned value is according to the full list of document pages.

You can also use an event to track the current page in view using the enterPage event. Note that listening on application event, as opposed to document model events, is done through standard jQuery event methods. This is an example of how to listen to this event:

var uEditObject = $('#uedit-control').data('UEdit');

$(uEditObject).on('enterPage',function(inEvent,inPageVisibleIndex,inTotalVisiblePages)
                            {
                                console.log('displaying page',inPageVisibleIndex,'of',inTotalVisiblePages);
                            });

The code sample writes to the browser console the index of the current page out of total pages. The index and pages count is according to visible pages. This means that if some spreads are invisible, it will exclude them from counting.

Layers and UEditLayer

The layers of a document are stacked one on top of the other. Each box in each page has a layer that it is attached to. The layer relation determines both whether this box is visible or not, per the layer visibility status, and its Z order. All boxes in a given layer are on top of all boxes in lower layers. In the layer the order of boxes is according to their order in the page array.

The object representing a layer in uEdit is UEditLayer. Its main properties are:

  1. name - The name of the layer for the purpose of display in a given layers list.
  2. color - The color of the layer. Determines the color of the frames of the boxes that are on top of it as well as the color of the selection box when a box is selected. The value is of type XLIMColor.
  3. visible - Determines whether the layer is visible or not. This may be statically set, or, when in preview, determined by its ADOR.
  4. adorName - The name of the ADOR that controls this layer visibility status. When not null or empty, and in preview this will provide a value to visible.

To assign a box to a layer, set the box object (UEditBox) layer member to one of the layer objects of the document. Use the same method to move an object between layers.

Layers List Manipulation

The layers list is owned by the document object (UEditDocument), through its layers array member.
You can add new layers by creating a new UEditLayer object and using either appendLayer(inLayer) or insertLayer(inLayer,inIndex) to add them to the page:

var layer = new UEditLayer();
layer.name = 'layer 1';
layer.color = new XLIMColor(UXLIMAttribute.eColor, null, false, XLIMColor.eGreen);
uEditObject().getDocument().insertLayer(layer,0);

The above code creates a new green layer with the name of layer 1, and attaches it to the document currently displayed in uEdit as the lowest layer (0).

Further manipulation of the layers list of a document should not be carried out directly on the layers array. Rather use these methods of UEditDocument:

  1. moveLayer(inLayer,inLayerToBeAfter) - move a layer in the layers list. Provide the layer that is supposed to be after it as the 2nd parameter. Passing null there will place the layer on top.
  2. deleteLayer(inLayer) - delete a layer from the layers list.
Clone this wiki locally