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
Available

CScript

itemlist::selected

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

Create a new text frame.

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:

  • 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.

    Ignored.

  • gutter (float) –

    Column spacing.

    Ignored.

  • vertical (bool) –

    Vertical text?

    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

CScript

frame::create_textframe

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

Create a new empty image frame.

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.

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:

  • 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

CScript

frame::create

comet.frame.createGroup(objects)

Group a selection of document items.

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

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
Available

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.

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?

    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

    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

    Ignored

Returns

The bounding box

Return type

CRect

Raises
Available

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
Available

See also

CFrame.moveTo()

CScript

itemlist::move_to