Frames & Selection

Generated reference for the iPrintessApi methods tagged #ai-api:frames-selection in printess-editor.d.ts. Custom types referenced below (parameter and return shapes) are documented on the Types reference.

canDeleteSelectedFrames

canDeleteSelectedFrames(): boolean

Tells if parts of the current selection can be deleted

Returns: boolean

canMoveSelectedFrames

canMoveSelectedFrames(): boolean

Tells if the current selection can be moved around by the user

Returns: boolean

canOpenSelectedGroup

canOpenSelectedGroup(): boolean

Returns true if selection has sub-doc (group) to open.

Returns: boolean

clearSelection

clearSelection(): Promise<void>

Clears current printess frames selection and shows document-wide properties like form fields.

Returns: Promise<void>

clearSelectionKeepZoom

clearSelectionKeepZoom(): Promise<void>

Clears current printess frames selection only if active and does not re-center the spread

Returns: Promise<void>

copyFrameShape

copyFrameShape(sourceFrame: string, targetFrames: string, searchBy: "name" | "class"): Promise<string[]>

Copies the shape of one frame to other frames: its outline and its additional paths. Fill, stroke and text wrapping of each target frame stay as they are - a frame without a shape so far gets the outline with no fill and no stroke. The shape scales with each target frame, like it does when a frame is resized. An image frame which gets the shape is masked by it. A sub-document frame which gets the shape stops tracing its own cut contour, because that contour would replace the copy - in the editor as soon as its document is selected, and in the output.

The source frame is found by id, js-name or title. The targets are all frames of the template - on every document and spread - which match targetFrames the way searchBy says: "name" matches the title or the js-name, "class" matches one of the class names (a leading “.” is ignored). The source frame itself is never a target.

All targets change in one undo step. Throws if the source frame is not found or has no shape.

Returns: Promise<string[]> — The ids of the frames which got the shape - empty if no frame matches

currentSpreadHasEditableFrames

currentSpreadHasEditableFrames(): { text: boolean, image: boolean }

Indicates if current spread has editable text or images with properties suitable for the frame bar

Returns: { text: boolean, image: boolean } — Separate flags for editable text and image frames on the current spread.

deleteSelectedFrames

deleteSelectedFrames(): Promise<boolean>

Deletes all selected frames which are allowed to be removed by the buyer

Returns: Promise<boolean>

editSelection

editSelection(): boolean

For a11y, edit selected frame inline, if possible

Returns: boolean

enterExpertMode

enterExpertMode(): void

Enter the buyer Expert-Mode to allow position, remove and rotation for every frame which is not locked

Returns: void

fireSelectionChangeCallback

fireSelectionChangeCallback(forceInLegacyUi?: boolean): Promise<void>

Forces selection change callback against buyer side ui

Returns: Promise<void>

getAllProperties

getAllProperties(): Promise<Array<Array<iExternalProperty>>>

Returns all available properties in the current document

Returns: Promise<Array<Array<iExternalProperty>>>

getAllPropertiesBySpreadId

getAllPropertiesBySpreadId(spreadId: string): Promise<Array<Array<iExternalProperty>>>

Returns a list of all available properties on a specific spread

Returns: Promise<Array<Array<iExternalProperty>>>

getFramePositionByName

getFramePositionByName(frameNameOrTitle: string): {
    left: number,
    top: number,
    width: number,
    height: number,
    anchorX: "left" | "center" | "right",
    anchorY: "top" | "middle" | "bottom",
    rotation: number,
    rotationPositionX: number,
    rotationPositionY: number,
    containerPosition: { left: number, top: number, width: number, height: number }
  } | null

Gets the geometry of a specific frame looked up by name or title. Returns null if no frame is selected

Returns: { left: number, top: number, width: number, height: number, anchorX: “left” | “center” | “right”, anchorY: “top” | “middle” | “bottom”, rotation: number, rotationPositionX: number, rotationPositionY: number, containerPosition: { left: number, top: number, width: number, height: number } } | null

getNumberUi

getNumberUi(property: iExternalProperty, metaProperty?: iExternalMetaPropertyKind | null): {
    meta: iExternalNumberUi;
    value: number;
  } | undefined

Returns the number UI model for any numeric property iExternalNumberUi and value will be returned and has min, max and step info Important: Number models can have different value ranges than the values stored in printess for better user experience uiHelper contains a method to create a slider control from this model

Returns: { meta: iExternalNumberUi; value: number; } | undefined

getSelectionPosition

getSelectionPosition(): {
    left: number,
    top: number,
    width: number,
    height: number,
    anchorX: "left" | "center" | "right",
    anchorY: "top" | "middle" | "bottom",
    rotation: number,
    rotationPositionX: number,
    rotationPositionY: number,
    containerPosition: { left: number, top: number, width: number, height: number }
  } | null

Gets the geometry of the current selected frame or frame-group Returns null if no frame is selected

Returns: { left: number, top: number, width: number, height: number, anchorX: “left” | “center” | “right”, anchorY: “top” | “middle” | “bottom”, rotation: number, rotationPositionX: number, rotationPositionY: number, containerPosition: { left: number, top: number, width: number, height: number } } | null

hasExpertButton

hasExpertButton(): boolean

Returns if UI should show a button to enter Expert-Mode

Returns: boolean

hasSelection

hasSelection(): boolean

Tells if printess has currently selected frames

Returns: boolean

isGroupSelected

isGroupSelected(): boolean

Returns true if a group of frames is selected instead of one plain frame - either a group (sub-doc) frame like a sticker, or several frames at once.

Returns: boolean

isInExpertMode

isInExpertMode(): boolean

Returns if Expert-Mode is active

Returns: boolean

leaveExpertMode

leaveExpertMode(): void

Leave the buyer Expert-Mode (see enterExpertMode())

Returns: void

mirrorSelection

mirrorSelection(axis: "x" | "y"): boolean

For a11y, mirror selected frame vertically or horizontally

Returns: boolean

moveSelectionLayer

moveSelectionLayer(direction: "front" | "back", toEnd?: boolean): boolean

For a11y, move selected frame within layers, if possible. Moves all the way to the front/back if toEnd is true.

Returns: boolean

openSelectedGroup

openSelectedGroup(): Promise<void>

Opens the selected sub doc (group)

Returns: Promise<void>

resizeSelection

resizeSelection(dimension: "height" | "width", mode: "grow" | "shrink"): boolean

For a11y, resize selected frame

Returns: boolean

rotateSelection

rotateSelection(counterClockwise: boolean): boolean

For a11y, rotate selected frame clockwise or counter clockwise

Returns: boolean

selectFirstBuyerBoxOnFocus

selectFirstBuyerBoxOnFocus(): boolean

For a11y, select any possible frame when printess-component receives focus()

Returns: boolean

selectFrames

selectFrames(propertyId: string): Promise<void>

Select frame by propertyId. Fires a subsequent selection changed callback.

Returns: Promise<void>

selectFramesByClass

selectFramesByClass(className: string): Promise<void>

Select frames by class name. Fires a subsequent selection changed callback.

Returns: Promise<void>

selectFramesByExchangeId

selectFramesByExchangeId(exchangeId: string): Promise<void>

Selects every frame on the current spread that carries this exchange-id - the id used to hand content from one layout snippet to the next. The id may sit on the frame as Exchange Image, Exchange Text or Exchange Story, so an image frame and a text frame sharing an id are both selected. An empty id selects nothing. Fires a subsequent selection changed callback.

Returns: Promise<void>

selectNextFrame

selectNextFrame(): boolean

For a11y, select next possible frame (on tab key)

Returns: boolean

selectPrevFrame

selectPrevFrame(): boolean

For a11y, select prev possible frame (on shift+tab key)

Returns: boolean

setNumberUiProperty

setNumberUiProperty(property: iExternalProperty, metaProperty: iExternalMetaPropertyKind | null, value: number): Promise<void>

Sets a numric values based on a retrieved number model. Number models can have different value ranges than the values stored in printess If a number value has been retrieved by getNumberUi its mandatory to set it via setNumberUiProperty

Returns: Promise<void>

setProperty

setProperty(propertyId: string, propertyValue: string | number | iStoryContent): Promise<void | (iExternalImageScaleHints & { scale: number })>

Sets the value of any top-level property passed to the external UI

Returns: Promise<void | (iExternalImageScaleHints & { scale: number })>

showExpertModeOnLoad

showExpertModeOnLoad(): boolean

Returns if Expert-Mode should be enabled on template load

Returns: boolean

transformFrame

transformFrame(o: {
    name: string,
    left?: number | string,
    top?: number | string,
    width?: number | string,
    height?: number | string,
    anchorX?: "left" | "center" | "right",
    anchorY?: "top" | "middle" | "bottom",
    rotation?: number,
    rotationPositionX?: number,
    rotationPositionY?: number,
  }): Promise<void>

A single frame with “name” will be positioned depending on the px position values you provide. (Just specify only the values you want to modify)

Values are absolute pixels of the frame’s top-left corner. The frame’s own anchors are read and kept, so a center/right/bottom pinned frame stays pinned and does not move on the axes you omit. Works without selecting the frame — the buyer’s current selection is not touched — and also finds frames on other spreads/documents.

Values can be a number (always pixels) or a Length string: “120px”, “5cm”, “10mm”, “0.5inch”, “12pt”, “50%” or “=”. A unitless string like “100” uses the current document’s unit. Percent values resolve against the parent’s matching axis.

Note: anchorX/anchorY/rotationPositionX/rotationPositionY are currently ignored; the frame keeps its configured anchor.

Returns: Promise<void>

transformSelection

transformSelection(position: {
    left?: number | string,
    top?: number | string,
    width?: number | string,
    height?: number | string,
    anchorX?: "left" | "center" | "right",
    anchorY?: "top" | "middle" | "bottom",
    rotation?: number,
    rotationPositionX?: number,
    rotationPositionY?: number,
  }): Promise<void>

The current selection of frames (one or more) will be positioned depending on the position values you provide. (Just specify only the values you want to modify)

All values are absolute pixels of the frame’s top-left corner, in the same space getSelectionPosition() returns — independent of the frame’s own anchor.

Sample code moves the frame 50px to the right: ``` const pos = api.getSelectionPosition(); pos.left += 50; await api.transformSelection(pos); ``` Values can be a number (always pixels) or a Length string: “120px”, “5cm”, “10mm”, “0.5inch”, “12pt”, “50%” or “=”. A unitless string like “100” uses the current document’s unit. Percent values resolve against the parent’s matching axis.

Note: anchorX/anchorY/rotationPositionX/rotationPositionY are currently ignored — they exist so the result of getSelectionPosition() can be passed in unchanged. The frame keeps its configured anchor.

Returns: Promise<void>