comet.CFrame

class comet.CFrame
Inherits:

comet.CPageItem

CFrame is a reference to a document page item (e.g. a frame)

CFrame is a reference to a document art object (e.g. a text frame)

Methods

CFrame.isInline()

Is this frame an inline frame?

Returns

Whether this frame is an inline frame

Return type

bool

Raises

CometError – On internal error

Available

CScript

frame::is_inline

CFrame.getSize(boundsKind=0)

Get the size of this frame.

Parameters

boundsKind (int) –

Which bounds to get:

  • 0: Frame with stroke

  • 1: Frame without stroke

Returns

tuple of (width, height)

Return type

tuple[float, float]

Available

CScript

frame::get_size

CFrame.setSize(width=- 1.0, height=- 1.0, boundsKind=0, refPoint=0, offsetX=0.0, offsetY=0.0, executeLayoutRules=False)

Change the size of this frame.

Frames must be greater than 0.0 Points and must not be smaller than the strokes at both sides.

So a frame with a stroke of 10 points must have a size of at least 20 points.

  • If strokes avoid frames resizing, the function tries to reduce the stroke at first.

  • Lines are treated differently by InDesign®: Slanted lines can become orthogonal lines. But orthogonal lines can only change their length. The attempt to turn orthogonal lines into slanted lines is rejected by InDesign® with the error kIllegalDimensionErr (11269)

  • Points are ignored by the function without errors.

Parameters

  • width (float) –

    New frame width

    • -1.0: Leave unchanged

  • height (float) –

    New frame height

    • -1.0: Leave unchanged

  • boundsKind (int) –

    Which bounds to set:

    • 0: Frame with stroke

    • 1: Frame without stroke

    Ignored. The value is always 1

  • refPoint (int) –

    The reference point which is fixed during resize.

    One of Reference Points.

    Default is comet.kRefPointTopLeft.

  • offsetX (float) –

    Horizontal offset from the given reference point

    Ignored.

  • offsetY (float) –

    Vertical offset from the given reference point

    Ignored.

  • executeLayoutRules (bool) –

    Execute layout rules “After geometry changes” while executing the command?

    • TrueYes, execute rules “after geometry” changes.

      This may cause problems and/or side effects like infinite recursion!

    • False : No, suppress rules.

Return type

None

Raises
Available

CScript

frame::resize

CFrame.getRefPoint(refPoint, pageRelative=True)

Get the coordinates of a frame’s reference point

Parameters

  • refPoint (int) –

    The reference point to get the coordinates for.

    One of Reference Points.

  • pageRelative (bool) –

    • True: Get the coordinates as page-relative

    • False: Get the coordinates as spread relative

    • True: Get the coordinates as artboard-relative

    • False: Get the coordinates as global

Returns

Coordinates (x, y)

Return type

tuple[float, float]

Raises
Available

CScript

frame::refpoint

CFrame.getColumnCount()

Get the number of text columns of the frame

Returns

The column count

Return type

int

Raises
Available

CScript

frame::count_columns

CFrame.setColumnCount(count)

Set the column count of the frame

Parameters

count (int) – The new count

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not a text frame

  • ValueError – When parameter count is < 1

  • CometError – On internal error

Return type

None

Available

CScript

frame::create_columns

CFrame.getColumnGutter()

Get the gutter of text columns of the frame

Returns

The column gutter

Return type

float

Raises
Available

CScript

frame::count_columns

CFrame.setColumnGutter(gutter)

Set the column gutter of the frame

Parameters

gutter (float) –

The new gutter value.

  • < 0.0: Reset to default value

Return type

None

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not a text frame

  • CometError – On internal error

Available

CScript

frame::create_columns

CFrame.getZOrder(intersecting=False)

Determine the Z order of this frame. If the frame is a group, this group is treated as one object, for all other groupings the frames are treated as individual objects.

Parameters

intersecting (bool) –

  • False: Determine Z-order within the spread.

  • True: Use only the frames that overlap the specified frame to determine the Z-order.

The frame that is furthest forward has Z-order 1 - but it does not have to be the frontmost frame of the spread.

Likewise, of course, the frame with the largest Z-value does not need to be the bottom frame of the spread.

Ignored

Returns

The 1-based Z order of the frame

Return type

int

Raises
Available

CScript

frame::get_z_order

CFrame.moveForward()

Move the frame forward one step in the Z order.

Return type

None

Raises

CometError – On internal error

Available

CScript

frame::bring_forward

CFrame.moveBackward()

Move the frame backward one step in the Z order.

Return type

None

Raises

CometError – On internal error

Available

CScript

frame::send_backward

CFrame.moveToFront()

Move the frame to the most forward position undernearth its parent.

Return type

None

Raises

CometError – On internal error

Available

CScript

frame::bring_to_front

CFrame.moveToBack()

Move the frame to the most backward position undernearth its parent.

Return type

None

Raises

CometError – On internal error

Available

CScript

frame::send_to_back

CFrame.isInFront()

Determine whether the frame is the topmost frame of its page.

Returns

Whether the frame is at the top.

Return type

bool

Raises

CometError – On internal error

Available

CScript

frame::is_in_front

CFrame.isInBack()

Determine whether the frame is the bottommost frame of its page.

Returns

Whether the frame is at the bottom.

Return type

bool

Raises

CometError – On internal error

Available

CScript

frame::is_at_back

CFrame.hasOverset(fullChain=True)

Are text parts of the text model or frame non-visible? If the text has this so-called overset, a small red plus is shown at the selected frame. The function can only ascertain the overset of textframes or texts.

Parameters

fullChain (bool) –

Check the complete text frame chain?

  • True : Check complete chain

  • False : Check only this frame

Returns

Whether the frame has overset

Return type

bool

Raises
Available

CScript

frame::overset

CFrame.getTextModel()

Fetch the text model interface of this frame if it is a text frame.

Returns

The frame’s text model

Return type

CTextModel

Raises
Available

CFrame.getText(position=0, length=- 1, format=0)

Get text content of a Text frame.

The export can be carried out as pure text (comet.kExportPlain) or as text with formatting.

Formattings are written as InDesign® TaggedText. The format of the TaggedText is independent from the settings of the export dialog and is always done with the following settings :

Coding ASCII, Unicode characters are written in the form <0x2202> Platform Windows,rn (13 10) is used as line delimiter of the (internal) formatting Style unabbreviated, i.e. ParaStyle instead of pstyle, …

If the text contains InDesign® variables, the internal code used in the document (and not the current value) is exported on pure text formats like comet.kExportPlain. Use the ~Plus~-Formats to replace InDesign® variables by their current values.

Parameters
Returns

The frame’s text

Return type

str

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not a text frame

  • ValueError – When parameter start, length or format has invalid Value

  • CometError – On internal error

Available

CScript

frame::gettext

See also

setText()

CFrame.setText(text, start=0, length=- 1, autoLoad=True, flags=0)

Replace text in the frame. Inserting formatted text like TaggedText or HTML is also possible.

Parameters

  • text (str) – The text to insert

  • start (int) – Insert position in the text

  • length (int) –

    Number of characters replace.

    Default is comet.kEnd == until the end

  • autoLoad (bool) –

    When inserting TaggedText, should placeholders be loaded?

    Ignored

  • flags (int) –

    Instructions for preparing TaggedText.

    • 0 : Off

    • 2 : Fix parastyles of all cells

    • 4 : Fix parastyles of complete text

    • 8 : Check tables

    • 16 : Replace <in> tags by <w2inline> tags

    • 32 : Repair hyperlinks

    Please note:
    For normal text, the parameter has no meaning.

    As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells. Changes to your TaggedText are not required for this.

    If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.

    Flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.

    Ignored

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not a text frame

  • CometError – On internal error

Returns

None

Available

CScript

frame::replace

See also

getText()

CFrame.replace(content, position=0, length=- 1, autoLoad=True, flags=0)

Replace text in a frame.

The text may be TaggedText.

The text may be prefixed HTML text.

Parameters

  • content (str) – The text to insert.

  • position (int) – The position to insert the text.

  • length (int) –

    How many characters should be overwritten at max?

    Default is comet.kEnd == overwrite until the end.

  • autoLoad (bool) –

    Should text placeholders in TaggedText be loaded?

    Ignored

  • flags (int) –

    Instructions for preparing TaggedText. For normal text, the parameter has no effect.

    • 0 : Off

    • 1 : Fix parastyles of non-empty cells

    • 2 : Fix parastyles of all cells

    • 4 : Fix parastyles of complete text

    • 8 : Check tables

    • 16 : Replace <in> tags by <w2inline> tags

    Ignored

    Values 1, 2 and 4 are ignored. Missing or empty paragraph styles are always calculated and used here.

Returns

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameters length or flags are out of range or invalid

  • CometError – On internal error

Available

CScript

frame::replace

CFrame.fit(refPoint=0, constantWidth=False)

Fit a frame to its content

Parameters

  • refPoint (int) –

    The reference point which is fixed during resizing.

    One of Reference Points.

  • constantWidth (bool) – When the text content is on a single line, should we keep the width?

Returns

Result sizes as (new width, new height)

Return type

tuple[float, float]

Raises
Available

CScript

frame::fit_better

CFrame.fitImage(method, data=5, size=0.0, maxScale=1.0)

Fit an image to its frame.

Parameters

  • method (int) –

    Fitting method. One of:

    • 0: Fill frame proportionally: Scale image proportionally to completely fill the frame

    • 1: Fit content proportionally: Scale image to become completely visible

    • 2: Fit content to frame:Scale image in both directions to completely fill the frame

    • 3: Fit frame to content: Fit the frame to match the image.

    • 4: Center content in frame

    • 5: Comet position

  • data (int) –

    Additional information about the placement of the image.

    Methods 0, 1, 2 and 4:

    -1: Use InDesign® built-in method only

    Otherwise: Use priint:comet method

    Method 5:

    Image position. If the parameter is omitted, then - if the image has already been placed by the Comet - the last Comet placement for this image is restored.

  • size (float) – Image placement size of bounding box for image.

  • maxScale (float) – Maximum image scaling factor

Returns

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter method has invalid value.

    • When parameter data has invalid value.

    • When parameter size has invalid value.

    • When parameter maxScale has invalid value.

  • CometError – On internal error

Available

CScript

frame::fit_image

CFrame.getChainFrames()

Get all frames in the chain of this frame.

The result is ordered in the order the frames are linked.

Returns

A list of all chained frames including this one.

Return type

list[CFrame]

Raises
Available

CScript

itemlist::chained

CFrame.getImage()

Get the full path to the image in this frame

Returns

The image path

Return type

str

Raises
Available

CScript

frame::image_getpath

CFrame.setImage(path, alignment=0, boundingBox=0.0, options={})

Insert an image into this frame

Replace the image

Parameters

  • path (str) – The full path to the image file

  • alignment (int) –

    The alignment of the image in the frame.

    Align this reference point with the same reference point of the old image.

    One of Reference Points.

  • boundingBox (float) –

    The new size of the image.

    • 0.0 : Fit image (proportionally) into the frame. If the image is smaller than the frame it is left unchanged.

    • > 0.0 : Fit image proportionally into a square frame of this size. If the image is smaller, it is not changed.

    • < 0.0 : Fit image proportionally into a square frame of this size. If the image is smaller, it is enlarged accordingly.

    Ignored

  • options (dict[str, str | int]) –

    Additional import options which depend on the input file type.

    Keys must be str. Value types depend on the provided keys.

    The following options are available:

    PDF

    ’kPageIndex’

    • Value type: int

    • Default: 0

    The page index to place from the PDF file.

    • -1: Use last page.

    • Greater than page count - 1: Use first page.

    • Else: Place the page with this index.

    ’kPageNumber’

    • Value type: int

    • Default: 1

    The page number to place from the PDF file. This behaves the same as ‘kPageIndex’ but uses 1-based numbers.

    This option is mutually exclusive with ‘kPageIndex’.

    ’kCropBox’

    • Value type: int or str

    • Default: ‘kDefault’

    The cropping behavior to apply.

    The following values are available:

    • ’kDefault’, -1 or 1: Use the application default.

    • ’kContent’, or 0: Crop to content.

    • ’kArt’, or 2: Crop to art.

    • ’kCrop’, or 3: Crop to page.

    • ’kTrim’, or 4: Crop to trim.

    • ’kBleed’, or 5: Crop to bleed.

    • ’kMedia’, or 6: Crop to media.

    • ’kContentAllLayers’, or 7: Crop to content (all layers).

      Not supported.

    ’kLayers’

    • Value type: list [str]

    • Default: []

    List of layer names.

    All specified layers of the PDF file will be made visible, all others invisible.

    If the list is empty, the layer visibility settings of the PDF file will be used.

    Attention: It is not sufficient to set the layer visibility in the PDF with the layer eyes only, you have to use the layer options for that!

    Not supported.

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter path is empty

    • When parameter alignment has invalid value

  • CometError – On internal error

Available

CScript
CFrame.getImageSize(boundsKind=0)

Ascertain the absolute size of the image in this frame.

Parameters

boundsKind (int) –

Which type of size to fetch.

  • 0: Bounding box

  • 1: Image frame size

Returns

Size as (width, height)

Return type

tuple[float, float]

Raises

  • TypeError – When this frame is not an image frame

  • ValueError – When parameter boundsKind has invalid value

  • CometError – On internal error

Available

CScript

frame::image_getsize

CFrame.setImageSize(width, height, refPoint=0)

Set the absolute size of the image in this frame.

Parameters
Return type

None

Raises
Available

CScript

frame::image_size

CFrame.getImagePosition(boundsKind=0)

Ascertain the position of the image inside this frame. The result values are relative to the top left corner of this frame.

Parameters

boundsKind (int) –

Fetch position relative to these bounds.

  • 0: Outer stroke path

  • 1: Path bounds (“blue” frame)

Returns

Position as (x, y)

Return type

tuple[float, float]

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not an image frame

  • ValueError – When parameter boundsKind has invalid value

  • CometError – On internal error.

Available

CScript

frame::image_getpos

CFrame.setImagePosition(x, y)

Set the position of the image in this frame.

Parameters

  • x (float) – New image x position

  • y (float) – New image y position

Return type

None

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not an image frame

  • CometError – On internal error.

Available

CScript

frame::image_pos

CFrame.getImageScale()

Ascertain the relative size of the image in this frame to its original size.

Return values are factors where 1.0 = 100%

Returns

Size as (scaling factor x, scaling factor y)

Return type

tuple[float, float]

Raises
Available

CScript

frame::image_getscale

CFrame.setImageScale(width, height, refPoint=0, frameRelativeRefPoint=False)

Set the size of the image in this frame relative to its original size.

Parameters

  • width (float) – New image width factor

  • height (float) – New image height factor

  • refPoint (int) –

    The reference point which is fixed during resize.

    One of Reference Points.

    Default is comet.kRefPointTopLeft

  • frameRelativeRefPoint (bool) –

    Should the graphics frame be used as the basis for the reference point instead of the image itself?

    • True: Use the graphics frame as the basis for calculating the reference points.

    • False: No, use image as basis for calculating the reference point.

Return type

None

Raises
Available

CScript

frame::image_scale

CFrame.getImageRotation()

Ascertain the rotation of the image in this frame.

Returns

The rotation angle in degrees

Return type

float

Raises
Available

CScript

frame::image_getrotation

CFrame.setImageRotation(angle, x, y)

Rotate the image in this frame.

Parameters

  • angle (float) – The rotation angle in degrees

  • x (float) – X value of the reference point for the rotation in points relative to the left edge of the image, not the frame.

  • y (float) – Y value of the reference point for the rotation in points relative to the left edge of the image, not the frame.

Return type

None

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not an image frame

  • CometError – On internal error.

Available

CScript

frame::image_rotate

CFrame.getImageSkew()

Get the current skew angle of the image in this frame.

Returns

The current skew angle of the image

Return type

float

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not an image frame

  • CometError – On internal error.

CFrame.setImageSkew(angle, x, y)

Skew the image of a graphic frame.

Parameters

  • angle (float) – The skew angle

  • x (float) – X value of the reference point for the rotation in points relative to the left edge of the image, not the frame.

  • y (float) – Y value of the reference point for the rotation in points relative to the left edge of the image, not the frame.

Return type

None

Raises

  • TypeError –

    • When parameter types are invalid

    • When this frame is not an image frame

  • CometError – On internal error

Available

CScript

frame::image_skew

CFrame.getTableCount(start=0, length=- 1)

Counts tables in the frame.

Parameters

  • start (int) – The start index

  • length (int) –

    The length to search inside the text.

    Default is comet.kEnd = Search until the end

Returns

The table count

Return type

int

Raises

  • TypeError –

    • When the frame is not a text frame

    • When parameters start or index have wrong type

  • ValueError – When parameters start or index are invalid

  • CometError – On internal error

Available

CScript

table::count

CFrame.getNthTable(index=0, start=0, length=- 1)

Get a table from the frame. This queries the entire frame chain if the frame is linked.

Parameters

  • index (int) – The table index to get

  • start (int) – Search from a specific start position

  • length (int) –

    The length to search inside the text.

    Default is comet.kEnd = Search until the end

Returns

The found table

Return type

CTable

Raises

  • TypeError –

    • When the frame is not a text frame

    • When parameters start or index have wrong type

  • ValueError – When parameters start or index are invalid

  • CometError – On internal error

Available

CScript

table::get

CFrame.getBuiltElements()

Get all elements built by an repeating element placeholder. This function only yields valid results when this frame has a repeating element placeholder and has been built at least once.

Returns

A list of built elements.

Return type

list[CElement]

Available

CScript

elementlist::get_area_built_elements

CFrame.getCometGroup(searchHierarchy=True)

Get the comet group ID of this frame.

Parameters

searchHierarchy (bool) –

Search document hierarchy if the frame has no group ID?

Ignored

Returns

The comet group or None if the frame does not belong to a group

Return type

CCometGroup | None

Raises
Available

CScript

frame::get_cometgroup

CFrame.getCometGroupID(searchHierarchy=True)

Get the comet group ID of this frame.

Parameters

searchHierarchy (bool) –

Search document hierarchy if the frame has no group ID?

Ignored

Returns

The comet group ID or 0 if the frame does not belong to a group

Return type

int

Raises
Available

CScript

frame::get_cometgroup

CFrame.setCometGroupID(ID)

Add a frame to a Comet group. If the frame is a parent frame of a comet group, the entire group is added as a subgroup.

Parameters

ID (int) – The new comet group ID

Return type

None

Raises
Available

CScript

frame::add_to_cometgroup

CFrame.removeFromCometGroup(ID=- 1)

Detach a frame from a Comet group. The frame is then no longer assigned to any group, except for frames that are themselves the main frame of a group: this membership is retained.

If the Comet ID is -1, the frame is detached from any membership, otherwise only if it is a member of the specified group.

Parameters

ID (int) –

The group ID to remove from.

  • -1: Remove from any group.

Raises
Available

CScript

frame::remove_from_cometgroup

Link all placeholders and all subframes with the given ID.

Parameters

  • recordID (CIDType) – The record ID to link the content to.

  • start (int) – The text start index to begin linking

  • length (int) –

    The text length to link placeholders for.

    Default is comet.kEnd == link every placeholder until the text end

  • autoLoad (bool) –

    Should all placeholders be loaded after linking?

    See also

    load()

  • applyRules (bool) –

    Only relevant when *autoLoad* is true.

    Apply layout rules “After load” after successful execution?

  • changeStaticLinks (bool) – Overwrite static product links?

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter recordID has invalid value

    • When parameter start has invalid value

    • When parameter length has invalid value

  • CometError – On internal error

Available

CFrame.load(start=0, length=- 1, applyRules=False, placeholderIDs=[], recordIDs=[])

Execute the load action for all placeholders of a frame or text including its sub-objects.

Parameters

  • start (int) –

    The text start index to begin loading.

    Only evaluated for text frames.

  • length (int) –

    The text length to load placeholders for.

    Default is comet.kEnd == load every placeholder until the text end.

    Only evaluated for text frames.

  • applyRules (bool) – Apply layout rules “After load” after successful execution?

  • placeholderIDs (list[int]) –

    List of placeholderIDs to restrict loading to. Entries must be of type int

    • []: Impose no restrictions

  • recordIDs (list[CIDType]) –

    List of recordIDs to restrict loading to.

    • []: Impose no restrictions

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter start has invalid value

    • When parameter length has invalid value

  • CometError – On internal error

Available

CFrame.store(start=0, length=- 1, placeholderIDs=[], recordIDs=[])

Execute the store action for all placeholders of a frame or text including its sub-objects.

Parameters

  • start (int) –

    The text start index to begin storing.

    Only evaluated for text frames.

  • length (int) –

    The text length to store placeholders for.

    Default is comet.kEnd == store every placeholder until the text end.

    Only evaluated for text frames.

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter start has invalid value

    • When parameter length has invalid value

  • CometError – On internal error

Available

CFrame.build()

Execute the build action of a frame. This action should normally create the repeating elements for this frame. The placeholder of the frame must be:

RelatedTo kMultiFrame (=6)

CharacterStyleID > 0

Return type

None

Raises

CometError – On internal error

Available

CFrame.getSmartItemData(key)

Get the frame properties to support products buildings.

Parameters

key (int) –

Which property to fetch.

Results are:

  • 0: Frame label (Single character)

  • 1: Sequence number

  • 2: Type

    • 0 : Normal

    • 1 : Can continue

    • 2 : Repeat (not supported for now)

    • 3 : Can continue but do not change its height

  • 3: Rule to execute before inserting template

    • -3 : New right page

    • -2 : New left page

    • -1 : New page

  • 4: Use this frame in text flows?

    • 0 : Insert text content

    • 1 : Insert as inline

    • 2 : Do not use

  • 5: Use for builds?

    • 0 : Yes

    • 1 : Do not use

    • 2 : Use but ignore on reorganizations

  • 6: Bit field with additional info

    • 0x00000001 : Load frame place holder

    • 0x00000002 : Load text place holder

  • 7: Area type

    • 0 : Bounding Box

    • 1 : Path (star)

    • 2 : Path with holes (empty star)

    • 3 : ignore (minus)

Returns

The stored value. The type depends on the data to fetch:

Return type

str | int

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameter key has invalid value

Available

CScript

frame::get_smart_item_data

CFrame.setSmartItemData(key, value)

Set the frame properties to support products buildings.

Parameters

  • key (int) – Which property to set

  • value (str | int) –

    The value to set.

    See getSmartItemData() for possible parameter values. The type depends on the parameter key:

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameter key has invalid value

Available

CScript

frame::set_smart_item_data

CFrame.getNail(referencePoint)

Determine whether this frame has a nail at a specific reference point.

Parameters

referencePoint (int) –

The reference point to query.

One of Reference Points.

Returns

Nail type, edge nail prefers maximum size change.

Nail type can be:

  • 0 : No nail or error

  • 1 : Nail

  • 2 : Percent nail

  • 3 : Magnet (only if not pinned by a nail at this side)

  • 4 : Percent magnet (only if not pinned by a nail at this side)

Return type

tuple[int, bool]

Raises
Available

CScript

frame::get_nail

CFrame.setNail(referencePoint, type, preferMax=False)

Set or remove priint:adjust nails.

Please note that due to the experimental nature of this function, it is not convered by support

Parameters

  • referencePoint (int) –

    The reference point to change the nail for.

    One of Reference Points.

  • type (int) –

    The type of nail to set.

    • 0 : Remove

    • 1 : Normal (green) nail

    • 2 : Relative (red) nail

    • -1 : Toggle

  • preferMax (bool) –

    Edge type, for edge nails only and ignored if parameter type is -1

    • True : Prefer longer side

    • False : Prefer shorter side

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter referencePoint has invalid value

    • When parameter type has invalid value

  • CometError – On internal error

Available

CScript

frame::set_nail

CFrame.applyMagnets(applyRules=False, applyBuildActions=True)

Apply magnets of this frame.

This recursively updates all dependent frames aswell.

Parameters

  • applyRules (bool) – Apply adapter rules of frames?

  • applyBuildActions (bool) – Apply rules of type “While building products” of frames?

Raises
Available

CScript

frame::apply_magnets

CFrame.applyLayoutRules(situation, callerData=None, recordID=None)

Apply layout rules of this frame.

Rules are not executed if the given rule type is suppressed.

Parameters
Return type

None

Available

Raises
CScript

frame::apply_layout_rules

CFrame.getPageElement(checkCometGroup=False, checkTopLeft=False, queryNearest=False)

Determine the page element in which a frame or the frame’s comet group is located.

The assignment to a page element is determined exclusively by the current XY position of the frame (or the comet group of the frame) and the current page template.

Parameters

  • checkCometGroup (bool) –

    • False: Use the frame itself

    • True: Use the comet group of the frame

  • checkTopLeft (bool) –

    • False: The bounding box around the frame or the comet group must fit into the page element.

    • True: The upper left corner of the bounding box must be in the page element.

  • queryNearest (bool) –

    Behavior on overlapping elements.

    • False: Use the first element found (This is the element with the smallest sequence number.)

    • True: Use the element whose upper left corner is closest to the upper left corner of the frame/comet group

    The parameter is used only if checkTopLeft is True

Returns

1-based page element sequence number, page element name

Return type

tuple[int, str]

Raises
Available

CScript

frame::get_page_element

CFrame.getTemplate(getName=False)

Determine the template which inserted this frame into the document.

Parameters

getName (bool) –

Whether to determine the template name from the active data connection.

  • False: Do not ask the data connection.

    The name in the result tuple is empty in this case.

  • True: Ask the data connection.

    The function will raise when the name could not be determined

Returns

Template ID, template name

Return type

tuple[int, str]

Raises

CometError –

  • On internal error

  • When parameter getName is True and the name could not be determined.

Available

CScript

frame::get_template

CFrame.duplicate(x=None, y=None, addToCometGroup=False, document=None, page=- 1, layer='')

Duplicate this frame.

By default the new frame has no comet group. Set addToCometGroup to True to copy the original comet group ID.

Parameters

  • x (None | float) –

    The new x coordinate for the duplicated frame.

    The parameter can type can be:

    • None:

      Use the coordinate of the source frame.

    • float:

      Page-relative coordinate in pt.

  • y (None | float) –

    The new y coordinate for the duplicated frame.

    The parameter can type can be:

    • None:

      Use the coordinate of the source frame.

    • float:

      Page-relative coordinate in pt.

  • addToCometGroup (bool) –

    Whether to add the duplicate to the same comet group as the original.

    If you duplicate into another document, the parameter has no effect!

  • document (CDocument | None) –

    The duplicate may be placed into a different document which can be designated here.

    • None: Place into same document as the original frame.

  • page (CPage | int) –

    The target page

    The parameter can type can be:

    • CPage:

      A page belonging to the same document as the parameter document (when it is set), or to the same document as the source frame

    • int:

      Page index

      • -1: Same as source frame

  • layer (CLayer | str) –

    The target layer

    The parameter can type can be:

    • CLayer:

      A layer belonging to the same document as the parameter document (when it is set), or to the same document as the source frame

    • str:

      A layer name.

      • Empty str: Same as the source frame

      When this layer does not exist yet, it is not automatically created. In this case the frame is placed on the default one.

Returns

The newly duplicated frame

Return type

CFrame

Raises
Available

CScript

frame::duplicate