The module processes document frames of InDesign® documents.

Here you will find examples to use frame.

Version :
20.10.2021, 12:36 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 bookmark?

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 to be a frame.
itemRef ItemRef - Any ItemRef or 0

Version 1.4.1 R383, 28. June 2007

priint:comet InDesign® Plug-Ins

item::defined

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 a line. If a layer name is specified, the frame is set up on this layer. Is a column number is defined larger than 0, a text frame is automatically defined with the column spacing gutter. If the spacing is smaller than 0, the default spacing in InDesign® will be used.

Name Type Default Description
Return int   Error code or 0
itemRef ItemRef - with item::alloc generated reference. The frame can be defined, contains the variable a valid reference to the newly defined frame.
type int - Frame type
kRectangle
kOval
kPolygon
kStar
kSpline
kLine
If the column number is larger than 0, a text frame will automatically be allocated.
l, t, r, b float - frame square in points, point s are relative to the page margins, not to the page!
page int - 1-based page number
layerName String or char* "" Name of the layer
If the information is missing, the first layer will be used.
columns int 1 Column number. If the column number is larger than 0, a text frame will be automatically allocated.
vertical int 0 orientation of text

0 horizontal
1 vertical
gutter float -1.0 Column spacing
-1.0 Use the pre-defined column spacing from
•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
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) - ???'

#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 set up. 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, // Seite   "Ebene 3",// layer name   1, // columns   0, // vertical columns?   12.3,// gutter   13, 40// edges and its length   ); if (result != 0) { showmessage ("Fehler %d",result); item::release (frame); return 1; } result = frame::create (frame,   kLine,   10.0, 210.0, 300.0, 400.0,   2, // page   "Ebene 3",// layer   ); frame::stroke_rgb (frame, 255, 0, 0, 20.0); frame::color (frame, "", 1, 1);
item::release (frame); return 1; }   "Layer 3",// layer name   1, // column number   0, // vertical column   12.3,// column spacing   13, 40// Page and edge length   ); 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   "Ebene 3",// layer name   ); frame::stroke_rgb (frame, 255, 0, 0, 20.0); frame::color (frame, "", 1, 1);
item::release (frame); return 1; }


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   error code or 0
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 (1-based)
<=0 : same page like srcFrame
layerName String or char* "" Destination layer
"" : same layer like srcFrame
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

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 set up on this layer. If a column number larger than 0, columns will be automatically set up in the frames with the spacing *gutter*. If the spacing is smaller than 0, the default spacing 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   Error code or 0
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 or char* Current layer name of the target layer
columns int 1 Column number
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

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   Error code or 0
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 page number
layer String or char* Current layer name of the target layer  
columns int 1 Column number
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

int	pg  	= -1;
ItemRef	frame  	= item::alloc ();
char	layerName[256];
int	result;
result = frame::create_textframe_f (   frame,   10.0, 10.0, 200.5, 200.5,   pg,   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

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   Error code or 0
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 being that the position and size specifications of the frame can be defined as floats.

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   Error code or 0
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 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;
}

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

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   Error code or 0
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

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

Get the co-ordinates of a reference point of a frame.

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Valid frame
which int kRefPointTopLeft 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

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   Error code or 0
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 Error code
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

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 Error code

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

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 Error code
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 InDesing 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

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 Error code
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 InDesing 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

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   Error code or 0
itemRef ItemRef - with item::alloc allocated and from frame::create_textframe defined reference
columns int - Column number
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
document::insert_macro

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

Number of a text column. If the frame is not a text frame, the call is answered with 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			gt;
    int			dir;
cols = frame::count_columns (gFrame, >); wlog ("", "Frame : %d columns, gutter %f\n", cols, gt);
cols = page::count_columns (page::get (gFrame), >, &dir); wlog ("", "Page %d : %d columns, gutter %f, direection %d\n", page::get (gFrame), cols, gt, 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

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   Error code or 0
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
document::insert_macro

static int remove(ItemRef itemRef)

Synonymous for delete_textframe.

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

Selection of a frame in the document.

Name Type Default Description
Return int   Error code or 0
itemRef ItemRef - Frame reference
selectPage int scroll Should the selected frame be scrolled into the visible area?  
replaceOrAdd int Remove old selection. Only select this frame (true) or expand 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   Error code oder 0
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   Error code or 0
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   Error code oder 0
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   Error code oder 0
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 and all its sub-frames to the size of its contents. The command acts exactly like item::fitframe. 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   Error code oder 0
frameRef ItemRef - Frame reference
refPoint int kRefPointTopLeft Ignored for inline frames. In wich 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.

kRefPointDefault
kRefPointTopLeftNew
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
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, kRefPointTopLeftNew, &w, &h);

seit v3.4 R5220 (3. Mar 20124)

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

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. The command acts exactly like item::fitframe. Frames of one lined texts are fitted to a new width too from InDesign® by default. To suppress this behavior, set constantWidth to 1.

Unlike in frame::resize et. al. the left top reference point is named by kRefPointTopLeftNew here. To get the default fitting behavior, use kRefPointDefault.

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   Error code oder 0
frameRef ItemRef - Frame reference
refPoint int kRefPointTopLeft Ignored for inline frames. In wich 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.

kRefPointDefault
kRefPointTopLeftNew
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
 
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, kRefPointTopLeftNew, &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

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.

Name Type Default Description
Return int   error code or 0
frameRef ItemRef - Valid graphic frame
method int - Fitting method. One of:

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

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

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

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

4 : Center content in frame

5 : Comet position
data int Image Setting, otherwise 5 Additional information about the placement of the image.

Methods 0, 1, 2 and 4:
-1 : Use InDesign® built-in method only
Otherwise : Use priint:comet method

Method 5:
Image position. If the parameter is omitted, then - if the image has already been placed by the Comet - the last Comet placement for this image is restored.
size float 0.0 Image placement size of bounding box for image, see here
maxScale float 1.0 Maximum image scaling (1.0 means 100.0%)

#include "internal/types.h"

Scale the image proportionally to completely fill the frame. Protruding parts of the image are centered:
      
Translation of the text is Quality work is a matter of honor.

The method does not the same like the InDesign® menue Object -> Fit -> Fill frame proportionally! The results of InDesign® are (at least for us) not predictable. See the next three screenshots: Fig. 1shows the the original frame. In fig. 2 you can see, what InDesign® produces - the image fills the frame, yes. But the images is a little bit too large. Fig. 3 shows the result of fit_image with the minimally necessary image size:
      

Scale image to become completely visible:
     

The method does not the same like the InDesign® menue Object -> Fit -> Fit content proportionally! The results of InDesign® are (at least for us) not predictable.. See the next three screen shots. The 2nd screen shot is the result of InDesign®- as you can see, the image is NOT completely visible. Fig. 3 shows the result of fit_image with the maximum possible image size:
      

Scale image in both directions to completely fill the frame:
     

The method does not the same like the InDesign® menue Object -> Fit -> Fit content to frame! The results of InDesign® are (at least for us) not predictable. As you can see in fig. 2, InDesign® produces ?anything? Don't know. Fig. 3 shows the result of fit_image with the minimally necessary image size:
      

Fit the frame to match the image. Position, dimensions and rotation of the frame may change. Here are some screnn shots. Fig. 3 shows the result of fit_better:
      

The method does not the same like the InDesign® menue Object -> Fit -> Fit frame to content! - This is done by our method Fill frame proportionally:
     

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

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   error code or 0 -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
0 or (0.0, 00, 0.0, 0.0) : No crop
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   error code or 0
-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   Fehlercode oder 0
-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   Fehlercode oder 0
-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 place holder. But in different to textmodel::insert ("abc", 0); this text does not contain to the current place holder. With frame::insert you leave the protected textmodels place holder area definitly. Be aware that text inserted out side the place holder may inserted as often as the script is called!

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Text frames in which the text is to be inserted
tt String or char* - Text to be inserted (can also be tagged text)
position int 0 text-relative insert position, < 0 attach
auto_load int on Should the text placeholders in the tagged text 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)

Attach

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

Attach

frame::insert (frameRef, text)

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

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 place holders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins

insert

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

Attach text to 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"

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Text frame into which the text is to be inserted
String or char* tt - text to be inserted (can also be tagged text)
auto_load int 1 Should the text placeholders in the tagged text 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

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 place holders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

append, prefs::set_logstate

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

Replacing text in a frame. The text can be tagged, then it can be inserted formatted. If the content of the current place holder is removed by inserting the empty string (""), a zero width space (<0x200B>) is inserted to beware the place holder.

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

Name Type Default Description
Return int   Error code oder 0
frameRef ItemRef - Text frames in which the text is to be inserted
text String or char* - text to be inserted (can also be tagged text)
position int 0 text-relative insert positions or kEnd, kSelection
delete_len int kEnd Number of characteristics or kEnd to be deleted
auto_load int 1 Should the text placeholders in the tagged text 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 place holder scripts replaces the current place holder 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 (Tagged Text, Unicode characters, ...) the action is made in three single steps:

  - Replace the place holder 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 place holder // 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 place holder is replaced by the trailing text - but the place holder is removed. // Inserting the table at kEnd therfore now means : At the end of the whole text! // Because you have no place holder, 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

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 place holders.

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

replace

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 place holders are contained in the text, these will be removed in a similar fashion by textmodel::replace_all. As opposed to the function frame::replace, the current place holder is removed from the text, when you replace its whole content:

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

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

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

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Text frames in which the text is to be inserted
String or char* tt - text to be inserted (can also be tagged text)
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 tagged text 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 place holder scripts replaces the current place holder 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 (Tagged Text, Unicode characters, ...) the action is made in three single steps:

  - Replace the place holder 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 place holder // 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 place holder is replaced by the trailing text - but the place holder is removed. // Inserting the table at kEnd therfore now means : At the end of the whole text! // Because you have no place holder, 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

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 Error code
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 - Insert position for the table
>= 0 Text position
> Attach text length kEnd Attach
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 Error code
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
> Attach text length kEnd attach
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 -1 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

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   Error code or 0
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   Error code or 0
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)

Fill the frame with the specified colours. The colours are defined with the name of the record of the color panel. If only the corner type is to be defined, the color setting will be suppressed by an empty color name. It is then only a suppressor, of course.

  JoinType
0 Mitter
1 Round
2 Bevel

  CapType
0 Button
1 Round
2 Square

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Target frame
colorName String or char* - Name of the color or base color
joinType int -1 How do the frame corners meet together?
-1 ignore
otherwise see the table above
capType int -1 How do the frame lines end?
-1 ignore
otherwise see the table above
tint float -1.0 Tint of color (0.0-100.0)

-1.0 : Leave untouched

err_code = frame::color (frameRef, colorName);

joinType seit 1.0.20
Parameter tint since v3.3 R3112, 12. Oct. 2012

priint:comet InDesign® Plug-Ins, comet_pdf

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

Fill the frames in the specified colours. The colours are defined in their rgb values. If only the corner type is to be defined, the color settings can be suppressed through specification of -1 for r, g, b respectively. It is then only a suppressor.

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Target frame
r, g, b int - color porportions (0-255)
joinType int -1 How do the frame corners meet together?
-1 ignore
otherwise see the table above
capType int -1 How do the frame lines end?
-1 ignore
otherwise see the table above

err_code = frame::color (frameRef, r, g, b);

1.0.20. In previous versions the function is called frame::color.
joinType is 1.0.20

priint:comet InDesign® Plug-Ins, comet_pdf

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

Fill the frames in the specified colours. The colours are defined in their cmyk values.

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Target frame
c, m, y, k int - color porportions (0.0 - 1.0)
joinType int -1 How do the frame corners meet together?
-1 ignore
otherwise see the table above
capType int -1 How do the frame lines end?
-1 ignore
otherwise see the table above

err_code = frame::color (frameRef, r, g, b);

1.0.20. In previous versions the function is called frame::color.
joinType is 1.0.20

priint:comet InDesign® Plug-Ins, comet_pdf

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:

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   Error code or 0
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   Error code or 0
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   Error code or 0
frameRef ItemRef - Target frame
what int kOverprintBasic Part of frame to change?

kOverprintBasic : all
kOverprintFill : Fill
kOverprintStroke : Contour (stroke)
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

static int get_overprint(ItemRef frameRef, int what)

Get the overprint of frames.

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

Name Type Default Description
Return int   Frame overprinted?

0 : No
1 : Yes
frameRef ItemRef - Valid frame
what int kOverprintBasic Part of frame to ask?

kOverprintBasic : all
kOverprintFill : Fill
kOverprintStroke : Contour (stroke) kOverprintGap : Gaps of contour

#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

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)

Frame color and strength. The definition of the color is made by the name of the record of the color field. Following line types can be defined.

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   Error code or 0
frameRef ItemRef - Target frame
colorName String or char* - Name of a color or base color

"" : Leave color untouched
width float -1.0 Thickness of the frame in points
-1.0 ignore
tint float -1 color strength 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 "holes" of the frame or base color
Empty string : ignore
gapTint float -1.0 color strength of the "holes" 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 miter
-1.0 ignore
otherwise the value from the area 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)

Frame colours and strength. The definition of the color is defined with RGB. The function from version 1.0.20 is called frame::stroke_rgb.
Temporarily defined colours can not be given a color strength (tint), therefore this parameter is absent from function in contrast to frame::stroke.

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Target frame
r, g, b int - color values 0-255 respectively
width float ignore Thickness of the frame in points
-1.0 ignore
overPrint int ignore 1 Hintergrund überdrucken
0 Do not overprint background
-1 ignore
lineStyle int ignore see above table
-1 ignore
gapR, gapG, gapB int ignore color value of the "holes" of the frame 0-255 respectively
gapOverPrint int ignore 1 Overprint background of the "frame colours"
0 Do not overprint background
-1 ignore
gapTint float -1.0 color strength of the "holes" in the frame in % (0.0-100.0)
-1.0 ignore
alignment int -1 Where should the contour be applied?
-1 ignore
0 in the middle
1 interior
2 outside

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)

Frame colours and strength. The definition of the color is defined with RGB. The function from version 1.0.20 is called frame::stroke_rgb.
Temporarily defined colours can not be given a color strength (tint), therefore this parameter is absent from function in contrast to frame::stroke.

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Target frame
c, m, y, k float - color values (0.0 - 1.0 each)
width float ignore Thickness of the frame in points
-1.0 ignore
overPrint int ignore 1 Hintergrund überdrucken
0 Do not overprint background
-1 ignore
lineStyle int ignore see above table
-1 ignore
gapC gapM, gapY, gapK float color values for gaps (0.0 - 1.0 each)  
gapOverPrint int ignore 1 Overprint background of the "frame colours"
0 Do not overprint background
-1 ignore
gapTint float -1.0 color strength of the "holes" in the frame in % (0.0-100.0)
-1.0 ignore
alignment int -1 Where should the contour be applied?
-1 ignore
0 in the middle
1 interior
2 outside

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 error code
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 visible stroke width in points
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 error code
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 ("Cannot detect color");
return 0; }

Version 3.1 R2137, 20.09.2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_color, get_stroke

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   Error code or 0
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   Error code or 0
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   Error code or 0
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   Error code oder 0
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 Error code
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 Error code
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 Error code
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, see sql::dbconnection
table String or char* - Name of the target table
attr String or char* - 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.
ID int - ID in the target table
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.

priint:comet InDesign® Plug-Ins

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 component with frame::store_macro or textmodel::store_macro in 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 Error code
frameRef ItemRef - Text frames 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 of text template. With XML data and for SOAP, the sought insert must be located in the pageitems.xml file. The required import data will be retreived from the pageitems/data/ID.indd file of the XML data file (XML) or is located under the ID pageitems/data/ID.indd on the SOAP server.
With databased the tables and columns are freely selectable. If not otherwise specified, pageitems.data will automatically be used.
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 0 Target database. If the information is missing, the current data connection will be used.
table String or char* 0 Name of the target table. The name is only relevant when exporting to databases. When exporting in XML files and on SOAP server the inserts will be inserted in the pageitems.xml file and the data and the preview will be stored in the sub-folders of the data folder pageitems.
If the table name is empty (0 or ""), the pageitems database table will be used as the target table and the data stored in pageitems.data. In pageitems.preview a screenshot of the template is stored.
data_attr String or char* 0 The attribute is only relevant with importing from the database (not for XML or SOAP) and a table name not equal to 0, "" or "pageitems" and states the attribute of the target table, from which the text is to be retrieved. The attribute must be of the type BLOB and may not be called TEXT..

#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 wich 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 place holders, 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");
}

Version 1.1.6
Parameter deepDive since v3.3 R2812, 01.03.2012

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

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

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

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

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

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   Error code or 0
frameRef ItemRef - Target frame
colorName String or char* - Name of the color

err_code = image_blackframe::color (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   Error code or 0
frameRef ItemRef - Target frame
r, g, b int - color porportions (0-255)

err_code = image_blackframe::color (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   Error code or 0
frameRef ItemRef - Target frame
c, m, y, k int - color porportions (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)

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.

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.

Name Type Default Description
Return int   Error code oder 0
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 to be 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.

#include "internal/types.h"
err_code = textmodel::image (path [, alignment[, size]]);
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; }

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

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

Loading image place holder
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 error code
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 error code
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_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 into a given frame. In addition to frame::place_pdf you can define the "crop to" bounding box for the pdf.

Name Type Default Description
Return int   error code oder 0
frameRef ItemRef - Valid document frame
path String or char* - Fullp path to the PDF
pageIndex int 1 page to import (1-based). If page number is out of range, first page 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
transparentBkg int 0 Transparent background?

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

-1 : Use InDesing import options
0 : Crop to content (visible layers)
1 : Use InDesing 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 or char* 0 Any number of layers to show. All document layers not found in the list will hidden. If no layer is given, the document preferences are used.

comet_pdf ignores this list and uses the visibilities set in the PDF.

#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

priint:comet InDesign® Plug-Ins, comet_pdf

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

Fix a position of an image in its 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 or Error code
frameRef ItemRef - Graphic frame the image of which is 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 in a graphic frame. The specification is to be given in points.

Name Type Default Description
Return int   0 or Error code
frameRef ItemRef - Graphic frame the image of which is to be moved
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, refX float 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

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 scaling of an image in a graphic frame. The value 1.0 corresponds to the original size of the image.

Name Type Default Description
Return int   0 or Error code
frameRef ItemRef - Graphic frame the image of which is to be moved
x float - New scale for the image width
y float - New scale for the image height
refPoint int kRefPointTopLeft scaling reference point

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
refX, refY float 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

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

Rotate the image of graphic frame.

Name Type Default Description
Return int   0 or Error code
frameRef ItemRef - Graphic frame the image of which is to be moved
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

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

Skew the image of a graphic frame.

Name Type Default Description
Return int   0 or Error code
frameRef ItemRef - Graphic frame the image of which is to be moved
angle float - Skew angle
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..
rotation float 0.0 Value of the optional rotation in addition to the skew, not supported by InDesign® CS3.

See example for image_getpos.

Version 1.1.6

priint:comet InDesign® Plug-Ins, comet_pdf

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 Error code
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

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

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

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 Error code
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

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

Name Type Default Description
Return int   0 or Error code
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

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 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.
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
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 by the given factors.

Name Type Default Description
Return int   0 or Error code
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

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 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.
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 Error code
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

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

see frame::image

Name Type Default Description
Return int   Fehlercode oder 0

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 Error code
frameRef ItemRef - Frame, the connection of which is to be updated
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogues
1 Display the next dialog 2 Display all dialogues
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 Error code
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogues
1 Display the next dialog 2 Display all dialogues
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 Error code
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogues
1 Display the next dialog 2 Display all dialogues
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 Error code
frameList ItemList - List of the frames which are to be updated.
uiFlags int 0 Import dialog which is to be displayed
0 suppress all dialogues
1 Display the next dialog 2 Display all dialogues
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

static int parent(ItemRef frame, ItemRef parent)

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 Error code
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

Version 1.1.7, Januar 2005

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 Error code
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 Error code
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

ItemList, itemlist::append, ..., ungroup

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 place holder 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 Error code
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 ("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; }

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

priint:comet InDesign® Plug-Ins, comet_pdf

group, add_to_group, regrouped

static int group_content(ItemRef groupFrame, ItemList groupedItems)

Ascertain the content of a group.

Name Type Default Description
Return int   0 or error code
groupFrame ItemRef - group frame, see get_group
groupedItems ItemList 0 List of content, must be alloacted using item::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 ("no a 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

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

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

Name Type Default Description
Return int   0 or error code
frameRef ItemRef - valid frame
groupRef ItemRef 0 group frame
0 : ignore
otherwise : with item::alloc allocated result variable

Move a frame to an other layer. If the frame is a child of a InDesing 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; }

Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf

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 error code
oldGroup ItemRef - resolved group
newGroup ItemRef 0 new group.May by 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 a frame to a group. If the frame does not contain to a group, a new group is created from these frames. If the referenz points to a group itself, the second frame is added to these group. Learn more about regroupings. The group reference of the first frame is changed by this call!

Name Type Default Description
Return int   0 or error code
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

is_group, regrouped, ungroup, group, group_content, add_list_to_group

static int add_list_to_group(ItemRef frameRef, ItemList sibling)

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

Name Type Default Description
Return int   0 or error code
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

is_group, regrouped, ungroup, group, group_content

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 Error code
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 Error code
f ItemRef - Valid frame reference
0 - Use current script frame
mode int - Contour type

kWrapUndef - Leave contour type unchanged
kWrapNone - no effect on text
kWrapBand - text leads past area of strip
kWrapNextFrame - text continues in next frame
kWrapBothSides - text on both sides of object
kWrapWithinHoles - text within holes in object
kWrapAutoContour - text follows the shape (implies kWrapBothSides)
kWrapManualContour - text follows the standoff shape (implies kWrapBothSides)
kWrapLeftContour - text wraps only to the left side of the standoff
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

kWrapUndef - Contour type could not be ascertained
kWrapNone - no effect on text
kWrapBand - text leads past area of strip
kWrapNextFrame - text continues in next frame
kWrapBothSides - text on both sides of object
kWrapWithinHoles - text within holes in object
kWrapAutoContour - text follows the shape (implies kWrapBothSides)
kWrapManualContour - text follows the standoff shape (implies kWrapBothSides)
kWrapLeftContour - text wraps only to the left side of the standoff
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.
top float* 0 Upper contour height, may be 0.
right float* 0 Right contour width, may be 0.
bottom float* 0 Lower contour height, may be 0.

#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 Error code
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.).

Invert wrap.

Name Type Default Description
Return int   0 or Error code
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 Error code
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 Error code
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 Error code
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 Error code
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 Error code
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. 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 place holder or to the current text model?

0 : place holder
1 : text model
Ignored by Illustrator.

#include "internal/text.h"

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)

static int get_type(ItemRef f = 0, int* totalPoints = 0)

Get ttype of frame. Polygons are only detected, if all sides are of same length. Frames with more than 2 egdes and different side lengths are assumed to be a spline.

Name Type Default Description
Return int   frame type

kUndef : Unknown
kRectangle
kLine
kOval
kPolygon : Regelmässiges n-Eck oder Stern
kSpline
f ItemRef 0 Gültige Rahmenreferenz
0 - aktuellen Skriptrahmen verwenden
totalPoints int 0 Wieviel Eckpunkte besitzt der Rahmen. Besteht ein Rahmen aus mehreren Pfaden, werden die Eckpunkte der einzlenen Rahmen addiert. Die Variable darf 0 sein.

#include "internal/types.h"

Find an example at get_color.

Version 1.3.4 (P/R 94)

priint:comet InDesign® Plug-Ins

create, create2

static float get_opacity(ItemRef f = 0, int opacType = 0)

Get the tranparency of of 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 error code
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

static int is_inline(ItemRef frame)

Is the frame a n 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

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

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

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

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

static int is_guide(ItemRef frame)

Is the frame a "giude 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

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

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

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

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

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 error code
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

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 error code
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 must also be a string for number or boolean entries! 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

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 error code
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 error code
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 textplace holders. Text attribut changes such as font, textsize, color, ... are breaking the Comet place holders into several so called runs. The Comet plug ins are runs save. But for templates and master documents it would be a good idea, to remove this redundant information for performance reasons.

Using the application menu Plug Ins:Placeholder:Remove redundant place holders before save users can remove redundant place holders automatically.

The function removes all redundant place holders from the given text or from a parts of it.

Name Type Default Description
Return int   error code or 0
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

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 InDesing version prior CS3

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. 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

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 place holders. 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 error code
frameRef ItemRef 0 Valid text frame
0 : Current script frame
index int - place holder 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 to be the name
classid int 0 Klassennummer des Objektes
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
1 : Middle
1 : 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

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 error code
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 error code
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 wich 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

static int set_nail(
  ItemRef frameRef,
  int refPoint,
  int type = 0,
  int preferMax = 0)

Set or remove priint:adjust nails.

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 error code
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 (grreen) nail
2 : Relative (red) nail
-1 : Toggle
preferMax int -1 Edge type, for edge naiils 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

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 error code
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 error code
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); // 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, 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 error code
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 error code
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 defintion 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 error code
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;
// Import Comet templates 41 and 42 for (i = 41; i<43; i++) { // Import allocates *items* items = document::place_items (pool, "data", "pageitems", i, l, t);
// Collect imported frames itemlist::appendlist (frames, items);
itemlist::bbox (items, &l, &t, &r, &b); itemlist::release (items); items = 0;
t = b + 2.0; }
// Make the InDesign® group frame::group (frames, groupRef);
// "Inline" group // groupRef changes! res = frame::inline_above ( gFrame, textpos, groupRef, 0, // 0 - create, 4, // torwards spine 11.1, // space before 22.2, // space after 1); // lock wlog ("", "inline_above returns %d\n", res);

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 error code
textFrameRef ItemRef - valid text frame

0 : current textframe
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 error code 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 place holder.
len int - Search for an inline in the given text range (min 1). The range ist given relative to frame, not to the place holder.
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 the object be on the text frame's layer instead of anchored.

Inlines may change or loose their page by this action!

Name Type Default Description
Return int   0 or error code
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)

Lock a frame.

Name Type Default Description
Return int   0 or error code
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

static int unlock(ItemRef frameRef = 0)

Unlock a frame.

Name Type Default Description
Return int   0 or error code
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

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

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

static int get_cometgroup_member(
  ItemRef frameRef,
  char* label,
  ItemRef outMember)

Search for a frame with a given Comet label within a frames Comet group. If the frame contains to a continuing group, the group is searched first.

Name Type Default Description
Return int   Error code or 0
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   error code or 0
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)

Prüfe, ob ein Rahmen (implizit oder direkt) Mitglied einer Comet-Gruppe ist. 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 as sub group to the given frame.

Name Type Default Description
Return int   Error code or 0
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

static int remove_from_cometgroup(
  ItemRef frameRef,
  int groupID,
  int invalidateView = 0)

Remove a frame from a Comet group. If the given frame is the main frame, the function has no effect.

Name Type Default Description
Return int   Error code or 0
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

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)

Apply layout rules of the given frame. Rules are not executed if the given rule type is off (by plug-ins or by system::suppres_layoutrules).

Name Type Default Description
Return int   Error code or 0
frameRef ItemRef - Valid frame reference
0 : current script frame
what int - Type of layout rules to execute

1 : after create
2 : after update
4 : user action
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 lod rules only you may provied 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

system::suppress_layout_rules, system::wakeup_layout_rules, itemlist::apply_layout_rules

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   Error code or 0
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 handeled 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

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 error code
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

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 error code
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

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 error code
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

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 error code
frameRef ItemRef - Valid frame reference
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

static int is_masteritem_overriden(
  ItemRef masterItem,
  int pgNum,
  ItemRef pageItem)

Given a master page item, check whether it is overridden on a given document page.

Name Type Default Description
Return int   0 :not overridden, not a master page frame, error
1 : Yes, the master page item is overridden on the given page
masterItem ItemRef - Valid master page item
pgNum int - 1-based page index in document
pageItem ItemRef 0 On overridden master page items, the variable contains the according page item. May be 0, but if given, it must be allocated carefully (item::alloc).

Get the master page items of the first document page and override the first frame. After this check both directions (from the master 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 Masteritem PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# IsMasterOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# IsOverridenMaster %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 master page item.

Name Type Default Description
Return int   0 : not overridden, not coming from a master page, error
1 : Yes, it is a overridden master page item
pageItem ItemRef - valid page item
masterItem ItemRef 0 On overridden master page items, the variable contains the according master page item. May be 0, but if given, it must be allocated carefully (item::alloc).

Get the master page items of the first document page and override the first frame. After this check both directions (from the master 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 Master PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# IsMasterOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# IsOverridenMaster %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 master page item for a document page.

Attention: Single-sided master pages on facing pages and facing master pages on single pages are supported. But to avoid horizontal shifts of the overridden frames, spreads with more than two pages must use master pages with at least the same number of pages. Otherwise, you must correct the horizontal shift in your scripts.

Name Type Default Description
Return int   0 or error code
masterItem ItemRef - Valid master 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 master page items of the first document page and override the first frame. After this check both directions (from the master 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 Masteritem PageItem\n"); wlog ("", "# Override %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_masteritem_overriden (masterItem, 3, pageItem); wlog ("", "# MasterOverriden %d %d %d\n", result, item::getint (masterItem), item::getint (pageItem));
result = frame::is_overriden_masteritem (pageItem, masterItem); wlog ("", "# OverridenMaster %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 master 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 error code
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 master 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"
int main ()
{
    float		fa, fi, fv, fh;
    float		level	= frame::get_fill_level (gFrame, &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 error code
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

static int show(ItemRef frameRef, int visibilty = 1)

Change the visibilty 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. 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 error code
frameRef ItemRef - Valid page item

0 : current script frame
visibilty int 1 new visibilty

0 : hidden
1 : visible

CS5 Version 3.2 R2223, 14. Dez. 2010

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

hide, is_hidden

static int is_hidden(ItemRef frameRef)

Get the curren visibilty of a frame. 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   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

static char* get_name(
  ItemRef frameRef,
  int nameType = 0,
  int doTranslate = 0)

Get a frames name. Names are displayed inside the layer panel. You need at least CS5 for this feature. In versions prior CS5 the function will return an error code.

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

static int set_name(ItemRef frameRef, char* newName = 0)

Set a frames name. Names are displayed inside the layer panel. 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 error code
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

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 : Take 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

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

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 error code
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 place holder
0x00000002 : Load text place holder
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

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 extremly carefully while changing this values!

Name Type Default Description
Return int   0 or error code
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 place holder
0x00000002 : Load text place holder
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

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 error code
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 error code

Please use the function interactive::get instead.

static int get_multistate(
  ItemRef frameRef,
  ItemRef out_mso,
  int* out_state)

Name Type Default Description
Return int   0 or error code

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   Error code or 0
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   Fehlercode oder 0
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   Fehlercode oder 0
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 master 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   Fehlercode oder 0
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   Fehlercode oder 0
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   Fehlercode oder 0
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

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   error code or 0
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

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 error code
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.

Name Type Default Description
Return int   0 or error code
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 error code
frameRef ItemRef 0 valid frame

0 : current script frame
corner int 0 Corner of interest

0 :alle corners. Works only if all corners having the same settings.

Following setting will work from CS5 only.

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 error code
frameRef ItemRef 0 valid frame

0 : current script frame
applyRules int 0 Apply adapter rules of frames?

0 : No
1 : Yes
applyRules int 1 Apply rules of type "While building productss" 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

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 error code
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 error code
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 error code
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 Error code
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, kThrowError);
}

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, kThrowError);
}

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 error code
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 Error Code
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 Error Code
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 error Code
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)

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   Error code oder 0
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 to be 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.

#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)

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 error code
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 error code
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 Error code
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 Error code
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. 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. 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. 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. 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 error code
fr ItemRef - valid frame reference
lk ItemRef - Allocated 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

priint:comet InDesign® Plug-Ins

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 error code
lk ItemRef - valid link reference
fr ItemRef - allocted frame reference for the result

v3.3 R2550, 30.06.2011

priint:comet InDesign® Plug-Ins

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

priint:comet InDesign® Plug-Ins

document::get_links

static int doclink::get_type(ItemRef lk)

Determine the type of a frame link. In addition to links to images, you can can create links to text frames too, use the menu Edit -> Place and Link to do that.

Name Type Default Description
Return int   Current link type

-1 : Error
0 : Internal
1 : Text Frame
2 : Image
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

priint:comet InDesign® Plug-Ins

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 error code
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!)
  2. (Image) : Full path to the linked image
  3. (Text Frame) : Empty ("")

v3.3 R2550, 30.06.2011

priint:comet InDesign® Plug-Ins

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.

Name Type Default Description
Return int   0 or error code
lk ItemRef - valid link reference
fullpath char* - allocated string for the result string (the complete path to the linked file)

#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

priint:comet InDesign® Plug-Ins

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 error code
lk ItemRef - valid link reference
fullpath char* oder String - complete path to image

v4.1 R24141, 20. Nov 2018

priint:comet InDesign® Plug-Ins

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 error code -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

#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

priint:comet InDesign® Plug-Ins

document::get_links

This class has no child classes.

#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 ()
{
    int	pg	= -1;
    ItemRef	frame	= item::alloc ();
    ItemRef	frame2	= item::alloc ();
    char	layerName[256];
    char	tt[2000];
    int	result;<br>
    color::define ("Dark orange", 	255, 90, 0);
    color::define ("Orange", 	255, 127, 0);
    color::define ("Light orange", 	255, 190, 0);<br>
    result 	= frame::create_textframe (
     		frame,
     		10, 10, 200, 200,
     		pg,
     		layer::name (2, layerName));
    if (result != 0)
    {
        showmessage ("Error %d",result);
        item::delete (frame);
        return;
    }<br>
    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<br>
    result 	= frame::create_textframe (
     		frame2,
     		10, 210, 300, 400
     		pg,
     		layer::name (2, layerName));<br>
    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);<br>
    frame::link (frame, frame2);<br>
    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 : ";<br>
    tt += "#<in: 100.0, 100.0, 11,  3, -66, -99>Trulla du!</in>#";<br>
    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>";<br>
    tt += "*Good, eh?";<br>
    frame::insert (frame, tt, 0, true);<br>
    item::delete (frame);
    item::delete (frame2);
}

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!
20.10.2021, 12:36 Uhr
Plugin Version 1.0.10

Alphabetic index HTML hierarchy of classes or Java