comet.frame

The comet.frame module provides access to document frame processing functionality

Methods

comet.frame.getSelected(children=False, placeHolderIDs=[], layers=[], cometGroupIDs=[])

Get a list of all currently selected frames applying various filters.

Parameters:

• children (bool) – Include subframes aswell?

• placeHolderIDs (list[int]) –

  Restrict the result to frames with these placeholders.

  • Empty list: Impose no restrictions

  • [-1]: Allow all frames which have any placeholder

• layers (list[str | CLayer]) –

  Restrict the result to frames on these layers.

  The list can contain:

  • str

    Layer names

  • CLayer

    Layer (must belong to the same document)

  • Empty list : Do not impose restrictions

• cometGroupIDs (list[int]) –

  Restrict the result to frames of these comet groups.

  • Empty list: Impose no restrictions

  • [-1]: Allow all frames which are part of any comet group

Returns:

The found frames

Return type:

list[CFrame]

Raises:

• TypeError – When parameter types are invalid

• CometError – On internal error

Available:

InDesign® Illustrator®

CScript:

itemlist::selected

comet.frame.createTextFrame(dimensions, document=None, page=0, layer='', columns=1, gutter=-1.0, vertical=False)

Create a new text frame.

InDesign® comet_pdf®

If the script frame (gFrame) is a member of a Comet group and is on the same spread as the newly created frame, the new frame will become a member of this Comet group aswell.

If a column number larger than 0, columns will be automatically set up in the frames with the spacing gutter.

If the spacing is smaller than 0, the default spacing will be used.

Parameters:

• dimensions (tuple[float, float, float, float] | CRect) –

  The coordinates of the new frame relative to the page margins.

  The parameter type can be:

  • tuple [float, float, float, float]

    Values for left, top, right, bottom.

  • CRect

    Rectangle for the dimensions.

• document (None | CDocument) –

  The document to create the frame in

  The parameter type can be:

  • None

    Use the current (script-) document

  • CDocument

    A defined document

• page –

  The target page to create the frame on.

  The parameter type can be:

  • int

    Target page index inside document.

  • str

    Exact page name inside document.

  • CPage

    Target page. Must be inside document.

• layer (str | list[str] | CLayer) –

  The layer to create the frame on.

  The parameter type can be:

  • str

    Name of a top level layer.

    • Empty str:

      Use the default layer.

  • list [str]

    Nested layer path.

    • Empty list:

      Use the default layer.

  • int

    Top level layer index counting from the bottom.

  • CLayer

    Layer. Must be inside document

• columns (int) –

  Column count.

  Illustrator® Ignored.

• gutter (float) –

  Column spacing.

  Illustrator® Ignored.

• vertical (bool) –

  Vertical text?

  Illustrator® Ignored.

Returns:

The newly created frame

Return type:

CFrame

Raises:

• TypeError – When parameter types are invalid

• ValueError –

  • When parameter dimensions has invalid values

  • When parameter page has invalid value

  • When parameter columns has invalid value

  • When parameter gutter has invalid value

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

frame::create_textframe

comet.frame.createImageFrame(dimensions, document=None, page=0, layer='')

Create a new empty image frame.

InDesign® comet_pdf®

If the script frame (gFrame) is a member of a Comet group and is on the same spread as the newly created frame, the new frame will become a member of this Comet group aswell.

Illustrator® Since there are no empty image frames in Illustrator, this behaves like the menu item Object->priint:comet->Insert placeholder image

Parameters:

• dimensions (tuple[float, float, float, float] | CRect) –

  The coordinates of the new frame relative to the page margins.

  The parameter type can be:

  • tuple [float, float, float, float]

    Values for left, top, right, bottom.

  • CRect

    Rectangle for the dimensions.

• document (None | CDocument) –

  The document to create the frame in

  The parameter type can be:

  • None

    Use the current (script-) document

  • CDocument

    A defined document

• page –

  The target page to create the frame on.

  The parameter type can be:

  • int

    Target page index inside document.

  • str

    Exact page name inside document.

  • CPage

    Target page. Must be inside document.

• layer (str | list[str] | CLayer) –

  The layer to create the frame on.

  The parameter type can be:

  • str

    Name of a top level layer.

    • Empty str:

      Use the default layer.

  • list [str]

    Nested layer path.

    • Empty list:

      Use the default layer.

  • int

    Top level layer index counting from the bottom.

  • CLayer

    Layer. Must be inside document

Returns:

The newly created frame

Return type:

CFrame

Raises:

• TypeError – When parameter types are invalid

• ValueError –

  • When parameter dimensions has invalid values

  • When parameter page has invalid value

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

frame::create

comet.frame.createGroup(objects)

Group a selection of document items.

InDesign® comet_pdf® The function can group items only if all items are on the same spread.

If the items are part of a group, they can only be grouped with items of the same parent group.

If an item of the list is locked, all items of the new group will be locked.

Parameters:

objects (list[CPageItem]) – The items to group

Returns:

The newly created group

Return type:

CGroup

Raises:

• TypeError –

  • When parameter types are invalid

  • When parameter objects is empty list

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

frame::group

comet.frame.createCometGroup(frames)

Create a Comet group from a list of frames. Old memberships are overwritten without exceptions.

Parameters:

frames (list[CFrame]) – The frames to group

Returns:

The newly created comet group

Return type:

CCometGroup

Raises:

• TypeError – When parameter types are invalid

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

itemlist::create_cometgroup

comet.frame.getBBox(items, spreadRelative=False, lastPageOrSpread=False, spreadWide=False)

This function is the same as CPageItem.getBBox(), except it operates on a list of CPageItem objects and returns the union of their bounding boxes.

InDesign® comet_pdf® Bounding boxes are only determined page- or spread-wide!

If the item list contains entries of different pages or spreads, only the items of the first/last page or spread are used to determine the bounding box.

Parameters:

• frames (list[CPageItem]) – The items to get the bounding box for

• spreadRelative (bool) –

  Get the coordinates relative to the page or to the spread?

  • True: Spread relative

  • False: Page relative

  Illustrator® Ignored

• lastPageOrSpread (bool) –

  Use items of first or last page/spread in case of multiple pages or spreads?

  • False: First page/spread

  • True: Last page/spread

  Illustrator® Ignored

• spreadWide (bool) –

  If the item list contains items of different pages, should the items of the first/last page be used or the items of the first/last spread?

  • False: Items of same page

  • True: Items of same spread

  Illustrator® Ignored

Returns:

The bounding box

Return type:

CRect

Raises:

• TypeError – When parameter types are invalid

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

See also:

CPageItem.getBBox()

CScript:

itemlist::bbox

comet.frame.moveTo(frames, x, y, page=-1)

This function is the same as CFrame.moveTo(), except it operates on a list of CFrame objects.

Warning

If the list contains frames of different pages, only the frames of the first page are processed. This also applies if the pages belong to the same spread. The background to this is to avoid, as far as possible, that frames of pages fall into the work area.

Warning

When moving frames to a new page, the comet groups of these frames are lost.

Parameters:

• frames (list[CFrame]) – The frames to move. Must all belong to the same document.

• x (float) – The new x coodinate

• y (float) – The new y coordinate

• page (int | CPage) –

  Move frames to another page?

  • -1: Don’t change the page.

  The parameter type can be:

  • int to indicate a page index

  • CPage to indicate a page object

Return type:

None

Raises:

• TypeError – When parameter types are invalid

• ValueError – When page is int and has invalid index.

• CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

See also:

CFrame.moveTo()

CScript:

itemlist::move_to