comet.CPageItem¶
- class comet.CPageItem¶
- Inherited by:
InDesign® comet_pdf® CPageItem is a reference to a document page item (e.g. a frame)
Illustrator® 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:
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getUID()¶
Get the UID of this item as an int.
- Returns:
The UID of this item
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getType()¶
Determine the type of the item.
- Returns:
The type of the item.
One of Pageitem types
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getDocument()¶
Get the document this item belongs to.
- Returns:
The document
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- 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:
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getLayer()¶
Get the layer this item is on.
- Returns:
The item’s layer
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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:
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 raiseCometError
in this case.
ignoreLayerLocks (bool) –
Allow moving from and 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:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getParent()¶
Get the parent (e.g. containing frame) of this page item if one exists.
- Returns:
The parent item or
None
if none exists.- Return type:
CPageItem | None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- 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:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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?
InDesign® The internal untranslated name of an empty graphic frame is #Graphicframe. This is translated to Graphic frame by an English version of InDesign®.
Illustrator® Ignored
- Returns:
The name of this frame
- Return type:
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter nameType has invalid value.
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.setName(name)¶
Set the name of this item.
- CPageItem.getBBox(spreadRelative=False)¶
Get the bounding box of this item.
- CPageItem.moveTo(x, y, page=-1, executeLayoutRules=False, refPoint=0, useBBox=True)¶
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.
- 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?
refPoint (int) –
The reference point to move to the new coordinates.
One of Reference Points.
Default is
constants.kRefPointTopLeft
.InDesign® comet_pdf® Ignored. The left top point is always used.
useBBox (bool) –
Whether to move the reference point of the bounding box or the actual item.
True
: Move reference point of bounding box to the new coordinates.False
: Move the actual reference point of the page item to the new coordinates.
InDesign® comet_pdf® Ignored. The parameter is always true.
- Returns:
None
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter page has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- See also:
- CScript:
- CPageItem.getSize(boundsKind=0)¶
Get the size of this page item.
- Parameters:
boundsKind (int) –
Which bounds to get:
0: Frame with stroke
1: Frame without stroke
- Returns:
tuple of (width, height)
- Return type:
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.setSize(width=-1.0, height=-1.0, boundsKind=0, refPoint=0, offsetX=0.0, offsetY=0.0, executeLayoutRules=False)¶
Change the size of this page item.
Page items must be greater than 0.0 Points and must not be smaller than the strokes at both sides.
So a page item with a stroke of 10 points must have a size of at least 20 points.
InDesign®
If strokes avoid page item 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
Illustrator® Ignored. The value is always 1
refPoint (int) –
The reference point which is fixed during resize.
One of Reference Points.
Default is
constants.kRefPointTopLeft
.offsetX (float) –
Horizontal offset from the given reference point
Illustrator® Ignored.
offsetY (float) –
Vertical offset from the given reference point
Illustrator® Ignored.
executeLayoutRules (bool) –
Execute layout rules “After geometry changes” while executing the command?
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getRefPoint(refPoint, pageRelative=True)¶
Get the coordinates of this pageitem’s reference point
- Parameters:
refPoint (int) –
The reference point to get the coordinates for.
One of Reference Points.
pageRelative (bool) –
InDesign® comet_pdf®
- Returns:
Coordinates (x, y)
- Return type:
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameters refPoint has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getScale()¶
Get the item’s current scale factors.
- Returns:
The scale factors (vertical, horizontal) where 1.0 = 100%.
- Return type:
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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:
comet_pdf® Ignored. The left top point is always used.
Default is
constants.kRefPointTopLeft
executeLayoutRules (bool) –
Execute layout rules “After geometry changes” while executing the command?
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
When parameter x or y are <= 0.0
When parameter refPoint is of type
int
and has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getRotation()¶
Get the item’s rotation
- Returns:
The rotation in degrees
- Return type:
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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
constants.kRefPointCenter
.executeLayoutRules (bool) –
Execute layout rules “After geometry changes” while executing the command?
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter refPoint has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getSkew()¶
Get the current skew angle of the item.
- Returns:
The current skew angle
- Return type:
- Available:
InDesign® comet_pdf®
- CScript:
- 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:
Use a defined reference point. Value must be one of Reference Points
comet_pdf® Ignored. The left top point is always used.
Default is
constants.kRefPointTopLeft
executeLayoutRules (bool) –
Execute layout rules “After geometry changes” while executing the command?
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter refPoint is of type
int
and has invalid valueCometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getLocked()¶
Returns whether the item is locked.
- Returns:
Whether the item is locked
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.setLocked(locked=True)¶
Set the lock state of the item.
- Parameters:
locked (bool) – The new lock state
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.getVisible()¶
Determine whether the item is visible or hidden.
- Returns:
Whether the item is visible
- Return type:
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.setVisible(visible=True)¶
Set the visibility state of this item.
- CPageItem.getPrintable()¶
Get the printability of the item (printing and PDF exports).
- Returns:
Whether the item is marked as printable
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.setPrintable(enable)¶
Set the printability of the item (printing and PDF exports).
- Parameters:
enable (bool) – Enable printability?
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.getOverprint(what=0)¶
Get the overprint setting of the item.
- Parameters:
what (int) –
Which setting to query
One of Overprint settings
Default is
constants.kOverprintBasic
- Returns:
Whether overprint is active for the queried setting
- Return type:
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.setOverprint(enable, what=0)¶
Set the overprint setting of the item.
- Parameters:
enable (bool) – Enable the specified setting?
what (int) –
Which setting to change
One of Overprint settings
Default is
constants.kOverprintBasic
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.setStroke(options)¶
Set the stroke of this item.
- Parameters:
options (dict[str, bool | int | float | str | CColor | CSwatch | tuple[int, int, int], tuple[float, float, float, float], tuple[float, int, int]]) –
The stroke options.
Keys must be
str
.Value types depend on the provided keys.
The following options are available:
- Return type:
None
- Raises:
When parameter types are invalid.
When parameter options has non-
str
key.When parameter options has value type which does not match the expected type.
When parameter options[‘color’] has color values which are out of range.
When parameter options[‘width’] is < 0.0.
When parameter options[‘tint’] is out of range.
When parameter options[‘lineStyle’] is out of range.
When parameter options[‘gapTint’] is out of range.
When parameter options[‘alignment’] is out of range.
When parameter options[‘miter’] is out of range.
KeyError – When parameter options contains invalid key.
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- 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?
- Returns:
Full path to the object style
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.setObjectStyle(stylePath, removeOverrides=False)¶
Set this item’s object style.
- Parameters:
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getZOrder(intersecting=False)¶
Determine the Z order of this page item. If the page item is a group, this group is treated as one object, for all other groupings the page item are treated as individual objects.
- Parameters:
intersecting (bool) –
False
: Determine Z-order within the spread.True
: Use only the page items that overlap the specified page item to determine the Z-order.
The page item that is furthest forward has Z-order 1 - but it does not have to be the frontmost page item of the spread.
Likewise, of course, the page item with the largest Z-value does not need to be the bottom page item of the spread.
Illustrator® Ignored
- Returns:
The 1-based Z order of the page item
- Return type:
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.moveForward()¶
Move the page item forward one step in the Z order.
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.moveBackward()¶
Move the page item backward one step in the Z order.
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.moveToFront()¶
Move the page item to the most forward position undernearth its parent.
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.moveToBack()¶
Move the page item to the most backward position undernearth its parent.
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.isInFront()¶
Determine whether the page item is the topmost item of its page.
- Returns:
Whether the page item is at the top.
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.isInBack()¶
Determine whether the page item is the bottommost item of its page.
- Returns:
Whether the page item is at the bottom.
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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:
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter type has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getFillColor()¶
Get the primary fill color of this item.
- Returns:
The color and swatch if any is applied, else
None
.- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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.InDesign® comet_pdf® Only values of type
str
are supported. Other data types get converted to string representations of their values.- Return type:
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter key is empty
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- 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.
InDesign® comet_pdf® Only values of type
str
are supported. Other data types get converted to string representations of their values.- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.setScriptTag(key, value)¶
Set the value of a script tag. The value is overwritten if it already exists.
- Parameters:
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameters key is empty
CometError – On internal error
- Available:
InDesign® comet_pdf® Illustrator®
- CScript:
- CPageItem.removeScriptTags(keys)¶
Remove script tags.
- Parameters:
- Raises:
TypeError – When parameter types are invalid
CometError – On internal error
- Return type:
None
- Available:
InDesign® comet_pdf® Illustrator®
- CPageItem.getWrap()¶
Get the contour type and the contour spacing.
- Returns:
A tuple of: (mode, left contour width, top contour height, right contour width, bottom contour width)
Where mode is one of Wrap types
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.setWrap(mode=-1, left=None, top=None, right=None, bottom=None)¶
Set the contour type and the contour spacing.
- Parameters:
mode (int) –
The contour type.
One of Wrap types
left –
The parameter type can be:
top –
The parameter type can be:
right –
The parameter type can be:
bottom –
The parameter type can be:
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
ValueError – When parameter mode has invalid value
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getWrapIgnore()¶
Determine whether this apply should apply the text outline guidance of other items.
- Return bool:
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.setWrapIgnore(state=True)¶
Set whether or not this item should apply the text outline guidance of other items.
It does not influence whether the item itself sets an outline guide.
- CPageItem.overrideMasteritem(page)¶
Localize a given master page item for a document page.
Single-page spreads on double-page spreads and double-page spreads on single-page spreads are supported.
But in order to avoid horizontal shifts of the overridden items, spreads with more than two pages must use master pages with at least the same number of pages. Otherwise you must correct the horizontal shift in your scripts.
- Parameters:
The target page which has the master page of the master item applied.
The parameter can type can be:
- Returns:
The newly overridden and localized page item.
- Return type:
- Raises:
TypeError – When parameter types are invalid
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.isMasteritemOverriden(page)¶
Is this master page item localized on a given page?
Please note that, unlike
isOverridenMasteritem()
, this method requires a page specification. Overrides are always done on a per-page basis.
- CPageItem.isOverridenMasteritem()¶
Is this item an overridden master page item?
In contrast to
isMasteritemOverriden()
, the function does not require a page specification, as the page number can be determined implicitly from the given item reference.
- CPageItem.removeMasteritemOverride()¶
Remove all local overrides of this page item.
The function checks whether the page item is an overridden master page item at all and, if necessary, restores the original state of the master page item.
The item is then no longer localized.
If this page item is a sub-element of a group, the entire group is automatically processed.
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign® comet_pdf®
- CScript:
- CPageItem.getAlternativeText()¶
Determine the settings for the alternative text of this item.
This setting can be made manually in InDesign® using the dialog Object -> Object export options… dialog in the Alternative text category.
- Return A tuple of the following values:
Determined source of the alternative text.
User-defined alternative text. It is irrelevant whether the item actually uses this text (type 0) or not.
Namespace prefix in the XMP header. The value is defined automatically for XMP-based texts and is only of technical interest.
Input path in the XMP header. The value is defined automatically for XMP-based texts and is only of technical interest.
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.setAlternativeText(source, text='')¶
Define an alternative text as a frame or image description.
This setting can be made manually in InDesign® using the dialog Object -> Object export options… dialog in the Alternative text category.
- Parameters:
source (int) –
Source for the alternative text text.
0: User-defined. The text is specified in the text parameter.
The texts for the following information are determined from the IPTC core of the XMP structure of the image. You can define this information e.g. using the Adobe Bridge metadata panel.1: From XMP:Title
2: From XMP:Description
3: From XMP:Caption
6: From XMP:Alternative text (accessibility)
7: From XMP:Extended description (accessibility)
These values are set but not further supported by priint:comet.4: From other XMP
5: From structure
text (str) – User-defined description text. The specification is only used for source 0 (user-defined).
- Return type:
None
- Raises:
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.getPDFAccessibility()¶
Determine the settings for accessible description text of this item.
This setting can be made manually in InDesign® using the dialog Object -> Object export options… in the PDF with tags category.
- Returns:
A tuple of the following values:
Type of source of the accessible description text
Determined source of the accessible description text
User-defined accessible description text. It is irrelevant whether the item actually uses this text (type 0) or not.
Variable for the namespace prefix in the XMP header. The value is defined automatically for XMP-based texts and is only of technical interest.
Property path in the XMP header. The value is defined automatically for XMP-based texts and is only of technical interest.
- Return type:
- Raises:
CometError – On internal error
- Available:
InDesign®
- CScript:
- CPageItem.setPDFAccessibility(type, source, text='')¶
Define a text for the accessible description of the content of a frame.
This setting can be made manually in InDesign® using the dialog Object -> Object export options… dialog in the PDF with tags category.
- Parameters:
type (int) –
Apply tag:
0: From structure
1: Extra-textual element
2: Based on object
source (int) –
Source for actual text
0: User-defined. The text is specified in the text parameter.
The texts for the following information are determined from the IPTC core of the XMP structure of the image. You can define this information e.g. using the Adobe Bridge metadata panel.1: From XMP:Title
2: From XMP:Description
3: From XMP:Caption
6: From XMP:Alternative text (accessibility)
7: From XMP:Extended description (accessibility)
These values are set but not further supported by priint:comet.4: From other XMP
5: From structure
text (str) – User-defined description text. The specification is only used for source 0 (user-defined).
- Return type:
None
- Raises:
TypeError – When parameter types are invalid
When parameter type is out of range
When parameter source is out of range
CometError – On internal error
- Available:
InDesign®
- CScript:
- 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:
InDesign® comet_pdf® Illustrator®
- CScript: