The module processes document frames of InDesign® documents.

Here you will find examples to use frame.

Version :
12.03.2024, 15:56 Uhr

The module processes document frames of InDesign® documents. In addition to the available functions manually available via the InDesign® menu commands, there are other implemented functions which cannot be directly activated via InDesign®.

static int is_valid(ItemRef itemRef)

Does the reference point to an existing frame?

Name Type Default Description
Return int   1 : Yes, the ref points to an existing frame.

0 : No frame referenced. Do not use this reference as a frame.
itemRef ItemRef - Any ItemRef or 0

Version 1.4.1 R383, 28. June 2007

priint:comet InDesign® Plug-Ins, Illustrator

item::defined
comet.CFrame.isValid

static int create(
  ItemRef itemref,
  int type,
  float l,
  float t,
  float r,
  float b,
  int page,
  char* layer ="",
  int columns = 1,
  int vertical = 0,
  float gutter = 0.0,
  ...)

Create a new frame or line. If a layer name is given, the frame is created on this layer. If columns is larger than 0, the frame is crfeated as text frame with the given column spacing gutter. If the spacing is smaller than 0.0, the default spacing in InDesign® will be used.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - With item::alloc generated reference. If the frame could be created, the variable contains a valid reference to the newly created frame after execution.
type int - Frame type
kRectangle
kOval
kPolygon
kStar
kSpline
kLine

From comet_pdf only rectangular frames are supported!

l, t, r, b float - Bounding box of frame in points. Values are relative to the page margins, not to the page!
page int - 1-based number of existing page.
layerName String oder char* "" Name of the destination level

"" : Currently selected layer (InDesign) or last layer selected with layer::select (InDesign Server and comet_pdf)

Otherwise : Name of an existing level
columns int 1 Number of text columns. If the number of columns is greater than 0, the frame is automatically created as a text frame.

The specification is ignored for lines (type = kLine).
vertical int 0 Orientation of text

0 : horizontal
1 : vertical

The specification is ignored for lines (type = kLine).
gutter float -1.0 Column spacing
-1.0 : Use the default column spacing from InDesign

The specification is ignored for lines (type = kLine).
⇨type = kPolygon
sides int - Number of polygon sides
⇨type = kStar
edges int - Number of edges
inset int - Length of edges as a percent
⇨type = kSpline
type, x, y, ... int, float, ... - Shape description consisting of any number of points given in the following format (The description of the point types is taken 1:1 from Adobe's InDesign documentation):

Anchor point with continuing tangent :
kCS, x, y, leftDirX, leftDirY, rightDirX, rightDirY

Anchor point with unsmooth curve point, left->right tangent discontinue. (The start curve point of an open path is of type "kCK".) :
kCK, x, y, leftDirX, leftDirY, rightDirX, rightDirY

Anchor point with both tangent degenerated. (Two consecutive kL type points form a line.) :
kL, x, y

Splines are automatically scaled into the bounding box given by (l, t, r, b). To get the object in original size, set an empty bounding box (r = l and b = t).

Of course, you can come up with the points yourself - and be surprised. Useful point defintions you can get in the following simple way:

  1. Manually create the object in InDesign.®.
  2. Drag the finished object to your desktop. This creates a file Snippet_NN.idms on your desktop.
  3. Open the snippet file Snippet_NN.idms in any text editor.
  4. In the snippet file, search for the word <PathPointArray>.

In versions prior to v4.2 R33520 splines cannot be defined and the old syntax -1000000.1 or -1000000.2 (instead of kCS, ...) to distinguish point types used until then has no effect.

#include "internal/types.h"

On the layer layer 3 of the second page, a new text frame in the form of a 5-pronged star is created. The frame will then be crossed through with a line. color and arrangement of lines with the same functions can also be set up, which can also be used with frames. The rounded end of the cross-out is set in frame::color - where it does not actually belong but stroke does have enough parameters.

#include "internal/types.h"
int main () { ItemRef frame = item::alloc (); int result;
result = frame::create (   frame,   kStar,   10.0, 210.0, 300.0, 400.0,   2, // page   "Layer 3", // layer name   1, // columns   0, // vertical columns?   12.3, // gutter   13, 40 // edges and their lengths   ); if (result != 0) { showmessage ("Error %d",result); item::release (frame); return 1; } result = frame::create (frame,   kLine,   10.0, 210.0, 300.0, 400.0,   2, // page   "Layer 3" // layer   ); frame::stroke_rgb (frame, 255, 0, 0, 20.0); frame::color (frame, "", 1, 1);
item::release (frame); return 0; }

Create a simple spline in original size.

#include "internal/types.h"
int main () { ItemRef fr = item::alloc ();
frame::create (   fr, // the new created frame   kSpline, // type   0.0, 0.0, 0.0, 0.0, // bbox   1, "", // page num and layer   1, // columns   0, // text orientation   -1.0, // gutter   kCS, 103.37085648896758, -226.77165354330714, 50.929911606987304, -222.51968503937013, 155.81180137094785, -231.02362204724415,   kCS, 116.12676200077863, -58.11023622047246, 175.65432105589673, -102.0472440944882, 56.59920294566052, -14.17322834645671,   kCS, 29.67006908739279, -113.38582677165356, -8.597647448040284, -55.27559055118111, 67.93778562282587, -171.49606299212599);
return 0; }

kCS, kCK and kL since v4.2 R33520.

priint:comet InDesign® Plug-Ins, comet_pdf

create_textframe
document::pages
document::page
layer

static int create2(
  ItemRef itemref,
  int type,
  float l,
  float t,
  float r,
  float b,
  int page,
  char* layer ="",
  int columns = 1,
  int vertical = 0,
  float gutter = 0.0,
  ...)

Create a new frame, position is given releativ to the page (not as in create relative to the pages margins)

#include "internal/types.h"

Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf

static int duplicate(
  ItemRef resultFrame,
  ItemRef srcFrame,
  float x,
  float y,
  ItemRef docRef = 0,
  int pageNum = -1,
  char* layername = 0,
  int addToCometgroup = 0)

Duplicate an existing document frame. Duplicating is allowed between different opened documents.

By default, the new frame has no Comet group. If you want add the new frame to the Comet group of the original, set addToCometgroup to 1.

Name Type Default Description
Return int   0 or ErrorCode
resultFrame ItemRef - Newly created frame

0 : Not interested in
Otherwise : with item::alloc allocated ItemRef
srcFrame ItemRef - Valid frame references
x, y float - page relative position of the new frame in points
docRef ItemRef 0 destimation document

0 : same document like srcFrame
pageNum int -1 Destination page

<=0 : same page like srcFrame
Otherwise : 1-based number of existing page
layerName String or char* "" Destination layer

"" : Same layer like srcFrame Otherwise : Name of existing layer
addToCometgroup int 0 Add the new frame to the Comet group of the original?

0 : No
1 : Yes. If you duplicate into an other document, the parameter has no effect!
int main ()
{
    int		res;
    ItemRef	resref	= item::alloc ();
res = frame::duplicate (resref, gFrame, 10.0, 10.0); wlog ("", "duplicate result : %d (%d --> %d)\n",   res, item::getint (gFrame), item::getint (resref));
item::release(resref);
return 0; }

Version 2.1 R 679, 22. April 2008
Parameter addToCometgroup since version v3.3 R3005, 22nd may 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.duplicate

static int create_textframe(
  ItemRef itemref,
  int l,
  int t,
  int r,
  int b,
  int page,
  char* layer ="",
  int columns = 1,
  float gutter = 0.0,
  int vertical = 0)

Create a new text frame. If a layer name is specified, the frame is created on this layer. If a column number larger than 0 is given, columns will be automatically set up in the frames with the spacing *gutter*. If the spacing is smaller than 0, the default spacing from InDesign® will be used.

If the script frame 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.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - reference allocated with item::alloc
l, t, r, b int - frame square in points releativ to the page margins (not to the page!)
page int - 1-based page page number
layerName String oder char* "" Name of the destination level

"" : Currently selected layer (InDesign) or last layer selected with layer::select (InDesign Server and comet_pdf)

Otherwise : Name of an existing level
columns int 1 Number of columns
gutter float InDesign® settings Column spacing
vertical int 0 Orientation of text

0 : horizontal
1 : vertical

Set up a new single column frame on the second layer of the first page

int		pg  	= 1;
ItemRef	frame  	= item::alloc ();
char	layerName[256];
int		result;
result = frame::create_textframe (   frame,   10, 10, 200, 200,   pg,   layer::name (2, layerName));


priint:comet InDesign® Plug-Ins, comet_pdf
create_textframe_f
document::pages
document::page
layer
comet.frame.createTextFrame

static int create_textframe_f(
  ItemRef itemref,
  float l,
  float t,
  float r,
  float b,
  int page,
  char* layer ="",
  int columns = 1,
  float gutter = 0.0,
  int vertical = 0)

Create a new text frame. Position and size specifications are given as float numbers. If a layer name is defined, the frame will be set up on this layer. If a column number larger than 0 is defined, columns will be automatically set up in the frames with the spacing *gutter*. If the spacing is smaller than 0, the default spacing from InDesign® is used.

If the script frame is a member of a Comet group and lies on the same spread like the new created frame, the new created frame will get a member of this Comet group too.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - reference allocated with item::alloc
l, t, r, b float - Frame square in points relative to page margins (not to the page itself!)
page int - 1-based number of existing page
layer String oder char* "" Name of the destination level

"" : Currently selected layer (InDesign) or last layer selected with layer::select (InDesign Server and comet_pdf)

Otherwise : Name of an existing level
columns int 1 Number of columns
gutter float InDesign® settings Column spacing
vertical int 0 Orientation of text

0 : horizontal
1 : vertical

Set up a new single column frame on the second layer of the current page

ItemRef		frame  	= item::alloc ();
char		layerName[256];
int			result;
result = frame::create_textframe_f (   frame,   10.0, 10.0, 200.5, 200.5,   document::page (),   layer::name (2, layerName));

Parameter vertical since v4.0.5 R12346, 29. Jul 2016

priint:comet InDesign® Plug-Ins, comet_pdf
create_textframe_f
document::pages
document::page
layer
comet.frame.createTextFrame

static int create_subtextframe(
  ItemRef itemRef,
  int l,
  int t,
  int r,
  int b,
  ItemRef parent,
  int columns = 1,
  float gutter = 0.0,
  int vertical = 0)

Create a new text frame as a sub-frame to another frame. If a column number larger than 0 is specified, columns will be automatically set up in the frames with the spacing *gutter*. If the spacing is smaller than 0, the default spacing from InDesign® will be used.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - reference allocated with item::alloc
l, t, r, b int - frame square in points relative to the parent frame
parent ItemRef - valid reference to a frame
columns int 1 column number
gutter float InDesign® setting Column spacing
vertical int 0 Orientation of text

0 : horizontal
1 : vertical
int main ()
{
    ItemRef		frame	= item::alloc ();
    ItemRef		subframe= item::alloc ();
    char		layerName[256];
    int			result;
result = frame::create_textframe (   frame,   10, 210, 300, 400,   2,   layer::name (2, layerName)); if (result != 0) { showmessage ("Error %d",result); item::release (frame); return 1; }
result = frame::create_subtextframe (   subframe,   0, 0, 100, 40,   frame,   3, 8.3);
frame::select (frame); item::release (frame); item::release (subframe);
return 1; }

Parameter vertical since v4.0.5 R12346, 29. Jul 2016

priint:comet InDesign® Plug-Ins
create_subtextframe_f
document::find_frame
document::insert_macro

static int create_subtextframe_f(
  ItemRef itemRef,
  float l,
  float t,
  float r,
  float b,
  ItemRef parent,
  int columns = 1,
  float gutter = 0.0,
  int vertical = 0)

Create a new text frame as a sub-frame to another frame. The function is identical to create_subtextframe with the only difference that the position and size specifications of the frame can be defined as floating-point numbers (float).

create_subtextframe

static int bbox(
  ItemRef frameRef,
  float* left,
  float* top,
  float* right,
  float* bottom,
  int spreadRelative = 0,
  int boundsKind = 0)

Get the co-ordination of the frames bounding box. Be aware that the rectangle is bigger than the frame itself on rotated frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
left float* -  
top float* -  
right float* -  
bottom float* -  
spreadRelative int 0 Get the coordinates relative to the page or to the spread?

0 : page relative
1 : spread relative
boundsKind int 0 Type of path

0 : stroke bounds
1 : path bounds

Enlarge a frames height by 20.0 points. For demonstration purposes, the current frame size is written to the log file. These values are different on rotated frames.

int main ()
{
    float		l, t, r, b;
    float		w, h;
frame::bbox (gFrame, &l, &t, &r, &b); frame::get_size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n",   item::getint (gFrame),   r-l, b-t,   w, h); frame::resize (gFrame,w, h+20.0, 0, 0);
return 0; }

Parameter spreadRelative since v2.1 R 1750, 9. Feb. 2010
boundsKind since v3.4 R5126, 24. Jan 2014

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

prefs::get_transform_settings
prefs::set_transform_settings
comet.frame.getBBox
comet.CFrame.getBBox

static int size(
  ItemRef frameRef,
  float* width,
  float* height,
  int = 0)

see frame::get_size

static int get_size(
  ItemRef frameRef,
  float* width,
  float* height,
  int boundsKind = 0)

Get the co-ordination of the frames bounding box. Be aware that the rectangle is bigger than the frame itself on rotated frames. The result comes without application of the scaling, skew and rotation!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
width float* - On successful return it contains the the witdh of frame
height float* - On successful return it contains the the height of frame
boundsKind int 0 since v3.4 R5126 Bounds kind

0 : stroke bounds
1 : path bounds

Enlarge a frames height by 20.0 points. For demonstration reasons, the current frame size is written to the log file. These values are different on rotated frames.

int main ()
{
    float		l, t, r, b;
    float		w, h;
frame::bbox (gFrame, &l, &t, &r, &b); frame::get_size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n", item::getint (gFrame), r-l, b-t, w, h);
frame::resize (gFrame,w, h+20.0, 0, 0); return 0; }

Version 3.2 R2255, 1. Feb. 2011
Parameter since v3.4 R5126, 24. Jan 2014

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

prefs::get_transform_settings
prefs::set_transform_settings
comet.frame.getBBox
comet.CFrame.getSize

static int refpoint(
  ItemRef frameRef,
  int whichPoint,
  float* x,
  float* y,
  int spreadrel = 0)

Get the co-ordinates of a reference point of a frame. Reference points are the nine "touch points" of a frame: left-top, top-center, right-top, ... .

Please note that InDesign always assigns frames on spreads to the page on which the larger area of the bounding box around the frame is located.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame
which int - Reference point to calculate:

kRefPointTopLeft (0)
kRefPointTopCenter(1)
kRefPointTopRight(2)
kRefPointLeftCenter(3)
kRefPointCenter(4)
kRefPointRightCenter(5)
kRefPointBottomLeft(6)
kRefPointBottomCenter(7)
kRefPointBottomRight(8)
x float* - x co-ordinate of reference point in points
y float* - y co-ordinate of reference point in points
spreadrel int 0 Get co-ordinates relative to the page or to the spread?

0 : page relative
1 : spread relative

Pleaxse note that comet_pdf can handle up to two page per spread only.
#include "internal/types.h"

Move a (possible rotated) frame to its current bottom right corner.

int main ()
{
    float x, y;
    float x8, y8;
    float l, t, r, b;
frame::bbox (gFrame, &l, &t, &r, &b); frame::refpoint (gFrame, 0, &x, &y); frame::refpoint (gFrame, 8, &x8, &y8); frame::moveto (gFrame, x8+(x-l), y8+(y-t));
return 0; }

v4.0.5 R18123, 12. Mai 2017

priint:comet InDesign® Plug-Ins, comet_pdf

Parameter spreadrel since v4.0.5 R20011, 24. Aug 2017
comet.CFrame.getRefPoint

static int bbox_on_creation(
  ItemRef frameRef,
  float* left,
  float* top,
  float* right,
  float* bottom)

Get the frames bounding box at import time (only valid for frames imported by templates). Use this call to get the original distances of comet group frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference. The frame must be imported by a template.
left float* -  
top float* -  
right float* -  
bottom float* -  

Version 3.1, R1550, 18. Sept. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

static int textlength(ItemRef frameRef, int includeTables = 0)

If the defined frame is a text frame, the length of the text will be returned, otherwise 0. If a text continues over several frames, the length of the text over all the frames will be ascertained.

Name Type Default Description
Return int   Length of the entire text excluding concluding 0-Byte or 0, if the reference is not a text frame.
frameRef ItemRef - Frames the text lengths of which are to be ascertained
includeTables int 0 0 : primary story only
1 : complete text including all table cells

Version 1.1.4
Parameter includeTables since v3.4 R7022, 21. Nov. 2014

priint:comet InDesign® Plug-Ins
textmodel::fulllength

static int moveto(
  ItemRef frameRef,
  float x,
  float y,
  int pg = -1,
  int action = 0,
  int suprRules = 1)

Move a frame to a specified position. The frame may be moved to another page. The left upper corner of bounding box of the frame will be moved to specified position. The position specification follows in points.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid reference to a document frame
x float - New x-position of (the bounding box of) the frame in points
y float - New y-position of (the bounding box of) the frame in points
pg int -1 Page to which the frame is to be moved. Pages are counted beginning with 1.

-1 : leave page unchanged
action int 0 Should both the content and frame, or just the frame be moved? Obsolete in InDesign® CS3.
0 Move content and frame
1 Only move the frame
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.

Move a list of frames to an new position. Distances between frames are untouched.

itemlist::apply (
 	frame::moveto, frames, 1, 0,
 	leftMargin, topMargin, newPage, 0);

Move a (possible rotated) frame to its current bottom right corner.

int main ()
{
    float x, y;
    float x8, y8;
    float l, t, r, b;
frame::bbox (gFrame, &l, &t, &r, &b); frame::refpoint (gFrame, 0, &x, &y); frame::refpoint (gFrame, 8, &x8, &y8); frame::moveto (gFrame, x8+(x-l), y8+(y-t));
return 0; }

parameter pg is usable since version 1.3.5, R 236
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.frame.moveTo
comet.CFrame.moveTo

static int resize(
  ItemRef frameRef,
  float width,
  float height,
  int boundsKind = 0,
  int refPoint = 0,
  float offset_x = 0.0,
  float offset_y = 0.0,
  int suprRules = 1)

Change the size of a frame. To change the size the reference point can be specified, from which the change is made. All specifications are made in points.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

According to the given reference point and a possible offset from this point the frame may change its position. The followiing formula calculates the new position:

δw * (xref+xoff)/w * cos (α) + δh * (yref+yoff)/h * sin (α)

δw * (xref+xoff)/w * sin (α) - δh * (yref+yoff)/h * cos (α)

with:
Variable Description
w Current frame size
h
α Frame rotation
δw Size changes
δh
xref Reference point relative to the top left corner (0, 0) of the frame. Set this points by using kRefPointTopLeft, ... .
yref
xoff Offset from the reference point
yoff
Here's an Excel table with the formula.

Name Type Default Description
Return int   0 or ErrorCode

11266 : This error is generated internally by InDesign® in case the current stroke width prohibited the requested frame size. Please try to set the stroke width to an appropriate value using frame::stroke before calling frame::resize.
frameRef ItemRef - Valid reference to a document frame
width float - New width of the frame. Values > 0 are ignored for vertical lines.

<= 0.0 : Keep width of frame untouched. Vertical lines change their length. Slanted lines become vertical lines.
height float - New height of the frame. Values > 0 are ignored on horizontal lines.

<= 0.0 : Keep height of frame untouched. Horizontal lines change their length. Slanted lines become horizontal lines.
boundsKind int 0 since v3.4 R5126 Frame size based on:

0 : Stroke path
1 : Frame path
refPoint int kRefPointTopLeft Ignored for inline frames. Scaling reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
offset_x, offset_y float, float 0.0, 0.0 Ignored for inline frames. Offset from the given reference point in points.
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.
#include "internal/types.h"

Enlarge a frames height by 20.0 points. For demonstration reasons, the current frame size is written to the log file. These values are different on rotated frames.

int main ()
{
    float		l, t, r, b;
    float		w, h;
frame::bbox (gFrame, &l, &t, &r, &b); frame::get_size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n", item::getint (gFrame), r-l, b-t, w, h);
frame::resize (gFrame,w, h+20.0, 0, 0);
return 0; }

refPoint, offset_x, offset_x since Version 2.1 R684, 23.4.2008
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.setSize

static int move_to_layer(
  ItemRef frameRef,
  char* layerName,
  int mvGroup = 0,
  int ignoreLayerLocks = 0)

Move a frame to another layer of the document. The target layer is determined by its name. If the layer is to be determined by its index, see move_to_ilayer.

Sub frames and inline frames cannot moved to separate layers. Comet versions prior 3.2 R2245 may crash InDesign® in this case! Use frame::isinline, frame::get_group and frame::parent to check frames. Example 1 moves the whole group to a new layer if a sub frame is moved.

Since Comet 3.2 R2245 the function suppresses moving sub frames. With parameter mvGroup set to 1 the top most object is moved to a new layer instead.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 oder ErrorCode
frameRef ItemRef - Frame to be moved
layerName String or char* - Name of the target layer
mvGroup int 0 0 : Do not move sub or inline frames. The function will return the result code 1274 in this case.

1 : In case of sub or inline frames, the top most frame is moved instead.
ignoreLayerLocks int 0 Allow moving from and to locked layers:

0 : No. Do not move frames from or to locked layers.
1 : Yes. Ignore all layer locks. Attention : This may change te current document selection!

Move the currently selected frame to the layer named "ASDF".

int main ()
{
    String layerName = string::alloc("ASDF");
frame::move_to_layer (gFrame, layerName); string::release(layerName);
return 0; }

Move a frame to an other layer. If the frame is a child of a InDesign group, the top group is moved.

int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();
item::assign (top, fr); item::assign (child, fr);
while (frame::get_group (child, parent) == 0) { item::assign (child, parent); item::assign (top, parent); }
item::release (parent); item::release (child);
return frame::is_valid (top); }
int main () { ItemRef top = item::alloc ();
if (!get_top (gFrame, top)) return 0;
frame::move_to_layer (top, "Ebene 2");
return 0; }

1.0.20
Parameter mvGroup since version 3.2 R2245, 18.01.2011
Parameter ignoreLayerLocks since v3.3.1 R4222, 18.09.2013

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

move_to_ilayer
layer
get_group
comet.CFrame.setLayer

static int move_to_ilayer(
  ItemRef frameRef,
  int layerIndex,
  int mvGroup = 0,
  int ignoreLayerLocks = 0)

Move a frame to another layer of the document. The target layer is defined by its index. If the layer is to be determined by its name, see move_to_layer.

Sub frames and inline frames cannot moved to separate layers. Comet versions prior 3.2 R2245 may crash InDesign® in this case! Use frame::isinline, frame::get_group and frame::parent to check frames. Example 1 moves the whole group to a new layer if a sub frame is moved.

Since Comet 3.2 R2245 the function suppresses moving sub frames. With parameter mvGroup set to 1 the top most object is moved to a new layer instead.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame to be moved
layerIndex int - Index of the target layer
mvGroup int 0 0 : Do not move sub or inline frames. The function will return the result code 1274 in this case.

1 : In case of sub or inline frames, the top most frame is moved instead.
ignoreLayerLocks int 0 Allow moving from and to locked layers:

0 : No. Do not move frames from or to locked layers.
1 : Yes. Ignore all layer locks. Attention : This may change te current document selection!

Move a frame to an other layer. If the frame is a child of a InDesign group, the top group is moved.

int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();
item::assign (top, fr); item::assign (child, fr);
while (frame::get_group (child, parent) == 0) { item::assign (child, parent); item::assign (top, parent); }
item::release (parent); item::release (child);
return frame::is_valid (top); }
int main () { ItemRef top = item::alloc ();
if (!get_top (gFrame, top)) return 0;
frame::move_to_layer (top, "Ebene 2");
return 0; }

1.0.20
Parameter mvGroup since version 3.2 R2245, 18.01.2011

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

move_to_ilayer
layer
comet.CFrame.setLayer

static int create_columns(
  ItemRef itemRef,
  int columns,
  float gutter = -1.0)

Create text columns in the specified frames. The columns are given either the InDesign® default spacing (gutter < 0.0) or the specified spacing *gutter_width*.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - with item::alloc allocated and from frame::create_textframe defined reference
columns int - Number of columns
gutter float InDesign® setting Column spacing
err_code = frame::create_columns (itemRef, columns [, gutter]);


priint:comet InDesign® Plug-Ins, comet_pdf

create_subtextframe_f
count_columns
document::find_frame
document::insert_macro

static int count_columns(ItemRef itemRef = 0, float* gutter = 0)

Get the number of text columns of a frame. If the frame is not a text frame, the result is 0.

Name Type Default Description
Return int   Number of columns of a text frame or 0
0 : Frame undefined or no text frame
itemRef ItemRef - Frame, the numbers of columns of which are to be ascertained

0 : current script frame (since R2222)
gutter float* 0 Gutter width in points
int main ()
{
    int			cols;
    float		gut;
    int			dir;
cols = frame::count_columns (gFrame, &gut); wlog ("", "Frame : %d columns, gutter %f\n", cols, gut);
cols = page::count_columns (page::get (gFrame), &gut, &dir); wlog ("", "Page %d : %d columns, gutter %f, direection %d\n", page::get (gFrame), cols, gut, dir);
return 0; }

Version 1.3.1 (20. Jan. 2006)

Since version 3.1 R2222, 7. Dec. 2010 the itemRef 0 points to the current script script frame.

Parameter gutter since version 3.1 R2222, 7. Dec. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

create_columns
comet.CFrame.getColumnCount

static int delete_textframe(ItemRef itemRef)

Delete a frame and its content from the document. The passed item reference is thereafter invalid. The function is working for inline frames too.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame reference
err_code = frame::delete_textframe (itemRef);

Check whether a image file exists. If so, the image is placed. Otherwise, the frame remove from the document. After inserting an image to a text, fit the text frame.

int main ()
{
    char			path[4096];
    int			ipos		= -1;
    ItemRef		parent	= item::alloc ();
strcpy (path, "$DESKTOP/clara.JPG"); if (frame::isinline (gFrame)) { ipos = frame::inlinepos (gFrame); frame::textframe (gFrame, parent); }
if (file::exists (path)) frame::image (gFrame, path); else frame::remove (gFrame);
if (item::defined (parent)) { // remove case cap // fit textframe textmodel::initialchar (parent, ipos, 0, 0); frame::fit (parent); frame::fit (parent); }
return 0; }


priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
create_subtextframe_f
document::find_frame
document::insert_macro
comet.CFrame.remove

static int remove(ItemRef itemRef)

Synonymous for delete_textframe.

static int select(
  ItemRef itemRef,
  int selectPage = 1,
  int replaceOrAdd = 1)

Select a document frame.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame to select
selectPage int 1 Scroll selected frame(s) into the visible area?

1 : Yes
0 : No
replaceOrAdd int 1 Remove or extend current frame selection?

1 : Select this frame only
0 : Extend existing selection
err_code = frame::select (itemRef
 		[, selectPage
 		[, replaceOrAdd]]);


priint:comet InDesign® Plug-Ins

static int rectangle(ItemRef)

Change the form of a frame to a square. For the size of the square the square surrounding the frame will be used. Size specfications are therefore not necessary. In order to change the size of a frame, please use frame::resize.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame reference
err_code = frame::rectangle (itemRef);


priint:comet InDesign® Plug-Ins, comet_pdf
resize

static int oval(ItemRef)

Change the form of a frame to an oval or a circle. For the size the square surrounding the frame will be used, size specifications are therefore not necessary. In order to change the size of the frame, please use frame::resize.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame reference
err_code = frame::oval (itemRef);


priint:comet InDesign® Plug-Ins
resize

static int polygon(ItemRef itemRef, int sides)

Change the form of a frame to a polygon. For the size the square surrounding the frame will be used, size specifications are therefore not necessary. In order to change the size of the frame, please use frame::resize.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame reference
sides int - Number of pages
err_code = frame::polygon (itemRef, 7);


priint:comet InDesign® Plug-Ins
resize

static int star(
  ItemRef itemRef,
  int edges,
  int inset)

Change the form of a frame to a star. For the size the square surrounding the frame will be used, size specifications are therefore not necessary. In order to change the size of the frame, please use frame::resize.

Name Type Default Description
Return int   0 or ErrorCode
itemRef ItemRef - Frame reference
edges int - Number of edges
inset int - Length of the edges
err_code = frame::star (itemRef, 13, 4);


priint:comet InDesign® Plug-Ins
resize

static int spline(ItemRef frameRef, ...)

Change the form of a frame to a potato. You will only get the potato form of course if the point specifications are correct, in the main you will get something unexpected - as least this is my experience.

Name Type Default Description
Return int   Fehlercode or 0
itemRef ItemRef - Frame reference
x, y float - Spline points. Following the specification of -1000000.1 three points follow for 'anchor point with continuing tangent (kCS)' - whatever that may be. Following the specification of -1000000.2 three points follow for 'anchor point with unsmooth curve point, left->right tangent discontinue (kCK) - ???'


priint:comet InDesign® Plug-Ins

static int fit_better(
  ItemRef frameRef,
  int refPoint = 0,
  float* = 0,
  float* = 0,
  int constantWidth = 0,
  float method = 0.0)

Adjust a frame to the size of its contents. Frames of one lined texts are fitted to a new width too from InDesign® by default. To suppress this behavior, set constantWidth to 1.

Here you can find a reference document containing a complete description of the functionality and a lot of examples.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame reference
refPoint int kRefPointTopLeft Ignored for inline frames. In which case the bottom right corner is used always.

Which corner of the frame should be pinned? Text frames with more an one line of text can change their height only.

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight

To fit frames to the contained image, use the frame::fit_image function with method 3.
width float* 0 New width of the frame, return value
height float* 0 New height of the frame, return value
constantWidth int 0 Shall one line texts keep its frame width
0 : No
otherwise : Yes
method float 0.0 Behavior in case of rotated images.

<= -1.0 : InDesign® standard behavior. Frames are fitted to the INNER box of the image

otherwise : Frames are fitted to the bounding box of the rotated image.
#include "internal/types.h"

Fit the frame itemRef to its content. Following the call in w and h the new width or height of the frame.

float	w, h;
ItemRef	itemRef = ... 
err_code = frame::fit_better (itemRef, kRefPointTopLeft, &w, &h);

seit v3.4 R5220 (3. Mar 20124)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.fit
fit
fit_image

static int fit(
  ItemRef frameRef,
  int refPoint = 0,
  float* newwidth = 0,
  float* newheight = 0,
  int constantWidth = 0,
  float precision = 0.0)

Adjust a frame and all its sub-frames to the size of its contents. Frames of one lined texts are fitted to a new width too from InDesign® by default. To suppress this behavior, set constantWidth to 1.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame reference
refPoint int kRefPointTopLeft Ignored for inline frames. In this case the bottom right corner is used always.

Which corner of the origin frame should be pinned? Text frames with more an one line of text can change their height only.

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight

To fit frames to the contained image, use the frame::fit_image function with method 3.
width float* 0 New width of the frame, return value
height float* 0 New height of the frame, return value
constantWidth int 0 Shall one line texts keep its frame width
0 : No
otherwise : Yes
precision float 0.0 How close should the frame match the content? Only used for text frames. < 0.0001 : Use the InDesign® standard algorithm
otherwise : Use the Comet algorithm.
#include "internal/types.h"

Fit the frame itemRef to its content. Following the call in w and h the new width or height of the frame.

float	w, h;
ItemRef	itemRef = ... 
err_code = frame::fit (itemRef, kRefPointTopLeft, &w, &h);

ParameterconstantWidth since version 1.3.5, R 236
New parameters since version 1.4, R142, 4. Aug. 2006, refPoint added. That moves the rest of the parameters.
Parameter precision seit v3.3 R3728, 30.04.2013

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.fit
fit_better
fit_image
item::fitframe

static int fit_image(
  ItemRef frameRef,
  int method,
  int data = 0,
  float size = 0.0,
  float maxScale = 1.0)

Fitting an image and its frame together. In addition to the native InDesign® methods, customized priint:comet methods are supported.

[method = 0] The image is centered and scaled so that the frame is completely filled. If the frame and the image have different proportions, parts of the image will become invisible in one dimension. In the following screenshots you can see two (rotated) image frames. In both frames, fit_image (yourFrame, 0, 1); places and scales the image as shown in the third figure.

  

The default method of InDesign® (method = 0, data = -1) sometimes produces errors here. We have therefore implemented our own method in which this error does not occur. To do this, set the parameter data to a value not equal to -1.

In the following three screenshots you can see an example of the different results of InDesign and the priint:comet method. From a rotated image (first screenshot), InDesign® produces what you see in Figure 2 : The images completely covers the frame. But it is much too large. In figure 3 you can see the result of fit_image with the minimum required image size:

  

[method = 1] The image is centered and scaled so that it is fully visible. The image proportions are preserved. Here is a before/after example:

 

The results that InDesign® produces here are (at least for us) not always predictable. We have therefore implemented our own method in which these errors do not occur. For this set the parameter data to a value not equal to -1.

In the following three figures you can see an example of the different results of InDesign and priint:comet method. From a rotated image (image 1), InDesign® produces what you see in image 2. The image does not fit in any way! Figure 3 shows the result of fit_image with the maximum possible image size:

  

[method = 2] The image is scaled in both dimensions so that it completely fills the frame. If the image and frame have different proportions, the image will be distorted. Here is an example:

 

The default method of InDesign® (method = 1, data = -1) sometimes produces errors here. We have therefore implemented our own method in which this error does not occur. To do this, set the parameter data to a value other than -1.

In the following three screenshots you can see an example: From a rotated image (image 1) InDesign® produces this, what you see in image 2 - oops, what's that?! Where does the distortion come from all of a sudden? And what value does it actually have? In Figure 3 you can see the result of fit_image with the minimum required image size:

  

[method = 3] Fit the frame to the image content. The position, proportions and rotation of the frame are adjusted to the position, proportions and rotation of the image, if necessary. If the frame rotation should not be changed, use function frame::fit_better.

Here is an example of a frame with a rotated image (image 1 and 2). In image 3 you can see the result of frame::fit_better:

  

The method does not correspond to the InDesign® method Object -> Fit -> Fit frame to content! - the result corresponds to our implementation of Fill Frame Proportionally:

 

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid Graphic Frame
method int - Fitting method. One of:

0 : Fill frame proportionally: The image is centered and proportionately scaled to completely fill the frame. If the image and the frame have different proportions, parts of the image become invisible in one dimension.

1 : Fit content proportionally The image is centered and proportionately scaled so that it is completely visible. If the image and the frame have different proportions, white space is visible in one dimension.

2 : Fit content to frame. The image is centered and scaled in both directions so that it is completely visible. If the image and the frame have different proportions, the image will be distorted in one dimension.

3 : Fit frame to content. Anpassen des Rahmens an die Bildgröße.

4 : Center content in frame

5 : Use the priint:comet image placements
data int method 0,1,2 : -1
method 5 : 5
Additional information about the placement of the image

Methods 0, 1, 2:
-1 : Built-in InDesign® method
otherwise : priint:comet method
Using comet_pdf the parameter is ignored for obvious reasons.

Methods 3, 4: Parameter is ignored

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 0.0 Image placement size of bounding box for image, see here

For obvious reasons, this information is ignored by the methods 0 - 4.
maxScale float 1.0 Maximum image scaling (1.0 means 100.0%)

-1.0 : Any scaling > 0.0 allwoed

For obvious reasons, this information is ignored by the methods 0 - 4.
#include "internal/types.h"

Version 3.1, R 1928 11. Juni 2010
Parameter maxScale seit v4.0.5 R13604, 12. Sep 2016

priint:comet InDesign® Plug-Ins, comet_pdf

fit_better
is_graphicframe
set_fitting_options
comet.CFrame.fitImage

static int set_fitting_options(
  ItemRef frameRef,
  int refPoint,
  int fitting,
  Rect crop = 0,
  int autoFit = 0,
  int reApply = 1)

Set the frames fitting options. Supported since CS4.

Name Type Default Description
Return int   0 or ErrorCode -1199 : Versions prior CS4
frameRef ItemRef - Valid image frame
refPoint int - Reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
fitting int - Fitting method

0 : no fitting
1 : Fit content to frame
2 : Fit content proportionally
3 : Fill frame proportionally
crop Rect 0 Crop amounts (values > 0.0) or distances (values < 0.0) to the respective side in points.

0 or (0.0, 0.0, 0.0, 0.0) : No crop or spacing

Please note that InDesign includes the current image scaling in the calculation of the values. So a distance of -10.0pt will be only -5.0pt with a current image scaling of 50%!

autoFit int 0 Fit automatically? Ignored in CS4.
1 : Yes
0 : No
reApply int 1 Ignored in CS4, in this case changes always applied.

1 : Yes
0 : No
#include "internal/types.h"
#include "internal/types.h"
int main () { Rect crop = rect::alloc (12.0, 13.0, 14.0, 15.0);
frame::set_fitting_options (gFrame, kRefPointLeftCenter, 2, crop, 1, 1); return 0; }

Version 3.2.1 R2330, 7.März 2011
CS4-Suppport since Version 3.2.2 R2390, 14.04.2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_fitting_options(
  ItemRef frameRef,
  int* refPoint = 0,
  int* fitting = 0,
  Rect crop = 0,
  int* autoFit = 0)

Get fitting options of a given frame. Supported since CS4.

Name Type Default Description
Return int   0 or ErrorCode
-1199 : Versions prior CS4
frameRef ItemRef - Valid frame
refPoint int* 0 On successful return the address contains the reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
fitting int* 0 On successful return the address contains the fitting method

0 : Ohne
1 : Inhalt an Rahmen anpassen
2 : Inhalt proportional anpassen
3 : Rahmen proportional füllen
crop Rect 0 On successful return the rectangle contains the crop amounts
autoFit int* 0 On successful return the address contains the autoFit value. Since this behavior was invoked in CS5, versions prior CS5 always returning 0 here.
#include "internal/types.h"
#include "internal/types.h"
int main () { int refPoint; int fitting; Rect crop = rect::alloc (); int autoFit;
frame::get_fitting_options (gFrame, &refPoint, &fitting, crop, &autoFit); wlog ("", "Frame %d\n", item::getint (gFrame)); wlog ("", " %d %d [%f, %f, %f, %f], %d\n",   refPoint,   fitting,   rect::left (crop),   rect::top (crop),   rect::right (crop),   rect::bottom (crop),   autoFit); return 0; }

Version 3.2.1 R2330, 7.März 2011
CS4-Suppport since Version 3.2.2 R2390, 14.04.2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int clear_fitting_options(ItemRef frameRef)

Clear the frame fitting options of a given frame. Supported since CS5. Under CS4 you may use set_fitting_options with fitting set to 0 instead.

Name Type Default Description
Return int   0 oder Fehlercode
-1199 : Versionen vor CS5
frameRef ItemRef - Gültiger Bildrahmen
int main ()
{
    frame::clear_fitting_options (gFrame);
    return 0;
}

Version 3.2.1 R2330, 7.März 2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int apply_fitting_options(ItemRef frameRef)

Apply the frame fitting options of a given frame. Supported since CS4.

Name Type Default Description
Return int   0 oder Fehlercode
-1199 : Versionen vor CS4
frameRef ItemRef - Gültiger Bildrahmen
int main ()
{
    frame::apply_fitting_options (gFrame);
    return 0;
}

Version 3.2.1 R2330, 7.März 2011
CS4-Suppport since Version 3.2.2 R2390, 14.04.2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int insert(
  ItemRef frameRef,
  char* tt,
  int position = 0,
  int auto_load = 1,
  int flags = 0)

Inserting the text into a frame. The text can be tagged, then it can be inserted in format. text.h is necessary for the method :
#include "internal/text.h" }

The call frame::insert (gFrame, "abc", textmodel::start ()); inserts the text "abc" right before the current placeholder. But in different to textmodel::insert ("abc", 0); this text does not contain to the current placeholder. With frame::insert you leave the protected textmodels placeholder area definitly. Be aware that text inserted out side the placeholder may inserted as often as the script is called!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame in which the text is to be inserted
tt String or char* - Text to be inserted (can also be TaggedText)
position int 0 text-relative insert position

< 0 append
auto_load int on Should the text placeholders in the TaggedText be activated?
flags int 0 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, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • 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.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \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.

Insert at position 2

frame::insert (frameRef, text, 2)

Append

frame::insert (frameRef, text, -1)

Parameter flags since v4.0.5 R10000, 07. Feb 2016
Table check since v4.0.5 R21000 v1.0

priint:comet InDesign® Plug-Ins, comet_pdf
textmodel::insert
prefs::set_logstate
comet.CFrame.setText

static int rinsert(
  ItemRef frameRef,
  char* tt,
  int position = 0,
  int auto_load = 1,
  int flags = 0)

Recursive safe inserting text in a frame.

This function works like frame::insert but it is 'revursive safe' for self calling placeholders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins

insert
comet.CFrame.setText

static int append(
  ItemRef frameRef,
  char* tt,
  int auto_load = 1,
  int flags = 0)

Append text to a the text of a frame. The text can be tagged, then it will be inserted in format.
text.h is necessary for the method : #include "internal/text.h"

In linked text frames, the text is append to the last frame of the text chainframeRef.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame into which the text is to be inserted
String or char* tt - text to be inserted (can also be TaggedText)
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 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, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • 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.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \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.
frame::append (frameRef, text, 0);

Parameter flags since v4.0.5 R10000, 07. Feb 2016
Table check since v4.0.5 R21000 v3.0

priint:comet InDesign® Plug-Ins, comet_pdf

textmodel::append
prefs::set_logstate
comet.CFrame.setText

static int rappend(
  ItemRef frameRef,
  char* tt,
  int auto_load = 1,
  int flags = 0)

Recursive safe appending text to a frame.

This function works like frame::append but it is 'revursive safe' for self calling placeholders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

append
prefs::set_logstate
comet.CFrame.setText

static int replace(
  ItemRef frameRef,
  char* tt,
  int position = 0,
  int delete_len = -1,
  int auto_load = 1,
  int flags = 0)

Replace text within a frame. In actions of placeholders (load, sync, etc.), position and length are relative to the placeholder. If a placeholder script deletes the entire content of the placeholder, an invisible space (<0x200B>) is inserted as placeholder text.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame in which the text is to be inserted
text String or char* - Text to be inserted (can also be TaggedText)
position int 0 Insertion position. In placeholder scripts, the text position is relative to the placeholder.

kEnd : End of text, in placeholder scripts the end of the placeholder
kSelection
delete_len int kEnd Number of characters to be deleted

kEnd : End of text, in placeholder scripts up to the end of the placeholder
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 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, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • 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.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \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.
#include "internal/text.h"

The following placeholder scripts replaces the current placeholder text by a text containing a table. Because it may be hard to find out the numbers of characters inserted into the document by a given string (TaggedText, Unicode characters, ...) the action is made in three single steps:

  - Replace the placeholder text by the text before the table
  - Insert table
  - Append the remaining text

Comment Dont worry about the missing %!TT in the examples. The tag <CharStyle> is handled by the plugins automatically, see see to learn more.

//
// Script 1 : Using textmodel::replace and textmodel::insert
//
#include "internal/types.h"
#include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
textmodel::replace ("<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
textmodel::insert ("XXX", kEnd);
return 0;
}
// // Script 2: Using frame::replace and frame::insert // You get the same result as with script 1. // But take care to use the current placeholder // positions and lengths. // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace (gFrame, "<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start ());
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());
return 0; }
// // Script 3 : Not working! // Using frame::replace_all instead of frame::replace, the script will do wrong things: // The current placeholder is replaced by the trailing text - but the placeholder is removed. // Inserting the table at kEnd therfore now means : At the end of the whole text! // Because you have no placeholder, textmodel::start and textmodel::length are both 0. // The text XXX therefor is inserted at the beginning of the text :-( // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start (), textmodel::length ());
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());
return 0; }
// // Script 4 : Panel script // The complete text of the current frame is replaced! // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", kEnd);
return 0; }

Replace position 2-5

frame::replace (frameRef, text, 2, 3);

Replace position 2

frame::replace (frameRef, text, 2, kEnd);

Replace everything

frame::replace (frameRef, text);

Like frame::append

frame::replace (frameRef, text, kEnd);

Like frame::insert

frame::replace (frameRef, text, 2, 0);

Replace the current text selection

frame::replace (frameRef, text, kSelection, 0);

Parameter flags since v4.0.5 R10000, 07. Feb 2016
Table check since v4.0.5 R21000 v3.0

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

textmodel::replace
prefs::set_logstate
comet.CFrame.setText

static int rreplace(
  ItemRef frameRef,
  char* tt,
  int position = 0,
  int delete_len = -1,
  int auto_load = 1,
  int flags = 0)

Recursive safe replacing text in a frame.

This function works like frame::replace but it is 'revursive safe' for self calling placeholders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

replace
comet.CFrame.setText

static int replace_all(
  ItemRef frameRef,
  char* tt,
  int position = 0,
  int delete_len = -1,
  int auto_load = 1,
  int flags = 0)

Replace text in a frame. If the text contains placeholders, these placeholder may be removed by replace_all. In contrast to frame::replace replace_all removes the current placeholder if (and only if) you replace the entire text of the current placeholder in a placeholder script (load, sync, ...).

frame::replace (gFrame, "aa", textmodel::start (), textmodel::length ()) replaces the content of the current placeholder by "aa".

frame::replace_all (gFrame, "aa", textmodel::start (), textmodel::length ()) replaces the current placeholder by the (unlinked) text "aa".

text.h is necessary for the method : #include "internal/text.h" .

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame in which the text is to be inserted
String or char* tt - text to be inserted (can also be TaggedText)
position int 0 text-relative insert position or kEnd, kSelection
delete_len int 0 Number of the character or kEnd to be deleted
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 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, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • 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.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \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.
#include "internal/text.h"

The following placeholder scripts replaces the current placeholder text by a text containing a table. Because it may be hard to find out the numbers of characters inserted into the document by a given string (TaggedText, Unicode characters, ...) the action is made in three single steps:

  - Replace the placeholder text by the text before the table
  - Insert table
  - Append the remaining text

Comment Dont worry about the missing %!TT in the examples. The tag <CharStyle> is handled by the plugins automatically, see see to learn more.

//
// Script 1 : Using textmodel::replace and textmodel::insert
//
#include "internal/types.h"
#include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
textmodel::replace ("<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
textmodel::insert ("XXX", kEnd);
return 0;
}
// // Script 2: Using frame::replace and frame::insert // You get the same result as with script 1. // But take care to use the current placeholder // positions and lengths. // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace (gFrame, "<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start ());
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());
return 0; }
// // Script 3 : Not working! // Using frame::replace_all instead of frame::replace, the script will do wrong things: // The current placeholder is replaced by the trailing text - but the placeholder is removed. // Inserting the table at kEnd therfore now means : At the end of the whole text! // Because you have no placeholder, textmodel::start and textmodel::length are both 0. // The text XXX therefor is inserted at the beginning of the text :-( // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start (), textmodel::length ());
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());
return 0; }
// // Script 4 : Panel script // The complete text of the current frame is replaced! // #include "internal/types.h" #include "internal/text.h"
int main () { int T = table::alloc ();
if (!T) return;
frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);
table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0); table::release (T);
frame::insert (gFrame, "XXX", kEnd);
return 0; }

Parameter flags since v4.0.5 R10000, 07. Feb 2016
Table check since v4.0.5 R21000 v3.0

priint:comet InDesign® Plug-Ins, comet_pdf

textmodel::replace
frame::replace
prefs::set_logstate
comet.CFrame.setText

static int excel_import(
  ItemRef frameRef,
  char* path,
  int pos,
  int delLength = 0)

Insert the Excel table into the text. The specified frame must be a text frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame, in which the table is to be inserted
path String or char* - Complete path for the Excel file. Otherwise Word files or images may be located at this point.
pos int - Text position for inserting the table

>= 0 Text position
> Text length : append
kEnd : Append
kSelection : Current cursor position
delLength int 0 Number of characters to be deleted
kEnd Delete to end of text
#include "internal/text.h"
err_code = frame::excel_import (frame, path, pos, delLength);

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins
textmodel::excel_import

static int excel_update(
  ItemRef frameRef,
  char* path,
  int tindex,
  int min_row = 0,
  int max_row = -1,
  int min_col = 0,
  int max_col = -1,
  int pos = -1,
  int delLength = 0)

Update a table of the text in a text table. As a basis for the updating, the specified Excel table is used. If the new table is larger, the appropriate lines and columns are added. For the formatting of newly set up lines and columns, the foregoing lines and columns are used. The foramatting of the original table can for the moment be assumed for the new lines and columns.
The target table is defined via the 0-based index. If no original table is in existance, the table is completely inserted once again. In this case, all formattings of the original table can be assumed. The specified frame must be a text frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame, which should be inserted or updated
path String or char* - Complete path to an Excel file.
tindex int - 0-based table index
min_row int 0 Update after this line
max_row int kEnd Only update to this line
kEnd Update to the last line
min_col int 0 Update from this column
max_col int kEnd Only update to this column
kEnd Update to the last column
pos int kEnd If the table does yet exist, a new table will be set up at this text position.
>= 0 : Text position
> Text length : Append kEnd : Append
kSelection : Current cursor position
delLength int 0 Number of the characters to be deleted
kEnd Delete to the end of text
#include "internal/text.h"
err_code = frame::excel_update (frame, path, index, pos, delLength);

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins
textmodel::excel_update

static int overset(
  ItemRef fm,
  int fullChain = -1,
  ItemRef lastFrameUsed = 0)

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 define the overset of textframes or texts.

Name Type Default Description
Return int   0 : no overset or error
Return int   otherwise : text overset The value is not the number of invisible letters.
fm ItemRef 0 If no frame is specified, the current text model will be used as a test. If a frame is specified, it will be attempted to test this text.
fullChain int kFullChain Shall I check the complete text frame chain?
kFullChain : Check complete chain
0 : Check the given frame itself
lastFrameUsed ItemRef 0 Only with comet_pdf and fullChain == -1! After successful execution of the function, the parameter contains a reference to the last frame of the chain that still contains text.

0 : Ignore value
otherwise : Allocated ItemRef
#include "internal/text.h"
int 	k = frame::overset (fm );

Version 1.1.4
kFullChain since version 1.4 R310, 9. Feb. 2007
Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
textmodel::overset
comet.CFrame.hasOverset

static int link(ItemRef from, ItemRef to)

Connect two text frames so that the content of the first frame with continue into the second frame where there is an excess.

Name Type Default Description
Return int   0 or ErrorCode
from ItemRef - Text frame the text of which should be continued where there is an excess
to ItemRef - Text frame which should take up the overflow text

0 : since v4.1.6 R26111 and not in comet_pdf Release text chain from from.
err_code = frame::link (frameRef_From, frameRef_to);

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_link(ItemRef frameRef, ItemRef toRef)

Find the next text frame in a text frame chain.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - valid frame reference
toRef ItemRef 0 With item::alloc created pointer to the resulting frame. After successful return and an empty toRef (!is_valid), the frame does not have a successor.
#include "internal/text.h"
#include "internal/types.h"

Apply a vertical justification for the current script frame - but not if it is the last frame of a chain of text frames. But, if it is a last frame, reset all spaces before the paragraphs in this frame.

#include "internal/text.h"
#include "internal/types.h"
int main() { ItemRef succ = item::alloc (); int succRes = frame::get_link (gFrame, succ); int tpos = frame::get_textpos (gFrame);
if (succRes == 0 && !frame::is_valid (succ)) { textmodel::justify_reset (gFrame, tpos); }
textmodel::justify (gFrame, 0, kFrameEnd);
return 0; }

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_textpos(
  ItemRef frameRef,
  int* len,
  Table tableIn = 0,
  int* firstRow = 0,
  Table tableOut = 0,
  int* lastRow = 0)

Find the position of the text shown in a frame of chained text frame list.

Name Type Default Description
Return int   text position
-1 : error
frameRef ItemRef - valid frame reference
len int* 0 length of text shown in the frame
tableIn Table 0 If the text starts with a continued table, the variable will contain this table after successful return.

0 : Ignore continued tables
firstRow int* 0 If the text starts with a continued table, the variable will contain the first visible body row of this table.

0 : Ignore continued tables
tableOut Table 0 If the text ends with an uncompleted table, the variable will contain this table after successful return.

0 : Ignore uncompleted tables
lastRow int* 0 If the text ends with an uncompleted table, the variable will contain the last visible body row of this table.

0 : Ignore uncompleted tables
#include "internal/text.h"

Apply a vertical justification for the current script frame - but not if it is the last frame of a chain of text frames. But, if it is a last frame, reset all spaces before the paragraphs in this frame.

#include "internal/text.h"
#include "internal/types.h"
int main() { ItemRef succ = item::alloc (); int succRes = frame::get_link (gFrame, succ); int tpos = frame::get_textpos (gFrame);
if (succRes == 0 && !frame::is_valid (succ)) { textmodel::justify_reset (gFrame, tpos); }
textmodel::justify (gFrame, 0, kFrameEnd);
return 0; }

Version 2.1, R1401, 29.06.2009
tableIn, firstRow, tableOut, lastRow since v3.4 R5200, 25. Feb 2014

priint:comet InDesign® Plug-Ins

static int color(
  ItemRef frameRef,
  char* colorName,
  int joinType = -1,
  int capType = -1,
  float tint = -1.0)

Set the fill color of the frame. The color is given via a defined swatch color.

For historical reasons, the function can also be used to define the line ends (join and cap type) of the frame contour. If the background color is to remain unchanged in this case, enter the value 0 or "" in the parameter colorName.
  JoinType
0 Mitter
1 Round
2 Bevel
  CapType
0 Button
1 Round
2 Square

Name Type Default Description
Return int   0 or Error Code
frameRef ItemRef - Valid frame
colorName String oder char* - New fill color of the frame

0 or "" : Leave unchanged
Otherwise : Valid name of Swatches panel or a Default Color
joinType int -1 How do the lines of the frame contour meet?

-1 : Leave unchanged
Otherwise : see above table
capType int -1 How do the lines of the contour end?

-1 : Leave unchanged
Otherwise : see above table
tint float -1.0 Degree of color coverage (0.0-100.0)

-1.0 : Leave unchanged

Parameter joinType and capType since v1.0.20
Parameter tint since v3.3 R3112, 12. Oct. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CPageItem.setFillColor

static int color_rgb(
  ItemRef frameRef,
  int r,
  int g,
  int b,
  int joinType = -1,
  int capType = -1)

Fill the frame in the specified color. The color is defined via its RGB values.

For historical reasons, the function can also be used to define the line ends (join and cap type) of the frame contour. If the background color is to remain unchanged in this case, enter the -1 for the each of the rgb values.
  JoinType
0 Mitter
1 Round
2 Bevel
  CapType
0 Button
1 Round
2 Square

Name Type Default Description
Return int   0 or Error Code
frameRef ItemRef - Valid frame
r, g, b int, int, int - RGB values of the fill color in the range 0-255

-1, -1, -1 : Leave unchanged
joinType int -1 How do the lines of the frame contour meet?

-1 : Leave unchanged
Otherwise : see above table
capType int -1 How do the lines of the contour end?

-1 : Leave unchanged
Otherwise : see above table
tint float -1.0 Degree of color coverage (0.0-100.0)

-1.0 : Leave unchanged

Parameter joinType and capType since v1.0.20
Parameter tint since v3.3 R3112, 12. Oct. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CPageItem.setFillColor

static int color_cmyk(
  ItemRef frameRef,
  float c,
  float m,
  float y,
  float k,
  int joinType = -1,
  int capType = -1)

Fill the frame in the specified color. The color is defined via its RGB values.

For historical reasons, the function can also be used to define the line ends (join and cap type) of the frame contour. If the background color is to remain unchanged in this case, enter the -1 for the each of the rgb values.
  JoinType
0 Mitter
1 Round
2 Bevel
  CapType
0 Button
1 Round
2 Square

Name Type Default Description
Return int   0 or Error Code
frameRef ItemRef - Valid frame
c, m, y, k float, float, float, float - CMYK values of the fill color in the range 0.0 - 1.0

-1.0, -1.0, -1.0, -1.0 : Leave unchanged
joinType int -1 How do the lines of the frame contour meet?

-1 : Leave unchanged
Otherwise : see above table
capType int -1 How do the lines of the contour end?

-1 : Leave unchanged
Otherwise : see above table
tint float -1.0 Degree of color coverage (0.0-100.0)

-1.0 : Leave unchanged

Parameter joinType and capType since v1.0.20
Parameter tint since v3.3 R3112, 12. Oct. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CPageItem.setFillColor

static int opacity(
  ItemRef frameRef,
  float opacity,
  int blendMode = -1,
  int overPrint = -1,
  int opacType = 0)

Change the transparency of a frame. types.h is necessary for the method : #include "internal/types.h" If the background color is defined with RGB values and not by the name of a color panel record, the opacity parameter has no effect.

The following table gives the possible values, with which the frame contents can be connected with the background:
Value Method
0 Normal
1 Multiply
2 Screen
3 Overlay
4 SoftLight
5 HardLight
6 ColorDodge
7 ColorBurn
8 Darken
9 Lighten
10 Difference
11 Exclusion
12 Hue
13 Saturation
14 Color
15 Luminosity
16 NonZeroOverprint

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
opacity float - Transparency in % (0.0 - 100.0)

-1.0 : Keep untouched
blendMode int -1 Blend with the background, see above table

-1 : Keep untouched
overPrint int -1 Over print background

-1 : Keep untouched
opacType int kBlendingBasic What transperency do you mean?

kBlendingBasic : all
kBlendingStroke : contour
kBlendingFill : fill
kBlendingContent : content
#include "internal/types.h"
err_code = frame::opacity (frameRef, opacity [, blendMode]);

Since v4.05, 26. Nov 2015. Please use frame::set_blending instead.
Parameter overPrint since Version 1.0.20
Parameter opacType since v3.3.1 R3956, 27. Jun 2013

priint:comet InDesign® Plug-Ins, comet_pdf

get_opacity
set_blending
get_blending
set_overprint
get_overprint

static int set_blending(
  ItemRef frameRef,
  int what,
  float opacity,
  int blendMode = -1,
  int isolation = -1,
  int knockout = -1)

Set opacity and blendings of frames. The functions sets opacity, blendmode, knockout and isolation of frames and can applied to strokes, fills, and contents separately.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
what int kBlendingBasic Destination in frame

kBlendingBasic : all
kBlendingStroke : Contour (stroke)
kBlendingFill : Fill
kBlendingContent : Content
opacity float - Opacity in % (0.0 - 100.0)

-1.0 : Keep untouched
blendMode int -1 Blend mode
-1 : Keep untouched
For possible values see here.
isolation int -1 Isolate blend mode?

-1 : Keep untouched

Not used in comet_pdf.
knockout int -1 Knockout group?

-1 : Keep untouched

Not used in comet_pdf.
#include "internal/types.h"
#include "internal/types.h"
char * what2str (int what, char * ws) { if (what == kBlendingBasic) strcpy (ws, "Basic"); else if (what == kBlendingStroke) strcpy (ws, "Stroke"); else if (what == kBlendingFill) strcpy (ws, "Fill"); else if (what == kBlendingContent) strcpy (ws, "Content"); else sprintf (ws, "Blend %d", what);
return ws; }
int w_blendings (ItemRef fr, char * mess) { float opac; int blendmode; int isolation; int knockout; int what; char ws[255];
wlog ("", "Frame %d, %s\n", item::getint (gFrame), mess);
for (what = kBlendingBasic; what <= kBlendingContent; what++) { opac = frame::get_blending (gFrame, what, &blendmode, &isolation, &knockout); wlog ("", " %s\t%f\t%d\t%d\t%d\n",   what2str (what, ws),   opac,   blendmode,   isolation,   knockout); }
wlog ("", "\n"); return 0; }
int change_blending (ItemRef fr, int what, float opacity, int blendmode, int isolation, int knockout) { int result = frame::set_blending (fr, what, opacity, blendmode, isolation, knockout); char mess [512]; char ws [255];
sprintf (mess, "%s changed to (%f, %d, %d, %d)",   what2str (what, ws),   opacity,   blendmode,   isolation,   knockout); w_blendings (fr, mess); return result; }
int w_overprints (ItemRef fr, char * mess) { wlog ("", "%s :: frame %d overprints : fill %d, stroke %d, gap %d\n",   mess,   item::getint (fr),   frame::get_overprint (fr, kOverprintFill),   frame::get_overprint (fr, kOverprintStroke),   frame::get_overprint (fr, kOverprintGap)); return 0; }
int main () { w_blendings (gFrame, "Original");
change_blending (gFrame, kBlendingStroke, 30.0, 3, 1, 1); change_blending (gFrame, kBlendingFill, 40.0, 4, 1, 0); change_blending (gFrame, kBlendingContent, 50.0, 5, 1, 0); change_blending (gFrame, kBlendingBasic, 60.0, 6, 1, 0);
w_overprints (gFrame, "Before"); frame::set_overprint (gFrame, kOverprintFill, 0); frame::set_overprint (gFrame, kOverprintStroke, 1); frame::set_overprint (gFrame, kOverprintGap, 1); w_overprints (gFrame, "After");
return 0; }

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_overprint
get_overprint

static float get_blending(
  ItemRef frameRef,
  int what,
  int* blendMode = 0,
  int* isolation = 0,
  int* knockout = 0)

Get opacity and blend mode of frames.

Name Type Default Description
Return float   Opacity in % (0.0 - 100.0)

-1.0 : Error
frameRef ItemRef - Valid frame
what int kBlendingBasic Destination in frame

kBlendingBasic : all
kBlendingStroke : Contour (stroke)
kBlendingFill : Fill
kBlendingContent : Content
blendMode int* 0 Blend mode
For possible values see here.
isolation int* 0 Blend mode isolated?

0 : No
1 : Yes

Not supported by comet_pdf.
knockout int* 0 Is Knockout group?

0 : No
1 : Yes

Not used in comet_pdf.
#include "internal/types.h"

see set_blending

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_overprint
get_overprint

static int set_overprint(
  ItemRef frameRef,
  int what,
  int overprint)

Set the overprint of frames. You may set overprinting for frame fill, stroke and gaps of strokes separately.

Overprints are not implemented for comet_pdf for now. The function has no effect therefor in the renderer.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
what int kOverprintBasic Part of frame to change?

0 kOverprintBasic : Fill, contour, and gaps of contour
1 kOverprintStroke : Contour (stroke)
2 kOverprintFill : Fill
3 kOverprintGap : Gaps of contour
overprint int - Do overprint

0 : No
1 : Yes
#include "internal/types.h"

See get_overprint

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_blending
get_overprint
comet.CFrame.setOverprint

static int get_overprint(ItemRef frameRef, int what)

Get the overprint of a frame.

Overprints are not implemented for comet_pdf for now. The function has no effect therefor in the renderer.

Name Type Default Description
Return int   Will the given frame parts be overprinted??

0 : No
1 : Yes
-1 : Error or property not available
frameRef ItemRef - Valid frame
what int - Part of frame to ask for.

1 kOverprintStroke : Contour (stroke)
2 kOverprintFill : Fill
3 kOverprintGap : Gaps in the contour (stroke)
otherwise : Error (-1)
#include "internal/types.h"

See set_overprint

v4.0.5 R9720, 4. Dez 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_blending
set_overprint
comet.CFrame.getOverprint

static int stroke(
  ItemRef frameRef,
  char* colorName= "",
  float width = -1.0,
  float tint = -1.0,
  int overPrint = -1,
  int lineStyle = -1,
  char* gapColor = "",
  float gapTint = -1.0,
  int gapOverPrint = -1,
  int lineAlign = -1,
  float miter = -1.0)

Definition of the frame contour. The definition of the color is made by the name of a defined swatch. The following line types can be used:
LineStyle Name Availability
0 SolidPath  
1 DashedPath  
2 CannedDash4x4  
3 CannedDash3x2  
4 CannedDot  
5 SingleWavy since InDesign® CS
6 StraightHash since InDesign® CS
7 RightSlantHash since InDesign® CS
8 LeftSlantHash since InDesign® CS
9 WhiteDiamond since InDesign® CS
10 JapaneseDots since InDesign® CS
11 ThinThin  
12 ThinThick  
13 ThickThin  
14 ThickThick  
15 ThinThickThin  
16 ThickThinThick  
17 Triple ab InDesign® CS
18 TableStripe ab InDesign® CS

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
colorName String or char* - Name of a color or base color

0 or "" : Leave color untouched
width float -1.0 Weight of stroke in points

-1.0 ignore
tint float -1 Color tint in % (0.0-100.0)

-1.0 ignore
overPrint int -1 Overprint background?

1 yes
0 no
-1 ignore
lineStyle int -1 See table above

-1 ignore
gapColor String or char* "" Color to fill the gaps of the frame or base color

0 or "" : ignore
gapTint float -1.0 Color tint of the gaps in the frame in % (0.0-100.0)

-1.0 ignore
gapOverprint int -1 Overprint gap background?

1yes
0 no
-1 ignore
alignment int -1 Where should the contours be added?

-1 ignore
0 in the middle
1 interior
2 outside
miter float -1.0 Line miter
-1.0 ignore
otherwise a value from the range 1.0 - 500.0
main ()
{
    frame::stroke (
     	gFrame,
     	"Lime",	// Light green
     	20.0,	// Strength
     	50.0,	// Transparency
     	-1,		// Overprint
     	5		// Line style
     	);
}

The parameters from tint are available from version 1.0.20.
You can leave the color untouched since Version 2.1 R684, 24.04.2008

priint:comet InDesign® Plug-Ins, comet_pdf

static int stroke_rgb(
  ItemRef frameRef,
  int r,
  int g,
  int b,
  float width = -1.0,
  int overPrint = -1,
  int lineStyle = -1,
  int gapR = 0,
  int gapG = 0,
  int gapB = 0,
  int gapOverPrint = -1,
  int lineAlign = -1,
  float miter = -1.0)

Definition of the frame contour with RGB color. The color of the contour is defined via the RGB components (0-255) of the color.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
r, g, b int, int, int - Color values each 0-255

-1, -1, -1 : ignore
width float -1.0 Weight of stroke in points

-1.0 ignore
overPrint int -1 1 Overprint background
0 Do not overprint background
-1 ignore
lineStyle int -1 See above table

-1 ignore
gapR, gapG, gapB int, int, int -1, -1, -1 Color value of the "holes" in the stroke, each 0-255

-1, -1, -1 : ignore
 
gapOverPrint int -1 1 Overprint background of stroke gaps
0 Do not overprint
-1 ignore
alignment int -1 Where should the contour be applied?

-1 ignore
0 in the middle
1 interior
2 outside
miter float -1.0 Line miter
-1.0 ignore
otherwise a value from the range 1.0 - 500.0
err_code = frame::stroke (frameRef, r, g, b [, width]);

The parameters from tint are available from version 1.0.20.

priint:comet InDesign® Plug-Ins, comet_pdf

static int stroke_cmyk(
  ItemRef frameRef,
  float c,
  float m,
  float y,
  float k,
  float width = -1.0,
  int overPrint = -1,
  int lineStyle = -1,
  float gapC = 0.0,
  float gapM = 0.0,
  float gapY = 0.0,
  float gapK = 0.0,
  int gapOverPrint = -1,
  int lineAlign = -1,
  float miter = -1.0)

Definition of the frame contour with CMYK color. The color of the outline is defined via the CMYK components (0.0 -1.0) of the color.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
c, m, y, k float, float, float, float - Color values, each in range 0.0 - 1.0

-1.0, -1.0, -1.0, -1.0 : Farbe ignorieren
width float -1.0 Weight of stroke in points

-1.0 ignore
overPrint int -1 1 Overprint background
0 Do not overprint background
-1 ignore
lineStyle int -1 See above table

-1 ignore
gapC, gapM, gapY, gapK float, float, float, float -1.0, -1.0, -1.0, -1.0 Color values for the gaps in the stroke, each in range 0.0 - 1.0

-1.0, -1.0, -1.0, -1.0 : ignore
gapOverPrint int -1 1 Overprint background of stroke gaps
0 Do not overprint
-1 ignore
alignment int -1 Where should the contour be applied?

-1 ignore
0 in the middle
1 interior
2 outside
miter float -1.0 Line miter
-1.0 ignore
otherwise a value from the range 1.0 - 500.0
err_code = frame::stroke (frameRef, r, g, b [, width]);

The parameters from tint are available from version 1.0.20.

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_stroke(
  ItemRef f = 0,
  int* lineType = 0,
  float* width = 0,
  float* visiblewidth = 0,
  int* overprint = 0,
  int* gapoverprint = 0,
  int* align = 0,
  float* miter = 0)

Get the properties of the frames stroke. To get the strokes color use get_stroke_color.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef 0 Vaid frame reference
0 : current script frame
linetype int* 0 type of stroke, see here[#frame_stroke]
width float* 0 stroke width in points
visiblewidth float* 0 Unused Visible line width in points. According to Adobe documentation, the visible line width is 0.0 if the line type [None] is selected - but InDesign® does not support this setting.
overprint int* 0 Overprinting background?
gapoverprint int* 0 Gap overprinting
align int* 0 Line alignment, see stroke for possible values.
miter int* 0 Edge join miter in points
int main ()
{
    int 		type;
    float		width, viswidth;
    int			overprint, gapoverprint;
    int			align;
    float		miter;
    char		colname[256];
    int			colspace;
    float		c1, c2, c3, c4;
    float		tint;
frame::get_stroke (   gFrame,   &type,   &width, &viswidth,   &overprint, &gapoverprint,   &align,   &miter);
wlog ("", "# Stroke of frame %d\n", item::getint (gFrame)); wlog ("", " type : %d\n", type); wlog ("", " width : %f (%f)\n", width, viswidth); wlog ("", " overprint : %d (%d)\n", overprint, gapoverprint); wlog ("", " align : %d\n", align); wlog ("", " miter : %f\n", miter);
frame::get_stroke_color (   gFrame,   0,   colname,   &colspace,   &c1, &c2, &c3, &c4,   &tint); wlog ("", " color : %s (%f, %f, %f, %f), %f%%\n", colname, c1, c2, c3, c4, tint);
frame::get_stroke_color (   gFrame,   1,   colname,   &colspace,   &c1, &c2, &c3, &c4,   &tint); wlog ("", " gap-color : %s (%f, %f, %f, %f), %f%%\n", colname, c1, c2, c3, c4, tint);
return 0; }

Version 3.1 R2137, 20.09.2010

priint:comet InDesign® Plug-Ins, comet_pdf

stroke
get_stroke_color

static int get_stroke_color(
  ItemRef f = 0,
  int forGap = 0,
  char* colName = 0,
  int* colSpace = 0,
  float* c1 = 0,
  float* c2 = 0,
  float* c3 = 0,
  float* c4 = 0,
  float* tint = 0)

Get the stroke color of a frame. In case of some errors, the out values of the call are leaved untouched.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef 0 valid frame
0 : current script frame
forGap int 0 Color or gap color

0 : Get the line color
1 : Get the gap color
colName String or char* 0 Name of color
0 : ignore
otherwise : allocated string
colSpace int* 0 color space
0 : ignore
otherwise :
  kRGB
  kCMYK
  kLab
c1, c2, c3, c4 float* 0 color values
0 : ignore
otherwise :
  r, g, b on kRGB
  c, m, y, k on kCMYK
  l, a, b on kLab
tint float* 0 tint of color
0 : ignore
otherwise : 0.0 - 100.0
#include "internal/types.h"

The example queries out the stroke color of the given frame.

#include "internal/types.h"
int main () { char colName[256]; int colSpace; float c1, c2, c3, c4, tint;
if (frame::get_stroke_color (0,0, colName,&colSpace,&c1,&c2,&c3,&c4,&tint) == 0) { if (colSpace == kRGB) { showmessage (   "Color Name : %s\nR : %f\nG : %f\nB : %f\nTint : %f\n",   colName,   c1, c2, c3, tint); } else if (colSpace == kCMYK) { showmessage (   "Color Name : %s\nC : %f\nM : %f\nY : %f\nK : %f\nTint : %f\n",   colName,   c1, c2, c3, c4, tint); } else if (colSpace == kLab) { showmessage (   "Color Name : %s\nL : %f\na : %f\nb : %f\nTint : %f\n",   colName,   c1, c2, c3, tint); } else { showmessage ("Unknown color space"); } } else { showmessage ("Color could not be determined."); }
return 0; }

Version 3.1 R2137, 20.09.2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_color
get_stroke

static int get_lineends(
  ItemRef frameRef,
  int* start,
  int* end)

Determine the line ends (aka arrows) of the path of a frame. Please note that both InDesign® and comet_pdf support the setting of line ends on arbitrary frames but only draw them on open paths. So the function can also return defined line ends on rectangular frames and other closed shapes.

The following line ends (arrows) are supported:

ID Description
0 None
1 Simple
2 Simple Wide
3 Triangle
4 TriangleWide
5 Barbed
6 Curved
7 Circle
8 CircleSolid
9 Square
10 SquareSolid
11 Bar

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef 0 Valid Frame Reference

0 : Use current script frame
start int* 0 After execution, the variable contains the arrow type of the beginning of the line, see Arrows.

0 : Ignore return value
end int* 0 After execution, the variable contains the arrow type of the end of the line, see Arrows.

0 : Ignore return value

v4.2 R31404, 15. Aug 2022

priint:comet InDesign® Plug-Ins, comet_pdf

set_lineends
get_type

static int set_lineends(
  ItemRef frameRef,
  int start,
  int end)

Set the line ends (aka arrows) of the path of a frame. Please note that both InDesign® and comet_pdf support the setting of line ends on arbitrary frames but only draw them on open paths. So the function can also set line ends on rectangular frames and other closed shapes.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef 0 Valid Frame Reference

0 : Use current script frame
start int -1 New arrow at the beginning of the path, see Arrows.

-1 : Leave unchanged
end int* 0 New arrow at the end of the path, see Arrows.

-1 : Leave unchanged

v4.2 R31404, 15. Aug 2022

priint:comet InDesign® Plug-Ins, comet_pdf

get_lineends
get_type

static int noshadow(ItemRef frameRef)

Remove the shadow of a frame. If the specified frame has no shadow, the function has no significance.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
err_code = frame::noshadow (frameRef);

v3.0

priint:comet InDesign® Plug-Ins

static int shadow(
  ItemRef frameRef,
  char* colorName,
  float opacity,
  int blendMode,
  float x_diff,
  float y_diff,
  float = -1.0)

Shadow (DropShadow) of a frame defined by color name. The definition of a color is made by the name of the record in the color field.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
colorName String or char* - color name or Standardfarbe
opacity float - Transparency in % (0.0 - 100.0)
blendMode int - Blend in with background (see table at frame::opacity)
x_diff float - Horizontal spacing of frames in points
y_diff float - Vertical spacing of frames in points
blur_r float - Size of the "impurity" in points
err_code = frame::shadow (frameRef, color,
 		opacity, blendMode,
 		x_diff, y_diff, [blur_r]);

v3.0

priint:comet InDesign® Plug-Ins

static int shadow(
  ItemRef frameRef,
  int r,
  int g,
  int b,
  float opacity,
  int blenMode,
  float x_diff,
  float y_diff,
  float blur_r= -1.0)

Shadow (DropShadow) of a frame defined by the RGB values of the color. The definition of the colours is made using their RGB values.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
r, g, b int - color proportion (0-255)
opacity float - Transparency in % (0.0 - 100.0)
blendMode int - Blend in with background (see table at frame::opacity)
x_diff float InDesign® setting Horizont spacing of frame in points
y_diff float InDesign® setting Vertical spacing of frame in points
blur_r float InDesign® setting Size of "impurity" in points
err_code = frame::shadow (frameRef, color,
 		opacity,  blendMode,
 		x_diff, y_diff, [blur_r]);

v3.0

priint:comet InDesign® Plug-Ins

static int vignette(
  ItemRef frameRef,
  int vigCorner,
  float width,
  int vigMode = 0,
  float oOpaque = 0.0,
  float iOpaque = 0.0)

Edges and corners
  VignetteCorners
0 Sharp
1 Soft
2 Diffusion
  VignetteMode
0 None
1 Rectangular
2 Elliptical
1 FollowShape

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
vigCorner int - Pointed or round or whatever else, see table above Table Vignette Corners
width float - Width of the alienation
vigMode int - Right-angled or oval , see table above Tabel Vignette Mode
oOpaque float - The transparency of the part of the frame which is made free by a rounded corner
iOpaque float - The transparency of the part of the frame which is overprinted by a round corner on the inside
err_code = frame::vignette (frameRef,
 		vigCorner, width
 		[, vigType
 		[, oOpaque
 		[, iOpaque]]]);

v3.0

priint:comet InDesign® Plug-Ins

static int store_text(
  ItemRef frameRef,
  int start,
  int len,
  DBC* dbc,
  char* attr,
  char* table,
  long ID,
  long egoistic = 0,
  char* pageItemName = 0)

Write the content of a frame in the data base. All formattings, placeholders and tables of the text are assigned to the database.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frames the contents of which are to be stored
start int - Start position, from which the text is to be stored
kSelection Current text selection
>= 0 Textposition. Values larger than the text length are placed at the end of the text
otherwise : text start
len int - Length of the text that is to be stored
kEnd Copy to end of the text <=0 : Secure an empty text
Is start == kSelection the length specification has no significance.
dbc DBC - Target database, see sql::dbconnection
attr String or char* - Attribute of the target table in which the result is to be written. The attribute must be of type BLOB and may not be called TEXT.
table String or char* - Name of the target table. If the table name is empty (0 or ""), the database table pageitems will be used as the target database and the data stored in pageitems.data. In pageitems.preview a screenshot of the template will be stored.
ID int - ID in the target table
-1 : Create a new item
egoistic int 1 since version 1.34 R 343 From this release on parts of linked frames can exported too.

1 : Use only the given frame
0 : Be care of linked frames too
pageItemName String or char* 0 name of template. Used only if table is empty or pageitems
#include "internal/text.h"

An example on the function can be found in textmodel::store.


Version 1.1.4 egoistic and pageItemName since version 1.4 R343, 31. May 2007

priint:comet InDesign® Plug-Ins

textmodel::store
frame::restore_text

static int store_macro(
  ItemRef frameRef,
  int start,
  int len,
  int ID,
  int* macroID = 0,
  DBC dbc = 0,
  char* table = 0,
  char* data_attr = 0,
  char* prv_attr = 0,
  int useOldStyle = 1,
  char* macroName = 0)

Write the contents of the current text model in the database. All formattings, placeholders, tables and floating frames of the text. For simple export, the formatted text without floating frames the command textmodel::gettext can be used with the parameter kExportTagged or kExportTT.

Name Type Default Description
Return int   0 oder ErrorCode
start int - Start position, from which the text is to be stored
kSelection Current text selection
>= 0 Text position. Values larger than the text length are placed at the end of the text
otherwise : text start
len int - Length of the text which is to be stored
kEnd Copy to end of text <=0 : Save empty text
Is start == kSelection the length specification has no significance.
ID int - ID in the target table. The text component will be set up as required.
<= 0 : Independently ascertain the next free ID
macroID int* 0 ID of the set up or changed template. In case of an errorl (return != 0) the variable is given the value 0.
dbc DBC 0 Target database. Is this information is absent, the current database connection will be used.
table String or char* 0 Name of the target table. The name is only relevant where exporting to the database. Where exporting in XML files and to SOAP server the entries and inserted to the file pageitems.xml and the data and the preview are filed in sub-files in the data folder pageitems.
If the table name is empty (0 or ""), the database table will be used as the target table pageitems and the data stored in pageitems.data. In pageitems.preview a screenshot of the template will be stored.
data_attr String or char* 0 The attribute is only relevant with export to databases (not for XML or SOAP) and a table name not equal to 0, "" or "pageitems" and defines the attribute of the target table, in which the result is to be written. The attribute must be of the type BLOB and may not be called TEXT..
prv_attr String or char* 0 The attribute is only relevant with export to databases (not for XML or SOAP) and a table name not equal to 0, "" or "pageitems" and defines the attribute of the target table, in which the screenshot which the result is to be written. The attribute must be of the type BLOB and may not be called TEXT..
useOldStyle int 1 since version 1.34 R 343 From this release on parts of linked frames are exported too. 1 : use only the home frame 0 : Be care of linked frames too
macroName String or char* 0 name of template. Used only if table is empty or pageitems
#include "internal/text.h"

Save the current text selection in a new template.

int main ()
{
    int		res;
    int		macroID;
res = frame::store_macro (   gFrame, // Current frame   -2, 0, // Current text selection   -1, // Store new template   ¯oID); // ID of the stored template
if (res == 0 && macroID != 0)   showmessage ("Template %d stored", macroID); else   showmessage ("Error %d", res);
return 0; }

Version 1.2 (11. August 2005) useOldStyle and macroName since version 1.4 R343, 31. May 2007

priint:comet InDesign® Plug-Ins, comet_pdf

textmodel::store
textmodel::restore
frame::store_macro
frame::insert_macro

static int restore_text(
  ItemRef frameRef,
  int start,
  int len,
  DBC* dbc,
  char* attr,
  char* table,
  long ID,
  int autoLoad = 1,
  long* inserted = 0)

Replace the specified text frame with database-stored content. All formattings and placeholders for the text are taken from the database. References used (Formats, colours, ...) will, if they have not yet been defined, be automatically inserted in the target document. The formats and colours already defined will be used as input for the target document.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame the contents of which are to be changed
start int - Start position, from which the existing text is to be overwritten
kSelection Current text selection
>= 0 Text position. Values larger than the text length are place at the end of the text
otherwise : text start
len int - Length of the text which is to be overwritten
kEnd Overwrite to the end of the text <=0 : Insert upon start
Is start == kSelection the length specification has no significance.
dbc DBC - Database where the macro is stored

0 : Current data connection

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
attr String oder char* - Attribute name in the table of macros. The attribute must be of type BLOB and must not be called TEXT.

0 or "" : "data"

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
table String oder char* - Name of the table with the macros.

0 or "" : "pageitems"

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
ID int - ID in the table of macros. In XML offline and SOAP/PubServerver connections, use the template ID here.
autoLoad int 1 Should placeholders, which are located in the inserted text, be set up again?
0 : Placeholder not to be loaded
otherwise :Load placeholders
inserted int* 0 How many characters have been inserted in the text? The variable only then has a purposeful value, if the function is ended without error.
#include "internal/text.h"

An example of the function can be found at textmodel::restore.

Version 1.1.4
The parameter autoLoad and inserted are implemented since Version 1.1.7, January 2005.
comet_pdf since v4.2 R32720, 14. Apr 2023

priint:comet InDesign® Plug-Ins ,comet_pdf

frame::store_text
textmodel::restore

static int insert_macro(
  ItemRef frameRef,
  int start,
  int len,
  int ID,
  int autoLoad = 0,
  int* inserted_len = 0,
  DBC dbc = 0,
  char* table = 0,
  char* data_attr = 0)

Insert a text macro saved with frame::store_macro or textmodel::store_macro inot the current document text. The text is inserted with all formattings. Missing paragraph and character styles are set up. Floating frames are automatically imported and connected. The placeholders of the inserted text can optionally be loaded. All placeholders of the inserted text and all text and frame placeholders of the connected frames will be loaded.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame in which the text template are to be inserted.
start int - Start position, from which the text is to be inserted
kSelection Current text selection
>= 0 Text position. Values larger than the text length are place at the end of the text
otherwise : text start
len int - Length of the text which is to be removed prior to the insertion. As the text is deleted all floating frames, which are connected with parts of the deleted text, are likewise deleted.
kEnd Delete to end of the text <=0 : Not an empty text
Is start == kSelection the length specification has no significance.
ID int - ID in the table of macros. In XML offline and SOAP/PubServerver connections, use the template ID here.
autoLoad int 0 Should the placeholders in the text be loaded again following the insertion of the text?
0 : do not load
Otherwise : load
inserted_len int* 0 How many characters were inserted in the text? The variable only has meaningful value if the function has ended without errors.
dbc DBC - Database where the macro is stored

0 : Current data connection

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
attr String oder char* - Attribute name in the table of macros. The attribute must be of type BLOB and must not be called TEXT.

0 or "" : "data"

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
table String oder char* - Name of the table with the macros.

0 or "" : "pageitems"

The specification is used in ODBC data connections only. In XML offline and SOAP/PubServerver connections the template storage is always used.
#include "internal/text.h"

Insert a text template.

int main ()
{
    int		result;
    int		inserted;
result = frame::insert_macro (   gFrame, // Current frame   -2, 0, // Current text selection   23, // Text template ID   1, // Load placeholder   &inserted); // Number of new characters
if (result == 0)   showmessage ("%d characters inserted", inserted); else   showmessage ("Error : %s.", serror (result));
return 0; }

Version 1.2.1 (11 August 2005)

priint:comet InDesign® Plug-Ins

textmodel::insert_macro
textmodel::store_macro
frame::store_macro

static char* image_getpath(
  ItemRef frameRef,
  char* path,
  int deepDive = 0)

Ascertain the path of the image of a Graphic Frame.

Name Type Default Description
Return char*   0 : Image path could not been ascertained
Otherwise the parameter path of the function will be returned
frameRef ItemRef - Reference to a valid Graphic Frame of the document
path String or char* - Reserved memory for the result path
deepDive int 0 You can include Graphic Frames AND its image into an other frame (I do NOT describe, how). In my eyes this is an InDesign® bug. How ever, the function shall return an image in this situation too. Set deepDive to 1 to let the function search for an image path inside the frames hierarchy too.
   

The function, of course, does not dive into InDesign® groups or text frames. But there can be other mysterious constructions, in which the function may find an image even if you don't want to find it.

We ONLY changed the behavior of THIS function. Other Comet function like functions to collect placeholders, to dos and to export document structures (placeholders.xml, elements.xml, groups.xml, ...) may still get different (or empty) image paths

Ignored by Illustrator.
int main ()
{
    char		path[4096];
if (frame::image_getpath (gFrame, path)) { showmessage (path); } else showmessage ("No image frame or no image");
return 0; }

Version 1.1.6
Parameter deepDive since v3.3 R2812, 01.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.CFrame.getImage

static int image_getpos(
  ItemRef frameRef,
  float* x = 0,
  float* y = 0,
  int boundsKind = 0)

Ascertain the position of an image in a Graphic Frame. The specification is given in points relative to the left upper corner of the Graphic Frame.

Name Type Default Description
Return int   0 : Image position could be ascertained
Error status : The frame is not a Graphic Frame or contains no graphic
frameRef ItemRef - Reference to a valid Graphic Frame of the document
x float* 0 Return variable for the spacing from the left side of the Graphic Frame. The specification is given in points.
The parameter may be 0.
y float* 0 Return variable for the spacing from the left side of the Graphic Frame. The specification is given in points.
The parameter may be 0.
boundsKind int 0 Get position relative to this bounds:

0 : outer stroke path
1 : path bounds ("blue" frame)

Does the specified frame contain an image?

if (!frame::image_getsize (gFrameRef))
{
    wlog("", "This frame contains an image!\n");
}

The example asks all characteristics supported by cscript of images in Graphic Frames.

int main ()
{
    char		path[4096];
    float		x, y, width, height, scaleX, scaleY, rotat, skew;
    char		fmt[8000];
strcpy (fmt, "%s\r Position : %.6f x %.6f"); strcat (fmt, "\r Size : %.6f x %.6f"); strcat (fmt, "\r Scaling : %.6f x %.6f"); strcat (fmt, "\r Rotation : %.6f"); strcat (fmt, "\r Skew : %.6f");
frame::image_getpath (gFrame, path); frame::image_getpos (gFrame, &x, &y, 1); frame::image_getsize (gFrame, &width, &height); frame::image_getscale (gFrame, &scaleX, &scaleY); frame::image_getrotation (gFrame, &rotat); frame::image_getskew (gFrame, &skew);
showmessage (fmt,   path,   x, y,   width, height,   scaleX, scaleY,   rotat, skew);
return 0; }

Version 1.1.6
boundsKind since v3.4 R5126, 24. Jan 2014

priint:comet InDesign® Plug-Ins, comet_pdf

static int image_getpath_bbox(
  ItemRef frameRef,
  float* l = 0,
  float* t = 0,
  float* r = 0,
  float* b = 0)

Calcalute the bounding box of the current clip path. Values are relative to the image frame. If the is no image or no clip path is set, the funtion returns an error code.

The function is equal to image::clippath.

Name Type Default Description
Return int   0 : Bounding box caclulated
Error code : no Graphic Frame, no image, or no clip path
frameRef ItemRef - valid document frame
l float* 0 left
t float* 0 top
r float* 0 right
b float* 0 bottom

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf

static int image_getsize(
  ItemRef frameRef,
  float* w = 0,
  float* h = 0,
  int bboxType = 0)

How big is the image of a Graphic Frame. The size specification is given in points.

Name Type Default Description
Return int   0 : Image position could be ascertained
Error status : The frame is not a Graphic Frame or contains no image
frameRef ItemRef - Reference to a valid Graphic Frame of the document
w float* 0 Return variable for width of the Graphic Frame. The specification is given in points.
The parameter may be 0.
h float* 0 Return variable for the height of the Graphic Frame. The specification is given in points.
The parameter may be 0.
bboxType int 0 0 : Size of the bounding box of the (possible rotated) image
1 : Current size of image frame

See example for image_getpos.

Version 1.1.6
Parameter bboxType since v3.4 R5126, 25. Jan 2013

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.getImageSize

static int image_getscale(
  ItemRef frameRef,
  float* x = 0,
  float* y = 0)

Scaling of an image of a Graphic Frame. The value 1.0 corresponds to 100%.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 : Image scaling could be ascertained
Error status : The frame is not a Graphic Frame of contains no image
frameRef ItemRef - Reference to a valid Graphic Frame of the document
x float* 0 Return variable for the scaling in X direction (100% corresponds to 1.0).
The parameter may be 0.
y float* 0 Return variable for the scaling in Y direction (100% corresponds to 1.0).
The parameter may be 0.

See example for image_getpos.

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.getImageScale

static int image_getrotation(ItemRef frameRef, float* x = 0)

Rotation of an image of a Graphic Frame. The specification is given in degrees as well in the corresponding InDesign® menu.

Name Type Default Description
Return int   0 : Rotatio degree could be ascertained
Error status : The frame is not a Graphic Frame of contains no image
frameRef ItemRef - Reference to a valid Graphic Frame of the document
x float* 0 Drehwinkel. Die Angaben sind analog den Angaben in InDesign® .
Der Parameter darf 0 sein.

See example for image_getpos.

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.getImageRotation

static int image_getskew(ItemRef frameRef, float* x = 0)

Skew of the image of a Graphic Frame. The specification is given in degrees as well in the corresponding InDesign® menu.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 : Skew degree could be ascertained
Error status : The frame is not a Graphic Frame of contains no image
frameRef ItemRef - Reference to a valid Graphic Frame of the document
x float* 0 Skew degree. The specification are analagous to the specification in InDesign® .
The parameter may be 0 .

See example for image_getpos.

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.getImageSkew

static int image_blackcolor(ItemRef frameRef, char* colorName)

Overlay the black of a B/W image with the given color. The functions effects only to B/W images!

InDesign® allows to set an opacity factor for named colors. But in fact, opacity means here adding to black! A 50%-red to black creates a dark red. I expected a light red. And, yes, 0%-red means black under this circumstances. So better use frame::opacity to get the expected effects here!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
colorName String or char* - Name of the color
err_code = frame::image_blackcolor (frameRef, colorName);

Version 2.1 R 913, 22. Aug. 2008

priint:comet InDesign® Plug-Ins

image_blackcolor_rgb
image_blackcolor_cmyk

static int image_blackcolor_rgb(
  ItemRef frameRef,
  int r,
  int g,
  int b)

Overlay the black of a B/W image with the given color. The functions effects only to B/W images!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
r, g, b int - color values (0-255)
err_code = frame::image_blackcolor (frameRef, r, g, b);

Version 2.1 R 913, 22. Aug. 2008

priint:comet InDesign® Plug-Ins

image_blackcolor
image_blackcolor_cmyk

static int image_blackcolor_cmyk(
  ItemRef frameRef,
  float c,
  float m,
  float y,
  float k)

Overlay the black of a B/W image with the given color. The functions effects only to B/W images!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Target frame
c, m, y, k int - color values (0.0 - 1.0)

Version 2.1 R 913, 22. Aug. 2008

priint:comet InDesign® Plug-Ins

image_blackcolor
image_blackcolor_rgb

static int image(
  ItemRef frameRef,
  char* path,
  int alignment = 5,
  float boundingBox = 0.0,
  int pathindex = -2,
  char* pathname = 0,
  int flags = 0,
  int cliptoFrame = 0,
  float tolerance = 0.0,
  float minPathSize = 0.0,
  float inset = 0.0,
  int alphaIndex = -2,
  char* alphaChannel = 0,
  int treshold = 255,
  int updateFlags = 0)

Place a file into a frame.

The current (and format-dependent) InDesign® import settings are used for the import. To view or change the import preferences, use the File -> Place menu command and enable the option Show import options in the appearing file dialog. Please do not forget to switch off the option again!

An example of how import options can be set on the script side can be found below.

With the help of so-called UNC paths you can insert images in such a way that the image path can be resolved correctly under Mac as well as under Windows without any changes. See here for more information. Please note : On Mac OS UNC paths are supported when inserting images from v4.2 R33250 only.

Images can be loaded from the Internet. To do this, use a valid http, https or ftp URL instead of a local file path. General information about Web Images can be found here.

Images can be loaded from Adobe CC Libraries. Use the following syntax for images of CC Libraries (The spaces are important!):

"CC Libraries: Libname/Imagename"

File aliases are allowed for library names here.

Images from CC Libraries are automatically downloaded locally by InDesign. If an image is deleted from a CC Library, these local copies may remain on your computer. To check if a CC Libraries image is still available, use the function file::exists.

The CC Libraries are constantly being developed by Adobe. Unfortunately there is no interface for Javascript or C++ for it. Our implementation is the result of deep diving into the XMLs and JSONs of CCLib and may be based on assumptions that have changed since it was introduced in November 2020. Please understand that we will not continue to develop the feature until Adobe introduces a CCLib interface.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame in which the image is to be inserted
path String oder char* - Image address

Local network : Complete file path. Paths may be begin with a file alias.

Internet : http, https or ftp URL of an existing image.

CC Libraries : Specification of the image in the format "CC Libraries: Libname/Imagename". File aliases are allowed for the library names. In this case only the name part of the path is used.
alignment int kMiddle see image positions
boundingBox float kFitBigContentProp Image size in points

kFitBigContentProp : Fit image (proportional) to the frame. Image less than the frame leave untouched

>0.0 : Fit image (proportional) to a square of the given size. Image less than the square leave untouched

<0.0 : Fit image (proportional) to a square of the given size. Image less than the square are zoomed
⇨ Photoshop Clipping Path
pathindex int 0 0-based index of clipping path

kIgnoreClipping : Ignore clip setting

kResetClipping : Reset any existing clipping.

>=0 : 0-based clipping path index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by pathname instead.
pathname String or char* "" Name of clipping path

Values ignored by InDesign® if the path is defined by its index already.
⇨ Properties for clipping. Also used for alpha channels.
flags int kAllowHolesFlag How to clip the image? Values can be added.

kInvertFlag Invert the resulting path by combining with a path equal to the bounds of the image.

kAllowHolesFlag For edge detection, do we remove the holes or leave them in.

kRestrictToFrameFlag

Value is ignored by comet_pdf.
cliptoFrame int 0 Use the the clipping path as the frames path?

0 : Keep old frame
1 : Change frame
tolerance float 0.0 A tolerance value in the range of 0.0 to 10.0 specifying how close to the original path we must be if we smooth the path. 0.0 indicates a perfect match. Smoothing may simplify the path, reducing the number of points.

The parameter is not applied by Indesign® Server and comet_pdf.
minPathSize float 0.0 subpaths smaller than the minPathSize will be deleted.

The parameter is not applied by Indesign® Server and comet_pdf.
inset float 0.0 How far to inset the path

The parameter is not applied by Indesign® Server and comet_pdf.
⇨ Alpha Channel
alphaIndex int 0 0-based index of channel, see image::alpha_channel_index

kResetClipping do not apply any alpha channel

>=0 : 0-based channel index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by alphaChannel instead.
alphaChannel String or char* "" Name of alpha channel

Values ignored by InDesign® if the channel is defined by its index already.
treshold int 255 Treshold for alpha channel.

0-255 : The alpha channel is applied to the image after the image import. The result is the same like using menu Object -> Clipping path -> Options and indeed it is a very bad result.

> 255 : Recommended! Apply the alpha channel directly while importing the image.
⇨ Update Flags
updateFlags int 0 For Web-Images Only

16 : If the local image file already exists, it is used without further checking.
#include "internal/types.h"
document::folder (path);
strcat (path, "/Bilder/Echinops/banaticus.JPG");
frame::image (frame, path, 5, 100.0);

Insert an image and apply its first alpha channel

#include "internal/types.h"
int main () { int result;
result = frame::image (   gFrame,   "your path",   kPlaceCentered,   kFitBigContentProp,   kIgnoreClipping, 0, 0,   0, 0.0, 0.0, 0.0,   0, 0); wlog ("", "Result of placing image : %d (%s).\n", result, serror (result)); return 0; }

The following example shows how to set import options for images on script side. More Import Options can be found here.
Please note that you have to get the current setting for pdfCrop as string here. But the value obtained is an enumeration type and must therefore be specified as int when resetting!

#include "internal/types.h"
int main () { char oldCrop [256]; char resetCmd [512]; ItemRef lk = item::alloc ();
run_javascript ("function main () {return app.pdfPlacePreferences.pdfCrop;} main ();", 0, 1, 0, kString, oldCrop); run_javascript ("app.pdfPlacePreferences.pdfCrop = PDFCrop.CROP_CONTENT_VISIBLE_LAYERS;");
frame::image (gFrame, "$DESKTOP/abc.pdf", 1);
sprintf (resetCmd, "app.pdfPlacePreferences.pdfCrop = %s;", oldCrop); run_javascript (resetCmd);
return 0; }

Import a Web Image and suppress the header request, if the current image download already exists. Please note that all unused parameters until the updateFlags parameter must be filled with default values!

#include "internal/types.h"
int main() { frame::image (gFrame, "https:www.wago.com/medias/?context=bWFzdGVyfGltYWdlc3wyMTgyMXxpbWFnZS9qcGVnfGFHRTBMMmhoTnk4eE16YzVPRFV5TnpBME1UVTJOZ3w3ODNlMDQ4ZWJjYTNiMzhkMDM4NWRkYjE4ZDc3YjM5OTUzNTAzZDM1ZWRjNTMwNmUxMmE5NDU1ZDM3MzQ0OGI3kOnlyHash", kMiddle, // alignment kFitBigContentProp, // boundingBox 0, "", // clip path index and name kAllowHolesFlag, 0, 0.0, 0.0, 0.0, // clip path info 0, "", 255, // alpha channel info 16); // suppress header check
return 0; }

pathindex, pathname, flags, cliptoFrame, tolerance, minPathSize, inset since Version 16. March 2006 (P/R38)

alphaIndex, alphaChannel since version 3.1 R1840, 30. April 2010

treshold since v3.3 R3500, 8. Mar 2013

Support of CC Libraries since v4.1.8 R27691, 2. Nov 2020

Parameter updateFlags seit v4.3 R34000, 23. Nov 2024

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.setImage
Loading image placeholder
Use image::setclip if only the clip path is to change.

static int embed_file(
  ItemRef frameRef,
  char* path,
  int alignment = 5,
  float boundingBox = 0.0)

Embed an image into a frame. The image ist defined by a file or an URL and has no connection to ist original after embedding. Clip paths like in frame::image are not applied. The alignments kConstrainToCell, kConstrainToCellWidth und kConstrainToCellHeight have no effects.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame. If the frame isn't a Graphic Frame, it will be converted automatically

0 : current script frame
path String or char* - complete path or URL to the image
alignment int kMiddle see image positions
boundingBox float kFitBigContentProp Image size in points

kFitBigContentProp : Fit image (proportional) to the frame. Image less than the frame leave untouched

>0.0 : Fit image (proportional) to a square of the given size. Image less than the square leave untouched

<0.0 : Fit image (proportional) to a square of the given size. Image less than the square are zoomed
#include "internal/types.h"

Embed a local image file into a frame.

#include "internal/text.h"
#include "internal/types.h"
int main () { char imgFile[255]; int res; char dp[2000];
document::folder (dp); strcpy (imgFile, dp); strcat (imgFile, "/"); strcat (imgFile, "clara.JPG"); res = frame::embed_file (gFrame, imgFile, kPlaceTopLeft, 0.0);
if (res == 0) wlog ("", "Embedding '%s' successfully finished\n", imgFile); else wlog ("", "Embedding '%s' done with error %d\n", imgFile, res);
return 0; }

You may also wish to embed image files from the internet.

#include "internal/text.h"
#include "internal/types.h"
int main () { char imgFile[255]; int res;
strcpy (imgFile, "http://www.hi13.de/Auto.JPG"); res = frame::embed_file (gFrame, imgFile, kPlaceTopLeft, 0.0);
if (res == 0) wlog ("", "Embedding '%s' successfully finished\n", imgFile); else wlog ("", "Embedding '%s' done with error %d\n", imgFile, res);
return 0; }

Version 2.0 R 644, 22. März 2008

priint:comet InDesign® Plug-Ins, comet_pdf

embed_image

static int embed_image(
  ItemRef frameRef,
  Image img,
  int alignment = 5,
  float boundingBox = 0.0)

Embedding an image in a frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference. If the frame is not a graphics frame, it is converted to a graphics frame.

0 : Current frame of the script
img Image - Image binary data, see Image
alignment int kMiddle see image positions
boundingBox float kFitBigContentProp Image size in points

kFitBigContentProp : Fit image (proportional) to the frame. Image less than the frame leave untouched

>0.0 : Fit image (proportional) to a square of the given size. Image less than the square leave untouched

<0.0 : Fit image (proportional) to a square of the given size. Image less than the square are zoomed

Version 2.0 R 644, 22. März 2008

priint:comet InDesign® Plug-Ins, comet_pdf

embed_file
image

static int place_pdf(
  ItemRef frameRef,
  char* path,
  int pageIndex = 1,
  int alignment = 5,
  float bounding = 0.0,
  int transparentBkg = 0,
  char* layer1 = 0,
  ...)

Place a PDF into a given frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame into which the PDF is to be placed

0 : current script frame
path String oder char* - Full local or UNC path to the PDF file to be placed in the document. The path may start with a defined $ALIAS.

[Since v4.2 R33270] URLs are also allowed here.
pageIndex int 1 Which page of the PDF should be placed?

≤0 : Last page
otherwise : 1-based page number. If the number of pages is greater than the given page number, the first page of the PDF will be placed.

Use parameter behavior to change the behavior for undefined page numbers.

alignment int kMiddle Position of the image in the frame, see image positions
bounding float kFitBigContentProp Specification of the size of the image in the frame. Specification in points.

kFitBigContentProp : Fit the image proportionally into the frame. If the image is smaller than the frame, it will not be changed.

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

<0.0 : Fit image proportionally into a square frame of the amount of this size. If the image is smaller, it will be resized accordingly.
transparentBkg int 0 Should the background be transparent?

0 : No
1 : Yes
layer1, ... String oder char* 0 Arbitrarily long 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!

The specifications are ignored by comet_pdf and if the PDF file is given by an URL. In these cases the layer visibilities of the PDF are used.
0, behavior 0, int 0, 2 Behavior with undefined page numbers. The specification is made, separated by a 0, after the layer names

1 : Cancel with pageNotFoundErr (1219)
2 : First page
3 : Last page
#include "internal/types.h"
err_code = frame::place_pdf (gFrame, "$DESKTOP/a.pdf", 3);

Import page 2 and show Layer 1 and Layer 2. Background is transparent and the image is bottom centered in a 100 point box.

int main()
{
    frame::place_pdf (
     	gFrame,
     	"/Users/paul/Desktop/for_pfd.pdf",
     	2,
     	8,
     	100.0,
     	1,
     	"Layer 1", "Layer 2");
    return 0;
}

Version 2.1, 23. Feb 2010 (R1760)
Parameter behavior since v4.2 R32235, 1. Feb 2023
ULR support since v4.2 R33270

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.setImage

static int place_pdf_with_crop(
  ItemRef frameRef,
  char* path,
  int pageIndex = 1,
  int alignment = 5,
  float bounding = 0.0,
  int transparentBkg = 0,
  int cropTo = -1,
  char* layer1 = 0,
  ...)

Place a PDF in a frame. The function is identical to frame::place_pdf, but in addition a cropping rule can be applied in the croptTo parameter.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame into which the PDF is to be placed

0 : current script frame
path String oder char* - Full local or UNC path to the PDF file to be placed in the document. The path may start with a defined $ALIAS.

[Since v4.2 R33270] URLs are also allowed here.
pageIndex int 1 Which page of the PDF should be placed?

≤0 : Last page
otherwise : 1-based page number. If the number of pages is greater than the given page number, the first page of the PDF will be placed.

Use parameter behavior to change the behavior for undefined page numbers.

alignment int kMiddle Position of the image in the frame, see image positions
bounding float kFitBigContentProp Specification of the size of the image in the frame. Specification in points.

kFitBigContentProp : Fit the image proportionally into the frame. If the image is smaller than the frame, it will not be changed.

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

<0.0 : Fit image proportionally into a square frame of the amount of this size. If the image is smaller, it will be resized accordingly.
transparentBkg int 0 Should the background be transparent?

0 : No
1 : Yes
cropTo int -1 Crop pdf to bounding box

-1 : Use InDesign import options
0 : Crop to content (visible layers)
1 : Use InDesign import options
2 : Crop to art
3 : Crop to page
4 : Crop to trim
5 : Crop to bleed
6 : Crop to media
7 : Crop to content (all layers), since CS5

The red marked wishes are not supported bycomet_pdf.
layer1, ... String oder char* 0 Arbitrarily long 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!

The specifications are ignored by comet_pdf and if the PDF file is given by an URL. In these cases the layer visibilities of the PDF are used.
0, behavior 0, int 0, 2 Behavior with undefined page numbers. The specification is made, separated by a 0, after the layer names

1 : Cancel with pageNotFoundErr (1219)
2 : First page
3 : Last page
#include "internal/types.h"
err_code = frame::place_pdf_with_crop (gFrame, "$DESKTOP/a.pdf", 3);

Import page 2 and show Layer 1 and Layer 2. Background is transparent and the image is bottom centered in a 100 point box.

int main()
{
    frame::place_pdf (
     	gFrame,
     	"/Users/paul/Desktop/for_pfd.pdf",
     	2,
     	8,
     	100.0,
     	1,
     	1,
     	"Layer 1", "Layer 2");
    return 0;
}

seit Version v3.3 R3011, 25.05.2012
Parameter behavior since v4.2 R32235, 1. Feb 2023
ULR support since v4.2 R33270

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.setImage

static int image_pos(
  ItemRef frameRef,
  float x,
  float y)

Set the position of the image inside a given Graphic Frame. Values are given in points relative to the upper left corner of the Graphic Frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Graphic Frame of the image to be moved
x float - Relative image position to the left upper frame corner in points
y float - Relative image position to the left upper frame corner in points

Fix all characteristics supported by cscript of the image in the Graphic Frame.

int main ()
{
    float    width, height;
frame::image_getsize (gFrame, &width, &height);
frame::image_pos (gFrame, 12.0, 34.0); frame::image_size (gFrame, 100.0, 140.0); frame::image_scale (gFrame, 0.5, 0.7777); frame::image_rotate (gFrame, -30.0, width/2.0, height/2.0); frame::image_skew (gFrame, -30.0, width/2.0, height/2.0, 90.0);
return 0;
}

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf

static int image_size(
  ItemRef frameRef,
  float width,
  float height,
  int refPoint = 0,
  float refX = 0.0,
  float refY = 0.0)

Set the size of the image inside a given Graphic Frame. Values are given in points.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Graphic Frame of the image to be resized
x float - New image width in points
y float - New image height in points
refPoint int kRefPointTopLeft Scaling reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
 
refX, refY float, float 0.0, 0.0 Reference point in points relative to the top left corner of the given frame.
#include "internal/types.h"

See example for image_getpos.

Version 1.1.6
refPoint, refX, refY since Version 2.1 R684, 23.4.2008

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.setImageSize

static int image_scale(
  ItemRef frameRef,
  float x,
  float y,
  int refPoint = 0,
  float refX = 0.0,
  float refY = 0.0,
  int frameRelativeRefPoint = 0)

Set the position of the image inside a given Graphic Frame. The value 1.0 corresponds to the original size (100%) of the image.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - raphic Frame of the image to be scaled
x float - New scale for the image width (1.0 for 100%)
y float - New scale for the image height (1.0 for 100%)
refPoint int kRefPointTopLeft scaling reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
refX, refY float, float 0.0, 0.0 Reference point in points relative to the top left corner of the given image.
frameRelativeRefPoint int 0 Use the graphicframe as base for the reference point (instead of the image)

0 : no
1 : yes
#include "internal/types.h"

See example for image_getpos.

Horizontal flipping an image. (For completeness followed by vertical flipping.):

int main ()
{
    float			x, y, rot;
    float			w, h;
frame::image_getsize (gFrame, &w, &h); frame::image_getscale (gFrame, &x, &y); frame::image_getrotation (gFrame, &rot);
frame::image_scale (gFrame, x, -y, kRefPointCenter); frame::image_rotate (gFrame, rot+180.0, w/2.0, h/2.0);
return 0; }

int main () { float x, y; frame::image_getscale (gFrame, &x, &y); frame::image_scale (gFrame, x, -y, kRefPointCenter); return 0; }

Version 1.1.6
refPoint, refX, refY since Version 2.1 R684, 23.4.2008
frameRelativeRefPointnt since v3.3 R2750, 23.11.2011

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.setImageScale

static int image_rotate(
  ItemRef frameRef,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0)

Rotate the image inside a given Graphic Frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Graphic Frame of the image to be rotated
angle float - Rotation angle in degrees
refpointX float 0.0 X value of the reference point for the rotation in points relative to the left edge of the image, not the frame.
refpointY float 0.0 Y-value of the reference point for the rotation in points relative to the upper edge of the image, not the frame.
#include "internal/types.h"

See example for image_getpos.

Horizontal flipping an image. (For completeness followed by vertical flipping.):

int main ()
{
    float			x, y, rot;
    float			w, h;
frame::image_getsize (gFrame, &w, &h); frame::image_getscale (gFrame, &x, &y); frame::image_getrotation (gFrame, &rot);
frame::image_scale (gFrame, x, -y, kRefPointCenter); frame::image_rotate (gFrame, rot+180.0, w/2.0, h/2.0);
return 0; }

int main () { float x, y; frame::image_getscale (gFrame, &x, &y); frame::image_scale (gFrame, x, -y, kRefPointCenter); return 0; }

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.setImageRotation

static int image_skew(
  ItemRef frameRef,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0)

Skew the image inside a given Graphic Frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Graphic Frame of the image to be skewd
angle float - Skew angle in degrees
refpointX float 0.0 X value of the reference point for the skewing in points relative to the left edge of the image, not the frame.
refpointY float 0.0 Y value of the reference point for the skewing in points relative to the upper edge of the image, not the frame.

See example for image_getpos.

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CFrame.setImageSkew

static int rotate(
  ItemRef frameRef,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1,
  int refPoint = 0)

Rotate a frame.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame to rotate
angle float - Rotation angle in degrees counter clock wise
refpointX float 0.0 Ignored since v4.1 R21457
refpointY float 0.0 Ignored since v4.1 R21457
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.
refPoint int kRefPointCenter \Fix point of roation

-1 : Ignore and use refpointX and refpointY

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
#include "internal/types.h"

Version 1.4 R336 (18. April 2007)
Parameter suprRules since v3.3 R3405, 5. Feb. 2012
Parameter refPoint siince v4.1 R21457, 11. Jan 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_rotate
comet.CFrame.setRotation

static float get_rotate(
  ItemRef frameRef,
  float* refpointX = 0,
  float* refpointY = 0)

Get the current rotation of a frame.

Name Type Default Description
Return float   Rotation angle in degrees
frameRef ItemRef - Valid frame reference

0 : current script frame
refpointX, refpointY float*, float* 0, 0 Reference point for rotation

0 : ignore
Ignored by Illustrator
int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;
frame::bbox (gFrame, &l, &t, &r, &b); frame::size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n",   item::getint (gFrame),   r-l, b-t,   w, h);
f = frame::get_rotate (gFrame, &refx, &refy); wlog ("", " rotation : %f (%f, %f)\n", f, refx, refy);
f = frame::get_skew (gFrame); wlog ("", " skew : %f\n", f);
f = frame::get_scale (gFrame, &sx, &sy); wlog ("", " scale : %f x %f\n", sx, sy);
return 0; }

Version 3.2 R2255, 3. Feb. 2011

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

rotate
comet.CFrame.getRotation

static float get_skew(ItemRef frameRef)

Get the current skew angle of a frame.

Name Type Default Description
Return float   Skew angle in degrees
frameRef ItemRef - Valid frame reference

0 : current script frame
int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;
frame::bbox (gFrame, &l, &t, &r, &b); frame::size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n",   item::getint (gFrame),   r-l, b-t,   w, h);
f = frame::get_rotate (gFrame, &refx, &refy); wlog ("", " rotation : %f (%f, %f)\n", f, refx, refy);
f = frame::get_skew (gFrame); wlog ("", " skew : %f\n", f);
f = frame::get_scale (gFrame, &sx, &sy); wlog ("", " scale : %f x %f\n", sx, sy);
return 0; }

Version 3.2 R2255, 3. Feb. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

skew
comet.CFrame.getSkew

static int get_scale(
  ItemRef frameRef,
  float* scalex = 0,
  float* scaley = 0)

Get the current frame scaling.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference

0 : current script frame
scalex, scaley float*, float* 0, 0 Current scalings (1.0 means 100%)

0 : ignore
int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;
frame::bbox (gFrame, &l, &t, &r, &b); frame::size (gFrame, &w, &h); wlog ("", "Frame %d : %f x %f (%f x %f)\n",   item::getint (gFrame),   r-l, b-t,   w, h);
f = frame::get_rotate (gFrame, &refx, &refy); wlog ("", " rotation : %f (%f, %f)\n", f, refx, refy);
f = frame::get_skew (gFrame); wlog ("", " skew : %f\n", f);
f = frame::get_scale (gFrame, &sx, &sy); wlog ("", " scale : %f x %f\n", sx, sy);
return 0; }

Version 3.2 R2255, 3. Feb. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

resize
comet.CPageItem.getScale

static int scale(
  ItemRef frameRef,
  float xscale,
  float yscale,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1,
  int refPoint = -1)

Scale a frame by the given scaling factors.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid document frame
xscale float - Factor for changing the frame width
yscale float - Factor for changing the frame height
refpointX float 0.0 X value of the fix point in points relative to the left edge of the frame

The value is ignored by comet_pdf and the refPoint is used always.
refpointY float 0.0 Y value of the fix point in points relative to the upper edge of the frame

The value is ignored by comet_pdf and the refPoint is used always.
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.
refPoint int -1 Reference point for scaling

-1 : Ignore and use refpointX and refpointY verwenden

kRefPointTopLeft (0)
kRefPointTopCenter(1)
kRefPointTopRight(2)
kRefPointLeftCenter(3)
kRefPointCenter(4)
kRefPointRightCenter(5)
kRefPointBottomLeft(6)
kRefPointBottomCenter(7)
kRefPointBottomRight(8)
#include "internal/types.h"

Version 1.4 R336 (18. April 2007)
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_scale
get_skew
comet.CPageItem.setScale
prefs::get_transform_settings
prefs::set_transform_settings

static int scale_to(
  ItemRef frameRef,
  float xscale,
  float yscale,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1,
  int refPoint = -1)

Scale a frame to the given factors.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid document frame
xscale float - New frame width in percent, 1.0 corresponds to 100%.
yscale float - New frame height in percent, 1.0 corresponds to 100%.
refpointX float 0.0 X value of the fix point in points relative to the left edge of the frame

The value is ignored by comet_pdf and the refPoint is used always.
refpointY float 0.0 Y value of the fix point in points relative to the upper edge of the frame

The value is ignored by comet_pdf and the refPoint is used always.
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.
refPoint int -1 Reference point for scaling

-1 : Ignore and use refpointX and refpointY verwenden

kRefPointTopLeft (0)
kRefPointTopCenter(1)
kRefPointTopRight(2)
kRefPointLeftCenter(3)
kRefPointCenter(4)
kRefPointRightCenter(5)
kRefPointBottomLeft(6)
kRefPointBottomCenter(7)
kRefPointBottomRight(8)
#include "internal/types.h"

v4.1.6 R26411, 12. Dec. 2019

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_scale
get_skew
prefs::get_transform_settings
prefs::set_transform_settings

static int skew(
  ItemRef frameRef,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0,
  float rotation = 0.0,
  int suprRules = 1)

Skew a frame horizontally. For a vertical skew, use the negative angle to skew followed by a rotation to the negative angle (use the same fix points for both transformations!).

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid document frame
angle float - Skew angle
refpointX float 0.0 X value of the fix point for the skewing in points relative to the left edge of the frame

Ingored from comet_pdf, the reference point here is the the top left corner always.
refpointY float 0.0 Y value of the fix point for the skewing in points relative to the upper edge of the frame

Ingored from comet_pdf, the reference point here is the the top left corner always.
rotation float 0.0 Value of the optional rotation in addition to the skew, not supported by InDesign® CS3.
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry changes".

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.

Version 1.4 R336 (18. April 2007)
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf

get_skew
comet.CFrame.setSkew

static int place_file(
  ItemRef frameRef,
  char* path,
  int alignment = 5,
  float size = 0.0)

see frame::image

Name Type Default Description
Return int   0 oder Fehlercode

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins
frame::image

static int reimport(
  ItemRef frame,
  int uiFlags = 0,
  int doAll = 0)

Update the connection of a frame. Only those connections will be updated the content of which is no longer up to date. If the content is up to date, the request will have no effect.

Using comet_pdf the function is a NOP only.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame, the connection of which is to be updated
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogs
1 Display the next dialog 2 Display all dialogs
doAll int 0 InDesign® does allow itself one small slip up : If the target file of a link is renamed and another file is given the name, which is to be specified in the link, InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell that the reference is newly loaded in all cases. the Reimport of all references can take some time to complete.

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf

static int reimport_all(
  int uiFlags = 0,
  int doAll = 0,
  int includePasteboard = 0)

Update the connections of all frames of the document. Only those connections will be updated which are not already up to date.

Using comet_pdf the function is a NOP only.

Name Type Default Description
Return int   0 or ErrorCode
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogs
1 Display the next dialog 2 Display all dialogs
doAll int 0 InDesign® does allow itself one small slip up : If the target file of a link is renamed and another file is given the name, which is to be specified in the link, InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell that the reference is newly loaded in all cases. the Reimport of all references can take some time to complete.
includePasteboard int 0 Also reimport frames on paste board?

0 : No. Do only reimport page frames
otherwise : yes

includePasteboard since v3.3 R5220 (3. Mar 2014)

priint:comet InDesign® Plug-Ins, comet_pdf

static int reimport_selected(int uiFlags = 0, int doAll = 0)

Update the connections of all selected frames of the document. Only those connections will be updated which are not already up to date.

Using comet_pdf the function is a NOP only.

Name Type Default Description
Return int   0 or ErrorCode
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogs
1 Display the next dialog 2 Display all dialogs
doAll int 0 InDesign® does allow itself one small slip up : If the target file of a link is renamed and another file is given the name, which is to be specified in the link, InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell that the reference is newly loaded in all cases. the Reimport of all references can take some time to complete.

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf

static int reimport_list(int uiFlags = 0, int doAll = 0)

Update the connections of all frames of the given list. Only those connections will be updated the contents of which are not already up to date.

Using comet_pdf the function is a NOP only.

Name Type Default Description
Return int   0 or ErrorCode
frameList ItemList - List of the frames which are to be updated.
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogs
1 Display the next dialog 2 Display all dialogs
doAll int 0 InDesign® does allow itself one small slip up : If the target file of a link is renamed and another file is given the name, which is to be specified in the link, InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell that the reference is newly loaded in all cases. the Reimport of all references can take some time to complete.

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf

static char* get_layer(ItemRef itemRef, char* name)

Ascertain the name of the layer on which a frame is located.

Name Type Default Description
Return String or char* (Depends on parameter name)   Name of the layer on which the specified frame lies, or empty string. Same as parameter name
itemRef ItemRef - Frame the layer of which is to be ascertained.
name String or char* - Reserved memory for the result

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.CFrame.getLayer

static int parent(
  ItemRef frame,
  ItemRef parent,
  int* textPos = 0)

Determine the enclosing frame of a frame. For inline frames, this is the frame in which the inline currently resides. For images the enclosing image frame is returned.

The function is not suitable for determining the InDesign group of a frame. To do this, please use the function frame::get_group.

Um zu erfragen, ob ein Rahmen innerhalb eines Textes steht, verwenden Sie die Funktion frame::isinline.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Inline frame or image (but not the frame containing the image)
parent ItemRef - Reserved memory for the result. The reference is only fulfilled, if the function returns the error code 0
textPos int* 0 Text position of the frame. The value is set only for inline frames, otherwise it is -1.

Version 1.1.7, Januar 2005
Parameter textPos seit v4.1.8 R29412, 19. Nov 2021

priint:comet InDesign® Plug-Ins, comet_pdf
frame::isinline
frame::textframe

static int isinline(ItemRef frame)

Is the specified frame located within the text?

Name Type Default Description
Return int   1 : ja
0 : nein
frame ItemRef - Frames the inline characteristics of which are to be inquired.

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf
frame::isinline
frame::textframe
position_visible

static int textframe(ItemRef frame, ItemRef textFrame)

DEPRECATED! Please use the frame::parent function instead.

Ascertain the text frames of an inline frame. This frame is different to the frames, which is ascertained through frame::parent.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Frames the text frames of which are to be inquired. If the specification is 0, the text frame of the current text model or the value of the variable gFrame is inquired.
textFrame ItemRef - Reserved memory for the result. The reference is only fulfilled, if the function returns the error code 0.

Please use the frame::parent function instead.
Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf
frame::isinline
frame::parent

static int floating(
  ItemRef textframe,
  ItemRef frame,
  int pos,
  int align,
  float alignOffset,
  int linePos,
  float lineOffset,
  int flag = 1)

DEPRECATED! Please use frame::inline_, frame::inline_above, frame::anchor and frame::get_anchor instead.

Name Type Default Description
Return int   -1199

Please use frame::inline_, frame::inline_above, frame::anchor and frame::get_anchor instead.

static int hasfloating(ItemRef textframe, int pos)

DEPRECATED! Please use frame::isinline and frame::get_anchor instead.

Name Type Default Description
Return int   0

Please use frame::isinline and frame::get_anchor instead.

static int group(ItemList frames, ItemRef newFrame = 0)

Group a selection of document frames. If at least one frame of the give list is locked, all frames are locked.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Liste valid frame references
newFrame itemRef - allocated memory for the result. If the frames are successfully grouped the variable will contain a valid reference to the group frames.
#include "internal/text.h"

A placeholder script inserts floating frames comprised of several frames at the start of the text.

#include "internal/text.h"
int main () { DataPool pool = datapool::alloc (); ItemList frames = itemlist::alloc (); ItemRef groupRef = item::alloc (); ItemList items = 0; float l = 0.0; float t = 0.0; float r, b; int i; int textpos;
if (!textmodel::available ()) return 0;
// Insert own frames into document // The templates 2-4 must be set up. for (i = 2; i<5; i++) { // Insert template // items are thereby aiutomatically allocated items = document::place_items (pool, "data", "pageitems", i, l, t);
// Group inserted frames itemlist::appendlist (frames, items);
// Next template position // The list items are then deleted. itemlist::bbox (items, &l, &t, &r, &b); itemlist::release (items); items = 0; t = b + 2.0; }
// Group inserted templates frame::group (frames, groupRef);
// Let group float textmodel::floating (groupRef, textmodel::start (),   kRightHanded, 5.0,   kBelowTop, 0.0);
return 0; }

Version 1.2.1 (25. August 2005)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

ItemList
itemlist::append
...
ungroup
comet.frame.createGroup

static int ungroup(ItemRef groupFrame, ItemList groupedItems = 0)

Resolve frame grouping.

The group you intent to resolve may be part of the list, the plug-ins are working on. Resolving the group may change this internal loop invariant and further steps on placeholder loadins may fail. The following example tries to explain the situation:

Regrouping the sub frames to a new group does not fix the problem. In the above example, a new group reference B# is created in this case, and B' is not member of loop invariant (A, B, C, D). See the following notes for solutions :

Use frame::add_to_group if you only want to add one or more frames to an existing group.

ItemRef	newRef	= item::alloc ();
:
frame::create_textframe (newRef, 36, 36, 136, 136, page::get (gFrame), "");
frame::add_to_group (gFrame, newRef);

Use frame::regrouped to inform the plugins about group changes in more complex situations.

ItemRef		newRef		= item::alloc ();
ItemRef		oldGroup	= item::alloc ();
ItemRef		newGroup	= item::alloc ();
ItemList 	li			= itemlist::alloc();
frame::create_textframe (newRef, 36, 36, 136, 136, page::get (gFrame), ""); if (frame::get_group(gFrame, oldGroup) == 0) {   frame::ungroup(oldGroup, li);   itemlist::append(li, newRef);   frame::group(li, newGroup);
  frame::regrouped (oldGroup, newGroup); }

In this case you have to call placeholder::load and/or placeholder::build for all subframes in your script. What you have to do depends on action type, the ungroup was called:

ItemRef		oldGroup	= item::alloc ();
ItemList 	li			= itemlist::alloc();
int			i;
if (frame::get_group(gFrame, oldGroup) == 0) {   frame::ungroup(oldGroup, li);
  for (i = 0; i < itemlist::length (li); i++)   {   placeholder::load (fr, 0, -2, 0, 1);   placeholder::build (fr);   } }

Name Type Default Description
Return int   0 or ErrorCode
groupFrame ItemRef - Frame grouping to be resolved
groupedItems ItemList 0 List of frames grouped by the frame
0 : not needed
otherwise : with itemlist::alloc allocated result list
#include "internal/types.h"

The script ungroups a frame and creates a new frame aside the frames of the group. All old frames of the group and the new frame are htan grouped together to one new group. Error handling is omitted here. Real scripts should ask for error results!

 ⇒ 

#include "internal/types.h"
int main () { ItemRef groupRef = item::alloc (); ItemRef newframe = item::alloc (); ItemList grouped = itemlist::alloc (); float l, t, r, b; char lay[256];
if (gRun > 1) return 0;
if (frame::get_group (gFrame, groupRef)) { showmessage ("Rahmen nicht gruppiert."); return 0; } frame::ungroup (groupRef, grouped);
itemlist::bbox (grouped, &l, &t, &r, &b); frame::create2 (   newframe,   kStar,   r+10.0, t, r+130.0, t+120.0,   page::get (gFrame),   frame::get_layer (gFrame, lay),   0, // Spaltenanzahl   0, // vertikale Spalten   0.0, // Spaltenabstand   5, 40); frame::color_rgb (newframe, 255, 0, 0, 0); frame::stroke_rgb (newframe, 0, 0, 0, 5.0); itemlist::append (grouped, newframe);
frame::group (grouped);
return 0; }

Version 1.2.1 (25. August 2005)
Parameter groupedItems since Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

group
add_to_group
regrouped
comet.CGroup.resolve

static int group_content(ItemRef groupFrame, ItemList groupedItems)

Get a list of all frames of an InDesign®/Illustrator group.

Name Type Default Description
Return int   0 or ErrorCode
groupFrame ItemRef - group frame, see get_group
groupedItems ItemList 0 List of content, must be allocated using itemlist::alloc

Select all frames beloning to the same group as gFrame

#include "internal/types.h"
int main () { ItemRef groupRef = item::alloc (); ItemList grouped = itemlist::alloc (); ItemRef nth = item::alloc (); int i;
if (gRun > 1) return 0;
if (frame::get_group (gFrame, groupRef)) { showmessage ("Your frame is not part of an InDesign Group."); return 0; } frame::group_content (groupRef, grouped);
for (i = 0; i < itemlist::length (grouped); i++) { frame::select (itemlist::get (grouped, nth, i), false, false); }
return 0; }

Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CGroup.getMembers

static int get_group(ItemRef frameRef, ItemRef groupRef = 0)

Query the InDesign® group frame of a frame. If the frame is not a part of an InDesign® group, the function returns an error code.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - valid frame
groupRef ItemRef 0 On successful return : Reference to the InDesign group

0 : Ignore
Otherwise : With item::alloc allocated result variable

Move a frame to the top left corner of its page. If the frame is part of an InDesign® group, the entire group is moved.

int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();
item::assign (top, fr); item::assign (child, fr);
while (frame::get_group (child, parent) == 0) { item::assign (child, parent); item::assign (top, parent); }
item::release (parent); item::release (child);
return frame::is_valid (top); }
int main () { ItemRef top = item::alloc ();
if (!get_top (gFrame, top)) return 0;
frame::moveto (top, 36.0, 36.0);
return 0; }

Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.getGroup

static int regrouped(ItemRef oldGroup, ItemRef newGroup = 0)

A group was resolved and recreated. To learn more see here.

Name Type Default Description
Return int   0 or ErrorCode
oldGroup ItemRef - Resolved group
newGroup ItemRef 0 New group. May be 0 (See here to learn more in this case!

Version 3.2 R2267, 7.Feb.2011

priint:comet InDesign® Plug-Ins, comet_pdf

add_to_group
add_list_to_group
ungroup
group

static int add_to_group(ItemRef frameRef, ItemRef sibling)

Add another frame to the InDesing group to which the first frame belongs. If the first frame is not part of an InDesign group, the two frames are grouped together. See here to learn more about regroupings. The group reference of the first frame is changed by this call!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame or group reference
sibling ItemRef - Add this frame to the group.

Create four frames and create a group from these four frames and from gFrame.

int main ()
{
    ItemRef		f	= item::alloc ();
    int			r;
    int			l	= 36;
    int			t	= 36;
    int			i;
for (i = 0; i < 4; i++) { frame::create_textframe (f,   l+(i*100),   t,   l+90+(i*100),   t+200,   page::get (gFrame),   ""); frame::color_rgb (f, 56+(i*50), 128, 0); frame::add_to_group (gFrame, f); }
return 0; }

Version 3.2 R2267, 7.Feb.2011

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

is_group
regrouped
ungroup
group
group_content
add_list_to_group
comet.CGroup.addMembers

static int add_list_to_group(ItemRef frameRef, ItemList siblings)

Add a list of frames to an InDesign group. If the frame does not contain to an InDesign group, a new group is created from these frames. If the reference points to a group itself, the list of frames is added to this group. See here to learn more about regroupings. The group reference of the first frame is changed by this call!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame or group reference
siblings ItemList - Add this frames to the group.

Create four frames and create a group from these four frames and from gFrame.

int main ()
{
    ItemRef		f	= item::alloc ();
    ItemList	fl	= itemlist::alloc ();
    int			r;
    int			l	= 36;
    int			t	= 36;
    int			i;
for (i = 0; i < 4; i++) { frame::create_textframe (f,   l+(i*100),   t,   l+90+(i*100),   t+200,   page::get (gFrame),   ""); frame::color_rgb (f, 56+(i*50), 128, 0); itemlist::append (fl, f); }
frame::add_list_to_group (gFrame, fl);
return 0; }

Version 3.2 R2267, 7.Feb.2011

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

is_group
regrouped
ungroup
group
group_content
comet.CGroup.addMembers

static int inlinepos(ItemRef inlineframe)

Ascertain the text position of an inliner frame.

Name Type Default Description
Return int   Textposition oder -1
inlineframe ItemRef - Inlinerahmen

Get all inlines of the currently selected table cell.

ItemList inlines_of_cell (ItemRef frame, Table T, int row, int col)
{
    ItemList	inlines		= itemlist::inlines (frame);
    ItemList	cellframes	= itemlist::alloc ();
    ItemRef		f			= item::alloc ();
    int			start, len, pos, i;
table::cell::get_textpos (T, col, row, &start, &len);
for (i = 0; i < itemlist::length (inlines); i++) { itemlist::get (inlines, f, i); pos = frame::inlinepos (f); if (pos >= start) { itemlist::append (cellframes, f); } }
itemlist::release (inlines); return cellframes; }
int main () { int start, end, row, col; Table T = table::alloc (); ItemRef frame = item::alloc (); ItemList inlines;
textmodel::selection (&start, &end, frame, 0, T, &col, &row); if (table::is_valid (T)) { inlines = inlines_of_cell (frame, T, row, col);
wlog ("", "# %d inlines in cell [r%d, c%d]\n", itemlist::length (inlines), row, col);
itemlist::release (inlines); }
return 0; }

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf

frame::isinline
frame::textframe
frame::floating
position_visible

static int set_creationdate(ItemRef f)

Set the frame date anew. For the date the current time information of the computer will always be used.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference

Version 1.2.1 (30. August 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int wrap(
  ItemRef f,
  int mode,
  float left = -1000.0,
  float top = -1000.0,
  float right = -1000.0,
  float bottom = -1000.0)

Set the contour type and the contour spacing of a frame.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
mode int - Contour type

-1 kWrapUndef - Leave contour type unchanged
0 kWrapNone - no effect on text
1 kWrapBand - text leads past area of strip
2 kWrapNextFrame - text continues in next frame
3 kWrapBothSides - text on both sides of object
4 kWrapWithinHoles - text within holes in object
6 kWrapManualContour - text follows the standoff shape (implies kWrapBothSides)
7 kWrapLeftContour - text wraps only to the left side of the standoff
8 kWrapRightContour - text wraps only to the right side of the standoff
left float -1000.0 Left contour width
-1000.0 - Ignore

In case of using a contour, the value is set but not used anyway.
top float -1000.0 Upper contour height
-1000.0 - Ignore

In case of using a contour, the value is used as the distance around the shape.
right float -1000.0 Right contour width
-1000.0 - Ignore

In case of using a contour, the value is set but not used anyway.
bottom float -1000.0 Lower contour height
-1000.0 - Ignore

In case of using a contour, the value is set but not used anyway.
#include "internal/types.h"

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int getwrap(
  ItemRef f,
  float* left = 0,
  float* top = 0,
  float* right = 0,
  float* bottom = 0)

Ascertain the contour type and the contour spacing of a frame.

Name Type Default Description
Return int   Kontortyp

-1 kWrapUndef - Contour type could not be ascertained
0 kWrapNone - no effect on text
1 kWrapBand - text leads past area of strip
2 kWrapNextFrame - text continues in next frame
3 kWrapBothSides - text on both sides of object
4 kWrapWithinHoles - text within holes in object
6 kWrapManualContour - text follows the standoff shape (implies kWrapBothSides)
7 kWrapLeftContour - text wraps only to the left side of the standoff
8 kWrapRightContour - text wraps only to the right side of the standoff
f ItemRef - Valid frame reference
0 - use current script frame
left float* 0 Left contour width, may be 0 (ignore return value).
top float* 0 Upper contour height, may be 0 (ignore return value).
right float* 0 Right contour width, may be 0 (ignore return value).
bottom float* 0 Lower contour height, may be 0 (ignore return value).
#include "internal/types.h"

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int wrap_ignore(ItemRef f, int state)

This request sets whether or not a frame supports wrapping . The function defines, whether a frame accept text wrap from other frames, not the text wrap property of the frame itself.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
state int - 0 - turn wrapping off
otherwise - activate wrapping

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf, comet_pdf

static int getwrap_ignore(ItemRef f)

Does a frame apply text wraps or not?

Name Type Default Description
Return int   1 - Wraps enabled
0 - Status could not be ascertained or wraps ignored.
f ItemRef - Valid frame reference
0 - Use current script frame

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int wrap_invert(ItemRef f, int state)

Invert a text wrap. Text behind (or above) the given frame does not flow around the frame but goes INSIDE the frame (and, yes, if there are more than one text, the frame shows multiple text parts.).

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
state int - 0 -Use wrap normally
otherwise - use inner part of the frame as wrap

Comet_pdf does not support inverse text wraps. Calls to this function will do nothing.

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int getwrap_invert(ItemRef f)

Is the frame wrap inverted?

Name Type Default Description
Return int   1 - Wrap inverted or status could not be ascertained
0 - Wrap used as "normal"
f ItemRef - Valid frame reference
0 - Use current script frame

Version 1.2.2 (18 October 2005)

priint:comet InDesign® Plug-Ins

static int wrap_zorderbased(ItemRef f, int state)

Take care on Z order of text wrap.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
state int - 0 -Use wrap normally
otherwise - Use contour only if the frame lies above the text

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int getwrap_zorderbased(ItemRef f)

Check Z order of frame for text wrapings?

Name Type Default Description
Return int   0 : Z order is ignored or ErrorCode
1 : Yes. Text wrap is only applied for frames behind the contour.
f ItemRef - Valid frame reference
0 - Use current script frame

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int wrap_side(ItemRef f, int side)

Set options for text wraps around frames and objects.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
side int - 0 - Right and eft side
1 - Left side
2 - Right side
3 - To binding
4 - Away binding
5 - Largest line (not for comet_pdf)

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int getwrap_side(ItemRef f)

Get options for text wraps around frames and objects.

Name Type Default Description
Return int   -1 : Error 0 : Right and eft side
1 : Left side
2 : Right side
3 : To binding
4 : Away binding
5 : Largest line (not for comet_pdf)
f ItemRef - Valid frame reference
0 - Use current script frame

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int wrap_contour(
  ItemRef f,
  int type = 0,
  int pathindex = -1,
  char* pathname = 0,
  int alphaindex = -1,
  char* alphaname = 0,
  float tolerance = 0.0,
  int treshhold = 0,
  int allowholes = 0)

Set options for text wraps around images. Don't forget to call frame::wrap before setting the contour options of the image!

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
type int 0 0 : Bounding Box (not in comet_pdf)
1 : Edge detection (not in comet_pdf)
2 : Alpha channel
3 : Photoshop path
4 : Graphic Frame (not in comet_pdf)
5 : Same as clipping
pathindex int 0 0-based index of Photoshop path. comet_pdf ignores this value, please use pathname instead.
pathname String or char* 0 Name of Photoshop path. If this value is not empty, pathindex is ignored.
alphindex int 0 0-based index of alpha channle. comet_pdf ignores this value, please use alphaname instead.
alphname String or char* 0 Name of alpha channle. If this value is not empty, alphaindex is ignored.
tolerance float 5.0 0.0 - 100.0

Tolerance for edge detection (not in comet_pdf).

Edge detection based on the image or an alpha channel occurs in two steps. The first step generates a polygonal path which perfectly matches what InDesign® believes is the edge. Because the polygonal path may contain thousands of points, it is smoothed into a bezier path during the second step if tolerance is non-zero. During this smoothing step, the tolerance indicates how closely the resulting path must match A value between 0 and 100 which indicates how closely the resulting path must match the polygonal path from step 1.
treshhold int 255 0 - 255

Treshhold for edge detection (not in comet_pdf).

During edge detection of an image or alpha channel, the source pixels are converted to grayscale and then to a 1-bit bitmap. The threshhold is a value between 0 and 255. Any gray value greater than or equal to the threshold will be mapped to white. All other pixels will be mapped to black.
allowholes int 0 Allow holes in case of edge detections? (not in comet_pdf)

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int getwrap_contour(
  ItemRef f,
  int* type = 0,
  int* pathindex = 0,
  char* pathname = 0,
  int* alphaindex = 0,
  char* alphaname = 0,
  float* tolerance = 0,
  int* treshhold = 0,
  int* allowholes = 0)

Get options for text wraps around frames and objects.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef - Valid frame reference
0 - Use current script frame
type int 0 Pointer to variable for result (0 allowed):
1 : Edge detection (not in comet_pdf)
2 : Alpha channel
3 : Photoshop path
4 : Graphic Frame (not in comet_pdf)
5 : Same as clipping
pathindex int 0 Result variable for 0-based Photoshop path index, can be 0.
pathname String or char* 0 Result variable for Photoshop path name, can be 0.
alphaindex int 0 Result variable for 0-based alpha channel index, can be 0.
alphaname String or char* 0 Result variable for alpha channel name, can be 0.
tolerance float* 0 Result variable for tolerance in case of edge detection, can be 0.
treshhold int* 0 Result variable for treshhold in case of edge detection, can be 0.
allowholes int* 0 Result variable for 'allow holes' in case of edge detection, can be 0.

Version 4.0.5 R9830, 14. Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static char* gettext(
  ItemRef f,
  String str,
  int pos = 0,
  int len = -1,
  int fmt = 0,
  int showProgress = 0,
  int tmRelative = 0)

Get text content of a Text frame. The command functions analagously to the command textmodel::gettext with an additional parameter which gives the required frame.

The export can be carried out as pure text (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 :

The function requires the following Includes

#include "internal/types.h"
#include "internal/text.h"

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 kExportPlain. Use the ~Plus~-Formats (available since v3.3 R2883) to replace InDesign® variables by their current values.

Name Type Default Description
Return char*   Contents. The returned pointer can be used in functions, which expect char*-String as parameter.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

f ItemRef - Valid frame reference
0 - Use current script frame
str String - Allocated string object
position int 0 Start position
>= 0 Text position
kSelection Current cursor position
len int kEnd Number of characters that are to be retrieved
fmt int kExportPlain Export format, see here
showProgress int false Is a progress bar to be displayed for the export?
Ignored by Illustrator.
tmRelative int 0 Position and length are relative to the current placeholder or to the current text model?

0 : placeholder
1 : text model
Ignored by Illustrator.
#include "internal/text.h"
#include "internal/types.h"

Here is a very simple example:

#include "internal/types.h"
#include "internal/text.h"
int main () { String str = string::alloc ();
frame::gettext (gFrame, str); showmessage ("--%s--", str);
return 0; }

Parameter tmRelative since version 2.1 R668, 16. April 2008
~Plus~-formats since v3.3 R2883, 20.04.2012

priint:comet InDesign® Plug-Ins, comet_pdf (text format kExportPlain only), Illustrator (text format kExportPlain only)

comet.CFrame.getText

static int get_type(ItemRef f = 0, int* totalPoints = 0)

Determine the (geometric) type of a frame. The function determines whether a frame is a line, rectangle, square, etc.

Name Type Default Description
Return int   Frame Type

-1 kUndef : Unknown
0 kRectangle
1 kOval
2 kPolygon : Any polygon (including stars)
4 kSpline
5 kLine
6 kSquare
7 kCircle
f ItemRef 0 Valid frame reference

0 : Use current script frame
totalPoints int* 0 How many shape points does the frame have? If a frame consists of several paths, the corner points of the individual paths are added together.

0 : Ignore result
#include "internal/types.h"

Find an example at get_color.

Version 1.3.4 (P/R 94)
kSquare and kCircle since v4.3 R34444

priint:comet InDesign® Plug-Ins

create
create2

static float get_opacity(ItemRef f = 0, int opacType = 0)

Get the tranparency of a frame. Values are given in a range of 0.0 - 100.0.

Name Type Default Description
Return float   transparency in percents (0.0 - 100.0)
-1.0 : error
f ItemRef 0 Valid frame
0 - use current script frame
opacType int 0 What type of transparency?

0 : object
1 : contour
2 : fill
3 : content

Find an example at get_color.

Version 1.3.4 (P/R 94)
Parameter opacType since v3.3.1 R3956, 27. Jun 2013

priint:comet InDesign® Plug-Ins, comet_pdf

opacity

static int get_blendmode(ItemRef f = 0)

Get frames blend mode.

Name Type Default Description
Return int   blend mode
-1 : error
otherwise : one of hte blendmode-values at opacity
f ItemRef 0 valid frame
0 - use current script frame

Find an example at get_color.

Version 1.3.4 (P/R 94)

priint:comet InDesign® Plug-Ins

opacity

static int get_color(
  ItemRef f = 0,
  char* colName = 0,
  int* colSpace = 0,
  float* c1 = 0,
  float* c2 = 0,
  float* c3 = 0,
  float* c4 = 0,
  float* tint = 0)

Get the background color of a frame. In case of some errors, the out values of the call are leaved untouched.

Name Type Default Description
Return int   0 or ErrorCode
f ItemRef 0 valid frame
0 : current script frame
colName String or char* 0 Name of color
0 : ignore
otherwise : allocated string
colSpace int* 0 color space
0 : ignore
otherwise :
  kRGB   kCMYK   kLab
c1, c2, c3, c4 float* 0 color values
0 : ignore
otherwise :
  r, g, b on kRGB
  c, m, y, k on kCMYK
  l, a, b on kLab
tint float* 0 tint of color
0 : ignore
otherwise : 0.0 - 100.0
#include "internal/types.h"

The example queries out some frame properties.

#include "internal/types.h"
int main () { char colName[256]; int colSpace; float c1, c2, c3, c4, tint;
showmessage ("type : %d\nopacity : %f\nblendmode : %d",   frame::get_type (),   frame::get_opacity (),   frame::get_blendmode ());
if (frame::get_color (0,colName,&colSpace,&c1,&c2,&c3,&c4,&tint) == 0) { if (colSpace == kRGB) { showmessage (   "color name : %s\nR : %f\nG : %f\nB : %f\nTint : %f\n",   colName,   c1, c2, c3, tint); } else if (colSpace == kCMYK) { showmessage (   "color name : %s\nC : %f\nM : %f\nY : %f\nK : %f\nTint : %f\n",   colName,   c1, c2, c3, c4, tint); } else if (colSpace == kLab) { showmessage (   "color name : %s\nL : %f\na : %f\nb : %f\nTint : %f\n",   colName,   c1, c2, c3, tint); } else { showmessage ("unknown color space"); } } else showmessage ("Cannot detect color");
return 0; }

Version 1.3.4 (P/R 94)

priint:comet InDesign® Plug-Ins, comet_pdf

color
color_rgb
comet.CPageItem.getFillColor

static int is_inline(ItemRef frame)

Is the frame an inline?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins, comet_pdf

frame::is_graphicframe
is_textframe
is_guide
is_standoff
position_visible
comet.CFrame.isInline

static int is_directinline(ItemRef frame)

Is the frame a direct inline?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins, comet_pdf

frame::is_graphicframe
is_textframe
is_guide
is_standoff

static int is_textonpath(ItemRef frame)

Is the frame a "text on path"?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins

frame::is_graphicframe
is_textframe
is_guide
is_standoff
set_top_options
comet.CFrame.getType

static int is_graphicframe(ItemRef frame)

Is the given frame a Graphic Frame?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame
int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);
showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c); return 0; }

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins, comet_pdf

frame::is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
has_embedded_image
placeholder::path
comet.CFrame.getType

static int is_empty_graphicframe(ItemRef frame)

I the given frame an empty Graphic Frame?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame
int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);
showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c); return 0; }

Version 2.1 R1830, 9. April 2010

priint:comet InDesign® Plug-Ins, comet_pdf

is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
has_embedded_image
placeholder::path

static int has_embedded_image(ItemRef frame)

Does the given frame contain an embedded image?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame
int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);
showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c); return 0; }

Version 2.1 R1830, 9. April 2010

priint:comet InDesign® Plug-Ins, comet_pdf

is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
placeholder::path
has_image
image_getpath

static int has_image(ItemRef frame)

Does the given frame contain an image?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 3.1 R2022, 27.07.2010

priint:comet InDesign® Plug-Ins, comet_pdf

is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
placeholder::path
has_embedded_image
image_getpath

static int is_graphic(ItemRef frame)

Is the frame a graphic?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins, Illustrator

frame::is_graphicframe
is_textframe
is_guide
is_standoff
comet.CPageItem.getType

static int is_textframe(
  ItemRef frame,
  int* startPos = 0,
  int* length = 0,
  int* idx = 0,
  ItemRef firstFrame = 0)

Is the frame a textframe?

Name Type Default Description
Return int   1 : Yes
0 : No
frame ItemRef - valid frame
startPos int* 0 On successful return it contains the first text position in the frame
length int* 0 On successful return it contains the length of the text shown in the frame
idx int* 0 On successful return it contains the (0-based) frame index in the chain of the text models frames
firstFrame ItemRef 0 On successful return it contains the first frame of the chain

Get al frames of the current page an log their text frame properties.

int main ()
{
    int 		result;
    ItemList	frames	= itemlist::pageframes (-1);
    int 		len		= itemlist::length (frames);
    ItemRef		frame	= item::alloc ();
    ItemRef		frame1	= item::alloc ();
    int			i		= 0;
    int 		a, b, idx;
while (i < len) { itemlist::get (frames, frame, i++); wlog ("", "# Frame %d : ", item::getint (frame)); if (frame::is_textframe (frame, &a, &b, &idx, frame1)) { wlog ("", "%d text frame [%d, %d], first %d\n", idx+1, a, a+b, item::getint (frame1)); } else wlog ("", "not a text frame\n"); }
return 0; }

Version 1.3.4, R172 startPos, length and idx, firstFrame since version 2.1 R1166, 26. Feb. 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::is_graphicframe
is_textframe
is_guide
is_standoff
comet.CPageItem.getType

static int is_guide(ItemRef frame)

Is the frame a "guide layer"?

Name Type Default Description
Return int   1 : Yes
0 : No
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins

frame::is_graphicframe
is_textframe
is_guide
is_standoff
comet.CPageItem.getType

static int is_standoff(ItemRef frame)

Is the frame a "stand off"?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins

frame::is_graphicframe
is_textframe
is_guide
is_standoff

static int is_textinset(ItemRef frame)

Is the frame a "text inset"?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins

frame::is_graphicframe
is_textframe
is_guide
is_standoff

static int is_group(ItemRef frame)

Is the frame a group?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins, Illustrator

frame::is_graphicframe
is_textframe
is_guide
is_standoff
comet.CPageItem.getType

static int is_media(ItemRef frame)

Is the frame a media object?

Name Type Default Description
Return int   1 : yes
0 : no
frame ItemRef - valid frame

Version 1.3.4, R172

priint:comet InDesign® Plug-Ins
frame::is_graphicframe
is_textframe
is_guide
is_standoff

static int is_qrcode(ItemRef frame)

Does the frame contain a QR code?

Only frames are recognised as QR codes if their QR code was created by image::qrcode or by the menu command Object -> Generate QR Code....

Name Type Default Description
Return int   1 : Yes
0 : No
frame ItemRef - Valid frame reference

v4.1.8 R27646, 20. Oct. 2020

priint:comet InDesign® Plug-Ins

image::qrcode
comet.CPageItem.getType

static char* get_script_tag(ItemRef frame, char* key = "Label")

Find the value of a script tag of a frame.

Name Type Default Description
Return char*   Value of script tag

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frame ItemRef - valid document frame
key String or char* "Label" "Label" : Get the value shown in the panel Window:Automation:Script Label

otherwise : The value set by a prior call to set_script_tag for the given key
int main ()
{
    showmessage ("Skriptlabel : '%s'.", frame::get_script_tag (gFrame));
frame::set_script_tag (gFrame, "Hallo Paul"); frame::set_script_tag (gFrame, "Paul", "Ich");
showmessage ("Skriptlabel (Neu): '%s'.", frame::get_script_tag (gFrame)); showmessage ("Value of Ich: '%s'.", frame::get_script_tag (gFrame, "Ich"));
return 0; }

Version 1.4 R 330, 3. Apr. 2007

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CFrame.getScriptTag

static int count_script_tags(ItemRef frame)

Count the number of defined script labels of a given frame.

Standard labels used by InDesign® and the priint:priint:comet InDesign® Plug-Ins are not counted!

Name Type Default Description
Return int   Number of script labels

0 : No script labels or error
frame ItemRef - Valid document frame

Version v4.1 R21778, 16. Feb 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_nth_script_tag
comet.CFrame.getScriptTags

static int get_nth_script_tag(
  ItemRef frame,
  int nth,
  char* key,
  char* value)

Get the nth key/value pair of the script labels of a given frame.

Standard labels used by InDesign® and the priint:priint:comet InDesign® Plug-Ins are ignored by the function!

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Valid document frame
nth int - Valid index of script label
key String oder char* - Allocated String or char* for the key
value String oder char* - Allocated String or char* for the value
int main ()
{
    String		key = string::alloc ();
    String		value = string::alloc ();
    int 		n;
for (n = 0; n < frame::count_script_tags (gFrame); n++) { frame::get_nth_script_tag (gFrame, n, key, value); wlog ("", " %d : '%s' : '%s'\n", n, key, value); }
string::release (key); string::release (value);
return 0; }

Version v4.1 R21778, 16. Feb 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

count_script_tags
comet.CFrame.getScriptTags

static int set_script_tag(
  ItemRef frame,
  char* value,
  char* key = "Label",
  int type = 0)

Set the value of a script tag of a frame.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Valid document frame
value String or char* - New value (its allowed to set "" or 0 here)
key String or char* "Label" "Label" : Set the value shown in the panel Window:Automation:Script Label
type int 0 Data type of the entry. This information is used only by Illustrator®!

kInt = 1 : Integer

kFloat = 2 : Decimal point

kBool = 4 : Bool
The following input values are supported besides number strings: "true", "kTrue, "yes", "false", "kFalse", "no". The value of the entry is set to "1" or "0" accordingly always.

otherwise : String

Please note that the value value Likewise, with get_script_tag and get_nth_script_tag you always get the value as string!
#include "internal/types.h"

Set an individual image counter to the selected frame:

int main ()
{
    char		v	[512];
strcpy (v, frame::get_script_tag (gFrame, "Image number")); if (!askstring (v, "Integer number", "Image number", 0, 0, 0)) return 0; frame::set_script_tag (gFrame, v, "Image number");
return 0; }

Parameter type since v4.1.8 R27590, 5. Oct 2020 Version 1.4 R 330, 3. Apr. 2007

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CPageItem.setScriptTag

static int set_origin(ItemRef frame)

The call is part of the document synchronization. Frames of variant documents that have an equivalent in the master document are containing these UIDs in the so called Origin-ID. Locally created frame of the variant have the Origin-ID 0. Based on this information, the synchronization can recognize whether and from which frame changes are to be taken from the master document. If the frame UIDs are displayed in the document, the Origin ID is shown next to the UID:

Here the frame with the UID 300 of the varaiant points to the frame (also) with the UID 300 of the master document. In the course of time, different changes to variant and master will result in frames whose origin ID is considerably different from the local UID.

How to enable the display of frame UIDs:

  1. Open the context menu in the document with CTRL-click or right mouse button
  2. Choose menue Nails and Magnets - > Show
  3. Again open the context menu in the document with CTRL-click or right mouse button
  4. Choose menue Nails and Magnets - > Show Frame UIDs

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Valid document frame

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins, comet_pdf

get_origin
document::create_variant

static int get_origin(ItemRef frame)

Get the UUID of the frame.

Name Type Default Description
Return int   Current Origin-ID of frame

0 : Not set or error
frame ItemRef - Valid document frame

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins, comet_pdf

set_origin
document::create_variant

static int remove_image(ItemRef frameRef)

Delete an image of a grafic frame

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - valid document frame

Version 1.4 R 297

priint:comet InDesign® Plug-Ins, comet_pdf

static int remove_redundant_tags(
  ItemRef frameref = 0,
  int startPos = 0,
  int len = -1)

Clean up textplaceholders. Text attribut changes such as font, textsize, color, ... are breaking the Comet placeholders into several so called runs. The Comet plug ins are runs save. But for templates and document templates it would be a good idea, to remove this redundant information for performance reasons.

Using the application menu Plug Ins:Placeholder:Remove redundant placeholders before save users can remove redundant placeholders automatically.

The function removes all redundant placeholders from the given text or from a parts of it.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 Valid text frame

0 : script frame
startPos int 0 text start position
len int kEnd Length of text to work on or kEnd, kSelection

With kSelection you can run over the script limitations and chang esome unexpected text.
#include "internal/text.h"

Version 1.4.1 R417, 24. Jul 2007

priint:comet InDesign® Plug-Ins

textmodel::remove_redundant_tags
textmodel::gremove_redundant_tags
document::remove_redundant_tags

static int set_objectstyle(
  ItemRef frameRef,
  char* stylePath,
  int applyEmptyCatWithRoot = 0,
  int clearOverrides = 0)

Apply object style to a frame. ':' is used as path delimiter for style folders used since CS4. Styles and folders therefor must not contain ':'s.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - valid frame

0 : script frame
stylename String or char* - style (path and) name. ':' is used as path delimiter. Standard style names can accepted in English and in the language of the current InDesign® version.

"" : Set current default object style for the frame type (text or graphic)
applyEmptyCat int 0 This is an InDesign®-API wrapper. The API contains the following description : "1 if we are applying empty (unchecked) cateogories from the root style" - may it be helpfull :-)
clearOverrides int 0 +-Remover

0 : Keep overrides
1 : Clear overrides

Version 1.4.2 R612, 14. Mar 2008
clearOverrides since v3.2.3 R2630, 5. Sept. 2011
stylePath = "" since v3.2.3 R2630, 5. Sept. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_objectstyle
comet.CFrame.setObjectStyle

static char* get_objectstyle(ItemRef frameRef)

Retreive (path and) name of a frames object style.

Name Type Default Description
Return char*   (Path and) name of the object style applied to the frame
"" : No style set or error or InDesign version prior CS3

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef - valid frame

0 : script frame
doTranslate int 0 Translate standard names?

0 : No. In this case, the names of the standard styles are always returned in English. In a German InDesign® this means:
  • "[Ohne]" --> "[None]"
  • "[Einfacher Grafikrahmen]" --> "[Normal Graphics Frame]"
  • "[Einfacher Textrahmen]" --> "[Normal Text Frame]"


1 : Translate standard names into the language of the current InDesign®

v3.2.3 R2630, 5.Sept. 2011
Parameter doTranslate seit v3.4 R5627, 27. Aug 2014

priint:comet InDesign® Plug-Ins, comet_pdf

set_objectstyle
comet.CFrame.getObjectStyle

static int insert_crossref(
  int index,
  int len,
  char* name,
  int classid = 0,
  int id = 0,
  int id2 = 0,
  int id3 = 0,
  char* sid = "",
  int borderVisble = 0,
  int borderWidth = 1,
  int borderHilite = 3,
  int borderStyle = 1,
  float borderCol1 = -1.0,
  float borderCol2 = -1.0,
  float borderCol3 = -1.0,
  float borderCol4 = -1.0,
  int* delBefore = 0)

Insert a cross reference destination into a text. This destination are not allowed to overlap different Comet placeholders. It is strongly recommanded to use 0 as the destinations length, but you can use longer destinations if you want. A cross reference destination will insert one (invisible, but existing) character into the text. Position is relative to the text in frameRef.

A detailed description about Comet cross references you will find here.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid text frame
0 : Current script frame
index int - placeholder relative position of the cross reference destination
len int - Number of characters occupied by destination. It is strongly recommanded to use 0 as the destinations length! But if you want ... .
name String or char* - reference name

"" : Cross reference is used as the name
classid int 0 Class number of the object
id, id2, id3 int 0 object IDs
sid String or char* "" StringID of the object
borderVisble int 0 visible in document?

0 : No
1 : Yes
borderWidth int 1 Frame width

1 : Thin
2 : Middle
3 : Bold
borderHilite int 3 Frame type
1 : Draw reference inverted (Not supported inInDesign® , but visible in PDF export.)
2 : Inset
3 : Outline
borderStyle int 1 Frame border style. InDesign® only supports the following two values:
0 : Continuous
1 : Dashed
borderCol1, borderCol2, borderCol3, borderCol4 float -1.0 Frame color in the range of 0.0 - 100.0 (or -1.0).

First three defined : use RGB
Four defined colors - use CMYK (don't work for now, sorry)
otherwise : Orange
delBefore int* 1 Attention : Its an address!. Automatically remove a reference of same name and Comet ID at the insertion point index. On return it contains whether a reference was deleted (1) or not (0).

You will find an example under textmodel::insert_crossref. Cross references to frames will work in same way.


Version 2.1 R668, 14. April 2008

priint:comet InDesign® Plug-Ins

textmodel::insert_crossref
document::update_crossrefs
hyperlink::find
hyperlink::find1
link
w2cross-Tag
comet.CTextModel.insertCrossRef

static int getbbox_before_adapt(
  ItemRef frameRef,
  float* fbox_l = 0,
  float* fbox_t = 0,
  float* fbox_r = 0,
  float* fbox_b = 0,
  float* ibox_l = 0,
  float* ibox_t = 0,
  float* ibox_r = 0,
  float* ibox_b = 0)

Get the original bounding boxes of a frame before the current page adaption was started. In situations outside the page adaption, the function will return an error. in case of text frames, the image box values are empty.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
fbox_l, fbox_t, fbox_r, fbox_b float* 0 Original bounding box of the document frame in points (left, top, right, bottom)
ibox_l, ibox_t, ibox_r, ibox_b float* 0 Original bounding box of the image frame relativ to the document frame in points (left, top, right, bottom). Bei Textrahmen erhalten Sie die Werte 0.0.

Version 2.1 R714, 19. Mai 2008

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_display_details(
  ItemRef frameRef,
  int what,
  int stripWidths = 1,
  float* l = 0,
  float* t = 0,
  float* r = 0,
  float* b = 0)

Find out the page adaption image details. The functions returns an error in case of text frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid Graphic Frame reference
what int - What kind of details?

0 : Image details 1 (minimum)
1 : Image details 2 (maximum)
stripWidths int 1 1 : Results contain the size of the protected strips. Values are given in points from the unscaled image.

0 : Results contain the remaining image area in points in respect to current current image scaling relativ to the image frame. With an image of 300 x 300 points and 100 point wide strips on every side, the remaining rectangle is then 100, 100, 200, 200. With scale factor 50% in x and y direction, the result would be 50, 50, 100, 100.
l, t, r, b float* 0 results in points

Version 2.1 R714, 16. Mai 2008

priint:comet InDesign® Plug-Ins

static int apply_display_details(
  ItemRef frameRef,
  int refPoint,
  int xposMethod = 1,
  int yposMethod = 1,
  int canChangeLeft = 1,
  int canChangeTop = 1,
  int canChangeRight = 1,
  int canChangeBottom = 1)

Apply the display details given in the Page adaption. The function has no effect on text frames.

In the Page adaption panel you can define two display details for any image.

The inner part of the image should be visible in any situation. The green parts are optional, the orange parts are forbidden. This a call to apply_display_details you change the frames size to satisfy this conditions. To pin the frame at one position, use refPoint.

Changing the frame size in respect to the given display details can change the nail fixed distances of an image frame.

After the page adaption has changed a frame size (and before applying the display details}), you may wish to reposition the image. Use xposMethod and yposMethod in this case:
Value Description Comments
kIgnore No reposition needed
kRequiredStrips, kForbiddenStrips Use the current strip arrangment to reposition the image. If, for example, from the left green strip 10 points are visible before the resizing and from right side 20 points and the frame was resized by 9 points, the image is moved 3 points left. On calls inside a page adaption only
kRequiredStripsUniform, kForbiddenStripsUniform The strips on both sides are equal, no matter on their former widths. The center between the strips becomes the center of image. If, for example, the image frame is 9 points bigger than the minimum allowed image size, the image is positioned at 4.5 points.
kRequiredStripsProp, kForbiddenStripsProp Position the image in respect to the given strip widths. If, for example, the left strip is 10 points wide and the right 20 points and the image frame is 9 points bigger, the image is posioned at 3 points no matter how the image was positioned before.

Name Type Default Description
Return int   0 oder Fehlercode
frameRef ItemRef - Referenz auf einen Grafikrahmen
refPoint int kRefPointTopLeft In Inlinerahmen wird die Angabe ignoriert. Referenzpunkt der Skalierung

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight

kRefPointNone
xposMethod, yposMethod int kRequiredStrips Image positioning, see table below

kIgnore
kRequiredStrips
kForbiddenStrips
kRequiredStripsUniform
kForbiddenStripsUniform
kRequiredStripsProp
kForbiddenStripsProp
canChangeLeft, canChangeTop, canChangeRight, canChangeBottom int 1 Enable/Disable frame resizing at the given frame side. Required/Forbidden image parts can become invisible/visible in case of suppressing.
#include "internal/text.h"
#include "internal/types.h"

Version 2.1 R714, 20. Mai 2008

priint:comet InDesign® Plug-Ins

static int get_nail(
  ItemRef frameRef,
  int refPoint,
  int* preferMax = 0)

Is an edge or a side of a frame nailed by the page adapting tool?

Name Type Default Description
Return int   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)
frameRef ItemRef - valid frame reference
refPoint int - kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
preferMax int* 0 1 : on edge nails which prefers the maximum size change
0 : otherwise
#include "internal/types.h"
int preferMax;
wlog ("", "Nail top left : %d (%d)\n",   frame::get_nail (gFrame, kRefPointTopLeft, &preferMax),   preferMax); wlog ("", "Nail top : %d (%d)\n",   frame::get_nail (gFrame, kRefPointTopCenter, &preferMax),   preferMax); wlog ("", "Nail top right : %d (%d)\n",   frame::get_nail (gFrame, kRefPointTopRight, &preferMax),   preferMax);
wlog ("", "Nail left : %d (%d)\n",   frame::get_nail (gFrame, kRefPointLeftCenter, &preferMax),   preferMax); wlog ("", "Nail right : %d (%d)\n",   frame::get_nail (gFrame, kRefPointRightCenter, &preferMax),   preferMax);
wlog ("", "Nail bottom left : %d (%d)\n",   frame::get_nail (gFrame, kRefPointBottomLeft, &preferMax),   preferMax); wlog ("", "Nail bottom : %d (%d)\n",   frame::get_nail (gFrame, kRefPointBottomCenter, &preferMax),   preferMax); wlog ("", "Nail bottom right : %d (%d)\n",   frame::get_nail (gFrame, kRefPointBottomRight, &preferMax),   preferMax);

Version 2.1 R835, 28. July 2008

priint:comet InDesign® Plug-Ins, comet_pdf

incoming_magnets
outgoing_magnets
apply_magnets
incoming_magnets
outgoing_magnets
comet.CFrame.getNail

static int set_nail(
  ItemRef frameRef,
  int refPoint,
  int type = 0,
  int preferMax = 0)

Set or remove priint:adjust nails.

Internal use only!

You may use this function, but please note that the function is not covered by support.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference

0 : current script frame
refPoint int - kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
type int -1 0 : Remove
1 : Normal (green) nail
2 : Relative (red) nail
-1 : Toggle
preferMax int 0 Edge type, for edge nails only and ignored if type==-1

0 : prefer shorter side
1 : prefer longer side
#include "internal/types.h"

v4.0.5, R10330, 11. Mar 2016

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
comet.CFrame.setNail

static int set_magnet(
  ItemRef fromRef,
  int fromSide,
  ItemRef toRef = 0,
  int toSide = -1,
  int type = 0,
  int isWhite = 0,
  int canAlt = 0)

Set or remove magnets for priint::adjust.

span[memo4]{Internal use only!}

You may use this function, but pleae note that the function in not subject of any support.

Name Type Default Description
Return int   0 or ErrorCode
fromRef ItemRef - Valid frame reference for magnet source

0 : Current script frame
fromSide int - Start side

0 : left
1 : top
2 : right
3 : bottom
toRef ItemRef 0 Valid frame reference for magnet destination. Ignored in csse of removing magnets.
toSide int -1 Destination side

0 : left
1 : top
2 : right
3 : bottom
type int 0 0 : Remove
3 : Normal (green) magnet
4 : Relative (red) magnet

Ask frame::get_magnet_type to get the type of a magnet.
isWhite int 0 0 : Normal frame magnet
1 : Magnet to the image of the frame
canAlt int 0 0 : Replace existing magnet(s) to the destination

1 : If a magnet to the destination exists already, add the new one as an alternative.

Redirect (vertical) magnets from source to dest(s) before removing a frame.

int main ()
{
    List		in		= list::alloc ();
    List		out		= list::alloc ();
    ItemRef		fr_in	= item::alloc ();
    ItemRef		fr_out	= item::alloc ();
    int			magRef, magType, magWhite;
    int			i;
frame::incoming_magnets (in, gFrame, 1); if (list::length (in) > 0) { frame::get_magnet_reference (fr_in, gFrame, list::get (in, 0));
frame::outgoing_magnets (out, gFrame, 3);
for (i = 0; i < list::length (out); i++) { magRef = list::get (out, i);
frame::get_magnet_reference (fr_out, gFrame, magRef); magType = frame::get_magnet_type (gFrame, magRef); magWhite = frame::get_magnet_is_white (gFrame, magRef);
if (magType) { frame::set_magnet (   fr_in, 3,   fr_out, 1,   magType,   magWhite,   0); } } }
frame::remove (gFrame); return 0; }

Transfer magnets from one frame (here we take the frame with the UID 229) to another frame (gFrame in example) and finally remove the frame.

int main ()
{
    List		in		= list::alloc ();
    List		out		= list::alloc ();
    ItemRef		fr		= item::alloc ();
    ItemRef		fr_in	= item::alloc ();
    ItemRef		fr_out	= item::alloc ();
    int			magRef, magType, magWhite;
    int			i;
item::define (fr, gFrame, 229);
frame::incoming_magnets (in, fr, 1); if (list::length (in) > 0) { magRef = list::get (in, i); frame::get_magnet_reference (fr_in, fr, magRef); frame::set_magnet (   fr_in, 3,   gFrame, 1,   frame::get_magnet_type (0, magRef),   frame::get_magnet_is_white (0, magRef),   0); }
frame::outgoing_magnets (out, fr, 3); for (i = 0; i < list::length (out); i++) { magRef = list::get (out, i); frame::get_magnet_reference (fr_out, gFrame, magRef); wlog ("", "TTT %d\n", frame::get_magnet_type (0, magRef)); frame::set_magnet (   gFrame, 3,   fr_out, 1,   frame::get_magnet_type (0, magRef),   frame::get_magnet_is_white (0, magRef),   0); }
frame::remove (fr);
return 0; }

v4.0.5, R10330, 11. Mar 2016

priint:comet InDesign® Plug-Ins, comet_pdf

set_nail
incoming_magnets
outgoing_magnets
get_magnet_reference
get_magnet_type
get_magnet_is_white

static int incoming_magnets(
  List resultList,
  ItemRef frameRef,
  int side)

Get all incoming magnets of one given side of a frame.

Name Type Default Description
Return int   0 or ErrorCode
resultList List - Allocated result list. On successful return it contains references to the magnets found at the given side of the frame. Use this values in subsequent calls to get_magnet_type, get_magnet_is_white, get_magnet_is_rotation_only and get_magnet_reference.
frameRef ItemRef - valid frame reference

0 :current script frame
side int - side of interest

0 : left
1 : top
2 : right
3 : bottom

Write all magnets to the top and from the bottom of a given frame to the logfile.

int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int	i;
    int	res;
res = frame::incoming_magnets (magnets, gFrame, 1); wlog ("", "incomings @ top : %d (result = %d)\n", list::length (magnets), res); for (i = 0; i < list::length (magnets); i++) { frame::get_magnet_reference (item, gFrame, list::get (magnets, i)); wlog ("", " %d : %d\n", i+1, item::getint (item)); }
frame::outgoing_magnets (magnets, gFrame, 3); wlog ("", "outgoings @ bottom : %d (result = %d)\n", list::length (magnets), res); for (i = 0; i < list::length (magnets); i++) { frame::get_magnet_reference (item, gFrame, list::get (magnets, i)); wlog ("", " %d : %d\n", i+1, item::getint (item)); }
return 0; }

Let a frame change the width of its magnet parent. (Impossible with magnets because of a magnet circuit.) You may use this script as an adapter action of the child frame. I would prefer the situation "After adaption", but its up to you.

int main ()
{
    List		magnets	= list::alloc ();
    ItemRef		item	= item::alloc ();
    int			res;
    float		l1, t1, r1, b1;
    float		l2, t2, r2, b2;
res = frame::incoming_magnets (magnets, gFrame, 1); // oben if (res) return 0; if (list::length (magnets) == 0) return 0;
frame::get_magnet_reference (item, gFrame, list::get (magnets, 0)); // Hauptmagnet frame::bbox (gFrame, &l1, &t1, &r1, &b1); frame::bbox (item, &l2, &t2, &r2, &b2); if (r1-l1 < 10.0) return 0; if (b2-t2 < 10.0) return 0;
frame::resize (item, r1-l1, b2-t2);
return 0; }

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

static int outgoing_magnets(
  List resultList,
  ItemRef frameRef,
  int side)

Get all outgoing magnets of one given side of a frame.

Name Type Default Description
Return int   0 or ErrorCode
resultList List - Allocated result list. On successful return it contains references to the magnets found at the given side of the frame. Use this values in subsequent calls to get_magnet_type, get_magnet_is_white, get_magnet_is_rotation_only and get_magnet_reference.
frameRef ItemRef - valid frame reference

0 :current script frame
side int - side of interest

0 : left
1 : top
2 : right
3 : bottom

Write all magnets to the top and from the bottom of a given frame to the logfile.

int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int		i;
    int		res;
res = frame::incoming_magnets (magnets, gFrame, 1); wlog ("", "incomings @ top : %d (result = %d)\n", list::length (magnets), res); for (i = 0; i < list::length (magnets); i++) { frame::get_magnet_reference (item, gFrame, list::get (magnets, i)); wlog ("", " %d : %d\n", i+1, item::getint (item)); }
frame::outgoing_magnets (magnets, gFrame, 3); wlog ("", "outgoings @ bottom : %d (result = %d)\n", list::length (magnets), res); for (i = 0; i < list::length (magnets); i++) { frame::get_magnet_reference (item, gFrame, list::get (magnets, i)); wlog ("", " %d : %d\n", i+1, item::getint (item)); }
return 0; }

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

static int get_magnet_type(ItemRef frameRef, int magnetRef)

Get the type of a magnet.

Name Type Default Description
Return int   type of magnet or 0:

0 : error
3 : magnet
4 : percent magnet
frameRef ItemRef - Ignored, set this to 0.
magnetRef int - magnet reference
You may get magnet references by the functions incoming_magnets und outgoing_magnets.

Write the types of all magnets from the bottom side o a frame to the logfile.

int main ()
{
    List	magnets	= list::alloc ();
    int		i;
frame::outgoing_magnets (magnets, gFrame, 3); for (i = 0; i < list::length (magnets); i++) { wlog ("", " %d : %d\n",   i+1,   frame::get_magnet_type (gFrame, list::get (magnets, i))); }
return 0; }

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_is_white
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

static int get_magnet_is_white(ItemRef frameRef, int magnetRef)

Is a given magnet a frame or an image (white) magnet?

Name Type Default Description
Return int   0 : frame magnet
1 : image magnet
frameRef ItemRef - Ignored and can set to 0
magnetRef int - magnet reference
You may get magnet references by the functions incoming_magnets und outgoing_magnets.

See get_magnet_type for an example.

 

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_type
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

static int get_magnet_is_rotation_only(ItemRef frameRef, int magnetRef)

Is a given magnet used in format adaption or in page rotations?

Name Type Default Description
Return int   0 : frame magnet
1 : image magnet
frameRef ItemRef - Ignored and can set to 0
magnetRef int - magnet reference
You may get magnet references by the functions incoming_magnets und outgoing_magnets.

See get_magnet_type for an example.

 

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_type
get_magnet_is_white
get_magnet_reference
apply_magnets

static int get_magnet_reference(
  ItemRef resultRef,
  ItemRef frameRef,
  int magnetRef)

Is a given magnet used in format adaption or in page rotations?

Name Type Default Description
Return int   0 or ErrorCode
resultRef ItemRef - allocated variable for the resulting frame
frameRef ItemRef - valid frame reference

0 : current script frame



Unlike the functions frame :: get_magnet_type ... the frame reference is actually needed here: it is necessary to complete the definition result reference.
magnetRef int - magnet reference
You may get magnet references by the functions incoming_magnets und outgoing_magnets.

Let a frame change the width of its magnet parent. (Impossible with magnets because of a magnet circuit.) You may use this script as an adapter action of the child frame. I would prefer the situation "After adaption", but its up to you.

int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int		res;
    float	l1, t1, r1, b1;
    float	l2, t2, r2, b2;
res = frame::incoming_magnets (magnets, gFrame, 1); // top side if (res) return 0; if (list::length (magnets) == 0) return 0;
frame::get_magnet_reference (item, gFrame, list::get (magnets, 0)); // main magnet frame::bbox (gFrame, &l1, &t1, &r1, &b1); frame::bbox (item, &l2, &t2, &r2, &b2); if (r1-l1 < 10.0) return 0; if (b2-t2 < 10.0) return 0;
frame::resize (item, r1-l1, b2-t2);
return 0; }

Version 3.2 R2250, 27. Jan. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
apply_magnets

static int inline_(
  ItemRef textFrameRef,
  int pos,
  ItemRef frameRef = 0,
  int flag = 1,
  float yoff = 0.0,
  int lock = 0)

Change a frame to a text inline or anchored frame.

Name Type Default Description
Return int   0 or Error rcode
textFrameRef ItemRef - valid frame reference
pos int - Text position for inline
frameRef ItemRef 0 Frame to inline. May be emtpy if flag = 2

On successful return it contains the new frame reference.

Changed on successful return!
flag int 1 What to do, if an inline exists at the given position already?

0 - create anyway
1 - delete an recreate
2 - do not create, but change
yoff float 0.0 y-offset given in points
lock int 0 Suppress manual changes

0 : no
1 : yes

Import some templates, group an inline them.

#include "internal/text.h"
#include "internal/types.h"
int main () { DataPool pool = datapool::alloc (); ItemList frames = itemlist::alloc (); ItemRef groupRef= item::alloc (); ItemList items = 0; float l = 0.0; float t = 0.0; float r, b; int i; int textpos = 200; int res;
if (!textmodel::available ()) return 0;
// Insert some frames // You must have any templates 41 and 42 defined for (i = 41; i<43; i++) { // insert template // items is allocated automatically items = document::place_items (pool, "data", "pageitems", i, l, t);
// collect inserted frames itemlist::appendlist (frames, items);
// Get frames bbox itemlist::bbox (items, &l, &t, &r, &b); itemlist::release (items); items = 0;
t = b + 2.0; }
// Group all new frames frame::group (frames, groupRef);
// Make them an inline // groupRef will change! res = frame::inline_ (   gFrame,   textpos,   groupRef,   0,   12.3, // yoff   1); // lock wlog ("", "inline_ returns %d\n", res);
return 0; }

Version 2.1 R1145, 28. Jan 2009

priint:comet InDesign® Plug-Ins, comet_pdf

frame::inline_above
frame::anchor
frame::get_anchor
inline_
release_inline

static int inline_above(
  ItemRef textFrameRef,
  int pos,
  ItemRef frameRef = 0,
  int flag = 1,
  int halign = 3,
  float spaceBefore = 0.0,
  float spaceAfter = 0.0,
  int lock = 0)

Create an "inline above" frame at a given text position. You may use this function to change the inline properties of an existing frame too.

Name Type Default Description
Return int   0 or ErrorCode
textFrameRef ItemRef - Valid text frame reference
pos int - text position to create/change the inline frame
frameRef ItemRef 0 Frame to convert to an inline. On successful return it contains (the changed) reference to the new inline. May be empty if flag = 2 ist.
flag int 1 What to do, if the given text position already points to an inline or anchored object?

0 -create anyway
1 - delete an recreate
2 - change properties only
halign int 3 horizontal alignment

0 : right
1 : centre
2 : left
3 : text alignment
4 : torwards spine
5 : away from spine
spaceBefore float 0.0 space before the inline in points
spaceAfter float 0.0 space after the inline in points
lock int 0 prevent manual positioning

0 : no
1 : yes

Do import some Comet templates, make one InDesign® group from the imported frames and "inline" this group into a text.

#include "internal/text.h"
#include "internal/types.h"
int main () { DataPool pool = datapool::alloc (); ItemList frames = itemlist::alloc (); ItemRef groupRef= item::alloc (); ItemList items = 0; float l = 0.0; float t = 0.0; float r, b; int i; int textpos = 200; int res;
if (!textmodel::available ()) return 0;
// Add some frames to the document // Templates 41 and 42 must exist! for (i = 41; i<43; i++) { // Insert template // items is allocated automatically here items = document::place_items (pool, "data", "pageitems", i, l, t);
// Collec t all insergted frames itemlist::appendlist (frames, items);
// Next template position // After that the items list will be released. itemlist::bbox (items, &l, &t, &r, &b); itemlist::release (items); items = 0;
t = b + 2.0; }
// Grouping imported templates frame::group (frames, groupRef);
// Insert group as inline above frame // groupRef ächanges thereby! res = frame::inline_above (   gFrame,   textpos,   groupRef,   0, // 0 - Always create,   // 1 - possibly delete and create,   // 2 - create or change   4, // to spline   11.1, // space before   22.2, // space after   1); // lock wlog ("", "inline_above returns %d\n", res);
return 0; }

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

frame::inline_
frame::anchor
frame::get_anchor
inline_above
release_inline

static int anchor(
  ItemRef textFrameRef,
  int pos,
  ItemRef frameRef = 0,
  int flag = 1,
  int spine = 0,
  int ref_obj = 0,
  int ref_pt = 3,
  int xrel = 4,
  float xoff = 0.0,
  int yrel = 4,
  float yoff = 0.0,
  int keepWithin = 1,
  int lock = 0)

Make a frame an anchored frame at a text position. You may use this funtion to change the properties of an anchored frame at a given text position too.

Name Type Default Description
Return int   0 or ErrorCode
textFrameRef ItemRef - valid text frame
pos int - text position of anchored frame
frameRef ItemRef 0 Frame to convert to an anchored frame. On successful return it contains (the changed) reference to the new anchored frame. May be empty if flag = 2 ist.
flag int 1 What to do, if the given text position already points to an inline or anchored object?

0 -create anyway
1 - delete an recreate
2 - change properties only
spine int 0 Relative to spine

0 : No
1 : Yes
ref_obj int kRefPointTopLeft Object anchor

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
ref_pt int kRefPointLeftCenter reference point. Attention : Not all reference points are supported by all frame preferences!

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
xrel int 4 x relative to

0 : column edge
1 : text frame
2 : page margin
3 : page edge
4 : anchor marker
xoff float 0.0 "x-Offset" in points
yrel int 4 y relativ zu

0 : column edge
1 : text frame
2 : page margin
3 : page edge
4 : line (Baseline)
5 : line (Height of X)
6 : line (Cap height)
7 : line (Botto of Leading)
8 : line (Top of Leading)
9 : Em-Box top
10 : Em-Box centre
11 : Em-Box bottom
yoff float 0.0 "y-Offset" in points
keepWithin int 1 Keep within Top/Bottom column boundaries

0 : no
1 : yes
lock int 0 Prevent manual positioning

0 : no
1 : yes
#include "internal/types.h"

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

inline_
inline_above
get_anchor
frame::anchor

static int get_anchor(
  ItemRef textFrameRef,
  int pos,
  int len,
  int* out_pos,
  int* out_type = 0,
  ItemRef out_frameRef = 0,
  int* rel_to_spine = 0,
  int* refpoint_obj = 0,
  int* refpoint_pt = 0,
  int* xrel = 0,
  float* xoff = 0,
  int* yrel = 0,
  float* yoff = 0,
  int* keepWithin = 0,
  int* locked = 0,
  int* halign = 0,
  float* spaceBefore = 0,
  float* spaceAfter = 0,
  float* yoff_inline = 0 )

Get the properties of an inline-above or anchored frame. If an object is found at the given text position, the appropriate out varibales for the object type are filled.
Set variables, you do not need to 0.

Name Type Default Description
Return int   0 or ErrorCode Error code 0 (no error) does NOT mean, that no inline was found at the given position. No object found you can see at out_pos == -1. kein Inline oder verankerter Rahmen gefunden wurde. Ob ein solches Objekt gefunden wurde, gibt die Variable out_pos == -1 an.}
textFrameRef ItemRef - Valid frame reference
0 : Current script frame
pos int - Search for an inline in the given text range. The range ist given relative to frame, not to the placeholder.
len int - Search for an inline in the given text range (min 1). The range ist given relative to frame, not to the placeholder.
kEnd : end of text
out_pos int* 0 on return : position of the first inline object
-1 : no inline found in the given range
out_type int* 0 Object type

0 : Inline
1 : Anchored frame
2 : Inline above
out_frameRef ItemRef 0 Anchored frame. 0 or allocte before by item::alloc
rel_to_spine int* 0 Anchored frames only, out_type == 1 Relative to spine?
refpoint_obj int* 0 Anchored frames only, out_type == 1 Reference point of the object
refpoint_pt int* 0 Anchored frames only, out_type == 1 Reference point of anchor
xrel int* 0 Anchored frames only, out_type == 1
xoff float* 0 Anchored frames only, out_type == 1 x-offset in points
yrel int* 0 Anchored frames only, out_type == 1
yoff float* 0 Anchored frames only, out_type == 1 y-offset in points
keepWithin int* 0 Anchored frames only, out_type == 1 Not not move away from frame
locked int* 0 out_type == 0 | 1 | 2
halign int* 0 Inline aboves only, out_type == 2
spaceBefore float* 0 Inline aboves only, out_type == 2 given in points
spaceAfter float* 0 Inline aboves only, out_type == 2 given in points
yoff_inline float* 0 Inlines only, out_type == 0 y-offset in points
#include "internal/text.h"

Inspect all inlines of the current script frame.

#include "internal/text.h"
#include "internal/types.h"
int main () { int pos = 0; int type, rel_to_spine, refpoint_obj, refpoint_pt, xrel, yrel, keepWithin; int locked, halign; float xoff, yoff, yoff2, spaceBefore, spaceAfter; ItemRef inlineRef = item::alloc (); int res;
while (1) { res = frame::get_anchor (   gFrame,   pos,   kEnd,   &pos, // out_pos   &type,   inlineRef,   // Anchor   &rel_to_spine,   &refpoint_obj,   &refpoint_pt,   &xrel, &xoff,   &yrel, &yoff,   &keepWithin,   &locked,   // Inline_Above   &halign,   &spaceBefore,   &spaceAfter,   // Inline   &yoff2);
if (res != 0 || pos < 0) break;
if (type == 0) { // Inline wlog ("", "%d : Inline found (UID = %d)\n", pos, item::getint (inlineRef)); wlog ("", "\ty-Offset : %f\n", yoff2); wlog ("", "\tLocked : %d\n", locked); } else if (type == 1) { // Anchor wlog ("", "%d : Anchor found (UID = %d)\n", pos, item::getint (inlineRef)); wlog ("", "\tSpine : %d\n", rel_to_spine); wlog ("", "\tRefpoint Object : %d\n", refpoint_obj); wlog ("", "\tRefpoint Position : %d\n", refpoint_pt); wlog ("", "\tX Relative To : %d\n", xrel); wlog ("", "\tX-Offset : %f\n", xoff); wlog ("", "\tY Relative To : %d\n", yrel); wlog ("", "\tY-Offset : %f\n", yoff); wlog ("", "\tKeep Within : %d\n", keepWithin); wlog ("", "\tLocked : %d\n", locked); } else if (type == 2) { // Inline Above wlog ("", "%d : Inline above found (UID = %d)\n", pos, item::getint (inlineRef)); wlog ("", "\tAlign : %d\n", halign); wlog ("", "\tSpace before : %f\n", spaceBefore); wlog ("", "\tSpace After : %f\n", spaceAfter); }
pos = pos+1;
} return 0; }

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

frame::inline_
frame::inline_above
frame::anchor
get_anchor

static int release_inline(
  ItemRef inlineRef,
  float new_left = -10000.0,
  float new_right = -10000.0)

Make an inline a 'normal' frame, i.e. the frame is no longer part of the text then but a page frame. If the given frame is not an inline, the function returns an error.

Inlines that extend beyond the page can switch the page or fall entirely within the pasteboard by calling the function.

Name Type Default Description
Return int   0 or ErrorCode
inlineRef ItemRef - valid referenz to an inline. You may use get_anchor to squize out such a reference from of a text.

After successful return, inlineRef points to the new non-inline frame.
new_left, new_right float -10000.0 New frame position.

-10000.0, -10000.0 or missing : Same position like the inline

Version 2.1, R1789, 1. March 2010
Parameters new_left, new_right since v4.0.5, R10912, 19. Apr 2016
Available for InDesign® Server since v4.0.5 R12022, 11. Jul 2016

priint:comet InDesign® Plug-Ins, comet_pdf

is_inline
get_anchor
anchor
inline_above
inline_
textmodel::get_anchor
textmodel::anchor
textmodel::inline_above
textmodel::inline_

static int lock(ItemRef frameRef = 0)

Protect a frame from manual changes.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 Valid frame reference
0 : current script frame

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

unlock
is_locked
comet.CFrame.setLocked

static int unlock(ItemRef frameRef = 0)

Allow manual changes to a frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 Valid frame reference
0 : current script frame

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

lock
is_locked
comet.CFrame.setLocked

static int is_locked(ItemRef frameRef = 0)

Is the given frame locked by InDesign® ?

Name Type Default Description
Return int   0 : No
1 : Yes
frameRef ItemRef 0 Valid frame reference
0 : current script frame

Version 2.1 R1145, 28. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

lock
unlocked
comet.CFrame.getLocked

static int get_cometgroup(ItemRef frameRef, int searchHierarchy = 1)

Get the CometGroup-ID of a frame.

Name Type Default Description
Return int   Comet group ID of the frame or 0
frameRef ItemRef - Valid frame reference
0 : current script frame
searchHierarchy int 1 1 : Search document hierarchy if the frame has no group ID.

Remove all frames of any sub group of the given frame.
Since Comet 3.1 R1616 you can use the built-in function frame::remove_sub_cometgroups instead.

int remove_subgroups (ItemRef frame)
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int			mbID	= 0;
    int 		i;
if (groupID == 0) return 0;
group = itemlist::get_cometgroup_members (0, groupID, 1); if (!group) return 0;
for (i = 0; i < itemlist::length (group); i++) { mb = itemlist::get (group, mb, i); mbID = frame::get_cometgroup (mb, 0); if (mbID!=groupID) { frame::remove (mb); } }
return 0; }

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::get_cometgroup
comet.CFrame.getCometGroupID

static int get_cometgroup_member(
  ItemRef frameRef,
  char* label,
  ItemRef outMember)

Search for a frame with a given Comet label within the Comet Group of the frame. If the frame contains to a continuing group, the group is searched first.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame
label String or char* - Comet label to search for. Label can set using panel Template-Behavior and must be of length 1.
outMember ItemRef 0 Allocated ItemRef for the result (may be 0).

Search for the frame with Comet label "A" within the Comet group of gFrame.

int main ()
{
    ItemRef		member	= item::alloc ();
frame::get_cometgroup_member (gFrame, "A", member); wlog ("", "# UID of member '%s' : %d\n", "A", item::getint (member));
return 0; }

v3.2.3 R2401, 18.04.2011

priint:comet InDesign® Plug-Ins, comet_pdf

get_cometgroup
itemlist::get_cometgroup_members

static int remove_sub_cometgroups(ItemRef frameRef)

Remove all frames from any Comet subgroup of a frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 Valid frame reference
0 : current script frame

Since the function is not available for Comet 2.1, you may use this workaround:

int remove_subgroups (ItemRef frame)
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int			mbID	= 0;
    int 		i;
if (groupID == 0) return 0;
group = itemlist::get_cometgroup_members (0, groupID, 1); if (!group) return 0;
for (i = 0; i < itemlist::length (group); i++) { mb = itemlist::get (group, mb, i); mbID = frame::get_cometgroup (mb, 0); if (mbID!=groupID) { frame::remove (mb); } }
return 0; }

Version 3.1 R1616, 30.10.2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_cometgroup

static int is_member_of(
  ItemRef frameRef,
  int groupID,
  int searchHierarchy = 1)

Check whether a frame is a member (direct or via sub groups) of the given Comet Group.

Name Type Default Description
Return int   1 : Yes, is a member
0 : No, not a member
frameRef ItemRef - Valid frame reference
0 : current script frame
groupID int - Comet group ID
searchHierarchy int 1 1 : Search document hierarchy if the frame has no group ID.

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::are_members_of

static int add_to_cometgroup(
  ItemRef frameRef,
  int groupID,
  int invalidateView = 0)

Add a frame to a given Comet Group. If the frame is the parent frame of a group, the complete group is added.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame
groupID int - Comet-group ID
invalidateView int 0 Invalidate view. For preformance reasons, use 0 in build scripts.

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::add_to_cometgroup
comet.CFrame.setCometGroupID

static int remove_from_cometgroup(
  ItemRef frameRef,
  int groupID,
  int invalidateView = 0)

Remove a frame from a Comet Group. As a rule, 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 given Comet Group ID is set to -1, the frame will be deleted from any membership, otherwise only if it is a member of the given group.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame
groupID int - Comet-group ID -1 : Do not check current membership
invalidateView int 0 Invalidate view. For preformance reasons, use 0 in build scripts.

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::remove_from_cometgroup
comet.CFrame.removeFromCometGroup

static int apply_layout_rules(
  ItemRef frameRef,
  int what,
  ItemRef caller = 0,
  char* key = 0,
  char* callerData1 = 0,
  char* callerData2 = 0,
  int id = 0,
  int id2 = 0,
  int id3 = 0,
  char* sid = 0)

Execute the layout rules of a frame. You can specify which layout rules should be executed. If the layout rule type is disabled (by system::suppres_layoutrules or by the plugins in general) these rules are not executed.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame
what int - Type of layout rules to execute

2 : After loading placeholders
1 : After Create
32 : At product build up
4 : At reorganisation
8 : After geometry changes
caller ItemRef 0 Only in case of sending events: Reference to sender
key String or char* 0 Only in case of sending events: Event key
callerData1, callerData2 String or char*, String or char* "", "" Only in case of sending events: Additional data for the receiver
id, id2, id3, sid int, int, int, String or char* 0, 0, 0, "" For unlinked frames on load rules only you may provide an object ID here.

A frame has a layout rule as described:

If event "from script" then
    showmessage ("Hallo");
End

A second frame executes the following script. This will show the message provided by the first frame.

int main ()
{
    ItemRef        receiver    = item::alloc ();
item::define (receiver, gFrame, 222);// 222 - uid of first frame frame::apply_layout_rules (receiver, 15, gFrame, "from script");
return 0; }

Version 3.1, R1550, 18. Sept. 2009
Parameter caller, keycallerData1, callerData2, id, id2, id3, sid since v3.3 R3388, 7. Jan. 2013

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

system::suppress_layout_rules
system::wakeup_layout_rules
itemlist::apply_layout_rules
comet.CFrame.applyLayoutRules

static int set_top_options(
  ItemRef frameRef = 0,
  int textAlign = 4,
  int pathAlign = 3,
  int effectType = 1,
  int overlapOffset = 0,
  int flip = 0)

Set the (text on path) options.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid document frame with text on path
0 : current script frame
textAlign int 4 Text alignment - one oth the following values. Do not use other values!

1 : Ascender
2 : Descender
3 : Center
4 : Base line
5 : Above right Em box
6 : Below left Em box
7 : Above right ICF box
8 : Below left ICF box
pathAlign int 4 Path alignment - one oth the following values. Do not use other values!

1 : Top
2 : Bottom
3 : Center
effectType int 4 Effekt - one oth the following values. Do not use other values!

1 : Rainbow
2 : Skew
3 : 3D Ribbon
4 : Stair step
5 : Gravity
overlapOffset int 0 A vaue between -800 und 800.Do not use other values!
flip int 0 Flip text?

0 : No
1 : Yes

Version 2.1 R1611, 19. Oct 2009

priint:comet InDesign® Plug-Ins

is_textonpath

int get_z_order(ItemRef frameRef, int respectTo)

Get the Z order of a given frame. If the given item is a group, the group is treated as one object, all other grouped frames are handled as single objects.

Name Type Default Description
Return int   <=0 : Error
otherwise : 1-based Z order of the given frame. Frames more in the background have bigger Z orders.
frameRef ItemRef - Valid frame reference
0 : current script frame
respectTo int 0 0 :Get the Z order in respect to all frames of the spread
1 : Use only the intersecting frames to get the Z order.

Information about the Z order.

int main()
{
    wlog ("", "Z-Order (page rel) : %d\n", 	frame::get_z_order (gFrame, 0));
    wlog ("", "Z-Order 		: %d\n", 	frame::get_z_order (gFrame, 1));
    wlog ("", "in front 	: %d\n", 	frame::is_in_front (gFrame));
    wlog ("", "at back 		: %d\n", 	frame::is_at_back (gFrame));
return 0; }

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

is_in_front
is_at_back
itemlist::intersections
comet.CFrame.getZOrder

static int bring_to_front(ItemRef frameRef)

Bring the frame to the front of its page.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.moveToFront

static int bring_forward(ItemRef frameRef)

Bring forward the frame for one Z-layer.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.moveForward

static int send_backward(ItemRef frameRef)

Send backward the frame for one Z-layer.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.moveBackward

static int send_to_back(ItemRef frameRef)

Send a frame to the back.

Since version v3.3 locked frames are changed too. Versions prior v3.3 may crash InDesign® in case of locked frames. Use frame::is_locked, frame::unlock and frame::lock to check, unlock and finally relock frames in this case.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.moveToBack

static int is_in_front(ItemRef frameRef)

Is the given frame the frontmost frame on its page?

Name Type Default Description
Return int   0 : no
1 : Yes
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.isInFront

static int is_at_back(ItemRef frameRef)

Is the given frame the last frame on its page?

Name Type Default Description
Return int   0 : no
1 : Yes
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.isInBack

static int is_masteritem_overriden(
  ItemRef masterItem,
  int pgNum,
  ItemRef pageItem)

Given a parent page item, check whether it is overridden on a given document page.

Name Type Default Description
Return int   0 :not overridden, not a parent page frame, error
1 : Yes, the parent page item is overridden on the given page
masterItem ItemRef - Valid parent page item
pgNum int - 1-based page index in document
pageItem ItemRef 0 On overridden parent page items, the variable contains the according page item. May be 0, but if given, it must be allocated carefully (item::alloc).

Get the parent page items of the first document page and override the first frame. After this check both directions (from the parent page and from the document page) - all results must be equal of course.

int main ()
{
    ItemList		masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef			masterItem	= item::alloc ();
    ItemRef			pageItem	= item::alloc ();
    int				result;
itemlist::get (masters, masterItem, 0);
result = frame::override_masteritem (masterItem, 3, pageItem); wlog ("", "# Action Result Parentitem PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# IsParentOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# IsOverridenParent %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem)); wlog ("", "\n");
return 0; }

Version 2.1, R1760, 22.2.2010

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::masteritems
is_overriden_masteritem
override_masteritem
remove_masteritem_override

static int is_overriden_masteritem(ItemRef pageItem, ItemRef masterItem = 0)

Give a page item, check whether it is an overridden parent page item.

Name Type Default Description
Return int   0 : not overridden, not coming from a parent page, error
1 : Yes, it is a overridden parent page item
pageItem ItemRef - valid page item
masterItem ItemRef 0 On overridden parent page items, the variable contains the according parent page item. May be 0, but if given, it must be allocated carefully (item::alloc).

Get the parent page items of the first document page and override the first frame. After this check both directions (from the parent page and from the document page) - all results must be equal of course.

int main ()
{
    ItemList		masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef			masterItem	= item::alloc ();
    ItemRef			pageItem	= item::alloc ();
    int				result;
itemlist::get (masters, masterItem, 0);
result = frame::override_masteritem (masterItem, 3, pageItem); wlog ("", "# Action Res Parent PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# IsParentOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# IsOverridenParent %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem)); wlog ("", "\n");
return 0; }

Version 2.1, R1760, 22.2.2010

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::masteritems
is_masteritem_overriden
override_masteritem
remove_masteritem_override

static int override_masteritem(
  ItemRef masterItem,
  int pgNum,
  ItemRef newItem)

Override a given parent page item for a document page.

Attention: Single-sided parent pages on facing pages and facing parent pages on single pages are supported. But to avoid horizontal shifts of the overridden frames, spreads with more than two pages must use parent pages with at least the same number of pages. Otherwise, you must correct the horizontal shift in your scripts.

Name Type Default Description
Return int   0 or ErrorCode
masterItem ItemRef - Valid parent page item
pgNum int - 1-based page index in document
pageItem ItemRef 0 On successful return, the variable contains the according page item. May be 0, but if given, it must be allocated carefully (item::alloc).

Get the parent page items of the first document page and override the first frame. After this check both directions (from the parent page and from the document page) - all results must be equal of course.

int main ()
{
    ItemList	masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef		masterItem	= item::alloc ();
    ItemRef		pageItem	= item::alloc ();
    int			result;
itemlist::get (masters, masterItem, 0);
result = frame::override_masteritem (masterItem, 3, pageItem); wlog ("", "# Action Result ParentItem PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# ParentOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# OverridenParent %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem)); wlog ("", "\n");
return 0; }

Version 2.1, R1760, 22.2.2010

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::masteritems
is_masteritem_overriden
is_overriden_masteritem
remove_masteritem_override

static int remove_masteritem_override(ItemRef & paageItem)

Remove all overrides from a given frame. The function checks, if the given frame is an overridden parent page items and - if so - removes all local changes. If the given frame pageItem is a member of an InDesign® group, the whole group is resetted.

Name Type Default Description
Return int   0 or ErrorCode
masterItem ItemRef - Valid page item

Actually, the 'if' is not necessary in the following script.

int main ()
{
    int				result;
if (frame::is_overriden_masteritem (gFrame)) { wlog ("", "# overridden parent item selected, removing overrides\n"); result = frame::remove_masteritem_override (gFrame); wlog ("", "# result %d\n", result); } return 0; }

Version 2.1, R1760, 22.2.2010

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::masteritems
is_masteritem_overriden
is_overriden_masteritem
override_masteritem

static int copy_image(
  ItemRef source,
  ItemRef dest,
  int applyLayoutRules = 0)

Copy an image into another frame. If the destination is not a Graphic Frame, it will converted. The image is duplicated using the same position, size, rotation and skew. All effects are rebuilded. Optionally you can apply the After geometry changes to fix the image according to the given rules.

Name Type Default Description
Return int   0 oder Fehlercode
source ItemRef - Gültige Rahmenreferenz
dest ItemRef - Zielrahmen
applyLayoutRules int 1 Apply layout rules After geometry changes?

1 : Yes
0 : No
int main ()
{
    ItemRef		r1	= item::alloc ();
    ItemRef		r2	= item::alloc ();
item::define (r1, document::current (), 206); item::define (r2, document::current (), 318);
frame::copy_image (r1, r2, 1);
return 0; }

Version 3.2 R2127, 14. Sept. 2010

priint:comet InDesign® Plug-Ins

static float get_visible_area(ItemRef frameRef, int flags = 0)

Calculate the size of visible part(s) of a frame. You may use the current clipping path for images instead of the frames shape. Shapaes and clipping paths may as complex as you want. even Bézier curves are supported. The visble area of a frame is the intersection of the following areas :

As you can imagine easily, the procedure for calculating intersections and sizes of arbitrary shapes is very complex. To solve the integrals of the curve pieces (Bézier curves), some interpolations are used. This may cause an average error of 0.03 per thousand (150 times less than the allowed alcohol in alcohol-free beer).

Name Type Default Description
Return float   size of visible parts or 0.
frameRef ItemRef - valid frame reference
flags int 0 Control the calculation

kUseClippath : In case of images, use the intersection of the current image clip path and the frame shape instead of the frame shape alone. Paths may be arbitrarily complex.

kAllowHoles : Normaly holes in images are counted to the image size. You may turn off this behavior by using the kAllowHoles flag. The option is valid only if kUseClippath is active.

kCheckTransparenz : As described above, frame transparency is ignored for overlappings. Using image clip path stands in contradiction to this assumption because the whole background is treated as transparent area. Using kCheckTransparenz, the clip path is used only if the frame has
  • no background color
  • blend mode is not "normal"
  • Oopacity is less than 100.0
The option is valid only if kUseClippath is active.

kIgnoreOverlaps : Ignore frames overlaping *frameRef*. kUseMargins : Only visible parts of the frame are counted. Frame parts in the paste board are ignored. If the flag kUseMargins is set, the visible background area is shrinked to page of the frame without the page margins.
#include "internal/types.h"

The example shows a layout rule fired on every geometry change. In this case, the areas of all page frames are recalculated.

#include "internal/types.h"
int gFlags = kUseClippath+kUseMargins;
int recalc_area (ItemRef fr) { float A = frame::get_visible_area (fr, flags); char str [5000];
sprintf (str, "Visible :%f pt2\n", A); frame::replace (fr, str); wlog ("", "%d : %f square points\n", item::getint (fr), A);
return 0; } int main () { ItemList inter = itemlist::pageframes (page::get (gFrame)); ItemRef f = item::alloc (); int i;
for (i = 0; i < itemlist::length (inter); i++) { itemlist::get (inter, f, i); recalc_area (f); }
return 0; }

Version 3.2 R2210, 2. Dez. 2010

priint:comet InDesign® Plug-Ins

get_fill_level
document::get_visible_areas

static float get_fill_level(
  ItemRef frameRef,
  int flags = 0,
  float* fa = 0,
  float* fi = 0,
  float* fv = 0,
  float* fh = 0)

Calculate the size of the shape and (if available) the image of a given frame. In addition you can calculate the size of the visible and hidden image parts. The function returns the fill level of the frame in percent (0.0 - 100.0).

Name Type Default Description
Return float   fill level (0.0 - 100.0) of image frame

-1.0 : on
  • text frames
  • empty Graphic Frames
  • kCheckTransparenz an "non transparent" frame background, see parameter flags.
  • error
Except on the errors case, the shape size is calculated for every frame.
frameRef ItemRef - valid frame reference
flags int 0 Control the calculation

kAllowHoles : Normaly holes in images are counted to the image size. You may turn off this behavior by using the kAllowHoles flag.

kCheckTransparenz : As described above, frame transparency is ignored for overlappings. Using image clip path stands in contradiction to this assumption because the whole background is treated as transparent area. Using kCheckTransparenz, the clip path is used only if the frame has
  • no background color
  • blend mode is not "normal"
  • Oopacity is less than 100.0
fa float* 0 shape size given in square points
fi float* 0 image size given in square points

0.0 on text or empty Graphic Frames
fv float* 0 size of visible image parts in square points

0.0 on text or empty Graphic Frames
fh float* 0 size of hidden image parts in square points

0.0 on text or empty Graphic Frames
#include "internal/types.h"
#include "internal/types.h"
int main () { int flags = kAllowHoles + kCheckTransparenz; float fa, fi, fv, fh; float level = frame::get_fill_level (gFrame, flags, &fa, &fi, &fv, &fh);
wlog ("", "# Fill level of %d : %f\n", item::getint (gFrame), level); wlog ("", "# Shape : %f\n", fa); wlog ("", "# Image : %f\n", fi); wlog ("", "# Visible : %f\n", fv); wlog ("", "# Hidden : %f\n", fh); wlog ("", "# Free : %f\n", fa-fv);
return 0; }

Version 3.2 R2210, 2. Dez. 2010

priint:comet InDesign® Plug-Ins

get_visible_area

static int hide(ItemRef frameRef)

Hide a frame. The frame still exists in the document but isn't visible anymore. You need at least CS5 for this feature. In versions prior CS5 the function will return an error code.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid page item

0 : current script frame

Hide all Comet group siblings of a frame.

int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;
if (groupID == 0) return 0; group = itemlist::get_cometgroup_members (0, groupID, 1); if (!group) return 0;
for (i = 0; i < itemlist::length (group); i++) { mb = itemlist::get (group, mb, i);
if (item::getint (gFrame) != item::getint (mb)) { frame::hide (mb); } } }

CS5 Version 3.2 R2223, 14. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

show
is_hidden
comet.CFrame.setVisible

static int show(ItemRef frameRef, int visibility = 1)

Change the visibility state of a frame. You do not need to call this function after frame creations by frame::create, <in>-tag, inserting templates, and so on.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid page item

0 : current script frame
visibility int 1 new visibility

0 : hidden
1 : visible

CS5 Version 3.2 R2223, 14. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

hide
is_hidden
comet.CFrame.setVisible

static int is_hidden(ItemRef frameRef)

Get the curren visibility of a frame.

Name Type Default Description
Return int   1 : visible
0 : hidden or error code
frameRef ItemRef - Valid page item

0 : current script frame

CS5 Version 3.2 R2223, 14. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

show
hide
comet.CFrame.getVisible

static char* get_name(
  ItemRef frameRef,
  int nameType = 0,
  int doTranslate = 0)

Get a frames name. Names are displayed inside the layer panel.

Name Type Default Description
Return char*   Name of frame.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef - Valid page item

0 : current script frame
nameType int 0 What kind of name you wish to retrieve?

0 : user defined name. If empty, default name.
1 : default name
2 : user defined name. If not set, the result string is empty ("")
doTranslate int 0 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®.

0 : do not translate
1 : translate

Set the names of all frames of a Comet group

int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;
    char		name[2000];
    if (groupID == 0)	return 0;
    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)			return 0;
for (i = 0; i < itemlist::length (group); i++) { mb = itemlist::get (group, mb, i);
wlog ("", "# Frame %d :\n", item::getint (mb)); wlog ("", "# '%s'\n", frame::get_name (mb));
sprintf (name, "Cometgroup %d.%d", groupID, i+1); frame::set_name (mb, name);
wlog ("", "# '%s'\n", frame::get_name (mb)); } }

CS5 Version 3.2 R2223, 14. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

set_name
itemlist::pageframes
comet.CFrame.getName

static int set_name(ItemRef frameRef, char* newName = 0)

Set a frames name. Names are displayed inside the layer panel.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid page item

0 : current script frame
newName String or char* 0 New name of frame

0 or "" : Reset name to InDesign® default.

Set the names of all frames of a Comet group

int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;
    char		name[2000];
    if (groupID == 0)	return 0;
    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)			return 0;
for (i = 0; i < itemlist::length (group); i++) { mb = itemlist::get (group, mb, i);
wlog ("", "# Frame %d :\n", item::getint (mb)); wlog ("", "# '%s'\n", frame::get_name (mb));
sprintf (name, "Cometgroup %d.%d", groupID, i+1); frame::set_name (mb, name);
wlog ("", "# '%s'\n", frame::get_name (mb)); } }

CS5 Version 3.2 R2223, 14. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_name
itemlist::pageframes
comet.CFrame.setName

static int get_page_element(
  ItemRef frameRef = 0,
  int chkGroup = 0,
  int checkLeftTopOnly = 0,
  char* out_element_name = 0,
  int queryNearest = 0)

Find the page element of a given frame or its Comet group.

Name Type Default Description
Return int   1-based sequence number of the page element or -1 in case of some errors
frameRef ItemRef 0 valid frame reference

0 : current script frame
chkGroup int 0 0 : use frame only

1 : use Comet group of frame
checkLeftTopOnly int 0 0 : The whole bounding box of the frame (or its Comet group) must match the page element

1 : The top left corner of bounding box of the frame (or its Comet group) must be inside the page element
out_element_name String or char* 0 Allocated string for the name of the found page element

0 : ignore name
queryNearest int 0 Behavior on overlapping elements

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

1 : 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 checkLeftTopOnly == 1.

Get the page element of a frame by checking its top left corner.

int main ()
{
    char		ename [2000];
    int			seq;
seq = frame::get_page_element (gFrame, 0, 1, ename);
wlog ("", "# Frame %d\n", item::getint (gFrame)); wlog ("", "# Element : %d (%s)\n", seq, ename);
return 0; }

Version 3.2 R2267, 8. Feb. 2011
queryNearest since v4.0.5 R20456, 10. Oct. 2017

priint:comet InDesign® Plug-Ins, comet_pdf

productlist::get_established
get_template
get_chapter_id
get_smart_item_data
datapool::get_main_template
datapool::get_template_name
comet.CFrame.getPageElement

static int get_template(ItemRef frameRef = 0, char* out_template_name = 0)

Find the template that inserted a frame into the document.

Name Type Default Description
Return int   template ID or 0 in case of some errors
frameRef ItemRef 0 valid frame reference

0 : current script frame
out_element_name String or char* 0 Allocated string for the name of the found template

0 : ignore name
int main ()
{
    char		ename [2000];
    int			tid;
    int			ttid, l, m, r, cl, cm, cr;
tid = frame::get_template (gFrame); ttid = datapool::get_main_template (tid, &l, &m, &r, &cl, &cm, &cr);
wlog ("", "# Frame %d\n", item::getint (gFrame)); wlog ("", "# Template : %d of %d (%s) with [%d, %d, %d, %d, %d, %d]\n", tid, ttid, datapool::get_template_name (tid), l, m, r, cl, cm, cr);
return 0; }

Version 3.2 R2267, 8. Feb. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

productlist::get_established
get_page_element
get_chapter_id
get_smart_item_data
datapool::get_main_template
datapool::get_template_name
comet.CFrame.getTemplate

static int get_chapter_id(ItemRef frameRef = 0)

Find the chapter id of a frame. Chapter IDs are defined to support page breaks while establishing products.

Name Type Default Description
Return int   template ID or 0 in case of some errors
frameRef ItemRef 0 valid frame reference

0 : current script frame

Version 3.2 R2267, 8. Feb. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

productlist::get_established
get_page_element
get_template
get_smart_item_data
datapool::get_main_template
datapool::get_template_name

static int get_smart_item_data(
  ItemRef frameRef = 0,
  char* label = 0,
  int* seq = 0,
  int* type = 0,
  int* prerule = 0,
  int* forTextflow = 0,
  int* forBuild = 0,
  int* flags = 0,
  int* nettoAreaType = 0)

Get the frame properties to support products buildings. Set this properties using the panel 'Template behavior'.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame reference

0 : current script frame
label String or char* 0 frame label
seq int* 0 sequence number
type int* 0 Type

0 : normal
1 : can continue
2 : repeat (not supported for now)
3 : can continue but do not change its height
prerule int* 0 rule to execute before inserting template

-3 :new right page
-2 : new left page
-1 : new page
forTextflow int* 0 Use this frame in text flows?

0 : insert text content
1 : insert as inline
2 : do not use
forBuild int* 0 Use for builds?

0 : yes
1 : do not use
2 : use but ignore on reorganizations
flags int* 0 Bit field with additional infos

0x00000001 : Load frame placeholder
0x00000002 : Load text placeholder
nettoAreaType int* 0 Area type

0 : Bounding Box
1 : Path (star)
2 : Path with holes (empty star)
3 : ignore (minus)
int main ()
{
    char			label [128];
    int 			seq, type, prerule, text, build;
strcpy (label, ""); frame::get_smart_item_data (gFrame, label, &seq, &type, &prerule, &text, &build); wlog ("", "# Frame %d\n", item::getint (gFrame)); wlog ("", "# Label : '%s'\n", label); wlog ("", "# Seq : %d\n", seq); wlog ("", "# Type : %d\n", type); wlog ("", "# Pre : %d\n", prerule); wlog ("", "# Text : %d\n", text); wlog ("", "# Build : %d\n", build);
return 0; }

Version 3.2 R2267, 8. Feb. 2011
Parameter flags und nettoAreaType since v3.3 R3237, 25.10.2012

priint:comet InDesign® Plug-Ins, comet_pdf

productlist::get_established
get_page_element
get_template
get_chapter_id
datapool::get_main_template
datapool::get_template_name
placeholder::sget_value
placeholder::change_tags
comet.CFrame.getSmartItemData

static int set_smart_item_data(
  ItemRef frameRef = 0,
  char* label = 0,
  int seq = -1,
  int type = -1,
  int prerule = -1,
  int forTextflow = -1,
  int forBuild = -1,
  int flags = -1,
  int nettoAreaType = -1)

Set the frame properties to support products buildings. Be extremely careful while changing this values!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame reference

0 : current script frame
label String or char* 0 New frame label. Only the first character of the string is used.

0 : do not change
seq int -1 sequence number

-1 : do not change
type int -1 Type

-1 : do not change
0 : normal
1 : can continue
2 : repeat (not supported for now)
3 : can continue but do not change its height
prerule int -4 rule to execute before inserting template

-4 : do not change
-3 :new right page
-2 : new left page
-1 : new page
forTextflow int -1 Im Textfluss benutzt?

-1 : do not change
0 : insert text content
1 : insert as inline
2 : do not use
forBuild int -1 Use for builds?

-1 : do not change
0 : yes
1 : do not use
2 : use but ignore on reorganizations
flags int -1 Bit field with additional infos

-1 : do not change
0x00000001 : Load frame placeholder
0x00000002 : Load text placeholder
nettoAreaType int -1 Area type

-1 : do not change
0 : Bounding Box
1 : Path (star)
2 : Path with holes (empty star)
3 : ignore (minus)

v3.3 R3237, 25.10.2012

priint:comet InDesign® Plug-Ins, comet_pdf

frame::get_smart_item_data
placeholder::sget_value
placeholder::change_tags
comet.CFrame.setSmartItemData

static int change_rule_param(int index, char* str)

Change a parameter of a layout rule. The function has an effect only on layout rules. Parameter values must be not longer than 5000.

You may change gParam1, ..., gParam4 directly inside a layout rule. But this changes are not taken to the document. Subsequent calls to the rule will use the unchanged old parameters. Using change_rule_param you change the parameter directly inside the document.

Attention : change_rule_param will also change your local copie of the parameter value gParam1, ..., resp. gParam4.

Name Type Default Description
Return int   0 or ErrorCode
index int - 1-4 for the appropriate parameter
str String or char* - New value. Attention : change_rule_param will also change your local copy of the parameter value gParam1, ..., resp. gParam4.

Everytime the rule is executed, parameter 2 is increased by 1. Parameter 2 must be intiated by an integer.

int main ()
{
    frame::change_rule_param (2, itoa (val (gParam2)+1));
    return 0;
}

Change the image placement on every call of the rule. Parameter 1 must be intiated by an integer in the range 1-9.

int main ()
{
    int 			alig	= val (gParam1);
alig = alig + 1; if (alig > 9) alig = 1;
frame::fit_image (gFrame, 5, alig, 195.0);
wlog ("", "111 : %s\n", gParam1); frame::change_rule_param (1, itoa (alig)); wlog ("", "222 : %s\n", gParam1);
return 0; }

Version 3.2.3 R2310, 26.04.2011

priint:comet InDesign® Plug-Ins

static int shows_textend(ItemRef frameRef)

Does the frame contain the end of the text?

Name Type Default Description
Return int   -1 : Error

0 : No (Frame has an overset or is linked together with another text frame.)

1 : Yes, text ends here.

2 : Frame does not contain text (This happens in a text frame chain with more frames than text.)
frameRef ItemRef 0 valid frame reference

0 : current script frame

Version 3.2.3 R2312, 29.04.2011

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

textmodel::overset

static int to_interactive(
  ItemRef frameRef,
  ItemRef out_mso,
  int* out_state)

DEPRECATED! Please use the function interactive::get instead.

Name Type Default Description
Return int   0 or ErrorCode

Please use the function interactive::get instead.

static int get_multistate(
  ItemRef frameRef,
  ItemRef out_mso,
  int* out_state)

Deprecated! Please use the function interactive::get instead.

Name Type Default Description
Return int   0 or ErrorCode

Please use the function interactive::get instead.

static int set_area_build_parameter(
  ItemRef frameRef,
  int parameterType,
  int value)

Set a layoutparameter for the area build mode.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference

0 : current frame
parameterType int - Which layout parameter should be set?
  • 0: No
  • 1: Yes
Value Layout parameter which is being set Possible values for value Data type
0 Build mode
Changing this parameter causes the other alignment parameters to reset to their default values.
  • 0: Row by row
  • 1: Column by column
int
1 Horizontal direction
  • 0: Left to right
  • 1: Right to left
2 Vertical direction
  • 0: Top to bottom
  • 1: Bottom to top
3 Internal row/column alignment:
First row/column
  • 0: Top/Left
  • 1: Centered
  • 2: Bottom/Right
4 Internal row/column alignment:
Intermediate rows/columns
  • 0: Top/Left
  • 1: Centered
  • 2: Bottom/Right
5 Internal row/column alignment:
Last row/column
  • 0: Top/Left
  • 1: Centered
  • 2: Bottom/Right
6 Row/Column alignment to frame
First row/column
  • 0: Left/Top
  • 1: Centered
  • 2: Right/Bottom
  • 3: Justify Horizontally/Vertically
7 Row/Column alignment to frame
Intermediate rows/columns
  • 0: Left/Top
  • 1: Centered
  • 2: Right/Bottom
  • 3: Justify Horizontally/Vertically
8 Row/Column alignment to frame
Last row/column
  • 0: Left/Top
  • 1: Centered
  • 2: Right/Bottom
  • 3: Justify Horizontally/Vertically
9 Row/Column distribution in frame
  • 0: Top/Left
  • 1: Centered
  • 2: Bottom/Right
  • 3: Justify Vertically/Horiontally
10 X Minimum distance float
11 Y Minimum distance
12 Make invisible int
value int/float - New value - the data type of this parameter is dependend on the parameter type(see table parameterType above).

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building
frame::get_area_build_parameter

static int get_area_build_parameter(ItemRef frameRef, int parameterType)

Get a layoutparameter for the area build mode.

Name Type Default Description
Return int/float   Value of the queried parameter. Data type depends on the queried parameter (See table at frame::set_area_build_parameter).
frameRef ItemRef - Valid frame reference

0 : current frame
parameterType int - Which layout parameter should be gotten? See table at frame::set_area_build_parameter

Get the area build mode of the current frame (Row/Column)

int main()
{
    int 	mode = -1;
mode = frame::get_area_build_parameter(gFrame, 0); if (mode == 0) { showmessage("Frame is in row build mode"); } else if (mode == 1) { showmessage("Frame is in column build mode"); } else { showmessage("Failed to get mode from frame"); }
return 0; }

Get the X minimum distance of the current frame (float-value)

int main()
{
    float xDistance = -1.0;
xDistance = frame::get_area_build_parameter(gFrame, 10); if (xDistance >= 0.0) { showmessage("Frame has minimum x distance of %.2fpt set", xDistance); }
return 0; }

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building
frame::set_area_build_parameter

static int is_area_build_masterframe(ItemRef frameRef)

Determines wether the frame is the first element of an area build frame chain.

Name Type Default Description
Return int   0 (No) or 1 (Yes)
frameRef ItemRef - Valid frame reference

0 : current frame

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int add_to_area_build_chain(ItemRef frameOfExistingChain, ItemRef frameRef)

Adds a frame to an area build frame chain.

Name Type Default Description
Return int   0 oder Fehlercode
frameOfExistingChain ItemRef - Frame of an existing area build frame chain or frame with area build placeholder
frameRef ItemRef - Valid frame reference

0 : current frame

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int remove_from_area_build_chain(ItemRef frameRef)

Removes a frame from an area build chain.

Name Type Default Description
Return int   0 oder Fehlercode
frameRef ItemRef - Valid frame reference

0 : current frame

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int get_area_build_order(ItemRef frameRef)

Get the order of a frame inside an area build frame chain. The result is a multiple of ten or -1 (Frame does not belong to a frame chain).

Name Type Default Description
Return int   Order number inside the frame chain (-1 = Frame does not belong to a chain. 0 = Frame is parent frame of the chain).
frameRef ItemRef - Valid frame reference

0 : current frame

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int move_in_area_build_order(ItemRef frameRef, int moveUp)

Moves a frame inside the order of an area build frame chain. Does not work on the first frame of the chain or when moving a frame inside the order is not possible (e.g. Moving the last frame in the chain downwards).

Name Type Default Description
Return int   0 oder Fehlercode
frameRef ItemRef - Valid frame reference

0 : current frame
moveUp int - Move frame up or down?

0: Down
1: Up

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int get_area_build_chain_members(ItemRef frameRef, ItemList memberList)

Moves a frame inside the order of an area build frame chain. Does not work on the first frame of the chain or when moving a frame inside the order is not possible (e.g. Moving the last frame in the chain downwards).

Name Type Default Description
Return int   0 oder Fehlercode
frameRef ItemRef - Valid frame reference

0 : current frame
memberList ItemList - A list allocated with itemlist::alloc for the results. When the list remains empty the frame does not belong to a frame chain.

Version 4.1 R14700

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int reorganize_area_build_frames(ItemRef frameRef)

Reorganizes the already built repeating elements in an area build chain. Elements which no longer fit into the layout frames are deleted from the document.

Name Type Default Description
Return int   0 oder Fehlercode
frameRef ItemRef - First layout frame of an area build chain.

0 : current frame

Version 4.1 15678

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int get_area_build_placed_into(ItemRef frameRef)

Get the layout frame in which an element frame was placed during an area build process. The result can be ascertained using two methods:

Build information: Get the layout frame which the element frame was placed into during area build

Geometry: Get the first layout frame of the layout frame chain which completely contains this element frame.

Name Type Default Description
Return int   ErrorCode or 0
resultFrame ItemRef - Reserved memory for the result.
inputFrame ItemRef - Frame of the element.
mode int 0 Mode

0: Build information
1: Geometry

Version 4.1 21612

priint:comet InDesign® Plug-Ins, comet_pdf

Documentation for area building

static int get_printable(ItemRef frameRef = 0)

Printability* of frames.

*) "Printability" means printing and PFD exports.

Name Type Default Description
Return int   Frame printable?
1 : yes
0 : no
frameRef ItemRef 0 Valid frame

0 : current frame

v3.3 R2800, 21. Feb. 2012

priint:comet InDesign® Plug-Ins

document::get_notes_printable
document::set_notes_printable
comet.CFrame.getPrintable

static int set_printable(ItemRef frameRef = 0, int newState = 0)

Set the printability* of a frame.

*) "Printability" means printing and PFD exports.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame reference

0 : current frame
newState int 0 Printability
0 : Do not print or export to PDF
1 : Print and export to PDF

Toggle the print state of a frame.

int main ()
{
    frame::set_printable (gFrame, !frame::get_printable (gFrame));
    return 0;
}

v3.3 R2800, 21. Feb. 2012

priint:comet InDesign® Plug-Ins

document::get_notes_printable
document::set_notes_printable
comet.CFrame.setPrintable

static int store_magnet_distances(ItemRef frames)

Save magnet distances of a frame and all frames reachable from this frame.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - valid frame

0 : current script frame
int main ()
{
    frame::store_magnet_distances (0);
    return 0;
}

v3.3 R850, 29.03.2012

priint:comet InDesign® Plug-Ins

itemlist::store_magnet_distances

static int set_corner(
  ItemRef frameRef = 0,
  int corner = 0,
  int type = 0,
  float radius = 0.0)

Set corner options of a frame. To define the line ends (line cap) and how the lines joind (join type) please use the functions color, color_rgb or color_cmyk.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame

0 : current script frame
corner int 0 Corner of interest

0 :alle corners

Following setting will work from CS5 only.

1 : left top
2 : right top
3 : left bottom
4 : right bottom
type int 0 Corner type

0 : plain
1 : rounded
2 : inverse rounded
3 : inset
4 : bevel
5 : fancy
radius float 0.0 Radius in points

v3.3 R3136, 29.08.2012

priint:comet InDesign® Plug-Ins, comet_pdf

get_corner

static int get_corner(
  ItemRef frameRef = 0,
  int corner = 0,
  int* type = 0,
  float* radius = 0)

Get corner options of a frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame

0 : current script frame
corner int 0 Corner of interest

0 : All corners. This only works if all corners having the same settings.
1 : left top
2 : right top
3 : left bottom
4 : right bottom
type int* 0 After successful return it contains the type of the corner

0 : plain
1 : rounded
2 : inverse rounded
3 : inset
4 : bevel
5 : fancy
radius float* 0.0 After successful return it contains the radius of the corner in points

v3.3 R3136, 29.08.2012

priint:comet InDesign® Plug-Ins, comet_pdf

set_corner

static int apply_magnets(
  ItemRef frame = 0,
  int applyRules = 0,
  int applyBuildActions = 1)

Apply magnets of a given frame. Recursive updating of all frames depending on the given frame.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame

0 : current script frame
applyRules int 0 Apply adapter rules of frames?

0 : No
1 : Yes
applyBuildActions int 1 Apply rules of type "While building products" of frames?

0 : No
1 : Yes

v3.3 R4100, 1. Aug. 2013

priint:comet InDesign® Plug-Ins, comet_pdf

Parameter applyRules and applyBuildActions since v4.0.5 R11000
get_nail
incoming_magnets
outgoing_magnets
get_magnet_type
get_magnet_reference
comet.CFrame.applyMagnets

static int apply_magnet_rules(
  ItemRef frame,
  int actionType,
  int actionIndex)

Apply adapter rules of a given frame.

The global variables gPage~Org, gPage~New, g~Resize~, gOrgFrame~, gLastFrame~, gOrgImage~ defined in this scripts are depending on the current page size changes and may have invalid values here!

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 valid frame

0 : current script frame
actionType int - Apply rules of the given type:

1 : Before adaption
2 : After move
3 : After resize
4 : After adaption
6 : While building products
actionIndex int - Index of rule in frame

-1 : Apply all rules of the given type

otherwise : 0-based index of rule. Action type is ignored in this case. If the given rule is diabled, it is executed anyway. You may use this behavior, to define rules execute only from this function but ignored by any adaption.

v4.0.5 R11000, 21. Apr 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int rmv_magnets(ItemRef frame, int full_closure = 0)

Remove all nails, magnets and adapter script from all frames of a given list.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - valid frame
full_closure int 0 0 : only this frame

otherwise : Clean magnets in all frame available by magnets from the given frame

v3.4 R5356, 2. Jul 2014

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::rmv_magnets

static int is_note(ItemRef frame = 0)

Is the given frame a Comet note or not?

Name Type Default Description
Return int   0 : No Comet note or error
1 : Yes, the frame is a Comet note
frameRef ItemRef 0 valid frame

0 : current script frame

v3.3 R2310, 3. Feb 2011

priint:comet InDesign® Plug-Ins

static int write_frame_info(ItemRef document, ItemRef frame)

Write information about a frame into the data sources. This can overwrite existing frame info entries. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frame ItemRef - Frame
frameSearchFlags int kUseDefault How should frame infos to overwrite be identified?
Combination of the following flags:
kUseDefault (kUseTemplateId + kUseFrameLabel + kUseRecordStringId + kUseBuildByRecordStringId)
kUseTemplateId
kUseFrameLabel
kUseRecordStringId
kUseBuildByRecordStringId
kUsePlaceholderId
kUseFrameType
kUseScriptTags
kUseRecordStringId
kUseFrameUID
kUsePlaceholderInfo1
kUsePlaceholderInfo2
kUseFrameInfoId Use the value of the scripttag "frameInfoId"
kUseRecordId
kUseRecordId2
kUseRecordId3
kUseBuildByRecordId
kUseBuildByRecordId2
kUseBuildByRecordId3
documentType int kLocalDoc In which document scope should we search for existing frame infos?
kLocalDoc
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
kThrowError Leaves the frame info entry unchanged and puts an error message into the logfile.
kUseLatest Overwrites the frame with the most recent update date.
#include "internal/frameinfos.h"

Write the current frame

int main ()
{
    return frame::write_frame_info(gDocument, gFrame);
}

v4.0.5

priint:comet InDesign® Plug-Ins, comet_pdf

frame::apply_frame_info

static int apply_frame_info(
  ItemRef document,
  ItemRef frame,
  int propertyFlags,
  int searchType,
  int documentType,
  StringList keyValues = 0)

Restore saved information about a frame from the data sources and set it back to the frame. More information at Frame infos

Name Type Default Description
Return int   0 oder ErrorCode
document ItemRef - Document
frame ItemRef - Frame
propertyFlags int - Which information should be restored?
Combination of the following flags:
kApplyScriptTags
kApplyPage
kApplyLayer
kApplyXPosAbs
kApplyYPosAbs
kApplyXPosRel : Not possible when kApplyXPosAbs is set!
kApplyYPosRel : Not possible when kApplyYPosAbs is set!
kApplyWidth
kApplyHeight
kApplyFrameRotate
kApplyFrameSkew
kApplyImageXOffset : Only for Graphic Frames
kApplyImageYOffset : Only for Graphic Frames
kApplyImageXScale : Only for Graphic Frames
kApplyImageYScale : Only for Graphic Frames
kApplyImageRotate : Only for Graphic Frames
kApplyImageSkew : Only for Graphic Frames
kApplyObjectStyle
frameSearchFlags int kUseDefault How should the stored frame be identified?
Combination of the following keywords:
kUseDefault (kUseTemplateId + kUseFrameLabel + kUseRecordStringId + kUseBuildByRecordStringId)
kUseTemplateId
kUseFrameLabel
kUseRecordStringId
kUseBuildByRecordStringId
kUsePlaceholderId
kUseFrameType
kUseScriptTags
kUseRecordStringId
kUseFrameUID
kUsePlaceholderInfo1
kUsePlaceholderInfo2
kUseFrameInfoId Use the value of the scripttag "frameInfoId"
kUseRecordId
kUseRecordId2
kUseRecordId3
kUseBuildByRecordId
kUseBuildByRecordId2
kUseBuildByRecordId3
documentType int kLocalDoc How should the document source be identified?
kLocalDoc
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
kThrowError Leaves the frame unchanged and puts an error message into the logfile.
kUseLatest Uses the frame info with the most recent update date.
#include "internal/frameinfos.h"

Restore frame geometry of the current frame

#include "internal/frameinfos.h"
int main () { int propertyFlags = kApplyXPosAbs   + kApplyYPosAbs   + kApplyWidth   + kApplyHeight   + kApplyFrameRotate   + kApplyFrameSkew;
return frame::apply_frame_info(gDocument, gFrame, propertyFlags, kUseDefault, kLocalDoc); }

Restore all properties of the current frame

#include "internal/frameinfos.h"
int main () { int propertyFlags = kApplyScriptTags   + kApplyXPosAbs   + kApplyYPosAbs   + kApplyWidth   + kApplyHeight   + kApplyFrameRotate   + kApplyFrameSkew   + kApplyImageXOffset   + kApplyImageYOffset   + kApplyImageXScale   + kApplyImageYScale   + kApplyImageRotate   + kApplyImageSkew;
return frame::apply_frame_info(gDocument, gFrame, propertyFlags, kUseDefault, kLocalDoc); }

v4.0.5

priint:comet InDesign® Plug-Ins, comet_pdf

frame::write_frame_info
itemlist::write_frame_info
itemlist::write_frame_info2
document::write_frame_info

static int delete_frame_info(
  ItemRef docRef,
  ItemRef frameRef,
  int frameSearchFlags = kUseDefault,
  int documentType = kLocalDoc,
  int conflictBehavior = kThrowError)

Delete frame infos from the data sources
More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frame ItemRef - Frame
frameSearchFlags int kUseDefault How should the stored frame be identified?
See frame::apply_frame_info
documentType int kLocalDoc How should the document source be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
Siehe frame::apply_frame_info
#include "internal/frameinfos.h"

Delete the frame infos of the current frame from the data sources

#include "internal/frameinfos.h"
int main () { if (gRun > 1) { return 0; } frame::delete_frame_info(gDocument, gFrame);
return 0; }

v4.0.5 R8650

priint:comet InDesign® Plug-Ins, comet_pdf

frame::write_frame_info
frame::apply_frame_info
itemlist::delete_frame_info
itemlist::delete_frame_info2
document::delete_frame_info

static int set_frameinfoid(ItemRef frame, char* value)

Sets the script tag with the key "frameInfoId" to the specified value

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame for which the tag should be set.
value String or char* - New value of the tag

v4.0.5 R8423

priint:comet InDesign® Plug-Ins

frame::apply_frame_info
frame::get_frameinfoid

static char* get_frameinfoid(ItemRef frame)

Returns the value of the script tag with the key "frameInfoId".

Name Type Default Description
Return char*   Value of the tag
frameRef ItemRef - Frame from which the tag should be gotten.

v4.0.5 R8423

priint:comet InDesign® Plug-Ins

frame::apply_frame_info
frame::set_frameinfoid

static int prepare_translations(
  ItemRef frameRef,
  int placeholderID,
  int autoStore,
  int get_record_id_func,
  IDType recordID,
  int behavior = 0)

Like document::prepare_translations, but the function works in the text model of the given frame only.

Even if the frame is part of a text chain, the complete text is processed. Calling the function in a loop of a list frames therefor may change the text multiple times.

Please not, that the the example given in document::prepare_translations will work only insufficently for frames: The record will start at 100 for every call. To avoid this problem, use a globale variable here instead of the fix value.

v4.0.4 R8160, 18 Jun 2015

priint:comet InDesign® Plug-Ins

document::prepare_translations

static int link_with_unique_placeholder(
  ItemRef frameRef,
  int placeholderID,
  int autoStore,
  int get_record_id_func,
  IDType recordID)

Synonym for prepare_translations.

prepare_translations

static int export_embedded_image(
  ItemRef frameRef,
  char* path,
  char* outpath)

Export an embedded image into a file.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame

0 : Current script frame
path String or char* - Complete path of the image file. Existing files are overridden.
outpath String or char* 0 Different embedded images can have different image formats. Therefor the image path given in path can auomatically be extentend with the appropriate format extension

0 : Suppress adding extensions
allocated string : Add or replace the format extension. On successful return, outpath contains the complete path of the generated file.

v4.0.5 R9813, 8 Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int export_html(
  char* outputFolder,
  char* outputName,
  int startPos = 0,
  int length = -1,
  int copyImages = 0,
  char* resultString = 0,
  char* title = 0,
  char* css = 0,
  int flags = 0)

DEPRECATED! Please use the function html::export_ instead.Export the textmodel as an HTML file. Style information is put into a seperate .css file into a subfolder in the target folder. More information can be found here.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef 0 Frame
outputFolder String or char* - Target folder
outputName String or char* - Name of the target file (without extension)
startPos int 0 Start index in the text model
length int -1 Length in the text model (-1 = until the end)
copyImages int 0 Just link images or copy them? (0 = link, 1 = copy)
resultString String or char* 0 Write the result to this string - when provided prevents writing to file
title String or char* 0 Title for the html document (uses the filename by default)
css String or char* 0 Use this as CSS (Either a path to a CSS file or a string containing styles)
flags int 0 Additional export options
Combination of the following flags:
kExportUnsupported (Non HTML-supported image formats are exported as .png)
kExportNonExisting (Non existing images are exported as .png from the previews)
#include "internal/types.h"

Please use the function html::export_ instead.
4.0.5 R13882

priint:comet InDesign® Plug-Ins
textmodel::export_html

static int has_linked_url(ItemRef frameRef = 0, char* used_url = 0)

Does a frame have a Web Image? General information about Web Images can be found here.

Name Type Default Description
Return int   0 : No or error
1 : Yes
frameRef ItemRef 0 Valid frame reference

0 : current script frame
used_url char* or String 0 On return, it contains the URL of image. Alloctaed char* or String or 0

v.4.0.5 R19777 (24. Jul 2017)
Parameter used_url seit v4.1 R23560 (16. Aug 2018)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::linked_urls
document::linked_urls

static int has_embedded_url(ItemRef frameRef)

Check whether a frame has an embedded Web Image. General information about Web Images can be found here.

Name Type Default Description
Return int   0 : No or error
1 : Yes
frameRef ItemRef - Valid frame.

0 : current script frame

v4.0.5 R19777, 20. Jul 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
itemlist::embedded_urls
document::embedded_urls

static int link_url(
  ItemRef frameRef,
  char* url,
  int alignment = 5,
  float boundingBox = 0.0,
  int pathindex = -2,
  char* pathname = nil,
  int flags = 0,
  int cliptoFrame = 0,
  float tolerance = 0.0,
  float minPathSize = 0.0,
  float inset = 0.0,
  int alphaIndex = -2,
  char* alphaChannel = nil,
  int treshold = 255,
  int updateFlags = 16)

Place a URL based file into a frame. The URL is downloaded and then linked into the document. General information about Web Images can be found here.

The download is done by default without a progress bar. With prefs::show_url_progress you can enable the progress bar for URL downloads.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Frame in which the image is to be inserted 0 : current script frame
path char* - Complete path of the file, which is to be inserted in the document
alignment int kPlaceCentered see image positions
boundingBox float kFitBigContentProp Image size in points

kFitBigContentProp : Fit image (proportional) to the frame. Image less than the frame leave untouched

>0.0 : Fit image (proportional) to a square of the given size. Image less than the square leave untouched

<0.0 : Fit image (proportional) to a square of the given size. Image less than the square are zoomed
⇨ Photoshop clipping path
pathindex int 0 0-based index of clipping path

kIgnoreClipping : Ignore clip setting

kResetClipping : Reset any existing clipping.

>=0 : 0-based clipping path index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by pathname instead.
pathname String or char* "" Name of clipping path

Values ignored by InDesign® if the path is defined by its index already.
⇨ Properties for clipping. Also used for alpha channels.
flags int kAllowHolesFlag How to clip the image? Values can be added.

kInvertFlag Invert the resulting path by combining with a path equal to the bounds of the image.

kAllowHolesFlag For edge detection, do we remove the holes or leave them in.

kRestrictToFrameFlag

Value is ignored by comet_pdf.
cliptoFrame int 0 Use the the clipping path as the frames path?

0 : Keep old frame
1 : Change frame
tolerance float 0.0 A tolerance value in the range of 0.0 to 10.0 specifying how close to the original path we must be if we smooth the path. 0.0 indicates a perfect match. Smoothing may simplify the path, reducing the number of points.

The parameter is not applied by Indesign® Server and comet_pdf.
minPathSize float 0.0 subpaths smaller than the minPathSize will be deleted.

The parameter is not applied by Indesign® Server and comet_pdf.
inset float 0.0 How far to inset the path

The parameter is not applied by Indesign® Server and comet_pdf.
⇨ Alpha channels
alphaIndex int 0 0-based index of channel, see image::alpha_channel_index

kResetClipping do not apply any alpha channel

>=0 : 0-based channel index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by alphaChannel instead.
alphaChannel String or char* "" Name of alpha channel

Values ignored by InDesign® if the channel is defined by its index already.
treshold int 255 Treshold for alpha channel.

0-255 : The alpha channel is applied to the image after the image import. The result is the same like using menu Object -> Clipping path -> Options and indeed it is a very bad result.

> 255 : Recommended! Apply the alpha channel directly while importing the image.
updateFlags int 0 0 : No further wishes
16 : If the local image file already exists, it is used without further checking.
#include "internal/types.h"
int main ()
{
    String	str 	= string::alloc ();
    int 	result;
if (!system::shiftkey ()) { frame::gettext (gFrame, str); result = frame::link_url (gFrame, string::get (str), 9, 0.0); string::release (str); } else { frame::check_url_link (gFrame); }
return 0; }

v.4.0.5 R19777 (24. Jul 2017)
Parameter updateFlags since v4.3 R34200, 23. Jan 2024

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::has_linked_url
frame::has_embedded_url, frame::check_url_link
frame::get_url, prefs::show_url_progress

static int embed_url(
  ItemRef frameRef,
  char* url,
  int alignment = 5,
  float boundingBox = 0.0,
  char* formatString = 0)

MAGIC  Import an embedded image from an URL. General information about Web Images can be found here.. The image is inserted directly into the document via an URL. The following URLs are supported:

File-URLs and normal paths are imported directly using frame::embed_file without any information about the original image.

If the frame has an URL already, you can call the function with an empty URL ("" or 0). This is usefull in the following cases:

  1. User 1 knows the URL and embeds the image.
  2. User 1 sends the document to user 2 at place B.
  3. User 2 can update the images without knowings its URLs.

Frames must not contain the embeded image itself to be update-able. The URL is enough.

If the new image has the same proportions like the old one, position, rotation, scaling and skew of the old image are applied to the new image. Otherwise the placement infos of the function call are used.

The download is done by default without a progress bar. With prefs::show_url_progress you can enable the progress bar for URL downloads.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame. If the frame isn't a Graphic Frame, it will be converted automatically

0 : current script frame
url char* - Complete URL to the image

"" : If the frames contains an image URL already, the URL can be emtpy.
alignment int kMiddle see image positions
boundingBox float kFitBigContentProp Image size in points

kFitBigContentProp : Fit image (proportional) to the frame. Image less than the frame leave untouched

>0.0 : Fit image (proportional) to a square of the given size. Image less than the square leave untouched

<0.0 : Fit image (proportional) to a square of the given size. Image less than the square are zoomed.
formatString char* 0 Used only in comet_pdf. Image format given in common imge file extensions like "png", or "jpeg". The value is only used in later calls to export_embedded_image.
#include "internal/types.h"

Embed an image given by an URL.

#include "internal/types.h"
int main () { String str = string::alloc (); int result; if (!system::shiftkey ()) { frame::gettext (gFrame, str); result = frame::embed_url (gFrame, string::get (str), 9, 0.0, 0); string::release (str); } else { frame::check_url_link (gFrame); }
return 0; }

v4.0.5 R19777, 20. Jul 2017

priint:comet InDesign® Plug-Ins, comet_pdf R
embed_file
has_embedded_url
remove_url_link
itemlist::embed_urls

static int check_url_link(ItemRef frameRef, int* state)

Check whether the image is a Web Image and was changed on server side. General information about Web Images can be found here.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Valid frame reference 0 : current script frame
state int* - After execution, this indicates the state of the Web Image

-1: Error while checking status
0: Ok
1: Out of date, need update

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::check_url_links
document::check_url_links

static int update_url_link(ItemRef frameRef, int flags)

Update a Web Image. General information about Web Images can be found here..

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Frame to be updated
flags int 0 1: Show progress bar

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::update_url_links
document::update_url_links

static int remove_url_link(ItemRef frameRef)

Remove the link to a Web Image from the frame. The image in the frames is untouched, only the original image address (its URL) is removed. General information about Web Images can be found here..

Name Type Default Description
Return int   0 or ErrorCode
frame ItemRef - Valid frame reference

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

itemlist::remove_url_links
document::remove_url_links

static char* get_url(ItemRef frameRef = 0)

Get the web address (URL) stored behind the frame. General information about Web Images can be found here.

Name Type Default Description
Return char*   Web address (URL) of image

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef 0 Valid frame reference 0 : current script frame

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static char* get_url_importresult(ItemRef frameRef = 0)

Get the last import result of a We Image. General information about Web Images can be found here.

Name Type Default Description
Return char*   Last import result..

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef 0 Valid frame reference 0 : current script frame
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static int get_url_state(ItemRef frameRef = 0, int doCheck = 1)

Get the last import result of a Web Image. General information about Web Images can be found here.

Name Type Default Description
Return int   0 : Okay
1 : Image changed on server
2 : Image not available
frameRef ItemRef 0 Valid frame reference 0 : current script frame
doCheck int 1 Check state before

0 : No
1 : Yes
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static int get_url_alignment(ItemRef frameRef = 0)

Get the initial alignment of the Web Image. General information about Web Images can be found here.

Name Type Default Description
Return int   Initial alignment
frameRef ItemRef 0 Valid frame reference 0 : current script frame
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static char* get_url_filedate(ItemRef frameRef = 0)

Get the time stamp of the original file of a Web Image. The time stamp may be change on server in the mean time. To get the current time stamp call get_url_state before. General information about Web Images can be found here.

Name Type Default Description
Return char*   time stamp of original file in web

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef 0 Valid frame reference 0 : current script frame
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static char* get_url_importdate(ItemRef frameRef = 0)

When was the last time the Web Image was imported?
Format: DD.MM.YYYY HH:MM:SS
e.g. 03.12.1986 14:32:47

General information about Web Images can be found here.

Name Type Default Description
Return char*   Last time the file was imported

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

frameRef ItemRef 0 Valid frame reference 0 : current script frame
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No image URL in frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

static float get_url_sizeinfo(ItemRef frameRef = 0)

Initial size hint of Web Image. General information about Web Images can be found here.

Name Type Default Description
Return int   Initial size hint of the Web Image.
frameRef ItemRef 0 Valid frame reference 0 : current script frame
int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}

v.4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url

static int doclink::get(ItemRef fr, ItemRef lk)

Get a frames link.

Name Type Default Description
Return int   0 or ErrorCode

noImageErr (101) : The frame is not an image
fr ItemRef - valid frame reference
lk ItemRef - Allocated link reference for the result

In InDesign® this reference is not a document frame. You can use the result only in the other doclink methods. Using it in other frame methods will cause execution errors! To get the links document frame, please use frame::doclink::get_frame.

In comet_pdf the reference contains the input frame fr in case of success and can (besides the doclink methods) be used directly in all other frame functions .
#pragma plain
#include "internal/types.h"
int main () { ItemList lks = itemlist::alloc (); ItemRef lk = item::alloc (); ItemRef fr = item::alloc (); char p [5000]; int i;
document::get_links (0, 0, "", lks); wlog ("", "%d links found\n", itemlist::length (lks));
for (i = 0; i < itemlist::length (lks); i++) { itemlist::get (lks, lk, i); frame::doclink::get_frame (lk, fr); frame::doclink::get_path (lk, p); wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",   item::getint (lk),   item::getint (fr),   frame::doclink::get_type (lk),   frame::doclink::get_state (lk),   p); }
return 0; }

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

doclink::get_frame
document::get_links

static int doclink::get_frame(ItemRef lk, ItemRef fr)

Get the frame of a link.

Name Type Default Description
Return int   0 or ErrorCode
lk ItemRef - valid link reference
fr ItemRef - allocted frame reference for the result

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

doclink::get
document::get_links

static int doclink::get_state(ItemRef lk)

Get the state of a frame link.

Name Type Default Description
Return int   Current link state

-1 : Error
0 : Link is up-to-date and available for use.
1 : Link is out-of-date and needs to be updated
2 : Link resource is embedded, and link is up-to-date.
3 : Link resource is cached, and link is up-to-date.
4 : Link resource is contained, and link is up-to-date.
5 : Link resource is missing.
6 : Link resource is not accessible by the user.
7 : Link resource state is pending an update.
8 : Link resource state cannot be determined.

comet_pdf does only support the states -1 (Error), 0 (Image file exists), 2 (Embedded) und 5 (Image file missing).
lk ItemRef - valid link reference
#pragma plain
#include "internal/types.h"
int main () { ItemList lks = itemlist::alloc (); ItemRef lk = item::alloc (); ItemRef fr = item::alloc (); char p [5000]; int i;
document::get_links (0, 0, "", lks); wlog ("", "%d links found\n", itemlist::length (lks));
for (i = 0; i < itemlist::length (lks); i++) { itemlist::get (lks, lk, i); frame::doclink::get_frame (lk, fr); frame::doclink::get_path (lk, p); wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",   item::getint (lk),   item::getint (fr),   frame::doclink::get_type (lk),   frame::doclink::get_state (lk),   p); }
return 0; }

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int doclink::get_type(ItemRef lk)

Determine the type of a frame link. In addition to links to images, InDesign® can create links to text frames too, use the menu Edit -> Place and Link to do that.

Links to text frames are not supported by comet_pdf!

Name Type Default Description
Return int   Current link type

-1 : Error
0 : Internal
1 : Image
2 : Text Frame
lk ItemRef - valid link reference
#pragma plain
#include "internal/types.h"
int main () { ItemList lks = itemlist::alloc (); ItemRef lk = item::alloc (); ItemRef fr = item::alloc (); char p [5000]; int i;
document::get_links (0, 0, "", lks); wlog ("", "%d links found\n", itemlist::length (lks));
for (i = 0; i < itemlist::length (lks); i++) { itemlist::get (lks, lk, i); frame::doclink::get_frame (lk, fr); frame::doclink::get_path (lk, p); wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",   item::getint (lk),   item::getint (fr),   frame::doclink::get_type (lk),   frame::doclink::get_state (lk),   p); }
return 0; }

v4.1.6 R26314, 22. Nov 2019
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int doclink::get_path(ItemRef lk, char* fullpath)

Get the complete path of a link reference.

Name Type Default Description
Return int   0 or ErrorCode
lk ItemRef - valid link reference
fullpath String or char* - Allocated string for the result string (the complete path to the linked file)

The result depends on the type of the link, see doclink::get_type:
  1. (Internal) : UID of the text frame (as char* or string!), InDesign® only
  2. (Image) : Full path to the linked image
  3. (Text Frame) : Empty (""), InDesign® only
Embedded images with a reference to their original file provide the path of this original file.

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int doclink::update(ItemRef lk)

Update the link by reimporting the data. The update uses the setting last used to import the data. If this fails because the data is no longer appropriate for this import filter, the import uses the standard import code which picks a new filter.

For comet_pdf the command is available but does not execute anything.

Name Type Default Description
Return int   0 or ErrorCode
lk ItemRef - valid link reference
#pragma plain
#include "internal/types.h"
int main () { ItemList lks = itemlist::alloc (); ItemRef lk = item::alloc (); ItemRef fr = item::alloc (); char p [5000]; int i;
document::get_links (0, 0, "", lks); wlog ("", "%d links found\n", itemlist::length (lks));
for (i = 0; i < itemlist::length (lks); i++) { itemlist::get (lks, lk, i); frame::doclink::get_frame (lk, fr); frame::doclink::get_path (lk, p); wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",   item::getint (lk),   item::getint (fr),   frame::doclink::get_type (lk),   frame::doclink::get_state (lk),   p); }
return 0; }

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int doclink::relink(ItemRef lk, char* path)

Import a new image into the link. The function corresponds to frame::image with the frame of the doclink object and the placement kPlaceLikeExisting.

Name Type Default Description
Return int   0 or ErrorCode
lk ItemRef - valid link reference
fullpath char* oder String - complete path to image

v4.1 R24141, 20. Nov 2018
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int doclink::copy_to_folder(
  ItemRef lk,
  char* destPath,
  int relink = 0)

Copies links' resources to the specified folder, and optionally relinks the resources.

Name Type Default Description
Return int   0 or ErrorCode -1122 : kCannotCopyLinkToFolderErr
lk ItemRef - valid link reference
destPath String or char* - Complete path to the destination folder. The folder is created if it does not exist.
relink int 0 Update link??

0 : no, leave it untouched
1 : Yes, the link should point to duplicated file
int main ()
{
    ItemList  		lks    	= itemlist::alloc ();
    ItemRef      	lk     	= item::alloc ();
    int           	i;
document::get_links (0, 0, "", lks);
for (i = 0; i < itemlist::length (lks); i++) { itemlist::get (lks, lk, i); frame::doclink::copy_to_folder (lk, "$DESKTOP/aaabbb", 1); }
return 0; }

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_links

static int note::get_dest(
  ItemRef nt,
  int* type = 0,
  int* dest = 0)

Determine the type and destination of a Comet Note.

The note is defined by its document reference (not its ID). In InDesign®, this reference corresponds to the document frame. In comet_pdf the reference points directly to the note object (and must not be used in frame functions under any circumstances therefore!). Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.

About editing notes by their IDs, see \URL[here].{document.html#notes::find}.

Name Type Default Description
Return int   0 or ErrorCode
nt ItemRef - Valid note reference. Notes can be fetched with the itemlist::~_notes functions.
type int* 0 If executed successfully, the variable contains the type of the note:

kNoteTypePage
kNoteTypePageIndex
kNoteTypeGroup
kNoteTypeFrame
dest int* 0 On successful execution, the variable contains the note's destination as an integer..

With item::define you can make the result an ItemRef for frame and page notes.
#include "internal/types.h"

Get all Comet notes of a document.

#include "internal/types.h"
int main () { ItemRef fr = item::alloc (); int i, tyte, dest, result; ItemList notes;
if (gRun > 1) return 0;
notes = itemlist::doc_notes (); itemlist::select (notes);
for (i = 0; i < itemlist::length (notes); i++) { itemlist::get (notes, fr, i); frame::note::get_dest (fr, &type, &dest); wlog ("", "Note %d : Type = %d, Dest = %d\n", item::getint (fr), type, dest); }
itemlist::release (notes); item::release (fr);
return 0; }

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes
frame::note::change_dest
frame::note::remove
document::notes::find
document::notes::delete_note

static int note::change_dest(
  ItemRef nt,
  int type,
  int dest)

Change the destination of a Comet Note. The function checks if the target exists before changing it and returns an error code if the target is missing. After successful relinking, the note is moved to the correct page and realigned to the target if necessary.

The note is defined by its document reference (not its ID). In InDesign®, this reference corresponds to the document frame. In comet_pdf the reference points directly to the note object (and must not be used in frame functions under any circumstances therefore!). Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.

About editing notes by their IDs, see \URL[here].{document.html#notes::find}.

Name Type Default Description
Return int   0 or ErrorCode
nt ItemRef - Valid note reference. Notes can be fetched with the itemlist::~_notes functions.
type int - New type of note. The following specifications are allowed:

kNoteTypePage
kNoteTypePageIndex
kNoteTypeGroup
kNoteTypeFrame
dest int - New reference target. Please note that an integer is always expected.

For Frame Notes (kNoteTypeFrame) get the corresponding specification using item::getint.

For Page Notes (kNoteTypePage), get the corresponding specification using page::get_uid.

Page indexes (kNoteTypePageIndex) are always 1-based.
#include "internal/types.h"

Relink all Comet Notes of the Comet Group of the current frame to Comet Group 25185.

#include "internal/types.h"
int main () { ItemRef fr = item::alloc (); int i; ItemList notes;
if (gRun > 1) return 0;
notes = itemlist::group_notes (); for (i = 0; i < itemlist::length (notes); i++) { itemlist::get (notes, fr, i); frame::note::change_dest (fr, kNoteTypeGroup, 25185); }
itemlist::select (notes);
return 0; }

Move all page-indexed Comet Notes to page 1. Then do 'something' with page deletion etc.. Then create new pages. And finally move the notes back to the page where they were at the beginning. If the page is missing in the meantime, the note is deleted.

#include "internal/types.h"
int change_pageindex (ItemList notes, int pindex) { ItemRef fr = item::alloc (); int n, result;
for (n = 0; n < itemlist::length (notes); n++) { itemlist::get (notes, fr, n); result = frame::note::change_dest (fr, kNoteTypePageIndex, pindex); if (result != 0) { frame::note::remove (fr); } }
item::release (fr);
return 0; } int main () { int pages = document::pages (); int p; ItemListList allNotes = itemlistlist::alloc (); ItemList notes;
if (gRun > 1) return 0; if (pages == 1) return 0;
document::notes::show ();
// Page 1 will certainly not be deleted. // So move all notes to page index 1 // for (p = 2; p <= pages; p++) { notes = itemlist::page_notes (0, p, kNoteTypePageIndex); itemlistlist::append (allNotes, notes); // Remember those notes change_pageindex (notes, 1); }
// For testing purposes remove all pages except the first one // for (p = 2; p <= pages; p++) { page::remove (2); }
// Then create one page less than before // page::create (pages-2);
// And move back all notes to their old pages. // Superfluous notes are deleted. // p = 2; for (notes = itemlistlist::first (allNotes); notes; notes = itemlistlist::next (allNotes)) { change_pageindex (notes, p); itemlist::release (notes); // We don't need this list anymore p++; }
// Clean up // itemlistlist::release (allNotes);
return 0; }

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes
frame::note::get_dest
frame::note::remove
document::notes::find
document::notes::delete_note

static int note::remove(ItemRef nt)

Remove a Comet Note from the document.

The note is defined by its document reference (not its ID). In InDesign®, this reference corresponds to the document frame. In comet_pdf the reference points directly to the note object (and must not be used in frame functions under any circumstances therefore!). Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.

About editing notes by their IDs, see \URL[here].{document.html#notes::find}.

Name Type Default Description
Return int   0 or ErrorCode
nt ItemRef - Reference of the note to be deleted. Notes can be fetched with the itemlist::~_notes functions.

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes
frame::note::get_dest
frame::note::change_dest
document::notes::find
document::notes::delete_note

#include "internal/types.h"

The following example illustrates some of the typical frame commands. The illustration shows the result of the script execution.

#include "internal/types.h"
main () { ItemRef frame = item::alloc (); ItemRef frame2 = item::alloc (); char layerName[256]; char tt[2000]; int result;
color::define ("Dark orange", 255, 90, 0); color::define ("Orange", 255, 127, 0); color::define ("Light orange", 255, 190, 0);
result = frame::create_textframe (   frame,   10, 10, 200, 200,   document::page (),   layer::name (2, layerName)); if (result != 0) { showmessage ("Error %d",result); item::release (frame); return; }
frame::star (frame, 21, 10); frame::color (frame, "Orange"); frame::stroke (frame, "Orange", 1.5); frame::shadow (frame, "Dark orange",   50.0, 1, // tint, blendmode   8.3, 9.3,// xd, yd   3.0); // blur
result = frame::create_textframe (   frame2,   10, 210, 300, 400   document::page (),   layer::name (2, layerName));
frame::color (frame2, "Light orange"); frame::stroke (frame2, "Orange", 12.3); frame::shadow (frame2, "Dark orange",   50.0, 1, // tint, blendmode   8.3, 9.3,// xd, yd   3.0); // blur frame::vignette (frame2, 3, 10.0, 1, 100.0, 100.0);
frame::link (frame, frame2);
tt = "%!TT<ParaStyle:description>"; tt += "The globe thistle in Latin is called "; tt += "<CharStyle:batch name><w2:1,3, -22, -33>X</w2>"; tt += "<CharStyle:> And this is how is looks : ";
tt += "#<in: 100.0, 100.0, 11, 3, -66, -99>Trulla du!</in>#";
tt += "*<in: 100.0, 100.0>"; tt += "%!TT<ParaStyle:description>"; tt += "What does the sub-frames say about chicory? "; tt += "<CharStyle:batch name><w2:1,1, -22, -33>X</w2>! <CharStyle:>"; tt += "Ah yes, of course!"; tt += "</in>";
tt += "*Good, eh?";
frame::insert (frame, tt, 0, true);
item::release (frame); item::release (frame2);
return 0; }

The script ungroups a frame and creates a new frame aside the frames of the group. All old frames of the group and the new frame are than grouped together to one new group. Error handling is omitted here. Real scripts should ask for error results!

 ⇒ 

#include "internal/types.h"
int main () { ItemRef groupRef = item::alloc (); ItemRef newframe = item::alloc (); ItemList grouped = itemlist::alloc (); float l, t, r, b; char lay[256];
if (gRun > 1) return 0;
if (frame::get_group (gFrame, groupRef)) { showmessage ("frame not grouped"); return 0; } frame::ungroup (groupRef, grouped);
itemlist::bbox (grouped, &l, &t, &r, &b); frame::create2 (   newframe,   kStar,   r+10.0, t, r+130.0, t+120.0,   page::get (gFrame),   frame::get_layer (gFrame, lay),   0, // columns   0, // vertical?   0.0, // gutter   5, 40);
frame::color_rgb (newframe, 255, 0, 0, 0); frame::stroke_rgb (newframe, 0, 0, 0, 5.0); itemlist::append (grouped, newframe);
frame::group (grouped, gOutFrame);
return 0; }

Paul Seidel, Thanks to Joseph!
12.03.2024, 15:56 Uhr
Plugin Version 1.0.10

Alphabetic index HTML hierarchy of classes or Java