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>

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

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>