@infigo-official/types-for-megaedit/v1/Document/Pages.d.ts

Type definitions for MegaEdit Scripting

/**
 * This module gives access to all page specific functions.
 * 
 * @module Document / Page Functions
 */

/**
 * The page mode defines the mode of the current page. The following page modes are available:
 * - Single: every page within the document is identified as a single page. Normally all pages have the same size, but via dynamic canvas sizes and non-uniform aspect ratio, every page can have different dimensions.
 * - Spread: spread setups generally work with double pages layed out horziontally. Normally the first and last page have only a single editable side. If you have editable inside cover pages enabled, both pages can be customized.
 */
declare enum PageMode {
    /**
     * This identifies a single page.
     */
    Single = 'Single',
    /**
     * This identifies a double page spread. Both sides of the page are customizable.
     */
    Double = 'Double',
    /**
     * This identifies the first page in a spread setup without editable inside cover pages. The right page can be customized.
     */
    SpreadFirst = 'Right',
    /**
     * This identifies the last page in a spread setup without editable inside cover pages. The left page can be customized.
     */
    SpreadLast = 'Left'
}

/**
 * The info object will point to a specific layout item.
 */
type AppliedLayoutInfo = {
    /**
     * The layout category name
     */
    cat: string;
    /**
     * The layout name
     */
    name: string;
}

/**
 * The background can be set for both sides of the spread. This is always an array with two elements and the page mode determines which element is used/can be set.
 */
type BackgroundPageListing = [ BackgroundItem | null, BackgroundItem | null ];

/**
 * The layout can be set for both sides of the spread. This is always an array with two elements and the page mode determines which element is used/can be set.
 */
type LayoutPageListing = [ AppliedLayoutInfo | null, AppliedLayoutInfo | null ];

/**
 * Page object represents a page entry within the job/document.
 */
type Page = {
    /**
     * The background property holds the background information for the page. This is an array with two entries. If no background is used the value will be null, otherwise a {@link BackgroundItem}.
     * Single pages can only have the first array element set, double pages can have both elements set. Spread start or end pages can have only the respective element set.
     */
    background: BackgroundPageListing;
    /**
     * The display name of the page. This can be controlled by the product setup or via scripting, but if empty, it will be autogenerated to provide a running count based on the page mode: "Page 1", "Page 2" for single pages or "1 + 2", "3 + 4" etc
     */
    displayName: string;
    /**
     * The total number of fields currently on the page.
     */
    fieldCount: number;
    /**
     * The unique id of the page (GUID).
     */
    id: string;
    /**
     * Boolean flag to control if the page is a cover page.
     */
    isCover: boolean;
    /**
     * The layouts used for the current page. This is an array with two entries. If no layout is used the value will be null, otherwise a {@link LayoutItem}.
     * Single pages can only have the first array element set, double pages can have both elements set. Spread start or end pages can have only the respective element set.
     */
    layout: LayoutPageListing;
    /**
     * The mode of the page. Note that the configuration of the product predetermines the page mode.
     */
    mode: PageMode;
    /**
     * The name of the page.
     */
    name: string;
    /**
     * Flag to control if the page can be deleted via the UI. If this is set to true, the end user will not be able to delete the page, despite the product configuration. Deleting via scripting would still be possible no matter the setting. This is essentially controlling only the user interface. Not to be confused with {@link canDelete}, which is controlled by the product configuration and is immutable.
     */
    notDeletable: boolean;
    /**
     * Flag to control if the page can be deleted fundamentaly. That is defined generally by the configuration of the product (e.g. the first or last spread page can not be deleted). Not to be confused with the {@link notDeletable} flag, which is a configurable setting.
     * This flag is immutable.
     */
    canDelete: boolean;
    /**
     * The final size of the page. See also the canvas configuration for further details.
     */
    size: Size;
    /**
     * A list of tags set against the page. Tags can be used to store additional data against a page. This is available for scripting and can be via the product build process.
     */
    tags: string[];
    /**
     * Flag to control if the page is visible. Invisbile pages will not show up in the editor, however will still be available in the output (delete pages to remove them from the output).
     */
    visible: boolean;
}

/**
 * This informational item holds page information about the current job. It is fast to generate and should be used to get an overview of the pages instead of enumerating all pages.
 */
type PageInfo = {
    /**
     * The page count is the number of page objects within the editor. Each page will have a mode depending on the setup (spread vs single pages).
     */
    pageCount: number;
    /**
     * The minimum number of pages based on the product configuration.
     */
    min: number;
    /**
     * The maximum number of pages based on the product configuration.
     */
    max: number;
    /**
     * The actual page count refers to the number of pages within the final output. This is without cover pages and sums up the spread pages correctly too.
     */
    actualPageCount: number;
    /**
     * Flag if the current configuration is using a book layout / spreads.
     */
    bookLayout: boolean;
    /**
     * Flag to control if this configuration is using cover pages.
     */
    hasCover: boolean;
    /**
     * Flag to control if the covers are split in front and back or if a full spread is shown.
     */
    separateCoverPages: boolean;
    /**
     * Flag to control if the inside cover (if any) are editable
     */
    editInsideCover: boolean;
    /**
     * The dimensions of the first page. Note: based on the product configuration, all pages will have the same size, but it could also differ when covers or dynamic canvas sizes are used.
     */
    firstPageDimension: Size;                
}

/**
 * The page position is used to control which sub page to target.
 */
declare enum SubPagePosition {
    /**
     * Any/All sub pages should be targeted.
     */
    Any = 'a',
    /**
     * Only the left page should be targeted.
     */
    Left = 'l',
    /**
     * Only the right page should be targeted.
     */
    Right = 'r'
}

/**
 * The _pages_ interface gives access to manage and maintain the pages within the document.
 * - retrieving pages
 * - manipulating pages (set layout, name, etc)
 * - add, remove and rearrange (change order) of pages
 * - render the page (either getting the render directly or updating the mini preview available in the UI)
 * 
 * Note that this manages MegaEdit page objects, which are, depending on the configuration, full spreads or individual pages.
 */
interface Pages {
    /**
     * Return an array of all pages in the document.
     * @returns An array of all pages in the document.
     */
    All(): Page[];
    /**
     * Return a single page either by it's unique id ({@link Page.id}) or by it's zero-based index.
     * Return null if not found
     * @param idOrIndex If this is a number, we will try to find the page by it's index. If this is a string, we will try to find the page by it's id. 
     * @returns The {@link Page} object if index or id is valid, otherwise null.
     */
    ByIdOrIndex(idOrIndex: number | string): Page | null;
    /**
     * Return pages by their name. If exact is set to true, the name has to match exactly, otherwise it will return pages where the name parameter is within the page name. This will return an array, so it can be any number of matching results.
     * @param name The name of the string to search for.
     * @param callback [Deprecated] Optional callback to be triggered once the search has finished with the results as parameter. Shouldn't be used anymore, please pass _null_ instead.
     * @param exact Boolean flag to control if the name has to match exactly or if it is enough if the name is contained within the page name.
     * @returns An array of the found pages. If no pages are found, the array will be empty.
     */
    ByName(name: string, callback?: null, exact?: boolean): Page[];
    /**
     * Return the current number of pages in the document.
     * @returns The number of pages in the document.
     */
    Count(): number;
    /**
     * Returns an informational object with the page information for the current job. This is fast to generate and should be used to get an overview of the pages instead of enumerating all pages.
     * @returns The page info object.
     */
    Info(): PageInfo;
    /**
     * Helper function to add media items to the current document - similar to the ME Upload UI. The media items are added full page.
     * For multi page media items it can optionally add all pages by also inserting pages. It will also resize the pages to match the media.
     * 
     * It does the following actions:
     * - display a loading overlay during the action
     * - add pages as necessary to match the start index parameter (aka this will add blank pages if necessary)
     * - it will reuse existing pages, but will add enough pages for all the media items to add (for multi page media items) as necessary
     * - clear all pages where we add media items
     * - if dynamic canvas with varying aspect ratios is used, it will resize the pages to match the media item based on the minimum DPI.
     * - position all the media centered to use up all the available space - including bleed
     * - the fields will have the following settings
     * -- FitWithoutCropping: no cropping is enabled on the image field
     * -- DoNotSelect: the field cannot be selected
     * -- NoImageDropTarget: the field will not act as a drop target for drag and drop
     * -- Set the field tag as either ME_DIRECT_MEDIA_USAGE_FIT or ME_DIRECT_MEDIA_USAGE - indicating if the page fits directly the media item or not
     * - Once we have added all media items, it will reinitialize the editor, clear the undo items, update all page previews, usage counters and also save the job
     * - then it will remove the overlay screen. If it could not add all media items (e.g. we reached the max page count), an error message to the end user will be shown
     * 
     * @param index The zero based starting index where to insert the pages into. It will add pages if they do not exist if necessary, otherwise reuse existing pages. All pages will be cleared.
     * @param media The media item to insert. If this is a multi page media item, it will add all pages by also inserting pages based on the flag. If possible, it will resize the pages to match the media.
     * @param includeChildren Flag to control if all children of the media item should be added as well. This is only relevant for multi page media items.
     * @param callback This optional callback is triggered once the process has finished (the overlay has been removed). The parameter will  indicate if all media items could be added or not.
     */
    AddMedia(index: number, media: UserMediaItem, includeChildren: boolean, callback?: (success: boolean) => void): void;
    /**
     * Helper function to change the z-index of the fields on a page in one call. This is helpfull to rearrange the fields on a single page easily instead of adjusting the z-index of each field individually.
     * Notes:
     * - all fields in the list must exist on the page already, fields which do not exist will be simply ignored
     * - this will affect the order of all fields on the page, not just the ones in the list
     * - the fields listed will be at the back of the page in the same order as outlined here
     * - any fields not listed on the page will come afterwards, the order will not be deterministic
     * 
     * That means this should be called ideally only with all fields on that page to get a deterministic result.
     *      
     * @param pageOrIndexOrId The page to rearrange. Identified by zero-based index, page id, page name or page object.
     * @param fieldOrIdList The list of fields, either as field objects or as their ids. The order of this array will determine the order of the result.
     * @param ignoreUndo Flag to control if an undo record should be created.
     * @param ignoreEvent Flag to control if change events should be triggered
     * @returns Returns true if the page has been found and has been rearranged, otherwise false.
     */
    ReArrange(
        pageOrIndexOrId: number | string | Page,
        fieldOrIdList: BaseField[] | string[],
        ignoreUndo: boolean,
        ignoreEvent: boolean
    ): boolean;
    /**
     * Clears content on the given page
     * @param pageOrIndexOrId The page to clear. Identified by zero-based index, page id, page name or page object.
     * @param drawingsOnly Optional flag to clear only drawings - that is only fields of type {@link PathField}. Default is false.
     * @param callback [Deprecated] Optional callback to be triggered once the clear has finished. Shouldn't be used anymore, please pass _null_ instead.
     * @param keepDoNotSelectAndDelete Optional flag to delete all fields except those which are marked as {@link BaseFieldRestrictions.doNotDelete} and {@link BaseFieldRestrictions.doNotSelect}. Default is false. This is very useful to clear a page but keep the original design parts.
     * @returns Returns true if the page has been found and has been cleared, otherwise false.
     */
    Clear(pageOrIndexOrId: number | string | Page, drawingsOnly?: boolean, callback?: null, keepDoNotSelectAndDelete?: boolean): boolean;

    /**
     * Call to update the small page preview within the UI for the page selector. This is because not all changes to the page will trigger an update of the preview - only when triggered via the UI.
     * This can be used to update an individual page - or by passing _null_, all pages will be updated.
     * 
     * @param pageOrIndexOrId The optional page to update. If null, all pages will be updated. Identified by zero-based index, page id, page name or page object.
     * @param callback The callback will be triggered once the update has finished. The parameter will indicate if the preview has been updated or not, which can be false if the page does not exist.
     */
    UpdatePreview(pageOrIndexOrId: number | Page | string | null, callback?: (hasUpdated: boolean) => void): void;
    /**
     * Helper function to generate a render of the given page. This will return a base64 encoded image of the page or _false_ if the render failed.
     * @param pageOrIndexOrId The page to render. Identified by zero-based index, page id, page name or page object.
     * @param size The size of the render identified by the width in pixels. The height will be calculated based on the aspect ratio of the page.
     * @param callback The callback will be triggered once the render is ready. It will pass as the first parameter the base64 encoded image or _false_ if the render failed.
     * @param renderPrintOnly Optional flag to control if only fields marked for print should be rendered or if all fields should be included. By default all fields are included.    
     */
    Render(pageOrIndexOrId: number | string | Page, size: number, callback: (image: string | boolean) => void, renderPrintOnly?: boolean): void;

    /**
     * Set the background to a determined color. This will remove any existing background item. Any MegaEdit color value can be used.
     * 
     * @param pageOrIndexOrId The page to set the background for. Identified by zero-based index, page id, page name or page object.
     * @param color The color to set. Any MegaEdit color value can be used.
     * @param position Optional position, this can be used to target only the left or right page of a spread. Default is {@link SubPagePosition.Any}.
     * @returns True if the background has been set, otherwise false.
     */
    SetBackgroundColor(pageOrIndexOrId: number | string | Page, color: string, position?: SubPagePosition): boolean;
    /**
     * Set the background to a determined background item. This will remove any existing background item.
     * 
     * @param pageOrIndexOrId The page to set the background for. Identified by zero-based index, page id, page name or page object.
     * @param background The background item to set. This can be null to remove the background.
     * @param position Optional position, this can be used to target only the left or right page of a spread. Default is {@link SubPagePosition.Any}.
     * @returns True if the background has been set, otherwise false.
     */
    SetBackground(pageOrIndexOrId: number | string | Page, background: BackgroundItem | null, position?: SubPagePosition): boolean;
    /**
     * Set the name of a page. If the name is empty, it will be autogenerated.
     * 
     * @param pageOrIndexOrId The page to set the name for. Identified by zero-based index, page id, page name or page object.
     * @param name The new page name or an empty string to use the autogenerated name.
     * @returns True if the name has been set, otherwise false.
     */
    SetName(pageOrIndexOrId: number | string | Page, name: string): boolean;
    /**
     * Changes the visibility state of a page. This is only applied to the user interface. The page would be part of the output (delete the page to remove it from there).
     * @param pageOrIndexOrId The page to set the visibility for. Identified by zero-based index, page id, page name or page object.
     * @param visible Flag to control if the page should be visible or not.
     * @returns True if the visibility has been set, otherwise false.
     */
    SetVisible(pageOrIndexOrId: number | string | Page, visible: boolean): boolean;
    /**
     * Set the page tags to the given list. This will replace any existing tags.
     * @param pageOrIndexOrId The page to set the tags for. Identified by zero-based index, page id, page name or page object.
     * @param tags The tag array. Note that each tag should be unique and may not contain the '|' character.
     * @returns True if the tags have been set, otherwise false.
     */
    SetTags(pageOrIndexOrId: number | string | Page, tags: string[]): boolean;
    /**
     * Set the deletable flag for the page. Note that there are two areas which control the delete feature. At first comes the product configuration which defines which pages can never be deleted. 
     * In addition, scripts can flag certain pages which can never be deleted despite the configuration sees them as optional.
     * 
     * @param pageOrIndexOrId The page to set the delete flag for. Identified by zero-based index, page id, page name or page object.
     * @param deletable The deletable flag. If false, the page cannot be deleted via the UI. If true, the system may still prevent deletion based on the product configuration (e.g. spread start/end pages, cover, min page count etc).
     */
    SetDeletable(pageOrIndexOrId: number | string | Page, deletable: boolean): boolean;
    /**
     * Sets a layout to a page. This will adjust the target page contents and copy data from the old layout to the new layout if possible.
     * 
     * @param pageOrIndexOrId The page to set the layout for. Identified by zero-based index, page id, page name or page object.
     * @param layout The new layout to set.
     * @param index The zero based index of the subpage. This is only relevant for double pages. Default is 0 for single pages and full spread layouts as well as for spread pages for the left subpage. 1 is used for the right subpage of a spread page.
     * @param callback The callback gets triggered once the layout has been applied.
     */
    SetLayout(pageOrIndexOrId: number | string | Page, layout: LayoutItem, index?: number, callback?: () => void): void;
    /**
     * This will add a new page to the document. The default tags, name and layout will be applied if set. The page mode is predetermined (single or spread) based on the product configuration.
     * @param callback The callback will be triggered once the function has finished. If successfull, it will pass the new page object as a parameter. Otherwise it will pass null.
     * @param afterPageOrId An optional parameter to define the page (via object or id) after which to insert the new page. Otherwise it will be added at the end.
     * @param ignorePageLimit Flag to control if the page limit should be ignored for the new page (e.g. would allow to go over the maximum count). This can only be used for server side code in the output generation stage.
     */
    Add(callback?: (page: Page | null) => void, afterPageOrId?: string | Page | null, ignorePageLimit?: boolean): void;
    /**
     * Deletes a page from the document. Note that there are two areas which control the delete feature. At first comes the product configuration which defines which pages can never be deleted. In addition, a script can mark a page as not deletable.
     * Only the first constraint will be checked here. The script setting is for UI only.
     * @param pageOrIndexOrId The page to delete. Identified by zero-based index, page id, page name or page object.
     * @returns True if the page has been deleted, otherwise false.
     */
    Delete(pageOrIndexOrId: number | string | Page): boolean;
    /**
     * Changes the order of a page by moving it within the page listing forward or backwards based on the _advance_ parameter. 
     * The advance parameter can be positive or negative and the code ensures that the page will not be moved outside of the page listing (e.g. you can use a large negative number to move the page to the start of the listing).
     * The function will not ensure that the final page order is valid (e.g. in case of cover or spread start/end pages) - that needs to be done by the caller.
     * 
     * @param pageOrIndexOrId The page to move. Identified by zero-based index, page id, page name or page object.
     * @param advance The number of pages to move the page. This can be positive or negative.
     * @returns True if the page has been moved, otherwise false.
     */
    Move(pageOrIndexOrId: number | string | Page, advance: number): boolean; 
}