comet.CPageItem

class comet.CPageItem
Inherited by:

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

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

Methods

CPageItem.isValid()

Determine whether this item is still valid and exists in a document. An item may be invalid e.g. when it is deleted from the owning document by calling remove()

Returns

Whether the item is still valid

Return type

bool

Available

CScript

frame::is_valid

CPageItem.getUID()

Get the UID of this item as an int.

Returns

The UID of this item

Return type

int

Raises

CometError – On internal error

Available

CScript

item::getint

CPageItem.getType()

Determine the type of the item.

Returns

The type of the item.

One of Pageitem types

Return type

int

Raises

CometError – On internal error

Available

CScript
CPageItem.getDocument()

Get the document this item belongs to.

Returns

The document

Return type

CDocument

Raises

CometError – On internal error

Available

CPageItem.getPage(queryNearest=False)

Get the page this item is on.

Parameters

queryNearest (bool) – When the item is not on a page find the closest page?

Returns

The page the item is on

Return type

CPage

Raises
Available

CScript

page::get

CPageItem.getLayer()

Get the layer this item is on.

Returns

The item’s layer

Return type

CLayer

Raises

CometError – On internal error

Available

CScript

frame::get_layer

CPageItem.setLayer(layer, moveGroup=False, ignoreLayerLocks=False)

Move this item to another layer.

Parameters

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

    The new target layer.

    The parameter type can be:

    • str

      Name of a top level layer.

    • list [str]

      Nested layer path.

    • int

      Top level layer index counting from the bottom.

    • CLayer

      Layer. Must be in the same document as this item.

  • moveGroup (bool) –

    • True: In case of sub or inline frames, the topmost item is moved instead.

    • False: Do not move sub or inline frames. The function will raise CometError in this case.

  • ignoreLayerLocks (bool) –

    Allow moving from and to locked layers?

    • TrueIgnore all layer locks.

      Attention : This may change te current document selection

    • False : Do not move items from or to locked layers.

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameter layer is empty str or invalid int or None

  • CometError – On internal error

Available

CScript
CPageItem.getGroup()

Get the group this item belongs to, if any.

Returns

The group if one exists, else None

Return type

CGroup | None

Raises

CometError – On internal error

Available

CScript

frame::get_group

CPageItem.getName(nameType=0, translate=False)

Get the name of this item as displayed in the layer panel.

Parameters

  • nameType (int) –

    The kind of name to retrieve.

    • 0: User defined name. If empty return the default name.

    • 1: Default name

    • 2: User defined name. If not set the result string is empty

  • translate (bool) –

    Translate the default name?

    The internal untranslated name of an empty graphic frame is #Graphicframe. This is translated to Graphic frame by an English version of InDesign®.

    Ignored

Returns

The name of this frame

Return type

str

Raises
Available

CScript

frame::get_name

CPageItem.setName(name)

Set the name of this item.

Parameters

name (str) –

The new name

  • Empty str: Reset to default name

Raises

TypeError – When parameter types are invalid

Available

CScript

frame::set_name

CPageItem.getBBox(spreadRelative=False)

Get the bounding box of this item.

Parameters

spreadRelative (bool) –

Get the coordinates relative to the page or to the spread the item is on?

Ignored

Returns

The bounding box

Return type

CRect

Raises

TypeError – When parameter types are invalid

Available

CScript

frame::bbox

CPageItem.moveTo(x, y, page=- 1, executeLayoutRules=False)

Move a frame to new coordinates. The frame may also be moved to another page. The new position is the position of the left upper corner of the frame’s bounding box.

See also

frame.moveTo()

Parameters

  • x (float) – The new X position

  • y (float) – The new Y position

  • page –

    Move frames to another page?

    The parameter type can be:

    When the parameter is -1, the page is unchanged.

  • 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, supress rules if any.

Returns

None

Raises
Available

CScript

frame::moveto

CPageItem.getScale()

Get the item’s current scale factors.

Returns

The scale factors (vertical, horizontal) where 1.0 = 100%.

Return type

tuple[float, float]

Available

CScript

frame::get_scale

CPageItem.setScale(x, y, refPoint=0, executeLayoutRules=False)

Scale the item by the given factors.

Parameters

  • x (float) – Width factor

  • y (float) – Height factor

  • refPoint –

    The reference point to scale the frame around

    Depending on the parameter type, the behavior changes as follows:

    int

    Use a defined reference point.

    One of Reference Points.

    tuple (float, float)

    Horizontal and vertical offset from the top left point.

    Ignored. The left top point is always used.

    Default is comet.kRefPointTopLeft

  • 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

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter x or y are <= 0.0

    • When parameter refPoint is of type int and has invalid value

  • CometError – On internal error

Available

CScript

frame::scale

CPageItem.getRotation()

Get the item’s rotation

Returns

The rotation in degrees

Return type

float

Available

CScript

frame::get_rotate

CPageItem.setRotation(angle, refPoint=4, executeLayoutRules=False)

Rotate the item around it’s own reference point.

The rotation angle is absolute.

Parameters

  • angle (float) – The angle to rotate the item in degrees counter clockwise

  • refPoint (int) –

    The reference point which is fixed during rotation.

    One of Reference Points.

    Default is comet.kRefPointCenter.

  • 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::rotate

CPageItem.getSkew()

Get the current skew angle of the item.

Returns

The current skew angle

Return type

float

Available

CScript

frame::get_skew

CPageItem.setSkew(angle, refPoint=0, executeLayoutRules=False)

Skew an item horizontally. For a vertical skew, use the negative angle to skew followed by a rotation to the negative angle (use the same reference point for both transformations!).

Parameters

  • angle (float) – The skew angle

  • refPoint (int | tuple[float, float]) –

    The reference point to scale the item around

    Depending on the parameter type, the behavior changes as follows:

    int

    Use a defined reference point. Value must be one of Reference Points

    tuple [float, float]

    Horizontal and vertical offset from the top left point.

    Ignored. The left top point is always used.

    Default is comet.kRefPointTopLeft

  • executeLayoutRules (bool) –

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

    • True:

      Yes, 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::skew

CPageItem.getLocked()

Returns whether the item is locked.

Returns

Whether the item is locked

Return type

bool

Raises

CometError – On internal error

Available

CScript

frame::is_locked

CPageItem.setLocked(locked=True)

Set the lock state of the item.

Parameters

locked (bool) – The new lock state

Return type

None

Raises
Available

CScript
CPageItem.getVisible()

Determine whether the item is visible or hidden.

Returns

Whether the item is visible

Return type

bool

Available

CScript

frame::is_hidden

CPageItem.setVisible(visible=True)

Set the visibility state of this item.

Parameters

visible (bool) – Whether the item should be visible or not

Return type

None

Raises

TypeError – When parameter types are invalid

Available

CScript
CPageItem.getPrintable()

Get the printability of the item (printing and PDF exports).

Returns

Whether the item is marked as printable

Return type

bool

Raises

CometError – On internal error

Available

CScript

frame::get_printable

CPageItem.setPrintable(enable)

Set the printability of the item (printing and PDF exports).

Parameters

enable (bool) – Enable printability?

Return type

None

Raises
Available

CScript

frame::set_printable

CPageItem.getOverprint(what=0)

Get the overprint setting of the item.

Parameters

what (int) –

Which setting to query

One of Overprint settings

Default is comet.kOverprintBasic

Returns

Whether overprint is active for the queried setting

Return type

bool

Raises
Available

CScript

frame::get_overprint

CPageItem.setOverprint(enable, what=0)

Set the overprint setting of the item.

Parameters
Return type

None

Raises
Available

CScript

frame::set_overprint

CPageItem.getObjectStyle(translate=False)

Get the full path to this item’s object style.

When the style if part of a hierarchy, the name is delimited by ‘:’

Parameters

translate (bool) –

Translate default names?

  • True: Default names are returned in the host software locale.

  • False: In this case, the names of the default styles are always returned in English.

Returns

Full path to the object style

Return type

str

Raises

CometError – On internal error

Available

CScript

frame::get_objectstyle

CPageItem.setObjectStyle(stylePath, removeOverrides=False)

Set this item’s object style.

Parameters

  • stylePath (str) –

    Full object style path.

    When the style if part of a hierarchy, the name is delimited by ‘:’

    • ’’: Use default object style for this item type

  • removeOverrides (bool) – Remove local overrides?

Return type

None

Raises
Available

CScript

frame::set_objectstyle

CPageItem.getOpacity(type=0)

Get the opacity of this item.

Parameters

type (int) –

Which opacity type to get.

  • 0 : Object

  • 1 : Stroke

  • 2 : Fill

  • 3 : Content

Returns

The opacity in range[0.0, 100.0]

Return type

float

Raises
Available

CScript

frame::get_opacity

CPageItem.getFillColor()

Get the primary fill color of this item.

Returns

The color and swatch if any is applied, else None.

Return type

tuple[CColor, CSwatch | None]

Raises

CometError – On internal error

Available

CScript

frame::get_color

CPageItem.setFillColor(color)

Set the primary fill color of this item.

Parameters

color (CColor | CSwatch | str | tuple[int, int, int] | tuple[float, float, float, float]) –

The color data to apply.

The parameter type can be:

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameter color is invalid or any provided values inside are invalid

  • CometError – On internal error

Available

CScript

frame::color

CPageItem.getScriptTag(key)

Get the value of a single script tag. Returns None when the key does not exist.

Parameters

key (str) – The script tag key to get the value for

Returns

The found value or None if the key does not exist.

Only values of type str are supported. Other data types get converted to string representations of their values.

Return type

str | int | float | bool | None

Raises
Available

CScript

frame::get_script_tag

CPageItem.getScriptTags()

Fetches all script tags of the item. Data types may vary depending on the tag type.

Returns

A list of all script tags as key/values.

Only values of type str are supported. Other data types get converted to string representations of their values.

Return type

list[tuple[str, str | int | float | bool]]

Raises

CometError – On internal error

Available

CScript
CPageItem.setScriptTag(key, value)

Set the value of a script tag. The value is overwritten if it already exists.

Parameters

  • key (str) – The script tag key to set

  • value (str | int | float | bool) –

    The value to set.

    Only values of type str are supported. Other data types get converted to string representations of their values.

Return type

None

Raises
Available

CScript

frame::set_script_tag

CPageItem.removeScriptTags(keys)

Remove script tags.

Parameters

keys (list[str]) – The script tag keys to remove

Raises
Return type

None

Available

CPageItem.remove()

Deletes this item and all it’s children from it’s document.

All subsequent calls to this item’s or the item’s children functions will fail.

Return type

None

Raises

CometError – On internal error

Available

CScript

frame::remove