Sample: Adding Pages and Boxes

This sample shows how to add a page to a document and a text box to a page. You can read more about manipulating pages of the document in Spreads, Pages and Layers.

To demonstrate this functionality, we will add two buttons to the tutorial sample (from getting started). One for adding a page, and another one for adding a text box to a page.

The end result sample site is available here.

Adding a Page

When adding a page to a document, we would like to do the following:

1. Create a new spread to contain the page.
2. Create a new page and place it as the only child of the spread.
3. Insert the spread to a document at a certain position. In this example, we will add the new page/spread after the page that is currently in view.
4. Scroll to the new page.

Creating the spread and the page is done with the following code:

var newSpread = new UEditSpread();
newSpread.insertPage(new UEditPage(),0);

Creating the objects is done with a simple new. The new page is placed as the first child of the spread with insertPage.

Getting the current page in view, so we can place the new spread after it is done with:

var currentPageIndex = uEditObject().getActualPageInView();

getActualPageInView returns the index of the page currently in view, where the index is its index in the full page list, whether visible or not. This index is the one to use with the array returned by getPages() method of the document.

Insertion is done with the following code:

uEditObject().getDocument().insertSpread(newSpread,
    theDocument.spreads.indexOf(
        theDocument.getPages()[currentPageIndex].parent)+1);

The new spread is inserted using insertSpread. The index of insertion is the index of the spread of the page which follows this page. This page is indicated by currentPageIndex. Using theDocument.getPages() result with this index will fetch the UEditPage object for this page index. Using its parent member we get to the spread. Using theDocument.spreads.indexOf with this spread we get the spread index, and adding 1 will provide the next spread index, which is where we want to place the new spread.

Finally, scrolling to the new page is done with:

uEditObject().goToActualPage(currentPageIndex+1);

which uses goToActualPage with the new page index (1 after the current). goToActualPage is used as we are using the page index in the actual page list, as opposed to basing our index only on visible pages (in which case we would use goToPage).

You can find the complete code for this addition here

Adding a Text Box

Now let's add a text box. We will add a text box to the current page. After the box is added, we will focus on it, and enter directly into editing it, so you can type right after adding the box.

We will do it following these stages:

1. Create a box object, define its dimensions and position on the page. Set its type to text.
2. Attach the box to the current page.
3. Set its layer to be the top layer, so this will be the top box on the page.
4. Create a text segment that will function as this text box text content. Add it to the document
5. Set up the new box as its frame, which would now make it a text box for this text.
6. Focus on the box, select it, and enter into text edit mode on it.

First, let's create the box. Use this code:

var newBox = new UEditBox();
newBox.width = newBox.height = 200;
newBox.left = newBox.top = 0;
newBox.type = UEditBox.eTypeText;

The box object is created with a new command. Then, the width and height are set to 200, and its position to 0,0, which is the page top left. Its type is set to UEditBox.eTextType, making it a text box. We should still attach it to an actual text stream. The reason a text box does not automatically get a text stream is that text stream is an independent entity. This is because, potentially, a text stream may flow between multiple boxes. As such, it is owned by none but the document. All text streams in the document may be accessed directly through the texts member of the document obejct.

Next, we'll attach the box to the current page:

uEditObject().getDocument().getPages()[uEdit.getActualPageInView()].attachBox(newBox);

We simply grab the current page in view and grab the page object from getPages.
Note that the page does not yet have a layer reference which sets its z-order position. So we need to add a reference. For this we'll take the top layer and set it as the box layer:

newBox.layer = getTopVisibleLayer(theDocument);

getTopVisibleLayer loops the layers of the document from top to bottom looking for the first one that is visible. You can find the code here.

Now, set up a text stream, add it to the document and add the new box as a frame for this text:

var newText = new UEditText();
theDocument.appendText(newText);
newText.appendFrame(newBox);

And, to finish, we'll enter editing mode on the box. Focus on it, select it and enter the edit mode:

uEditObject().focusOnBox(newBox,true);
uEditObject().select(newBox);
uEditObject().getDocumentView().startTextEditModeOnSelection();

focusOnBox makes sure a box is in view. Passing true as the second parameter will avoid also zooming the view so the box fills it.
select with a box parameter selects a box. Pass 'null' to deselect.
getDocumentView().startTextEditModeOnSelection() starts text editing on the current selected box.

Nearly done. Since multiple functions are carried out on the document, this will result in multiple "undo" steps. This will not do, as we would like this action of adding a box to be undone in a single "undo" click. To do this, we need to start an undo transaction at the beginning of our code, and end it when done. We do this by placing the next line before the document changes:

uEditObject().getUndoService().pushUndoTransaction('add text box');

The parameter passed to pushUndoTransaction is the name of the undo step. This is useful if you want to display names for undo steps, like in an undo menu.

After everything is done, pop the undo transaction to finalize this single undo step:

uEditObject().getUndoService().popUndoTransaction();

That's it!

For the full code of adding the box refer to here.